ESP32-learning-materials/蓝牙通信协议.md

蓝牙数据传输协议与 API 通信文档

本文档是固件与蓝牙客户端（微信小程序）之间 BLE 通信的唯一协议说明，包含 GATT 定义、二进制帧格式、命令清单、TLV 定义、结果码/状态码、主动推送、响应模型与客户端接入要求。

本文档以当前工程代码为准，对应源码： include/ble_tlv_protocol.h、src/ble_tlv_protocol.cpp、src/radar_manager.cpp、src/tasks_manager.cpp、src/wifi_manager.cpp。 若代码与本文档不一致，以代码为准并同步更新本文档。

---

概述

本协议用于雷达设备与蓝牙客户端（微信小程序）之间的双向通信。设备作为 BLE GATT Server（外设），客户端作为 GATT Client（中心）；所有业务数据统一封装为 TLV 二进制帧，通过 GATT 特征的写入与 Notify 收发。

┌──────────────┐   b1 写入（命令）        ┌────────────────┐
│              │ ──────────────────────▶ │                │
│  BLE 客户端  │   b2 通知（响应）        │    雷达设备    │
│  （小程序）  │ ◀────────────────────── │ （GATT Server）│
│              │   a1/a2/b3 通知（推送）  │                │
│              │ ◀────────────────────── │                │
└──────────────┘                         └────────────────┘

通信模型

方向	特征	说明
客户端 → 设备	b1（Write）	下发命令
设备 → 客户端	b2（Notify）	命令响应，按 seq 与请求匹配
设备 → 客户端	a1 / a2 / b3（Notify）	主动推送数据与状态，不做请求匹配

协议特点

1. 统一帧格式 AA 55 | VER | CMD | SEQ | LEN | PAYLOAD | CRC，二进制紧凑，适合嵌入式设备。
2. 命令与数据分离：命令走 b1/b2 一问一答，数据与状态走 a1/a2/b3 主动推送。
3. 结果以 TLV_RESULT_CODE 判定，错误码/状态码的文案由客户端本地映射。
4. 支持 Notify 分包与客户端重组（当前固定 20 字节一包）。
5. 状态推送去重：仅在状态变化时经 b3 发送。
6. 配网等耗时命令采用"先 PROCESSING、后最终结果"的异步响应模型。

当前实现参数

项目	值
协议版本	0x01
帧头	0xAA 0x55
校验	CRC16-CCITT（覆盖 VERSION ~ PAYLOAD，大端）
Notify 分包	固定 20 字节
命令接收缓冲	256 字节（超限返回 ERR_PROTO_FRAME_TOO_LARGE）
默认连续推送间隔	500 ms（可通过 TLV_INTERVAL_MS 设置为 100~10000 ms）

---

一、设计原则

1. 客户端必须先按 GATT 特征 UUID 分流，再按 CMD 命令码解析。
2. b1/b2 是命令请求/响应通道：客户端写 b1，设备通过 b2 Notify 响应。
3. a1/a2/b3 是主动推送通道，不参与请求响应匹配。
4. Notify 单包可能小于整帧，客户端必须按特征分别维护重组 buffer。
5. 命令结果只以 TLV_RESULT_CODE 为事实来源，错误文案由客户端按错误码本地映射。
6. 运行状态变化通过 b3 推送，与命令结果解耦。
7. 协议层不再使用 flags、ACK、TLV_STATE、TLV_STEP、TLV_MESSAGE、TLV_ERROR_MESSAGE。
8. READ 不作为主协议能力，客户端不依赖读特征获取业务数据（只有 a1/a2/b2/b3 为 Notify，b1 为 Write）。

---

二、GATT 服务与特征

2.1 Radar Data Service（雷达数据服务）

Service UUID：a8c1e5c0-3d5d-4a9d-8d5e-7c8b6a4e2f1a

别名	UUID	属性	方向	职责
a1	beb5483e-36e1-4688-b7f5-ea07361b26a1	NOTIFY	设备→客户端	连续雷达数据流推送
a2	beb5483e-36e1-4688-b7f5-ea07361b26a2	NOTIFY	设备→客户端	雷达状态主动推送

