Grbl Commands - fra589/grbl-Mega-5X GitHub Wiki

'$' Commands

The $ system commands provide additional controls for the user, such as printing feedback on the current G-code parser modal state or running the homing cycle.

$$ and $x=val - View and Write Grbl settings See Configuration for more details.

G-code parameters G-code parameters store the coordinate offset values for G54-G59 work coordinates, G28/G30 pre-defined safety positions, relative to machine. G92 coordinate offset, tool length offsets, and probing (not officially, but we added here anyway). Most of these parameters are directly written to EEPROM anytime they are changed and are persistent. The non-persistent parameters, which will are not retained when reset or power-cycled, are G92, G43.1 tool length offsets, and the G38.2 probing data.

  • G53-G59 Work Offsets can be changed via the G10 L2 Px or G10 L20 Px command in G-code defined by the NIST gcode standard and the EMC2 (linuxcnc.org) standard. G10 L2 Poo Xxx Yyy Zzz oo is the work offset number, xx is the X offset, yy is the Y offset, and zz is the Z offset.
  • G28/G30 pre-defined positions can be changed via the G28.1 and the G30.1 commands, respectively.

$# - View gcode parameters When $# is called, Grbl will respond with the stored offsets from machine coordinates for each system as follows:

[G54:4.000,0.000,0.000]
[G55:4.000,6.000,7.000]
[G56:0.000,0.000,0.000]
[G57:0.000,0.000,0.000]
[G58:0.000,0.000,0.000]
[G59:0.000,0.000,0.000]
[G28:1.000,2.000,0.000]
[G30:4.000,6.000,0.000]
[G92:0.000,0.000,0.000]
[TLO:0.000]
[PRB:0.000,0.000,0.000:0]

TLO denotes tool length offset (for the default z-axis), and PRB denotes the coordinates of the last probing cycle, where the suffix :1 denotes if the last probe was successful and :0 as not successful.

$G - View gcode parser state This command prints all of the active gcode modes in Grbl's G-code parser. When sending this command to Grbl, it will reply with a message starting with an [GC: indicator like:

[GC:G0 G54 G17 G21 G90 G94 M0 M5 M9 T0 S0.0 F500.0]

These active modes determine how the next G-code block or command will be interpreted by Grbl's G-code parser. For those new to G-code and CNC machining, modes sets the parser into a particular state so you don't have to constantly tell the parser how to parse it. These modes are organized into sets called "modal groups" that cannot be logically active at the same time. For example, the units modal group sets whether your G-code program is interpreted in inches or in millimeters. A short list of the modal groups, supported by Grbl, is shown below, but more complete and detailed descriptions can be found at LinuxCNC's website. The G-code commands in bold indicate the default modes upon powering-up Grbl or resetting it.

Modal Group Member Words
Motion Mode G0, G1, G2, G3, G38.2, G38.3, G38.4, G38.5, G80
Coordinate System Select G54, G55, G56, G57, G58, G59
Plane Select G17 (XY), G18 (XZ), G19 (YZ)
Distance Mode G90 (absolute), G91 (incremental)
Arc IJK Distance Mode G91.1
Feed Rate Mode G93 (inverse time mode), G94 (units per minute mode)
Units Mode G20 (inch), G21 (mm)
Cutter Radius Compensation G40
Tool Length Offset G43.1, G49
Program Mode M0, M1, M2, M30
Spindle State M3, M4, M5
Coolant State M7, M8, M9

In addition to the G-code parser modes, Grbl will report the active T tool number, S spindle speed, and F feed rate, which all default to 0 upon a reset. For those that are curious, these don't quite fit into nice modal groups, but are just as important for determining the parser state. Note that this list does not include the non-modal g-code commands group and they are not listed in the $G parser report, because they only affect the current line they are commanded in. For completeness, here are the non-modal commands supported by Grbl:

G4, G10 L2, G10 L20, G28, G30, G28.1, G30.1, G53, G92, G92.1

