MQTTメッセージペイロード仕様

CloudPRNT Version MQTT における、各MQTTメッセージのペイロード仕様について説明します。

MQTTメッセージのペイロードは、全てJSONフォーマットのデータです。

Server to Printer

トピック名(メソッド)一覧

CloudPRNTサーバーがプリンターに対して発行するメッセージの一覧です。

Method Name	Description	Trigger POST	Full MQTT / Pass URL
request-post	プリンターに サーバーポーリング (POST) を実行させます。	✓
request-client-status	プリンターに client-status メッセージを発行させます。		✓
request-get-server-info	プリンターに サーバー設定情報取得リクエスト (GET) を実行させます。	✓	✓
print-job	プリンターに印刷を実行させます。		✓
order-client-action	プリンターに Client Action を実行させます。		✓
claim-barcode-reader	プリンターに接続されているバーコードリーダーが読み取ったデータを要求します。		✓
output-to-display	プリンターに接続されているカスタマーディスプレイを制御します。		✓
apply-starconfiguration	プリンターにStar Configuration Formatを適用し、プリンター設定を変更します。		✓

request-post

概要

プリンターに サーバーポーリング (POST) を実行させるためのメッセージです。

このメッセージを受信したプリンターは サーバーポーリング (POST) を実行します。

この サーバーポーリング (POST) をきっかけに、 CloudPRNT Version HTTP の印刷動作を開始できます。

トピック

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

ペイロード例

{
    "title" : "request-post"
}

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"request-post"固定。

request-client-status

プリンターに client-status メッセージを発行させるためのメッセージです。

通常、プリンター側で状態変化があった場合のみプリンターからステータス通知メッセージが発行されます。

サーバーがすぐにプリンターの状態を知りたいときはこのメッセージを発行することで、即座にプリンターの状態を取得できます。

プリンターから定期的に client-status を発行させたい場合、サーバー設定情報取得リクエスト (GET) レスポンス (GET) の pollingTimeSec キーを参照してください。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"request-client-status"固定。

request-get-server-info

プリンターに サーバー設定情報取得リクエスト (GET) を任意のタイミングで実行させるためのメッセージです。

このメッセージを受信したプリンターは サーバー設定情報取得リクエスト (GET) を実行します。

取得した設定が、前回取得した設定から変更されていれば、新しい設定でCloudPRNT動作を開始します。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"request-get-server-info"固定。

print-job

プリンターに印刷を実行させるためのメッセージです。

このメッセージを受信したプリンターは、ペイロードに従い印刷動作を開始します。

その後、 print-result メッセージを発行します。

注釈

本メッセージをプリンターに送信する前に、プリンターが現在印刷中でないことを確認してください。具体的な方法は以下の通りです。

直前の print-job メッセージによる印刷命令に対し、プリンターから print-result メッセージを受信した。

プリンターから発行された client-status メッセージの printingInProgress キーの値が false である。

トピック

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

ペイロード例

以下の例では、プリンターはペイロードの printData で指定されたURLに対し 印刷ジョブリクエスト (GET) を実行し、そのレスポンスで得られたデータを印刷します。

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

以下の例では、プリンターはペイロードの printData で指定されたテキストデータを印刷します。

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"print-job"固定。
jobToken	string	true	各印刷ジョブに割り当てる固有のトークン。
jobType	string	true	raw : printDataキーの値を印刷する。 url : printDataキーの値で指定されたURLから印刷データを 印刷ジョブリクエスト (GET) で取得して印刷する。
mediaTypes	[string]	true	printDataで指定する印刷データの種類を指定する。 印刷ジョブメディアタイプ jobTypeがrawのとき、文字列配列には一つの値だけ指定する。
printData	string	true	印刷データを指定する。
printerControl	object	false	プリンターのカット動作等を指定する値をまとめたオブジェクト。 jobTypeがrawで、printDataに制御コマンドを含めることができない場合に利用。

printerControlオブジェクト詳細

