GRBL essentials
Just enough GRBL to drive a laser. The commands, states, and settings that matter most.
GRBL is the open-source firmware running on most diode and small CO2 laser controllers. Beam Bench talks to it over serial. You do not need to understand GRBL deeply to use Beam Bench, but the moments you will need it (debugging, calibration, recovering from alarm) are easier when you know the basics.
The model
GRBL is a streaming interpreter. The host (Beam Bench, or the Console panel) sends one G-code line at a time. GRBL parses, plans, executes, and acknowledges each line with ok or error:N.
GRBL has a machine state:
| State | Meaning |
|---|---|
Idle | Ready for commands. |
Run | Executing a move. |
Hold | Paused mid-move. Resume with ~. |
Jog | Executing a jog (special non-streamed move). |
Alarm | Something went wrong, limit hit, soft limit, etc. Cannot move until cleared. |
Door | Safety door is open. |
Check | Dry-run mode, parses but does not move. |
Home | Running homing cycle. |
Sleep | Sleeping. |
You see these states reflected in the Laser Control connection bar.
Real-time commands
A handful of single-character commands bypass the parser. They are immediate, not queued:
| Char | Action |
|---|---|
? | Status query (returns position, state). |
~ | Resume / cycle start. |
! | Feed hold (pause). |
^X (Ctrl+X byte) | Soft reset. |
Beam Bench uses these under the hood, the Pause and Stop buttons send ! and reset.
$ settings
GRBL stores config in EEPROM, accessed via $ settings. Common ones:
| Setting | Meaning |
|---|---|
$0 | Step pulse, microseconds. |
$10 | Status report mask. |
$20-$23 | Soft / hard limits, homing. |
$30 | Maximum spindle / laser S value. |
$31 | Minimum spindle / laser S value. |
$32 | Laser mode. |
$100-$102 | Steps/mm for X / Y / Z. |
$110-$112 | Maximum rate (mm/min) for X / Y / Z. |
$120-$122 | Acceleration (mm/s²). |
$130-$132 | Maximum travel for X / Y / Z (used for soft limits). |
Dump all settings with $$ in the Console panel. For $30, keep the current value unless the controller documentation specifies a different maximum S. The $30=… line is a template: replace the ellipsis with that documented value, and do not paste the line unchanged. Set Device Settings S-value Max to the same value.
See Dollar settings reference for the full list.
Laser mode ($32)
$32=1 enables GRBL laser mode. Motion-scaled power also requires dynamic M4 output. With $32=1 and M4, GRBL scales laser power through motor deceleration and acceleration; constant-power M3 output remains at the commanded power while moving.
For dynamic-power engraving, enable $32=1 and use M4. If the active machine profile selects Constant Power (M3), power does not scale with motion.
Error and alarm codes
When GRBL returns error:N or alarm:N, the number tells you what happened. Common ones:
| Code | Type | Meaning |
|---|---|---|
error:1 | Error | Expected command letter. |
error:2 | Error | Bad number format. |
error:9 | Error | G-code locked out during alarm state. |
error:20 | Error | Unsupported command. |
alarm:1 | Alarm | Hard limit triggered. |
alarm:9 | Alarm | Homing failed. |
See GRBL error codes troubleshooting.
Homing and unlocking
$H runs the homing cycle (moves to limit switches). After homing, the machine knows where 0,0 is.
When in alarm state, the machine refuses to move. Clear with $X (unlock). Beam Bench's Move panel has an Unlock button that does this.
Job placement with Start From and Job Origin
Beam Bench's Start From and Job Origin controls translate the planned geometry to the selected anchor before G-code is emitted. Absolute Coords uses the design's workspace coordinates, Current Position anchors it to the current head position, and User Origin anchors it to the saved user origin.
Normal job start does not emit G92 for these placement modes. Use the controls in Laser Control, and see Job origin vs workspace origin for the complete placement model.
How Beam Bench handles it
Beam Bench wraps all of this. You do not see GRBL directly during normal operation. The Console panel lets you talk to GRBL when you need to. The Connection Diagnostics panel shows raw TX/RX traffic and connection state for debugging.