CPUtil: Developer support tool

CPUtil is a useful back-end tool to help with implementing CloudPRNT servers that are not .NET framework or .NET Core-based.
Since its source code is published, server developers can implement necessary functions by freely modifying CPUtil as necessary.

CPUtil can be built and used on the following platforms supported by .NET Core 3.1 or later:

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

CPUtil allows you to build a self-contained package that can be run on the desired platform without the need for .NET Framework or .NET Core installation.
It is also possible to build a general framework-dependent package that is fully platform-neutral, but it requires a locally installed .NET Core Runtime (3.1 or later).

Once built, CPUtil can be integrated with projects on the server using a language or environment that invokes the following external processes:

PHP
Python
Node.js
Lua
Perl

If you are building a server based on ASP.NET or ASP.NET Core, use the .NET API directly instead of invoking CPUtil.

CPUtil - Download

Pre-built Binaries

Pre-built CPUtil binaries are provided for each platform.
Download them according to your operating environment.

Note:
For macOS x64 (10.15 or later), decompress the zip file and use the pkg installer.

Building from the Source

CPUtil is a .NET Core 3.1 (V1.1.1 or earlier) / .NET 6.0 (V1.1.2 or later) console application provided as a CloudPRNTSDKSamples solution project. You can freely customize and build it from the source as necessary.
Building environment: A platform where the SDK of .NET Core 3.1 or later can be used

Source repository: https://github.com/star-micronics/cloudprnt-sdk/tree/master/CloudPRNTSDKSamples

Example of a build command: (Ubuntu)

Download the CloudPRNTSDKSamples project.
Open the terminal and execute the following command (modify the parts "--version and -r" as necessary):

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

After the execution, the pre-built CPUtil binaries are stored in the package/cputil-linux-x64 folder.

CPUtil - Installation

There is no special installation specific to each platform.
When you extract the supplied package, the CPUtil binaries become ready to be executed. The installation location and method can be selected by the server administrator.

If system-wide installation is required, the recommended method is as follows:

Extract the package of your required OS and architecture to a system-wide location. For Linux, it would be /opt/star/cputil.
Add the extracted folder to the PATH variable to make CPUtil accessible through scripting, or place a symbolic link in a CPUtil binary PATH accessible folder (/usr/local/bin).

Note:
For macOS x64 (10.15 or later), install CPUtil by using the pkg installer provided by Star Micronics.　Decompress the zip file and use the pkg installer.
If CPUtil is installed using the pkg installer, PATH is automatically created, eliminating the need to add it to the environmental variable.

CPUtil - How to Use

Decoding the Star ASB Status

The Star CloudPRNT client device notifies the server of the status in Star ASB format (a string of seven or more hexadecimal values) through a POST request.
Example:

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

Since this is not easily decoded in all languages, CPUtil provides a function to convert it into JSON format data.
Example:

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

The above example generates the following output:

{
  "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
}

Handling Print Job Media Types

CPUtil helps with the job creation part of the CloudPRNT printing process.
The server prepares a print job in a single input format, which may not be natively supported by the CloudPRNT client device. In such cases, the server uses CPUtil to convert the print job into a format supported by the CloudPRNT client as necessary.

The supported input print job media types are as follows:

Images

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

Plain text - text/plain
Star Document Markup - text/vnd.star.markup

A list of JSON input data formats supported by CPUtil can be retrieved directly from CPUtil using the supportedinputs option.

cputil supportedinputs

The above command generates the following output:

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

Setting transmittable print job output formats

Each input document is convertible into various output formats. The output formats vary depending on the input type.
Each input format can be converted into one or more output formats supported by the Star CloudPRNT client device. This ensures that CPUtil allows the Star CloudPRNT server to print to any target device.

If a CloudPRNT-compatible server has a print job specific to a client (example: Star mC-Print2 or mC-Print3), the following must be performed:

Wait for a poll request from the client (a request with JSON-format data sent through HTTP POST).
Reply to the client in an appropriate JSON response using the following fields:

jobReady Set print job ready (true).
mediaTypes Set an array of print job media type names that can be provided to the client.

Example:

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

At this point of print job negotiation, CPUtil can be used to prepare an output format mediaTypes list based on the input format to be used by the server.

