Dart SDK 適合 Flutter 應用程式，也適合希望複用一套列印範本的 Android、iOS、桌面端客戶端。初學時建議把程式碼分成兩層：連線層負責取得裝置，範本層負責產生 ESC、TSPL 或 CPCL 指令。

套件選擇

包	用途
nib	標準聚合套件，匯出 core、Boxliy/Aryten/Lin8inch 方言和圖片能力。
nib_core	ConnectedDevice、WritePipeline、ChunkPolicy、接收源和查詢分發。
nib_esc_boxliy、nib_tspl_boxliy、nib_cpcl_boxliy	Boxliy 方言建構器和回應解析器。
nib_esc、nib_tspl、nib_cpcl	Aryten 相容方言。
nib_esc_lin8inch、nib_tspl_lin8inch	Lin8inch 方言。
nib_bluetooth_ble	BLE 掃描、連線、特徵值選擇和 credit 流控。
nib_bluetooth_classic	經典藍牙印表機連線。

正式專案一般從 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、經典藍牙或測試裝置只要實現這個合約，就可以使用同一套建構器和寫入管線。

第一次列印

下面範例使用標準套件裡的 Aryten TSPL 建構器。NullDevice 只適合本機測試；實際專案裡要換成 BLE 或經典藍牙連線回傳的裝置。

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 特徵值組合。

預設 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() 流包裝成接收源。

Boxliy 方言提供這些 parser：

方言	解析器
ESC	EscResponseParser
TSPL	TsplResponseParser
CPCL	CpclResponseParser

EscResponseParser 和 TsplResponseParser 常用 parse(query, data)；CPCL 既有查詢解析，也有 parseEvent(...) 用於狀態frame。

方法与命令清单

下面列出这个语言 SDK 中常用且对接方需要理解的公开入口。构建器方法会生成对应打印机指令；是否能在某台机器上使用，仍以机器固件支持的 ESC、TSPL、CPCL 或 Lin8inch 指令组为准。

Core、连接与写入

对象	方法 / 命令	作用	参数说明
ConnectedDevice<T>	origin(), deviceName(), deviceMac(), connectionState(), connectionStateChanges(), disconnect(), write(data), read(options)	抽象真实打印机连接，供模板、写入管线和查询层统一使用。	`data` 是待写入字节；`sendDone` 用于平台适配层确认写入完成；`ReadOptions` 控制读取策略。
WritePipeline	write(device, data, options)	把已经构建好的字节按分片、超时、取消和流控规则写入设备。	`device` 为连接；`data` 为字节；`WriteOptions` 包含 `ChunkPolicy`、`WriteMode`、取消、超时、backpressure。
ReceiveSource / QueryDispatcher	start(listener), stop(), query(matcher, timeout), cancel(), shutdown()	把设备回包接入监听器或查询分发器，用于状态、电量、型号等查询。	`matcher` 从原始回包中返回匹配结果；`timeout` 控制等待时间；listener 接收 data/error/closed。
BLE credit	BleCreditOptions, BleLaneCreditFlowControlStrategy, BleSignalCreditFlowControlStrategy, selectBleCreditCharacteristicPair()	处理 BLE 特征值选择、MTU 分片、credit 通知和 fallback 写入。	配置 service/write/read/credit UUID、initialCredit、initialMtu、payload overhead、strategy 和 fallbackMode。

指令构建器

对象	方法 / 命令	作用	参数说明
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()	生成 ESC/Boxliy 基础指令，适合小票、便携打印机和支持 ESC 的机型。	文本或字节用 `raw`；行距/定位使用 rows、dots、location；条码二维码传 value/type/height/size/level；图片传 bitmap、byteWidth、height 或 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()	生成 TSPL 标签指令，适合需要纸张尺寸、坐标、条码和二维码的标签模板。	`size/gap` 使用毫米；图元使用 x/y/width/height/thickness；文字使用 font/rotation/xMul/yMul/content；图片使用 bitmap 或 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()	生成 CPCL 标签指令，适合 CPCL 机型的页面、文字、线条、条码和图片。	`begin` 传 height/copies；文字传 font/size/x/y/content/rotation；条码传 type/width/ratio/height/x/y/value；图片传 x/y/bitmap/byteWidth/height。
EscLin8inch	batteryLevel(), extendedModel(), bootVersion(), advancedDensity(), advancedDensityStatus(), mediaProfile(), mediaProfileStatus(), grayMode(), wirelessProvisioning(), wirelessProvisioningStatus(), compressedRasterTransport(), mediaTag(), mediaTagUid(), consumedMediaLength(), remainingMediaLength(), restoreLabelStartPosition(), alternateMotionProfile()	在 ESC 基础上增加 Lin8inch 遥测、介质、配网和光栅传输相关命令。	`advancedDensity` 传浓度等级；`mediaProfile` 传介质枚举；`wirelessProvisioning` 传 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()	在 TSPL 基础上增加 Lin8inch 状态反馈、介质、色带和出纸配置命令。	`printCompletion` 传 4 字节 token；`printerStatus` 传状态 flag；`configureStock` 传 sensor、markOrGapMm、offsetMm。

回包解析

对象	方法 / 命令	作用	参数说明
EscResponseParser / TsplResponseParser / CpclResponseParser	parse(query, data), parse(data)	把打印机回包解析成状态、电量、文本、MAC、事件或未知响应。	`query` 指定状态、电量、版本、型号、序列号等查询类型；`data` 是设备回包原始字节。

實戰建議

• 先按機型確認 ESC、TSPL 或 CPCL，不要在一個範本裡混用多個方言。
• 連線、權限、重連放在服務層；列印範本只關心紙寬、座標和內容。
• 標籤列印先確認毫米尺寸、DPI、間隙和濃度，再寫範本。
• BLE 真機測試要覆蓋大圖、連續列印、斷線重連和 credit 通知。