MQTT Message Payload Specification
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 |
---|---|---|---|
Make a printer perform Polling the server (POST) . |
✓ |
||
Make a printer publish client-status message. |
✓ |
||
Make a printer perform Server setting information request (GET) . |
✓ |
✓ |
|
Causes a printer to perform printing. |
✓ |
||
Make a printer perform Client Action . |
✓ |
||
Requests the data read by a barcode reader attached to a printer. |
✓ |
||
Control a customer display connected to a printer. |
✓ |
||
Apply a Star Configuration Format to a printer and change the printer settings. |
✓ |
request-post
overview
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
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
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
Note
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. |
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
|
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
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
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
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
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
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 |
---|---|---|---|
Notify a printer status. |
✓ |
||
Report a print result for the received print-job message. |
✓ |
||
Notify a result of the received apply-starconfiguration message. |
✓ |
||
Notify that a printer has been disconnected from a MQTT broker. |
✓ |
client-status
overview
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
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 |
starconfiguration-result
overview
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 |
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
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 |
unintentionalDisconnection |
boolean |
false |
true : The printer was unintentionally disconnected from the network.
false : The printer was turned off correctly with a soft switch.
|