MQTT Message Payload Specification

Describes the payload specifications of each MQTT message in CloudPRNT Version MQTT .
The payload of MQTT messages is all JSON formatted data.

Server to Printer

List of topic names (methods)

A list of messages published by a CloudPRNT server to printers.

Method Name

Description

Trigger POST

Full MQTT / Pass URL

request-post

Make a printer perform Polling the server (POST) .

request-client-status

Make a printer publish client-status message.

request-get-server-info

Make a printer perform Server setting information request (GET) .

print-job

Causes a printer to perform printing.

order-client-action

Make a printer perform Client Action .

claim-barcode-reader

Requests the data read by a barcode reader attached to a printer.

output-to-display

Control a customer display connected to a printer.

apply-starconfiguration

Apply a Star Configuration Format to a printer and change the printer settings.

request-post

overview

A message to make a printer perform Polling the server (POST) .
A Printer that receive this message perform Polling the server (POST) .
Triggered by this Polling the server (POST) , the CloudPRNT Version HTTP printing operation can be started.

Topic

star/cloudprnt/to-device/{printermac}/request-post

Payload example

{
    "title" : "request-post"
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “request-post”.

request-client-status

A message that make a printer publish a client-status message.
Normally, a printer publishes a status notification message only when there is a status change on the printer side.
When a CloudPRNT server wants to know a printer status immediately, it can obtain the printer status immediately by publishing this message.
If you want the printer to periodically publish client-status message, refer to the pollingTimeSec key of the Server setting information request (GET), Response (GET).

Topic

star/cloudprnt/to-device/{printermac}/request-client-status

Payload example

{
    "title" : "request-client-status"
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “request-client-status”.

request-get-server-info

This message is used to make a printer execute Server setting information request (GET) at any given time.
A printer that receives this message executes Server setting information request (GET) .
If the obtained settings have been changed from the previously obtained settings, CloudPRNT operation will start with the new settings.

Topic

star/cloudprnt/to-device/{printermac}/request-get-server-info

Payload example

{
    "title" : "request-get-server-info"
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “request-get-server-info”.

order-client-action

This is a message to make the printer perform Client Action .
When a printer receives this message, it will publish a client-status message.
The Client Action response is included in its payload.

Topic

star/cloudprnt/to-device/{printermac}/order-client-action

Payload example

{
    "title" : "order-client-action",
    "clientAction": [ {"request": "<request type>", "options": "<request parameters>"} ]
}
{
    "title" : "order-client-action",
    "clientAction": [
        {"request": "ClientType", "options": ""},
        {"request": "Encodings", "options": ""}
    ]
}

Payload details

Key

Type

Required

Decsription

title

string

true

“Fixed to “order-client-action”.

clientAction

[object]

true

Client Action object

[clientAction].request

string

true

Client Action request

[clientAction].options

string

true

Client Action parameter

claim-barcode-reader

This is a message to request the data read by a barcode reader connected to a printer.
A printer that receives the claim request publishes a client-status message when it reads the data with a barcode reader.
The payload of client-status contains the read data.

Topic

star/cloudprnt/to-device/{printermac}/claim-barcode-reader

Payload example

{
    "title" : "claim-barcode-reader",
    "claimBarcodeReader": [
        {
            "name": "<device name>",
            "claim" : true
        }
    ]
}

Payload details

Key

Type

Required

Decsription

title

string

true

“Fixed to “claim-barcode-reader”.

claim-barcode-reader

[object]

true

barcode reader control object

[claimBarcodeReader].name

string

true

Specify the barcode reader device name you want to control

[claimBarcodeReader].claim

boolean

true

true : Barcode reader control start
false : Barcode reader control end

output-to-display

This message is for controlling a customer display connected to a printer.

Topic

star/cloudprnt/to-device/{printermac}/output-to-display

Payload example

{
    "title" : "output-to-display",
    "display": [
        {
            "name": "<device name>",
            "message": "<message markup>"
        }
    ]
}

Payload details

Key

Type

Required

Decsription

title

string

true

“Fixed to “output-to-display”.

display

[object]

true

customer display control object

[display].name

string

true

Specify the customer display device name you want to control

[display].claim

string

true

Content to be displayed on a customer display.
Refer to Display .

apply-starconfiguration

This message is for applying a Star Configuration Format to a printer.
A printer that receives this message applies the Star Configuration Format according to the payload.
It then Publishes a starconfiguration-result message.

Topic

star/cloudprnt/to-device/{printermac}/apply-starconfiguration

Payload example

In the example below, a printer applies the Star Configuration Format data specified in the starconfiguration payload.

{
    "title" : "apply-starconfiguration",
    "jobToken" : "tokenID",
    "jobType" : "raw",
    "starconfiguration" : "DQogInRpdGxlIjogInN0YXJfY29uZmlndXJhdGlvbiIs..."
}

In the example below, a printer executes Print job requests (GET) to the URL specified in the starconfiguration of the payload and applies the data obtained in the response.

{
    "title" : "apply-starconfiguration",
    "jobToken" : "tokenID",
    "jobType" : "url",
    "starconfiguration" : "https://dataserver..."
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “apply-starconfiguration”.

jobToken

string

true

A unique token that you assign to each job.

jobType

string

true

raw : Applies the value of the starconfiguration key.
url : Acquire and apply data from the URL specified by the starconfiguration key value with Print job requests (GET) .

starconfiguration

string

true

Specifies a StarConfiguration Format data.

Additional information about payload

  • jobToken

    A printer remembers the last 10 jobTokens. If an apply-starconfiguration message with the same jobToken is received, the settings will not be applied.
    If a duplicate jobToken is received, the jobToken duplication will be notified in the statusCode key of the starconfiguration-result message.
  • starconfiguration

    If jobType is raw, store StarConfiguration Format data in Base64 format.
    If jobType is url, stores the URL of the StarConfiguration Format data data.

Printer to Server

Note

Publishing MQTT messages from a printer to a CloudPRNT server only occurs when using CloudPRNT Version MQTT (Full MQTT / Pass URL) .
In CloudPRNT Version MQTT (Trigger POST), a printer does not publish MQTT messages.

List of topic names (methods)

A list of messages published by a printer to a CloudPRNT server.

Method Name

Description

Trigger POST

Full MQTT / Pass URL

client-status

Notify a printer status.

print-result

Report a print result for the received print-job message.

starconfiguration-result

Notify a result of the received apply-starconfiguration message.

client-will

Notify that a printer has been disconnected from a MQTT broker.

client-status

overview

This message is used to notify a CloudPRNT server of a printer status.
A printer publishes this message in the following situations.
  • When connected to a MQTT broker

  • When a printer status changes

  • When a barcode is read while claiming a barcode reader

  • When a request-client-status message is received from a CloudPRNT server

  • When an order-client-action message is received from the CloudPRNT server

Topic

star/cloudprnt/to-server/{printermac}/client-status

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “client-status”.

Other key-value specifications follow JSON Request of Polling the server (POST) .

starconfiguration-result

overview

This is a message to notify the setting result after receiving a apply-starconfiguration message from a CloudPRNT server and performing the StarConfig setting operation.

Topic

star/cloudprnt/to-server/{printermac}/starconfiguration-result

Payload example

{
    "title" : "starconfiguration-result",
    "jobToken" : "tokenID",
    "statusCode": "200%20OK",
    "printerMAC": "<Ethernet MAC address>",
    "uniqueID": "<server assigned ID>",
    "firmware": "success",
    "skip": 0,
    "error": 0
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “starconfiguration-result”.

jobToken

string

true

jobToken assigned by a apply-starconfiguration message issued by a CloudPRNT server

statusCode

string

true

Refer to Printer Status Codes

printerMAC

string

true

Printer Ethernet MAC address

uniqueID

string

false

ID assigned by a CloudPRNT server with SetID of Client Action .

firmware

string

false

The result of the execution will be set

skip

string

true

The number of items skipped will be set

error

string

true

The number of items that were processed in error will be set

client-will

overview

A Will message registered when a printer connects to a MQTT broker.
Delivered by a broker when a printer is unintentionally disconnected from the network.
Depending on the printer model, when the power is turned off and successfully terminated, the printer will publish a message in the same format on the spot instead of Will registered with the broker.
The value of the unintentionalDisconnection key can be used to determine whether an abnormal disconnection occurred.

Topic

star/cloudprnt/to-server/{printermac}/client-will

Payload example

{
    "title" : "client-will",
    "printerMAC": "<Ethernet MAC address>",
    "uniqueID": "<server assigned ID>",
    "unintentionalDisconnection" : true
}

Payload details

Key

Type

Required

Decsription

title

string

true

Fixed to “client-will”.

printerMAC

string

true

Printer Ethernet MAC address

uniqueID

string

false

ID assigned by a CloudPRNT server with SetID of Client Action .

unintentionalDisconnection

boolean

false

true : The printer was unintentionally disconnected from the network.
false : The printer was turned off correctly with a soft switch.