doc: 更新上位机协议, 增加数据长度

doc/HSJL 上位机串口通信协议.md

@@ -1,19 +1,25 @@
 # HSJL 上位机串口通信协议
 
-> 版本：v1.0
-> 日期：2025 年 6 月 5 日
+> 版本：v1.1
+> 日期：2025 年 6 月 10 日
 
 ---
 
 ## 总览
 
+HSL 上位机服务于 HSJL 演示验证，用于演示 3 节点组网通信功能（1 个主节点，2 个从节点）。
+
 - 物理接口：UART（串口通信）
 - 通信方式：PC 主动下发控制帧，节点响应或上传数据
 - 支持功能：
-  - 指令控制
-  - 图像数据传输
-  - 节点遥测与状态上报
-
+  - 状态查询：查询板卡的硬件状态
+  - 指令控制：业务速率切换、节点角色切换、时隙表切换等
+  - 图像数据传输：
+    - 业务部分 Payload 为图像数据，数据流向为 PC 下发 → 空口发送 → 空口接收 → 节点上传。
+    - 对于较大的图片，需要 PC 进行数据包切割与重组。
+    - 业务流向为主-从双向，主节点需要向不同从节点发送数据，不同从节点也会给主节点发送数据。
+  - （可选）节点遥测：读取节点工作状态日志，并进行存储。
+  
 - UART 串口配置
 
   | 参数     | 配置值     |
@@ -28,14 +34,20 @@
 
 每帧数据通过串口独立传输，格式如下：
 
+``` mermaid
+block-beta
+  columns 6
+  a["帧头"] b["数据段"] c["Dummy Byte"] d["校验和"] e["数据段长度"] f["帧尾"]
 ```
-[帧头][数据段][Dummy Byte][校验和][数据长度][帧尾]
+
+```
+[帧头][数据段][Dummy Byte][校验和][数据段长度][帧尾]
 ```
 
 | 字段名     | 字节数 (Byte) | 说明 |
 |--|--|--|
 | 帧头       | 2 | 固定值：`0x5A 0x54` |
-| 数据段    | ≤1000 | 业务数据内容 |
+| 数据段    | ≤950 | 业务数据内容 |
 | Dummy Byte | 1 | 固定填充：`0x00` |
 | 校验和     | 1 | 所有**数据段**字节累加和（无符号累加） |
 | 数据段长度 | 2 | 数据段字节数（不含 Dummy/校验/帧尾） |
@@ -57,6 +69,14 @@
 
 数据段格式如下，下发（PC→节点）和上传（节点→PC）均使用一致的格式：
 
+``` mermaid
+block-beta
+  columns 8
+  HEAD["帧头"]:1 DATA["数据段"]:3 DUMMY["Dummy Byte"]:1 CHECKSUM["校验和"]:1 LENGTH["数据段长度"]:1 TAIL["帧尾"]:1
+  
+  NULL11[" "]:1 CMD["指令"]:1 TYPE["节点类型"]:1 PAYLOAD["Payload"]:1 NULL12[" "]:1 NULL13[" "]:1 NULL14[" "]:1 NULL15[" "]:1
+```
+
 ```
 [指令][节点类型][Payload]
 ```
@@ -65,18 +85,18 @@
 | -------- | ------------- | ---------------- |
 | 指令     | 1             | 控制指令         |
 | 节点类型 | 1             | 固定填充：`0xEE` |
-| Payload  | ≤1000         | 由指令类型决定   |
+| Payload  | ≤950          | 由指令类型决定   |
 
 指令类型如下：
 
 | 指令   | 含义                  | 下发 Payload 长度 (Byte) | 上传 Payload 长度 (Byte) |
 | ------ | --------------------- | ------------------------ | ------------------------ |
 | `0xE1` | 自检                  | 0, payload 无数据        | 21                       |
-| `0xE2` | Echo 测试             | ≤1000                    | 与下发长度一致           |
+| `0xE2` | Echo 测试             | ≤950                     | 与下发长度一致           |
 | `0xE3` | 节点配置              | 4                        | None，无上传             |
 | `0x33` | 系统信息 (目前可忽略) | 54                       | None，无上传             |
-| `0xE4` | 发送数据下发          | ≤1000                    | None，无上传             |
-| `0xE5` | 接收数据上传          | None，无下发，自动上传   | ≤1000                    |
+| `0xE4` | 发送数据下发          | ≤950                     | None，无上传             |
+| `0xE5` | 接收数据上传          | None，无下发，自动上传   | ≤950                     |
 | `0xE6` | 遥测                  | 0, payload 无数据        | 188                      |
 
 ### 自检指令
@@ -104,28 +124,73 @@
 
 ### Echo 测试
 
-Echo 测试中节点将 PC 下发的数据直接回传，不做其他处理。
+Echo 测试中节点将 PC 下发的数据直接回传，不做其他处理。Echo 测试数据的 Payload 格式如下，顺序存储，长度可变。
+
+| 字段名   | 字节数 (Byte) | 说明                   |
+| -------- | ------------- | ---------------------- |
+| 数据长度 | 2             | 数据字节数             |
+| 数据     | ≤950          | 长度由数据长度字段决定 |
 
 ### 节点配置指令
 