2.2 Device Config Service（设备配置服务）

Service UUID：a8c1e5c0-3d5d-4a9d-8d5e-7c8b6a4e2f1b

别名	UUID	属性	方向	职责
b1	beb5483e-36e1-4688-b7f5-ea07361b26b1	WRITE	客户端→设备	命令写入通道
b2	beb5483e-36e1-4688-b7f5-ea07361b26b2	NOTIFY	设备→客户端	命令响应通道
b3	beb5483e-36e1-4688-b7f5-ea07361b26b3	NOTIFY	设备→客户端	设备信息与状态主动推送

2.3 通道职责

通道	属性	匹配模式	说明
b1	Write	请求→响应	客户端发送命令
b2	Notify	请求→响应	设备返回命令响应，按 seq 匹配
a1	Notify	仅推送	连续雷达数据流，不做请求匹配
a2	Notify	仅推送	雷达状态推送，不做请求匹配
b3	Notify	仅推送	设备信息/状态推送，不做请求匹配

---

三、二进制帧格式

3.1 帧结构

┌──────┬──────┬───────┬─────┬─────┬───────┬───────┬─────────┬───────┬───────┐
│ SOF1 │ SOF2 │  VER  │ CMD │ SEQ │ LEN_H │ LEN_L │ PAYLOAD │ CRC_H │ CRC_L │
│ 1B   │ 1B   │  1B   │ 1B  │ 1B  │  1B   │  1B   │  N B    │  1B   │  1B   │
└──────┴──────┴───────┴─────┴─────┴───────┴───────┴─────────┴───────┴───────┘

字段	偏移	长度	说明
SOF1	0	1	帧头，固定 0xAA
SOF2	1	1	帧头，固定 0x55
VERSION	2	1	协议版本，当前 0x01
CMD	3	1	命令码
SEQ	4	1	命令请求/响应序列号；主动推送见下表
LEN	5-6	2	PAYLOAD 长度，大端
PAYLOAD	7	N	TLV 编码数据区
CRC	7+N	2	CRC16-CCITT，大端

• 最小帧长：9 字节（空 PAYLOAD）。
• 所有多字节整数均为大端。

SEQ 取值规则（与代码一致）

帧类型	SEQ
命令请求（b1）与响应（b2）	请求的 seq，原样返回
a1 连续推送	设备侧自增（bleSequenceCounter++）
a2 雷达状态推送	固定 0x00
b3 设备信息/状态推送	固定 0x00

客户端只在 b2 上按 seq 匹配请求响应；a1/a2/b3 不参与匹配，因此 a1 的自增 seq 仅作参考。

3.2 CRC16-CCITT

• 算法：CRC16-CCITT（与代码 crc16Ccitt() 一致）
• 多项式：0x1021
• 初值：0xFFFF
• 输入/输出反转：否
• 最终异或：无
• 计算范围：从 VERSION 到 PAYLOAD 末尾（不含 SOF1/SOF2 与 CRC 本身）
• 字节序：大端

3.3 TLV 编码

┌────────┬───────┬───────┬─────────┐
│  TYPE  │ LEN_H │ LEN_L │  VALUE  │
│  1B    │  1B   │  1B   │  N B    │
└────────┴───────┴───────┴─────────┘

LEN 为大端，VALUE 长度由 LEN 指定。

3.4 Notify 分包与重组

固件统一通过 sendFrameToBLE() 发送 Notify：

• 当前为固定 20 字节分片模式（BLE_FIXED_20_BYTE_MODE = 1），单包最大 20 字节。
• 发送带互斥锁与流控（约 500 B/s，包间隔 ≥5ms）。
• 仅当对应特征已被客户端订阅（CCCD 0x2902）且已连接时才发送。

客户端必须为每个 Notify 特征分别维护重组 buffer：

通道	Buffer	说明
a1	a1Buffer	连续数据流重组
a2	a2Buffer	雷达状态重组
b2	b2Buffer	命令响应重组
b3	b3Buffer	设备信息/状态重组

---

四、命令码总览

