Dart SDK は Flutter アプリに適しており、同じ印刷テンプレートを再利用したい Android、iOS、デスクトップクライアントにも適しています。初めて使うときは、コードを 2 層に分けることをおすすめします。接続層はデバイスの取得を担当し、テンプレート層は ESC、TSPL、CPCL 命令の生成を担当します。

パッケージ選択

パッケージ	用途
nib	標準集約パッケージ。core、Boxliy/Aryten/Lin8inch 方言、画像機能を export します。
nib_core	ConnectedDevice、WritePipeline、ChunkPolicy、受信ソース、クエリ分配。
nib_esc_boxliy、nib_tspl_boxliy、nib_cpcl_boxliy	Boxliy 方言ビルダーとレスポンス parser。
nib_esc、nib_tspl、nib_cpcl	Aryten 互換方言。
nib_esc_lin8inch、nib_tspl_lin8inch	Lin8inch 方言。
nib_bluetooth_ble	BLE スキャン、接続、characteristic 選択、credit フロー制御。
nib_bluetooth_classic	クラシック Bluetooth プリンター接続。

正式なプロジェクトでは、通常 package:nib/nib.dart から始めます。モジュール単位で配布する必要がある場合にだけ、下位パッケージを直接使います。

ConnectedDevice 契約

実プリンターへ接続した後は、ConnectedDevice<T> にラップする必要があります。

abstract class ConnectedDevice<T> {
  T origin();
  String? deviceName();
  String? deviceMac();
  ConnectionState connectionState();
  Stream<ConnectionState> connectionStateChanges();
  Future<void> disconnect();
  Future<void> write(Uint8List data, {bool sendDone = true});
  Stream<Uint8List> read(ReadOptions? options);
}

BLE、クラシック Bluetooth、テストデバイスのいずれでも、この契約を実装すれば同じビルダーと書き込みパイプラインを使えます。

初回印刷

次のサンプルは標準パッケージ内の Aryten TSPL ビルダーを使います。NullDevice はローカルテストにだけ適しています。実プロジェクトでは、BLE またはクラシック Bluetooth 接続が返すデバイスに置き換えてください。

import 'package:nib/nib.dart';

final device = NullDevice.instance;

final printer = TsplAryten(device)
  ..size(40, 30)
  ..cls()
  ..text(x: 20, y: 20, content: 'NIB SDK')
  ..print();

await printer.flush();

flush() はビルダーの現在のバイト列を、ビルダーにバインドされたデバイスへ書き込みます。より細かい進捗、タイムアウト、分割制御が必要な場合は、WritePipeline を直接使います。

final result = await WritePipeline.write(
  device,
  printer.bytes(),
  options: WriteOptions(
    chunkPolicy: ChunkPolicy.fixed(1024),
  ),
);

if (!result.success) {
  // 根据 cancelled、timedOut、backpressured 做业务处理。
}

core のデフォルト分割サイズは 1024 バイトです。つまり WriteOptions() はデフォルトで ChunkPolicy.fixed(NibDefaults.chunkSize) を使います。

BLE 分割と credit

通常の BLE 書き込みでは、MTU に基づいて分割を制御する必要があります。

final flow = BleFlowController.forNegotiatedMtu(185);

await WritePipeline.write(
  device,
  printer.bytes(),
  options: flow.writeOptions,
);

nib_bluetooth_ble は credit フロー制御も提供します。

API	用途
BleCreditOptions	credit を有効にし、UUID、戦略、初期 credit、MTU、fallback を設定します。
BleLaneCreditFlowControlStrategy	lane-credit 戦略。デフォルト初期 credit は 1。
BleSignalCreditFlowControlStrategy	signal-credit 戦略。デフォルト初期 credit は 0。
selectBleCreditCharacteristicPair()	service、write、read、credit characteristic の組み合わせを見つけます。

デフォルト UUID は FF00 service、FF02 write、FF01 read、FF03 credit です。デフォルト初期 MTU は 20 です。lane-credit のデフォルト payload overhead は 3、signal-credit のデフォルト payload overhead は 0 です。BleCreditOptions.enabled のデフォルトは false であり、デバイスが credit 通知を必要とする場合だけ有効にします。

受信、クエリ、解析

core の受信とクエリの型には、ReceiveSource、StreamReceiveSource、ReceiveSources.fromDevice()、QueryDispatcher<T>、PendingQuery<T> があります。ConnectedDevice には receiveSource() 拡張メソッドもあり、read() stream を受信ソースにラップできます。

Boxliy 方言は次の parser を提供します。

方言	parser
ESC	EscResponseParser
TSPL	TsplResponseParser
CPCL	CpclResponseParser

EscResponseParser と TsplResponseParser では parse(query, data) をよく使います。CPCL にはクエリ解析に加えて、ステータスフレーム用の parseEvent(...) もあります。

Methods and Commands

The tables below list the public entry points integration teams usually need. Builder methods generate printer commands; actual availability still depends on the ESC, TSPL, CPCL, or Lin8inch command family supported by the target firmware.

Core, Connection, and Writing