In the case of a server that uses a PNG image as the input source of a print job, the command is as follows: * sourceimage.png is the name of the input file.

cputil mediatypes sourceimage.png

The above command generates the following JSON data-ready output:

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

If the server has not yet prepared print job data or does not store it as a local file, the mediatypes-mime option is used, instead of the input file name, to generate a list of possible output types based on the input type.

cputil mediatypes-mime image/png

The above command generates the following JSON data-ready output:

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

Converting a print job

When the server sends a JSON response to the CloudPRNT poll with the jobReady field set to true and provides a valid mediaTypes list, the client device will recognize that there is a print job and perform the following steps:

Select the preferred mediaType from the types available in the mediaType list.
Normally, the first format supported by the client device on the list is selected, but exact judgment depends on the client device.
Send an HTTP GET request to the CloudPRNT server to retrieve the job and specify mediaType selected in the query string parameter.

When the server receives the HTTP GET request, it needs to return a print job encoded in the requested media type.
The server prepares the job internally in a single format and converts it into the requested format using CPUtil.

To specify the conversion of an output print job, use the following option:

decode <format><filename><output>

Convert the <filename> file into the <format> format data specified in the media type string. The converted data is output to the file specified in <output>.

The output print job media type that can be specified in <format> is as follows:

application/vnd.star.line
application/vnd.star.starprnt
application/vnd.star.starprntcore
application/vnd.star.raster (Can be specified only if the input source is an image)
application/vnd.star.linematrix (Cannot be specified if the input source is an image)

For example, if the server prepares a print job as PNG data and the client device requests it as StarPRNT printer command data (application/vnd.star.starprnt), you can convert PNG data into StarPRNT printer command data using CPUtil.

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

The above is an example of converting the input PNG file "sourceimage.png" into StarPRNT command data and saving it to "outputdata.bin."
If it is more convenient to write the output data to standard output, use "-" or "[stdout]" as the output file name.

Also, if the server prepares a print job as a Star Document Markup format text file (extension: ".stm") and the client device requests it as StarPRNT printer command data (application/vnd.star.starprnt), you can convert Star Document Markup data into StarPRNT printer command data using CPUtil.

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

The above is an example of converting the input Star Document Markup format text file "starmarkup.stm" into StarPRNT command data and saving it to "outputdata.bin."

Conversion options

Conversion options include image scaling, cropping, and dithering.

To make scaling and cropping work, you need to notify CPUtil of the printer print width.
The CloudPRNT server can retrieve the print width information through a CloudPRNT clientAction "PageInfo" request.

A conversion option must be specified before the decode option from the command line.

Print width

To specify the print area size, use one of the following options:

`thermal2`/`thermal58`	Set the print area (384 dots) of a 2inch/58mm printer, such as mC-Print2.
`thermal3`/`thermal80`	Set the print area (576 dots) of a 3inch/80mm printer, such as mC-Print3 or Star TSP650II.
`thermal4`/`thermal112`	Set the print area (832 dots) of a 4inch/112mm printer, such as Star TSP800II.
`thermal82`/`thermal83`	Set the print area (640 dots) of a 82mm/83mm printer, such as Star TSP700II.
`matrix3`/`matrix76`	Set the print area (210 dots) of a dot-matrix 76mm printer, such as Star SP700.
`matrix69.5`	Set the print area (190 dots) of a dot-matrix 69.5mm printer, such as Star SP700.
`matrix57.5`	Set the print area (160 dots) of a dot-matrix 57.5mm printer, such as Star SP700.
`printarea <dot length>`	Specify any print area of the printer in `<dot length>`. (Example: `printarea 576`)

Image dithering

To specify dithering, use the dither option.

To make an image scalable to fit the print area, use the scale-to-fit option.
If no option is specified, the image is not scaled, and if the image is larger than the print area, it is cropped.

Example:

If you prepare print data as StarPRNT commands for a 2inch printer from a PNG source and set dithering and image scaling, use the following command:

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

Controlling the cash drawer and the buzzer

When converting to an output format that includes device commands (example: application/vnd.star.starprnt), you can set CPUtil with the following commands to include control commands to open the cash drawer (or sound the buzzer) connected to the printer:

