Report extensions

Typographical conventions

Convention	Description
{ }	Braces indicates the items within them are optional.
< >	Chevrons indicates the item within is a variable or a constant.
<axis bitmask>	A bitfield where bit 0 represents the X-axis, bit 1 the Y-axis etc...
<axis values>	A comma separated list of decimal values
|	Used within < > as a separator for allowed literal values.

Realtime report

[<Idle|Run|Hold|Jog|Alarm|Door|Check|Home|Sleep|Tool>{:<substatus>}|<WPos:|MPos:><axis positions>{|Bf:<block buffers free>,<RX characters free>}{|Ln:<line number>}{|FS:<feed rate>,<programmed rpm>{,<actual rpm>}}{|Pn:<signals>}{|WCO:<axis offsets>}{|WCS:G<coordinate system>}{|Ov:<overrides>}{|A:<accessory status>}{|MPG:<0|1>}{|H:<0|1>{,<axis bitmask>}}{|D:<0|1>}{|Sc:<axisletters>}{|TLR:<0|1>}{|FW:<firmware>}{|In:<result>}]

A new status, Tool has been added for the tool change protocol.

Note that a report with the Home status is now pushed before the homing sequence starts. While homing status report requests are queued and not responded to.

Optional substatuses can be added to some statuses depending on $10 setting flags.

Run{:<1|2>} - feed hold pending or probing.
1 - feed hold pending. A feed hold issued during a spindle synchronized motion will be delayed until this is finished. Until then this substate will be added.
2 - is probing motion.

Alarm{:<alarm code>} - current alarm code. Note that is is always added starting from build 20201212 if alarm code is > 0 and the report is requested by sending 0x87.

Enhanced element |Pn:<signals>
<signals> is a string containing any of the following letters:

P - probe triggered
O - probe disconnected, new
X - X limit switch asserted
Y - Y limit switch asserted
Z - Z limit switch asserted
A - A limit switch asserted, new
B - B limit switch asserted, new
C - C limit switch asserted, new
U - U limit switch asserted, new
V - V limit switch asserted, new
W - W limit switch asserted, new
D - Door switch asserted
R - Reset switch asserted
H - Feed hold switch asserted
S - Cycle start switch asserted
E - E-Stop switch asserted, new
L - Block delete switch asserted, new
T - Optional program stop switch asserted, new
M - Motor warning, new - was W in builds <= 20220922
F - Motor fault, new - was M in builds <= 20220922 Q - Single step blocks asserted, new in builds >= 20240110

Enhanced element |A:<accessory status
<accessory status> is a string containing any of the following letters:

S - spindle is running in a clockwise direction (M3)
C - spindle is running in a counterclockwise direction (M4)
M - mist coolant is on (M7)
F - flood coolant is on (M8)
T - tool change is pending (M6), new

New element |WCS:G<coordinate system> added on a coordinate system change.

New element |MPG:<0|1> used to inform that a pendant has released/taken control of the input stream.
0 - pendant has released control, senders should resume normal operation - pendant enters listening mode.
1 - pendant has taken over input stream, senders should disable UI but still update controls.

New element |SD:<pct complete>{,<filename>} used to inform status when streaming from SD card.

New element |H:<0|1>{,<axis bitmask>} used to report homing status changes.
0 - homing is not complete.
1 - homing complete.
<axis bitmask> is only added if single axis homing commands are enabled, if so this contains which axes are currently homed.

This element is only added when homing is enabled and then on homing status changes.

New element |D:<0|1> used to report radius/diameter mode changes.
0 - G8: radius mode (default).
1 - G7: diameter mode.

This status is only reported when lathe mode is enabled.

New element |Sc:<axisletters> used to report which axes are scaled, only added on changes.

New element |TLR:<0|1> used to report tool length reference offset status, only added on changes.
0 - Not set.
1 - Set.

New element |FW:<firmware> used to report firmware type, only added to full report requested by 0x87.

This element is always reported as |FW:grblHAL and only when COMPATIBILITY_LEVEL is less than 2. Available from build 20210112.

New element |In:<result> used to report last result from M66 - Wait for input, only added on changes.
-1 is reported if M66 execution failed, 0 or positive value if not. For digital inputs 0 for low level or 1 for high level is reported. Available from build 20210613.

