完整协议说明

1. 协议模式总览

本项目在同一条 BLE 透传链路上支持四种工作模式。模式由设置页 protocolMode 控制，通讯页和参数页会按当前模式切换 UI、参数分组和自动读取协议。

模式	key	通讯页	参数页	说明
无协议	`none`	串口发送卡片、日志卡片	不显示协议参数组	只做原始字节透传和日志观察
标准 Modbus	`modbus-rtu`	标准 Modbus 指令卡片、日志卡片	Modbus 寄存器组	使用从机地址、功能码和 Modbus CRC
存储访问	`storage-access`	同步、CodeInfo、特殊指令、读写卡片、日志卡片	存储访问结构体组/单变量组	按字节访问 DATA、IDATA、XDATA、CODE 或 32 位统一地址空间
Bootloader	设置页升级工具	Bootloader 工具卡片	不参与参数页	独立升级协议，不和 Modbus/存储访问混用

切换协议时，参数页会同步切换对应协议的分组集合。自动读取运行中如果检测到协议变化，会停止当前读取循环，避免用旧协议继续访问新模式下的参数组。

2. 公共链路规则

所有协议均通过 BLE 透传发送原始字节。发送队列、响应等待、日志和超时由 transport/ble-core.js 统一处理。

项目	规则
发送单位	原始字节数组
日志显示	HEX 或文本两种显示方式
响应识别	由 `protocols/transport-helpers.js` 根据待响应协议调用对应解析器
包长限制	设置页最大包长用于 Modbus 和存储访问分片，`0` 表示不限制
参数自动读取	由设置页“自动轮询”开关控制，参数页“读取”只执行一次全量读取

3. 无协议模式

无协议模式不解析帧格式，也不绑定参数页分组。

功能	行为
发送	通讯页原始串口发送卡片支持 HEX 或文本
日志	显示发送和接收日志
响应	不要求特定响应帧
参数页	不显示标准 Modbus 或存储访问参数组

适用场景：临时调试私有串口命令、观察设备透传输出、验证蓝牙链路连通性。

4. 标准 Modbus RTU

标准 Modbus 使用常规 RTU 帧格式：

SLAVE FUNC DATA... CRC_L CRC_H

CRC 使用 CRC16-Modbus，低字节在前。

参数	值
多项式	`0x8005` 反射形式
初值	`0xFFFF`
输入反转	是
输出反转	是
结果异或	`0x0000`
输出顺序	低字节在前

支持功能码：

功能码	名称	方向	参数页用途
`0x01`	读线圈	读	bit/coil 类型参数组
`0x02`	读离散输入	读	只读 bit 类型参数组
`0x03`	读保持寄存器	读	可读写寄存器组
`0x04`	读输入寄存器	读	只读寄存器组
`0x05`	写单线圈	写	单个 bit 写入
`0x06`	写单寄存器	写	单个 16 位寄存器写入
`0x10`	写多个寄存器	写	连续寄存器批量写入

数量限制按当前最大包长计算。默认 64 字节包长下，0x03/0x04 单帧最多读取 29 个寄存器，0x10 单帧最多写入 27 个寄存器。超过限制时参数页会按连续片段分片读取或写入。

异常响应格式：

SLAVE (FUNC | 0x80) EXCEPTION_CODE CRC_L CRC_H

标准 Modbus 与存储访问完全独立，不解析 CodeInfo TLV 信息块，也不使用存储访问的 CMD/AREA。

5. 存储访问协议

存储访问协议不带从机地址，不属于标准 Modbus。普通内存访问帧格式为：

CMD ADDR LEN DATA... CRC_H CRC_L

CRC 使用 CRC16-CCITT-FALSE，高字节在前。所有多字节协议字段均为大端序。

CMD 位定义：

bit7      ERR       异常标志
bit6      CTL       特殊指令标志位
bit5~bit4 RSV       保留，普通读写保持 0
bit3      RW        读写标志，0=读，1=写
bit2~bit0 MODE      地址模式或存储区域

地址模式与存储区域：

MODE	名称	地址宽度	读	写	说明
`0x00`	保留	-	禁止	禁止	保留
`0x01`	DATA	16 位	支持	支持	内部直接寻址 RAM
`0x02`	IDATA	16 位	支持	支持	内部间接寻址 RAM
`0x03`	XDATA	16 位	支持	支持	外部数据空间或扩展 RAM
`0x04`	CODE	16 位	支持	禁止	程序存储区
`0x05..0x06`	保留	-	禁止	禁止	保留
`0x07`	ADDR32	32 位	支持	支持	统一 32 位字节地址

