更新记录

1.0.0（2026-04-19）

新增

• 完整的 BLE 功能实现
• 7 大功能模块（状态管理、扫描、连接、GATT、数据转换、事件系统、高级功能）
• 40+ API 接口
• 10 种事件类型
• 自动权限适配（Android 12+）
• 多设备连接支持
• 自动重连机制
• MTU 协商
• 配对/绑定管理
• 数据转换工具
• CRC16 校验

平台兼容性

uni-app(4.41)

uni-app x(4.76)

Changbi BLE 插件

一个功能全面、易用稳定的 UniApp 低功耗蓝牙（BLE）通信 UTS 插件。

特性

• ✅ 完整的 BLE 功能支持（扫描、连接、读写、通知等）
• ✅ 自动权限适配（Android 12+ 新权限体系）
• ✅ 多设备同时连接
• ✅ 自动重连机制
• ✅ MTU 协商（23-517 字节）
• ✅ 配对/绑定管理
• ✅ RSSI 信号强度监测
• ✅ 完善的事件系统
• ✅ 数据转换工具（Hex、字符串、CRC16）
• ✅ 详细的错误处理

平台支持

• ✅ Android API 21+ (Android 5.0+)
• ❌ iOS（暂不支持）
• ❌ HarmonyOS（暂不支持）

安装

将插件复制到项目的 uni_modules 目录下。

快速开始

import * as BLE from '@/uni_modules/changbi-ble'

// 1. 初始化蓝牙适配器
await BLE.openBluetoothAdapter({ debug: true })

// 2. 请求权限
const granted = await BLE.requestBluetoothPermissions()
if (!granted) {
  console.log('权限被拒绝')
  return
}

// 3. 监听设备发现事件
BLE.on('deviceFound', (data) => {
  console.log('发现设备:', data.device)
})

// 4. 开始扫描
await BLE.startBluetoothDevicesDiscovery({
  scanMode: 'balanced',
  timeout: 10000
})

// 5. 连接设备
await BLE.createBLEConnection({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  timeout: 10000,
  autoReconnect: true
})

// 6. 发现服务
const services = await BLE.getBLEDeviceServices('AA:BB:CC:DD:EE:FF')
console.log('服务列表:', services)

// 7. 启用通知
await BLE.notifyBLECharacteristicValueChange({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  serviceId: '0000180d-0000-1000-8000-00805f9b34fb',
  characteristicId: '00002a37-0000-1000-8000-00805f9b34fb',
  state: true
})

// 8. 监听特征值变化
BLE.on('characteristicValueChange', (data) => {
  console.log('收到数据:', data.value)
})

// 9. 写入数据
await BLE.writeBLECharacteristicValue({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  serviceId: '0000180d-0000-1000-8000-00805f9b34fb',
  characteristicId: '00002a39-0000-1000-8000-00805f9b34fb',
  value: '48656C6C6F', // "Hello" 的 Hex
  writeType: 'write'
})

核心功能

1. 状态与权限管理

• openBluetoothAdapter() - 初始化蓝牙适配器
• closeBluetoothAdapter() - 关闭蓝牙适配器
• getBluetoothAdapterState() - 获取适配器状态
• isBLESupported() - 检查 BLE 支持
• requestBluetoothPermissions() - 请求蓝牙权限
• checkBluetoothPermissions() - 检查权限状态
• openBluetoothSettings() - 打开蓝牙设置
• openLocationSettings() - 打开位置设置

2. 扫描与发现

• startBluetoothDevicesDiscovery() - 开始扫描
• stopBluetoothDevicesDiscovery() - 停止扫描
• getBluetoothDevices() - 获取已发现设备列表

3. 连接与配对

• createBLEConnection() - 连接设备
• closeBLEConnection() - 断开连接
• isDeviceConnected() - 检查连接状态
• getConnectedBluetoothDevices() - 获取已连接设备
• createBLEBond() - 创建配对
• removeBLEBond() - 移除配对
• getBondState() - 获取配对状态
• getBondedDevices() - 获取已配对设备

4. GATT 数据交互

• getBLEDeviceServices() - 获取服务列表
• readBLECharacteristicValue() - 读取特征值
• writeBLECharacteristicValue() - 写入特征值
• notifyBLECharacteristicValueChange() - 启用/禁用通知
• readBLEDescriptorValue() - 读取描述符
• writeBLEDescriptorValue() - 写入描述符
• setBLEMTU() - 请求 MTU
• getBLEMTU() - 获取当前 MTU

5. 数据处理与转换

• hexToBytes() - Hex 转字节数组
• bytesToHex() - 字节数组转 Hex
• stringToHex() - 字符串转 Hex
• hexToString() - Hex 转字符串
• calculateCRC16() - 计算 CRC16 校验值

6. 事件监听系统

• on() - 注册事件监听器
• off() - 移除事件监听器
• offAll() - 移除所有监听器

支持的事件：

• adapterStateChange - 适配器状态变化
• deviceFound - 发现新设备
• connectionStateChange - 连接状态变化
• characteristicValueChange - 特征值变化
• mtuChange - MTU 变化
• bondStateChange - 配对状态变化
• rssiChange - RSSI 变化
• scanStart - 扫描开始
• scanStop - 扫描停止
• error - 错误事件

7. 高级功能

• readBLERSSI() - 读取 RSSI
• setConnectionPriority() - 设置连接优先级
• getDeviceName() - 获取设备名称
• getConnectionParameters() - 获取连接参数
• clearDeviceCache() - 清除设备缓存

注意事项

1. Android 12+ 需要新的蓝牙权限（BLUETOOTH_SCAN、BLUETOOTH_CONNECT）
2. 扫描需要位置权限（ACCESS_FINE_LOCATION）
3. 所有蓝牙数据传输使用 Hex 字符串格式
4. 建议在使用前先检查权限和蓝牙状态
5. 连接失败时可以尝试清除设备缓存后重试

完整文档

详细的 API 文档请查看 API.md

许可证

MIT License