Swift SDK 适合新的 iOS 和 macOS 原生项目。源码中没有找到可确认的 Package.swift，所以这里不写具体 SwiftPM product 名称；请按交付包的导入方式接入对应模块。

模块内容

模块	常用类型
Core	NibScript、NibDevice、NibPen、NibWritePipeline、接收源和查询分发。
BLE	NibBleCentral、NibBleDevice、NibBleConnectionOptions、credit 流控。
Boxliy dialects	NibEscBoxliy、NibTsplBoxliy、NibCpclBoxliy 和响应解析器。
Aryten dialects	NibEscAryten、NibTsplAryten、NibCpclAryten。
Image helpers	交付版本中可用的图片准备和打印辅助能力。

Core 对象

NibDevice 是最小设备合约：

public protocol NibDevice: AnyObject {
  var name: String { get }
  var connected: Bool { get }

  func write(_ data: Data) throws
  func read(maxLength: Int) throws -> Data
  func close() throws
}

NibScript 保存构建好的 Data，并提供 length、string、hexString。NibWritePipeline 负责分片写入，默认 chunkSize 是 512 字节。

第一次打印

let connectedDevice: NibDevice = /* BLE 或平台设备 */

let script = NibTsplAryten()
  .size(width: 40, height: 30)
  .cls()
  .text(x: 20, y: 20, content: "NIB SDK")
  .print()
  .script

let pipeline = NibWritePipeline()
try pipeline.write(script, to: connectedDevice)

构建器负责生成脚本，NibWritePipeline 负责把脚本分片写入设备。需要改变分片大小时：

let pipeline = NibWritePipeline(chunkSize: 185)
try pipeline.write(script, to: connectedDevice)

BLE 接入

BLE 入口是 NibBleCentral：

let central = NibBleCentral()
try central.startDiscovery(timeout: 10)

// 用户选择 discoveredDevices 里的目标设备后：
let device = try central.connect(
  selectedDevice,
  options: NibBleConnectionOptions()
)

NibBleConnectionOptions 可以配置 serviceUUIDs、writeCharacteristicUUID、readCharacteristicUUID、连接和发现超时、writeMode、credit 和自定义 flowControl。写入模式是 NibBleWriteMode.withResponse 或 .withoutResponse，默认是 .withoutResponse。

BLE credit 流控

credit API 包括：

API	用途
NibBleCreditOptions	配置是否启用 credit、UUID、初始 credit、MTU、策略和 fallback。
NibBleLaneCreditWriter	lane-credit 策略。
NibBleSignalCreditWriter	signal-credit 策略。
NibBleFlowControlStrategy	自定义流控策略协议。

默认 UUID 是 FF00 service、FF02 write、FF01 read、FF03 credit。lane-credit 默认初始 credit 是 1，payload overhead 是 3；signal-credit 默认初始 credit 是 0，payload overhead 是 0。NibBleCreditOptions 默认不启用，除非选择 .signalCredit 或显式设置 enabled: true。

接收、查询和 dataStream

Core 接收类型包括 NibReceiveSource、NibCallbackReceiveSource、NibPollingReceiveSource 和 NibReceiveListener。查询类型包括 NibQueryDispatcher<Response>、NibPendingQuery<Response> 和 NibResponseMatcher<Response>。

NibReceiveSource 提供 dataStream() 扩展，可以把回包转换成 AsyncStream<Data>：

for await data in device.receiveSource.dataStream() {
  let response = NibTsplResponseParser.parse(query: .status, raw: data)
  if response.isReady {
    break
  }
}

Boxliy 方言 parser 名称：

方言	解析器
ESC	NibEscResponseParser
TSPL	NibTsplResponseParser
CPCL	NibCpclResponseParser

方法与命令清单

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

Core、连接与写入

对象	方法 / 命令	作用	参数说明
NibDevice / NibScript	write(_ data), read(maxLength), close(), length, string, hexString	抽象真实打印机连接，供模板、写入管线和查询层统一使用。	`maxLength` 限制读取长度；`NibScript` 包装构建好的 Data。
NibPen / NibWritePipeline	append(bytes), append(data), append(text), crlf(), clear(), reset(), write(script, to), write(data, to)	把已经构建好的字节按分片、超时、取消和流控规则写入设备。	`chunkSize` 在 pipeline 初始化时配置；返回实际写入字节数。
NibBleCentral / NibBleDevice	startDiscovery(), stopDiscovery(), connect(), disconnect(), discover(options), write(), read(), close()	处理 BLE 特征值选择、MTU 分片、credit 通知和 fallback 写入。	`NibBleConnectionOptions` 配置 service/write/read UUID、timeout、writeMode 和 credit。
NibReceiveSource / NibQueryDispatcher	start(listener), stop(), accept(), receive(), query(timeout, matcher), wait(), cancel(), shutdown(), dataStream()	把设备回包接入监听器或查询分发器，用于状态、电量、型号等查询。	`matcher` 返回泛型响应；`wait(timeout:)` 用于同步等待查询结果。

指令构建器

对象	方法 / 命令	作用	参数说明
NibEscBoxliy / NibEscAryten	reset(), text(), newLine(), bold(), underline(), fontSize(), lineRow(), feed(), lineDot(), backLineDot(), location(), cut(), lineDotCut(), batteryVolume(), info(), model(), version(), printerVersion(), name(), mac(), sn(), state(), status(), enable(), stopJob(), wakeup(), barcode(), qrcode(), image(), raw(), clear()	生成 ESC/Boxliy 基础指令，适合小票、便携打印机和支持 ESC 的机型。	Swift ESC 直接支持 `text`；条码/二维码/图片参数与方法签名一致。
NibTsplBoxliy / NibTsplAryten	size(), cls(), print(), gap(), text(), barcode(), qrcode(), bitmap(), status(), state(), batteryVolume(), version(), versions(), model(), models(), sn(), sns(), raw(), clear()	生成 TSPL 标签指令，适合需要纸张尺寸、坐标、条码和二维码的标签模板。	`text` 传 x/y/font/rotation/xMulti/yMulti/content；`bitmap` 传 Data 或 prepared bitmap。
NibCpclBoxliy / NibCpclAryten	begin(), pageWidth(), text(), barcode(), qrcode(), line(), box(), image(), form(), print(), status(), sn(), model(), version(), batteryVolume(), raw(), clear()	生成 CPCL 标签指令，适合 CPCL 机型的页面、文字、线条、条码和图片。	`begin` 传 height/copies；`line/box` 传坐标和 thickness；`image` 传 data/byteWidth/height/compress。

回包解析

对象	方法 / 命令	作用	参数说明
NibEscResponseParser / NibTsplResponseParser / NibCpclResponseParser	parse(raw), parse(query, raw)	把打印机回包解析成状态、电量、文本、MAC、事件或未知响应。	返回结构包含 query、type、raw、rawHex、statusByte、statusFlags、isReady、电量、文本、描述等字段。

实战建议

• 先确认机型支持 ESC、TSPL 还是 CPCL，再选构建器。
• BLE 权限、扫描、重连和 App 生命周期逻辑放在连接层。
• 模板层只处理纸张尺寸、坐标、图片和文字内容。
• 真机验证 write mode、MTU、credit 通知、大图片和连续打印。