普通读请求：

CMD ADDR_3 ADDR_2 ADDR_1 ADDR_0 LEN_H LEN_L CRC_H CRC_L
或
CMD ADDR_H ADDR_L LEN_H LEN_L CRC_H CRC_L

普通读响应回显 CMD、ADDR、LEN，然后携带 LEN 字节数据。

普通写请求：

CMD ADDR_3 ADDR_2 ADDR_1 ADDR_0 LEN_H LEN_L DATA... CRC_H CRC_L
或
CMD ADDR_H ADDR_L LEN_H LEN_L DATA... CRC_H CRC_L

普通写响应只回显 CMD、ADDR、LEN。写 CODE 区必须返回写保护异常。

特殊指令使用固定 CMD=0x4F：

请求: 4F OP DATA... CRC_H CRC_L
响应: 4F OP STATUS DATA... CRC_H CRC_L
异常: CF EXCEPTION_CODE CRC_H CRC_L

特殊指令表：

OP	名称	请求 DATA	成功响应 DATA	用途
`0x01`	RESET	无	无	复位
`0x02`	START	无	无	启动
`0x03`	STOP	无	无	停止
`0x04`	SET_CONTROL_REF	`REF_H REF_L`	无	控制参考值，`int16_t` 大端
`0x05`	READ_CODE_INFO_DESCRIPTOR	无	`CODE_ADDR32 + CODE_LEN16 + ADDR_WIDTH8 + MEMORY_ENDIAN16 + MAX_PACKET16`	读取 CodeInfo bootstrap 描述符

完整帧细节、异常码、示例和从机参考见 存储访问协议.md。

6. CodeInfo 与参数组同步

存储访问同步固定分两步：

发送特殊指令 4F 05 CRC_H CRC_L，读取 CodeInfo bootstrap 描述符。
根据 bootstrap 返回的 CODE_ADDR32 + CODE_LEN16 + ADDR_WIDTH8 + MEMORY_ENDIAN16 + MAX_PACKET16 读取完整 CodeInfo TLV 信息块。ADDR_WIDTH=32 使用 MODE=0x07 ADDR32，ADDR_WIDTH=16 使用 MODE=0x04 CODE；MAX_PACKET 非 0 时与设置页最大包长取较小值。

bootstrap 中 MEMORY_ENDIAN16 使用原始字节标记目标内存变量字节序：55 AA 表示变量值大端，AA 55 表示变量值小端。多字节协议控制字段始终固定大端，包括 CMD、ADDR、普通读写 LEN、CODE_LEN 和 MAX_PACKET；TLV LEN 为单字节字段，不涉及大小端。

CodeInfo 信息块使用纯 TLV 格式，不再包含固定头、format_version、board_info_format、struct_entry_len 或 struct_table：

TYPE LEN VALUE...

常用 TLV：

TYPE	名称	VALUE
`0x01`	`cave_freq`	`uint8_t`，KHz
`0x02`	`ref_volt`	`uint8_t`，实际参考电压乘 10
`0x03`	`amp_gain`	`uint8_t`
`0x04`	`rs_shunt`	`uint16_t`，mΩ
`0x05`	`bus_div`	`float32`，大端
`0x06`	`along_div`	`float32`，大端
`0x07`	`chip_model`	UTF-8 或 ASCII 字符串
`0x08`	`model`	UTF-8 或 ASCII 字符串
`0x20`	16 位地址结构体实例	`mem_type + byte_addr16 + byte_len16 + type_name`
`0x21`	16 位地址单独变量	`mem_type + byte_addr16 + byte_len16 + type_name`
`0x28`	32 位地址结构体实例	`byte_addr32 + byte_len16 + type_name`
`0x29`	32 位地址单独变量	`byte_addr32 + byte_len16 + type_name`

TLV LEN 为 1 字节，表示单项 VALUE 字节数；整段 CodeInfo 总长度仍由 bootstrap CODE_LEN16 决定。内存入口 TLV 的地址宽度由 TYPE 决定，bootstrap ADDR_WIDTH 只决定读取 CodeInfo 信息块本体时使用 16 位 CODE 地址还是 32 位统一地址。0x20/0x21 按 mem_type=0x01..0x04 使用 DATA/IDATA/XDATA/CODE，0x28/0x29 统一使用 MODE=0x07 ADDR32 且不携带 mem_type。

