9.6 KiB
BLE 通信协议明细
基于 软件系统说明.docx 整理。本文档用于把 BLE 通信协议推进到"可联调设计"层，把帧结构、服务、命令表和时序骨架补到足够继续细化的程度。
本文档仍然遵循一个原则：不虚构未被产品说明证实的命令字、UUID 或 payload 值。以下内容中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。
已确认事实
- 通信方式：
BLE 5.0 GATT - 协议帧格式：帧头
0xAA 0x55，随后是长度、类型、数据、XOR 校验 - 已知服务 UUID：
FFE0：设备信息服务FFE1：数据通信服务FFE2：OTA 升级服务
- 业务流程中至少存在以下设备交互阶段：连接设备、确认佩戴、自动扫描、开始治疗
供应商补充协议摘录（2026-05-11）
根目录新增的 协议简述.docx 已归档到 docs/protocols/协议简述.docx，解析稿见 docs/protocols/协议简述-补充解析.md。
补充文档主要给出 FFE1 数据通信相关信息：
| UUID/字段 | 名称 | 属性/说明 |
|---|---|---|
FFE1 |
数据通信服务 / Command | 文档中同时写作服务和 Command，Write+Read，下发控制指令 |
FFE4 |
Status | Read + Notify，设备状态及 ADC 值数据上报 |
Command 参数区被描述为 33 字节：
- IO1-IO5，每个 IO 含 4 个光强字段：红灯、红外、紫外、暖黄
- IO1-IO5，每个 IO 含 2 字节电流增益
- Byte31-Byte32：保持时间高/低字节
- Byte33：异或校验
与当前实现的关键差异
由于项目当前优先目标是尽快跑通真机，新补充协议先作为当前执行协议：FFE1 写 Command，FFE4 订阅 Status，Command 直接写 33 字节参数块。旧 0xAA 0x55 | length | type | payload | XOR checksum 帧协议暂作为历史参考和后续兼容方案保留。
需要硬件侧优先确认：
FFE1、FFE4、FFE5的最终服务/特征分配。- Command 写入是否为裸 33 字节，还是仍需现有帧封装。
- Byte33 XOR 的计算范围。
- Byte31-Byte32 保持时间单位和字节序。
- Status/ADC 上报的完整字节布局。
帧结构草案
帧总体格式
| 字段 | 偏移 | 长度 | 值域 | 来源 | 说明 |
|---|---|---|---|---|---|
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?? |
无（通知） | 进度百分比 | 是 |
会话时序草案
连接后初始化时序（建议）
以下为建议流程，非最终定义：
- 小程序扫描并连接设备 GATT
- 发现
FFE0、FFE1、FFE2服务 - 订阅
FFE1的notify_data通知 - 读取
FFE0的device_info获取设备基本信息 - 根据业务需要发送后续命令
治疗主流程时序（建议）
- 发送
START_WEARING_CHECK - 等待
WEARING_CHECK_RESULT通知 - 佩戴确认通过后发送
START_AUTO_SCAN - 等待
AUTO_SCAN_RESULT通知 - 扫描完成后发送
START_TREATMENT - 接收
TREATMENT_PROGRESS周期通知 - 治疗完成或用户主动停止后发送
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 机制和帧计算规则。