命令	值	通道	说明
CMD_PING	0x01	b1/b2	Ping 请求/响应（可携带回显内容）
CMD_QUERY_STATUS	0x10	b1/b2	查询设备概览
CMD_QUERY_RADAR	0x12	b1/b2	查询雷达数据快照
CMD_START_CONTINUOUS	0x14	b1/b2	启动连续推送
CMD_STOP_CONTINUOUS	0x16	b1/b2	停止连续推送
CMD_RADAR_SLEEP_QUERY	0x17	b1/b2	雷达睡眠/综合状态查询开关
CMD_CONTINUOUS_PUSH	0x18	a1	连续雷达数据主动推送
CMD_DEVICE_INFO_PUSH	0x19	b3	设备信息/状态主动推送
CMD_RADAR_STATUS_PUSH	0x1A	a2	雷达状态主动推送
CMD_WIFI_SCAN	0x20	b1/b2	WiFi 扫描
CMD_WIFI_CONFIG	0x22	b1/b2	WiFi 配网
CMD_GET_SAVED_WIFI	0x24	b1/b2	查询已保存 WiFi
CMD_DELETE_SAVED_WIFI	0x26	b1/b2	删除已保存 WiFi
CMD_LED_CONTROL	0x30	b1/b2	系统指示灯开关
CMD_ERROR_RESP	0x7E	b2	协议层/入口级错误响应

---

五、命令详解（b1 写入 / b2 响应）

5.1 CMD_PING（0x01）

请求（b1）：

TLV	类型	必选	说明
TLV_ECHO_CONTENT	string	否	回显内容，可携带任意字符串

响应（b2）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	SUCCESS
TLV_ECHO_CONTENT	string	仅当请求携带内容时原样回显

---

5.2 CMD_QUERY_STATUS（0x10）

请求：无 PAYLOAD。

响应（b2，按代码 buildStatusPayload() 的字段与顺序）：

TLV	类型	必选	说明
TLV_RESULT_CODE	uint8	是	结果码
TLV_DEVICE_SN	uint64	否	设备序列号，仅 device_sn > 0 时发送
TLV_PROTOCOL_VERSION	string	是	协议版本（当前 "1.0.0"）
TLV_FIRMWARE_VERSION	string	是	固件版本
TLV_DEVICE_TYPE	string	是	设备类型（当前 "Radar"）
TLV_MAC_ADDRESS	string	是	MAC 地址
TLV_WIFI_CONFIGURED	uint8	是	是否保存过 WiFi（0/1）
TLV_WIFI_CONNECTED	uint8	是	WiFi 是否已连接（0/1）
TLV_IP_ADDRESS	string	否	IP 地址，仅 WiFi 已连接时发送
TLV_SSID	string	否	当前 WiFi 名称，仅 WiFi 已连接时发送
TLV_WIFI_STATUS	uint8	否	WiFi 状态，当前状态非 0 时发送
TLV_MQTT_STATUS	uint8	否	MQTT 状态，当前状态非 0 时发送
TLV_RADAR_SLEEP_STATUS	uint8	否	雷达睡眠查询状态，当前状态非 0 时发送
TLV_LED_ENABLED	uint8	是	系统指示灯开关（0/1），始终发送

---

5.3 CMD_QUERY_RADAR（0x12）

请求：无 PAYLOAD。

响应（b2，按代码 processQueryRadarData()）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_TIMESTAMP	uint32	设备运行时间戳（millis()，单位 ms）
TLV_PRESENCE	uint8	是否有人（0=无人，1=有人）
TLV_HEART_RATE_X10	uint16	心率×10
TLV_BREATH_RATE_X10	uint16	呼吸率×10
TLV_MOTION	uint8	运动状态
TLV_DISTANCE_CM	uint16	距离（cm）
TLV_POS_X_MM	int16	X 坐标（mm）
TLV_POS_Y_MM	int16	Y 坐标（mm）
TLV_POS_Z_MM	int16	Z 坐标（mm）
TLV_BODY_MOVEMENT	uint8	体动

快照即使无人也返回，字段为 0 属合法，客户端自行判断有效性。

---

5.4 CMD_START_CONTINUOUS（0x14）

