6.1. ICommandBuilder 移行ガイド(StarPRNT V5搭載機能)

本ページは、プリンターモデル依存を最小限に抑えることを目的とした ICommandBuilder 移行ガイドです。

ICommandBuilder とは、従来のバイナリ形式でのコマンド生成ではなくヒューマンリーダブルなコマンド生成を可能にする機能で、StarPRNT V5.0以降の拡張ライブラリ(以降、 starioextension )に搭載しています。

今までは開発者がプリンターエミュレーションの仕様を理解した上でコマンドを生成しなければいけませんでしたが、本機能により学習コストを抑えることができ、機種追加時の工数削減も期待できます。

本ページを参考に ICommandBuilder をご活用ください。

6.1.1. 必要な作業内容一覧

ICommandBuilder への移行とプリンターモデルの追加に必要な作業は以下です。

  1. starioextension の導入

  2. APIとコマンド作成方法の変更

  3. Emulationの指定

  4. portNameの指定

重要

プリンターモデルの組み合わせによっては、 portSettings指定の変更 も必要になります。

6.1.2. starioextension の導入

プロジェクトに starioextension が組み込まれていることを確認してください。 各ライブラリは同一SDKバージョンの物をご利用ください。

1. ライブラリの組み込み

Mavenリポジトリを使用する
dependencies {
    implementation 'com.starmicronics:stario:starioVersion'
    implementation 'com.starmicronics:starioextension:starioextensionVersion'
    ...
}
AARファイルを使用する
dependencies {
    implementation(name: 'stario', ext: 'aar')
    implementation(name: 'starioextension', ext: 'aar')
    ...
}

2. ライブラリのインポート

今回追加する starioextension および stario のパッケージ名です。

  • com.starmicronics.stario

  • com.starmicronics.starioextension

ライブラリ導入手順の詳細は、 ライブラリ追加方法 に記載しています。

6.1.3. APIとコマンド作成方法の変更方法(ICommandBuilderの導入)

全体フローの違い

下記フローに示すように、 ICommandBuilder の導入にコマンド生成部以外の変更は必要ありません。

migrationFlowJP

印刷データ作成(プリンター内蔵フォント)プログラム上の変更

レシート上の文字に使用されるプリンター内蔵フォント印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。

対応している機能の一覧は ICommandBuilder をご確認ください。

注釈

TSP100シリーズはプリンターフォントに対応していません。 印刷データ作成(画像データ)プログラム上の変更 をご確認ください。

Before: starioだけを利用する
ArrayList<byte[]> command = new ArrayList<byte[]>();

command.add(new byte[] { 0x1b, 0x40 });             // Initialization
command.add(new byte[] { 0x1b, 0x1d, 0x61, 0x01 }); // Alignment
command.add("Hello world".getBytes());
command.add({0x1b, 0x64, 0x02});                    // Cut paper
After: stario + ICommandBuilder/starioextensionを利用する
ICommandBuilder builder = StarIoExt.createCommandBuilder(emulation);

builder.beginDocument();
builder.appendAlignment(AlignmentPosition.Right);
builder.append("Hello world".getBytes());
builder.appendCutPaper(CutPaperAction.PartialCutWithFeed);
builder.endDocument()

byte[] command = builder.getCommands();

印刷データ作成(画像データ)プログラム上の変更

レシート上の店舗ロゴなどに使用される画像データ印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。

対応している機能の一覧は ICommandBuilder をご確認ください。

Before: starioだけを利用する
ArrayList<byte[]> commands = new ArrayList<byte[]>();
RasterDocument rasterDoc = new RasterDocument(RasSpeed.Medium, RasPageEndMode.FeedAndFullCut, RasPageEndMode.FeedAndFullCut, RasTopMargin.Standard, 0, 0, 0);
StarBitmap starbitmap = new StarBitmap(bitmap_image, false, maxWidth);

commands.add(rasterDoc.BeginDocumentCommandData());
commands.add(starbitmap.getImageRasterDataForPrinting_Standard(true));
commands.add(rasterDoc.EndDocumentCommandData());

//
// Class: Graphic data to Star command
//
public class StarBitmap {

    // omitted

