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(...) 用于状态帧。

方法与命令清单

下面列出这个语言 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 通知。