Skip to content

二进制协议 ​

适用于在小机云控制台「二进制转换表」里启用了十六进制转换的蓝牙项目。 未启用时走 文本协议,两者可以同时存在(见「与文本协议的关系」)。

# 帧格式 ​

[0xAE][CMD:1][LEN:1][PAYLOAD:LEN]
字段长度说明
帧头1固定 0xAE,用于在字节流中同步
CMD1命令码,高 4 位是类别:0x0x 鉴权、0x1x 数据
LEN1PAYLOAD 的字节数(0~255),不包含帧头、CMD、LEN
PAYLOADLEN负载
  • 整帧长度 = 3 + LEN。
  • 接收方必须按 LEN 定界 切帧,不能用固定长度:0xAE 可能出现在 PAYLOAD 里。
  • 非法 CMD 或长度不足时丢弃 1 字节重新找 0xAE,不要整包丢弃。

单包限制

App 端的数据帧(0x10)按单包解析,不做跨包拼接。PAYLOAD 不要超过 17 字节(3 + 17 = 20,即默认 MTU 的单个通知长度)。 超过时请拆成多条数据帧,或用文本协议分批发送。

# 命令表 ​

CMD名称方向LEN说明
0x01请求挑战设备 → App0鉴权开始
0x02挑战App → 设备44 字节大端 UTC 秒级时间戳
0x03应答设备 → App8HMAC-SHA256 摘要截断前 8 字节
0x0F成功App → 设备1reason 见下表
0x0E失败App → 设备1reason 见下表
0x10数据帧双向可变默认值,可在转换表里改(0x10~0x1F)
0x11属性帧设备 → App2rssi / 电量上报

结果码 reason ​

CMDreason含义
0x0F0x01命中本地缓存,直接通过
0x0F0x02服务器校验通过
0x0E0x02校验失败(摘要不匹配)
0x0E0x03失败次数过多,设备被临时锁定
0x0E0x04未通过鉴权就发送了数据帧

固件只需判断 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]
字节字段类型说明
0capacityuint8电量 0~100,101 表示充电中
1rssiint8信号强度,负数表示 dBm
  • 电量在 byte0,信号在 byte1。PageHexTest 与 App 都按这个顺序解析,改顺序会导致电量显示成信号值。
  • 蓝牙端「设备状态」组件只显示电量,信号强度由 App 根据连接计算,因此 byte1 可以填 0。
  • 只发 1 字节(AE 11 01 [capacity])也是合法的,App 按电量解析。

# 字段编码规则 ​

转换表里每个字段有 type、byteOffset、bitOffset、dataBits、unsigned、scale、arrayLength、items。编码时按类型分派:

type占用规则
Boolean1 bittrue/1 为 1,其余为 0
NumberdataBits 位无符号钳位到 [0, 2^n-1];有符号用补码
FloatdataBits 位先做 round(值 / scale),再按整数编码
ColordataBits 位16 位 = RGB565(R5G6B5),24 位 = RGB888,8 位 = R3G3B2
ArrayarrayLength bit每项 1 bit,选中为 1
String1 bit ~ dataBits 位方向键 1 bit;下拉/单选按钮写 items 索引
Object—不支持二进制,强制走文本协议

位序(最容易写错的地方) ​

字节内 bit 编号为 0~7,0 是最低位。不同字段的写入顺序不一样:

字段顺序说明
Boolean / Array / 方向键LSB 优先bitOffset 直接是字节内 bit 序号,bitOffset=0 就是 bit0
Number / Float / ColorMSB 优先从起始 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)。

转换表:

字段类型byteOffsetbitOffsetdataBitsscale
enabledBoolean001—
sliderNumber1081
temperatureFloat20160.1
colorColor4016—

值:开关开、滑块 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初版:帧格式、鉴权、数据帧、属性帧、编码规则

# 相关文档 ​