请求（b1）：

TLV	类型	必选	说明
TLV_INTERVAL_MS	uint16	是	推送间隔，有效范围 100~10000 ms

响应（b2）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_INTERVAL_MS	uint16	成功时回传实际生效的间隔

错误：缺少参数 → ERR_PROTO_PARAM_MISSING；超出范围 → ERR_PROTO_PARAM_INVALID。

效果：启动后设备通过 a1 推送 CMD_CONTINUOUS_PUSH，并通过 a2 每 200ms 推送 CMD_RADAR_STATUS_PUSH。

---

5.5 CMD_STOP_CONTINUOUS（0x16）

请求：无 PAYLOAD。

响应（b2）：TLV_RESULT_CODE = SUCCESS。

说明：幂等操作，无论当前是否在推送都返回成功；BLE 断开时设备自动停止推送，重连后需重新下发 CMD_START_CONTINUOUS。

---

5.6 CMD_RADAR_SLEEP_QUERY（0x17）

请求（b1）：

TLV	类型	必选	说明
TLV_RADAR_SLEEP_ENABLED	uint8	是	0=关闭，1=开启

响应（b2）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_RADAR_SLEEP_ENABLED	uint8	当前开关状态

错误：缺失 → ERR_PROTO_PARAM_MISSING；非 0/1 → ERR_PROTO_PARAM_INVALID。

推送：开关状态变化时经 b3 推送 RADAR_SLEEP_QUERY_ENABLED (0x31) / RADAR_SLEEP_QUERY_DISABLED (0x30)。

---

5.7 CMD_LED_CONTROL（0x30）

请求（b1）：

TLV	类型	必选	说明
TLV_LED_ENABLED	uint8	是	0=关闭，1=开启

响应（b2）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_LED_ENABLED	uint8	当前开关状态

错误：缺失 → ERR_PROTO_PARAM_MISSING；非 0/1 → ERR_PROTO_PARAM_INVALID。

持久化与推送：开关状态保存到 Flash（Preferences 命名空间 radar_data，键 ledEnabled），断电保持；状态变化时经 b3 推送 LED_ENABLED (0x33) / LED_DISABLED (0x32)。

---

5.8 CMD_WIFI_SCAN（0x20）

请求：无 PAYLOAD。

异步响应（b2）：

第一阶段（立即）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	PROCESSING (0x01)

第二阶段（扫描完成）：

TLV	类型	必选	说明
TLV_RESULT_CODE	uint8	是	结果码
TLV_WIFI_COUNT	uint16	否	WiFi 数量，成功且非空时发送
TLV_WIFI_ITEM	block	否	WiFi 条目，可重复多个

每个 TLV_WIFI_ITEM 内为独立 TLV：

TLV	类型	说明
TLV_SSID	string	WiFi 名称
TLV_RSSI	int8	信号强度（dBm）
TLV_SECURITY	uint8	加密类型，见第十节

错误：启动扫描失败 → ERR_WIFI_BUSY；超时 → ERR_WIFI_SCAN_TIMEOUT。

---

5.9 CMD_WIFI_CONFIG（0x22）

请求（b1）：

TLV	类型	必选	说明
TLV_SSID	string	是	WiFi 名称
TLV_PASSWORD	string	是	WiFi 密码

异步响应（b2）：

第一阶段（立即）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	PROCESSING (0x01)
TLV_SSID	string	正在配置的 SSID（回显）

第二阶段（完成）：

TLV	类型	必选	说明
TLV_RESULT_CODE	uint8	是	结果码
TLV_SSID	string	否	成功时发送
TLV_IP_ADDRESS	string	否	成功时发送

错误：SSID 为空 → ERR_PROTO_PARAM_MISSING；其他常见错误 ERR_WIFI_BUSY (0x26)、ERR_WIFI_SSID_NOT_FOUND (0x21)、ERR_WIFI_SIGNAL_WEAK (0x25)、ERR_WIFI_WRONG_PASSWORD (0x22)、ERR_WIFI_SCAN_TIMEOUT (0x20)、ERR_DEV_STORAGE_FAIL (0x41)。

---