Since some of the elements are only sent on changes an additional real time request character, 0x87, has been added for getting the complete status.

NOTE: Drivers and/or plugins may extend this report with additional elements. Senders should be able to handle that, as a minimum by ignoring them.

Other request responses or push messages

NOTE: all request responses are delimited with (ends with) ok after the last line.

System command extensions

$help or $help <topic>

Lists help topics or help for a specific topic. Most topics are for available settings, $help commands will list available $ system commands.
NOTE: Some system commands may not be documented in this Wiki page as they could be implemented by a plugin or a driver and documented elsewhere, or because I have not made the effort to keep the documentation up to date.

$I response:

Number of supported axes and tool table entries added to the first line:
[OPT:<options>,<block buffer size>,<RX buffer size>{,<number of axes>{,<number of tool table entries>}}]

$I+ extended response adds these tags:

A second line of options is added:
[AXS:<number of axes>:<axisletters>]

where <number of axes> is taken from the N_AXIS symbol definition in grbl/config.h.
and <axisletters> is the axisletters understood by the parser. For a 3-axis machine these are always XYZ, further axes will add to the string up to XYZABCUV for an 8-axis machine.
If ABC remapping is enabled by uncommenting AXIS_REMAP_ABC2UVW in grbl/config.h ABC will be replaced by UVW according to the number of axes enabled.
Available from build 20220923.

A third line of options is added:
[NEWOPT:<comma separated list>]

<comma separated list> can contain any of the following values:

ATC - Automatic tool change (M6) available.
BD - Block delete signal/handling available.
BT - Bluetooth streaming available.
ENUMS - code enumerations are available.
ES - E-stop signal available.
ETH - Ethernet streaming available.
HOME - Homing is enabled.
LATHE - Lathe mode configured.
MPG - MPG mode available (via secondary UART input).
NOPROBE - probe input not available.
ODO - odometer data is available.
OS - Optional stop signal/handling available.
PC - Probe connected signal/handling available.
PID - PID log data available.
RT+ or RT- - Top bit set versions of printable real-time commands plus some additional ones are available.
SED - Settings descriptions available. Use $SED=<n> to output description for setting <n>, e.g. $SED=14 to get a description for $14.
SD - SD Card streaming available.
YM - YModem file transfer to SD card available.
SS - Spindle sync available.
TC - Manual tool change (M6) available.
WIFI - Wi-Fi streaming available.
FTP - FTP file transfer from/to local storage available.
WebDAV - WebDAV file transfer from/to local storage available.

A fourth line with firmware name added:

[FIRMWARE:grblHAL]

A fifth line with enabled input signals added:

[SIGNALS:<signals>]

where <signals> is the same signal letters used for the |Pn:<signals> element in the realtime report.
Added in builds >= 20231228.

If auxilary inputs or outputs are available number of ports is added, e.g:

[AUX IO:3,1,0,0]

The comma separated list contains number of digital inputs, digital outputs, analog inputs and analog outputs respectively. Available from build 20210613.

Optional driver info, e.g:

[DRIVER:MSP432]
[DRIVER VERSION:200928]
[DRIVER OPTIONS:USB]
[BOARD:CNC BoosterPack]

Optional plugin info, e.g.:

[PLUGIN:KEYPAD v1.00]

etc. for each plugin deciding to report itself.

Parser state report extensions

$G response:

[GC:<parser state>]

Some missing from legacy grbl and new gcodes added, these are:

G5 G7 G8 G43 G49 G50 G51 G73 G81 G82 G83 G85 G86 G89 G96 G97 G98 G99 M1 M50 M51 M53 M56 M60

A new setting flag has been added to $10 for pushing this report on changes (following a status report request).

NOTE: Further codes may be added to this list as they become supported.

NGC parameters report extensions

$# response:

Offsets for G59.1, G59.2 and G59.3 has been added.

If scaling is active scaling factors are added:
[G51:<axis scaling factors>]

If homing is enabled axis home positions in machine coordinates are added together with a bitmask indicating which axis values are valid.

[HOME:<axis home positions>:<axis bitmask>]

If a tool table is available (a compile time option in grbl/config.h) tool table contents is added.

[T:<tool number>,<axis offsets>]

