更新记录

1.0.0（2025-11-11） 下载此版本

全部ble功能封装

平台兼容性

uni-app(3.6.14)

bleutils 使用说明

下面文档介绍项目中 utils/bleutils.js 的设计目的、可用接口、事件与示例用法，帮助快速接入和调试蓝牙功能。

概述

bleutils 是对 uni-app 低功耗蓝牙（BLE）API 的封装：

• 所有原生 API 均被 Promise 包装，便于 async/await 使用；
• 内部统一维护设备列表（deviceList）、已连接设备 id、log 事件等状态；
• 提供事件订阅机制（on/off）用于页面/组件订阅蓝牙事件，页面无需直接调用 uni.onXXX。

模块导出为单例：

import bleutils from '@/utils/bleutils'

支持的事件（可 on(type, fn) / off(type, fn)）

• deviceListChanged：发现或更新设备后派发，回调参数为设备数组。
• adapterStateChanged：适配器状态变化（available 等）。
• connectStateChanged：连接状态变化，参数示例 { deviceId, connected }。
• characteristicChanged：监听到特征值变化时触发，参数为原始回调对象（含 value）。
• notifyEnabled：启用 notify 成功回调。
• rssiChanged：获取 RSSI 时触发。
• mtuChanged：MTU 设置变更时触发。
• bluetoothDeviceLog：当发现新设备时，会 emit 一个短记录 { name, deviceId, index } 方便页面即时展示。

主要 API（Promise）

• 适配器

  • openBluetoothAdapter(params)
  • closeBluetoothAdapter(params)
  • getBluetoothAdapterState(params)

• 设备发现

  • startBluetoothDevicesDiscovery(params)
  • stopBluetoothDevicesDiscovery(params)
  • getBluetoothDevices() （返回内部维护的 devices 列表）
  • clearDevices()

• 连接

  • createBLEConnection({ deviceId })
  • closeBLEConnection({ deviceId })
  • getConnectedBluetoothDevices(params)

• 服务/特征

  • getBLEDeviceServices({ deviceId })
  • getBLEDeviceCharacteristics({ deviceId, serviceId })
  • readBLECharacteristicValue(params)
  • writeBLECharacteristicValue(params) — 支持传 writeType（write / writeNoResponse），如果不传则不指定。
  • notifyBLECharacteristicValueChange(params)

• 其它

  • getBLEDeviceRSSI(params)
  • setBLEMTU(params)
  • ensurePermissions()：尝试请求安卓定位权限（如果可用）。
  • offAll()：清空已注册回调。

页面集成示例

<script setup>
import { onMounted, onUnmounted, ref } from 'vue'
import bleutils from '@/utils/bleutils'

const deviceList = ref([])
const connected = ref('')

function onDevices(list) { deviceList.value = list }
function onConnect(res) { connected.value = res.connected ? res.deviceId : '' }
function onChar(res) { console.log('notify raw', res) }

onMounted(() => {
  bleutils.on('deviceListChanged', onDevices)
  bleutils.on('connectStateChanged', onConnect)
  bleutils.on('characteristicChanged', onChar)
})
onUnmounted(() => {
  bleutils.off('deviceListChanged', onDevices)
  bleutils.off('connectStateChanged', onConnect)
  bleutils.off('characteristicChanged', onChar)
})

async function startScan() {
  await bleutils.openBluetoothAdapter()
  await bleutils.startBluetoothDevicesDiscovery()
}

async function connect(deviceId) {
  await bleutils.createBLEConnection({ deviceId })
  // bleutils 内部会在连接后遍历所有服务并尝试启用第一个具有 notify 权限的特征（autoNotify）
}

async function writeExample() {
  // bleutils 提供 writeBLECharacteristicValue
  await bleutils.writeBLECharacteristicValue({
    deviceId: connected.value,
    serviceId: '...',
    characteristicId: '...',
    value: someArrayBuffer,
    writeType: 'write' // 可选：'writeNoResponse' 或忽略
  })
}
</script>

自动化策略（封装内行为说明）

• autoNotify：createBLEConnection 成功后，bleutils 会（页面层也有调用）自动遍历该设备所有 service，并在找到第一个 properties.notify === true 的 characteristic 时调用 notifyBLECharacteristicValueChange({ state:true }) 并 emit('notifyEnabled')。
• sendCmd（页面示例中实现的行为）：遍历所有 service，找到第一个 write 或 writeNoResponse 的 characteristic 进行写入。页面 UI 提供 writeType 选项（write / writeNoResponse / ignore），当为 ignore 时写入接口不会传 writeType 参数。

调试建议与常见问题

• 如果 autoNotify 报告“未找到可notify特征”，请确认设备提供的是自定义服务（不是 00001800 / 00001801 等通用服务），并确保具有 notify:true 的 characteristic。可使用日志区查看 bleutils 输出的所有 service 与 characteristics 列表。
• 若 onBLECharacteristicValueChange 未收到数据：
  • 确认 notify 开启成功；
  • 确认设备端真的主动推送 notify（notify 是设备主动推送，不是客户端轮询）；
  • 在日志查看原始 res 对象以判断数据类型与长度。
• 写入失败：检查 characteristic.properties 是否包含 write 或 writeNoResponse，并选择合适的 writeType。

事件与日志收集

bleutils 在关键点会 addLog（主日志区）和 console.log 输出，便于调试。页面已集成右侧日志抽屉用于查看所有操作历史（包括发现、新设备、连接、notify、写入结果等）。

小结

utils/bleutils.js 的目标是把 BLE 的复杂性封装到单一模块：

• 页面只需 import、on/off 订阅事件、调用简单的API（open/start/stop/connect/write），几行代码即可完成完整蓝牙调试流程；
• 模块已提供充分日志与 defensive 处理（例如在 closeBluetoothAdapter 时主动清空连接缓存并 emit 断开事件），以保证 UI 与实际 BLE 状态一致。

若需要我可以：

• 生成一个更详细的 API 列表（每个方法参数和返回示例）；
• 在 README 中加入常用故障排查步骤和 nRF Connect 调试示例；
• 将示例代码同步入 README.md 或界面帮助弹窗。