Dart SDK는 Flutter 애플리케이션에 적합하며, 한 벌의 인쇄 템플릿을 재사용하려는 Android, iOS, 데스크톱 클라이언트에도 적합합니다. 처음에는 코드를 두 계층으로 나누는 것을 권장합니다. 연결 계층은 디바이스를 얻고, 템플릿 계층은 ESC, TSPL 또는 CPCL 명령어를 생성합니다.

패키지 선택

패키지	용도
nib	표준 통합 패키지입니다. core, Boxliy/Aryten/Lin8inch dialect와 이미지 기능을 내보냅니다.
nib_core	ConnectedDevice, WritePipeline, ChunkPolicy, 수신 소스, 질의 분배를 제공합니다.
nib_esc_boxliy, nib_tspl_boxliy, nib_cpcl_boxliy	Boxliy dialect 빌더와 응답 parser입니다.
nib_esc, nib_tspl, nib_cpcl	Aryten 호환 dialect입니다.
nib_esc_lin8inch, nib_tspl_lin8inch	Lin8inch dialect입니다.
nib_bluetooth_ble	BLE 스캔, 연결, characteristic 선택, credit 흐름 제어입니다.
nib_bluetooth_classic	클래식 블루투스 프린터 연결입니다.

정식 프로젝트는 일반적으로 package:nib/nib.dart부터 시작합니다. 모듈 단위로 전달해야 할 때만 하위 패키지를 직접 사용하세요.

ConnectedDevice 계약

실제 프린터 연결 후에는 ConnectedDevice<T>로 감싸야 합니다.

abstract class ConnectedDevice<T> {
  T origin();
  String? deviceName();
  String? deviceMac();
  ConnectionState connectionState();
  Stream<ConnectionState> connectionStateChanges();
  Future<void> disconnect();
  Future<void> write(Uint8List data, {bool sendDone = true});
  Stream<Uint8List> read(ReadOptions? options);
}

BLE, 클래식 블루투스, 테스트 디바이스는 이 계약만 구현하면 같은 빌더와 쓰기 파이프라인을 사용할 수 있습니다.

첫 인쇄

아래 예제는 표준 패키지의 Aryten TSPL 빌더를 사용합니다. NullDevice는 로컬 테스트에만 적합합니다. 실제 프로젝트에서는 BLE 또는 클래식 블루투스 연결이 반환한 디바이스로 교체해야 합니다.

import 'package:nib/nib.dart';

final device = NullDevice.instance;

final printer = TsplAryten(device)
  ..size(40, 30)
  ..cls()
  ..text(x: 20, y: 20, content: 'NIB SDK')
  ..print();

await printer.flush();

flush()는 빌더의 현재 바이트를 바인딩된 디바이스에 씁니다. 더 세밀한 진행률, 타임아웃 또는 분할 제어가 필요하면 WritePipeline을 직접 사용하세요.

final result = await WritePipeline.write(
  device,
  printer.bytes(),
  options: WriteOptions(
    chunkPolicy: ChunkPolicy.fixed(1024),
  ),
);

if (!result.success) {
  // 根据 cancelled、timedOut、backpressured 做业务处理。
}

core의 기본 분할 크기는 1024 바이트입니다. 즉 WriteOptions()는 기본적으로 ChunkPolicy.fixed(NibDefaults.chunkSize)를 사용합니다.

BLE 분할과 credit

일반 BLE 쓰기는 보통 MTU에 맞춰 분할을 제어해야 합니다.

final flow = BleFlowController.forNegotiatedMtu(185);

await WritePipeline.write(
  device,
  printer.bytes(),
  options: flow.writeOptions,
);

nib_bluetooth_ble는 credit 흐름 제어도 제공합니다.

API	용도
BleCreditOptions	credit을 활성화하고 UUID, 전략, 초기 credit, MTU, fallback을 구성합니다.
BleLaneCreditFlowControlStrategy	lane-credit 전략이며, 기본 초기 credit은 1입니다.
BleSignalCreditFlowControlStrategy	signal-credit 전략이며, 기본 초기 credit은 0입니다.
selectBleCreditCharacteristicPair()	service, write, read, credit characteristic 조합을 찾습니다.

기본 UUID는 FF00 service, FF02 write, FF01 read, FF03 credit입니다. 기본 초기 MTU는 20입니다. lane-credit의 기본 payload overhead는 3, signal-credit의 기본 payload overhead는 0입니다. BleCreditOptions.enabled의 기본값은 false이며, 디바이스가 credit 알림을 필요로 할 때만 켜세요.

수신, 질의, 파싱

core의 수신 및 질의 타입에는 ReceiveSource, StreamReceiveSource, ReceiveSources.fromDevice(), QueryDispatcher<T>, PendingQuery<T>가 있습니다. ConnectedDevice에는 receiveSource() 확장 메서드도 있어 read() 스트림을 수신 소스로 감쌀 수 있습니다.

Boxliy dialect는 다음 parser를 제공합니다.

dialect	parser
ESC	EscResponseParser
TSPL	TsplResponseParser
CPCL	CpclResponseParser