5.10 CMD_GET_SAVED_WIFI（0x24）

请求：无 PAYLOAD。

响应（b2，即时命令）：

TLV	类型	必选	说明
TLV_RESULT_CODE	uint8	是	SUCCESS 或 ERR_DEV_STORAGE_FAIL
TLV_WIFI_COUNT	uint16	否	成功时发送
TLV_WIFI_ITEM	block	否	成功时发送，可重复多个

每个 TLV_WIFI_ITEM 内为独立 TLV：

TLV	类型	说明
TLV_SSID	string	WiFi 名称
TLV_PASSWORD	string	WiFi 密码

注意：已保存网络回包中包含密码，仅用于本地配网管理。

---

5.11 CMD_DELETE_SAVED_WIFI（0x26）

请求（b1）：

TLV	类型	必选	说明
TLV_SSID	string	是	要删除的 WiFi 名称

响应（b2，成功时）：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_SSID	string	被删除的 SSID
TLV_WIFI_COUNT	uint16	删除后剩余数量

错误：SSID 为空 → ERR_PROTO_PARAM_MISSING；网络不存在 → ERR_WIFI_SSID_NOT_FOUND；删除失败 → ERR_DEV_STORAGE_FAIL。

---

5.12 CMD_ERROR_RESP（0x7E）

用于协议层/入口级、无法归属到具体业务命令的错误（未知命令、帧过大、队列满、队列未初始化等），设备通过 b2 返回：

TLV	类型	说明
TLV_RESULT_CODE	uint8	错误码

---

六、主动推送（a1 / a2 / b3）

6.1 a1 — CMD_CONTINUOUS_PUSH（0x18）连续雷达数据

• 触发：CMD_START_CONTINUOUS 成功后，按 TLV_INTERVAL_MS 间隔推送（默认 500ms），且仅在数据发生变化时发送。
• 帧：cmd = 0x18，seq = 设备侧自增。
• TLV：

TLV	类型	说明
TLV_PRESENCE	uint8	是否有人（0/1）
TLV_HEART_RATE_X10	uint16	心率×10
TLV_BREATH_RATE_X10	uint16	呼吸率×10
TLV_MOTION	uint8	运动状态

无人时上述字段均发 0。TLV_SLEEP_STATE、TLV_HEART_WAVEFORM、TLV_BREATH_WAVEFORM 当前代码未发送（已注释），客户端不应依赖。

6.2 a2 — CMD_RADAR_STATUS_PUSH（0x1A）雷达状态

• 触发：CMD_START_CONTINUOUS 成功后，每 200ms 推送。
• 帧：cmd = 0x1A，seq = 0x00。
• TLV：

TLV	类型	说明
TLV_DISTANCE_CM	uint16	距离（cm）
TLV_POS_X_MM	int16	X 坐标（mm）
TLV_POS_Y_MM	int16	Y 坐标（mm）
TLV_POS_Z_MM	int16	Z 坐标（mm）
TLV_BODY_MOVEMENT	uint8	体动

6.3 b3 — CMD_DEVICE_INFO_PUSH（0x19）设备信息与状态

• 触发：BLE 连接建立时同步当前状态；WiFi/MQTT/雷达睡眠查询/指示灯状态变化时推送（去重，仅变化时发送）。
• 帧：cmd = 0x19，seq = 0x00。

状态推送 TLV：

TLV	类型	说明
TLV_DEVICE_STATUS	uint8	设备状态码，见第九节

设备信息推送 TLV：

TLV	类型	说明
TLV_RESULT_CODE	uint8	结果码
TLV_PROTOCOL_VERSION	string	协议版本
TLV_FIRMWARE_VERSION	string	固件版本
TLV_DEVICE_TYPE	string	设备类型
TLV_MAC_ADDRESS	string	MAC 地址
TLV_DEVICE_SN	uint64	设备序列号，仅存在时发送

---

七、TLV 类型码

7.1 设备信息（0x01-0x0F）