Object	Method / Command	Purpose	Parameters
ConnectedDevice<T>	origin(), deviceName(), deviceMac(), connectionState(), connectionStateChanges(), disconnect(), write(data), read(options)	Abstracts the real printer connection for templates, write pipelines, and query handling.	`data` is the byte payload; `sendDone` lets adapters signal completion; `ReadOptions` controls read behavior.
WritePipeline	write(device, data, options)	Writes built bytes to a device with chunking, timeout, cancellation, and flow-control rules.	`device` is the connection; `data` is the bytes; `WriteOptions` contains `ChunkPolicy`, `WriteMode`, cancellation, timeout, and backpressure.
ReceiveSource / QueryDispatcher	start(listener), stop(), query(matcher, timeout), cancel(), shutdown()	Routes device responses into listeners or query dispatchers for status, battery, model, and similar queries.	`matcher` maps raw responses to results; `timeout` bounds waiting; listeners receive data/error/closed events.
BLE credit	BleCreditOptions, BleLaneCreditFlowControlStrategy, BleSignalCreditFlowControlStrategy, selectBleCreditCharacteristicPair()	Handles BLE characteristic selection, MTU chunking, credit notifications, and fallback writes.	Configure service/write/read/credit UUIDs, initialCredit, initialMtu, payload overhead, strategy, and fallbackMode.

Command Builders

Object	Method / Command	Purpose	Parameters
EscBoxliy / EscAryten	reset(), raw(), newLine(), feed(), lineRow(), lineDot(), backLineDot(), location(), cut(), lineDotCut(), enable(), stopJob(), wakeup(), batteryVolume(), info(), model(), version(), printerVersion(), name(), mac(), sn(), state(), status(), barcode(), qrcode(), image(), imageGray(), clear(), flush()	Builds ESC/Boxliy commands for receipt, portable, and ESC-compatible printers.	Use `raw` for text or bytes; rows/dots/location control feed and positioning; barcode/QR use value/type/height/size/level; images use bitmap, byteWidth, height, or a prepared bitmap.
TsplBoxliy / TsplAryten	size(), gap(), bline(), continuous(), label(), direction(), codePage(), speed(), density(), reference(), offset(), shift(), gapSensor(), ribbon(), cut(), tear(), peel(), cls(), text(), barcode(), qrcode(), dmatrix(), line(), box(), circle(), ellipse(), image(), print(), raw(), clear(), flush()	Builds TSPL label commands for templates with paper size, coordinates, barcodes, and QR codes.	`size/gap` use millimeters; drawing primitives use x/y/width/height/thickness; text uses font/rotation/xMul/yMul/content; images use bitmap or prepared bitmap.
CpclBoxliy / CpclAryten	begin(), pageWidth(), feed(), gapSense(), barSense(), paperType(), text(), barcode(), qrcode(), line(), box(), bold(), underline(), waterMark(), inverseLine(), image(), form(), print(), status(), realtimeStatus(), sn(), model(), version(), batteryVolume(), raw(), clear(), flush()	Builds CPCL label commands for page setup, text, lines, barcodes, and images.	`begin` takes height/copies; text uses font/size/x/y/content/rotation; barcodes use type/width/ratio/height/x/y/value; images use x/y/bitmap/byteWidth/height.
EscLin8inch	batteryLevel(), extendedModel(), bootVersion(), advancedDensity(), advancedDensityStatus(), mediaProfile(), mediaProfileStatus(), grayMode(), wirelessProvisioning(), wirelessProvisioningStatus(), compressedRasterTransport(), mediaTag(), mediaTagUid(), consumedMediaLength(), remainingMediaLength(), restoreLabelStartPosition(), alternateMotionProfile()	Adds Lin8inch telemetry, media, provisioning, and raster transport commands on top of ESC.	`advancedDensity` takes a density level; `mediaProfile` takes a media enum; `wirelessProvisioning` takes ssid/password/mode.
TsplLin8inch	automaticStatusFeedback(), printCompletion(), printerStatus(), firmwareVersion(), serialNumber(), macAddress(), deviceSpeed(), deviceSelfTest(), thermalStatus(), productId(), versionInfo(), selfTestPage(), modelSetting(), serialSetting(), versionSetting(), gbkCodepage(), utf8Codepage(), gapDetection(), configureStock(), configurePresentation(), twoColorRibbon(), directThermal()	Adds Lin8inch status feedback, media, ribbon, and presentation commands on top of TSPL.	`printCompletion` takes a 4-byte token; `printerStatus` takes a status flag; `configureStock` takes sensor, markOrGapMm, and offsetMm.

Response Parsing

Object	Method / Command	Purpose	Parameters
EscResponseParser / TsplResponseParser / CpclResponseParser	parse(query, data), parse(data)	Parses printer responses into status, battery, text, MAC, event, or unknown response objects.	`query` identifies status, battery, version, model, serial-number, and similar queries; `data` is the raw response.

実践上のおすすめ

• 機種に基づいて ESC、TSPL、CPCL のどれかを確認し、1 つのテンプレート内で複数の方言を混用しないでください。
• 接続、権限、再接続はサービス層に置きます。印刷テンプレートは紙幅、座標、内容だけを扱います。
• ラベル印刷では、先にミリメートルサイズ、DPI、ギャップ、濃度を確認してからテンプレートを書きます。
• BLE の実機テストでは、大きな画像、連続印刷、切断後の再接続、credit 通知をカバーしてください。