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와 응답 parser.
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를 만들 수도 있습니다. 어떤 dialect를 사용하든 실제 쓰기는 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. dialect builder로 스크립트를 생성합니다.
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 writer입니다.
BNBleSignalCreditWriter	signal-credit writer입니다.
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 dialect parser 이름은 다음과 같습니다.

dialect	parser
ESC	BNEscResponseParser
TSPL	BNTsplResponseParser
CPCL	BNCpclResponseParser

“질의 명령어 전송, 응답 대기, parser 호출”은 인쇄 세션 계층이 담당하고, UI 계층은 결과만 표시하는 것을 권장합니다.

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.

실전 권장 사항

• 실제 장비에서 블루투스 권한, 포그라운드/백그라운드 전환, 연결 끊김 후 재연결, 연속 인쇄를 검증하세요.
• 큰 이미지와 라벨 템플릿은 모두 BNWritePipeline으로 분할 쓰기해야 합니다.
• UUID, write mode, credit 전략은 반드시 구체적인 모델에 맞춰 확인하세요.
• Objective-C와 Swift 혼합 개발 시 템플릿 계층을 일반 SDK 타입으로 유지하고 페이지 수명주기에 직접 의존하지 않게 하세요.