$I - View build info This prints the Grbl version and source code build date. Optionally, $I can also store a short string to help identify which CNC machine you are communicating with, if you have more than machine using Grbl. To set this string, send Grbl $I=xxx, where xxx is your customization string that is less than 80 characters.

$N - View startup blocks

$Nx are the startup blocks that Grbl runs every time you power on Grbl or reset Grbl. Grbl can store 2 blocks of G-code as a system default.

$Nx= - Save startup block Typical usage for a startup block is simply to set your preferred modal states, such as G20 inches mode, always default to a different work coordinate system etc. To set a startup block, type $N0= followed by a valid G-code block and an enter.

$C - Check gcode mode This toggles the Grbl's gcode parser to take all incoming blocks and process them completely, as it would in normal operation, but it does not move any of the axes, ignores dwells, and powers off the spindle and coolant. This is intended as a way to provide the user a way to check how their new G-code program fares with Grbl's parser and monitor for any errors (and checks for soft limit violations, if enabled).

$X - Kill alarm lock Grbl's alarm mode is a state when something has gone critically wrong, such as a hard limit or an abort during a cycle, or if Grbl doesn't know its position. By default, if you have homing enabled and power-up the Arduino, Grbl enters the alarm state, because it does not know its position. The alarm mode will lock all G-code commands until the '$H' homing cycle has been performed, or if a user needs to override the alarm lock to move their axes off their limit switches.

$H - Run homing cycle This command is the only way to perform the homing cycle in Grbl. Homing is a completely separate command handled by the controller. TIP: After running a homing cycle, rather jogging manually all the time to a position in the middle of your workspace volume. You can set a G28 or G30 pre-defined position to be your post-homing position, closer to where you'll be machining. To set these, you'll first need to jog your machine to where you would want it to move to after homing. Type G28.1 (or G30.1) to have Grbl store that position. So then after '$H' homing, you could just enter G28 (or G30) and it'll move there automagically.

$J= - Run jogging motion Executing a jog requires a specific command structure, as described below:

  • $J= to indicate the jog. It works like a normal G1 command.
  • Feed rate is only interpreted in G94 units per minute. A prior G93 state is ignored during jog.
  • Required words:
    • XYZ: One or more axis words with target value.
    • F - Feed rate value. NOTE: Each jog requires this value and is not treated as modal.
  • Optional words: Jog executes based on current G20/G21 and G90/G91 g-code parser state. If one of the following optional words is passed, that state is overridden for one command only.
    • G20 or G21 - Inch and millimeter mode
    • G90 or G91 - Absolute and incremental distances
    • G53 - Move in machine coordinates

Example: G21 and G90 are active modal states prior to jogging. These are sequential commands.

  • $J=X10.0 Y-1.5 will move to X=10.0mm and Y=-1.5mm in work coordinate frame (WPos).
  • $J=G91 G20 X0.5 will move +0.5 inches (12.7mm) to X=22.7mm (WPos). Note that G91 and G20 are only applied to this jog command.
  • $J=G53 Y5.0 will move the machine to Y=5.0mm in the machine coordinate frame (MPos). If the work coordinate offset for the y-axis is 2.0mm, then Y is 3.0mm in (WPos).

Jog commands behave almost identically to normal g-code streaming. Every jog command will return an ok when the jogging motion has been parsed and is setup for execution. If a command is not valid or exceeds a soft-limit, Grbl will return an error:. Multiple jogging commands may be queued in sequence.

$RST= - Restore Grbl settings and data to defaults These commands are not listed in the main Grbl $ help message, but are available to allow users to restore parts of or all of Grbl's EEPROM data. Note: Grbl will automatically reset after executing one of these commands to ensure the system is initialized correctly.

  • $RST=$ : Erases and restores the $$ Grbl settings back to defaults, which is defined by the default settings file used when compiling Grbl. Often OEMs will build their Grbl firmwares with their machine-specific recommended settings. This provides users and OEMs a quick way to get back to square-one, if something went awry or if a user wants to start over.
  • $RST=# : Erases and zeros all G54-G59 work coordinate offsets and G28/30 positions stored in EEPROM. These are generally the values seen in the $# parameters printout. This provides an easy way to clear these without having to do it manually for each set with a G20 L2/20 or G28.1/30.1 command.
  • $RST=* : This clears and restores all of the EEPROM data used by Grbl. This includes $$settings, $# parameters, $N startup lines, and $I build info string. Note that this doesn't wipe the entire EEPROM, only the data areas Grbl uses. To do a complete wipe, please use the Arduino IDE's EEPROM clear example project.