`drawer-start`	Opens the cash drawer at the start of the print job.
`drawer-end`	Opens the cash drawer at the end of the print job.
`drawer-none`	Does not open the cash drawer. (Default)

`buzzer-start X` (X is a number)	Sounds the buzzer a specified number of times at the start of the print job.
`buzzer-end X` (X is a number)	Sounds the buzzer a specified number of times at the end of the print job.

Example:

To prepare print data as StarPRNT commands for a 2inch printer from a PNG source and open the cash drawer at the end of the print job, use the following command:

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

To prepare print data as StarPRNT commands for a 3inch printer from a Star Document Markup format text file and sound the buzzer once at the end of the print job, use the following command:

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

Note:

Number specification does not work on MCS10. Use buzzer-start 1 or buzzer-end 1.
Some output data formats (text/plain, image/png, image/jpeg, etc.) do not support device commands. In such cases, use the CloudPRNT protocol to control the cash drawer or buzzer through an http print job response header (GET response header).

Using the hold print control

This feature is available with mC-Label3, TSP100IV SK, TSP650IISK and IFBD-HI01X(Ver 1.9.0 or later).
The above printers have a hold print feature to check if paper remains at the paper exit.

You can use the following options to set whether to notify the hold print status and whether to use hardware-based hold print control.
The setting is applied to the next print job after the current print job is sent.

`presentstatus-default`	Complies with the printer setting about the hold print status notification.
`presentstatus-valid`	Enables the hold print status notification.
`presentstatus-invalid`	Disables the hold print status notification.

`holdprint-default`	Complies with the printer setting about whether to use the hardware-based hold print control.
`holdprint-valid`	Enables the hardware-based hold print status notification.
`holdprint-invalid`	Disables the hardware-based hold print status notification.

Example:

To prepare print data as StarPRNT commands for a 2inch printer from a PNG source, enable the hold print status notification, and disable the hardware-based hold print status notification, use the following command:

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

Note:

In CloudPRNT, it is recommended to specify holdprint-invalid to disable the hardware-based hold print status notification. The printer performs the hold print control based on the hold print status (presentstatus-xxx).
Some output data formats (text/plain, image/png, image/jpeg, etc.) do not support device commands. In such cases, use the CloudPRNT protocol to control the hold print feature through an http print job response header (GET response header).

Specify encoding type

This option is for non-UTF-8 support model (TSP700II/TSP800II/SP700).
The markup source files used by cputil are plain text files encoded in UTF-8. Therefore, some characters may be garbled on non-UTF-8 supported devices. In that case, it may be able to alleviate it by specifying the sbcs option.

`utf8`	Specify that the target device supports UTF-8 encoding (default).
`sbcs`	Specify that the target device supports only single byte codepages. If single byte characters are [0x20 - 0x7E] / cp932[0xA1 - 0xDF] or iso-8859-1[0xA1 - 0xFF](Exclude 0xAD), then it can be printed.

Example:

For example, to prepare print data as StarLine commands for a 3 inch printer from a markup source, with enabling utf8 option:

cputil thermal3 utf8 decode application/vnd.star.line starmarkup.stm outputdata.bin

For example, to prepare print data as StarLine commands for a 3 inch printer from a markup source, with enabling sbcs option:

cputil thermal3 sbcs decode application/vnd.star.line starmarkup.stm outputdata.bin

Note:

If it is not specified this optioin, the utf8 option will be used as default. Also, when the sbcs option is used, if diffrent codepage characters are mixed in the same line, these characters will be empty.

Specifying the cut type when an input source is text or an image

When converting to an output format that includes device commands (example: application/vnd.star.starprnt), you can set CPUtil with the following commands to include control commands to specify the cut type when the input source is text or an image:

`fullcut`	Performs a full cut at the end of the print job. (Default)
`partialcut`	Performs a partial cut at the end of the print job.

Target media types (input sources):

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

Example:

To prepare print data as StarPRNT commands for a 3inch printer from a PNG source and perform a partial cut at the end of the print job, use the following command:

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

Note:
If the input source media type is application/vnd.star.markup, this setting is ignored.

CPUtil - Server Integration

CPUtil is designed to be as easy as possible to integrate with web development technology on the server. To make this feasible, the following requirements must be met:

