TinyG Status Reports

Status Reports in JSON

Status reports provide a view of what's going on in the controller. They report "dynamic gcode model" state. In plain English, they tell you where you are (position), if the machine is moving, how fast, what it's doing, when a move is done, and other stuff as well. They can be returned on-demand, or can be automatically generated during movement so you can see move progress. They are delivered in JSON so the UI can use it, or can be delivered in plain test for a command-line user.

The following variables can be reported in a status report

Request | Response | Description
---------|--------------|-------------
n | line_number | Gcode line number (N word)
vel | velocity | actual velocity - may be different than programmed feed rate 
feed | feed_rate          | gcode programmed feed rate (F word) 
stat | machine_state      | 1=reset, 2=alarm, 3=stop, 4=end, 5=run, 6=hold, 7=probe, 9=homing 
unit | units_mode         | 0=inch, 1=mm
coor | coordinate_system  | 0=g53, 1=g54, 2=g55, 3=g56, 4=g57, 5=g58, 6=g59
momo | motion_mode        | 0=traverse, 1=straight feed, 2=cw arc, 3=ccw arc
plan | plane_select       | 0=XY plane, 1=XZ plane, 2=YZ plane
path | path_control_mode  | 0=exact stop, 1=exact path, 2=continuous
dist | distance_mode      | 0=absolute distance mode, 1=incremental distance mode
frmo | feed_rate_mode     | 0=units-per-minute-mode, 1=inverse-time-mode
macs | machine state | internal state for deeper inspection
cycs | cycle state | internal state for deeper inspection
mots | motion state | internal state for deeper inspection
hold | hold state | internal state for deeper inspection

The following are available for all axes, XYZABC. Only pos is expanded for illustration

Request | Response | Description
---------|--------------|-------------
posx | x work position | X work position in prevailing units (mm or inch) 
posy | y work position
posz | z work position
posa | a work position
posb | b work position
posc | c work position
mpox | x absolute position | X machine position in absolute coordinate system (mm or inch).
g92x | offset | G92 origin offset for X axis
g54x | coord 1 offset | X axis G54 coordinate system offset
g55x | coord 2 offset | X axis G55 coordinate system offset
g56x | coord 3 offset | X axis G56 coordinate system offset
g57x | coord 4 offset | X axis G57 coordinate system offset
g58x | coord 5 offset | X axis G58 coordinate system offset
g59x | coord 6 offset | X axis G59 coordinate system offset
g28x | G28 position | X axis G28 saved position
g30x | G30 position | X axis G30 saved position

It's worth noting that any gettable variable can be put in a status report - the above variables are listed as they represent the Gcode model state. For example fv would return the firmware version, but this would not change.

It's also worth noting that any variable can be independently queried as an individual variable, and axis variables (e.g. pos, G55) can be queried as a group, e.g. pos, or g55

Text Mode Status Reports

Text Mode On-Demand Status Reports

Enter a '?' to get a status report in text mode.

Text Mode Automatic Status Reports

Automatically generated status reports may enabled with $sv=1 or $sv=2. Reports will be generated for each new command entered, during movement every N milliseconds, and when the machine has stopped (i.e. at the end of the final move in the buffer).

Filtered status reports $sv=1 return only variables that have changed since the previous report. This saves serial bandwidth and host processing time.

$sv=0      turn off automatic status reports
$sv=1      turn on filtered automatic status reports
$sv=2      turn on unfiltered automatic status reports
$si=200    request status reports every 200 ms during movement

JSON Mode Status Reports

JSON mode status reports are parent/child objects with a "sr" parent and one or more child NV pairs, as in the example below.

{"sr": {"line":1245, "posx":23.4352, "posx":-9.4386, "posx":0.125, "vel":600, "unit":"1", "stat":"5"}"f":[1,0,19,2131]}}

JSON Mode On-Demand Status Reports

This will return a single status report. The two forms below are equivalent.

{"sr":""}
{"sr":null}         the `null` value is used instead of "" in this case. Either are accepted.

JSON Mode Automatic Status Reports

Automatically generated status reports may enabled with {"sv":1} or {"sv":2}. Reports will be generated for each new command entered, during movement every N milliseconds, and when the machine has stopped (i.e. at the end of the final move in the buffer).

Filtered status reports {"sv":1} return only variables that have changed since the previous report. This saves serial bandwidth and host processing time.

{"sv":0}      turn off automatic status reports
{"sv":1}      turn on filtered automatic status reports
{"sv":2}      turn on unfiltered automatic status reports
{"si":200}    request status reports every 200 ms during movement

Set Status Report Fields

In addition to on-demand and automatic status reports, JSON mode also supports setting the fields to be displayed in status reports. Although this command is only supported in JSON mode, the fields set in JSON apply to both JSON and text mode reports.

Variables to be included in a status reports are selected by setting values to 'true'. These variables will be returned on subsequent SR requests in the order they were provided in the SET command. There is no incremental setting of variables - all variables are reset and must be specified in a single SET command.

For example, the string below could be used to set up the status report in the example above, and eliminate any previously recorded settings. Note that the 'true' term is not in quotes - it is actually the JSON value for true, not a string that says "true". Example:

{"sr":{"line":true,"posx":true, "posy":true,"posz":true, "vel":true, "unit":true, "stat":true}}