rnww-plugin-bluetooth

RNWW Plugin Bluetooth

React Native WebView Bluetooth 통신 플러그인 (BLE + Classic Bluetooth)

설치

npm install rnww-plugin-bluetooth

빠른 시작

import { registerBluetoothHandlers } from 'rnww-plugin-bluetooth';

registerBluetoothHandlers({
  bridge: yourBridgeImplementation,
  platform: { OS: Platform.OS },
});

플랫폼 지원

기능	Android	iOS
BLE 스캔	✅	✅
BLE 연결	✅	✅
GATT 읽기/쓰기	✅	✅
BLE 알림	✅	✅
Classic Bluetooth	✅	❌
페어링 관리	✅	❌
Bluetooth 활성화 요청	✅	❌
MTU 요청	✅	자동

Bridge Handlers

상태 및 권한

getBluetoothState

Bluetooth 상태를 확인합니다.

const result = await bridge.call('getBluetoothState');
// result.state: 'poweredOn' | 'poweredOff' | 'unauthorized' | 'unsupported' | 'unknown' | 'resetting'

checkBluetoothPermissions / requestBluetoothPermissions

권한을 확인하고 요청합니다.

const permission = await bridge.call('checkBluetoothPermissions');
// {
//   isAvailable: boolean,
//   isEnabled: boolean,
//   scanPermission: 'granted' | 'denied' | 'undetermined',
//   connectPermission: 'granted' | 'denied' | 'undetermined',
//   requiredPermissions: string[],
//   deniedPermissions: string[]
// }

if (permission.scanPermission !== 'granted') {
  await bridge.call('requestBluetoothPermissions');
}

requestEnableBluetooth (Android only)

Bluetooth 활성화를 요청합니다.

const result = await bridge.call('requestEnableBluetooth');

BLE 스캔

startBleScan

BLE 장치 스캔을 시작합니다.

bridge.call('startBleScan', {
  timeout: 10000,              // 스캔 타임아웃 (ms), 0 = 무제한
  scanMode: 'balanced',        // 'lowPower' | 'balanced' | 'lowLatency'
  serviceUUIDs: ['180D'],      // 필터링할 서비스 UUID (선택)
  allowDuplicates: false,      // 중복 장치 허용 여부
  nameFilter: 'MyDevice',      // 이름 필터 (선택)
  rssiThreshold: -70           // RSSI 임계값 (선택)
});

stopBleScan

BLE 스캔을 중지합니다.

bridge.call('stopBleScan');

isScanning

스캔 중인지 확인합니다.

const result = await bridge.call('isScanning');
// result.isScanning: boolean

Classic Bluetooth 스캔 (Android only)

startClassicScan

Classic Bluetooth 장치 스캔을 시작합니다.

bridge.call('startClassicScan', {
  timeout: 12000,       // 스캔 타임아웃 (ms)
  nameFilter: 'HC-05'   // 이름 필터 (선택)
});

stopClassicScan

Classic 스캔을 중지합니다.

bridge.call('stopClassicScan');

getBondedDevices

페어링된 장치 목록을 조회합니다.

const result = await bridge.call('getBondedDevices');
// result.devices: [{ address, name, bondState }]

연결

connectBle

BLE 장치에 연결합니다.

bridge.call('connectBle', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  options: {
    timeout: 10000,           // 연결 타임아웃 (ms)
    autoConnect: false,       // 자동 재연결 여부
    requestMtu: 512,          // MTU 크기 요청 (Android)
    connectionPriority: 'balanced'  // 'balanced' | 'high' | 'lowPower'
  }
});

connectClassic (Android only)

Classic Bluetooth 장치에 연결합니다.

bridge.call('connectClassic', {
  address: 'AA:BB:CC:DD:EE:FF',
  options: {
    uuid: '00001101-0000-1000-8000-00805F9B34FB',  // SPP UUID (기본값)
    secure: true,   // 보안 연결 사용 여부
    timeout: 10000
  }
});

disconnect

장치 연결을 해제합니다.

bridge.call('disconnect', { deviceId: 'AA:BB:CC:DD:EE:FF' });

disconnectAll

모든 장치 연결을 해제합니다.

bridge.call('disconnectAll');

isConnected

연결 상태를 확인합니다.

const result = await bridge.call('isConnected', { deviceId: 'AA:BB:CC:DD:EE:FF' });
// result.isConnected: boolean

