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

Ruida Controllers​

Rayforge connects to Ruida-based controllers (e.g. RDC6442, RDC6445, Ruida R5) through the Ruida RPA driver, which talks the controller's native protocol over USB or UDP, or via TUI RPC through the Ruida Protocol Analyzer. The Generic Ruida RPA and Monport MP-570 60W CO2 device profiles provide starting points for new machines.

Features:

  • USB and UDP connectivity; when both are configured, Rayforge swaps automatically between them as cables are connected and disconnected
  • Job sending with position reporting, jogging, homing, and Move to Position
  • Framing traces the job outline with beam-off absolute moves, so it works without firing the laser
  • Honors each step's Power Mode setting: Dynamic (M4) enables the controller's power scaling and Constant (M3) disables it
  • Serial ports can be bound from a USB device dropdown with VID:PID matching, so auto-reconnect follows the machine after the OS re-enumerates USB devices

Power tuning settings:

  • Power scaling — raises the emitted minimum power as the layer's cut speed decreases
  • VECTOR power floor — minimum power for vector cut compensation during acceleration and deceleration, reducing over-burn at the ends of lines
  • IMAGE power bias — power added to raster scan lines, since CO2 tubes do not fire at very low power settings

Limitations:

  • Experimental — so far tested on a RDC6442S controller (Monport MP570 CO2)
  • No G-code generation; Ruida uses its own proprietary protocol
  • Rotary mode is not yet supported

Experimental Drivers​

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