V2 连接准备

本页只说明蓝牙连接参数、BLUFI 传输方式和标识字段。握手完成后再查看握手与状态。

扫描设备

小程序先打开蓝牙适配器并开始扫描，再从扫描结果中筛选目标设备：

1. 硬件当前广播名通常是 BLE-XXXX；具体后缀以扫描结果为准。广播名只用于展示和辅助识别，不能当作云端设备 ID；
2. 广播数据包含 BLUFI Service 0xFFFF，小程序应以 Service UUID 或对应 Service Data 确认 BLUFI 设备；
3. 保存微信蓝牙 API 返回的 deviceId，后续连接和订阅都使用它；
4. 连接成功后必须通过 AT+GETID 获取并校验完整的云端业务 device_id，不能从广播名、蓝牙地址或 deviceId 推导。

GATT 与 BLUFI

项目	约定
BLUFI Service	0xFFFF
写特征	0xFF01
通知特征	0xFF02
连接顺序	连接后先订阅 0xFF02，再发送命令
Android MTU	通过 wx.setBLEMTU 协商到 512；iOS 使用系统自动协商
BLE 安全	当前业务不要求 BLE 加密或 Bonding

连接步骤

1. 使用扫描结果中的 deviceId 建立微信蓝牙连接。
2. 发现 Service 0xFFFF。
3. 找到写特征 0xFF01 和通知特征 0xFF02。
4. 订阅 0xFF02 的通知。
5. Android 通过 wx.setBLEMTU 协商 MTU 到 512。
6. 通过 BLUFI Custom Data 发送 AT+BLE_READY。

不要直接写裸字符串

所有文本命令和业务 JSON 都是 BLUFI Custom Data 逻辑载荷，必须由 BLUFI 客户端完成组帧、分包和写入，不能直接向 GATT 特征写入裸 ASCII 字符串。

deviceId 是什么

deviceId 是微信小程序蓝牙 API 为发现到的蓝牙设备提供的连接标识，不是函数，也不是云端设备 ID。它通常来自 wx.getBluetoothDevices 或 wx.onBluetoothDeviceFound 的设备列表，并传给 wx.createBLEConnection：

wx.createBLEConnection({
  deviceId: device.deviceId
})

小程序可以把它保存到自己的变量中，但文档统一使用官方名称 deviceId，不再另造字段名。

标识分工

标识	含义	用途
device_id	云端业务设备 ID	云端绑定、业务鉴权和设备关联
deviceId	微信小程序蓝牙 API 返回的设备连接标识	建立连接、订阅通知和连接缓存
Wi-Fi MAC	Wi-Fi STA/ESP 主 MAC	硬件内部生成广播名和雷达标记；不作为小程序业务身份
bleName	蓝牙广播名，如 BLE-XXXX	扫描展示和辅助识别，不能替代 device_id
BLUFI Service	0xFFFF 及其 Service Data	确认目标是当前 BLUFI 设备

如果小程序内部把云端字段命名为 cloudDeviceId，它仍然是云端业务 ID，不能推导手机蓝牙 deviceId。两者必须分别保存。

传输约定

• 每次业务 JSON 操作使用唯一的 request_id。
• 设备的 ACK、发现事件和最终结果都原样回传该 request_id。
• 业务 JSON 也必须通过 BLUFI Custom Data 发送。
• payload 超过 512 字节时，设备返回 payload_too_large。