boot-welcome-usb 0.1.0

package/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  root: true,
+  extends: ['universe/native', 'universe/web'],
+  ignorePatterns: ['build'],
+};

package/README.md

@@ -0,0 +1,241 @@
+# boot-welcome-usb
+
+Android AOA(Android Open Accessory) 프로토콜을 통해 USB로 연결된 Mac/PC와 통신하는 Expo Native Module.
+
+## 개요
+
+WelcomeUSBFront 기능에서 사용되며, Android 태블릿(Accessory)이 Mac의 EventBoot-Desktop(Host)과 USB 케이블을 통해 QR 코드 접수 데이터를 주고받습니다.
+
+```
+Android 태블릿 (이 모듈)  ──USB 케이블──  Mac (eventboot-desktop)
+      Accessory 모드                        Host 모드
+```
+
+## 프로젝트 구조
+
+```
+boot-welcome-usb/
+├── android/
+│   ├── build.gradle
+│   └── src/main/java/net/eventboot/welcomeusb/
+│       ├── BootWelcomeUsbModule.kt      # Expo Module 정의
+│       ├── AoaAccessoryManager.kt       # USB Accessory 연결 관리
+│       └── AoaProtocol.kt              # 메시지 프레이밍
+├── src/
+│   ├── index.ts                         # 모듈 export
+│   ├── BootWelcomeUsb.types.ts         # TypeScript 타입
+│   ├── BootWelcomeUsbModule.ts         # 네이티브 모듈 바인딩
+│   └── useUsbAoa.ts                    # React Hook
+├── example/                            # 테스트용 예제 앱
+├── build/                              # TypeScript 빌드 산출물
+├── expo-module.config.json
+└── package.json
+```
+
+## 개발 환경 설정
+
+### 모듈 빌드
+
+```bash
+cd modules/boot-welcome-usb
+
+# TypeScript 빌드
+npm run build
+
+# 빌드 산출물 삭제
+npm run clean
+
+# 린트
+npm run lint
+```
+
+### example 앱 실행
+
+```bash
+cd modules/boot-welcome-usb/example
+
+npm install
+npx expo run:android
+```
+
+> example 앱은 `package.json`의 `expo.autolinking.nativeModulesDir` 설정으로 상위 모듈을 자동 인식합니다.
+
+## eventboot 프로젝트에서 사용하기
+
+### 1. 의존성 등록
+
+`package.json` (프로젝트 루트)에 로컬 경로로 추가:
+
+```json
+{
+  "dependencies": {
+    "boot-welcome-usb": "./modules/boot-welcome-usb"
+  }
+}
+```
+
+```bash
+npm install
+```
+
+### 2. Config Plugin 등록
+
+`app.json`의 `plugins` 배열에 AOA Config Plugin이 등록되어 있어야 합니다:
+
+```json
+{
+  "plugins": [
+    "./plugins/withAndroidAoaAccessory"
+  ]
+}
+```
+
+이 플러그인은 Android Manifest에 USB Accessory 관련 설정을 자동으로 추가합니다.
+
+### 3. 네이티브 빌드
+
+Expo Native Module이므로 **네이티브 빌드가 필요**합니다. Expo Go에서는 동작하지 않습니다.
+
+```bash
+# 개발 빌드
+eas build --profile development --platform android
+
+# 또는 로컬 빌드
+npx expo run:android
+```
+
+## API 사용법
+
+### 기본 함수
+
+```typescript
+import BootWelcomeUsbModule, {
+  getConnectionState,
+  requestPermission,
+  sendData,
+  addListener,
+} from 'boot-welcome-usb';
+
+// 연결 상태 확인
+const state = await getConnectionState();
+// 'DISCONNECTED' | 'CONNECTED' | 'AOA_SWITCHING' | 'AOA_READY' | 'ERROR'
+
+// USB 권한 요청
+const granted = await requestPermission();
+
+// 데이터 전송 (JSON 문자열)
+const success = await sendData(JSON.stringify({
+  id: 'uuid-123',
+  type: 'REQUEST',
+  path: '/scan',
+  body: JSON.stringify({ qrcode: 'TICKET-001' }),
+}));
+```
+
+### 이벤트 리스너
+
+```typescript
+import { addListener } from 'boot-welcome-usb';
+
+// 연결 상태 변경
+const sub1 = addListener('onConnectionStateChanged', (event) => {
+  console.log('상태:', event.state, event.message);
+});
+
+// 데이터 수신 (Host로부터 응답)
+const sub2 = addListener('onDataReceived', (event) => {
+  const message = JSON.parse(event.messageJson);
+  console.log('수신:', message);
+});
+
+// 에러
+const sub3 = addListener('onError', (event) => {
+  console.error('에러:', event.code, event.message);
+});
+
+// 정리
+sub1.remove();
+sub2.remove();
+sub3.remove();
+```
+
+### React Hook
+
+```typescript
+import { useUsbAoa } from 'boot-welcome-usb';
+
+function MyComponent() {
+  const { connectionState, isConnected } = useUsbAoa();
+
+  return <Text>{isConnected ? '연결됨' : '미연결'}</Text>;
+}
+```
+
+### useWelcomeUSBFront Hook (앱 내부)
+
+실제 WelcomeUSBFront 화면에서는 이 훅을 사용합니다. 기존 HTTP 방식과 동일한 `WelcomeDeskApiResult`를 반환합니다:
+
+```typescript
+import { useWelcomeUSBFront } from '@/hooks/welcome/useWelcomeUSBFront';
+
+function WelcomeUSBScreen() {
+  const { connectionState, isConnected, sendQRCode, requestPermission } = useWelcomeUSBFront();
+
+  const handleScan = async (qrcode: string) => {
+    const result = await sendQRCode(qrcode);
+    // result: { customer, receptionResult, isError, errorMessage }
+  };
+}
+```
+
+## 통신 프로토콜
+
+### 메시지 프레이밍
+
+USB 스트림은 메시지 경계가 없으므로 Length-Prefix 프레이밍을 사용합니다:
+
+```
++-------------------+------------------------+
+| Length (4 bytes)  | JSON Payload (N bytes) |
+| Big-Endian uint32 | UTF-8 encoded          |
++-------------------+------------------------+
+```
+
+### 메시지 형식
+
+```typescript
+interface AoaMessage {
+  id: string;      // UUID (요청-응답 매칭)
+  type: 'REQUEST' | 'RESPONSE' | 'PING' | 'PONG';
+  path: string;    // "/scan", "/ping"
+  body?: string;   // JSON 문자열
+}
+```
+
+### 요청/응답 예시
+
+**QR 스캔 요청** (Android → Mac):
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "type": "REQUEST",
+  "path": "/scan",
+  "body": "{\"qrcode\":\"TICKET-12345\"}"
+}
+```
+
+**QR 스캔 응답** (Mac → Android):
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "type": "RESPONSE",
+  "path": "/scan",
+  "body": "{\"data\":{\"customer\":{\"name\":\"홍길동\"},\"receptionResult\":\"OK_IN\"}}"
+}
+```
+
+## 테스트 환경
+
+- **Android 에뮬레이터**: USB Accessory 테스트 불가. **실기기 필수**.
+- **ADB 충돌**: AOA 모드 전환 시 ADB 연결이 끊어질 수 있음. `adb kill-server` 후 테스트 권장.
+- **Mac에서 EventBoot-Desktop 실행 필수**: USB Host 역할을 하는 `modules/eventboot-desktop` Electron 앱이 Mac에서 실행 중이어야 함.

