boot-cdc-scanner

안드로이드용 USB-CDC 바코드 스캐너 Expo Native Module입니다.

CDC-ACM 시리얼 포트로 열거되는 모든 스캐너(Zebra DS9208 USB CDC, Newland NLS-FM431 USB CDC, 그 외 표준 CDC-ACM 스캐너)를 라인 단위로 읽습니다.

iOS는 미지원(스텁만 있음). 웹은 no-op.

설치

npm install boot-cdc-scanner
# 또는
yarn add boot-cdc-scanner

Expo Config Plugin은 필요 없습니다. 라이브러리의 AndroidManifest.xml에 선언된 <uses-feature android:name="android.hardware.usb.host"/>가 앱 매니페스트에 자동 병합됩니다. 장치별 권한은 런타임에 안드로이드 시스템 다이얼로그로 요청합니다.

Gradle (jitpack 저장소)

의존 라이브러리 usb-serial-for-android는 jitpack에 호스팅됩니다. 앱의 settings.gradle에 jitpack 저장소가 없다면 아래를 추가하세요.

dependencyResolutionManagement {
  repositories {
    maven { url 'https://jitpack.io' }
  }
}

사용 예

스캐너 사용은 검색 → 권한 요청 → 연결 → 사용의 단계로 분리되어 있습니다.

import {
  listDevices, requestDevicePermission, connectDevice, disconnect,
  enableScanner, disableScanner, setStatus, beep,
  getConnectedScanner,
  addBarcodeListener, addStateListener, addErrorListener, addDevicesChangedListener,
} from 'boot-cdc-scanner';

useEffect(() => {
  const s1 = addBarcodeListener(e => console.log('scan', e.code));
  const s2 = addStateListener(e => console.log('state', e.state));
  const s3 = addErrorListener(e => console.warn('err', e.code, e.message));
  const s4 = addDevicesChangedListener(e => console.log('devices', e.devices));

  (async () => {
    const devices = await listDevices();
    const target = devices[0];
    if (!target) return;
    if (!target.hasPermission) {
      const result = await requestDevicePermission(target.id);
      if (result === 'denied') return;
    }
    await connectDevice(target.id);
    await enableScanner();
  })();

  return () => {
    s1.remove(); s2.remove(); s3.remove(); s4.remove();
    disableScanner();
    disconnect();
  };
}, []);

API

검색 / 연결

• listDevices() — 연결 가능한 CDC 스캐너 목록 반환(id, vid, pid, name, hasPermission, permissionDenied).
• requestDevicePermission(id) — 안드로이드 USB 권한 다이얼로그 요청. 결과는 'granted' | 'denied' | 'already'.
• connectDevice(id) — 선택한 디바이스에 연결(상태 CONNECTED).
• disconnect() — 연결 해제(상태 DISCONNECTED).
• getConnectedScanner() — 현재 연결된 어댑터 정보 또는 null.

사용

• enableScanner() — 바코드 이벤트 수신 시작(상태 READY).
• disableScanner() — 수신 중지(상태 DISABLED). HW는 제어하지 않고 앱 레벨에서 이벤트를 드롭.
• setStatus('READY' | 'PROCESSING' | 'DISABLED') — 드롭 방식의 상태 제어.
  • PROCESSING은 "계속 읽되 이벤트는 올리지 않음". 앱이 한 건 처리 중일 때 사용. 다시 받으려면 setStatus('READY').
• beep(tone?) — BEL(0x07) 송신 시도(지원 스캐너 한정).

이벤트

• onBarcodeScanned — 바코드 수신(addBarcodeListener).
• onScannerStateChanged — 상태 변화(DISCONNECTED | CONNECTED | READY | PROCESSING | DISABLED, addStateListener).
• onError — 에러(addErrorListener).
• onDevicesChanged — USB 디바이스 연결/해제 변화(addDevicesChangedListener).

CDC 전용 어댑터는 호스트→스캐너 제어 명령을 보내지 않습니다. 스캐너 LED/Aim은 항상 켜져 있고, 스캔 억제는 앱 레벨 드롭으로 처리됩니다.

장치 준비

각 스캐너를 USB CDC(USB Virtual COM) 모드로 전환한 뒤 연결하세요.

• Zebra DS9208: DS9208 Product Reference Guide 6장의 "USB CDC Host" 설정 바코드 스캔 → VID=0x05E0, PID=0x1701.
• Newland NLS-FM431: 유저 가이드의 "USB CDC" 설정 바코드(@INTERF8)를 @SETUPE1/@SETUPE0 사이에 스캔 → VID=0x1EAB, PID=0x0006.
• 그 외 CDC-ACM 모드를 지원하는 스캐너는 usbClass: "CDC_ACM" 매칭으로 자동 인식됩니다.

추가 디바이스는 android/src/main/res/raw/device_profiles.json에 매칭 규칙(VID/PID 또는 usbClass: "CDC_ACM")을 넣어 등록할 수 있습니다.

(선택) USB 연결 시 앱 자동 실행

스캐너를 꽂을 때 앱이 자동으로 포어그라운드로 올라오길 원하면, 사용처 앱의 AndroidManifest.xml에 직접 아래를 추가하세요(라이브러리가 자동으로 주입하지 않습니다).

<activity ...>
  <intent-filter>
    <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"/>
  </intent-filter>
  <meta-data
    android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
    android:resource="@xml/device_filter"/>
</activity>

Example 앱

example/ 디렉토리에 실장비 수동 테스트용 앱이 있습니다. 포함된 화면:

• 연결 상태 배지, 어댑터/VID/PID 표시
• enableScanner / disableScanner / setStatus / beep 버튼
• IME 우회 회귀 검증용 TextInput
• 이벤트/에러 로그 리스트