    StarBitmap(Bitmap picture, boolean supportDithering, int maxWidth) {
        try {
            if (picture.getWidth() > maxWidth) {
                ScallImage(picture, maxWidth);
            } else {
                height = picture.getHeight();
                width = picture.getWidth();
                pixels = new int[height * width];

                for (int y = 0; y < height; y++) {
                    for (int x = 0; x < width; x++) {
                        pixels[PixelIndex(x, y)] = picture.getPixel(x, y);
                    }
                }
            }
            dithering = supportDithering;
            imageData = null;
        } catch (OutOfMemoryError e) {
            throw e;
        }
    }
    public byte[] getImageRasterDataForPrinting_Standard(boolean compressionEnable) {
            ////////////////////////////////////////////////////////////////////////////////////
            // About 100 lines omitted
            // Create an array according to the specifications of Star_Raster_Command (ESC * r)
            ////////////////////////////////////////////////////////////////////////////////////
        return imageData;
    }
After: stario + ICommandBuilder/starioextensionを利用する
ICommandBuilder builder = StarIoExt.createCommandBuilder(emulation);

builder.beginDocument();
builder.appendBitmap(bitmap_image, true, width, true); // create Star command from bitmap data
builder.appendCutPaper(CutPaperAction.PartialCutWithFeed);
builder.endDocument();
byte[] command = builder.getCommands();

6.1.4. プリンターモデルの追加方法

プリンターモデルの追加や移行をする場合でも、プリンターコマンドの生成に ICommandBuilder を利用しているのであれば、ほとんどのケースはエミュレーション指定の変更だけで完了します。

ただし、一部状況においては追加の変更が必要になるため、下記案内を参考に変更をお願いします。

Emulationの指定方法( ICommandBuilder )

mC-Print3とそれ以外のプリンターでは、搭載しているエミュレーションが異なることがあります。

Emulation のページで対応エミュレーションを確認し、 ICommandBuilder インスタンス生成時にエミュレーション指定を変更してください。

例として、TSP100/TSP650IIとmC-Print3では、下記表に沿ったエミュレーション指定の変更が必要です。

Printer

Emulation

TSP650II

StarLine

TSP100

StarGraphic

mC-Print3

StarPRNT

エミュレーション指定のサンプル
// TSP650II (StarLine)
// Emulation emulation = Emulation.StarLine;

// TSP100 (StarGraphic)
// Emulation emulation = Emulation.StarGraphic;

// mC-Print3 (StarPRNT)
Emulation emulation = Emulation.StarPRNT;
ICommandBuilder builder = StarIoExt.createCommandBuilder(emulation);

searchPrinter の検索方法

searchPrinter によるプリンターの検索方法は同一です。

検索で得られるモデル名をアプリケーション内で何かしらの判別に利用している場合は、対応が必要になります。

例として、検索結果に含まれるプリンターモデル名は下記の通りです。

LANインターフェース

Printer

Model Name (PortInfo)

mC-Print2

"MCP21", "MCP20"

mC-Print3

"MCP31", "MCP30"

mC-Label3

"MCL32"

TSP100IV

"TSP143IV"

TSP100IV SK

"TSP143IV"

TSP100IIILAN

"TSP143IIILAN", "TSP143IIIW"

TSP650II

"TSP654"

TSP700II

"TSP743II"

TSP800II

"TSP847II"

SP700

"SP712", "SP742", "SP717", "SP747"

USBインターフェース

Printer

Model Name (PortInfo)

mC-Print2

"mC-Print2"

mC-Print3

"mC-Print3"

mC-Label3

"mC-Label3"

mPOP

"mPOP"

TSP100IV

"Star TSP143IV-UE"

TSP100IV SK

"Star TSP143IV-UE SK"

TSP100III

"Star TSP143IIIU"

TSP100IIU+

"Star TSP143IIU+"

TSP650II

"TSP654II"

TSP700II

"TSP743II"

TSP800II

"TSP847II"

SP700

"SP712", "SP742", "SP717", "SP747"

SM-S230i

"Star SM-S230i"

Bluetoothインターフェース

Printer

Model Name (PortInfo)

mC-Print2

"mC-Print2-XXXXX"

mC-Print3

"mC-Print3-XXXXX"

mC-Label3

"mC-Label3-XXXXX"

mPOP

"STAR mPOP-XXXXX"[1], "mPOP-XXXXX"[2]

TSP100III

"TSP100-XXXXX"

TSP650II

"Star Micronics"

TSP700II

"Star Micronics"

TSP800II

"Star Micronics"

SP700

"Star Micronics"

SM-S210i

"Star Micronics"[3], "SM-S210I-XXXXX"[4]

SM-S230i

"Star Micronics"[3], "SM-S230I-XXXXX"[4]

SM-T300

"Star Micronics"[3], "SM-T300-XXXXX"[4]

SM-T300i

"Star Micronics"[3], "SM-T300i-XXXXX"[4]

SM-T400i

"Star Micronics"[3], "SM-T400i-XXXXX"[4]

SM-L200

"Star Micronics"

SM-L300

"Star Micronics"

XXXXX : 製品ごと異なる5桁の識別番号

[1]

POP10の場合

[2]

POP10CBIの場合

[3]

ファームウェアバージョン5.0未満

[4]

ファームウェアバージョン5.0以降

getPort - portName引数の指定方法

Bluetoothインターフェース

portName の指定に searchPrinter の戻り値( PortInfo )を利用している場合、引数の変更は必要ありません。

ただし、引数を直接設定(固定値など)している場合は、デバイス名の初期値がmC-Print3とそれ以外で異なるため、引数を変更しなければいけない可能性があります。

例として、TSP100/TSP650IIとmC-Print3の初期値は下記の通りです。

Printer

Bluetooth DeviceName

TSP100

"TSP100-XXXXX"

TSP650II

"Star Micronics"

mC-Print3

"mC-Print3-XXXXX"

XXXXX : 製品ごと異なる5桁の識別番号

portNameのサンプル
StarIOPort port = null;
String portSettings = "";

// TSP650II (Bluetooth)
// String portName = "BT:Star Micronics";

// TSP100 (Bluetooth)
// String portName = "BT:TSP100-XXXXX";

// mC-Print3 (Bluetooth)
// String portName = "BT:mC-Print3-XXXXX";

// No changes required if used "BT:"
String portName = "BT:";

port = StarIOport.getPort(portName, portSettings, 10000, context);

その他インターフェース

プリンター固有のデバイス名はありません。 getPort のページを参考に、インターフェースごと適切な portName を設定してください。

getPort - portSettings引数の指定方法

各プリンターモデルで適用すべき識別子が異なることがあります。 getPort のページ「2. portSettings 引数」を参考に変更してください。

例として、TSP100/TSP650IIとmC-Print3の portSettings は同一です。

Printer

portSettings

TSP100

""

TSP650II

""

mC-Print3

""

portSettingsのサンプル
StarIOPort port = null;
String portName = "BT:";

// String portSettings = "l10000"
String portSettings = "";

port = StarIOport.getPort(portName, portSettings, 10000, context);

印字領域の指定方法

プリンターモデルの組み合わせによっては印字領域設定の初期値が異なります。必要に応じて appendPrintableArea で領域を指定してください。

appendBitmap などを用いてグラフィックデータを印刷している場合は、移行先プリンターモデルの印字領域に合わせてレイアウト変更をお願いします。

6.1.5. コマンド生成からデータ送信までのコード上の流れ

コマンド生成から書き込みまでの一連です。実際には下記関数を非UIスレッドで実行してください。

public void printSample() {
    try {
        ICommandBuilder builder = StarIoExt.createCommandBuilder(StarIoExt.Emulation.StarPRNT);

        builder.beginDocument();
        builder.append("Hello, World!!").getBytes();
        builder.appendCutPaper(CutPaperAction.PartialCutWithFeed);
        builder.endDocument();

        byte[] commands = builder.getCommands();

        String portName = "BT:";
        String portSettings = "";
        StarIOPort port = StarIOPort.getPort(portName, portSettings, 1000, context);

        StarPrinterStatus status;
        status = port.beginCheckedBlock();

        if (status.offline) {
            // Printer Offline
        }

        port.writePort(commands, 0, commands.length);

        status = port.endCheckedBlock();
        if (status.coverOpen) {
            // Printer CoverOpen
        } else if (status.receiptPaperEmpty) {
            // Printer ReceiptPaperEmpty
        } else if (status.offline) {
            // Printer Offline
        }

        // Print Success

    } catch (StarIoPortException e) {
        // Port Exception
    }
}