jw-beauty/docs/design/01-BLE通信协议明细.md

BLE 通信协议明细

基于 软件系统说明.docx 整理。本文档用于把 BLE 通信协议推进到"可联调设计"层，把帧结构、服务、命令表和时序骨架补到足够继续细化的程度。

本文档仍然遵循一个原则：不虚构未被产品说明证实的命令字、UUID 或 payload 值。以下内容中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。

已确认事实

• 通信方式：BLE 5.0 GATT
• 协议帧格式：帧头 0xAA 0x55，随后是长度、类型、数据、XOR 校验
• 已知服务 UUID：
  • FFE0：设备信息服务
  • FFE1：数据通信服务
  • FFE2：OTA 升级服务
• 业务流程中至少存在以下设备交互阶段：连接设备、确认佩戴、自动扫描、开始治疗

帧结构草案

帧总体格式

字段	偏移	长度	值域	来源	说明
header	0	2 字节	0xAA 0x55	文档确认	帧头标识
length	2	1 字节	待确认	文档确认存在，定义待补	数据长度
type	3	1 字节	待确认	文档确认存在，枚举待补	命令/数据/事件类型
payload	4	N 字节	待确认	文档确认存在	业务载荷
checksum	4+N	1 字节	待确认	文档确认为 XOR	校验

必须补齐的帧定义

项目	当前状态	阻塞影响
length 是否包含 type、checksum	未定义	无法正确解析帧
checksum XOR 计算范围	未定义	无法正确校验帧
多字节字段字节序	未定义	数值解析错误
字符串编码方式	未定义	文本解析错误
最大 payload 长度	未定义	分包策略无法设计
MTU 约束	未定义	传输效率与可靠性

建议帧计算规则（待确认）

以下为建议方案，非最终定义：

• length：建议仅表示 payload 的字节长度
• checksum：建议对 length、type、payload 所有字节做 XOR 运算
• 字节序：建议统一大端序（Big-Endian）
• 字符串：建议统一 UTF-8

服务与 characteristic 草案

FFE0 设备信息服务

职责：提供设备基础信息。

建议 characteristic 划分（待确认）：

建议名称	建议属性	说明
device_info	read	读取设备型号、固件版本、硬件版本、序列号
battery_level	read / notify	电量信息

UUID 值：待确认

FFE1 数据通信服务

职责：承担主要业务通信。

建议 characteristic 划分（待确认）：

建议名称	建议属性	说明
write_cmd	write / writeWithoutResponse	小程序向设备发送命令
notify_data	notify	设备向小程序上报数据和事件

UUID 值：待确认

FFE2 OTA 升级服务

职责：固件升级传输。

建议 characteristic 划分（待确认）：

建议名称	建议属性	说明
ota_control	write / notify	OTA 控制命令和状态通知
ota_data	writeWithoutResponse	升级包分片传输

UUID 值：待确认

命令表草案

以下命令基于业务流程推导，所有 type 值和 payload 结构都是待确认的占位。

设备信息类

建议命令名	建议方向	建议功能	type 占位	payload 请求	payload 响应	待确认
GET_DEVICE_INFO	小程序 -> 设备	读取设备型号、固件版本、序列号	0x??	空	设备信息结构体	是
GET_BATTERY	小程序 -> 设备	读取设备电量	0x??	空	电量值	是
GET_DEVICE_STATUS	小程序 -> 设备	读取设备当前状态	0x??	空	状态码	是

治疗流程类