The scripting language on the server can invoke an external process and retrieve its output.
The web host can execute native binaries using server-side scripting.
The host server environment is supported by .NET Core.
At present, the supported environments include Windows (32/64-bit), Linux (64-bit including Arm-based Raspberry Pi), and Mac OS 64-bit.

Invoking CPUtil

PHP

PHP has a few methods to invoke CPUtil: triggering an external process to read the output with a command and including the output directly in an HTTP response.
Refer to the system(), passthru(), and exec() functions. In most cases, you can use passthru() to insert the CPUtil output directly into a response.

For example, when you invoke cputil mediatypes-mime text/vnd.star.markup, a list of print job types that can be generated with Star Document Markup is output to JSON data. This can be used as a value in the mediaTypes field of a CloudPRNT POST response.

Node.js

In a Node.js environment, you can use the native child_process module to invoke CPUtil as an external process.
For convenience, there are some synchronous and asynchronous alternatives for the child_process module. For details, refer to the child_process.exec(), child_process.execSync(), child_process.execFile(), and child_process.execFileSync() functions.

In specific use cases, such as shell script automation, the synchronous methods would be preferable. However, note that synchronous methods may affect performance because the event loop is stopped during the completion of the generated process.

For example, to start CPUtil as a child process and convert the ASB status into JSON, use the following command:

const child_process = require('child_process');

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

When Using CPUtil on the Server

CPUtil is intended to assist with CloudPRNT-specific requirements for server development. For this reason, it is assumed to be used to process CloudPRNT POST and GET requests.
The primary function of CPUtil is to convert print jobs from one format to another. Since not all CloudPRNT client devices support the same print data format output commands, this function is useful when the CloudPRNT server creates a print job.

It also provides a mechanism that negotiates job data formats that can be supported by both the server and the client device. To prevent additional work and complexity from being applied to the codes on the server (particularly, it is necessary to convert or render print jobs using multiple ways), CPUtil supports negotiation and automatically converts print jobs as necessary.

POST requests (CloudPRNT poll)

The CloudPRNT client device issues an HTTP POST request to the specified URL on the server.
This POST request is used to notify the server of the current client device status and make it possible for the server to respond to the request.

A POST request from the client device is triggered when the printer status is updated at the specified interval or an event occurs on the client device, such as a barcode scan.

Meanwhile, a POST response from the server allows various types of requests, such as notifying the client device that there is a print job, refreshing the customer display, making a request for additional information (paper size, print area, etc.) about the client device, and setting a unique ID of the client device.

By using CPUtil in POST requests and responses, developers are provided with the following two supports:

Decoding the status
A POST request includes both a simple device status code and more detailed Star ASB format status information.
In most cases, it is enough to use the status code alone, but if the server requires more details, bitmask information must be decoded from hexadecimal data included in the ASB status string. However, it is inconvenient to perform this operation through implementation on the server, so you need to use CPUtil to convert the Star ASB string into formatted JSON data.
For details, refer to the Decoding the Star ASB Status section.
Managing print job formats
During a print job notification, CPUtil is used to generate the correct value of the mediaTypes field of a JSON format response.

Managing print job formats

When CPUtil is used, the server can prepare a print job using any media type regardless of the media types supported by the client device.
The following input sources are currently available: PNG, JPEG, BMP, GIF, ASCII/UTF8 text, and Star Document Markup.

When the server receives a POST request and is requested to print a job, it needs to provide a JSON format response body with the jobReady field set to true and a list of available media types specified in mediaTypes.

The following is an example of using CPUtil with the command (cputil mediatypes-mime text/vnd.star.markup) to generate a response with a list of available media types:
* Example of a bash shell script to be invoked through cgi

#!/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 requests (retrieving a print job)

When being notified that there is a print job, the CloudPRNT client device sends an HTTP GET request to the server. At this time, the device selects the compatible data format from the mediaTypes list. This format is set in the query string parameter of the GET request.

The server uses CPUtil in a GET handler to internally convert the print job from the input source media type to the format requested by the CloudPRNT client device.

The following is a bash script example of converting a locally stored Star Document Markup file into the media format requested by the printer when it is invoked as a CGI script to process a GET request:

#!/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" -