常量	值	类型	说明
TLV_RESULT_CODE	0x02	uint8	结果码
TLV_TIMESTAMP	0x04	uint32	时间戳
TLV_PROTOCOL_VERSION	0x05	string	协议版本
TLV_DEVICE_SN	0x06	uint64	设备序列号，仅存在时发送
TLV_FIRMWARE_VERSION	0x07	string	固件版本
TLV_DEVICE_TYPE	0x08	string	设备类型
TLV_MAC_ADDRESS	0x09	string	MAC 地址

7.2 雷达数据（0x10-0x1F）

常量	值	类型	说明
TLV_HEART_RATE_X10	0x10	uint16	心率×10（720 = 72.0 bpm）
TLV_BREATH_RATE_X10	0x11	uint16	呼吸率×10（180 = 18.0 次/分）
TLV_PRESENCE	0x12	uint8	存在检测（0=无人，1=有人）
TLV_MOTION	0x13	uint8	运动状态
TLV_SLEEP_STATE	0x14	uint8	睡眠状态
TLV_DISTANCE_CM	0x15	uint16	距离（cm）
TLV_POS_X_MM	0x16	int16	X 坐标（mm）
TLV_POS_Y_MM	0x17	int16	Y 坐标（mm）
TLV_POS_Z_MM	0x18	int16	Z 坐标（mm）
TLV_BODY_MOVEMENT	0x19	uint8	体动

7.3 WiFi（0x20-0x2F）

常量	值	类型	说明
TLV_SSID	0x20	string	WiFi 名称
TLV_PASSWORD	0x21	string	WiFi 密码
TLV_WIFI_COUNT	0x22	uint16	WiFi 数量
TLV_WIFI_ITEM	0x23	block	WiFi 条目（嵌套 TLV）
TLV_RSSI	0x24	int8	信号强度（dBm）
TLV_SECURITY	0x25	uint8	加密类型，见第十节

7.4 控制与状态（0x30-0x3F）

常量	值	类型	说明
TLV_INTERVAL_MS	0x31	uint16	推送间隔（ms）
TLV_RADAR_SLEEP_ENABLED	0x32	uint8	雷达睡眠查询开关（0=关，1=开）
TLV_DEVICE_STATUS	0x33	uint8	设备状态码（b3 推送）
TLV_WIFI_STATUS	0x34	uint8	WiFi 状态
TLV_MQTT_STATUS	0x35	uint8	MQTT 状态
TLV_RADAR_SLEEP_STATUS	0x36	uint8	雷达睡眠查询状态
TLV_LED_ENABLED	0x37	uint8	系统指示灯开关（0=关，1=开）

7.5 通用消息（0x40-0x4F）

常量	值	类型	说明
TLV_IP_ADDRESS	0x41	string	IP 地址
TLV_WIFI_CONFIGURED	0x42	uint8	是否保存过 WiFi（0/1）
TLV_WIFI_CONNECTED	0x43	uint8	WiFi 是否已连接（0/1）
TLV_ECHO_CONTENT	0x44	string	回显内容

7.6 波形（0x60-0x6F）

常量	值	类型	说明
TLV_HEART_WAVEFORM	0x60	uint8	心跳波形（原始 int8 + 128）
TLV_BREATH_WAVEFORM	0x61	uint8	呼吸波形（原始 int8 + 128）

---

八、结果码

常量	值	说明
SUCCESS	0x00	成功
PROCESSING	0x01	命令已接收，处理中
ERR_PROTO_CMD_UNKNOWN	0x13	未知命令
ERR_PROTO_PARAM_MISSING	0x14	参数缺失
ERR_PROTO_PARAM_INVALID	0x15	参数非法
ERR_PROTO_BUSY	0x16	设备忙
ERR_PROTO_FRAME_TOO_LARGE	0x18	请求帧过大（超过 256 字节）
ERR_WIFI_SCAN_TIMEOUT	0x20	WiFi 扫描超时
ERR_WIFI_SSID_NOT_FOUND	0x21	未找到 SSID
ERR_WIFI_WRONG_PASSWORD	0x22	WiFi 密码错误
ERR_WIFI_SIGNAL_WEAK	0x25	WiFi 信号弱
ERR_WIFI_BUSY	0x26	WiFi 忙
ERR_DEV_STATE_INVALID	0x40	当前设备状态不允许
ERR_DEV_STORAGE_FAIL	0x41	存储失败
ERR_DEV_QUEUE_FULL	0x42	命令队列已满

