TinyG Status Reports

Status Reports in JSON

Status reports return the dynamic gcode model state. In plain English, they tell you where you are. And other stuff as well. This is useful for the user or the UI to know what's happening in the machine. For example, hitting '?' from the command line will return the current XYZ position, the inches/mm units mode, and some other relevant data.

Status reports can also be automatically generated during movement so you can see move progress.

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=shutdown, 3=stop, 4=end, 5=run, 6=hold, 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, 1=incremental distance
frmo | feed_rate_mode     | 0=units-per-minute-mode, 1=inverse-time-mode
gc | gcode_block        | gcode block currently being run
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). Also Y,Z,A,B,C 
g92x | offset | G92 origin offset for X axis (also Y,Z,A,B,C)
g54x | coord system 1 offset | X axis G54 coordinate system offset (also Y,Z,A,B,C)
g55x | coord system 2 offset | X axis G55 coordinate system offset (also Y,Z,A,B,C)
g56x | coord system 3 offset | X axis G56 coordinate system offset (also Y,Z,A,B,C)
g57x | coord system 4 offset | X axis G57 coordinate system offset (also Y,Z,A,B,C)
g58x | coord system 5 offset | X axis G58 coordinate system offset (also Y,Z,A,B,C)
g59x | coord system 6 offset | X axis G59 coordinate system offset (also Y,Z,A,B,C)
g28x | G28 home position | X axis G28 home position (also Y,Z,A,B,C)
g30x | G30 home position | X axis G30 home position (also Y,Z,A,B,C)

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.

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

On-Demand Text Mode Status Report

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

Automatic Text Mode Status Reports

Status reports may also be automatically generated by setting the status report interval to a non-zero value. Reports will be generated during movement every N milliseconds, and at the end of each Gcode bloack that causes a movement, and when the machine has stopped (i.e. at the end of the final move in the buffer).

$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, "xpos":23.4352, "ypos":-9.4386, "zpos":0.125, "vel":600, "unit":"1", "stat":"5"}"f":[1,0,19,2131]}}

The following use-cases are supported:

Set Status Report Fields

The elements to be included in a status reports may be specified by setting values to 'true'. The elements will be returned on subsequent SR requests in the order they were provided in the SET command. (I know, dictionaries are supposed to be unordered, but the firmware will record and return back the attributes in the order listed). There is no incremental setting of elements - all attributes 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". Examples:

{"sr":{"line":true,"xpos":true, "ypos":true,"zpos":true, "vel":true, "unit":true, "stat":true}}

JSON On-Demand Status Report

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 Automatic Status Reports

Status reports may also be automatically generated by setting the status report interval to a non-zero value. Reports will be generated during movement every N milliseconds, and at the end of each Gcode bloack that causes a movement, and when the machine has stopped (i.e. at the end of the final move in the buffer).

{"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