Objective-C SDK 適合已有 iOS 專案、Objective-C / Swift 混編專案，以及以 framework 或 Nib.xcframework 形式交付的專案。標準入口標頭檔案是：

#import <Nib/Nib.h>

Framework 內容

模組	常用類型
Core	BNDevice、BNScript、BNWritePipeline、BNReceiveSource、BNQueryDispatcher。
BLE	BNBleCentral、BNBleDevice、BNBleConnectionOptions、credit 流控。
Boxliy dialects	BNEscBoxliy、BNTsplBoxliy、BNCpclBoxliy 和回應解析器。
Aryten dialects	BNEscAryten、BNTsplAryten、BNCpclAryten。
Lin8inch dialects	BNEscLin8inch、BNTsplLin8inch。
Image helpers	交付套件中可用的圖片準備和列印輔助能力。

Core 物件

BNDevice 是最小裝置合約：

@protocol BNDevice <NSObject>

@property(nonatomic, copy, readonly) NSString *name;
@property(nonatomic, assign, readonly) BOOL connected;

- (BOOL)writeData:(NSData *)data error:(NSError **)error;
- (NSData *)readWithTimeout:(NSTimeInterval)timeout error:(NSError **)error;
- (BOOL)closeWithError:(NSError **)error;

@end

BNScript 儲存建構好的 NSData，BNWritePipeline 負責按 chunkSize 分片寫入 BNDevice。

第一次列印

#import <Nib/Nib.h>

id<BNDevice> connectedDevice = /* BLE 或平台设备 */;

BNTsplAryten *printer = [[BNTsplAryten alloc] init];
BNScript *script = [[[[[printer sizeWithWidth:40 height:30]
    cls]
    textAtX:20 y:20 content:@"NIB SDK"]
    print]
    script];

BNWritePipeline *pipeline = [[BNWritePipeline alloc] initWithDevice:connectedDevice chunkSize:512];

NSError *error = nil;
BOOL ok = [pipeline writeScript:script error:&error];

如果裝置使用 ESC 收據式輸出，也可以用 BNEscBoxliy 建構 BNScript。無論使用哪種方言，真正寫入都交給 BNDevice 或 BNWritePipeline。

BLE 接入

BLE 入口是 BNBleCentral。常見流程是：

1. 建立 BNBleCentral。
2. 呼叫 startDiscoveryWithDisconnectConnectedDevice:useMac:timeout:serviceUUIDs:discovered:error: 掃描。
3. 選擇 BNBleDiscoveredDevice。
4. 建立 BNBleConnectionOptions，按裝置設定 service、write、read、write mode 和 credit。
5. 呼叫 connectDiscoveredDevice:options:completion: 得到 BNBleDevice。
6. 使用方言建構器產生指令碼。
7. 通過 BNWritePipeline 或 BNBleDevice 寫入。

BNBleConnectionOptions 裡可以設定 writeMode，對應 BNBleWriteMode 的 with response / without response 寫入模式。

BLE credit 流控

credit API 在 BNBleCredit.h：

API	用途
BNBleCreditOptions	配置 credit 是否啟用、UUID、初始 credit、MTU、策略和 fallback。
BNBleLaneCreditWriter	lane-credit 寫入器。
BNBleSignalCreditWriter	signal-credit 寫入器。
BNBleFlowControlStrategy	自定義流控策略協議。

[BNBleCreditOptions defaultOptions] 使用 FF00 service、FF02 write、FF01 read、FF03 credit notify，初始 credit 為 1，初始 MTU 為 20，payload overhead 為 3。一般 BNBleConnectionOptions 預設不啟用 credit；只有裝置需要 credit 通知時才設定 creditOptions。

接收、查詢和解析

Core 接收與查詢類型包括 BNReceiveSource、BNCallbackReceiveSource、BNPollingReceiveSource、BNReceiveListener、BNQueryDispatcher、BNPendingQuery 和 BNResponseMatcher。BLE 裝置也暴露 receiveSource，可用於通知回包。

Boxliy 方言 parser 名稱：

方言	解析器
ESC	BNEscResponseParser
TSPL	BNTsplResponseParser
CPCL	BNCpclResponseParser

建議由列印會話層負責“傳送查詢指令、等待回包、呼叫 parser”，UI 層只展示結果。

方法与命令清单

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

Core、连接与写入

