更新记录

0.0.1（2026-04-25）

• 添加安卓 ble 低功耗蓝牙的基础支持

平台兼容性

uni-app x(4.57)

wicos-ble

wicos-ble 是一个面向 uni-app x 的 Android BLE 原生插件，用 UTS 封装 Android 蓝牙低功耗能力，对外提供接近 uni-app 蓝牙 API 风格的调用方式。它主要服务于 BLE 调试、扫描、连接、服务发现、特征值读写和通知订阅等场景。

特性

• Android-only BLE 能力封装。
• 支持蓝牙适配器初始化、设备扫描、GATT 连接与断开。
• 支持服务、特征值、读写、通知/指示、MTU 协商。
• 支持设备发现、连接状态变化、特征值变化、MTU 变化事件回调。
• 内置权限申请流程，适配 Android 12+ 与旧版 Android 的权限差异。
• 对非 Android 平台提供统一的 fallback 错误返回。

目录结构

uni_modules/wicos-ble/
├── README.md
├── index.uts
├── interface.uts
├── unierror.uts
├── package.json
└── app-android/
    ├── index.uts
    ├── ble-manager.uts
    ├── callbacks.uts
    └── permissions.uts

文件职责

• index.uts：插件根入口，对外导出统一 API；非 Android 平台在这里返回 fallback 错误。
• app-android/index.uts：Android 平台主入口，负责把具体 API 组装出来。
• app-android/ble-manager.uts：Android BLE 核心状态管理与业务逻辑。
• app-android/callbacks.uts：扫描回调和 GATT 回调实现。
• app-android/permissions.uts：蓝牙权限申请与打开适配器流程。
• interface.uts：领域类型、结果结构和错误码声明。
• unierror.uts：插件错误对象与错误码文案。
• package.json：uni_modules 插件元数据。

平台支持

• 当前仅支持 APP-ANDROID。
• 其他平台会返回 90017，表示当前平台不支持此 BLE 插件。

安装方式

通常将整个 wicos-ble 目录放入项目的 uni_modules 下即可。页面侧通过下面的方式导入：

import {
  openBluetoothAdapter,
  startBluetoothDevicesDiscovery,
  createBLEConnection,
  getBLEDeviceServices
} from "@/uni_modules/wicos-ble"

调用流程

推荐按下面的顺序调用插件接口：

1. 打开蓝牙适配器

先调用 openBluetoothAdapter 完成权限申请和适配器初始化。成功后再进入扫描和连接流程。

openBluetoothAdapter(
  () => {
    console.log("蓝牙已就绪")
  },
  (err: UniError) => {
    console.log(err.errCode + ":" + err.errMsg)
  }
)

2. 开始扫描设备

适配器可用后，调用 startBluetoothDevicesDiscovery 开始扫描。页面通常同时监听 onBluetoothDeviceFound，把发现到的设备实时刷新到列表。

startBluetoothDevicesDiscovery(
  () => {
    console.log("开始扫描")
  },
  (err: UniError) => {
    console.log(err.errMsg)
  }
)

3. 选择设备并建立连接

拿到扫描结果后，先通过设备地址调用 createBLEConnection。连接成功不代表已经可以操作数据，真正完成点是后续服务发现成功。

createBLEConnection(
  deviceId,
  () => {
    console.log("连接成功")
  },
  (err: UniError) => {
    console.log(err.errMsg)
  }
)

4. 获取服务与特征值

连接成功后，依次调用 getBLEDeviceServices 和 getBLEDeviceCharacteristics，把目标服务和特征值加载出来。

这一步通常会先筛选出支持 read、write、notify 或 indicate 的特征值，再决定下一步操作。

5. 订阅通知或写入数据

如果特征值支持通知，调用 notifyBLECharacteristicValueChange(..., true, ...) 开启订阅，并通过 onBLECharacteristicValueChange 接收设备主动推送的数据。

如果特征值支持写入，先确认是 write 还是 writeNoResponse，再调用 writeBLECharacteristicValue 发送字节数组。

6. 读取值或协商 MTU

当特征值支持 read 时，调用 readBLECharacteristicValue 直接读取当前值。

如果需要更大的数据包，可以调用 requestBLEMTU 发起 MTU 协商，并通过 onBLEMTUChange 获取结果。

7. 关闭连接与清理

操作完成后，调用 closeBLEConnection 断开单个设备；页面退出或完全结束 BLE 操作时，再调用 closeBluetoothAdapter 清理资源和回调。

API 概览

适配器

openBluetoothAdapter(success, fail)

打开蓝牙适配器并完成初始化，会自动检查并申请所需权限。

• success: () => void：初始化成功时回调。
• fail: (err: UniError) => void：初始化失败时回调，返回插件错误对象。

注意事项：

• Android 12+ 会申请 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT。
• Android 11 及以下会申请 ACCESS_FINE_LOCATION 和 ACCESS_COARSE_LOCATION。
• 如果系统蓝牙未开启，会返回 90001。

closeBluetoothAdapter()

关闭蓝牙适配器，释放扫描、连接和回调资源。

