흐름 제어는 애플리케이션이 인쇄 데이터를 디바이스에 쓸 때 “얼마나 작게 자를지, 얼마나 빠르게 쓸지, 언제 기다릴지”를 결정합니다. 처음 연동할 때는 세 가지로 이해하면 됩니다.

1. 전체 명령어 바이트를 여러 chunk로 나눕니다.
2. 매번 현재 전송 방식이 안정적으로 감당할 수 있는 크기만 씁니다.
3. BLE 디바이스가 credit을 요구하면 디바이스 알림을 기다린 뒤 계속 씁니다.

Dialect builder는 ESC, TSPL 또는 CPCL 바이트 생성만 담당합니다. 분할 크기, 쓰기 모드, BLE credit, 실패 처리는 device, connection 또는 print session 계층에 두어야 합니다.

일반 분할

일반 분할은 인쇄 명령어의 의미를 해석하지 않고 최종 payload를 바이트 수 기준으로 자릅니다. 예를 들어 3000바이트 데이터를 1024바이트로 분할하면 1024, 1024, 952 세 조각으로 씁니다.

각 언어 core의 기본 일반 분할 크기는 다릅니다.

SDK	기본 chunk size
TypeScript	512 bytes
Dart	1024 bytes
Java	1024 bytes
Swift	512 bytes
Objective-C	512 bytes

이 기본값은 일반 전송을 시작하기에 적합하지만, 모든 BLE 디바이스의 최적값이라는 뜻은 아닙니다. 패킷 손실, 쓰기 실패, 인쇄가 중간에 끊기는 문제가 있으면 먼저 디바이스 최대 쓰기 길이, 플랫폼 write API 제한, BLE credit 필요 여부를 확인하세요.

BLE MTU

BLE의 MTU는 ATT 데이터 한 패킷의 상한이지, 애플리케이션이 임의로 쓸 수 있는 전체 비즈니스 데이터 크기가 아닙니다. 보수적인 시작값은 20 bytes입니다. 플랫폼이나 디바이스가 MTU를 협상했다면 NIB의 BLE helper는 보통 ATT header가 3 bytes를 차지하므로 mtu - 3을 payload 크기로 사용합니다.

예를 들어 협상된 MTU가 185라면 권장 payload는 182 bytes입니다. 이 경우에도 여전히 “분할 쓰기”이며, 분할 크기가 일반 기본값이 아니라 BLE MTU에서 온다는 차이만 있습니다.

BLE Credit

일부 BLE 프린터는 애플리케이션의 연속 쓰기를 허용하지 않습니다. 디바이스가 notify로 SDK에 현재 몇 패킷을 더 쓸 수 있는지 알려주고, SDK는 credit 하나를 소비해 chunk 하나를 씁니다. credit이 소진되면 다음 알림을 기다립니다.

NIB에는 현재 두 가지 credit 전략이 있으며, 앞으로 새 전략이나 디바이스 Family 전용 전략이 추가될 수 있습니다.

전략	메커니즘	적합한 경우
lane-credit	디바이스의 credit notify를 읽습니다. 알림은 MTU와 쓰기 가능 credit을 동시에 갱신할 수 있습니다. payload chunk 하나를 쓸 때마다 credit 하나를 소비합니다.	디바이스에 고정된 read/notify/credit 특성값이 있고, credit 알림이 주 쓰기 채널 용량을 나타내는 경우.
signal-credit	전용 signal/credit 알림으로 쓰기를 제어합니다. MTU 알림은 별도로 도착할 수 있고, credit 알림이 도착한 뒤에야 실제 쓰기를 허용합니다.	디바이스가 “신호”와 일반 읽기 응답을 분리하거나, 전용 신호 특성값으로 리듬을 제어해야 하는 경우.

lane-credit의 기본 BLE credit 시작점은 보통 “유효한 알림을 관찰한 뒤 credit에 따라 쓰기”에 더 적합합니다. signal-credit의 기본 credit은 0이며, 양수 credit 알림을 기다려야 씁니다. 연동 시 service UUID, 쓰기 특성값, 읽기/알림 특성값, credit 특성값, MTU 형식, credit 알림 형식을 확인해야 합니다.

fallback / fail / bypass-write

Credit 모드에서 가장 흔한 문제는 애플리케이션이 credit을 켰지만 디바이스가 예상대로 notify를 보내지 않는 경우입니다. NIB는 이 상황을 두 가지 방식으로 처리합니다.

모드	동작
fail	credit을 기다리지 못하면 바로 실패시키고, 쓰기 또는 BLE credit 타임아웃으로 노출합니다. 정식 연동과 엄격한 검증에 적합합니다.
bypass-write	credit이 활성화되지 않았거나 대기 타임아웃이 발생하면 credit을 우회하고 남은 데이터를 일반 쓰기 경로로 보냅니다. 연동 디버깅, 호환성 테스트, 실제로 디바이스가 credit을 필요로 하지 않는지 확인할 때 적합합니다.

bypass-write를 장기 기본값으로 두지 마세요. “디바이스가 credit 없이도 인쇄되는가”를 판단하는 데는 도움이 되지만, 디바이스가 실제로 credit에 의존한다면 우회 후에도 패킷 손실, 멈춤, 부분 인쇄가 발생할 수 있습니다.

선택 방법

단순한 것에서 복잡한 것으로 선택하세요.

1. USB, 네트워크, 클래식 블루투스 등 안정적인 스트림 전송: 먼저 SDK 기본 일반 분할을 사용합니다.
2. BLE지만 디바이스 전용 요구사항이 없음: 보수적 20 bytes를 먼저 사용하거나, 플랫폼이 제공하는 maximum write length를 사용합니다.
3. BLE에서 MTU 협상 완료: mtu - 3을 payload 분할 크기로 사용합니다.
4. BLE 문서나 패킷 캡처에서 credit notify가 확인됨: 디바이스 프로토콜에 따라 lane-credit 또는 signal-credit을 활성화합니다.
5. credit 필요 여부가 불확실함: 연동 단계에서는 짧게 bypass-write로 비교할 수 있습니다. 정식 출시 전에는 명확한 credit 전략 또는 일반 분할 전략으로 바꿔야 합니다.

“짧은 텍스트는 정상이고 큰 이미지나 긴 라벨은 실패”한다면 보통 명령어 생성 문제가 아니라 분할, MTU, credit 또는 플랫폼 쓰기 모드가 디바이스와 맞지 않는 문제입니다.