---

九、设备状态码

TLV_DEVICE_STATUS / TLV_WIFI_STATUS / TLV_MQTT_STATUS / TLV_RADAR_SLEEP_STATUS 共用同一组状态码。

9.1 WiFi 状态

常量	值	说明
WIFI_DISCONNECTED	0x10	WiFi 断开
WIFI_CONNECTING	0x11	WiFi 连接中
WIFI_CONNECTED	0x12	WiFi 已连接
WIFI_FAILED	0x13	WiFi 连接失败

9.2 MQTT 状态

常量	值	说明
DEV_MQTT_DISCONNECTED	0x20	MQTT 断开
DEV_MQTT_CONNECTING	0x21	MQTT 连接中
DEV_MQTT_CONNECTED	0x22	MQTT 已连接
DEV_MQTT_FAILED	0x23	MQTT 连接失败

9.3 雷达睡眠查询状态

常量	值	说明
RADAR_SLEEP_QUERY_DISABLED	0x30	雷达睡眠/综合状态查询已关闭
RADAR_SLEEP_QUERY_ENABLED	0x31	雷达睡眠/综合状态查询已开启

9.4 系统指示灯状态

常量	值	说明
LED_DISABLED	0x32	系统指示灯已关闭
LED_ENABLED	0x33	系统指示灯已开启

---

十、WiFi 安全类型

常量	值	说明
WIFI_SEC_OPEN	0	开放网络
WIFI_SEC_WEP	1	WEP 加密
WIFI_SEC_WPA	2	WPA 加密
WIFI_SEC_WPA2	3	WPA2 加密
WIFI_SEC_WPA3	4	WPA3 加密
WIFI_SEC_UNKNOWN	255	未知类型

---

十一、响应模型

11.1 同步命令

客户端写 b1 → 设备从 b2 通知响应

响应帧：

cmd = 原命令码
seq = 请求 seq
payload = TLV_RESULT_CODE + 业务数据 TLV

失败时同样使用原命令码响应，TLV_RESULT_CODE 为对应错误码；无法归属具体业务命令的入口级错误使用 CMD_ERROR_RESP (0x7E)。

11.2 异步长命令

适用：CMD_WIFI_SCAN、CMD_WIFI_CONFIG。

阶段一（立即）: cmd=原命令码, seq=原seq, TLV_RESULT_CODE = PROCESSING (0x01)
阶段二（完成）: cmd=原命令码, seq=原seq, TLV_RESULT_CODE = SUCCESS / ERR_XXX + 业务 TLV

客户端收到 PROCESSING 后不要清除 pending 请求，继续等待最终结果。

---

十二、客户端接入要求

12.1 基本原则

1. 先按特征 UUID 分流，再按 cmd 解析。
2. 每个 Notify 特征维护独立重组 buffer。
3. 只在 b2 上按 seq 匹配请求响应。
4. a1/a2/b3 不做请求响应匹配。
5. 所有结果判断以 TLV_RESULT_CODE 为准，文案本地映射。

12.2 伪代码

const buffers = { a1: new Uint8Array(0), a2: new Uint8Array(0), b2: new Uint8Array(0), b3: new Uint8Array(0) }

function onNotify(characteristicId, chunk) {
  const channel = mapCharacteristicToChannel(characteristicId)
  buffers[channel] = concatBytes(buffers[channel], chunk)
  while (true) {
    const frame = tryExtractFrame(buffers[channel])
    if (!frame) break
    buffers[channel] = frame.remaining
    if (!verifyCrc(frame.bytes)) continue
    dispatchByChannel(channel, frame.decoded)
  }
}

const pending = new Map()

function sendCommand(cmd, payload) {
  const seq = nextSeq()
  pending.set(seq, { cmd })
  return writeB1(encodeFrame({ cmd, seq, payload }))
}