• 无参数。
• 无返回值。

注意事项：

• 通常在页面退出、切换到不再需要 BLE 的场景时调用。
• 调用后需要重新 openBluetoothAdapter 才能继续使用。

getBluetoothAdapterState()

获取当前蓝牙适配器状态。

• 返回值：BluetoothAdapterState
• 字段：
  • discovering：当前是否正在扫描。
  • available：当前蓝牙是否开启。

扫描

startBluetoothDevicesDiscovery(success, fail, services?, allowDuplicates?)

开始扫描 BLE 设备。

• success: () => void：扫描启动成功时回调。
• fail: (err: UniError) => void：扫描启动失败时回调。
• services?: string[]：可选，按服务 UUID 过滤扫描结果。
• allowDuplicates?: boolean：可选，是否允许重复上报同一设备。

注意事项：

• 返回 90013 表示扫描启动失败。
• 当前实现会把扫描结果缓存到内部设备列表，并通过 onBluetoothDeviceFound 逐条通知。

stopBluetoothDevicesDiscovery(success)

停止扫描 BLE 设备。

• success: () => void：停止成功后回调。

注意事项：

• 即使当前没有扫描，调用也不会抛出错误。

getBluetoothDevices()

获取当前扫描缓存中的设备列表。

• 返回值：BluetoothDeviceInfo[]

设备字段：

• name：设备名称，可能为空字符串。
• deviceId：设备地址。
• RSSI：信号强度。
• advertisData：广播原始数据。
• advertisServiceUUIDs：广播中的服务 UUID 列表。
• localName：广播本地名称。

onBluetoothDeviceFound(callback)

注册设备发现事件。

• callback: (res: DeviceFoundResult) => void

回调结构：

• device：单个新发现设备。

offBluetoothDeviceFound(callback?)

注销设备发现事件。

• callback?：可选，传入具体回调时只移除该回调；不传则清空全部回调。

连接

createBLEConnection(deviceId, success, fail, timeout?)

连接到指定 BLE 设备，并在连接后自动发现服务。

• deviceId: string：目标设备地址。
• success: () => void：服务发现成功后回调。
• fail: (err: UniError) => void：连接或服务发现失败时回调。
• timeout?: number：可选，连接超时时间，默认 15000 毫秒。

注意事项：

• 连接成功并不代表设备可用，真正完成标志是服务发现成功。
• 超时会返回 90006。
• 设备断开会返回 90014。

closeBLEConnection(deviceId, success, fail)

断开指定设备的 GATT 连接。

• deviceId: string：目标设备地址。
• success: () => void：断开成功后回调。
• fail: (err: UniError) => void：断开失败时回调。

注意事项：

• 如果设备当前没有连接，会返回 90014。

onBLEConnectionStateChange(callback)

注册连接状态变化事件。

• callback: (res: ConnectionStateChangeResult) => void

回调结构：

• deviceId：设备地址。
• connected：true 表示已连接，false 表示已断开。

offBLEConnectionStateChange(callback?)

注销连接状态变化事件。

• callback?：可选，传入具体回调时只移除该回调；不传则清空全部回调。

服务与特征值

getBLEDeviceServices(deviceId, success, fail)

获取指定设备下的 GATT 服务列表。

• deviceId: string：目标设备地址。
• success: (services: BLEservice[]) => void：获取成功时回调。
• fail: (err: UniError) => void：获取失败时回调。

返回数据：

• BLEservice.uuid：服务 UUID。
• BLEservice.isPrimary：当前实现固定为 true。

注意事项：

• 如果设备未连接或服务尚未就绪，会返回 90014。

getBLEDeviceCharacteristics(deviceId, serviceId, success, fail)

获取指定服务下的特征值列表。

• deviceId: string：目标设备地址。
• serviceId: string：服务 UUID。
• success: (characteristics: BLECharacteristic[]) => void：获取成功时回调。
• fail: (err: UniError) => void：获取失败时回调。

返回数据：

• BLECharacteristic.uuid：特征值 UUID。
• BLECharacteristic.serviceId：所属服务 UUID。
• BLECharacteristic.properties：属性集合。

属性集合包含：

• read
• write
• notify
• indicate
• writeNoResponse

注意事项：

• 如果未找到特征值，会返回 90008。

writeBLECharacteristicValue(deviceId, serviceId, characteristicId, value, success, fail)

向指定特征值写入字节数组。

• deviceId: string：目标设备地址。
• serviceId: string：服务 UUID。
• characteristicId: string：特征值 UUID。
• value: ByteArray：写入内容。
• success: () => void：写入请求已受理时回调。
• fail: (err: UniError) => void：写入失败时回调。

注意事项：

• 内部会根据特征值属性自动选择 WRITE_TYPE_DEFAULT 或 WRITE_TYPE_NO_RESPONSE。
• 如果特征值不支持写入，会返回 90015。
• 如果写入操作在底层失败，会返回 90009。

readBLECharacteristicValue(deviceId, serviceId, characteristicId, success, fail)

读取指定特征值。