TLO report may include offsets for all axes, dependent on compatibility level.

[TLO:<<offset>|<axis offsets>>]

If tool length reference offset is set with the $TLR command, offset for the linear axis is added .
NOTE: This may change in future versions to include offsets for all axes. Senders parsing this tag should be coded to handle that.

[TLR:<tool length reference offset>]

Pins

$pins - enumerate pins.

Outputs a list of pin mappings, processor pin designation -> named pin function.
NOTE: This list may not be 100% accurate in that some pins may be missing from the list, depending on the driver and/or the board map used.

$pinstate - enumerate auxillary pins with current state and capabilities in machine readable format:

[PINSTATE:<type>|<description>|<id>|<mode>|<capabilities>|<state>]

• <type> - string designating the type: AIN - analog in, AOUT - analog out, DIN - digital in, DOUT - digital out.

• <description> - string, may be set by plugin code. If the pin is available for use via M62-M68 it is labeled P<n> or E<n> where <n> is the port number.

• <id> - numeric id, used internally.

• <mode> - current mode as a string consisting of the following characters:
  For digital pins, in the first position:
  I - inverted.
  N - normal or non inverted.
  In the second position, digital input pins only:
  - - floating.
  D - pulldown enabled.
  U - pullup enabled.
  NOTE: this is the internal MCU state, not at the board physical pin connection.
  In the third position, digital input pins only:
  - - interrupt disabled.
  C - change interrupt enabled.
  F - falling edge interrupt enabled.
  H - high state interrupt interrupt enabled.
  L - low state interrupt enabled.
  R - rising edge enabled.
  For analog input pins this element is left empty.
  For analog output pins a single character:
  N - normal (DAC) mode enabled.
  P - PWM mode enabled.
  S - PWM servo mode enabled.

• <capabilities> - capabilities as a string consisting of the following characters:
  For digital pins, in the first position:
  - - inversion not available.
  I - inversion available. .
  In the second position, digital input pins only:
  - - pull up/down not available.
  B - both pull up/down available.
  D - pulldown available.
  U - pullup available.
  In the third position, digital input pins only:
  - - not interrupt capable.
  A - all interrupt modes are avaiable.
  C - change interrupts (rising/falling) available.
  F - falling edge interrupt available.
  H - high state interrupt interrupt available.
  L - low state interrupt available.
  R - rising edge available.
  For analog input pins this element is left empty.
  For analog output pins a single character:
  N - normal (DAC) mode available.
  P - PWM mode available.
  S - PWM servo mode available. This typically requires a plugin that reconfigures PWM capable pins.

• <state> - current state. For digital pins 0 or 1 for low and high respectively, for analog pins the input or output value.
  If the driver does not support reading the state ? is reported.

Spindles

Spindles can be enumerated with the $SPINDLES or $SPINDLESH system commands. Response is one line for each spindle, last line is ok.

The $SPINDLES outputs spindle information in human readable format.

<id> <name> {<info>}

• <id> - spindle id, allocated at registration.
• <name> - name of spindle.
• <info> - optional spindle information, depending on controller configuration:
  , enabled as spindle <n> where <n> is the spindle number.
  , active designates the spindle as currentlyy active.

0 - PWM
0 - PWM, enabled as spindle 0, active

The $SPINDLESH outputs spindle information in machine readable format.

[SPINDLE:<id>|<spindle number>|<type>|<capabilities>|<name>{|<min RPM>,<max RPM>}]

• <id> - spindle id, allocated at registration.
• <spindle number> - used for M104P<n> or $<n> command/parameters, if spindle is not enabled - is reported.
• <type> - spindle type identifier, see the spindle_type_t enum in spindle_control.h for valid values.
• <capabilities> - spindle capabilities as a string consisting of the following characters:
  * - spindle is the currently active spindle.
  S - spindle at speed state is supported.
  D - direction control is supported.
  L - laser mode is supported.
  P - PID RPM control is supported.
  I - PWM output inversion is supported.
  R - RPM range limits is supported. Either read from settings or from the spindle controller.
  V - variable speed is supported.
  E - spindle encoder data is supported (actual RPM, angular position etc.).
• <name> - name of spindle.
• <min RPM> - minimum RPM supported.
• <max RPM> - maximum RPM supported.

