연동 전 확인의 목표는 “이 장비가 실제로 어떻게 인쇄하는지”를 명확히 하는 것입니다. NIB SDK는 명령어를 만들고, connected device에 쓰고, 필요할 때 응답을 읽습니다. 하지만 장비가 어떤 Family에 속하는지, 어떤 명령어를 지원하는지, 현재 BLE에서 어떤 characteristic에 써야 하는지는 자동 판단하지 않습니다.

정보를 일찍 확인할수록 빠른 시작을 한 번에 성공시키기 쉽습니다.

디바이스 정보

항목	확인할 내용
디바이스 모델	모델, 하드웨어 버전, 커스텀 펌웨어 여부, Boxliy, Aryten, Lin8inch 중 어느 Family에 속하는지.
명령어 지원	장비가 ESC, TSPL, CPCL 중 무엇을 지원하는지. SDK 패키지 이름으로 장비 기능을 역추론하지 마세요.
용지 사양	영수증 용지 폭, 라벨 크기, 간격, 블랙마크, 연속지, 커터 또는 박리 필요 여부.
인코딩 요구사항	텍스트에 GBK, UTF-8 또는 다른 codepage가 필요한지. 중국어 인쇄는 특히 확인해야 합니다.
이미지/래스터	이미지, Logo, 서명 또는 래스터 콘텐츠를 인쇄해야 하는지. 이미지 처리는 NIB의 image/raster 기본 기능을 기반으로 합니다.
상태 기능	용지 없음, 커버 열림, 배터리, 펌웨어 버전, 시리얼 번호 등을 읽어야 하는지, 그리고 장비가 실제로 해당 질의를 지원하는지.
인쇄 파라미터	속도, 농도, 방향, 매수, 라벨 시작점 등 비즈니스 기본값.

어떤 명령어를 선택할지는 실제 장비 지원을 기준으로 해야 합니다. 일부 장비는 특정 명령어 집합만 지원합니다. 장비 지원 목록은 개발자, 하드웨어 담당자 또는 고객지원에 확인하세요.

연결 정보

연결	확인할 내용
BLE	service UUID, 쓰기 characteristic, 읽기/알림 characteristic, MTU 또는 최대 쓰기 길이, write with response 여부, credit/알림 리듬 여부.
클래식 블루투스	페어링 방식, 시스템 권한, socket 동작, 쓰기 블로킹, 연결 끊김 복구.
USB / WebUSB	브라우저 또는 플랫폼 권한, vendor/product 필터링, interface, endpoint, 사용자 수동 디바이스 선택 필요 여부.
네트워크	host, port, 연결 타임아웃, 쓰기 타임아웃, 재연결과 재시도 전략.
미니프로그램/크로스엔드 브리지	플랫폼 API 이름, 권한 팝업 시점, 디바이스 ID 수명주기, 백그라운드/포그라운드 전환 후 연결 상태.

연결 계층이 최종적으로 만들어야 하는 것은 connected device이지, 인쇄 템플릿이 직접 호출할 플랫폼 원시 객체가 아닙니다.

애플리케이션 요구사항

항목	확인할 내용
대상 플랫폼	TypeScript, Dart, Java, Objective-C, Swift 중 실제로 전달할 언어.
인쇄 내용	영수증, 라벨, 바코드, QR 코드, 이미지, 배치 작업인지, 또는 단순 텍스트만 인쇄하는지.
세션 전략	인쇄 전에 임시 연결할지, 연결을 유지할지, 실패 후 자동 재시도할지.
상태 읽기	인쇄 전/후 상태 읽기가 필수인지, 응답이 없을 때 비즈니스에서 어떻게 처리할지.
로그 요구사항	연결, 바이트 길이, 분할 진행률, 상태 응답, 오류 원인을 기록할지.
오프라인 기능	인쇄 작업을 캐시할지, 연결 복구 후 어떻게 보충 인쇄할지.

이 정보에 따라 SDK 연동 시 언어 페이지, 연결 페이지, 흐름 제어와 상태 읽기 페이지 중 무엇을 먼저 봐야 할지가 결정됩니다.

흔한 증상

빠졌거나 잘못된 사실	흔한 증상	다음 단계
명령어 계열 선택 오류	디바이스에 쓰기는 되지만 인쇄하지 않거나 원시 명령 텍스트가 출력됩니다.	디바이스 자료로 돌아가 장비가 ESC, TSPL, CPCL 중 무엇을 지원하는지 확인합니다.
용지 사양 오류	라벨 위치가 밀리거나, 절반만 인쇄되거나, 연속 배출되거나, black mark/gap 위치 잡기에 실패합니다.	용지 폭, 라벨 높이, gap/black mark/continuous 설정을 확인합니다.
BLE characteristic 오류	연결은 성공하지만 쓰기에 실패하거나, 쓰기 성공 후 아무 반응이 없습니다.	service, write, read/notify characteristic을 대조하고, 다른 characteristic 자동 선택을 허용할지 확인합니다.
분할 크기 과대	작은 데이터는 인쇄되지만 큰 템플릿이나 이미지가 실패합니다.	MTU 또는 플랫폼 최대 쓰기 길이에 따라 chunk size를 설정합니다.
인코딩 불일치	영어는 정상이고 중국어는 깨지거나 누락됩니다.	장비 codepage를 확인하고 대응하는 빌더/인코딩 설정을 선택합니다.
상태 기능 미지원	질의가 타임아웃되거나 응답을 파싱할 수 없습니다.	장비와 현재 명령어 계열이 해당 상태 질의를 지원하는지 확인합니다.