Skip to main content

Firmware Compatibility

This page documents firmware compatibility for laser controllers used with Rayforge.

Overview​

Rayforge is designed primarily for GRBL-based controllers but also supports Marlin, Smoothieware, and other firmware types.

Compatibility Matrix​

FirmwareVersionStatusDriverNotes
GRBL1.1+CompatibleGRBL Serial / GRBL Serial SimpleRecommended
grblHAL2023+CompatibleGRBL Serial / GRBL TelnetModern GRBL fork
GRBL0.9LimitedGRBL SerialOlder, may have issues
SmoothiewareAllCompatibleSmoothieDriver (Telnet)Network-based
Marlin2.0+CompatibleMarlin SerialLaser mode required
ESP3DAllCompatibleGRBL TelnetNetwork-based
OctoPrintAllExperimentalOctoPrintSee notes below
Other-Not supported-Request support

GRBL Firmware​

Status: Fully Supported Versions: 1.1+ Drivers: GRBL Serial, GRBL Serial Simple

What is GRBL 1.1?

GRBL 1.1 is the most common firmware for hobby CNC and laser machines. Released in 2017, it's stable, well-documented, and widely supported.

Features supported by Rayforge:

  • Serial communication (USB)
  • Real-time status reporting
  • Laser mode (M4 constant power)
  • Settings read/write ($$, $X=value)
  • Homing cycles ($H)
  • Work coordinate systems (G54)
  • Jogging commands ($J=)
  • Feed rate override
  • Soft limits
  • Hard limits (endstops)

Known limitations:

  • Power range: 0-1000 (S parameter)
  • No network connectivity (USB only)
  • Limited onboard memory (small G-code buffer)

Checking GRBL Version​

Query version:

Connect to your controller and send:

$I

Response examples:

[VER:1.1h.20190825:]
[OPT:V,15,128]
  • 1.1h = GRBL version 1.1h
  • Date indicates build

GRBL 0.9 (Older)​

Status: Limited Support

GRBL 0.9 is an older version with some compatibility issues:

Differences:

  • Different status report format
  • No laser mode (M4) - uses M3 only
  • Fewer settings
  • Different jogging syntax

If you have GRBL 0.9:

  1. Upgrade to GRBL 1.1 if possible (recommended)
  2. Use M3 instead of M4 (less predictable power)
  3. Test thoroughly - some features may not work

Upgrade instructions: See GRBL Wiki

GRBL Serial Simple Driver​

Rayforge includes a second GRBL serial driver for devices where the standard buffer-counting driver causes false alarms or communication errors.

How it works:

  • Uses a ping-pong protocol: send one line, wait for "ok", send the next
  • No character-counting buffer management
  • No deadlock detection or stall recovery
  • Simpler and more predictable on some devices

When to use:

  • Your device gets false buffer stall alarms with the standard driver
  • Communication errors occur intermittently with the standard driver
  • You have a device with unusual buffer behavior

When not to use:

  • The standard GRBL Serial driver works reliably for most devices
  • The simple driver lacks deadlock recovery, so jobs may stop on a lost "ok" response without automatic recovery

grblHAL​

Status: Compatible Versions: 2023+ Driver: GRBL Serial

What is grblHAL?​

grblHAL is a modern fork of GRBL with enhanced features:

  • Multiple controller hardware support (STM32, ESP32, etc.)
  • Ethernet/WiFi networking
  • SD card support
  • More I/O pins
  • Enhanced laser support

Compatibility with Rayforge:

  • Fully compatible - grblHAL maintains GRBL 1.1 protocol
  • All GRBL features work
  • Additional features (networking, SD) not yet supported by Rayforge
  • Status reporting identical to GRBL

Using grblHAL:

  1. Select "GRBL Serial" driver in Rayforge
  2. Connect via USB serial (just like GRBL)
  3. All features work as documented for GRBL

Future: Rayforge may add support for grblHAL-specific features (networking, etc.)

GRBL Telnet Driver​

Status: Supported Firmware: grblHAL, ESP3D, and other networked GRBL controllers Driver: GRBL Telnet

About the GRBL Telnet Driver​

The GRBL Telnet driver connects to GRBL-based controllers over the network via a Telnet interface. This is ideal for boards with built-in WiFi or Ethernet — no USB cable required.