getConnectedDevices

연결된 장치 목록을 조회합니다.

const result = await bridge.call('getConnectedDevices');
// result.connections: [{ deviceId, state, type }]

BLE GATT 작업

discoverServices

서비스를 발견합니다.

bridge.call('discoverServices', { deviceId: 'AA:BB:CC:DD:EE:FF' });

// 결과는 onBluetoothEvent 'servicesDiscovered' 이벤트로 수신

readCharacteristic

특성 값을 읽습니다.

bridge.call('readCharacteristic', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  serviceUuid: '180D',
  characteristicUuid: '2A37'
});

// 결과는 onBluetoothEvent 'characteristicRead' 이벤트로 수신

writeCharacteristic

특성 값을 씁니다.

bridge.call('writeCharacteristic', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  serviceUuid: '180D',
  characteristicUuid: '2A39',
  value: 'SGVsbG8=',  // Base64 인코딩된 데이터
  options: {
    withResponse: true  // Write with response (기본: true)
  }
});

setNotification

알림(Notification)을 활성화/비활성화합니다.

bridge.call('setNotification', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  serviceUuid: '180D',
  characteristicUuid: '2A37',
  enable: true
});

// 알림 데이터는 onBluetoothEvent 'notification' 이벤트로 수신

requestMtu (Android only)

MTU 크기를 요청합니다.

bridge.call('requestMtu', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  mtu: 512  // 23-517
});

// 결과는 onBluetoothEvent 'mtuChanged' 이벤트로 수신

Classic Bluetooth 데이터 (Android only)

writeClassic

Classic Bluetooth 데이터를 전송합니다.

bridge.call('writeClassic', {
  deviceId: 'AA:BB:CC:DD:EE:FF',
  value: 'SGVsbG8='  // Base64 인코딩된 데이터
});

수신 데이터는 onBluetoothEvent의 notification 이벤트로 전달됩니다.

페어링 (Android only)

createBond

장치를 페어링합니다.

bridge.call('createBond', { deviceId: 'AA:BB:CC:DD:EE:FF' });

removeBond

페어링을 해제합니다.

bridge.call('removeBond', { deviceId: 'AA:BB:CC:DD:EE:FF' });

리소스 정리

disposeBluetoothHandlers

브릿지 핸들러와 리소스를 정리합니다.

bridge.call('disposeBluetoothHandlers');

이벤트

onBluetoothEvent

모든 Bluetooth 이벤트를 수신합니다.

bridge.on('onBluetoothEvent', (event) => {
  console.log('Bluetooth Event:', event.type, event);
});

이벤트 타입

타입	설명
stateChange	Bluetooth 상태 변경
deviceDiscovered	장치 발견
scanStarted	스캔 시작
scanStopped	스캔 중지
connected	연결됨
disconnected	연결 해제됨
connectionFailed	연결 실패
servicesDiscovered	서비스 발견 완료
characteristicRead	특성 읽기 완료
characteristicWritten	특성 쓰기 완료
notification	알림 데이터 수신
mtuChanged	MTU 변경됨
bondStateChanged	페어링 상태 변경
error	에러 발생

BluetoothEvent 구조

interface BluetoothEvent {
  type: BluetoothEventType;
  deviceId?: string;
  data?: {
    state?: BluetoothState;
    device?: BluetoothDevice;
    services?: BleService[];
    result?: ReadResult;
    notification?: NotificationEvent;
    mtu?: number;
    bondState?: 'none' | 'bonding' | 'bonded';
    error?: string;
    errorCode?: string;
  };
  timestamp: number;
}

타입 정의

BluetoothDevice

interface BluetoothDevice {
  id: string;           // 장치 ID (BLE: UUID, Classic: MAC)
  name: string | null;
  type: 'ble' | 'classic';
  rssi?: number;
  ble?: BleDevice;
  classic?: ClassicDevice;
}

BleDevice

interface BleDevice {
  id: string;
  name: string | null;
  rssi: number;
  advertisementData?: string;  // Base64
  serviceUUIDs?: string[];
  isConnectable?: boolean;
  manufacturerData?: {
    companyId: number;
    data: string;  // Base64
  };
  localName?: string;
  txPowerLevel?: number;
}

BleService

interface BleService {
  uuid: string;
  isPrimary: boolean;
  characteristics?: BleCharacteristic[];
}

