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 类型，避免直接依赖页面生命周期。