-节点配置指令下发的 Payload 格式如下，顺序存储，共 19 字节：
+节点配置指令下发的 Payload 格式如下，顺序存储，共 4 字节：
 
-| 字段名     | 字节数 (Byte) | 说明                                                        |
-| ---------- | ------------- | ----------------------------------------------------------- |
-| 节点使能   | 1             | `0xAA`: 启用<br />`0x55`: 停用                              |
-| 节点角色   | 1             | `0x11`: 簇首<br />`0x00`: 成员                              |
-| 业务速率   | 1             | `0x22`:  128 kbps<br />`0x33`: 256 kbps<br />`0x44`: 2 Mbps |
-| 时隙表编号 | 1             | 编号值，0~2                                                 |
+| 字段名               | 字节数 (Byte) | 说明                                                       |
+| -------------------- | ------------- | ---------------------------------------------------------- |
+| 节点使能             | 1             | `0xAA`: 启用<br />`0x55`: 停用                             |
+| 节点 ID              | 1             | `0x00`: 簇首<br />`0x01`~`0x09`: 成员                      |
+| 业务速率             | 1             | `0x22`: 128 kbps<br />`0x33`: 256 kbps<br />`0x44`: 2 Mbps |
+| 时隙表编号（可扩展） | 1             | 编号值，0~2（可扩展）                                      |
+
+> [!warning]
+>
+> 时隙表单次运行周期为 500 ms，不同时隙表中主从节点数据交互次数、可用从节点 ID 范围不同，**从节点只与主节点进行通信**，目前暂定时隙表如下：
+>
+> - 0 号时隙表，主节点分别给 2 个从节点发送 1 次；每个从节点给主节点发送 1 次。
+> - 1 号时隙表，主节点分别给 2 个从节点发送 5 次；每个从节点给主节点发送 5 次。
+> - 2 号时隙表，待定。
 
 ### 发送数据下发
 
-需注意整个 UART 帧的长度（包括帧头、数据段、Dummy、校验和、数据段长度、帧尾）不超过 1024 Byte。
+发送数据的 Payload 格式如下，顺序存储，长度可变。
+
+```mermaid
+block-beta
+  columns 11
+  HEAD["帧头"]:1 DATA_CHUNK["数据段"]:6 DUMMY["Dummy Byte"]:1 CHECKSUM["校验和"]:1 LENGTH["数据段长度"]:1 TAIL["帧尾"]:1
+  
+  NULL11[" "]:1 CMD["指令"]:1 TYPE["节点类型"]:1 PAYLOAD["Payload"]:4 NULL12[" "]:1 NULL13[" "]:1 NULL14[" "]:1 NULL15[" "]:1
+  
+  NULL21[" "]:1 NULL22[" "]:1 NULL23[" "]:1 DATAID["数据 ID"]:1 DSTID["目的节点 ID"]:1 D_LEN["数据长度"]:1 DATA["数据"]:1 NULL24[" "]:1 NULL25[" "]:1 NULL26[" "]:1 NULL27[" "]:1
+```
+
+| 字段名      | 字节数 (Byte) | 说明                    |
+| ----------- | ------------- | ----------------------- |
+| 数据 ID     | 4             | 数据编号                |
+| 目的节点 ID | 1             | 消息目的节点 ID         |
+| 数据长度    | 2             | 数据长度（不含数据 ID） |
+| 数据        | ≤950          | 长度由数据长度字段决定  |
+
+> [!Warning]
+>
+> 1. 需注意整个 [UART 帧](#UART 帧结构定义)的长度（包括帧头、数据段、Dummy、校验和、数据段长度、帧尾）不超过 1024 Byte。
+> 2. 数据最大长度同时由业务速率档位决定：
+>    - 128 kbps 档位：数据长度最大为 42 Byte。
+>    - 512 kbps 档位：数据长度最大为 267 Byte。
+>    - 2 Mbps 档位：数据长度最大为 1222 Byte，但是受限于 PL buffer 的长度，[UART 帧](#UART 帧结构定义)的长度不超过 1024 Byte。
 
 ### 接收数据上传
 
-接收到的数据将自动打包上传，无需下发指令。
+接收到的数据将自动打包上传，无需下发指令。接收数据的 Payload 格式与发送的格式一致，顺序存储，长度可变。
 
-### 遥测指令
+| 字段名    | 字节数 (Byte) | 说明                    |
+| --------- | ------------- | ----------------------- |
+| 数据 ID   | 4             | 数据编号                |
+| 源节点 ID | 1             | 消息来源节点 ID         |
+| 数据长度  | 2             | 数据长度（不含数据 ID） |
+| 数据      | ≤950          | 长度由数据长度字段决定  |
+
+### （可选）遥测指令
 
 遥测指令上传的 Payload 由 5 部分组成，顺序存储，共 188 字节：