JSON Request

The request body sent from the client is in JSON format, based on the following template:

{
    "status": "<ASB Hex format>",
    "printerMAC": "<Ethernet MAC address>",
    "uniqueID": "<server assigned ID>",
    "statusCode": " <description>",
    "printingInProgress": bool,
    "clientAction": [{
    "request": "<request type>",
    "result": "<request result>"
    }],
    "barcodeReader": [{
    "name": "<device logical name>",
    "status": { "connected": bool, "claimed": bool },
    "scan": [ {"data": "<scanned barcode character sequence>",
    "symbology": "<symbology of scanned barcode>"}]
    }],
    "keyboard": [{
    "name": "<device logical name>",
    "status": { "connected": bool, "claimed": bool },
    "keyPresses": "<key presses since last poll>"
    }],
    "display": [{
    "name": "<device logical name>",
    "status": {"connected": bool}
    }]
}

All fields, except "statusCode" are optional and will be specified only if configured and needed, or may have a null value, servers should be able to handle either case..

The "clientAction" field is specified only if the server has sent a "clientAction" request to ask for specific details, (e.g. firmware version, memory switch setting etc) or to inform the server of events that are not encoded in printer device status.

  • "status" - provides the server with printer status information in Star ASB style. If this is not provided, then the server can assume that the printer is online if statusCode value beginning with "2" (e.g. "200" is provided).
  • "printerMAC" - provide the server with the MAC address of the printer. Note that this is primarily for client identification purposes and may not be the MAC address that the request is issued from in case the client has multiple routes to the server. For example, the HI01/02x interface with always use the Ethernet MAC address, even if WiFi is used.
  • "uniqueID" - a server assigned ID. This field will only be included in the request if the server has assigned an ID.
  • "statusCode" - provide a 3 digit status code (based on http status codes, but not directly compatible) and description of the printer state. Typically this will be "200 OK" to indicate that the printer is online and ready. In case of print job failure, or offline, then an error state can also be passed, see Printer Status Codes section for details. Status codes from a CloudPRNT client are URL encoded, because they may also be sent as a URL parameter, for example when the printer sends a DELETE request.
  • "printingInProgress" - added in HI01x/HI02x firmware version 1.4. A Boolean value which indicates that a print operation is currently in progress. This is provided by clients which may issue polls to the server during a print operation. This is helpful to indicate that the "jobReady" response field will be ignored and so the server may avoid doing database or similar checks to determine whether a job is available. It may also be useful status to display to users. Please note that this field is optional and may not be included in the POST request from all clients, therefore it should not be used as a signal that printing is completed (please monitor GET/DELETE and POST responses for this).
  • "clientAction" - an array of responses to server requests, see Client Action section below. If there are no responses needed, then this field may be missing, of have a value of null.
  • "barcodeReader" - added in HI01x/HI02x firmware version 1.4. An array of objects representing available barcode reader hardware. Please see Barcode Reader section below.
  • "keyboard" - added in HI01x/HI02x firmware version 1.4. An array of objects representing available keyboards. Please see Keyboard section below.
  • "display" - added in HI01x/HI02x firmware version 1.4. An array of objects representing available line displays. Please see Display section below.

Example POST requests

  • Common poll data, includes printer status and MAC address identifier
{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "statusCode": "200%20OK",
    "clientAction": null
}
  • Poll sent after the server has requested the polling interval and list of supported encodings using "clientAction" requests, to a printer with an "UniqueID" set to "Star1"
{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "clientAction": [
    {"request":"GetPollInterval","result":"10"},
    {"request":"Encodings","result":"image/png; image/jpeg; application/vnd.star.raster;
    application/vnd.star.line; application/vnd.star.linematrix; text/plain; application/octet-stream"}
    ]
}