• deviceId: string：目标设备地址。
• serviceId: string：服务 UUID。
• characteristicId: string：特征值 UUID。
• success: (value: ByteArray) => void：读取成功时回调。
• fail: (err: UniError) => void：读取失败时回调。

注意事项：

• 只有支持 read 的特征值才可读取。
• 如果读取失败，会返回 90010。

通知与 MTU

notifyBLECharacteristicValueChange(deviceId, serviceId, characteristicId, state, success, fail)

开启或关闭特征值通知。

• deviceId: string：目标设备地址。
• serviceId: string：服务 UUID。
• characteristicId: string：特征值 UUID。
• state: boolean：true 为开启，false 为关闭。
• success: () => void：设置成功后回调。
• fail: (err: UniError) => void：设置失败时回调。

注意事项：

• 只有支持 notify 或 indicate 的特征值才可注册通知。
• 如果注册失败，会返回 90012。

requestBLEMTU(deviceId, mtu)

主动发起 MTU 协商。

• deviceId: string：目标设备地址。
• mtu: number：期望 MTU 值。

返回值：

• boolean：是否成功发起请求。

注意事项：

• 这不是最终协商结果，最终结果通过 onBLEMTUChange 接收。
• 如果请求发起失败，通常是设备未连接或底层调用失败。

onBLEMTUChange(callback)

注册 MTU 变化事件。

• callback: (res: MTUChangeResult) => void

回调结构：

• deviceId：设备地址。
• mtu：协商后的 MTU 值。

offBLEMTUChange(callback?)

注销 MTU 变化事件。

• callback?：可选，传入具体回调时只移除该回调；不传则清空全部回调。

辅助能力

isBluetoothDevicePaired(deviceId)

检查指定设备是否已配对。

• deviceId: string：目标设备地址。

返回值：

• boolean

onBLECharacteristicValueChange(callback)

注册特征值变化事件，通常用于监听设备主动推送的数据。

• callback: (res: CharacteristicValueChangeResult) => void

offBLECharacteristicValueChange(callback?)

注销特征值变化事件。

• callback?：可选，传入具体回调时只移除该回调；不传则清空全部回调。

事件回调

onBluetoothDeviceFound

扫描到设备时触发，返回设备信息：

{
  device: BluetoothDeviceInfo
}

onBLEConnectionStateChange

连接状态变化时触发：

{
  deviceId: string
  connected: boolean
}

onBLECharacteristicValueChange

特征值通知内容变化时触发：

{
  deviceId: string
  serviceId: string
  characteristicId: string
  value: ByteArray
}

onBLEMTUChange

MTU 协商结果变化时触发：

{
  deviceId: string
  mtu: number
}

错误码

插件通过 UniError / BLEFailImpl 对外返回错误信息。常见错误如下：

权限要求

插件在 openBluetoothAdapter 内部申请权限。

• Android 12 及以上：BLUETOOTH_SCAN、BLUETOOTH_CONNECT
• Android 11 及以下：ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION

如果用户拒绝权限，插件会返回 90004。

实现说明

这个插件的结构已经调整为“根入口 + Android 平台实现”：

• index.uts 只保留跨平台导出和非 Android fallback。
• app-android/index.uts 负责 Android 平台 API 组装。
• ble-manager.uts 负责 BLE 状态机和业务处理。
• callbacks.uts 专门处理扫描和 GATT 回调。
• permissions.uts 专门处理权限申请和初始化流程。

这样做的目标是把平台边界和业务边界拆开，降低后续维护成本，也更贴近 uni-app x UTS 插件的推荐结构。

使用建议

• 只在 Android 端调用这个插件。
• 页面层只依赖 @/uni_modules/wicos-ble，不要直接引入 Android SDK 类。
• 连接、扫描、通知注册等回调建议在页面初始化时统一注册，在关闭蓝牙或离开页面时统一注销。
• 写入特征值前先检查特征值是否支持 write 或 writeNoResponse。

常见问题

1. 扫描没有结果

• 确认已经调用 openBluetoothAdapter。
• 确认蓝牙已开启。
• 确认权限已经授予。
• 确认目标设备真的在广播 BLE。

2. 连接失败

• 确认设备 MAC 地址正确。
• 确认设备当前仍可连接。
• 确认设备不是已经被其他客户端独占。
• 检查是否超时，必要时调整 createBLEConnection 的 timeout。

3. 读写失败

• 先通过 getBLEDeviceCharacteristics 查看特征值属性。
• 只有带 read 的特征值才能读取。
• 只有带 write 或 writeNoResponse 的特征值才能写入。

4. 通知没有回调

• 确认已先调用 notifyBLECharacteristicValueChange(..., true, ...)。
• 确认特征值支持 notify 或 indicate。
• 确认设备侧真的有推送数据。

关联页面

项目中可直接调用这个插件的页面是：

• pages/BLE/index.uvue

该页面提供了扫描、连接、服务查看、特征值读写和日志展示的完整调试入口。

版本说明

• 当前版本：1.0.0
• 插件 ID：wicos-ble