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”.

print-job

This is a message to let a printer execute printing.
When a printer receives this message, it starts printing operation according to the payload.
It then publishes a print-result message.

Note

Before sending this message to a printer, please make sure that the printer is not currently printing. The specific method is as follows.

The server received a print-result message from the printer in response to a print command from the previous print-job message.

The value of the printingInProgress key in the client-status message issued by the printer is false.

Topic

star/cloudprnt/to-device/{printermac}/print-job

Payload example

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

{
    "title" : "print-job",
    "jobToken" : "tokenID",
    "jobType" : "url",
    "mediaTypes" : ["application/vnd.star.starprnt", "image/vnd.star.png"],
    "printData" : "https://dataserver..."
}

In the example below, a printer prints the text data specified by printData in the payload.

{
    "title" : "print-job",
    "jobToken" : "tokenID",
    "jobType" : "raw",
    "mediaTypes" : ["text/plain"],
    "printData" : "Hello, StarMicronics.",
    "printerControl" : {
        "cutter" : {
            "type" : "partial",
            "feed" : true
        }
    }
}

Payload details

Key	Type	Required	Decsription
title	string	true	Fixed to “print-job”.
jobToken	string	true	A unique token assigned to each print job.
jobType	string	true	raw : Print the value of the printData key. url : Get the print data from the URL specified by the printData key value with Print job requests (GET) and print it.
mediaTypes	[string]	true	Specifies the type of print data specified in printData. Content Media Types When jobType is raw, specify only one value in the string array.
printData	string	true	Specify print data.
printerControl	object	false	An object that contains values that specify the cutting operation of the printer, etc. Use when jobType is raw and printData cannot contain control commands.

printerControl object specification

Key	Type	Required	Decsription
buzzer	object	false	An object that summarizes the values associated with the buzzer control
buzzer.startPattern	number	false	Performs buzzer before printing the sent job. The specified value is a number of performing buzzer. Value Range: From ‘1’ to ‘3’ (The number of times specification does not work in MCS10, so please specify 1.)
buzzer.endPattern	number	false	Performs buzzer after printing the sent job. The specified value is a number of performing buzzer. Value Range: From ‘1’ to ‘3’ (The number of times specification does not work in MCS10, so please specify 1.)
cutter	object	false	An object that summarizes the values associated with the cutter control
cutter.type	string	false	Specify the cutting operation after printing the job. full : full cut partial : partial cut none : Not not cut
cutter.feed	boolean	false	Specifies the paper feed for the cut operation after printing the job. true : Paper feed false : Do not feed paper
imageDitherPattern	string	false	Specify the dithering method to use when printing and image. fs : use Floyd Steinberg error diffusion dither (Default) none : disable dithering
cashDrawer	string	false	Trigger opening a cash drawer at the start or end of a job. none : do not use the drawer start : open before printing end : open after printing
holdPrintSensor	object	false	An object that summarizes the values associated with the hold print sensor
holdPrintSensor.paperPresentStatusControl	string	false	Set a flag that the client will use to decide a command about an control of paper present status send to printer at prnting a job. If specified this option, then PaperPresentStatusControl value of Client Action is ignore once. default : After sending next print job, follows a client’s memory switch setting. valid - After sending next print job, informs the paper present status in printer ASB status at 7th byte. invalid - After sending next print job, does not inform the paper present status.
holdPrintSensor.holdPrintControl	string	false	Set a flag that the client will use to decide a command about an control of hold print send to printer at prnting a job. If specified this option, then HoldPrintControl value of Client Action is ignore once. default : After sending next print job, follows a client’s memory switch setting. valid : After sending next print job, enable the FW control of hold print. invalid - After sending next print job, disable the FW control of hold print. It recommends to set invalid when use this option.

Additional information about payload

jobToken

A printer remembers the last 10 jobTokens. If a print-job message with the same jobToken is received, print processing will not be performed.

If a duplicate jobToken is received, the jobToken duplication will be notified in the statusCode key of the print-result message.
jobType

If raw is specified, do not specify multiple values for the mediaTypes key.

If url is specified, a print-result message is published after the printer completes printing. Not Print job confirmation (DELETE)
printData

If jobType is raw, the print data itself is stored. If the mediaType is not text/plain, store it in Base64 format.

If jobType is url, stores the URL of the print data.
printerControl

Corresponds to the response header of Print job requests (GET) .

Use when jobType is raw and printData cannot contain control commands.

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	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) .

print-result

overview

This is a message to notify the print result after a printer receives a print-job message from a CloudPRNT server and performs the printing operation.

Topic

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

Payload example

{
    "title" : "print-result",
    "jobToken" : "tokenID",
    "printSucceeded" : true,
    "statusCode": "200%20OK",
    "printerMAC": "<Ethernet MAC address>",
    "uniqueID": "<server assigned ID>"
}

Payload details

Key	Type	Required	Decsription
title	string	true	Fixed to “print-result”.
jobToken	string	true	jobToken assigned by a print-job message issued by a CloudPRNT server
printSucceeded	boolean	true	true : Successfully printed. false : Printing failed.
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 .

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.