CPUtil：開発サポートツール

CPUtilは、.NETベース(.NET framework, .NET Coreなど）ではないCloudPRNTサーバーの実装を支援する便利なバックエンドツールです。
またソースコードを公開しているため、サーバー開発者は必要に応じてCPUtilを自由に変更して、必要な機能を実装することができます。

CPUtilは .NET Core 3.1以降がサポートする以下のプラットフォームで構築および使用できます。

Windows x86 and x64
Linux x64
Linux Arm (Raspberry PI compatible)
Apple macOS (OSX) x64

こちらからダウンロードできるCPUtilは、 .NET Frameworkまたは.NET Coreのインストールを必要とせずに目的のプラットフォームで実行できる、自己完結型のパッケージです。

また、公開しているソースコードから、プラットフォームに依存しない一般的なフレームワーク依存パッケージを構築することもできます。
この場合はローカルにインストールされた .NET Core Runtime（3.1以降）が必要です。

CPUtilを構築すると、次のような外部プロセスを呼び出すことができる言語または環境を使用して、サーバー側プロジェクトと統合できます。

PHP
Python
Node.js
Lua
Perl

ASP.NETまたはASP.NET Coreに基づいてサーバーを構築している場合は、CPUtilを呼び出す代わりに.NET APIを直接使用してください。

CPUtil - ダウンロード

ビルド済みバイナリファイル

ビルド済みCPUtilバイナリファイルは、対応する各プラットフォームごとに提供されます。
環境に合わせてダウンロードを行ってください。

Note:
macOS x64 (10.15以降) 環境におけるインストールは、zipを解凍してpkgインストーラーをご利用ください。

ソースからのビルド

CPUtilは、CloudPRNTSDKSamplesソリューションのプロジェクトとして提供される、 .NET Core 3.1 (V1.1.1以前) / .NET 6.0(V1.1.2以降) のコンソールアプリケーションです。自由にカスタマイズを行い、必要に応じてソースからビルドできます。
ビルド環境：.NET Core 3.1以降のSDKが利用可能なプラットフォーム

ソースリポジトリ : https://github.com/star-micronics/cloudprnt-sdk/tree/master/CloudPRNTSDKSamples

ビルドコマンド例：（Ubuntu環境の例）

CloudPRNTSDKSamplesプロジェクトをダウンロードする
ターミナルを開き、下記コマンドを実行する（--version、-rの内容は適宜変更してください）


cd [Your Environment Path]/CloudPRNTSDKSamples/cputil
 dotnet add package StarMicronics.CloudPRNT-Utility --version 1.1.2
 dotnet publish -o package/cputil-linux-x64 -c Release -r linux-x64

上記を実行すると、package/cputil-linux-x64フォルダにビルド済みcputilバイナリが格納されます。

CPUtil - インストレーション

各プラットフォームに特別なインストールは必要ありません。
提供されたパッケージを展開すると、cputilバイナリをすぐに実行できます。インストール場所と方法は、サーバー管理者が選択します。

システム全体のインストールが必要な場合、推奨される方法は次のとおりです。

要求するOSとアーキテクチャのパッケージをシステム全体の場所に展開します。Linuxでは例えば、/opt/star/cputilになります。
展開されたフォルダーをPATH変数に追加してcputilがスクリプトからアクセスできるようにするか、シンボリックリンクをcputilバイナリのPATHアクセス可能なフォルダー（/usr/local/bin）に配置します。

Note:
macOS x64 (10.15以降) 環境におけるインストールは、弊社が提供するpkgインストーラーをご利用ください。/　zipを解凍してpkgインストーラーをご利用ください。
なお、pkgインストーラーでインストールを行った場合には自動でPATHが作成されるため、環境変数等に追加する必要はありません。

CPUtil - 使用方法

Star ASB ステータスデコード

Star CloudPRNTクライアントデバイスはPOSTリクエストを通じて、ステータスをStar ASB形式（7つ以上の16進数値の文字列）でサーバーへ通知します。
例：


"23 86 00 00 00 00 00 00 00 00 00"

これは全ての言語で簡単にデコードできるわけではないため、CPUtilはこれをJSON形式のデータに変換する機能を提供します。
例：


cputil jsonstatus "23 86 00 00 00 00 00 00 00 00 00"

上記の例では以下の出力を生成します。


{
  "Online": true,
  "CoverOpen": false,
  "CompulsionSwitch": false,
  "OverTemperature": false,
  "Recoverable": true,
  "CutterError": false,
  "MechanicalError": false,
  "ReceiveBufferOverflow": false,
  "BlackMarkError": false,
  "PresenterPaperJam": false,
  "VoltageError": false,
  "PaperEmpty": false,
  "PaperLow": false
}

印刷ジョブのメディア形式の処理

CPUtilはCloudPRNT印刷プロセスのジョブ生成部分をサポートします。
サーバーは単一の入力形式で印刷ジョブを準備できますが、CloudPRNTクライアントデバイスでネイティブにサポートされていない場合があります。そのような場合に、サーバーはCPUtilを使用して必要に応じてCloudPRNTクライアントがサポートする形式に印刷ジョブを変換することができます。

サポートされている入力用の印刷ジョブのメディア形式は以下の通りです。

画像

PNG - image/png
JPEG - image/jpeg
BMP - image/bmp
GIF - image/gif

プレーンテキスト - text/plain
Starドキュメントマークアップ - text/vnd.star.markup

CPUtilでサポートされている入力データ形式のJSON形式のリストは、supportedinputsオプションを使用してCPUtilから直接取得することもできます。


cputil supportedinputs

以下の出力を生成します。


[
  "text/plain",
  "text/vnd.star.markup",
  "image/png",
  "image/jpeg",
  "image/bmp",
  "image/gif"
]

送信可能な印刷ジョブの出力形式を設定する

各入力ドキュメントは様々な出力形式に変換できます。出力できる形式は入力タイプによって異なります。
各入力形式は、Star CloudPRNTクライアントデバイスでサポートされている1つ以上の出力形式に変換できます。これにより、CPUtilを使用すればStar CloudPRNTサーバーから任意のターゲットデバイスに印刷可能であることが保証されます。

CloudPRNT互換サーバーに特定のクライアント（例えば mC-Print2、mC-Print3）向けの印刷ジョブが用意されている場合、以下を行う必要があります。

クライアントからのポーリングリクエスト（HTTP POSTによって送信されたJSON形式のデータを持つリクエスト）を待つ
次のフィールドを使用して、適切なJSONレスポンスにてクライアントに返信する

jobReady 印刷ジョブの準備があること(true)を設定
mediaTypes クライアントに提供可能な印刷ジョブのメディアタイプ名の配列を設定

例：


{
  "jobReady": true,
  "mediaTypes": ["image/jpeg", "image/png"]
}

印刷ジョブネゴシエーションのこの時点で、CPUtilを使用してサーバーが使用する予定の入力形式に基づいた出力形式のmediaTypesリストを準備できます。

例えば、PNG画像を印刷ジョブの入力ソースとして使用するサーバーの場合は以下になります。※sourceimage.pngは入力ファイルの名前です


cputil mediatypes sourceimage.png

以下のJSONデータレディの出力を生成します。


["application/vnd.star.raster","application/vnd.star.line","application/vnd.star.starprnt","application/vnd.star.starprntcore","image/png","image/jpeg"]

また、サーバーがまだ印刷ジョブデータを準備していない場合や、ローカルファイルとして保存していない場合は、入力ファイル名の代わりにmediatypes-mimeオプションを使用して、入力形式に基づいて可能な出力のリストを生成することができます。


cputil mediatypes-mime image/png

以下のJSONデータレディの出力を生成します。


["application/vnd.star.raster","application/vnd.star.line","application/vnd.star.starprnt","application/vnd.star.starprntcore", "image/png","image/jpeg"]

印刷ジョブを変換する

サーバーが、jobReadyフィールドをtrueに設定したCloudPRNTポーリングへのJSON形式のレスポンスと、有効なmediaTypesリストを提供すると、クライアントデバイスは印刷するジョブがあることを認識して、次の手順を実行します。

メディアタイプリストで利用可能なものから優先順位の高いmediaTypeを選択します。
通常はクライアントデバイスがサポートしているリストの最初の形式が選択されますが、正確な決定はクライアントデバイスに依存します。
CloudPRNTサーバーに対してHTTP GETリクエストを実行してジョブを取得し、クエリ文字列パラメーターで選択したmediaTypeを指定します。

サーバーがHTTP GETリクエストを受信したとき、要求されたメディアタイプでエンコードされた印刷ジョブを返す必要があります。
サーバーは内部的に一つの形式でジョブを準備し、CPUtilを使用して要求された形式に変換できます。

出力する印刷ジョブの変換を指定するには、次のオプションを使用します。


decode <format> <filename> <output>

<filename>のファイルを、メディアタイプの文字列で指定された<format>形式のデータに変換します。変換されたデータは<output>で指定されたファイルに出力されます。

<format>で指定可能な出力印刷ジョブのメディアタイプは以下になります。

application/vnd.star.starprnt

例えば、サーバーが印刷ジョブをPNGデータとして準備し、クライアントデバイスがそれをStarPRNTプリンターコマンドデータ（application/vnd.star.starprnt）として要求した場合、CPUtilを使用してPNGデータからStarPRNTコマンドデータへ変換できます。


cputil decode application/vnd.star.starprnt sourceimage.png outputdata.bin

上記の例では、入力したPNGファイル”sourceimage.png"をStarPRNTコマンドデータに変換して "outputdata.bin"へ保存します。
出力データを標準出力に書き込む方が便利な場合は、出力ファイル名として"-"または"[stdout]"を使用します。

また、サーバーが印刷ジョブをStarドキュメントマークアップ形式のテキストファイル(拡張子：".stm")として準備し、クライアントデバイスがそれをStarPRNTプリンターコマンドデータ（application/vnd.star.starprnt）として要求した場合、 CPUtilを使用してStarドキュメントマークアップデータからStarPRNTコマンドデータへ変換できます。


cputil decode application/vnd.star.starprnt starmarkup.stm outputdata.bin

上記の例では、入力したStarドキュメントマークアップ形式のテキストファイル"starmarkup.stm"をStarPRNTコマンドデータに変換して "outputdata.bin"へ保存します。

変換オプション

変換オプションには、画像の拡大縮小、トリミング、およびディザリング処理が含まれます。

スケーリングとトリミングを機能させるにはCPUtilにプリンターの印刷幅を通知する必要があります。
CloudPRNTサーバーは、CloudPRNT "clientAction"の"PageInfo"リクエストを介して印刷幅情報を取得できます。

変換オプションは、decodeオプションの前にコマンドラインで指定する必要があります。

印刷幅

印刷領域のサイズを指定するには、次のオプションのいずれかを使用します。

`thermal2`/`thermal58`	mC-Print2などの2インチ/58mmプリンターの印刷領域(384 dots)を設定します。
`thermal3`/`thermal80`	mC-Print3などの3インチ/80mmプリンターの印刷領域(576 dots)を設定します。
`printarea <dot length>`	`<dot length>`で指定されるプリンターの任意の印刷領域を設定します。 (例: `printarea 576`)

イメージディザリング

ディザリングを指定するには、ditherオプションを使用します。

画像を印刷領域に合わせて拡大縮小するように指定するには、scale-to-fitオプションを使用します。
指定しない場合画像は拡大縮小されず、印刷領域よりも画像サイズが大きい場合はトリミングされます。

指定例：

PNGソースから2インチプリンター用のStarPRNTコマンドとして印刷データを準備し、ディザリング処理とページに合わせて画像を拡大縮小する設定をする場合は以下のように指定します。


cputil thermal2 dither scale-to-fit decode application/vnd.star.starprnt sourceimage.png outputdata.bin

キャッシュドロワー・ブザーの制御

デバイスコマンドを含めることができる出力形式に変換する場合(例： application/vnd.star.starprnt)、プリンターに接続されたキャッシュドロワー(またはブザー)を制御するために、次のオプションで制御コマンドを含めるようにCPUtilにて指定することができます。

`drawer-start`	印刷ジョブの開始時にキャッシュドロワーを開きます。
`drawer-end`	印刷ジョブの終了時にキャッシュドロワーを開きます。
`drawer-none`	キャシュドロワーの操作はしません。 (初期設定)

`buzzer-start X` (Xは数字)	印刷ジョブの開始時に指定した回数ブザーを鳴らします。
`buzzer-end X` (Xは数字)	印刷ジョブの終了時に指定した回数ブザーを鳴らします。

指定例：

PNGソースから2インチプリンター用のStarPRNTコマンドとして印刷データを準備し、印刷終了時にキャッシュドロワーを開く設定をする場合は以下のように指定します。


cputil thermal2 scale-to-fit drawer-end decode application/vnd.star.starprnt sourceimage.png outputdata.bin

Starドキュメントマークアップ形式のテキストファイルから3インチプリンター用のStarPRNTコマンドとして印刷データを準備し、印刷ジョブ終了時にブザーを1回鳴らす設定をする場合は以下のように指定します。


cputil thermal3 buzzer-end 1 decode application/vnd.star.starprnt starmarkup.stm outputdata.bin

Note:

MCS10では回数指定は機能しません。buzzer-start 1またはbuzzer-end 1を指定してください。
特定の出力データ形式(text/plain、image/png、image/jpegなど)は、デバイスコマンドをサポートしていません。このような場合、CloudPRNTプロトコルを使用してhttp印刷ジョブの応答ヘッダー(GETレスポンスヘッダー)を利用してキャッシュドロワーまたはブザーを制御するように指定してください。

用紙保持制御を利用する

この機能はmC-Label3とTSP100IV SKで利用できます。
上記プリンターには、印刷実行後に用紙が排出口に残っているかどうかを検知する用紙保持制御機能があります。

以下のオプションは、用紙保持ステータスを通知するかどうか / ハードウェアによる用紙保持制御を利用するかどうかを指定できます。
現在の印刷ジョブを送信したあとの、次回の印刷ジョブから適用されます。

`presentstatus-default`	用紙保持ステータスの通知は、プリンター本体設定に従います。
`presentstatus-valid`	用紙保持ステータスの通知を有効にします。
`presentstatus-invalid`	用紙保持ステータスの通知を無効にします。

`holdprint-default`	ハードウェアによる用紙保持制御の利用については、プリンター本体設定に従います。
`holdprint-valid`	ハードウェアによる用紙保持制御を有効にします。
`holdprint-invalid`	ハードウェアによる用紙保持制御を無効にします。

指定例：

PNGソースから2インチプリンター用のStarPRNTコマンドとして印刷データを準備し、用紙保持ステータスの通知を有効にし、ハードウェアによる用紙保持制御を無効にする場合は、以下のように指定します。


cputil thermal2 scale-to-fit presentstatus-valid holdprint-invalid decode application/vnd.star.starprnt sourceimage.png outputdata.bin

Note:

CloudPRNTにおいてはholdprint-invalidを指定してハードウェアによる用紙保持制御を無効にすることを推奨します。プリンターは用紙保持ステータス (presentstatus-xxx) により、用紙保持制御を行います。
特定の出力データ形式(text/plain、image/png、image/jpegなど)は、デバイスコマンドをサポートしていません。このような場合、CloudPRNTプロトコルを使用してhttp印刷ジョブの応答ヘッダー(GETレスポンスヘッダー)を利用して用紙保持機能を制御するように指定してください。

入力ソースがテキストまたは画像の場合のカットタイプ指定

デバイスコマンドを含めることができる出力形式に変換する場合(例： application/vnd.star.starprnt)、入力ソースがテキストや画像の場合にカットタイプを指定するために、次のオプションで制御コマンドを含めるようにCPUtilにて指定することができます。

`fullcut`	印刷ジョブの終了時にフルカットを実行します。 (初期設定)
`partialcut`	印刷ジョブの終了時にパーシャルカットを実行します。

対象メディアタイプ(入力ソース):

text/plain
image/png
image/jpeg
image/bmp
image/gif

指定例：

PNGソースから3インチプリンター用のStarPRNTコマンドとして印刷データを準備し、印刷終了時にパーシャルカットの実行設定をする場合は以下のように指定します。


cputil thermal3 partialcut decode application/vnd.star.starprnt sourceimage.png outputdata.bin

Note:
入力ソースのメディアタイプがapplication/vnd.star.markupの場合、本設定は無視されます。

CPUtil - サーバーへのインテーグレーション

CPUtilは、サーバー側のWeb開発技術との統合を可能な限り簡単にすることを目的としています。これを可能にするには下記の要件を満たす必要があります。

サーバー側のスクリプト言語において、外部プロセスを呼び出してその出力を取得できる必要があります。
Webホストでは、サーバー側のスクリプトからネイティブバイナリを実行できる必要があります。
ホストサーバー環境は、.NET Coreでサポートされているタイプでなければなりません。
現時点では、Windows（32ビット/64ビット）、Linux（64ビット/Arm-Raspberry Piを含む）、Mac OS 64ビットが含まれます。

CPUtilの呼び出し

PHP

PHPは、外部プロセスをトリガーしてコマンドで出力を読み取る方法、またはHTTP応答に直接出力を含める方法がいくつかあります。
system()、passthru()、exec()関数を参照してください。ほとんどの場合、passthru()を使用して、CPUtil出力を直接応答に挿入できます。

例えば、cputil mediatypes-mime text/vnd.star.markupを呼び出すと、Starドキュメントマークアップから生成可能な印刷ジョブのタイプリストがJSONデータで出力されます。これはCloudPRNT POSTレスポンスのmediaTypesフィールドの値として利用できます。

Node.js

Node.js環境では、ネイティブのchild_processモジュールを使用して、CPUtilを外部プロセスとして呼び出すことができます。
便宜上、child_processモジュールは同期および非同期のいくつかの代替手段を提供します。詳しくは、child_process.exec()、child_process.execSync()、child_process.execFile()、child_process.execFileSync()関数を参照してください。

シェルスクリプトの自動化のような特定のユースケースでは、同期対応がより便利な場合があります。ただし、生成されたプロセスの完了中にイベントループが停止するため、同期メソッドはパフォーマンスに影響を与える可能性があることに注意してください。

例えば、CPUtilを子プロセスとして起動しASBステータスをJSONに変換するには下記のようになります。


const child_process = require('child_process');

 var jsonStatus = child_process.execFileSync('cputil', ['jsonstatus', req.body.status]);
 console.log(JSON.parse(jsonStatus));

サーバーでCPUtilを使用する場合

CPUtilは、サーバー開発のCloudPRNT固有の要件を支援することを目的としています。そのため、CloudPRNTのPOSTリクエストやGETリクエストを処理するとき等に利用されることを想定しています。
CPUtilの主な機能は印刷ジョブをある形式から別の形式に変換することです。すべてのCloudPRNTクライアントデバイスが同じ印刷データ形式の出力コマンドをサポートするわけではないため、CloudPRNTサーバーの印刷ジョブ生成時にこの機能が役立ちます。

また、サーバーとクライアントデバイスの両方がサポートするジョブデータ形式をネゴシエートできるメカニズムを提供します。サーバー側のコードに作業と複雑さを追加する（特に、複数の方法で印刷ジョブを変換またはレンダリングする必要がある）のを避けるため、 CPUtilはネゴシエーションを支援し必要に応じて印刷ジョブを自動的に変換します。

POSTリクエスト (CloudPRNTポーリング)

CloudPRNTクライアントデバイスは、サーバー上の指定されたURLにHTTP POSTリクエストを発行します。
このPOSTリクエストはサーバーに現在のクライアントデバイスの状態を通知し、かつサーバーが当該リクエストに対するレスポンスができるようにするために使用されます。

クライアントデバイスからのPOSTリクエストは、指定された定期的な間隔でプリンターのステータス更新を行うためか、バーコードスキャンなどクライアントデバイス側でイベントが発生した場合に実行されます。

一方、サーバーからのPOSTレスポンスでは、クライアントデバイスに向けて印刷できるジョブがあることを通知したり、カスタマーディスプレイ表示の更新をしたり、クライアントデバイスに関する追加情報（用紙サイズ/印刷領域など）をリクエストしたり、クライアントデバイスのユニークIDを設定したり、といったリクエストを行うことができます。

開発者はPOSTリクエスト/レスポンスの中でCPUtilを使用することで、以下の2つの範囲をサポートされます。

ステータスデコード
POSTリクエストには、シンプルなデバイスステータスコードとより詳細なStar ASB形式のステータス情報の両方が含まれます。
多くの場合ステータスコードを使用するだけで十分ですが、サーバーが詳細を知る必要がある場合は、ASBステータス文字列に含まれる16進データからビットマスク情報をデコードする必要があります。これをサーバー側の実装で行うのは不便なため、CPUtilを使用してStar ASB文字列をフォーマット定義済みJSONデータに変換します。
詳細については、Star ASBステータスデコードセクションを参照してください。
印刷ジョブ形式の管理
印刷ジョブの通知をする場合に、CPUtilを使用してJSON形式のレスポンス中のmediaTypesフィールドの正しい値を生成できます。

印刷ジョブ形式の管理

CPUtilを使用する場合、サーバーはクライアントデバイスがサポートできるメディア形式を気にすることなく、任意のメディア形式を使用して印刷ジョブを準備できます。
入力ソースとして、PNG、JPEG、BMP、GIF、ASCII/UTF-8テキスト、Starドキュメントマークアップを使用できます。

サーバーがPOSTリクエストを受信し、ジョブを印刷する必要がある場合フィールドjobReadyがtrueに設定されmediaTypesにクライアントに提供できるメディア形式を記述した文字列リストが設定された、 JSON形式のレスポンスボディを提供する必要があります。

CPUtilを利用して適切なメディア形式リストのレスポンスを生成するコマンド(cputil mediatypes-mime text/vnd.star.markup)の利用例は次のようになります。
※cgiを介して呼び出されるbashシェルスクリプトの例


#!/bin/bash
# Make a CloudPRNT post response to print a Star Markup job with cputil

OUTPUT_TYPES=`cputil mediatypes-mime text/vnd.star.markup`

echo "{"
echo "  \"jobReady\": true,"
echo "  \"mediaTypes\": $OUTPUT_TYPES"
echo "}"

上記は、以下のJSONデータをレスポンスとして出力します。


{
  "jobReady": true,
  "mediaTypes": ["text/vnd.star.markup","application/vnd.star.line","application/vnd.star.starprnt","application/vnd.star.starprntcore"]
}

GETリクエスト (印刷ジョブの取得)

CloudPRNTクライアントデバイスは印刷ジョブがあることを通知されたときに、サーバーにHTTP GETリクエストを実行します。このときデバイスはmediaTypesリストから互換性のあるデータ形式を選択します。これは、GETリクエストでのクエリ文字列パラメーターに設定されます。

サーバーはGETハンドラでCPUtilを使用して、サーバー内で入力ソースのメディア形式からCloudPRNTクライアントデバイスがリクエストする形式に印刷ジョブを変換できます。

次のbashスクリプト例はGETリクエストを処理するCGIスクリプトとして呼び出された場合に、ローカルで保存されているStarドキュメントマークアップファイルを、プリンターがリクエストしているメディア形式に変換しています。


#!/bin/bash

urldecode() {
    local data=${1//+/ }
    printf '%b' "${data//%/\x}"
}

# parse query string
declare -A param
while IFS='=' read -r -d '&' key value; do
    param["$key"]=$value
done <<<"${QUERY_STRING:+"${QUERY_STRING}&"}"

# get the output format requested by the cloudprnt device
OUTPUT_FORMAT=`urldecode "${param["type"]}"`

# get the unique ID of the CloudPRNT device which requested the print job
CP_MAC=`urldecode "${param["mac"]}"`

# Assume that print jobs are stored in a local file and named according the the device MAC address ID
INPUT_FILE="printjob-$CP_MAC.stm"

# use cputil to convert the input file and write directly to standard output
cputil decode "$OUTPUT_FORMAT" "$INPUT_FILE" -