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

# HSJL 上位机串口通信协议

> 版本：v1.2
> 日期：2025 年 6 月 16 日

---

## 总览

HSL 上位机服务于 HSJL 演示验证，用于演示 3 节点组网通信功能（1 个主节点，2 个从节点）。

- 物理接口：UART（串口通信）
- 通信方式：PC 主动下发控制帧，节点响应或上传数据
- 支持功能：
  - 状态查询：查询板卡的硬件状态
  - 指令控制：业务速率切换、节点角色切换、时隙表切换等
  - 图像数据传输：
    - 业务部分 Payload 为图像数据，数据流向为 PC 下发 → 空口发送 → 空口接收 → 节点上传。
    - 对于较大的图片，需要 PC 进行数据包切割与重组。
    - 业务流向为主-从双向，主节点需要向不同从节点发送数据，不同从节点也会给主节点发送数据。
  - （可选）节点遥测：读取节点工作状态日志，并进行存储。
  
- UART 串口配置

  | 参数     | 配置值     |
  |----------|------------|
  | 波特率   | 460800 |
  | 数据位   | 8          |
  | 停止位   | 1          |
  | 校验位   | 无         |
  | 流控     | 无         |

## UART 帧结构定义

每帧数据通过串口独立传输，格式如下：

``` mermaid
block-beta
  columns 6
  a["帧头"] b["数据段"] c["Dummy Byte"] d["校验和"] e["数据段长度"] f["帧尾"]
```

```
[帧头][数据段][Dummy Byte][校验和][数据段长度][帧尾]
```

| 字段名     | 字节数 (Byte) | 说明 |
|--|--|--|
| 帧头       | 2 | 固定值：`0x5A 0x54` |
| 数据段    | ≤950 | 业务数据内容 |
| Dummy Byte | 1 | 固定填充：`0x00` |
| 校验和     | 1 | 所有**数据段**字节累加和（无符号累加） |
| 数据段长度 | 2 | 数据段字节数（不含 Dummy/校验/帧尾） |
| 帧尾       | 2 | 固定值：`0x5A 0xFE` |

### 帧内冲突规避规则

为防止数据段中出现帧尾 `0x5A 0xFE`：

- 若数据段中出现 `0x5A 0xFE`，需插入 `0x00` 变成 `0x00 0x5A 0xFE`
- 接收端收到 `0x00 0x5A 0xFE` 还原为 `0x5A 0xFE`

### 帧长说明

- 数据段长度包括避免冲突填充的`0x00`
- 整个 UART 帧的长度（包括帧头、数据段、Dummy、校验和、数据段长度、帧尾）不超过 1024 Byte

## 数据段指令格式定义