同步到参数页后的规则：

条件	处理
`TYPE=0x20/0x28` 且未导入结构体定义	创建结构体组，每个字节按 `00`、`01`、`02` 命名
`TYPE=0x20/0x28` 且导入定义名、长度匹配	按 C 结构体字段展示，保留多字节字段整体值；字段类型为 enum 时按枚举项显示
`TYPE=0x21/0x29`	创建单变量组，1/2/4 字节默认推断为 `uint8_t`、`uint16_t`、`uint32_t`；匹配 enum 后按枚举项显示
相同名称但地址或区域不同	视为不同参数组
当前已有同区域、同地址、同名称、同长度且已导入定义	保留当前导入结构，只更新同步来源信息
未知 TLV `TYPE`	跳过

结构体和 enum 可在同一个 .h/.c/.txt 定义文件中导入。单独变量的 enum 匹配支持两种方式：type_name 直接等于 enum 类型名，或导入文件中存在 EnumType variable_name; 且变量名等于 type_name。enum 只影响显示与输入映射，不改变底层字节读写协议。

CodeInfo 卡片始终显示在通讯页存储访问协议卡片内。板卡信息 TLV 不存在时对应字段不显示；电机型号优先按 UTF-8 解析，也兼容纯 ASCII。

7. 参数值与转换公式

参数页读回的数据先按字段类型解码为原始值，再根据可选转换公式显示实际值。公式由参数配置自定义，适合标幺值转实际值、比例缩放和偏置换算。

存储访问参数组的多字节变量值按 bootstrap MEMORY_ENDIAN 解码和写入。标准 Modbus 寄存器仍保持 Modbus 字/字节规则，不受该字段影响。

公式支持变量：

变量	含义
`x`、`value`、`rawValue`	当前字段原始值
`caveFreq`	CodeInfo 载波频率
`refVolt`	CodeInfo 参考电压实际值
`ampGain`	CodeInfo 运放倍数
`rsShunt`	CodeInfo 采样电阻
`busDiv`	CodeInfo 母线电压分压比
`alongDiv`	CodeInfo 模拟输入电压分压比
`maxPacketLength`	同步描述符声明的最大完整协议帧长度
`addressWidth`	同步描述符声明的地址长度
`memoryEndian`	同步 bootstrap 声明的目标内存变量字节序，`big` 或 `little`

公式只支持数字、括号和 + - * /，不执行任意脚本。

8. Bootloader 协议

Bootloader 协议用于固件升级，独立于标准 Modbus 和存储访问。帧头固定为：

46 54 PAYLOAD... CRC_H CRC_L

CRC 使用 CRC16-CCITT-FALSE，高字节在前。

主要命令：

命令	载荷	响应长度	用途
握手	`39 42 4C`	15	读取 Bootloader 版本和芯片 ID
解锁	`08 4E 00`	8	进入可编程状态
编程	`44 ADDR_L ADDR_H DATA(128B)`	8	写入 128 字节程序块
全 Flash 校验	`19 43 43`	9	读取 Flash 校验值
页擦除开关	`08 50 45/44`	8	开启或关闭页擦除
退出	`08 42 42`	8	退出 Bootloader

ACK 为 0x06，NAK 为 0x15。固件文件加载、芯片型号识别、升级地址和 Flash 容量由 features/bootloader/ 处理。

9. 维护约束

标准 Modbus、存储访问、Bootloader 分别只保留一个协议入口：protocols/modbus-rtu/index.js、protocols/storage-access/index.js、protocols/bootloader/index.js。
页面只负责 UI 展示和事件转发，不直接拼帧、不直接解析二进制响应。
通讯页业务聚合在 features/communication/，参数页业务聚合在 features/parameter-groups/，存储访问业务聚合在 features/storage-access/service.js。
可复用且有明确领域边界的逻辑保留在 domain/parameter-groups/ 和 domain/storage-access/。
不再为单个按钮、单个字段、单个导入步骤新增小模块；新增能力优先并入现有协议模块、功能服务或领域模型。

完整协议说明.md 12 KB History Raw