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 通知、大圖片和連續列印。