# 协议简述补充解析

来源：仓库根目录 `协议简述.docx`，已归档到 `docs/protocols/协议简述.docx`。

本文只记录该补充文档的可读内容和与当前实现的差异判断。原 DOCX 内容较短，主要描述 `FFE1` 数据通信服务下的控制/状态特征，以及一组 33 字节控制参数。

## 原文抽取

### 服务/功能摘要

| UUID | 名称 | 说明 |
| --- | --- | --- |
| `FFE1` | 数据通信服务 | 控制指令 |
| `FFE4` | 设备状态及 ADC 值 | 数据上报 |

### 特征值摘要

| UUID | 名称 | 属性 | 说明 |
| --- | --- | --- | --- |
| `FFE1` | `Command` | `Write+Read` | 下发控制指令 |
| `FFE4` | `Status` | `Read + Notify` | 数据上报 |

> 注意：补充文档将 `FFE1` 同时写作“数据通信服务”和 `Command` 特征 UUID；这与当前代码中的 `FFE1` 服务、`FFE4` 命令特征、`FFE5` 状态特征不一致，需硬件侧确认最终 UUID 分配。

### Command 33 字节定义

| 字节 | 含义 |
| --- | --- |
| Byte1 | IO1 红灯光强 |
| Byte2 | IO1 红外灯光强 |
| Byte3 | IO1 紫外灯光强 |
| Byte4 | IO1 暖黄灯光强 |
| Byte5 | IO1 电流增益高字节 |
| Byte6 | IO1 电流增益低字节 |
| Byte7 | IO2 红灯光强 |
| Byte8 | IO2 红外灯光强 |
| Byte9 | IO2 紫外灯光强 |
| Byte10 | IO2 暖黄灯光强 |
| Byte11 | IO2 电流增益高字节 |
| Byte12 | IO2 电流增益低字节 |
| Byte13 | IO3 红灯光强 |
| Byte14 | IO3 红外灯光强 |
| Byte15 | IO3 紫外灯光强 |
| Byte16 | IO3 暖黄灯光强 |
| Byte17 | IO3 电流增益高字节 |
| Byte18 | IO3 电流增益低字节 |
| Byte19 | IO4 红灯光强 |
| Byte20 | IO4 红外灯光强 |
| Byte21 | IO4 紫外灯光强 |
| Byte22 | IO4 暖黄灯光强 |
| Byte23 | IO4 电流增益高字节 |
| Byte24 | IO4 电流增益低字节 |
| Byte25 | IO5 红灯光强 |
| Byte26 | IO5 红外灯光强 |
| Byte27 | IO5 紫外灯光强 |
| Byte28 | IO5 暖黄灯光强 |
| Byte29 | IO5 电流增益高字节 |
| Byte30 | IO5 电流增益低字节 |
| Byte31 | 保持时间高字节 |
| Byte32 | 保持时间低字节 |
| Byte33 | 异或校验 |

## 对当前实现的影响

当前小程序 BLE 实现位于 `miniprogram/services/ble/`。它采用的是帧协议：

```text
0xAA 0x55 | length | type | payload | XOR checksum
```

并且 `setParams()` 当前下发的 payload 是：

```text
region_mask | wavelength | brightness | duration_ms(4B) | mode | seq
```

补充文档描述的 Command 更像“裸 33 字节参数块”，没有出现 `0xAA 0x55` 帧头、命令 type、seq、ACK 或 `region_mask`。当前因赶进度先以该 33 字节协议为准，旧帧协议暂作为历史兼容代码保留。

主要差异如下：

| 项目 | 当前代码/文档 | 补充文档 | 影响 |
| --- | --- | --- | --- |
| 命令写入格式 | 帧格式 `0xAA55 + length + type + payload + checksum` | 33 字节参数块 | 需要确认设备固件实际接收哪一种格式 |
| 数据通信 UUID | `FFE1` 服务，`FFE4` 命令，`FFE5` 状态 | `FFE1` 服务/Command，`FFE4` Status | UUID 表存在冲突，需要硬件确认 |
| 治疗参数模型 | 区域 mask + 单一波长 + 全局亮度 | IO1-IO5 各自四种灯光强度 + 电流增益 | 当前 UI/协议无法表达每个 IO 的独立参数 |
| 时间字段 | `duration_ms` 4 字节大端毫秒 | 保持时间 2 字节 | 时间单位、范围、字节序均需确认 |
| 状态上报 | 当前解析 14 字节状态 | 仅说明“设备状态及 ADC 值” | 需要补齐 Status 字节表，尤其 ADC 字段 |
| 校验 | 当前 XOR 覆盖帧头/长度/type/payload | Byte33 为异或校验 | 需确认 Byte33 是否 XOR Byte1-Byte32 |

## 需要补充确认的问题

优先级从高到低：

1. `FFE1`、`FFE4`、`FFE5` 的最终含义：哪个是服务 UUID，哪个是 Command characteristic，哪个是 Status characteristic。
2. Command 写入时是否仍需要 `0xAA 0x55` 帧封装，还是直接写 33 字节参数块。
3. Byte33 XOR 校验范围：是否对 Byte1-Byte32 做 XOR，初始值是否为 `0x00`。
4. Byte31-Byte32 保持时间的单位：秒、100ms、分钟，或其他单位；以及字节序是否为高字节在前。
5. IO1-IO5 与面部区域/灯板通道的对应关系。
6. 红灯、红外、紫外、暖黄光强的取值范围和含义：是否为 PWM、百分比、DAC 值，范围是 `0-100` 还是 `0-255`。
7. 电流增益高/低字节的取值范围、字节序和单位。
8. Status/ADC 数据上报的完整字节布局：状态码、电量、温度、ADC 通道数、每通道字节序和单位。
9. 是否存在开始、停止、查询状态、绑定等命令字；如果没有，33 字节写入是否同时承担“设置参数并启动”的语义。
10. 是否需要 ACK/NACK；如果有，ACK 格式和错误码表是什么。

## 建议后续处理

- 当前已先接入 `buildVendorCommand33()`，由“区域 + 单一波长 + 全局亮度”生成 IO1-IO5 的默认 33 字节参数。
- 旧帧协议暂保留，后续如供应商补齐旧协议或要求兼容，可再做协议模式切换。
- 真机联调时优先抓取/打印实际写入的字节数组和 Status notify 原始数据，再补 Status/ADC 解析。