Features:

  • Network connectivity (Ethernet/WiFi)
  • Compatible with grblHAL and ESP3D-based boards
  • Same GRBL protocol as the serial driver

Using the GRBL Telnet driver:

  1. Configure networking on your controller (WiFi or Ethernet)
  2. Select "GRBL Telnet" driver in machine settings
  3. Enter the IP address and port of your controller
  4. Connect — the driver communicates over Telnet

Requirements:

  • Networked GRBL-compatible controller (grblHAL, ESP3D, etc.)
  • Controller and computer on the same network
  • Telnet interface enabled on the controller

Smoothieware​

Versions: All Driver: SmoothieDriver (Telnet-based)

About SmoothieDriver​

Rayforge includes a dedicated SmoothieDriver that connects to Smoothieware controllers via Telnet over network. This provides native support rather than relying on GRBL compatibility mode.

Features:

  • Network connectivity (Ethernet/WiFi)
  • Real-time status reporting
  • Native Smoothieware G-code support

Using Smoothieware with Rayforge:

  1. Configure network on your Smoothieboard (Ethernet or WiFi)
  2. Select SmoothieDriver in machine settings
  3. Enter IP address of your controller
  4. Select Smoothieware dialect in machine settings > G-code > Dialect

Requirements:

  • Smoothieboard with network connectivity
  • Controller and computer on same network
  • Telnet enabled in Smoothieware config

Limitations:

  • Requires network connection (no USB serial)
  • Settings ($$ commands) work differently than GRBL

Marlin​

Versions: 2.0+ with laser support Driver: Marlin Serial

Marlin Serial Driver​

Rayforge includes a dedicated MarlinSerialDriver that connects to Marlin firmware via serial (USB). Marlin 2.0+ can control lasers when properly configured.

Features:

  • Serial communication (USB)
  • Marlin handshake protocol (waits for "start" message)
  • G-code streaming line-by-line with ok acknowledgment
  • M114 position polling
  • Job execution with granular progress reporting
  • Homing (G28), jogging, move-to, tool change (T)
  • WCS offset setting (G10 L2 P)
  • Laser power control via the Marlin G-code dialect
  • Cancel via M410 (Quick Stop)
  • Auto-configuration probing (queries M115, M211, M503)

Requirements:

  1. Marlin 2.0 or later firmware
  2. Laser features enabled: 
    #define LASER_FEATURE
    #define LASER_POWER_INLINE
  3. Correct power range configured: 
    #define SPEED_POWER_MAX 1000

Using Marlin with Rayforge:

  1. Select "Marlin (Serial)" driver in machine settings
  2. Set the serial port and baud rate (typically 115200)
  3. Select Marlin dialect in machine settings > G-code > Dialect
  4. Configure Marlin for laser use
  5. Test power range matches (0-1000 or 0-255)