数据段格式如下，下发（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]
```

| 字段名   | 字节数 (Byte) | 说明             |
| -------- | ------------- | ---------------- |
| 指令     | 1             | 控制指令         |
| 节点类型 | 1             | 固定填充：`0xEE` |
| Payload  | ≤950          | 由指令类型决定   |

指令类型如下：

| 指令   | 含义                  | 下发 Payload 长度 (Byte) | 上传 Payload 长度 (Byte) |
| ------ | --------------------- | ------------------------ | ------------------------ |
| `0xE1` | 自检                  | 0, payload 无数据        | 21                       |
| `0xE2` | Echo 测试             | ≤950                     | 与下发长度一致           |
| `0xE3` | 节点配置              | 4                        | None，无上传             |
| `0x33` | 系统信息 (目前可忽略) | 54                       | None，无上传             |
| `0xE4` | 发送数据下发          | ≤950                     | None，无上传             |
| `0xE5` | 接收数据上传          | None，无下发，自动上传   | ≤950                     |
| `0xE6` | 遥测                  | 0, payload 无数据        | 188                      |

### 自检指令

自检指令上传的 Payload 格式如下，顺序存储，共 21 字节：

| 字段名                | 字节数 (Byte) | 说明                                                         |
| --------------------- | ------------- | ------------------------------------------------------------ |
| 节点状态              | 1             | `0xAA`: 正常<br />`0x55`: 异常                               |
| FPGA 电压状态         | 1             | `[0]`: VCCPINT 电源轨道状态<br />`[1]`: VCCPAUX 电源轨道状态<br />`[2]`: VCCO_DDR 电源轨道状态<br />`[3]`: VCCINT 电源轨道状态<br />`[4]`: VCCAUX 电源轨道状态<br />`[5]`: VCCBRAM 电源轨道状态<br />以上 `1` 表示正常，`0` 表示异常 |
| 时钟芯片锁定状态      | 1             | `[0]`:  PLL1 锁定状态<br />`[2]`: PLL2 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| (未使用) ADC 锁定状态 | 1             | `[0]`: AD-1 BBPLL 锁定状态<br />`[2]`: AD-2 BBPLL 锁定状态<br />`[4]`: AD-1 RFPLL 锁定状态<br />`[6]`: AD-2 RFPLL 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| (未使用) ADC-1 温度   | 1, int8       | 温度值，有符号数                                             |
| (未使用) ADC-2 温度   | 1, int8       | 温度值，有符号数                                             |
| FPGA 温度             | 1, int8       | 温度值，有符号数                                             |
| 天线 -1 频率          | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 -2 频率          | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 -3 频率          | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 PLL 锁定状态     | 1             | `[5]`: 天线-1-PLL1 锁定状态<br />`[4]`: 天线-1-PLL2 锁定状态<br />`[3]`: 天线-2-PLL1 锁定状态<br />`[2]`: 天线-2-PLL2 锁定状态<br />`[1]`: 天线-3-PLL1 锁定状态<br />`[0]`: 天线-3-PLL2 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| 天线工作状态          | 1             | `[2]`: 天线-3 工作状态<br />`[1]`: 天线-2 工作状态<br />`[0]`: 天线-1 工作状态<br />以上 `1` 表示抗干扰模式，`0` 表示普通模式 |
| 天线温度              | 1, int8       | 温度值，有符号数                                             |
| 天线状态预留          | 1             | 预留                                                         |
| 物理层配置 ID         | 1             | 节点 ID，用于区分物理层配置                                  |
| 额外控制预留          | 3             | 预留                                                         |

### Echo 测试

Echo 测试中节点将 PC 下发的数据直接回传，不做其他处理。Echo 测试数据的 Payload 格式如下，顺序存储，长度可变。

| 字段名   | 字节数 (Byte) | 说明                   |
| -------- | ------------- | ---------------------- |
| 数据长度 | 2             | 数据字节数             |
| 数据     | ≤950          | 长度由数据长度字段决定 |

### 节点配置指令

节点配置指令下发的 Payload 格式如下，顺序存储，共 4 字节：

| 字段名               | 字节数 (Byte) | 说明                                                       |
| -------------------- | ------------- | ---------------------------------------------------------- |
| 节点使能             | 1             | `0xAA`: 启用<br />`0x55`: 停用                             |
| 节点 ID              | 1             | `0x01`: 簇首<br />`0x02`~`0x0A`: 成员                      |
| 业务速率             | 1             | `0x22`: 128 kbps<br />`0x33`: 256 kbps<br />`0x44`: 2 Mbps |
| 时隙表编号（可扩展） | 1             | 编号值，0~2（可扩展）                                      |

> [!warning]
>
> 时隙表单次运行周期为 250 ms，不同时隙表中主从节点数据交互次数、可用从节点 ID 范围不同，**从节点只与主节点进行通信**，目前暂定时隙表如下：
>
> - 0 号时隙表，主节点分别给 2 个从节点发送 1 次；每个从节点给主节点发送 1 次。
> - 1 号时隙表，主节点分别给 2 个从节点发送 4 次；每个从节点给主节点发送 4 次。
> - 2 号时隙表，待定。

### 发送数据下发

发送数据的 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 档位：数据长度最大为 40 Byte。
>    - 512 kbps 档位：数据长度最大为 265 Byte。
>    - 2 Mbps 档位：数据长度最大为 1220 Byte，但是受限于 PL buffer 的长度，[UART 帧](#UART 帧结构定义)的长度不超过 1024 Byte。

### 接收数据上传

接收到的数据将自动打包上传，无需下发指令。接收数据的 Payload 格式与发送的格式一致，顺序存储，长度可变。

| 字段名    | 字节数 (Byte) | 说明                    |
| --------- | ------------- | ----------------------- |
| 数据 ID   | 4             | 数据编号                |
| 源节点 ID | 1             | 消息来源节点 ID         |
| 数据长度  | 2             | 数据长度（不含数据 ID） |
| 数据      | ≤950          | 长度由数据长度字段决定  |

### （可选）遥测指令

遥测指令上传的 Payload 由 5 部分组成，顺序存储，共 200 字节：

| 字段名       | 字节数 (Byte) |
| ------------ | ------------- |
| 时间戳       | 8             |
| 总线日志     | 16            |
| 链路层日志   | 100           |
| 物理层日志   | 56            |
| 硬件状态日志 | 20            |

#### 时间戳

时间戳是一个 64-bit 计数器，每一位代表 10 ns。

#### 总线日志

总线日志顺序存储，共 16 字节：

| 字段名         | 字节数 (Byte) | 说明                         |
| -------------- | ------------- | ---------------------------- |
| 节点配置记录   | 4             | 记录上一次节点配置指令       |
| 接收数据包计数 | 4             | 每接收一包数据，计数器+1     |
| 发送数据包计数 | 4             | 每发送一包数据，计数器+1     |
| 遥测请求计数   | 4             | 每收到一次遥测请求，计数器+1 |

#### 链路层日志

链路层日志顺序存储，共 100 字节：

| 字段名               | 字节数 (Byte) | 说明                                     |
| -------------------- | ------------- | ---------------------------------------- |
| 时元号               | 4             | 250 ms per LSB                           |
| 时隙号               | 1             | 2 ms per LSB                             |
| 节点类型             | 1             | `0xAA`: 簇首<br />`0xCC`: 成员           |
| 在网状态             | 1             | `0x11`: 在网<br />`0x00`: 断网           |
| 工作状态             | 1             | `0x11`: 建网状态<br />`0x22`: 正常运行   |
| 重连计数器           | 4             | 每断网重连一次，计数器+1                 |
| 天线编号             | 1             | 当前工作的天线编号                       |
| 建网帧发送计数器     | 4             | 每发送一次建网帧，计数器+1（仅簇首）     |
| 建网帧接收计数器     | 4             | 每配置接收一次建网帧，计数器+1（仅成员） |
| 建网帧接收正确计数器 | 4             | 每正确接收一次建网帧，计数器+1（仅成员） |
| 应答帧发送计数器     | 4             | 每发送一次应答帧，计数器+1（仅成员）     |
| 应答帧接收计数器     | 4             | 每配置接收一次应答帧，计数器+1（仅簇首） |
| 应答帧接收正确计数器 | 4             | 每正确接收一次应答帧，计数器+1（仅簇首） |
| 分发帧发送计数器     | 4             | 每发送一次分发帧，计数器+1（仅簇首）     |
| 分发帧接收计数器     | 4             | 每配置接收一次分发帧，计数器+1（仅成员） |
| 分发帧接收正确计数器 | 4             | 每正确接收一次分发帧，计数器+1（仅成员） |
| 网管帧发送计数器     | 4             | 每发送一次网管帧，计数器+1               |
| 网管帧接收计数器     | 4             | 每配置接收一次网管帧，计数器+1           |
| 网管帧接收正确计数器 | 4             | 每正确接收一次网管帧，计数器+1           |
| RTT帧发送计数器      | 4             | 每发送一次 RTT 帧，计数器+1              |
| RTT帧接收计数器      | 4             | 每配置接收一次 RTT 帧，计数器+1          |
| RTT帧接收正确计数器  | 4             | 每正确接收一次 RTT 帧，计数器+1          |
| 业务帧发送计数器     | 4             | 每发送一次业务帧，计数器+1               |
| 业务帧接收计数器     | 4             | 每配置接收一次业务帧，计数器+1           |
| 业务帧接收正确计数器 | 4             | 每正确接收一次业务帧，计数器+1           |
| 时间偏移量记录       | 4, int32      | 记录上一次节点时间和帧同步时间的偏差     |
| 发送数据ID记录       | 4             | 记录上一次发送数据的ID                   |
| 接收数据ID记录       | 4             | 记录上一次接收数据的ID                   |
| 预留                 | 3             | 预留                                     |

#### 物理层日志

物理层日志顺序存储，共 56 字节：

| 字段名         | 字节数 (Byte) | 说明                          |
| -------------- | ------------- | ----------------------------- |
| 捕获计数器     | 4             | 每捕获成功一次，计数器+1      |
| 帧同步计数器   | 4             | 每帧同步成功一次，计数器+1    |
| 译码计数器     | 4             | 每译码成功一次，计数器+1      |
| CRC 计数器     | 4             | 每 CRC 校验通过一次，计数器+1 |
| 多普勒估计     | 8, double     | 记录上一次多普勒估计结果      |
| 帧同步时间     | 8             | 记录上一次帧同步时间          |
| 捕获峰均比     | 8, double     | 记录上一次捕获峰均比          |
| 捕获码相位估计 | 1             | 记录上一次码相位估计结果      |
| 捕获频偏估计   | 1             | 记录上一次频偏估计结果        |
| 帧同步峰均比   | 8, double     | 记录上一次帧同步峰均比        |
| 帧同步频偏估计 | 1             | 记录上一次帧同步频偏通道      |
| 解交织幅度估计 | 2             | 记录解交织幅度估计            |
| 天线控制模式   | 1             | 记录天线控制模式              |
| 预留           | 2             | 预留                          |

#### 硬件状态日志

硬件状态日志与自检回令基本一致，顺序存储，共20 字节：

| 字段名                    | 字节数 (Byte) | 说明                                                         |
| ------------------------- | ------------- | ------------------------------------------------------------ |
| FPGA 电压状态             | 1             | `[0]`: VCCPINT 电源轨道状态<br />`[1]`: VCCPAUX 电源轨道状态<br />`[2]`: VCCO_DDR 电源轨道状态<br />`[3]`: VCCINT 电源轨道状态<br />`[4]`: VCCAUX 电源轨道状态<br />`[5]`: VCCBRAM 电源轨道状态<br />以上 `1` 表示正常，`0` 表示异常 |
| (未使用) 时钟芯片锁定状态 | 1             | `[0]`:  PLL1 锁定状态<br />`[2]`: PLL2 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| (未使用) ADC 锁定状态     | 1             | `[0]`: AD-1 BBPLL 锁定状态<br />`[2]`: AD-2 BBPLL 锁定状态<br />`[4]`: AD-1 RFPLL 锁定状态<br />`[6]`: AD-2 RFPLL 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| (未使用) ADC-1 温度       | 1, int8       | 温度值，有符号数                                             |
| (未使用) ADC-2 温度       | 1, int8       | 温度值，有符号数                                             |
| FPGA 温度                 | 1, int8       | 温度值，有符号数                                             |
| 天线 -1 频率              | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 -2 频率              | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 -3 频率              | 2             | `[15]`: 乒乓环工作指示，`1` 表示 PLL1 工作，`0` 表示 PLL2 工作<br />`[14:0]`: 频率，对应实际频率需要+3700 MHz |
| 天线 PLL 锁定状态         | 1             | `[5]`: 天线-1-PLL1 锁定状态<br />`[4]`: 天线-1-PLL2 锁定状态<br />`[3]`: 天线-2-PLL1 锁定状态<br />`[2]`: 天线-2-PLL2 锁定状态<br />`[1]`: 天线-3-PLL1 锁定状态<br />`[0]`: 天线-3-PLL2 锁定状态<br />以上 `1` 表示锁定，`0` 表示失锁 |
| 天线工作状态              | 1             | `[2]`: 天线-3 工作状态<br />`[1]`: 天线-2 工作状态<br />`[0]`: 天线-1 工作状态<br />以上 `1` 表示抗干扰模式，`0` 表示普通模式 |
| 天线温度                  | 1, int8       | 温度值，有符号数                                             |
| 天线状态预留              | 1             | 预留                                                         |
| 物理层配置 ID             | 1             | 节点 ID，用于区分物理层配置                                  |
| 额外控制预留              | 3             | 预留                                                         |