Key	Type	Required	Decsription
buzzer	object	false	ブザー制御に関連する値をまとめたオブジェクト
buzzer.startPattern	number	false	ジョブを印刷する前に、ブザーを指定回数分鳴らします。 指定可能範囲: 1 ~ 3 (MCS10では回数指定は機能しませんので、1回を指定してください)
buzzer.endPattern	number	false	ジョブを印刷したあとに、ブザーを指定回数分鳴らします。 指定可能範囲: 1 ~ 3 (MCS10では回数指定は機能しませんので、1回を指定してください)
cutter	object	false	カッター制御に関連する値をまとめたオブジェクト
cutter.type	string	false	ジョブを印刷したあとのカット動作を指定します。 full : フルカット partial : パーシャルカット none : カットしない
cutter.feed	boolean	false	ジョブを印刷したあとのカット動作の用紙フィードを指定します。 true : 用紙フィードする false : 用紙フィードしない
imageDitherPattern	string	false	画像イメージを印刷する場合のディザリング適用の有無を指定します。 fs : Floyd Steinberg 誤差拡散適用（デフォルト） none : 適用なし
cashDrawer	string	false	ジョブの印刷の前後におけるキャッシュドロアーオープンの設定をします。 none : ドロアーを利用しない start : 印刷前に実行 end : 印刷後に実行
holdPrintSensor	object	false	用紙保持センサーに関する値をまとめたオブジェクト
holdPrintSensor.paperPresentStatusControl	string	false	ジョブ印刷時に、排出口の用紙有無のステータス通知をクライアントに送信するかしないかの設定をするためのフラグを指定します。 このオプションを指定した場合、Client ActionのPaperPresentStatusControlの値は一度無視されます。 default : 次の印刷ジョブを送信した後、クライアントの現在設定値に従って用紙保持制御ステータスが通知されます(または通知されません)。 valid : 次の印刷ジョブを送信した後、プリンターASBステータスの7番目の値にて用紙保持制御ステータスが通知されます。 invalid : 次の印刷ジョブを送信した後、用紙保持制御ステータスは通知されません。
holdPrintSensor.holdPrintControl	string	false	ジョブ印刷時に、デバイスによる用紙保持制御の有効無効を設定をするためのフラグを指定します。 このオプションを指定した場合、Client ActionのHoldPrintControlの値は一度無視されます。 default : 次の印刷ジョブを送信した後、クライアントの現在設定値に従って用紙保持制御が有効になります(または無効になります)。 valid : 次の印刷ジョブを送信した後、デバイスによる用紙保持制御を有効にします。 invalid : 次の印刷ジョブを送信した後、デバイスによる用紙保持制御を無効にします。 このオプションの指定は、invalidを推奨します。

ペイロードに関する補足情報

• jobToken

  プリンターは直近10件のjobTokenを記憶します。同じjobTokenのprint-jobメッセージを受信した場合、印刷処理を行いません。

  重複したjobTokenを受け取った場合、print-result メッセージのstatusCodeキーでjobTokenの重複を通知します。

• jobType

  rawを指定した場合、mediaTypesキーには複数の値を指定しないでください。

  urlを指定した場合も、プリンターの印刷完了後には print-result メッセージが発行されます。印刷ジョブ完了確認 (DELETE) ではありません。

• printData

  jobTypeがrawの場合、印刷データそのものを格納します。mediaTypeがtext/plainではない場合は、Base64フォーマットで格納してください。

  jobTypeがurlの場合、印刷データのURLを格納します。

• printerControl

  印刷ジョブリクエスト (GET) のレスポンスヘッダーに相当します。

  jobTypeがrawで、printDataに制御コマンドを含めることができない場合に利用します。

order-client-action

プリンターに Client Action を実行させるためのメッセージです。

プリンターは本メッセージを受け取ると client-status メッセージを発行します。

そのペイロード中にClient Actionの応答が含まれます。

トピック

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

ペイロード例

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

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"order-client-action"固定。
clientAction	[object]	true	Client Actionオブジェクト
[clientAction].request	string	true	Client Actionリクエスト
[clientAction].options	string	true	Client Actionパラメータ

claim-barcode-reader

プリンターに接続されたバーコードリーダーの読み取ったデータを要求するためのメッセージです。

クレーム要求を受信したプリンターは、バーコードリーダーでデータを読み取ると、client-status メッセージを発行します。

client-status のペイロードに、読み取ったデータが格納されます。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"claim-barcode-reader"固定。
claimBarcodeReader	[object]	true	バーコードリーダー制御オブジェクト
[claimBarcodeReader].name	string	true	制御したいバーコードリーダーデバイス名を指定
[claimBarcodeReader].claim	boolean	true	true : バーコードリーダー制御開始 false : バーコードリーダー制御終了

output-to-display

プリンターに接続されているカスタマーディスプレイを制御するためのメッセージです。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"output-to-display"固定。
display	[object]	true	カスタマーディスプレイ制御オブジェクト
[display].name	string	true	制御したいカスタマーディスプレイデバイス名を指定
[display].claim	string	true	カスタマーディスプレイに表示させる内容。 カスタマーディスプレイ を参照してください。

apply-starconfiguration

プリンターにStar Configuration Formatを適用するためのメッセージです。

本メッセージを受信したプリンターは、ペイロードに従いStar Configuration Formatを適用します。

その後、starconfiguration-result メッセージを発行します。

トピック

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

ペイロード例

以下の例では、プリンターはペイロードの starconfiguration で指定されたStar Configuration Formatデータを適用します。

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