EscResponseParser와 TsplResponseParser는 보통 parse(query, data)를 사용합니다. CPCL은 질의 파싱뿐 아니라 상태 프레임을 위한 parseEvent(...)도 제공합니다.

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
ConnectedDevice<T>	origin(), deviceName(), deviceMac(), connectionState(), connectionStateChanges(), disconnect(), write(data), read(options)	Abstracts the real printer connection for templates, write pipelines, and query handling.	`data` is the byte payload; `sendDone` lets adapters signal completion; `ReadOptions` controls read behavior.
WritePipeline	write(device, data, options)	Writes built bytes to a device with chunking, timeout, cancellation, and flow-control rules.	`device` is the connection; `data` is the bytes; `WriteOptions` contains `ChunkPolicy`, `WriteMode`, cancellation, timeout, and backpressure.
ReceiveSource / QueryDispatcher	start(listener), stop(), query(matcher, timeout), cancel(), shutdown()	Routes device responses into listeners or query dispatchers for status, battery, model, and similar queries.	`matcher` maps raw responses to results; `timeout` bounds waiting; listeners receive data/error/closed events.
BLE credit	BleCreditOptions, BleLaneCreditFlowControlStrategy, BleSignalCreditFlowControlStrategy, selectBleCreditCharacteristicPair()	Handles BLE characteristic selection, MTU chunking, credit notifications, and fallback writes.	Configure service/write/read/credit UUIDs, initialCredit, initialMtu, payload overhead, strategy, and fallbackMode.

Command Builders

Object	Method / Command	Purpose	Parameters
EscBoxliy / EscAryten	reset(), raw(), newLine(), feed(), lineRow(), lineDot(), backLineDot(), location(), cut(), lineDotCut(), enable(), stopJob(), wakeup(), batteryVolume(), info(), model(), version(), printerVersion(), name(), mac(), sn(), state(), status(), barcode(), qrcode(), image(), imageGray(), clear(), flush()	Builds ESC/Boxliy commands for receipt, portable, and ESC-compatible printers.	Use `raw` for text or bytes; rows/dots/location control feed and positioning; barcode/QR use value/type/height/size/level; images use bitmap, byteWidth, height, or a prepared bitmap.
TsplBoxliy / TsplAryten	size(), gap(), bline(), continuous(), label(), direction(), codePage(), speed(), density(), reference(), offset(), shift(), gapSensor(), ribbon(), cut(), tear(), peel(), cls(), text(), barcode(), qrcode(), dmatrix(), line(), box(), circle(), ellipse(), image(), print(), raw(), clear(), flush()	Builds TSPL label commands for templates with paper size, coordinates, barcodes, and QR codes.	`size/gap` use millimeters; drawing primitives use x/y/width/height/thickness; text uses font/rotation/xMul/yMul/content; images use bitmap or prepared bitmap.
CpclBoxliy / CpclAryten	begin(), pageWidth(), feed(), gapSense(), barSense(), paperType(), text(), barcode(), qrcode(), line(), box(), bold(), underline(), waterMark(), inverseLine(), image(), form(), print(), status(), realtimeStatus(), sn(), model(), version(), batteryVolume(), raw(), clear(), flush()	Builds CPCL label commands for page setup, text, lines, barcodes, and images.	`begin` takes height/copies; text uses font/size/x/y/content/rotation; barcodes use type/width/ratio/height/x/y/value; images use x/y/bitmap/byteWidth/height.
EscLin8inch	batteryLevel(), extendedModel(), bootVersion(), advancedDensity(), advancedDensityStatus(), mediaProfile(), mediaProfileStatus(), grayMode(), wirelessProvisioning(), wirelessProvisioningStatus(), compressedRasterTransport(), mediaTag(), mediaTagUid(), consumedMediaLength(), remainingMediaLength(), restoreLabelStartPosition(), alternateMotionProfile()	Adds Lin8inch telemetry, media, provisioning, and raster transport commands on top of ESC.	`advancedDensity` takes a density level; `mediaProfile` takes a media enum; `wirelessProvisioning` takes ssid/password/mode.
TsplLin8inch	automaticStatusFeedback(), printCompletion(), printerStatus(), firmwareVersion(), serialNumber(), macAddress(), deviceSpeed(), deviceSelfTest(), thermalStatus(), productId(), versionInfo(), selfTestPage(), modelSetting(), serialSetting(), versionSetting(), gbkCodepage(), utf8Codepage(), gapDetection(), configureStock(), configurePresentation(), twoColorRibbon(), directThermal()	Adds Lin8inch status feedback, media, ribbon, and presentation commands on top of TSPL.	`printCompletion` takes a 4-byte token; `printerStatus` takes a status flag; `configureStock` takes sensor, markOrGapMm, and offsetMm.

Response Parsing

Object	Method / Command	Purpose	Parameters
EscResponseParser / TsplResponseParser / CpclResponseParser	parse(query, data), parse(data)	Parses printer responses into status, battery, text, MAC, event, or unknown response objects.	`query` identifies status, battery, version, model, serial-number, and similar queries; `data` is the raw response.

실전 권장 사항

• 먼저 모델별로 ESC, TSPL, CPCL 중 무엇을 지원하는지 확인하고, 하나의 템플릿 안에 여러 dialect를 섞지 마세요.
• 연결, 권한, 재연결은 서비스 계층에 두고, 인쇄 템플릿은 용지 폭, 좌표, 콘텐츠만 다루게 하세요.
• 라벨 인쇄는 템플릿 작성 전에 밀리미터 크기, DPI, 간격, 농도를 먼저 확인하세요.
• BLE 실제 장비 테스트는 큰 이미지, 연속 인쇄, 연결 끊김 후 재연결, credit 알림을 포함해야 합니다.