二进制协议
适用于在小机云控制台「二进制转换表」里启用了十六进制转换的蓝牙项目。 未启用时走 文本协议,两者可以同时存在(见「与文本协议的关系」)。
# 帧格式
[0xAE][CMD:1][LEN:1][PAYLOAD:LEN]| 字段 | 长度 | 说明 |
|---|---|---|
| 帧头 | 1 | 固定 0xAE,用于在字节流中同步 |
| CMD | 1 | 命令码,高 4 位是类别:0x0x 鉴权、0x1x 数据 |
| LEN | 1 | PAYLOAD 的字节数(0~255),不包含帧头、CMD、LEN |
| PAYLOAD | LEN | 负载 |
- 整帧长度 =
3 + LEN。 - 接收方必须按 LEN 定界 切帧,不能用固定长度:
0xAE可能出现在 PAYLOAD 里。 - 非法 CMD 或长度不足时丢弃 1 字节重新找
0xAE,不要整包丢弃。
单包限制
App 端的数据帧(0x10)按单包解析,不做跨包拼接。PAYLOAD 不要超过 17 字节(3 + 17 = 20,即默认 MTU 的单个通知长度)。 超过时请拆成多条数据帧,或用文本协议分批发送。
# 命令表
| CMD | 名称 | 方向 | LEN | 说明 |
|---|---|---|---|---|
0x01 | 请求挑战 | 设备 → App | 0 | 鉴权开始 |
0x02 | 挑战 | App → 设备 | 4 | 4 字节大端 UTC 秒级时间戳 |
0x03 | 应答 | 设备 → App | 8 | HMAC-SHA256 摘要截断前 8 字节 |
0x0F | 成功 | App → 设备 | 1 | reason 见下表 |
0x0E | 失败 | App → 设备 | 1 | reason 见下表 |
0x10 | 数据帧 | 双向 | 可变 | 默认值,可在转换表里改(0x10~0x1F) |
0x11 | 属性帧 | 设备 → App | 2 | rssi / 电量上报 |
结果码 reason
| CMD | reason | 含义 |
|---|---|---|
0x0F | 0x01 | 命中本地缓存,直接通过 |
0x0F | 0x02 | 服务器校验通过 |
0x0E | 0x02 | 校验失败(摘要不匹配) |
0x0E | 0x03 | 失败次数过多,设备被临时锁定 |
0x0E | 0x04 | 未通过鉴权就发送了数据帧 |
固件只需判断 0x0F 的 reason 为 0x01 或 0x02 时置「已认证」,0x0E 的 reason 为 0x02/0x03/0x04 时置「未认证」并清空接收缓冲。
# 鉴权
蓝牙项目使用 HMAC-SHA256 挑战应答:
设备 App 服务器
│ ① AE 01 00 │ │
│ ───────────────────────────→│ │
│ ② AE 02 04 [ts:4 大端] │ │
│ ←───────────────────────────│ │
│ ③ AE 03 08 [hmac:8] │ │
│ ───────────────────────────→│ ④ verifyHmac │
│ │ ─────────────────────────→│
│ ⑤ AE 0F 01 [02] 或 │ │
│ AE 0E 01 [reason] │ │
│ ←───────────────────────────│ │摘要算法:
key = ProjectSecret(字符串,不做 AES 加密)
msg = MAC(6 字节,正常序,不带冒号) || 时间戳(4 字节大端)
hmac = HMAC-SHA256(key, msg) 的前 8 字节- 时间戳与服务器时间相差超过 5 分钟 会被拒绝。
- 鉴权通过前,
0x10数据帧一律丢弃;App 会回AE 0E 01 04。 - 完整流程与 ESP32 参考实现见 设备校验 HMAC。
# 数据帧(0x10)
- 双向:App → 设备是控制,设备 → App 是上报。
- PAYLOAD 的字节布局由控制台的「二进制转换表」决定,不是固定格式。
- 一张转换表对应一个页面;设备实现必须按同一张表编解码。
# 属性帧(0x11)
固定 2 字节,设备上报到 App:
AE 11 02 [capacity:uint8] [rssi:int8]| 字节 | 字段 | 类型 | 说明 |
|---|---|---|---|
| 0 | capacity | uint8 | 电量 0~100,101 表示充电中 |
| 1 | rssi | int8 | 信号强度,负数表示 dBm |
- 电量在 byte0,信号在 byte1。
PageHexTest与 App 都按这个顺序解析,改顺序会导致电量显示成信号值。 - 蓝牙端「设备状态」组件只显示电量,信号强度由 App 根据连接计算,因此 byte1 可以填
0。 - 只发 1 字节(
AE 11 01 [capacity])也是合法的,App 按电量解析。
# 字段编码规则
转换表里每个字段有 type、byteOffset、bitOffset、dataBits、unsigned、scale、arrayLength、items。编码时按类型分派:
| type | 占用 | 规则 |
|---|---|---|
Boolean | 1 bit | true/1 为 1,其余为 0 |
Number | dataBits 位 | 无符号钳位到 [0, 2^n-1];有符号用补码 |
Float | dataBits 位 | 先做 round(值 / scale),再按整数编码 |
Color | dataBits 位 | 16 位 = RGB565(R5G6B5),24 位 = RGB888,8 位 = R3G3B2 |
Array | arrayLength bit | 每项 1 bit,选中为 1 |
String | 1 bit ~ dataBits 位 | 方向键 1 bit;下拉/单选按钮写 items 索引 |
Object | — | 不支持二进制,强制走文本协议 |
位序(最容易写错的地方)
字节内 bit 编号为 0~7,0 是最低位。不同字段的写入顺序不一样:
| 字段 | 顺序 | 说明 |
|---|---|---|
| Boolean / Array / 方向键 | LSB 优先 | bitOffset 直接是字节内 bit 序号,bitOffset=0 就是 bit0 |
| Number / Float / Color | MSB 优先 | 从起始 bit 开始高位先写,字节对齐时等价大端 |
| 下拉 / 单选按钮索引 | LSB 优先 | 值的最低位放在起始 bit,按 dataBits 位写入 |
举例:Number 16 位写在 byte2-3,值 255 → 00 FF(大端);同一位置若按 LSB 优先写会得到 FF 00,这是错的。
跨字节的位域(如 bitOffset=6、dataBits=4)按绝对位位置连续写入,不额外对齐到字节。
# 完整示例
页面:开关(enabled)、滑块(slider)、温度(temperature,scale=0.1)、颜色(color)。
转换表:
| 字段 | 类型 | byteOffset | bitOffset | dataBits | scale |
|---|---|---|---|---|---|
| enabled | Boolean | 0 | 0 | 1 | — |
| slider | Number | 1 | 0 | 8 | 1 |
| temperature | Float | 2 | 0 | 16 | 0.1 |
| color | Color | 4 | 0 | 16 | — |
值:开关开、滑块 128、温度 25.5℃、颜色 #FF0000。
enabled = 0x01
slider = 0x80
temperature = round(25.5 / 0.1) = 255 = 0x00FF
color = RGB565(31,0,0) = 0xF800
payload = 01 80 00 FF F8 00
整帧 = AE 10 06 01 80 00 FF F8 00设备上报电量 80、信号 -55 dBm:
AE 11 02 50 C9# 与文本协议的关系
转换表里每个字段有 mode:
binary:走0x10数据帧text:仍走$X#D#key:value&校验\r\n
两帧独立发送,设备需要同时支持两条链路。Object 类型(如 deviceState)不支持二进制,只能走文本。
# 版本记录
| 日期 | 变更 |
|---|---|
| 2026-11 | 初版:帧格式、鉴权、数据帧、属性帧、编码规则 |