function handleCommandResponse(frame) {
  const req = pending.get(frame.seq)
  if (!req) return
  const resultCode = getTlvU8(frame.payload, TLV_RESULT_CODE)
  if (resultCode !== PROCESSING) pending.delete(frame.seq)
  routeCommandResult(req.cmd, resultCode, frame.payload)
}

function tryExtractFrame(buffer) {
  const sofIndex = findSOF(buffer)
  if (sofIndex < 0) return null
  const headerLen = 7
  if (buffer.length < sofIndex + headerLen) return null
  const payloadLen = (buffer[sofIndex + 5] << 8) | buffer[sofIndex + 6]
  const totalLen = headerLen + payloadLen + 2
  if (buffer.length < sofIndex + totalLen) return null
  return {
    bytes: buffer.slice(sofIndex, sofIndex + totalLen),
    remaining: buffer.slice(sofIndex + totalLen),
  }
}

12.3 典型交互流程

连接初始化

1. 连接 BLE 设备
2. 订阅 b2、b3、a1、a2 的 Notify（未订阅时设备不会发送）
3. 等待 b3 推送设备信息 / 发送 CMD_QUERY_STATUS 获取完整状态
4. 按需发送 CMD_START_CONTINUOUS

WiFi 配网

1. 发送 CMD_WIFI_SCAN → 收到 PROCESSING → 收到最终结果，展示列表
2. 用户选择 SSID 并输入密码
3. 发送 CMD_WIFI_CONFIG → 收到 PROCESSING → 收到 SUCCESS（含 IP）
4. b3 推送 WIFI_CONNECTED

雷达数据监控

1. 发送 CMD_START_CONTINUOUS（interval=500ms）
2. a1 持续推送 CMD_CONTINUOUS_PUSH
3. a2 每 200ms 推送 CMD_RADAR_STATUS_PUSH
4. 发送 CMD_STOP_CONTINUOUS 停止

---

十三、数据解析注意事项

1. 心率/呼吸率：TLV_HEART_RATE_X10、TLV_BREATH_RATE_X10 为 uint16，实际值 = 值 / 10.0。
2. 波形：TLV_HEART_WAVEFORM、TLV_BREATH_WAVEFORM 原始为 int8，线上为 原始值 + 128，解析时减 128。（当前 a1 未发送波形。）
3. 坐标：TLV_POS_X_MM/Y/Z 为 int16，单位 mm；米 = 值 / 1000.0。
4. 设备序列号：TLV_DEVICE_SN 固定 uint64，无 SN 时不发送，客户端不应依赖。
5. 密码回包：CMD_GET_SAVED_WIFI 的 TLV_WIFI_ITEM 含 TLV_PASSWORD，仅用于本地配网管理。
6. 时间戳：TLV_TIMESTAMP 为设备 millis()，非绝对时间。

---

十四、固件实现约束

1. 所有业务 Notify 必须通过 sendFrameToBLE() 发送，不允许直接 setValue(整帧) + notify()。
2. a1/a2/b2/b3 均为 NOTIFY；b1 为 WRITE。
3. 命令响应 seq 必须与请求一致；主动推送 a1 自增、a2/b3 为 0。
4. b1 单次写入超过 256 字节时返回 ERR_PROTO_FRAME_TOO_LARGE；命令队列（10 深度）满时返回 ERR_DEV_QUEUE_FULL。
5. 仅当客户端订阅了对应特征的 Notify 时才发送，避免无效通知。
6. 所有多字节字段与 CRC 均为大端。
7. 修改协议时需同步更新本文档（新增命令/字段须保持向后兼容）。

---

十五、版本历史

版本	日期	说明
1.0	2026-06	初始版本，纯 TLV 协议，移除 legacy JSON 兼容
2.0	2026-09	合并 ble_protocol.md 与 ble_api_communication.md；以代码为准补齐 CMD_LED_CONTROL (0x30)、TLV_LED_ENABLED (0x37)、LED 状态码、CMD_QUERY_RADAR 的 TLV_TIMESTAMP、CMD_QUERY_STATUS 的 TLV_SSID/TLV_LED_ENABLED、已保存 WiFi 含密码、删除 WiFi 回包字段，并修正 SEQ 语义