JSON Details - synthetos/TinyG GitHub Wiki

NOTE: This page describes JSON operations in release 0.95 and later. This page is really a continuation of this page

Commands in JSON mode are sent as JSON objects. Some request and response examples:

{"xfr":n}        {"r":{"xfr":12000.000},"f":[1,0,14,3009]}   get the X axis max feed rate
{"xfr":12000}     {"r":{"xfr":12000.000},"f":[1,0,14,3009]}   set the X maximum feed rate to 12000 mm/min (assuming the system is in G21 mode)
{"x":n}          {"r":{"x":{"am":1,"vm":16000.000,....       get all configuration settings for the X axis
{"gc":"g0 x100"}  {"r":{"gc":"g0x100"},"f":[1,0,17,9360]}     execute the Gcode block "G0 X100"

where  "f":[1,0,255,1234]  
   is  "f":[<protocol_version>, <status_code>, <input_available>, <checksum>]

Footer in edge-0.97 (build 441.05 and later, including build 449): the footer has three elements and no checksum. The first element tells you which form it is, and follows the serial receive mode ($rxm):

A transaction ID, if the request had one, is returned as a top-level "tid" between "r" and "f" (see Text Wrappers and Transaction IDs). If a response is too long for the 512 byte output buffer, its body is dropped and {"r":{},"f":[...]} is returned; an OK status is then reported as 13 (buffer full). A syntax error is returned as {"r":{"err":"<the input line>"},"f":[...]} with status 111. The rest of this section describes the earlier 4 element footer.

Responses are wrapped in a response body and include a footer. Requests and responses are a single line of text terminated by CR, LF or CR/LF depending on the board configuration settings ($ec, $el). Requests and responses can be up to 256 characters long but are generally much shorter.

The 4 element footer below applies to firmware before build 441.05.

The footer contains a 4 element array:

Character echo ($ee) is always an option; it's just not a good one for JSON. In JSON mode it should be turned off ( $ee=0, or {"ee":0} ). It's a matter of preference for text mode.

JSON verbosity ($jv) sets the level of verbosity in JSON responses. It is set by {"jv":N} where N is one of:

Generally levels 2, 3 or 4 are recommended.

To get a parameter pass an object with a null value. The value is returned in the response. Some examples of valid requests and responses are provided below.

To set a parameter pass an object with the value to be set. The value applied is returned in the response. The response value may be different than the requested valued in some cases. For example, an attempt to set a status report interval less than the minimum will return the minimum interval. Trying to set a read-only value will return that value; for example, firmware version. In some other cases a value of 'false' will be returned. The following are examples of valid set commands. All requests and responses are on a single line of text (even if the table below wraps on your display).

An attempt to set a read-only value (for example fv) fails with status 104 (parameter is read-only). The status interval ranges from 100 through 2,147,483,647 ms: smaller nonnegative values are raised to 100, and larger values are refused with status 110.

The following groups can be read and set using JSON. The JSON strings provided below (i.e. the group with a null value ("")) will return all members of the group.

{"1":n}    return motor 1 settings
{"2":n}
{"3":n}
{"4":n}
{"x":n}    return X axis settings
{"y":n}
{"z":n}
{"a":n}
{"b":n}
{"c":n}
{"sys":n}  return system settings
{"pos":n}  return work coordinate positions fox XYZABC axes. In mm or inches depending on G20/G21
{"mpo":n}  return absolute machine positions fox XYZABC axes. Always in mm, regardless of G20/G21
{"ofs":n}  return current offsets fox XYZABC axes. Sums coordinate system and G92 offsets. in mm.
{"hom":n}  return homing state fox XYZABC axes, and 'e' for the entire machine. 1=homed, 0=not.
           (build 449: {home:1} starts a homing cycle like G28.2; home reads 2 while homing)
{"p1":n}   return PWM channel 1 settings (currently there is only 1 PWM channel)
{"g54":n}  return offsets for work coordinate system #1 (G54)
{"g55":n}  #2
{"g56":n}  #3
{"g57":n}  #4
{"g58":n}  #5
{"g59":n}  #6
{"g92":n}  return G92 offsets currently in effect
{"g28":n}  return coordinate saved by G28 command
{"g30":n}  return coordinate saved by G30 command
{"in":n}   return switch input states in1-in8 (build 449): -1 = input disabled, 0 = inactive (open), 1 = active (closed). Read-only
{"jid":n}  return the job ID jida-jidd (build 449): four 32-bit values for a host-defined job identifier. Not saved; cleared at reset
{"uda":n}  return user data uda0-uda3 (build 449); also udb, udc, udd. Sixteen 32-bit values for host use, saved to EEPROM
{"pwr":n}  return motor enable states pwr1-pwr4 (build 449): 1 = enabled. Read-only
{"prb":n}  return the last probe result (build 449); see the Probing page

Build 449: jid* and ud** values are raw 32-bit data. In JSON they are written and read as hex strings, e.g. {"uda0":"0x1234abcd"}; a number fails with status 116 and a string that does not start with 0x fails with status 102. Text mode prints them as decimal. admo (arc distance mode) reads 0 = G90.1 absolute IJK, 1 = G91.1 incremental IJK.

Group members are processed in order. A stored setting is persisted only after its setter succeeds. The first child read, write or persistence error is returned as the group's status, and later members are not processed. A rejected write is not persisted. Earlier successful writes remain applied and saved; a group SET does not roll them back. A member with a null value is a read, not a write.

For example, in {"x":{"vm":1500,"fr":0,"jm":20}}, the valid velocity write can succeed and be saved before the feed-rate write is refused. The group returns the feed-rate error, and the jerk setting is not changed.

Values within a group can be set by including that member in the set command. Examples:

Set velocity max and feed rate max only (other values are unchanged)
{"x":{"vm":1500,"fr":1500}}

Set all values in X
{"x":{"am":1,"vm":1500,"fr":1500,"tm":150,"jm":600000000,"jh":400000000,"jd":0.0100,"sn":1,"sx":0,"sv":750,"lv":150,"lb":5.000,"zb":0.000}}

Status messages are end-user text associated with each status code, similar to those on the Status Codes page. JSON does not return these whereas text mode does. JSON parsers must therefore work to the status codes, and provide their own end-user messages.

HOWEVER
There are 2 cases where messages are returned in responses

• System-generated advisory messages may be returned as "msg" tags. Unsupported microstep values are refused, not accepted with a warning; see microstep settings.

• Gcode provided messages. A Gcode block can have a comment that starts with the string "msg". For example, (msgChange tool and hit cycle start) will return "Change tool and hit cycle start" as data for a "msg" tag. Presumably the UI would want to display this message.

Gcode line numbers are returned as n objects if they are provided in a Gcode file - i.e. the line starts with Nxxxx where xxxxx is a number. An example is:

In JSON mode Gcode blocks may be provided either as native gcode text or wrapped in JSON as a "gc" object. In either case responses will be returned in JSON format. A JSON wrapper may only contain a single gcode block.

The first responses are pretty normal. The third has a comment in it. The fourth is what would happen if a MSG were communicated in the Gcode comment.