以下の例では、プリンターはペイロードの starconfiguration で指定されたURLに対し 印刷ジョブリクエスト (GET) を実行し、そのレスポンスで得られたデータを適用します。

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"apply-starconfiguration"固定。
jobToken	string	true	各ジョブに割り当てる固有のトークン。
jobType	string	true	raw : starconfigurationキーの値を適用する。 url : starconfigurationキーの値で指定されたURLからデータを 印刷ジョブリクエスト (GET) で取得して適用する。
starconfiguration	string	true	StarConfiguration Formatデータを指定する。

ペイロードに関する補足情報

• jobToken

  プリンターは直近10件のjobTokenを記憶します。同じjobTokenのapply-starconfigurationメッセージを受信した場合、設定適用処理を行いません。

  重複したjobTokenを受け取った場合、starconfiguration-result メッセージのstatusCodeキーでjobTokenの重複を通知します。

• starconfiguration

  jobTypeがrawの場合、Base64フォーマットのStar Configuration Formatデータを格納します。

  jobTypeがurlの場合、Star Configuration FormatデータのURLを格納します。

Printer to Server

注釈

プリンターからCloudPRNTサーバーへのMQTTメッセージ発行は、CloudPRNT Version MQTT (Full MQTT / Pass URL)で利用している場合のみ発生します。

CloudPRNT Version MQTT (Trigger POST)では、プリンターからMQTTメッセージを発行することはありません。

トピック名(メソッド)一覧

プリンターがCloudPRNTサーバーに対して発行するメッセージの一覧。

Method Name	Description	Trigger POST	Full MQTT / Pass URL
client-status	プリンターのステータスを通知します。		✓
print-result	受信した print-job メッセージに対する印刷結果を通知します。		✓
starconfiguration-result	受信した apply-starconfiguration メッセージに対する結果を通知します。		✓
client-will	プリンターがMQTTブローカーから切断されたことを通知します。		✓

client-status

概要

プリンターのステータスをCloudPRNTサーバーに通知するためのメッセージです。

プリンターは以下の場面で、本メッセージを発行します。

• MQTTブローカーに接続したとき

• プリンターステータスが変化したとき

• バーコードリーダーのクレーム中、バーコードを読み取ったとき

• CloudPRNTサーバーから request-client-status メッセージを受け取ったとき

• CloudPRNTサーバーから order-client-action メッセージを受け取ったとき

トピック

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"client-status"固定。

他のキーと値の仕様は サーバーポーリング (POST) の JSONリクエスト に準じます。

print-result

概要

プリンターがCloudPRNTサーバーから print-job メッセージを受け取り印刷動作を行ったあと、印刷結果を通知するためのメッセージです。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"print-result"固定。
jobToken	string	true	CloudPRNTサーバーが発行した print-job メッセージにより割り当てられたjobToken
printSucceeded	boolean	true	true : 印刷に成功した。 false : 印刷に失敗した。
statusCode	string	true	プリンターステータスコード を参照
printerMAC	string	true	プリンターのEthernetMACアドレス
uniqueID	string	false	CloudPRNTサーバーが Client Action の SetID で割り当てたID

starconfiguration-result

概要

CloudPRNTサーバーから apply-starconfiguration メッセージを受け取り、StarConfigの設定動作を行ったあと、設定結果を通知するためのメッセージです。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"starconfiguration-result"固定。
jobToken	string	true	CloudPRNTサーバーが発行した apply-starconfiguration メッセージにより割り当てられたjobToken
statusCode	string	true	プリンターステータスコード を参照
printerMAC	string	true	プリンターのEthernetMACアドレス
uniqueID	string	false	CloudPRNTサーバーが Client Action の SetID で割り当てたID
firmware	string	false	ファームウェア更新処理をした場合の実行結果
skip	string	true	処理をスキップされた項目数
error	string	true	処理がエラーとなった項目数

client-will

概要

プリンターがMQTTブローカーにConnectする際に登録するWillメッセージです。

プリンターが意図せずネットワークから切断されたとき、ブローカーから配信されます。

プリンターモデルによっては、電源を落として正常終了したとき、ブローカーに登録したWillではなく、プリンターがその場で同じフォーマットのメッセージを発行します。

unintentionalDisconnection キーの値により、異常切断かどうか判断できます。

トピック

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

ペイロード例

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

ペイロード詳細

Key	Type	Required	Decsription
title	string	true	"client-will"固定。
printerMAC	string	true	プリンターのEthernetMACアドレス
uniqueID	string	false	CloudPRNTサーバーが Client Action の SetID で割り当てたID
unintentionalDisconnection	boolean	false	true : プリンターがネットワークから意図せず切断された。 false : プリンターをソフトスイッチで正しく電源OFFした。