react-native-blekit

React Native BLE Turbo Module SDK（New Architecture）。

• Android：Kotlin + BluetoothGatt
• iOS：Swift + CoreBluetooth（经 ObjC++ Turbo Module 桥）
• 能力：蓝牙状态、权限、扫描、多连接、服务发现、Read/Write/Notify、MTU、RSSI、Bond（Android）、统一错误码与事件流

需要 React Native New Architecture（Turbo Modules / Codegen）。

安装

yarn add react-native-blekit
# 或本地联调
yarn add file:../react-native-blekit

iOS：

cd ios && pod install && cd ..

平台配置

Android

库已声明 BLE 权限。宿主 App（或本仓库 example）还需确保 AndroidManifest.xml 包含：

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Android 12+ 运行时需授予 BLUETOOTH_SCAN / BLUETOOTH_CONNECT；旧版通常需要定位权限才能扫描。

iOS

在 Info.plist 增加：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限以扫描并连接 BLE 设备</string>

快速开始

import BleKit, { stringToBase64, base64ToString } from 'react-native-blekit';

async function demo() {
  const state = await BleKit.state();
  if (state !== 'PoweredOn') {
    throw new Error(`Bluetooth unavailable: ${state}`);
  }

  const permission = await BleKit.requestPermissions();
  if (!permission.granted) {
    throw new Error('Bluetooth permission denied');
  }

  const stopFound = BleKit.on('deviceFound', (device) => {
    console.log('found', device.name, device.id, device.rssi);
  });

  await BleKit.startScan({ allowDuplicates: false });

  // ... 用户选择 deviceId 后
  await BleKit.stopScan();
  stopFound();

  await BleKit.connect(deviceId, { timeoutMs: 10000 });

  const services = await BleKit.discoverServices(deviceId);
  const characteristic = services[0]?.characteristics[0];
  if (!characteristic) return;

  const value = await BleKit.readCharacteristic(
    deviceId,
    characteristic.serviceUUID,
    characteristic.uuid
  );
  console.log('read', base64ToString(value));

  BleKit.on('characteristicValue', (event) => {
    console.log('notify', base64ToString(event.value));
  });

  await BleKit.setNotify(
    deviceId,
    characteristic.serviceUUID,
    characteristic.uuid,
    true
  );

  await BleKit.writeCharacteristic(
    deviceId,
    characteristic.serviceUUID,
    characteristic.uuid,
    stringToBase64('hello'),
    true
  );
}

API

状态与权限

| 方法 | 说明 | | --- | --- | | state() | 返回 Unknown \| Resetting \| Unsupported \| Unauthorized \| PoweredOff \| PoweredOn | | requestPermissions() | 申请平台 BLE 权限 | | openSettings() | 打开系统应用设置页 |

扫描

| 方法 | 说明 | | --- | --- | | startScan(options?) | 开始扫描；serviceUUIDs / allowDuplicates / scanMode | | stopScan() | 停止扫描 | | getScannedDevices() | 返回 JS 侧合并后的扫描缓存 |

事件：deviceFound

连接（最多 7 台）

| 方法 | 说明 | | --- | --- | | connect(deviceId, options?) | timeoutMs / autoConnect(Android) | | disconnect(deviceId) | 断开连接 | | getConnectedDevices() | 当前已连接设备 |

事件：connectionStateChange

GATT

| 方法 | 说明 | | --- | --- | | discoverServices(deviceId) | 发现服务与特征 | | readCharacteristic(...) | 返回 Base64 | | writeCharacteristic(..., valueBase64, withResponse) | 写入 | | setNotify(..., enable) | 订阅/取消 Notify/Indicate | | readCharacteristicBytes / writeCharacteristicBytes | Uint8Array 便捷方法 |

事件：characteristicValue、characteristicWrite

扩展

| 方法 | Android | iOS | | --- | --- | --- | | requestMtu(deviceId, mtu) | 请求 MTU | 返回协商写长度估算（maximumWriteValueLength + 3） | | readRssi(deviceId) | ✅ | ✅ | | createBond / removeBond | ✅ | 返回 UNSUPPORTED |

事件：bondStateChange、bleStateChange

事件订阅

const off = BleKit.on('deviceFound', (device) => { /* ... */ });
off();
BleKit.removeAllListeners();

错误码

BLUETOOTH_OFF、PERMISSION_DENIED、SCAN_FAILED、CONNECT_TIMEOUT、CONNECT_FAILED、DEVICE_DISCONNECTED、SERVICE_NOT_FOUND、CHARACTERISTIC_NOT_FOUND、READ_FAILED、WRITE_FAILED、NOTIFY_FAILED、MTU_FAILED、BOND_FAILED、UNSUPPORTED、BUSY、INVALID_ARGUMENT、UNKNOWN

Promise reject / 部分事件的 error 字段形如：

{ code: BleErrorCode; message: string; deviceId?: string }

运行 Example

yarn
yarn example ios
# 或
yarn example android

Demo 提供：权限申请、扫描列表、连接、服务/特征树、Read/Write/Notify、MTU/RSSI/Bond（Android）与日志面板。

注意：BLE 扫描与连接需在真机验证；模拟器通常没有可用蓝牙无线电。

架构说明

JS BleKit API
  └─ Turbo Module Spec (NativeBlekit)
       ├─ Android BlekitModule.kt + GattSession
       └─ iOS Blekit.mm ──► BleKitManager.swift (CoreBluetooth)

特征值跨端统一使用 Base64 string；UUID 在 JS 层会规范化为小写。

开发

yarn typecheck
yarn lint

License

MIT