$SLP - Enable Sleep Mode This command will disable everything, shutting down the spindle, coolant, and stepper enable pins and block any commands. It may only be exited by a soft-reset or power-cycle. Once re-initialized, Grbl will automatically enter an ALARM state. This feature is useful if you need to automatically de-power everything at the end of a job by adding this command at the end of your g-code program. Nice to have when you are leaving your machine unattended and want to power down everything automatically. Only a reset exits the sleep state.

Realtime commands

Realtime commands are single control characters that may be sent to Grbl to command and perform an action in real-time, which means that they can be sent at anytime, anywhere, and Grbl will immediately respond, regardless of what it is doing at the time. These commands include a reset, feed hold, resume, status report query, and overrides.

ASCII Realtime Command Descriptions Four realtime commands are type-able by users on a keyboard and shown in the $ Grbl help message. These realtime command characters control some of Grbl's basic functions.

  • 0x18 (ctrl-x) : Soft-Reset
    • Immediately halts and safely resets Grbl without a power-cycle.
    • If reset while in motion, Grbl will throw an alarm to indicate position may be lost from the motion halt; If reset while not in motion, position is retained and re-homing is not required.
    • An input pin is available to connect a button or switch.
  • ? : Status Report Query
    • Immediately generates and sends back runtime data with a status report.
  • ! : Feed Hold
    • Places Grbl into a suspend or HOLD state. If in motion, the machine will decelerate to a stop and then be suspended.
    • If jogging, a feed hold will cancel the jog motion and flush all remaining jog motions in the planner buffer. The state will return from JOG to IDLE, if was detected as ajar during the active hold.
    • By machine control definition, a feed hold does not disable the spindle or coolant. Only motion.
    • An input pin is available to connect a button or switch.
  • ~ : Cycle Start / Resume
    • Resumes a feed hold, a safety door/parking state when the door is closed, and the M0 program pause states.
    • If the parking compile-time option is enabled and the safety door state is ready to resume, Grbl will re-enable the spindle and coolant, move back into position, and then resume.
    • An input pin is available to connect a button or switch.

