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>",
    "jobToken": "<token string>",
    "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 Client Action 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.

Some JSON parameters are supported from certain firmware versions, depending on the supported models:

Key Name

IFBD-HI01X/HI02X

mC-Print2/3

TSP100IV

TSP100IV SK

mC-Label3

printingInProgress

1.4 or later

1.2 or later

1.0 or later

2.0 or later

1.0 or later

jobToken

1.8 or later

3.2 or later

1.0 or later

2.0 or later

1.0 or later

barcodeReader

1.4 or later

1.2 or later

1.0 or later

2.0 or later

1.0 or later

keyboard

1.4 or later

n/a

n/a

n/a

n/a

display

1.4 or later

1.2 or later

1.0 or later

2.0 or later

1.0 or later

Note

JSON parameters and supported models not listed in the table are supported by all firmware versions.

  • “status”
    Provides the server with printer status information in Star ASB style.
    For detail information about the printer status in Star ASB format, refer to the printer’s command specifications.
    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, 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 or 4digit 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.
  • “jobToken”
    Optional string value(Some models are supported from specific firmware versions).
    If the server has specified a job token string with jobReady true, then it will be included with each POST while that job is in progress.
    Once the corresponding DELETE has been accepted by the server (for this particular job) then this field will be excluded.
    Note that if the printer goes to an offline status (no paper, cover open) during printing when the server specifies the “jobToken” field, the printer will be notified until printer return to online status and receives the POST response which is included “jobReady” field set a true value.
  • “printingInProgress”
    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.
    Refer to Client Action .
    If there are no responses needed, then this field may be missing, of have a value of null.
  • “barcodeReader”
    An array of objects representing available barcode reader hardware. Please see Barcode Reader section below.
    Refer to Barcode Reader for details.
  • “keyboard”
    An array of objects representing available keyboards.
    Refer to Keyboard for details.
  • “display”
    An array of objects representing available line displays.
    Refer to Display for details.

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 Client Action 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"}
    ]
}

The example of polling during the print job processing which is after issuing a GET request from the client in response to the POST response including “jobReady”:”true” and “jobToken”:”PrintJob1” from the server.

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "jobToken": "PrintJob1",
    "printingInProgress": true,
    "clientAction": null
}

Client HTTP Request Header

Supported Device Versions:

Device Name

FW Version

IFBD-HI01X/HI02X

1.8 or later

mC-Print2/3

3.2 or later

TSP100IV

1.0 or later

TSP100IV SK

2.0 or later

mC-Label3

1.0 or later

Please refer to Client HTTP Request Headers for detail.

StatusCode for the device supported holdprint feature

Supported Device Versions:

Device Name

FW Version

IFBD-HI01X/HI02X with TSP650IISK

1.9 or later

TSP100IV SK

2.0 or later

mC-Label3

1.0 or later
Printers supported holdprint feature can detect whether if remains a printed receipt at paper exit.
And Star CloudPRNT client will inform a unique status by “status” / “statusCode”.
Reference: Printer Status Codes

During printing a print job:

{
    "status": "23 6 0 0 0 0 0(or 2) 0 0 ",
    "printerMAC": "00:11:62:0d:82:98",
    "statusCode": "220%20Printing%20In%20Progress",
    "printingInProgress": true,
    "clientAction": null
}

This “220” statusCode is equivalent to “printingInProgress: true”.

After printing a printjob(after DELETE request) and a paper is present at paper exit:

{
    "status": "23 6 0 0 0 0 2 0 0 ",
    "printerMAC": "00:11:62:0d:82:98",
    "statusCode": "221%20Output%20Paper%20Present",
    "printingInProgress": false,
    "clientAction": null
}
While this status / “221” statusCode informs, client will not issue GET request.
This behavior can be changed by the PaperPresentStatusMonitor of Client Action.

After taking the paper from paper exit:

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "jobToken": "PrintJob1",
    "printingInProgress": true,
    "clientAction": null
}
This “201” statusCode is equivalent to “200” statusCode(It will inform “200” statusCode from client in next POST request).
After this statusCode, client will issue GET request if server sends “jobReady:true”.