The Objective-C SDK is suitable for existing iOS projects, mixed Objective-C / Swift projects, and projects delivered as a framework or Nib.xcframework. The standard entry header is:

#import <Nib/Nib.h>

Framework contents

Module	Common types
Core	BNDevice, BNScript, BNWritePipeline, BNReceiveSource, BNQueryDispatcher.
BLE	BNBleCentral, BNBleDevice, BNBleConnectionOptions, credit flow control.
Boxliy dialects	BNEscBoxliy, BNTsplBoxliy, BNCpclBoxliy, and response parsers.
Aryten dialects	BNEscAryten, BNTsplAryten, BNCpclAryten.
Lin8inch dialects	BNEscLin8inch, BNTsplLin8inch.
Image helpers	Image preparation and print helpers available in the delivered package.

Core objects

BNDevice is the minimal device contract:

@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 stores built NSData, and BNWritePipeline writes to BNDevice in chunkSize chunks.

First print

#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];

If the device uses ESC receipt-style output, you can also use BNEscBoxliy to build a BNScript. Regardless of dialect, the actual write is handled by BNDevice or BNWritePipeline.

BLE integration

The BLE entry point is BNBleCentral. A common flow is:

1. Create BNBleCentral.
2. Call startDiscoveryWithDisconnectConnectedDevice:useMac:timeout:serviceUUIDs:discovered:error: to scan.
3. Select a BNBleDiscoveredDevice.
4. Create BNBleConnectionOptions, and set service, write, read, write mode, and credit according to the device.
5. Call connectDiscoveredDevice:options:completion: to obtain a BNBleDevice.
6. Generate a script with a dialect builder.
7. Write through BNWritePipeline or BNBleDevice.

BNBleConnectionOptions can set writeMode, corresponding to the with response / without response write modes of BNBleWriteMode.

BLE credit flow control

Credit APIs are in BNBleCredit.h:

API	Purpose
BNBleCreditOptions	Configures whether credit is enabled, UUIDs, initial credit, MTU, strategy, and fallback.
BNBleLaneCreditWriter	lane-credit writer.
BNBleSignalCreditWriter	signal-credit writer.
BNBleFlowControlStrategy	Custom flow-control strategy protocol.

[BNBleCreditOptions defaultOptions] uses FF00 service, FF02 write, FF01 read, and FF03 credit notify, with initial credit 1, initial MTU 20, and payload overhead 3. Normal BNBleConnectionOptions does not enable credit by default. Set creditOptions only when the device requires credit notifications.

Receiving, querying, and parsing

Core receive and query types include BNReceiveSource, BNCallbackReceiveSource, BNPollingReceiveSource, BNReceiveListener, BNQueryDispatcher, BNPendingQuery, and BNResponseMatcher. BLE devices also expose receiveSource, which can be used for notification responses.

Boxliy dialect parser names:

Dialect	Parser
ESC	BNEscResponseParser
TSPL	BNTsplResponseParser
CPCL	BNCpclResponseParser

The print session layer should handle “send query command, wait for response, call parser”. The UI layer should only display results.

Methods and Commands

The tables below list the public entry points integration teams usually need. Builder methods generate printer commands; actual availability still depends on the ESC, TSPL, CPCL, or Lin8inch command family supported by the target firmware.

Core, Connection, and Writing

Object	Method / Command	Purpose	Parameters
BNDevice / BNScript	writeData:error:, readWithTimeout:error:, closeWithError:, data, hexString, base64String, stringValue, length	Abstracts the real printer connection for templates, write pipelines, and query handling.	Objective-C reports failures through NSError pointers; BNScript stores NSData.
BNWritePipeline / BNPen	initWithDevice:chunkSize:, writeData:error:, writeScript:error:, appendByte:, appendBytes:length:, appendData:, appendText:, appendCRLF, clear, reset	Writes built bytes to a device with chunking, timeout, cancellation, and flow-control rules.	`chunkSize` controls chunking; BNPen manually appends bytes and text.
BNBleCentral / BNBleDevice	startDiscoveryWithDisconnectConnectedDevice:timeout:handler:, stopDiscovery, connectDiscoveredDevice:options:completion:, disconnectCurrentDevice, writeData:error:, readWithTimeout:error:	Handles BLE characteristic selection, MTU chunking, credit notifications, and fallback writes.	`BNBleConnectionOptions` configures UUIDs, timeouts, writeMode, credit, and flowControl.
BNReceiveSource / BNQueryDispatcher	startWithListener:, stop, acceptData:, queryWithMatcher:timeout:, cancelQuery:error:, shutdown	Routes device responses into listeners or query dispatchers for status, battery, model, and similar queries.	The matcher block returns a result from NSData; listeners receive data/error/closed events.

Command Builders

Object	Method / Command	Purpose	Parameters
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	Builds ESC/Boxliy commands for receipt, portable, and ESC-compatible printers.	Parameters follow Objective-C selectors; images take NSData, byteWidth, height, or 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	Builds TSPL label commands for templates with paper size, coordinates, barcodes, and QR codes.	Paper uses width/height/gap/offset; elements use x/y; QR uses cellWidth, level, and 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	Builds CPCL label commands for page setup, text, lines, barcodes, and images.	CPCL selectors carry parameter meaning in their names; coordinate, size, and thickness units depend on model 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 extension methods across ESC and TSPL command families.	Provisioning takes SSID/password/mode; status feedback takes a flag or token; media configuration takes sensor, mark/gap, and offset.

Response Parsing

Object	Method / Command	Purpose	Parameters
BNEscResponseParser / BNTsplResponseParser / BNCpclResponseParser	parseData:, parseQuery:data:, hexStringForData:	Parses printer responses into status, battery, text, MAC, event, or unknown response objects.	Response objects include query, type, rawData, rawHex, statusByte, statusFlags, isReady, batteryLevel, text, macAddress, and description.

Practical recommendations

• Validate Bluetooth permissions, foreground/background transitions, reconnects, and continuous printing on real devices.
• Large images and label templates should be written in chunks through BNWritePipeline.
• UUIDs, write mode, and credit strategy must be confirmed for each specific printer model.
• In mixed Objective-C and Swift projects, keep the template layer on ordinary SDK types and avoid depending directly on page lifecycle.