BLE 设备读写
HAC 中 BLE 扫描、读取、订阅、取消订阅和写入命令的最佳实践。
适用场景
BLE 设备读写用于在 HAC 中调用 Android 蓝牙能力，扫描附近低功耗蓝牙设备或标签，并对指定服务、特征进行读取、订阅或写入。
常见场景包括资产盘点、现场定位、传感器数据采集、设备选择和设备控制。BLE 打印不属于本页范围，应按打印机协议单独设计。
使用前提
- 应用运行在
HAC中； - 设备支持 BLE，并已开启蓝牙；
- Android 已授予蓝牙扫描、连接和定位相关权限；
- 目标设备处于可发现、可连接或可通信状态；
- 已掌握目标设备的 MAC 地址、服务 UUID、特征 UUID、读写权限和数据格式；
- 数据解析逻辑已准备好，尤其是二进制、Base64 或厂商协议数据。
命令速查
| 命令 | 用途 |
|---|---|
| 扫描BLE设备/标签 | 扫描附近 BLE 设备，返回名称和 MAC 地址 |
| 扫描BLE设备/标签并填充到单元格 | 扫描后直接写入单元格 |
| 从BLE设备读取数据 | 从指定服务和特征读取数据 |
| 从BLE设备读取数据到单元格 | 读取后直接写入单元格 |
| 向BLE设备订阅数据通知 | 订阅 Notify / Indicate 回调 |
| 向BLE设备订阅数据通知并填充到单元格 | 订阅后直接写入单元格 |
| 取消对BLE设备的订阅 | 停止指定订阅 |
| 向BLE设备写入数据 | 写入 Base64 数据 |
| 向BLE设备写入数据并填充到单元格 | 写入后回填结果 |
推荐流程
进入 BLE 页面
-> 检查蓝牙和权限
-> 扫描附近设备
-> 用户选择目标设备
-> 保存设备 MAC 地址
-> 按业务执行读取、订阅或写入
-> 展示结果和通信状态
-> 离开页面或切换设备时取消订阅订阅类页面：
选择目标设备
-> 执行【向BLE设备订阅数据通知】
-> 特征变化时触发子命令
-> 子命令解析数据并刷新页面
-> 离开页面时执行【取消对BLE设备的订阅】设计要点
- 不要一进入页面就自动读写；先扫描、选择、确认目标设备；
- 设备名称可能为空或重复，页面应优先用 MAC 地址区分；
- 扫描结果用于盘点时，显示已发现、已匹配、未匹配和最近发现时间；
- 写入会改变设备状态时，要展示目标设备和指令含义，必要时二次确认；
- 订阅、页面生命周期和设备切换必须绑定，避免旧回调写入当前页面；
- 高频回调要做节流、去重或执行中锁定。
异常处理
| 异常 | 常见原因 | 推荐处理 |
|---|---|---|
| 扫描不到设备 | 蓝牙未开、权限不足、距离远、设备休眠 | 提示开启蓝牙和权限，靠近后重扫 |
| 多个同名设备 | 名称重复或为空 | 使用 MAC 地址和业务绑定关系区分 |
| 读取失败 | UUID 错误、设备断开、特征不支持读取 | 保留目标设备，提示检查 UUID 或重连 |
| 数据无法解析 | 协议不匹配、Base64 解码失败 | 显示原始数据，记录设备型号和协议版本 |
| 订阅无回调 | 模式不匹配、特征不支持 Notify / Indicate | 允许切换模式或重新订阅 |
| 重复回调 | 重复订阅、旧订阅未取消、设备高频上报 | 取消旧订阅并按业务键去重 |
| 写入失败 | 特征不支持写入、Base64 格式错误、连接中断 | 保留指令，允许重新编码或重试 |