建议命令名	建议方向	建议功能	type 占位	payload 请求	payload 响应	待确认
START_WEARING_CHECK	小程序 -> 设备	启动佩戴确认	0x??	空	佩戴检测结果	是
WEARING_CHECK_RESULT	设备 -> 小程序	上报佩戴确认结果	0x??	无（通知）	佩戴状态	是
START_AUTO_SCAN	小程序 -> 设备	启动自动扫描	0x??	空	扫描结果	是
AUTO_SCAN_RESULT	设备 -> 小程序	上报自动扫描结果	0x??	无（通知）	扫描数据	是
START_TREATMENT	小程序 -> 设备	开始治疗	0x??	治疗参数（待确认）	确认/拒绝	是
PAUSE_TREATMENT	小程序 -> 设备	暂停治疗	0x??	空	确认	是
RESUME_TREATMENT	小程序 -> 设备	恢复治疗	0x??	空	确认	是
STOP_TREATMENT	小程序 -> 设备	结束治疗	0x??	空	治疗摘要	是
TREATMENT_PROGRESS	设备 -> 小程序	上报治疗进度	0x??	无（通知）	进度数据	是
TREATMENT_ERROR	设备 -> 小程序	上报治疗异常	0x??	无（通知）	错误码	是

OTA 类

建议命令名	建议方向	建议功能	type 占位	payload 请求	payload 响应	待确认
OTA_START	小程序 -> 设备	启动 OTA	0x??	固件版本、总大小	确认/拒绝	是
OTA_CHUNK	小程序 -> 设备	传输分片	0x??	分片序号、分片数据	确认	是
OTA_VERIFY	小程序 -> 设备	校验完整固件	0x??	校验值	校验结果	是
OTA_APPLY	小程序 -> 设备	应用新固件	0x??	空	结果	是
OTA_PROGRESS	设备 -> 小程序	上报 OTA 进度	0x??	无（通知）	进度百分比	是

会话时序草案

连接后初始化时序（建议）

以下为建议流程，非最终定义：

1. 小程序扫描并连接设备 GATT
2. 发现 FFE0、FFE1、FFE2 服务
3. 订阅 FFE1 的 notify_data 通知
4. 读取 FFE0 的 device_info 获取设备基本信息
5. 根据业务需要发送后续命令

治疗主流程时序（建议）

1. 发送 START_WEARING_CHECK
2. 等待 WEARING_CHECK_RESULT 通知
3. 佩戴确认通过后发送 START_AUTO_SCAN
4. 等待 AUTO_SCAN_RESULT 通知
5. 扫描完成后发送 START_TREATMENT
6. 接收 TREATMENT_PROGRESS 周期通知
7. 治疗完成或用户主动停止后发送 STOP_TREATMENT

异常处理时序（建议）

• 命令超时：建议 3-5 秒未收到响应则重试，最多重试 3 次
• 断连重连：建议重连后重新订阅 notify 并查询设备当前状态
• 治疗中断：建议重连后查询是否需要恢复上次治疗会话

ACK/NACK 机制建议

建议每个命令都存在对应的 ACK 或 NACK 响应（待确认）：

响应类型	含义
ACK	命令已接收并执行成功
NACK	命令接收失败或执行失败，附带错误码

建议错误码表（待确认）：

建议范围	含义
0x00	成功
0x01 - 0x0F	通用错误
0x10 - 0x1F	参数错误
0x20 - 0x2F	设备状态错误
0x30 - 0x3F	治疗相关错误
0x40 - 0x4F	OTA 相关错误

分包与粘包建议

当前文档未定义，以下为建议方案（待确认）：

• 建议每个 BLE 写入操作对应一个完整帧
• 若 payload 超过 MTU 限制，建议在应用层定义分包协议
• 每个分包建议携带：帧序号、是否最后一包的标记
• 接收端建议按序号拼装，收到最后一包后校验完整性

待确认问题

• 设备绑定是否依赖 BLE 返回的设备唯一标识，还是依赖扫码
• "确认佩戴"由什么传感器或状态判断，是自动还是手动
• "自动扫描"具体扫描什么数据
• 治疗模式、档位、时长是否由小程序下发
• 治疗记录是否由小程序组装后上传，还是由设备通过 MQTT 直接上报云端
• OTA 是否通过小程序中转升级包
• 是否需要设备端主动发起的连接认证或握手

当前结论

当前说明已经足够把 BLE 协议推进到"命令表草案"层。所有标为"待确认"的命令字、payload 和 UUID 都需要在下一步被确认或修正。最优先要补齐的是 FFE1 下的 characteristic UUID、命令字分配、ACK/NACK 机制和帧计算规则。