Limitations:

  • Experimental — feedback welcome
  • Settings read/write (like GRBL's $$) not supported
  • No network connectivity (USB only)

Firmware Upgrade Guide​

Upgrading to GRBL 1.1​

Why upgrade?

  • Laser mode (M4) for constant power
  • Better status reporting
  • More reliable
  • Better Rayforge support

How to upgrade:

  1. Identify your controller board:

    • Arduino Nano/Uno (ATmega328P)
    • Arduino Mega (ATmega2560)
    • Custom board

  2. Download GRBL 1.1:

  3. Flash firmware:

    Using Arduino IDE:

    1. Install Arduino IDE
    2. Open GRBL sketch (grbl.ino)
    3. Select correct board and port
    4. Upload

    Using avrdude:

    avrdude -c arduino -p m328p -P /dev/ttyUSB0 \
            -U flash:w:grbl.hex:i

  4. Configure GRBL:

    • Connect via serial
    • Send $$ to view settings
    • Configure for your machine

Backup Before Upgrade​

Save your settings:

  1. Connect to controller
  2. Send $$ command
  3. Copy all settings output
  4. Save to file

After upgrade:

  • Restore settings one-by-one: $0=10, $1=25, etc.
  • Or use defaults and reconfigure

Controller Hardware​

Common Controllers​

BoardTypical FirmwareRayforge Support
Arduino CNC ShieldGRBL 1.1Excellent
MKS DLC32grblHALExcellent
RuidaProprietaryExperimental
OctoPrint (Pi)VariousExperimental

For best Rayforge compatibility:

  1. Arduino Nano + CNC Shield (GRBL 1.1)

    • Cheap (~$10-20)
    • Easy to flash
    • Well documented

  2. MKS DLC32 (grblHAL)

    • Modern (ESP32-based)
    • WiFi capable
    • Active development

  3. Custom GRBL boards

    • Many available on marketplaces
    • Check for GRBL 1.1+ support

Firmware Configuration​

GRBL Settings for Laser​

Essential settings:

$30=1000    ; Max spindle/laser power (1000 = 100%)
$31=0       ; Min spindle/laser power
$32=1       ; Laser mode enabled (1 = on)

Machine settings:

$100=80     ; X steps/mm (calibrate for your machine)
$101=80     ; Y steps/mm
$110=3000   ; X max rate (mm/min)
$111=3000   ; Y max rate
$120=100    ; X acceleration (mm/sec)
$121=100    ; Y acceleration
$130=300    ; X max travel (mm)
$131=200    ; Y max travel (mm)

Safety settings:

$20=1       ; Soft limits enabled
$21=1       ; Hard limits enabled (if you have endstops)
$22=1       ; Homing enabled

Testing Firmware​

Basic test sequence:

  1. Connection test:

    Send: ?
    Expect: <Idle|...>

  2. Version check:

    Send: $I
    Expect: [VER:1.1...]

  3. Settings check:

    Send: $$
    Expect: $0=..., $1=..., etc.

  4. Movement test:

    Send: G91 G0 X10
    Expect: Machine moves 10mm in X

  5. Laser test (very low power):

    Send: M4 S10
    Expect: Laser turns on (dim)
    Send: M5
    Expect: Laser turns off

Troubleshooting Firmware Issues​

Firmware Not Responding​

Symptoms:

  • No response to commands
  • Connection fails
  • Status not reported

Diagnosis:

  1. Check baud rate:

    • GRBL 1.1 default: 115200
    • GRBL 0.9: 9600
    • Try both

  2. Check USB cable:

    • Data cable, not charge-only
    • Replace with known-good cable

  3. Check port:

    • Linux: /dev/ttyUSB0 or /dev/ttyACM0
    • Windows: COM3, COM4, etc.
    • Correct port selected in Rayforge

  4. Test with terminal:

    • Use screen, minicom, or PuTTY
    • Send ? and see if you get response

Future Firmware Support​

Ruida Controllers​

Rayforge includes experimental support for Ruida-based controllers (e.g. RDC6442, RDC6445, Ruida R5). The Ruida driver connects over the network and supports jogging, position reporting, air assist control, layer selection, auto-connect, and status polling.

Features:

  • Network connectivity (Ethernet/WiFi)
  • Position reporting
  • Jogging controls
  • Air assist and layer selection
  • Reference point support

Limitations:

  • Experimental — not yet fully stable
  • No G-code generation; Ruida uses its own proprietary protocol
  • Job sending is not yet supported

OctoPrint​

Rayforge includes an experimental OctoPrint driver that submits G-code directly to an OctoPrint server over the network. This is useful if your laser is connected to a Raspberry Pi or other machine running OctoPrint.

Features:

  • WebSocket connection for real-time status updates
  • REST polling fallback when WebSocket is unavailable
  • Auto-reconnect on connection loss
  • Job submission with automatic print start
  • Jogging, homing, and pause/resume controls
  • "Request Access" flow for OctoPrint application keys

Using the OctoPrint driver:

  1. Select "OctoPrint" driver in machine settings
  2. Enter the hostname or IP address of your OctoPrint server
  3. Set the port (default: 80)
  4. Click "Request Access" to obtain an API key through OctoPrint's application key flow
  5. Connect -- Rayforge will establish a WebSocket connection

Limitations:

  • Experimental and untested on real hardware -- feedback welcome
  • Cannot read or write firmware settings through OctoPrint
  • Probe results are not reported by OctoPrint
  • WCS offset reads are not supported

Contributing​

To add firmware support:

  1. Implement driver in rayforge/machine/driver/
  2. Define G-code dialect in rayforge/machine/models/dialect.py
  3. Test thoroughly on real hardware
  4. Submit pull request with documentation