对象	方法 / 命令	作用	参数说明
BNDevice / BNScript	writeData:error:, readWithTimeout:error:, closeWithError:, data, hexString, base64String, stringValue, length	抽象真实打印机连接，供模板、写入管线和查询层统一使用。	Objective-C 使用 NSError 指针返回错误；BNScript 保存 NSData。
BNWritePipeline / BNPen	initWithDevice:chunkSize:, writeData:error:, writeScript:error:, appendByte:, appendBytes:length:, appendData:, appendText:, appendCRLF, clear, reset	把已经构建好的字节按分片、超时、取消和流控规则写入设备。	`chunkSize` 控制分片；BNPen 用于手工追加字节和文本。
BNBleCentral / BNBleDevice	startDiscoveryWithDisconnectConnectedDevice:timeout:handler:, stopDiscovery, connectDiscoveredDevice:options:completion:, disconnectCurrentDevice, writeData:error:, readWithTimeout:error:	处理 BLE 特征值选择、MTU 分片、credit 通知和 fallback 写入。	`BNBleConnectionOptions` 配置 UUID、timeout、writeMode、credit 和 flowControl。
BNReceiveSource / BNQueryDispatcher	startWithListener:, stop, acceptData:, queryWithMatcher:timeout:, cancelQuery:error:, shutdown	把设备回包接入监听器或查询分发器，用于状态、电量、型号等查询。	matcher block 从 NSData 中返回结果；listener 接收 data/error/closed。

指令构建器

对象	方法 / 命令	作用	参数说明
BNEscBoxliy / BNEscAryten	reset, text:, newLine, bold:, underline:, fontWidth:height:, lineRow:, feed:, lineDot:, backLineDot:, location:, cut, lineDotCut, batteryVolume, info, model, version, printerVersion, name, mac, sn, state, status, enable, stopJob, wakeup, wakeupWithLength:, barcodeValue:type:height:, qrcodeValue:size:level:, imageData:byteWidth:height:, imagePreparedBitmap:, rawData:, clear	生成 ESC/Boxliy 基础指令，适合小票、便携打印机和支持 ESC 的机型。	参数名跟 Objective-C selector 对应；图片传 NSData、byteWidth、height 或 PXPreparedBitmap。
BNTsplBoxliy / BNTsplAryten	sizeWithWidth:height:, cls, print, printWithCopies:, density:, speed:, direction:mirror:, gap:, gapWithHeight:offset:, blineWithHeight:offset:, continuous, labelWithHeight:offset:, offset:, ribbon:, shift:, referenceWithHorizontal:vertical:, cut:, tear:, peel:, status, state, batteryVolume, version, versions, model, models, sn, sns, textAtX:y:content:, textAtX:y:font:rotation:xMulti:yMulti:content:, barcodeAtX:y:value:, qrcodeAtX:y:value:cellWidth:level:version:, bitmapAtX:y:data:byteWidth:height:, raw:, rawData:, clear	生成 TSPL 标签指令，适合需要纸张尺寸、坐标、条码和二维码的标签模板。	纸张使用 width/height/gap/offset；图元使用 x/y；二维码使用 cellWidth、level、version。
BNCpclBoxliy / BNCpclAryten	beginWithHeight:copies:, pageWidth:, textWithFont:size:x:y:content:, barcodeAtX:y:value:, barcodeType:width:ratio:height:x:y:value:rotation:, qrcodeAtX:y:value:cellWidth:level:, lineFromX:y:toX:y:thickness:dashed:, boxFromX:y:toX:y:thickness:, imageAtX:y:data:byteWidth:height:, bold:, underline:, waterMark:, gapSense, form, print, status, sn, model, version, batteryVolume, raw:, rawData:, clear	生成 CPCL 标签指令，适合 CPCL 机型的页面、文字、线条、条码和图片。	CPCL selector 已把参数语义写在名字中；注意坐标、尺寸和线宽单位以机型 DPI 为准。
BNEscLin8inch / BNTsplLin8inch	batteryLevel, extendedModel, bootVersion, advancedDensity:, mediaProfile:, wirelessProvisioningWithSSID:password:mode:, compressedRasterTransport, automaticStatusFeedback:, printCompletionD1:d2:d3:d4:, printerStatus:, configureStock:markOrGapMm:offsetMm:, configurePresentation:, twoColorRibbon:, directThermal	Lin8inch 扩展方法，覆盖 ESC 和 TSPL 两个指令组。	配网传 SSID/password/mode；状态反馈传 flag 或 token；介质配置传 sensor、mark/gap 和 offset。

回包解析

对象	方法 / 命令	作用	参数说明
BNEscResponseParser / BNTsplResponseParser / BNCpclResponseParser	parseData:, parseQuery:data:, hexStringForData:	把打印机回包解析成状态、电量、文本、MAC、事件或未知响应。	返回对象包含 query、type、rawData、rawHex、statusByte、statusFlags、isReady、batteryLevel、text、macAddress、description。

實戰建議

• 在真機上驗證藍牙權限、前後臺切換、斷線重連和連續列印。
• 大圖片和標籤範本都要通過 BNWritePipeline 分片寫入。
• UUID、write mode、credit 策略必須按具體機型確認。
• Objective-C 與 Swift 混編時，把範本層保持為一般 SDK 類型，避免直接依賴頁面生命週期。