package/android/build.gradle

@@ -0,0 +1,18 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'net.eventboot.welcomeusb'
+version = '0.1.0'
+
+android {
+  namespace "net.eventboot.welcomeusb"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/net/eventboot/welcomeusb/AoaAccessoryManager.kt

@@ -0,0 +1,315 @@
+package net.eventboot.welcomeusb
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbAccessory
+import android.hardware.usb.UsbManager
+import android.os.Build
+import android.os.ParcelFileDescriptor
+import android.util.Log
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.io.IOException
+
+private const val TAG = "BootWelcomeUsb.Manager"
+
+/**
+ * USB Accessory(AOA) 연결 수명주기를 관리하는 클래스.
+ *
+ * 주요 역할:
+ * - USB Accessory 연결/분리 BroadcastReceiver 등록 및 처리
+ * - USB 권한 요청 및 Accessory 열기
+ * - 백그라운드 스레드에서 수신 데이터를 읽어 MessageBuffer로 조립
+ * - Length-Prefix 프레이밍 프로토콜로 데이터 전송
+ *
+ * 연결 상태 흐름:
+ *   DISCONNECTED → (권한 획득) → CONNECTED → (스트림 열기) → AOA_READY
+ *   AOA_READY → (케이블 분리/에러) → DISCONNECTED
+ *
+ * @param context Android Context (BroadcastReceiver 등록 및 UsbManager 접근에 사용)
+ * @param onConnectionStateChanged 연결 상태 변경 콜백 (state, message)
+ * @param onDataReceived 완성된 JSON 메시지 수신 콜백
+ * @param onError 에러 발생 콜백 (code, message)
+ */
+class AoaAccessoryManager(
+    private val context: Context,
+    private val onConnectionStateChanged: (String, String?) -> Unit,
+    private val onDataReceived: (String) -> Unit,
+    private val onError: (String, String) -> Unit
+) {
+    private var usbManager: UsbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+    private var fileDescriptor: ParcelFileDescriptor? = null
+    private var inputStream: FileInputStream? = null
+    private var outputStream: FileOutputStream? = null
+    private var readThread: Thread? = null
+    private var isRunning = false
+
+    /** 수신 바이트를 버퍼링하여 Length-Prefix 메시지로 조립 */
+    private val messageBuffer = MessageBuffer()
+
+    companion object {
+        /** USB 권한 요청 시 사용하는 커스텀 Broadcast Action */
+        const val ACTION_USB_PERMISSION = "net.eventboot.welcomeusb.USB_PERMISSION"
+    }
+
+    /**
+     * USB Accessory 분리 및 권한 응답을 수신하는 BroadcastReceiver.
+     * - ACTION_USB_ACCESSORY_DETACHED: 케이블 분리 시 연결 해제
+     * - ACTION_USB_PERMISSION: 권한 요청 결과 수신 후 Accessory 열기
+     */
+    private val usbReceiver = object : BroadcastReceiver() {
+        override fun onReceive(context: Context, intent: Intent) {
+            when (intent.action) {
+                UsbManager.ACTION_USB_ACCESSORY_DETACHED -> {
+                    Log.d(TAG, "BroadcastReceiver: USB Accessory 분리됨")
+                    closeAccessory()
+                    onConnectionStateChanged("DISCONNECTED", "USB accessory detached")
+                }
+                ACTION_USB_PERMISSION -> {
+                    val granted = intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
+                    Log.d(TAG, "BroadcastReceiver: 권한 응답 granted=$granted")
+                    if (granted) {
+                        // Android 13(TIRAMISU)부터 타입 안전한 getParcelableExtra 사용
+                        val accessory = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                            intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY, UsbAccessory::class.java)
+                        } else {
+                            @Suppress("DEPRECATION")
+                            intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY)
+                        }
+                        accessory?.let { openAccessory(it) }
+                    } else {
+                        onError("PERMISSION_DENIED", "USB permission denied")
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * BroadcastReceiver를 등록한다.
+     * 모듈 생성(OnCreate) 시 호출된다.
+     */
+    fun register() {
+        Log.d(TAG, "register: BroadcastReceiver 등록")
+        val filter = IntentFilter().apply {
+            addAction(UsbManager.ACTION_USB_ACCESSORY_DETACHED)
+            addAction(ACTION_USB_PERMISSION)
+        }
+        // USB 권한 응답(ACTION_USB_PERMISSION)은 시스템에서 보내므로 RECEIVER_EXPORTED 필요
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            context.registerReceiver(usbReceiver, filter, Context.RECEIVER_EXPORTED)
+        } else {
+            context.registerReceiver(usbReceiver, filter)
+        }
+    }
+
+    /**
+     * BroadcastReceiver를 해제하고 USB 연결을 닫는다.
+     * 모듈 소멸(OnDestroy) 시 호출된다.
+     */
+    fun unregister() {
+        Log.d(TAG, "unregister: BroadcastReceiver 해제 및 연결 정리")
+        try { context.unregisterReceiver(usbReceiver) } catch (_: Exception) {}
+        closeAccessory()
+    }
+
+    /**
+     * 현재 USB 연결 상태를 문자열로 반환한다.
+     * - "AOA_READY": 스트림이 열려 있고 읽기 스레드가 동작 중 (데이터 송수신 가능)
+     * - "CONNECTED": FileDescriptor만 열린 상태
+     * - "DISCONNECTED": 연결 없음
+     */
+    fun getConnectionState(): String {
+        return when {
+            outputStream != null && isRunning -> "AOA_READY"
+            fileDescriptor != null -> "CONNECTED"
+            else -> "DISCONNECTED"
+        }
+    }
+
+    /**
+     * 연결된 USB Accessory를 탐색하여 권한이 있으면 바로 열고,
+     * 없으면 권한을 요청한다.
+     * @return Accessory를 성공적으로 열었으면 true
+     */
+    fun checkAndOpenAccessory(): Boolean {
+        val accessories = usbManager.accessoryList
+        Log.d(TAG, "checkAndOpenAccessory: 연결된 Accessory 수=${accessories?.size ?: 0}")
+        if (accessories.isNullOrEmpty()) {
+            onConnectionStateChanged("DISCONNECTED", "No USB accessory found")
+            return false
+        }
+        val accessory = accessories[0]
+        Log.d(TAG, "checkAndOpenAccessory: manufacturer=${accessory.manufacturer}, model=${accessory.model}")
+        if (usbManager.hasPermission(accessory)) {
+            Log.d(TAG, "checkAndOpenAccessory: 권한 있음, Accessory 열기")
+            openAccessory(accessory)
+            return true
+        } else {
+            Log.d(TAG, "checkAndOpenAccessory: 권한 없음, 권한 요청")
+            requestPermission(accessory)
+            return false
+        }
+    }
+
+    /**
+     * USB Accessory 접근 권한을 시스템에 요청한다.
+     * 결과는 usbReceiver의 ACTION_USB_PERMISSION으로 수신된다.
+     * @param accessory 권한을 요청할 Accessory (null이면 첫 번째 연결된 Accessory 사용)
+     */
+    /**
+     * 실제 USB 연결이 유효한지 FileDescriptor를 검증한다.
+     * outputStream/isRunning 플래그만으로는 스트림이 깨진 상태를 감지할 수 없으므로,
+     * FileDescriptor.valid()로 실제 OS 레벨 유효성을 확인한다.
+     */
+    private fun isConnectionAlive(): Boolean {
+        val fd = fileDescriptor?.fileDescriptor ?: return false
+        return fd.valid() && outputStream != null && isRunning
+    }
+
+    fun requestPermission(accessory: UsbAccessory? = null) {
+        if (isConnectionAlive()) {
+            Log.d(TAG, "requestPermission: 연결이 유효하므로 무시")
+            return
+        }
+        // 상태값은 AOA_READY이지만 실제 연결이 깨진 경우 정리 후 재연결
+        if (fileDescriptor != null || isRunning) {
+            Log.d(TAG, "requestPermission: 유효하지 않은 연결 정리 후 재연결")
+            closeAccessory()
+        }
+        val target = accessory ?: usbManager.accessoryList?.firstOrNull()
+        if (target == null) {
+            Log.w(TAG, "requestPermission: Accessory를 찾을 수 없음")
+            onError("NO_ACCESSORY", "No USB accessory found")
+            return
+        }
+        Log.d(TAG, "requestPermission: 권한 요청 (${target.manufacturer} ${target.model})")
+        // Android 12(S)부터 PendingIntent에 mutability 플래그 필수
+        val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            PendingIntent.FLAG_MUTABLE
+        } else {
+            0
+        }
+        val intent = Intent(ACTION_USB_PERMISSION).apply { setPackage(context.packageName) }
+        val permissionIntent = PendingIntent.getBroadcast(context, 0, intent, flags)
+        usbManager.requestPermission(target, permissionIntent)
+    }
+
+    /**
+     * USB Accessory를 열어 입출력 스트림을 생성하고 읽기 스레드를 시작한다.
+     * 성공 시 상태가 AOA_READY로 전환된다.
+     */
+    private fun openAccessory(accessory: UsbAccessory) {
+        try {
+            Log.d(TAG, "openAccessory: ${accessory.manufacturer} ${accessory.model}")
+            onConnectionStateChanged("CONNECTED", "Opening accessory: ${accessory.manufacturer} ${accessory.model}")
+            fileDescriptor = usbManager.openAccessory(accessory)
+            if (fileDescriptor == null) {
+                Log.e(TAG, "openAccessory: FileDescriptor가 null")
+                onError("OPEN_FAILED", "Failed to open USB accessory")
+                onConnectionStateChanged("ERROR", "Failed to open accessory")
+                return
+            }
+            val fd = fileDescriptor!!.fileDescriptor
+            inputStream = FileInputStream(fd)
+            outputStream = FileOutputStream(fd)
+            Log.d(TAG, "openAccessory: 스트림 생성 완료, 읽기 스레드 시작")
+            startReading()
+            onConnectionStateChanged("AOA_READY", "USB accessory connected and ready")
+        } catch (e: Exception) {
+            Log.e(TAG, "openAccessory: 에러 발생", e)
+            onError("OPEN_ERROR", "Error opening accessory: ${e.message}")
+            onConnectionStateChanged("ERROR", e.message)
+            closeAccessory()
+        }
+    }
+
+    /**
+     * 백그라운드 데몬 스레드에서 USB InputStream을 지속적으로 읽는다.
+     * 수신된 바이트는 MessageBuffer에 누적되며, 완성된 메시지가 있으면 콜백으로 전달한다.
+     * 연결이 끊어지면(bytesRead < 0 또는 IOException) 루프를 종료하고 정리한다.
+     */
+    private fun startReading() {
+        isRunning = true
+        Log.d(TAG, "startReading: 읽기 스레드 시작")
+        readThread = Thread {
+            val buffer = ByteArray(16384)
+            while (isRunning) {
+                try {
+                    val bytesRead = inputStream?.read(buffer) ?: -1
+                    if (bytesRead > 0) {
+                        Log.d(TAG, "read: ${bytesRead}바이트 수신")
+                        // 수신 바이트를 MessageBuffer에 누적
+                        messageBuffer.feed(buffer, 0, bytesRead)
+                        // 완성된 메시지를 모두 추출하여 전달
+                        var message = messageBuffer.poll()
+                        while (message != null) {
+                            Log.d(TAG, "read: 완성된 메시지 전달 (${message.length}자)")
+                            onDataReceived(message)
+                            message = messageBuffer.poll()
+                        }
+                    } else if (bytesRead < 0) {
+                        Log.d(TAG, "read: EOF 수신, 루프 종료")
+                        break
+                    }
+                } catch (e: IOException) {
+                    if (isRunning) {
+                        Log.e(TAG, "read: IOException 발생", e)
+                        onError("READ_ERROR", "Read error: ${e.message}")
+                    }
+                    break
+                }
+            }
+            // 외부에서 중지한 게 아니라면 연결 해제 처리
+            if (isRunning) {
+                Log.d(TAG, "read: 연결 해제 처리")
+                closeAccessory()
+                onConnectionStateChanged("DISCONNECTED", "Connection lost")
+            }
+        }.apply {
+            name = "AoaReadThread"
+            isDaemon = true
+            start()
+        }
+    }
+
+    /**
+     * Length-Prefix 프레이밍으로 JSON 메시지를 USB Host(Mac)에 전송한다.
+     * @param json 전송할 JSON 문자열
+     * @return 전송 성공 여부
+     */
+    fun sendData(json: String): Boolean {
+        return try {
+            val encoded = AoaProtocol.encodeMessage(json)
+            Log.d(TAG, "sendData: ${encoded.size}바이트 전송 시도")
+            outputStream?.write(encoded)
+            outputStream?.flush()
+            Log.d(TAG, "sendData: 전송 완료")
+            true
+        } catch (e: IOException) {
+            Log.e(TAG, "sendData: 전송 실패", e)
+            onError("WRITE_ERROR", "Write error: ${e.message}")
+            false
+        }
+    }
+
+    /**
+     * USB 연결 관련 리소스를 모두 해제한다.
+     * 읽기 스레드 중지 → 입출력 스트림 닫기 → FileDescriptor 닫기 순서로 정리.
+     */
+    fun closeAccessory() {
+        Log.d(TAG, "closeAccessory: 리소스 해제 시작")
+        isRunning = false
+        try { readThread?.interrupt() } catch (_: Exception) {}
+        readThread = null
+        try { inputStream?.close() } catch (_: Exception) {}
+        inputStream = null
+        try { outputStream?.close() } catch (_: Exception) {}
+        outputStream = null
+        try { fileDescriptor?.close() } catch (_: Exception) {}
+        fileDescriptor = null
+    }
+}

package/android/src/main/java/net/eventboot/welcomeusb/AoaProtocol.kt

@@ -0,0 +1,125 @@
+package net.eventboot.welcomeusb
+
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * USB AOA 통신에 사용되는 Length-Prefix 프레이밍 프로토콜.
+ *
+ * USB 스트림은 TCP/IP와 달리 메시지 경계가 없으므로,
+ * 각 메시지 앞에 4바이트 길이 헤더를 붙여 수신 측에서 메시지 경계를 식별한다.
+ *
+ * 프레임 구조:
+ * +-------------------+------------------------+
+ * | Length (4 bytes)  | JSON Payload (N bytes) |
+ * | Big-Endian uint32 | UTF-8 encoded          |
+ * +-------------------+------------------------+
+ */
+object AoaProtocol {
+    /**
+     * JSON 문자열을 Length-Prefix 프레임으로 인코딩한다.
+     * @param json 인코딩할 JSON 문자열
+     * @return [4바이트 Big-Endian 길이][JSON UTF-8 바이트] 형태의 바이트 배열
+     */
+    fun encodeMessage(json: String): ByteArray {
+        val jsonBytes = json.toByteArray(Charsets.UTF_8)
+        val buffer = ByteBuffer.allocate(4 + jsonBytes.size)
+        buffer.order(ByteOrder.BIG_ENDIAN)
+        buffer.putInt(jsonBytes.size)
+        buffer.put(jsonBytes)
+        return buffer.array()
+    }
+}
+
+/**
+ * 부분 읽기(partial read)를 버퍼링하여 완성된 메시지를 추출하는 클래스.
+ *
+ * USB 스트림에서 read()가 반환하는 바이트 수는 메시지 단위와 무관하므로,
+ * 수신 바이트를 내부 버퍼에 누적한 뒤 Length-Prefix 헤더를 파싱하여
+ * 완성된 메시지만 추출한다.
+ *
+ * 사용 패턴:
+ * ```
+ * val buffer = MessageBuffer()
+ * buffer.feed(receivedBytes, 0, bytesRead)
+ * var msg = buffer.poll()
+ * while (msg != null) {
+ *     processMessage(msg)
+ *     msg = buffer.poll()
+ * }
+ * ```
+ */
+class MessageBuffer {
+    /** 초기 64KB, 필요 시 자동 확장되는 내부 버퍼 */
+    private var buffer = ByteBuffer.allocate(65536).apply {
+        order(ByteOrder.BIG_ENDIAN)
+    }
+
+    /** 현재 버퍼에 쓰여진 바이트 수 (다음 쓰기 위치) */
+    private var writePosition = 0
+
+    /**
+     * 수신된 데이터를 내부 버퍼에 추가한다.
+     * 버퍼 용량이 부족하면 자동으로 2배 확장한다.
+     */
+    fun feed(data: ByteArray, offset: Int, length: Int) {
+        ensureCapacity(length)
+        System.arraycopy(data, offset, buffer.array(), writePosition, length)
+        writePosition += length
+    }
+
+    /**
+     * 버퍼에서 완성된 메시지 하나를 추출하여 반환한다.
+     * 아직 완성된 메시지가 없으면 null을 반환한다.
+     *
+     * 추출 후 남은 데이터는 버퍼 앞으로 이동(compaction)한다.
+     * 비정상적인 메시지 길이(음수 또는 10MB 초과)가 감지되면 버퍼를 초기화한다.
+     */
+    fun poll(): String? {
+        // 길이 헤더(4바이트)가 아직 도착하지 않음
+        if (writePosition < 4) return null
+
+        buffer.position(0)
+        buffer.order(ByteOrder.BIG_ENDIAN)
+        val messageLength = buffer.getInt(0)
+
+        // 비정상적인 메시지 길이 감지 시 버퍼 초기화
+        if (messageLength < 0 || messageLength > 10 * 1024 * 1024) {
+            writePosition = 0
+            return null
+        }
+
+        val totalNeeded = 4 + messageLength
+        // 메시지 본문이 아직 완전히 도착하지 않음
+        if (writePosition < totalNeeded) return null
+
+        // 완성된 메시지 추출
+        val jsonBytes = ByteArray(messageLength)
+        System.arraycopy(buffer.array(), 4, jsonBytes, 0, messageLength)
+
+        // 남은 데이터를 버퍼 앞으로 이동 (compaction)
+        val remaining = writePosition - totalNeeded
+        if (remaining > 0) {
+            System.arraycopy(buffer.array(), totalNeeded, buffer.array(), 0, remaining)
+        }
+        writePosition = remaining
+
+        return String(jsonBytes, Charsets.UTF_8)
+    }
+
+    /**
+     * 추가될 바이트를 수용할 수 있도록 버퍼 용량을 확보한다.
+     * 부족하면 기존 용량의 2배 또는 필요 크기 중 큰 값으로 확장한다.
+     */
+    private fun ensureCapacity(additionalBytes: Int) {
+        val required = writePosition + additionalBytes
+        if (required > buffer.capacity()) {
+            val newCapacity = maxOf(buffer.capacity() * 2, required)
+            val newBuffer = ByteBuffer.allocate(newCapacity).apply {
+                order(ByteOrder.BIG_ENDIAN)
+            }
+            System.arraycopy(buffer.array(), 0, newBuffer.array(), 0, writePosition)
+            buffer = newBuffer
+        }
+    }
+}

package/android/src/main/java/net/eventboot/welcomeusb/BootWelcomeUsbModule.kt

@@ -0,0 +1,92 @@
+package net.eventboot.welcomeusb
+
+import android.util.Log
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+private const val TAG = "BootWelcomeUsb"
+
+/**
+ * USB AOA(Android Open Accessory) 통신을 위한 Expo Native Module.
+ *
+ * Android 태블릿(Accessory)이 Mac의 EventBoot-Desktop(Host)과
+ * USB 케이블을 통해 QR 코드 접수 데이터를 주고받는다.
+ *
+ * JavaScript에서 'BootWelcomeUsb' 이름으로 접근하며,
+ * 연결 상태 변경 / 데이터 수신 / 에러 이벤트를 JS 측으로 전달한다.
+ */
+class BootWelcomeUsbModule : Module() {
+    private var manager: AoaAccessoryManager? = null
+
+    override fun definition() = ModuleDefinition {
+        // JS에서 requireNativeModule('BootWelcomeUsb')로 접근
+        Name("BootWelcomeUsb")
+
+        // JS로 전달되는 이벤트 정의
+        Events("onConnectionStateChanged", "onDataReceived", "onError")
+
+        // 모듈 생성 시 AoaAccessoryManager를 초기화하고 USB Accessory 연결을 시도
+        OnCreate {
+            Log.d(TAG, "OnCreate: 모듈 초기화 시작")
+            val ctx = appContext.reactContext ?: run {
+                Log.w(TAG, "OnCreate: reactContext가 null이므로 초기화 중단")
+                return@OnCreate
+            }
+            manager = AoaAccessoryManager(
+                context = ctx,
+                onConnectionStateChanged = { state, message ->
+                    Log.d(TAG, "연결 상태 변경: state=$state, message=$message")
+                    sendEvent("onConnectionStateChanged", mapOf(
+                        "state" to state,
+                        "message" to (message ?: "")
+                    ))
+                },
+                onDataReceived = { messageJson ->
+                    Log.d(TAG, "데이터 수신: ${messageJson.take(200)}")
+                    sendEvent("onDataReceived", mapOf(
+                        "messageJson" to messageJson
+                    ))
+                },
+                onError = { code, message ->
+                    Log.e(TAG, "에러 발생: code=$code, message=$message")
+                    sendEvent("onError", mapOf(
+                        "code" to code,
+                        "message" to message
+                    ))
+                }
+            )
+            manager?.register()
+            Log.d(TAG, "OnCreate: BroadcastReceiver 등록 완료")
+            manager?.checkAndOpenAccessory()
+            Log.d(TAG, "OnCreate: 모듈 초기화 완료")
+        }
+
+        // 모듈 소멸 시 BroadcastReceiver 해제 및 USB 연결 정리
+        OnDestroy {
+            Log.d(TAG, "OnDestroy: 모듈 소멸 시작")
+            manager?.unregister()
+            manager = null
+            Log.d(TAG, "OnDestroy: 모듈 소멸 완료")
+        }
+
+        // 현재 USB 연결 상태를 반환 (DISCONNECTED | CONNECTED | AOA_READY)
+        AsyncFunction("getConnectionState") {
+            val state = manager?.getConnectionState() ?: "DISCONNECTED"
+            Log.d(TAG, "getConnectionState: $state")
+            return@AsyncFunction state
+        }
+
+        // 사용자에게 USB Accessory 접근 권한을 요청
+        AsyncFunction("requestPermission") {
+            Log.d(TAG, "requestPermission 호출")
+            manager?.requestPermission()
+            return@AsyncFunction true
+        }
+
+        // Length-Prefix 프레이밍으로 JSON 메시지를 USB Host(Mac)에 전송
+        AsyncFunction("sendData") { messageJson: String ->
+            Log.d(TAG, "sendData: ${messageJson.take(200)}")
+            return@AsyncFunction manager?.sendData(messageJson) ?: false
+        }
+    }
+}

package/build/BootWelcomeUsb.types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * USB AOA 연결 상태.
+ * - DISCONNECTED: USB Accessory 미연결
+ * - CONNECTED: Accessory가 감지되었으나 스트림이 아직 열리지 않은 상태
+ * - AOA_SWITCHING: AOA 모드로 전환 중 (현재 미사용, 향후 확장 예약)
+ * - AOA_READY: 입출력 스트림이 열려 데이터 송수신 가능
+ * - ERROR: 연결 또는 권한 오류
+ */
+export type UsbAoaConnectionState = 'DISCONNECTED' | 'CONNECTED' | 'AOA_SWITCHING' | 'AOA_READY' | 'ERROR';
+/**
+ * USB AOA 통신에 사용되는 메시지 구조.
+ * Android 태블릿(Accessory)과 Mac(Host) 간에 이 형식의 JSON을 주고받는다.
+ *
+ * @property id - UUID. 요청-응답 매칭에 사용
+ * @property type - 메시지 유형 (REQUEST/RESPONSE: 데이터 교환, PING/PONG: 연결 확인)
+ * @property path - 요청 경로 (예: "/scan", "/ping")
+ * @property body - JSON 문자열로 직렬화된 페이로드 (선택)
+ */
+export interface AoaMessage {
+    id: string;
+    type: 'REQUEST' | 'RESPONSE' | 'PING' | 'PONG';
+    path: string;
+    body?: string;
+}
+/**
+ * 네이티브 모듈에서 JS로 전달되는 이벤트 맵.
+ * NativeModule<BootWelcomeUsbEvents> 제네릭에 사용되어 타입 안전한 이벤트 리스닝을 제공한다.
+ */
+export type BootWelcomeUsbEvents = {
+    /** USB 연결 상태가 변경될 때 발생 */
+    onConnectionStateChanged: (params: {
+        state: UsbAoaConnectionState;
+        message?: string;
+    }) => void;
+    /** USB Host(Mac)로부터 완성된 JSON 메시지를 수신할 때 발생 */
+    onDataReceived: (params: {
+        messageJson: string;
+    }) => void;
+    /** USB 통신 중 에러가 발생할 때 발생 (code: 에러 코드, message: 에러 설명) */
+    onError: (params: {
+        code: string;
+        message: string;
+    }) => void;
+};
+//# sourceMappingURL=BootWelcomeUsb.types.d.ts.map

package/build/BootWelcomeUsb.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BootWelcomeUsb.types.d.ts","sourceRoot":"","sources":["../src/BootWelcomeUsb.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3G;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,0BAA0B;IAC1B,wBAAwB,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,qBAAqB,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/F,8CAA8C;IAC9C,cAAc,EAAE,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1D,0DAA0D;IAC1D,OAAO,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC9D,CAAC"}

package/build/BootWelcomeUsb.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BootWelcomeUsb.types.js.map

package/build/BootWelcomeUsb.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BootWelcomeUsb.types.js","sourceRoot":"","sources":["../src/BootWelcomeUsb.types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * USB AOA 연결 상태.\n * - DISCONNECTED: USB Accessory 미연결\n * - CONNECTED: Accessory가 감지되었으나 스트림이 아직 열리지 않은 상태\n * - AOA_SWITCHING: AOA 모드로 전환 중 (현재 미사용, 향후 확장 예약)\n * - AOA_READY: 입출력 스트림이 열려 데이터 송수신 가능\n * - ERROR: 연결 또는 권한 오류\n */\nexport type UsbAoaConnectionState = 'DISCONNECTED' | 'CONNECTED' | 'AOA_SWITCHING' | 'AOA_READY' | 'ERROR';\n\n/**\n * USB AOA 통신에 사용되는 메시지 구조.\n * Android 태블릿(Accessory)과 Mac(Host) 간에 이 형식의 JSON을 주고받는다.\n *\n * @property id - UUID. 요청-응답 매칭에 사용\n * @property type - 메시지 유형 (REQUEST/RESPONSE: 데이터 교환, PING/PONG: 연결 확인)\n * @property path - 요청 경로 (예: \"/scan\", \"/ping\")\n * @property body - JSON 문자열로 직렬화된 페이로드 (선택)\n */\nexport interface AoaMessage {\n  id: string;\n  type: 'REQUEST' | 'RESPONSE' | 'PING' | 'PONG';\n  path: string;\n  body?: string;\n}\n\n/**\n * 네이티브 모듈에서 JS로 전달되는 이벤트 맵.\n * NativeModule<BootWelcomeUsbEvents> 제네릭에 사용되어 타입 안전한 이벤트 리스닝을 제공한다.\n */\nexport type BootWelcomeUsbEvents = {\n  /** USB 연결 상태가 변경될 때 발생 */\n  onConnectionStateChanged: (params: { state: UsbAoaConnectionState; message?: string }) => void;\n  /** USB Host(Mac)로부터 완성된 JSON 메시지를 수신할 때 발생 */\n  onDataReceived: (params: { messageJson: string }) => void;\n  /** USB 통신 중 에러가 발생할 때 발생 (code: 에러 코드, message: 에러 설명) */\n  onError: (params: { code: string; message: string }) => void;\n};\n"]}

package/build/BootWelcomeUsbModule.d.ts

@@ -0,0 +1,17 @@
+import { NativeModule } from 'expo';
+import { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';
+/**
+ * Android 네이티브 모듈(BootWelcomeUsbModule.kt)의 TypeScript 타입 선언.
+ * NativeModule을 상속하여 이벤트 리스닝(addListener)과 AsyncFunction 호출을 타입 안전하게 제공한다.
+ */
+declare class BootWelcomeUsbModule extends NativeModule<BootWelcomeUsbEvents> {
+    /** 현재 USB 연결 상태를 반환 (DISCONNECTED | CONNECTED | AOA_READY) */
+    getConnectionState(): Promise<string>;
+    /** 사용자에게 USB Accessory 접근 권한을 요청 */
+    requestPermission(): Promise<boolean>;
+    /** Length-Prefix 프레이밍으로 JSON 메시지를 USB Host(Mac)에 전송 */
+    sendData(messageJson: string): Promise<boolean>;
+}
+declare const _default: BootWelcomeUsbModule;
+export default _default;
+//# sourceMappingURL=BootWelcomeUsbModule.d.ts.map

package/build/BootWelcomeUsbModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BootWelcomeUsbModule.d.ts","sourceRoot":"","sources":["../src/BootWelcomeUsbModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,OAAO,OAAO,oBAAqB,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAC3E,8DAA8D;IAC9D,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IACrC,oCAAoC;IACpC,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;IACrC,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAChD;;AAID,wBAA2E"}

package/build/BootWelcomeUsbModule.js

@@ -0,0 +1,5 @@
+import { requireNativeModule } from 'expo';
+// JSI를 통해 네이티브 모듈 객체를 로드한다.
+// Android의 BootWelcomeUsbModule.kt에서 Name("BootWelcomeUsb")으로 등록된 모듈과 바인딩.
+export default requireNativeModule('BootWelcomeUsb');
+//# sourceMappingURL=BootWelcomeUsbModule.js.map

package/build/BootWelcomeUsbModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BootWelcomeUsbModule.js","sourceRoot":"","sources":["../src/BootWelcomeUsbModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAiBzD,4BAA4B;AAC5B,2EAA2E;AAC3E,eAAe,mBAAmB,CAAuB,gBAAgB,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\nimport { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';\n\n/**\n * Android 네이티브 모듈(BootWelcomeUsbModule.kt)의 TypeScript 타입 선언.\n * NativeModule을 상속하여 이벤트 리스닝(addListener)과 AsyncFunction 호출을 타입 안전하게 제공한다.\n */\ndeclare class BootWelcomeUsbModule extends NativeModule<BootWelcomeUsbEvents> {\n  /** 현재 USB 연결 상태를 반환 (DISCONNECTED | CONNECTED | AOA_READY) */\n  getConnectionState(): Promise<string>;\n  /** 사용자에게 USB Accessory 접근 권한을 요청 */\n  requestPermission(): Promise<boolean>;\n  /** Length-Prefix 프레이밍으로 JSON 메시지를 USB Host(Mac)에 전송 */\n  sendData(messageJson: string): Promise<boolean>;\n}\n\n// JSI를 통해 네이티브 모듈 객체를 로드한다.\n// Android의 BootWelcomeUsbModule.kt에서 Name(\"BootWelcomeUsb\")으로 등록된 모듈과 바인딩.\nexport default requireNativeModule<BootWelcomeUsbModule>('BootWelcomeUsb');\n"]}

package/build/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * boot-welcome-usb 모듈의 공개 API.
+ *
+ * 네이티브 모듈(BootWelcomeUsb)이 이미 EventEmitter이므로
+ * 별도의 EventEmitter 생성 없이 모듈의 addListener를 직접 위임한다.
+ */
+import type { EventSubscription } from 'expo-modules-core';
+import BootWelcomeUsbModule from './BootWelcomeUsbModule';
+import type { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';
+export * from './BootWelcomeUsb.types';
+export { useUsbAoa } from './useUsbAoa';
+/** 이벤트 이름 유니온 타입 */
+type EventName = keyof BootWelcomeUsbEvents;
+/** 각 이벤트 리스너의 첫 번째 파라미터(페이로드) 타입 추출 */
+type EventPayload<K extends EventName> = Parameters<BootWelcomeUsbEvents[K]>[0];
+/**
+ * 네이티브 이벤트 리스너를 등록한다.
+ * 반환된 EventSubscription의 remove()를 호출하여 리스너를 해제할 수 있다.
+ *
+ * @example
+ * const sub = addListener('onConnectionStateChanged', (e) => {
+ *   console.log(e.state, e.message);
+ * });
+ * // 정리
+ * sub.remove();
+ */
+export declare function addListener<K extends EventName>(eventName: K, listener: (event: EventPayload<K>) => void): EventSubscription;
+/** 현재 USB 연결 상태를 조회한다. */
+export declare function getConnectionState(): Promise<string>;
+/** 사용자에게 USB Accessory 접근 권한을 요청한다. */
+export declare function requestPermission(): Promise<boolean>;
+/**
+ * JSON 메시지를 USB Host(Mac)에 전송한다.
+ * 내부적으로 Length-Prefix 프레이밍이 적용된다.
+ * @param messageJson 전송할 JSON 문자열 (AoaMessage 형식 권장)
+ */
+export declare function sendData(messageJson: string): Promise<boolean>;
+export default BootWelcomeUsbModule;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,oBAAoB,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,oBAAoB;AACpB,KAAK,SAAS,GAAG,MAAM,oBAAoB,CAAC;AAC5C,uCAAuC;AACvC,KAAK,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7C,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GACzC,iBAAiB,CAEnB;AAED,0BAA0B;AAC1B,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1D;AAED,uCAAuC;AACvC,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAE1D;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;AAED,eAAe,oBAAoB,CAAC"}

package/build/index.js

@@ -0,0 +1,35 @@
+import BootWelcomeUsbModule from './BootWelcomeUsbModule';
+export * from './BootWelcomeUsb.types';
+export { useUsbAoa } from './useUsbAoa';
+/**
+ * 네이티브 이벤트 리스너를 등록한다.
+ * 반환된 EventSubscription의 remove()를 호출하여 리스너를 해제할 수 있다.
+ *
+ * @example
+ * const sub = addListener('onConnectionStateChanged', (e) => {
+ *   console.log(e.state, e.message);
+ * });
+ * // 정리
+ * sub.remove();
+ */
+export function addListener(eventName, listener) {
+    return BootWelcomeUsbModule.addListener(eventName, listener);
+}
+/** 현재 USB 연결 상태를 조회한다. */
+export async function getConnectionState() {
+    return await BootWelcomeUsbModule.getConnectionState();
+}
+/** 사용자에게 USB Accessory 접근 권한을 요청한다. */
+export async function requestPermission() {
+    return await BootWelcomeUsbModule.requestPermission();
+}
+/**
+ * JSON 메시지를 USB Host(Mac)에 전송한다.
+ * 내부적으로 Length-Prefix 프레이밍이 적용된다.
+ * @param messageJson 전송할 JSON 문자열 (AoaMessage 형식 권장)
+ */
+export async function sendData(messageJson) {
+    return await BootWelcomeUsbModule.sendData(messageJson);
+}
+export default BootWelcomeUsbModule;
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,oBAAoB,MAAM,wBAAwB,CAAC;AAG1D,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,SAAY,EACZ,QAA0C;IAE1C,OAAO,oBAAoB,CAAC,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAED,0BAA0B;AAC1B,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,OAAO,MAAM,oBAAoB,CAAC,kBAAkB,EAAE,CAAC;AACzD,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,OAAO,MAAM,oBAAoB,CAAC,iBAAiB,EAAE,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,WAAmB;IAChD,OAAO,MAAM,oBAAoB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC1D,CAAC;AAED,eAAe,oBAAoB,CAAC","sourcesContent":["/**\n * boot-welcome-usb 모듈의 공개 API.\n *\n * 네이티브 모듈(BootWelcomeUsb)이 이미 EventEmitter이므로\n * 별도의 EventEmitter 생성 없이 모듈의 addListener를 직접 위임한다.\n */\nimport type { EventSubscription } from 'expo-modules-core';\n\nimport BootWelcomeUsbModule from './BootWelcomeUsbModule';\nimport type { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';\n\nexport * from './BootWelcomeUsb.types';\nexport { useUsbAoa } from './useUsbAoa';\n\n/** 이벤트 이름 유니온 타입 */\ntype EventName = keyof BootWelcomeUsbEvents;\n/** 각 이벤트 리스너의 첫 번째 파라미터(페이로드) 타입 추출 */\ntype EventPayload<K extends EventName> = Parameters<BootWelcomeUsbEvents[K]>[0];\n\n/**\n * 네이티브 이벤트 리스너를 등록한다.\n * 반환된 EventSubscription의 remove()를 호출하여 리스너를 해제할 수 있다.\n *\n * @example\n * const sub = addListener('onConnectionStateChanged', (e) => {\n *   console.log(e.state, e.message);\n * });\n * // 정리\n * sub.remove();\n */\nexport function addListener<K extends EventName>(\n  eventName: K,\n  listener: (event: EventPayload<K>) => void,\n): EventSubscription {\n  return BootWelcomeUsbModule.addListener(eventName, listener);\n}\n\n/** 현재 USB 연결 상태를 조회한다. */\nexport async function getConnectionState(): Promise<string> {\n  return await BootWelcomeUsbModule.getConnectionState();\n}\n\n/** 사용자에게 USB Accessory 접근 권한을 요청한다. */\nexport async function requestPermission(): Promise<boolean> {\n  return await BootWelcomeUsbModule.requestPermission();\n}\n\n/**\n * JSON 메시지를 USB Host(Mac)에 전송한다.\n * 내부적으로 Length-Prefix 프레이밍이 적용된다.\n * @param messageJson 전송할 JSON 문자열 (AoaMessage 형식 권장)\n */\nexport async function sendData(messageJson: string): Promise<boolean> {\n  return await BootWelcomeUsbModule.sendData(messageJson);\n}\n\nexport default BootWelcomeUsbModule;\n"]}

package/build/useUsbAoa.d.ts

@@ -0,0 +1,22 @@
+import type { UsbAoaConnectionState } from './BootWelcomeUsb.types';
+/**
+ * USB AOA 연결 상태를 React 상태로 제공하는 훅.
+ *
+ * 마운트 시 현재 연결 상태를 조회하고,
+ * onConnectionStateChanged 이벤트를 구독하여 상태 변경을 실시간 반영한다.
+ * 언마운트 시 이벤트 구독을 자동 해제한다.
+ *
+ * @returns connectionState - 현재 연결 상태 문자열
+ * @returns isConnected - AOA_READY 상태 여부 (데이터 송수신 가능 여부)
+ *
+ * @example
+ * function StatusBar() {
+ *   const { connectionState, isConnected } = useUsbAoa();
+ *   return <Text>{isConnected ? '연결됨' : connectionState}</Text>;
+ * }
+ */
+export declare function useUsbAoa(): {
+    connectionState: UsbAoaConnectionState;
+    isConnected: boolean;
+};
+//# sourceMappingURL=useUsbAoa.d.ts.map

package/build/useUsbAoa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUsbAoa.d.ts","sourceRoot":"","sources":["../src/useUsbAoa.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS;;;EAuBxB"}

package/build/useUsbAoa.js

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react';
+import { addListener, getConnectionState } from './index';
+/**
+ * USB AOA 연결 상태를 React 상태로 제공하는 훅.
+ *
+ * 마운트 시 현재 연결 상태를 조회하고,
+ * onConnectionStateChanged 이벤트를 구독하여 상태 변경을 실시간 반영한다.
+ * 언마운트 시 이벤트 구독을 자동 해제한다.
+ *
+ * @returns connectionState - 현재 연결 상태 문자열
+ * @returns isConnected - AOA_READY 상태 여부 (데이터 송수신 가능 여부)
+ *
+ * @example
+ * function StatusBar() {
+ *   const { connectionState, isConnected } = useUsbAoa();
+ *   return <Text>{isConnected ? '연결됨' : connectionState}</Text>;
+ * }
+ */
+export function useUsbAoa() {
+    const [connectionState, setConnectionState] = useState('DISCONNECTED');
+    useEffect(() => {
+        // 마운트 시 현재 상태를 한 번 조회
+        getConnectionState().then((state) => {
+            setConnectionState(state);
+        });
+        // 상태 변경 이벤트 구독
+        const subscription = addListener('onConnectionStateChanged', (event) => {
+            setConnectionState(event.state);
+        });
+        return () => {
+            subscription.remove();
+        };
+    }, []);
+    return {
+        connectionState,
+        isConnected: connectionState === 'AOA_READY',
+    };
+}
+//# sourceMappingURL=useUsbAoa.js.map

package/build/useUsbAoa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUsbAoa.js","sourceRoot":"","sources":["../src/useUsbAoa.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG5C,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC,GAAG,QAAQ,CAAwB,cAAc,CAAC,CAAC;IAE9F,SAAS,CAAC,GAAG,EAAE;QACb,sBAAsB;QACtB,kBAAkB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAClC,kBAAkB,CAAC,KAA8B,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;QAEH,eAAe;QACf,MAAM,YAAY,GAAG,WAAW,CAAC,0BAA0B,EAAE,CAAC,KAAK,EAAE,EAAE;YACrE,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,YAAY,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO;QACL,eAAe;QACf,WAAW,EAAE,eAAe,KAAK,WAAW;KAC7C,CAAC;AACJ,CAAC","sourcesContent":["import { useEffect, useState } from 'react';\n\nimport type { UsbAoaConnectionState } from './BootWelcomeUsb.types';\nimport { addListener, getConnectionState } from './index';\n\n/**\n * USB AOA 연결 상태를 React 상태로 제공하는 훅.\n *\n * 마운트 시 현재 연결 상태를 조회하고,\n * onConnectionStateChanged 이벤트를 구독하여 상태 변경을 실시간 반영한다.\n * 언마운트 시 이벤트 구독을 자동 해제한다.\n *\n * @returns connectionState - 현재 연결 상태 문자열\n * @returns isConnected - AOA_READY 상태 여부 (데이터 송수신 가능 여부)\n *\n * @example\n * function StatusBar() {\n *   const { connectionState, isConnected } = useUsbAoa();\n *   return <Text>{isConnected ? '연결됨' : connectionState}</Text>;\n * }\n */\nexport function useUsbAoa() {\n  const [connectionState, setConnectionState] = useState<UsbAoaConnectionState>('DISCONNECTED');\n\n  useEffect(() => {\n    // 마운트 시 현재 상태를 한 번 조회\n    getConnectionState().then((state) => {\n      setConnectionState(state as UsbAoaConnectionState);\n    });\n\n    // 상태 변경 이벤트 구독\n    const subscription = addListener('onConnectionStateChanged', (event) => {\n      setConnectionState(event.state);\n    });\n\n    return () => {\n      subscription.remove();\n    };\n  }, []);\n\n  return {\n    connectionState,\n    isConnected: connectionState === 'AOA_READY',\n  };\n}\n"]}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["net.eventboot.welcomeusb.BootWelcomeUsbModule"]
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "boot-welcome-usb",
+  "version": "0.1.0",
+  "description": "EventBoot  Welcome AOA Module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module",
+    "open:ios": "xed example/ios",
+    "open:android": "open -a \"Android Studio\" example/android"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "boot-welcome-usb",
+    "BootWelcomeUsb"
+  ],
+  "repository": "https://github.com/bbm-sghong/boot-welcome-usb",
+  "bugs": {
+    "url": "https://github.com/bbm-sghong/boot-welcome-usb/issues"
+  },
+  "author": "sghong <sghong@bbmobile.co.kr> (https://github.com/bbm-sghong)",
+  "license": "MIT",
+  "homepage": "https://github.com/bbm-sghong/boot-welcome-usb#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.0.10",
+    "expo": "53.0.20",
+    "expo-module-scripts": "^55.0.2",
+    "react": "19.0.0",
+    "react-native": "^0.79.5"
+  },
+  "peerDependencies": {
+    "expo": "^53.0.0",
+    "react": "^19.0.0",
+    "react-native": "^0.79.0"
+  }
+}

package/src/BootWelcomeUsb.types.ts

@@ -0,0 +1,38 @@
+/**
+ * USB AOA 연결 상태.
+ * - DISCONNECTED: USB Accessory 미연결
+ * - CONNECTED: Accessory가 감지되었으나 스트림이 아직 열리지 않은 상태
+ * - AOA_SWITCHING: AOA 모드로 전환 중 (현재 미사용, 향후 확장 예약)
+ * - AOA_READY: 입출력 스트림이 열려 데이터 송수신 가능
+ * - ERROR: 연결 또는 권한 오류
+ */
+export type UsbAoaConnectionState = 'DISCONNECTED' | 'CONNECTED' | 'AOA_SWITCHING' | 'AOA_READY' | 'ERROR';
+
+/**
+ * USB AOA 통신에 사용되는 메시지 구조.
+ * Android 태블릿(Accessory)과 Mac(Host) 간에 이 형식의 JSON을 주고받는다.
+ *
+ * @property id - UUID. 요청-응답 매칭에 사용
+ * @property type - 메시지 유형 (REQUEST/RESPONSE: 데이터 교환, PING/PONG: 연결 확인)
+ * @property path - 요청 경로 (예: "/scan", "/ping")
+ * @property body - JSON 문자열로 직렬화된 페이로드 (선택)
+ */
+export interface AoaMessage {
+  id: string;
+  type: 'REQUEST' | 'RESPONSE' | 'PING' | 'PONG';
+  path: string;
+  body?: string;
+}
+
+/**
+ * 네이티브 모듈에서 JS로 전달되는 이벤트 맵.
+ * NativeModule<BootWelcomeUsbEvents> 제네릭에 사용되어 타입 안전한 이벤트 리스닝을 제공한다.
+ */
+export type BootWelcomeUsbEvents = {
+  /** USB 연결 상태가 변경될 때 발생 */
+  onConnectionStateChanged: (params: { state: UsbAoaConnectionState; message?: string }) => void;
+  /** USB Host(Mac)로부터 완성된 JSON 메시지를 수신할 때 발생 */
+  onDataReceived: (params: { messageJson: string }) => void;
+  /** USB 통신 중 에러가 발생할 때 발생 (code: 에러 코드, message: 에러 설명) */
+  onError: (params: { code: string; message: string }) => void;
+};

package/src/BootWelcomeUsbModule.ts

@@ -0,0 +1,20 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+import { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';
+
+/**
+ * Android 네이티브 모듈(BootWelcomeUsbModule.kt)의 TypeScript 타입 선언.
+ * NativeModule을 상속하여 이벤트 리스닝(addListener)과 AsyncFunction 호출을 타입 안전하게 제공한다.
+ */
+declare class BootWelcomeUsbModule extends NativeModule<BootWelcomeUsbEvents> {
+  /** 현재 USB 연결 상태를 반환 (DISCONNECTED | CONNECTED | AOA_READY) */
+  getConnectionState(): Promise<string>;
+  /** 사용자에게 USB Accessory 접근 권한을 요청 */
+  requestPermission(): Promise<boolean>;
+  /** Length-Prefix 프레이밍으로 JSON 메시지를 USB Host(Mac)에 전송 */
+  sendData(messageJson: string): Promise<boolean>;
+}
+
+// JSI를 통해 네이티브 모듈 객체를 로드한다.
+// Android의 BootWelcomeUsbModule.kt에서 Name("BootWelcomeUsb")으로 등록된 모듈과 바인딩.
+export default requireNativeModule<BootWelcomeUsbModule>('BootWelcomeUsb');

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * boot-welcome-usb 모듈의 공개 API.
+ *
+ * 네이티브 모듈(BootWelcomeUsb)이 이미 EventEmitter이므로
+ * 별도의 EventEmitter 생성 없이 모듈의 addListener를 직접 위임한다.
+ */
+import type { EventSubscription } from 'expo-modules-core';
+
+import BootWelcomeUsbModule from './BootWelcomeUsbModule';
+import type { BootWelcomeUsbEvents } from './BootWelcomeUsb.types';
+
+export * from './BootWelcomeUsb.types';
+export { useUsbAoa } from './useUsbAoa';
+
+/** 이벤트 이름 유니온 타입 */
+type EventName = keyof BootWelcomeUsbEvents;
+/** 각 이벤트 리스너의 첫 번째 파라미터(페이로드) 타입 추출 */
+type EventPayload<K extends EventName> = Parameters<BootWelcomeUsbEvents[K]>[0];
+
+/**
+ * 네이티브 이벤트 리스너를 등록한다.
+ * 반환된 EventSubscription의 remove()를 호출하여 리스너를 해제할 수 있다.
+ *
+ * @example
+ * const sub = addListener('onConnectionStateChanged', (e) => {
+ *   console.log(e.state, e.message);
+ * });
+ * // 정리
+ * sub.remove();
+ */
+export function addListener<K extends EventName>(
+  eventName: K,
+  listener: (event: EventPayload<K>) => void,
+): EventSubscription {
+  return BootWelcomeUsbModule.addListener(eventName, listener);
+}
+
+/** 현재 USB 연결 상태를 조회한다. */
+export async function getConnectionState(): Promise<string> {
+  return await BootWelcomeUsbModule.getConnectionState();
+}
+
+/** 사용자에게 USB Accessory 접근 권한을 요청한다. */
+export async function requestPermission(): Promise<boolean> {
+  return await BootWelcomeUsbModule.requestPermission();
+}
+
+/**
+ * JSON 메시지를 USB Host(Mac)에 전송한다.
+ * 내부적으로 Length-Prefix 프레이밍이 적용된다.
+ * @param messageJson 전송할 JSON 문자열 (AoaMessage 형식 권장)
+ */
+export async function sendData(messageJson: string): Promise<boolean> {
+  return await BootWelcomeUsbModule.sendData(messageJson);
+}
+
+export default BootWelcomeUsbModule;

package/src/useUsbAoa.ts

@@ -0,0 +1,45 @@
+import { useEffect, useState } from 'react';
+
+import type { UsbAoaConnectionState } from './BootWelcomeUsb.types';
+import { addListener, getConnectionState } from './index';
+
+/**
+ * USB AOA 연결 상태를 React 상태로 제공하는 훅.
+ *
+ * 마운트 시 현재 연결 상태를 조회하고,
+ * onConnectionStateChanged 이벤트를 구독하여 상태 변경을 실시간 반영한다.
+ * 언마운트 시 이벤트 구독을 자동 해제한다.
+ *
+ * @returns connectionState - 현재 연결 상태 문자열
+ * @returns isConnected - AOA_READY 상태 여부 (데이터 송수신 가능 여부)
+ *
+ * @example
+ * function StatusBar() {
+ *   const { connectionState, isConnected } = useUsbAoa();
+ *   return <Text>{isConnected ? '연결됨' : connectionState}</Text>;
+ * }
+ */
+export function useUsbAoa() {
+  const [connectionState, setConnectionState] = useState<UsbAoaConnectionState>('DISCONNECTED');
+
+  useEffect(() => {
+    // 마운트 시 현재 상태를 한 번 조회
+    getConnectionState().then((state) => {
+      setConnectionState(state as UsbAoaConnectionState);
+    });
+
+    // 상태 변경 이벤트 구독
+    const subscription = addListener('onConnectionStateChanged', (event) => {
+      setConnectionState(event.state);
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  return {
+    connectionState,
+    isConnected: connectionState === 'AOA_READY',
+  };
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+// @generated by expo-module-scripts
+{
+  "extends": "expo-module-scripts/tsconfig.base",
+  "compilerOptions": {
+    "outDir": "./build"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}