BleCharacteristic

interface BleCharacteristic {
  uuid: string;
  serviceUuid: string;
  properties: {
    broadcast: boolean;
    read: boolean;
    writeWithoutResponse: boolean;
    write: boolean;
    notify: boolean;
    indicate: boolean;
    authenticatedSignedWrites: boolean;
    extendedProperties: boolean;
  };
  value?: string;  // Base64
}

BluetoothError

type BluetoothError =
  | 'BLUETOOTH_UNAVAILABLE'
  | 'BLUETOOTH_DISABLED'
  | 'PERMISSION_DENIED'
  | 'DEVICE_NOT_FOUND'
  | 'DEVICE_NOT_CONNECTED'
  | 'ALREADY_CONNECTED'
  | 'CONNECTION_FAILED'
  | 'CONNECTION_TIMEOUT'
  | 'SERVICE_NOT_FOUND'
  | 'CHARACTERISTIC_NOT_FOUND'
  | 'OPERATION_FAILED'
  | 'OPERATION_NOT_SUPPORTED'
  | 'WRITE_FAILED'
  | 'READ_FAILED'
  | 'NOTIFICATION_FAILED'
  | 'SCAN_FAILED'
  | 'BONDING_FAILED'
  | 'INVALID_INPUT'
  | 'UNKNOWN';

권한 설정

Android

AndroidManifest.xml에 자동 추가:

<!-- Android 12+ (API 31+) -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- Android 11 이하 -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<!-- BLE 스캔에 필요 (Android 6-11) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS

Info.plist에 추가:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth를 사용하여 장치와 통신합니다.</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth를 사용하여 장치와 통신합니다.</string>

예제: Heart Rate Monitor

// 권한 확인
const permission = await bridge.call('checkBluetoothPermissions');
if (!permission.isEnabled) {
  await bridge.call('requestEnableBluetooth');
}
if (permission.scanPermission !== 'granted') {
  await bridge.call('requestBluetoothPermissions');
}

// 이벤트 리스너 등록
bridge.on('onBluetoothEvent', (event) => {
  switch (event.type) {
    case 'deviceDiscovered':
      console.log('발견:', event.data?.device?.name);
      // Heart Rate 서비스(180D)를 가진 장치 연결
      if (event.data?.device?.ble?.serviceUUIDs?.includes('180D')) {
        bridge.call('stopBleScan');
        bridge.call('connectBle', {
          deviceId: event.deviceId
        });
      }
      break;

    case 'connected':
      console.log('연결됨:', event.deviceId);
      bridge.call('discoverServices', { deviceId: event.deviceId });
      break;

    case 'servicesDiscovered':
      console.log('서비스 발견:', event.data?.services);
      // Heart Rate Measurement 특성에 알림 활성화
      bridge.call('setNotification', {
        deviceId: event.deviceId,
        serviceUuid: '180D',
        characteristicUuid: '2A37',
        enable: true
      });
      break;

    case 'notification':
      // Heart Rate 데이터 수신
      const value = event.data?.notification?.value;
      if (value) {
        const bytes = atob(value);
        const heartRate = bytes.charCodeAt(1);
        console.log('Heart Rate:', heartRate, 'bpm');
      }
      break;

    case 'disconnected':
      console.log('연결 해제:', event.deviceId);
      break;
  }
});

// BLE 스캔 시작 (Heart Rate 서비스 필터)
bridge.call('startBleScan', {
  serviceUUIDs: ['180D'],
  timeout: 10000
});

예제: Classic Bluetooth SPP (Android)

// 페어링된 장치 확인
const bonded = await bridge.call('getBondedDevices');
const hc05 = bonded.devices?.find(d => d.name?.includes('HC-05'));

if (hc05) {
  // Classic Bluetooth 연결
  bridge.call('connectClassic', {
    address: hc05.address
  });
}

// 이벤트 리스너
bridge.on('onBluetoothEvent', (event) => {
  switch (event.type) {
    case 'connected':
      console.log('SPP 연결됨');
      // 데이터 전송
      const data = btoa('Hello Arduino!');
      bridge.call('writeClassic', {
        deviceId: event.deviceId,
        value: data
      });
      break;

    case 'notification':
      // 데이터 수신
      const received = atob(event.data?.notification?.value || '');
      console.log('수신:', received);
      break;
  }
});

라이선스

MIT