NOTE: the min/max RPM elements are optional and will not be added to the output unless the spindle has been initialized.

[SPINDLE:0|0|0|*DLIRV|PWM|0.0,1000.0]

Code sets and enumerations

Code sets and translations can be fetched from the controller, superseding the use of files that has to be kept in sync. Since grblHAL supports plugins and driver specific extensions it will be hard to keep senders up to date via files that has to be updated.

Alarm codes

Alarms can be enumerated with the $EA system command. Response is one line for each alarm, last line is ok.

[ALARMCODE:<code>|<message>|<description>]

[ALARMCODE:1|Hard limit|Hard limit has been triggered. Machine position is likely lost due to sudden halt. Re-homing is highly recommended.]

Error codes

Error codes can be enumerated with the $EA system command. Response is one line for each alarm, last line is ok.

[ERRORCODE:<code>|<message>|<description>]

[ERRORCODE:1|Expected command letter|G-code words consist of a letter and a value. Letter was not found.]

Settings

Settings can be enumerated with the $ES, $ESG or $ESH system commands. Response is one line for each setting, last line is ok.

$ES formatted:

[SETTING:<id>|<group id>|<name>|{<unit>}|<data type>|{<format}]|{<min>}|{<max>}]

• <id> - setting id or number
• <group id> - id to setting group the setting belongs to, see below. For advanced settings handling.
• <name> - name or short description of setting.
• <unit> - optional unit for setting.
• <data type> - code for data type, see below.
• <format> - format string or comma separated list of allowed values/labels for data type 1, 2, and 3.
• <min> - optional minimum value allowed.
• <max> - optional maximum value allowed.

Data types:

• 0 - Boolean, typically rendered as a check box.
• 1 - Bitfield, typically rendered as a column of check boxes.
  The <format> field contains a comma separated list of labels: the first corresponds to bit 0, second to bit 1 and so on. Labels named "N/A" are for unavailable fields and should not be shown in the UI.
• 2 - Exclusive bitfield, typically rendered as a column of check boxes.
  The <format> field contains a comma separated list of labels: the first corresponds to bit 0, second to bit 1 and so on. Labels named "N/A" are for unavailable fields and should not be shown in the UI.
  When bit 0 is not set checkboxes for other bits should be disabled.
• 3 - Radio buttons The <format> field contains a comma separated list of labels: the first corresponds to the value 0, second to value 1 and so on. Labels named "N/A" are for unavailable options and should not be shown in the UI.
• 4 - Axis mask, a bit field typically rendered as a column of check boxes. Number of check boxes corresponds to number of axes, bit 0 is for the X-axis, bit 1 for Y and so on.
• 5 - Integer, typically rendered as a numeric input field.
• 6 - Decimal, typically rendered as a numeric input field.
• 7 - String.
• 8 - Password, as string except data entry could be hidden.
• 9 - IPv4, IP v4 address as a string in dot notation.

Data formats:

• Numeric: start with - if negative values are allowed, a number of # or 0 characters, . for decimal point followed by a number of 0 characters.
  # - suppress if character in position is 0
0 - do not suppress if character in position is 0
• Strings: x(<n>) where <n> is the maximum number of characters allowed. E.g. x(32).

[SETTING:0|18|Step pulse time|microseconds|6|#0.0|2.0|]

$EAG formatted (from build 20210823):

Outputs alarm information in Grbl csv-format. Output is intended for sender use. Note: The column for pre v1.1 alarm messages is populated with "N/A", Not Available.

$EEG formatted (from build 20210823):

Outputs error code information in standard Grbl csv-format. Output is intended for sender use. Note: The column for pre v1.1 error messages is populated with "N/A", Not Available.

$ESG formatted (from build 20210819):

Outputs settings information in standard Grbl csv-format. Output is intended for sender use.

$ESH formatted (from build 20210819):

Outputs settings information in grblHAL tab-separated format. Output is intended for sender use.

Setting groups

Setting groups can be enumerated with the $EG system command. Response is one line for each group, last line is ok. Setting groups are hierachical and can be used for presenting settings in a grouped manner (treeview).

[SETTINGGROUP:<id>|<parent id>|<name>]

[SETTINGGROUP:1|0|General]

---

2024-02-01