Extended-ASCII Realtime Command Descriptions Grbl v1.1 installed more than a dozen new realtime commands to control feed, rapid, and spindle overrides. To help prevent users from inadvertently altering overrides with a keystroke and allow for more commands later on, all of the new control characters have been moved to the extended ASCII character set. These are not easily type-able on a keyboard, but, depending on the OS, they may be entered using specific keystroke and code. GUI developers will need to be able to send extended ASCII characters, values 128 (0x80) to 255 (0xFF), to Grbl to take advantage of these new features.

  • 0x84 : Safety Door
    • Although typically connected to an input pin to detect the opening of a safety door, this command allows a GUI to enact the safety door behavior with this command.
    • Immediately suspends into a DOOR state and disables the spindle and coolant. If in motion, the machine will decelerate to a stop and then be suspended.
    • If executed during homing, Grbl will instead halt motion and throw a homing alarm.
    • If already in a suspend state or HOLD, the DOOR state supersedes it.
    • If the parking compile-time option is enabled, Grbl will park the spindle to a specified location.
    • Command executes when Grbl is in an IDLE, HOLD, RUN, HOMING, or JOG state. It is otherwise ignored.
    • If jogging, a safety door will cancel the jog and all queued motions in the planner buffer. When the safety door is closed and resumed, Grbl will return to an IDLE state.
    • An input pin is available to connect a button or switch, if enabled with a compile-time option.
    • Some builds of Grbl v0.9 used the @ character for this command, but it was undocumented. Moved to extended-ASCII to prevent accidental commanding.
  • 0x85 : Jog Cancel
    • Immediately cancels the current jog state by a feed hold and automatically flushing any remaining jog commands in the buffer.
    • Command is ignored, if not in a JOG state or if jog cancel is already invoked and in-process.
    • Grbl will return to the IDLE state or the DOOR state, if the safety door was detected as ajar during the cancel.
  • Feed Overrides
    • Immediately alters the feed override value. An active feed motion is altered within tens of milliseconds.
    • Does not alter rapid rates, which include G0, G28, and G30, or jog motions.
    • Feed override value can not be 10% or greater than 200%.
    • If feed override value does not change, the command is ignored.
    • Feed override range and increments may be changed in config.h.
    • The commands are:
      • 0x90 : Set 100% of programmed rate.
      • 0x91 : Increase 10%
      • 0x92 : Decrease 10%
      • 0x93 : Increase 1%
      • 0x94 : Decrease 1%
  • Rapid Overrides
    • Immediately alters the rapid override value. An active rapid motion is altered within tens of milliseconds.
    • Only effects rapid motions, which include G0, G28, and G30.
    • If rapid override value does not change, the command is ignored.
    • Rapid override set values may be changed in config.h.
    • The commands are:
      • 0x95 : Set to 100% full rapid rate.
      • 0x96 : Set to 50% of rapid rate.
      • 0x97 : Set to 25% of rapid rate.
  • Spindle Speed Overrides
    • Immediately alters the spindle speed override value. An active spindle speed is altered within tens of milliseconds.
    • Override values may be changed at any time, regardless of if the spindle is enabled or disabled.
    • Spindle override value can not be 10% or greater than 200%
    • If spindle override value does not change, the command is ignored.
    • Spindle override range and increments may be altered in config.h.
    • The commands are:
      • 0x99 : Set 100% of programmed spindle speed
      • 0x9A : Increase 10%
      • 0x9B : Decrease 10%
      • 0x9C : Increase 1%
      • 0x9D : Decrease 1%
      • 0x9E : Toggle Spindle Stop
    • Toggles spindle enable or disable state immediately, but only while in the HOLD state.
    • The command is otherwise ignored, especially while in motion. This prevents accidental disabling during a job that can either destroy the part/machine or cause personal injury. Industrial machines handle the spindle stop override similarly.
    • When motion restarts via cycle start, the last spindle state will be restored and wait 4.0 seconds (configurable) before resuming the tool path. This ensures the user doesn't forget to turn it back on.
    • While disabled, spindle speed override values may still be altered and will be in effect once the spindle is re-enabled.
    • If a safety door is opened, the DOOR state will supersede the spindle stop override, where it will manage the spindle re-energizing itself upon closing the door and resuming. The prior spindle stop override state is cleared and reset.
  • 0xA0 : Toggle Flood Coolant
    • Toggles flood coolant state and output pin until the next toggle or g-code command alters it.
    • May be commanded at any time while in IDLE, RUN, or HOLD states. It is otherwise ignored.
    • This override directly changes the coolant modal state in the g-code parser. Grbl will continue to operate normally like it received and executed an M8 or M9 g-code command.
    • When $G g-code parser state is queried, the toggle override change will be reflected by an M8 enabled or disabled with an M9 or not appearing when M7 is present.
  • 0xA1 : Toggle Mist Coolant
    • Enabled by ENABLE_M7 compile-time option. Default is disabled.
    • Toggles mist coolant state and output pin until the next toggle or g-code command alters it.
    • May be commanded at any time while in IDLE, RUN, or HOLD states. It is otherwise ignored.
    • This override directly changes the coolant modal state in the g-code parser. Grbl will continue to operate normally like it received and executed an M7 or M9 g-code command.
    • When $G g-code parser state is queried, the toggle override change will be reflected by an M7 enabled or disabled with an M9 or not appearing when M8 is present.