ch32v307_camera/doc/设计文档/对接集成指南.md

# 对接集成指南

> 文档版本：1.0 · 日期：2026-03-15 · 适用对象：ConfigServer 开发方
>
> 本文档描述如何对接 CH32V307 红外采集端，内容直接来源于固件代码，无需阅读源码即可完成对接开发。

---

## 1. 网络接入参数

### 1.1 固定参数

| 参数 | 值 |
|------|-----|
| MCU IP | `192.168.7.10` |
| MCU 子网掩码 | `255.255.255.0` |
| MCU 网关 | `192.168.7.1` |
| 以太网规格 | 1000M RGMII（标准以太网帧） |

### 1.2 服务端监听要求

Server 端需在 **192.168.7.50** 上监听两个 TCP 端口（MCU 主动连入）：

| 端口 | 用途 | 连接方向 |
|------|------|---------|
| **5511** | 控制流（握手/配置/心跳） | MCU → Server |
| **5512** | 数据流（温度帧上报） | MCU → Server |

> 两个连接均为 MCU 主动发起，Server 侧需以 TCP Server（Listen）模式等待。

---

## 2. 握手流程

MCU 上电并完成内部初始化后，按以下顺序建立连接：

```
1. MCU 建立控制流 TCP 连接（Server 5511）
        │
        ↓
2. MCU 发送 TYPE_HANDSHAKE（Class=CLASS_SYSTEM=0x04）
   Value 结构（Handshake_t，46 字节）：
        ├─ ProtocolVersion: uint16_t = 0x0200（协议 v2.0）
        ├─ DeviceUUID[16]:  6 字节 MAC 地址填入前 6 字节，其余填 0
        ├─ AuthToken[16]:   全零（当前版本不鉴权）
        ├─ HardwareVersion[8]: "CH32V307"（参考）
        └─ FirmwareVersion[8]: 固件版本号
        │
        ↓
3. Server 回复握手响应（同类型或 TYPE_ACK_PAYLOAD）
   MCU 收到响应后标记控制流"就绪"
        │
        ↓
4. MCU 建立数据流 TCP 连接（Server 5512）
        │
        ↓
5. 系统就绪，开始接受配置并上报数据
```

**重要**：握手完成前，MCU 不会上报任何温度帧。如 Server 长时间未收到数据，请检查握手响应是否正确发送。

---

## 3. 配置下发

配置通过**控制流（5511）**发送，支持三种配置类型，可单独或组合发送。

### 3.1 Config2D — 2D 触发模式配置

**帧格式**：FrameHeader（Class=0x01, Type=0x22）+ TLV + Config2D_t

Config2D_t 全字段（按结构体内存顺序，均小端序）：

| 字段 | 类型 | 偏移 | 说明 | 推荐初始值 |
|------|------|------|------|-----------|
| `Enabled` | uint8_t | 0 | 1=启用 2D 模式，0=禁用 | 1 |
| `IsLive` | uint8_t | 1 | 保留，填 0 | 0 |
| `DeviceId` | uint16_t | 2 | 设备 ID | 0 |
| `Width` | uint16_t | 4 | 传感器宽度（256） | 256 |
| `Height` | uint16_t | 6 | 传感器高度（192） | 192 |
| `Fps` | uint8_t | 8 | 期望帧率（参考值，DVP 硬件控制） | 25 |
| `Exposure` | uint32_t | 9 | 曝光时间（传感器支持时有效） | 0 |
| `AutoExposure` | uint8_t | 13 | 自动曝光（0/1） | 0 |
| `MaskEnabled` | uint8_t | 14 | 掩码使能 | 0 |
| `MaskThreshold` | int16_t | 15 | 掩码阈值（0.1°C/LSB） | 0 |
| `MaskWidth` | uint16_t | 17 | 掩码宽度 | 0 |
| `MaskHeight` | uint16_t | 19 | 掩码高度 | 0 |
| `Angle` | int16_t | 21 | 旋转角度（当前未使用） | 0 |
| `TargetWidth` | uint16_t | 23 | 输出 ROI 宽度（像素） | 64 |
| `TargetHeight` | uint16_t | 25 | 输出 ROI 高度（像素） | 64 |
| `TriggerMode` | uint8_t | 27 | **0=内部温度触发，1=外部 GPIO 触发** | 1 |
| `TriggerGpioLine` | uint8_t | 28 | 外部触发 GPIO 编号（参考，MCU 固定 PA15） | 0 |
| `TriggerDelayMs` | uint16_t | 29 | 触发后延迟采集的时间（ms） | 0 |
| `TriggerBurstCount` | uint8_t | 31 | 每次触发连拍帧数 | 3 |
| `TriggerInternalIntervalMs` | uint16_t | 32 | 连拍帧间隔（ms） | 200 |
| `TriggerTemperatureThreshold` | int16_t | 34 | 内部触发温度阈值（0.1°C/LSB），如 `800` = 80.0°C | 800 |
| `TriggerDebounceIntervalMs` | uint16_t | 36 | 外部触发防抖时间（ms） | 50 |
| `TriggerCondition` | uint8_t | 38 | 内部触发判据：**0=ROI 均值，1=ROI 最大值** | 1 |
| `TriggerRoiX` | uint16_t | 39 | 触发检测 ROI 左上角 X | 0 |
| `TriggerRoiY` | uint16_t | 41 | 触发检测 ROI 左上角 Y | 0 |
| `TriggerRoiW` | uint16_t | 43 | 触发检测 ROI 宽度（0=全帧） | 256 |
| `TriggerRoiH` | uint16_t | 45 | 触发检测 ROI 高度（0=全帧） | 192 |
| `NGioDelay` | uint16_t | 47 | NG 输出 GPIO 脉宽（ms） | 200 |
| `OutputGpioLine` | uint8_t | 49 | 输出 GPIO 编号（固定 PA8） | 0 |
| `AlarmGpioLine` | uint8_t | 50 | 告警 GPIO（当前未使用） | 0 |
| `AlarmHoldMs` | uint16_t | 51 | 告警持续时间（当前未使用） | 0 |
| `StoreNgImagesOnly` | uint8_t | 53 | 仅存储 NG 图像（当前未使用） | 0 |
| `TrainingEnabled` | uint8_t | 54 | 训练模式（当前未使用） | 0 |
| `TrainingSampleThreshold` | uint16_t | 55 | 训练样本阈值（当前未使用） | 0 |
| `ProcessingTimeoutMs` | uint16_t | 57 | 处理超时（ms，当前未使用） | 0 |
| `MaxProcessingQueueSize` | uint8_t | 59 | 最大处理队列（当前未使用） | 0 |
| `Reserved` | uint8_t | 60 | 保留，填 0 | 0 |

### 3.2 Config1D — 1D 采集模式配置

**帧格式**：FrameHeader（Class=0x01, Type=0x23）+ TLV + Config1D_t

Config1D_t 全字段：

| 字段 | 类型 | 偏移 | 说明 | 推荐初始值 |
|------|------|------|------|-----------|
| `Enabled` | uint8_t | 0 | 1=启用 1D 模式，0=禁用 | 0 |
| `RunMode` | uint8_t | 1 | **0=停止采集，1=运行** | 1 |
| `TriggerType` | uint8_t | 2 | **1=内部（连续热帧），2=外部（PA15 GPIO）** | 1 |
| `BufferSize` | uint16_t | 3 | 采集缓冲区大小（样本数，最大 512） | 200 |
| `TriggerTempLimit` | int16_t | 5 | 触发温度阈值（0.1°C/LSB） | 500 |
| `StartPointsToRemove` | uint16_t | 7 | 保留 | 0 |
| `ReferenceLength` | uint16_t | 9 | 参考长度（保留） | 0 |
| `HighTimerLimit` | uint16_t | 11 | 外部触发防抖等待时间（ms） | 100 |
| `TimerCLimit` | uint16_t | 13 | 保留 | 0 |
| `NgCountLimit` | uint8_t | 15 | 触发后连续低温帧数达此值则停止采集 | 5 |
| `LSizeStart` | uint16_t | 16 | 发送时去掉头部样本数（切片） | 0 |
| `RSizeStart` | uint16_t | 18 | 发送时去掉尾部样本数（切片） | 0 |
| `NGioDelay` | uint16_t | 20 | NG 输出脉宽（ms，1D 使用） | 200 |
| `OutputGpioLine` | uint8_t | 22 | 输出 GPIO（固定 PA8） | 0 |
| `AlarmGpioLine` | uint8_t | 23 | 告警 GPIO（未使用） | 0 |
| `AlarmHoldMs` | uint16_t | 24 | 告警持续（未使用） | 0 |

> **2D 与 1D 互斥**：`Config2D.Enabled=1` 时 MCU 进入 2D 模式；`Config1D.Enabled=1` 且 `Config2D.Enabled=0` 时进入 1D 模式。同时置 1 时 2D 优先。

---

## 4. 温度帧接收

温度帧通过**数据流（5512）**接收，帧类型为 `TYPE_TEMP_FRAME(0x10)`，Class=`CLASS_DATA(0x02)`。

### 4.1 2D 温度帧解析

Value 布局（TemperatureFrameHeader_t + 像素数组）：

```
[TemperatureFrameHeader_t] 18 字节
    ├─ FrameNumber: uint32_t LE  — 帧序号（与 DVP 帧计数对应）
    ├─ Width:       uint16_t LE  — 输出 ROI 宽度（TargetWidth 或有效宽度）
    ├─ Height:      uint16_t LE  — 输出 ROI 高度
    ├─ MinTemp:     int16_t LE   — ROI 内最低温度（0.1°C/LSB）
    ├─ MaxTemp:     int16_t LE   — ROI 内最高温度（0.1°C/LSB）
    ├─ AvgTemp:     int16_t LE   — ROI 内平均温度（0.1°C/LSB）
    ├─ RoiTemp:     int16_t LE   — TriggerRoi 区域特征温度（0.1°C/LSB）
    ├─ FrameType:   uint8_t      — 帧类型标识（0x01=触发帧，0x02=TEMP_REQ 帧）
    ├─ Status:      uint8_t      — 状态（0=正常）
    ├─ Is2D:        uint8_t      — 1=2D 矩阵帧
    └─ Reserved:    uint8_t      — 填 0

[像素数组] Width × Height × 2 字节
    每个像素：uint16_t 小端序
    排列：行优先（row0 col0, row0 col1, ..., row0 colW-1, row1 col0, ...）
    单位：0.1°C/LSB，转为摄氏度 = 原始值 × 0.1
```

**Python 解析示例**：

```python
import struct

def parse_2d_frame(data: bytes):
    hdr_fmt = '<IHHhhhhhBBBB'   # TemperatureFrameHeader_t
    hdr_size = struct.calcsize(hdr_fmt)
    frame_num, w, h, min_t, max_t, avg_t, roi_t, _, ft, st, is2d, _ = struct.unpack_from(hdr_fmt, data)
    pixels_raw = struct.unpack_from(f'<{w*h}H', data, hdr_size)
    pixels_celsius = [v * 0.1 for v in pixels_raw]
    # pixels_celsius[row * w + col] = 第 row 行、第 col 列的温度（°C）
    return {
        'frame_num': frame_num, 'width': w, 'height': h,
        'max_temp': max_t * 0.1, 'min_temp': min_t * 0.1,
        'pixels': pixels_celsius
    }
```

### 4.2 1D 温度帧解析

当 `Is2D=0` 时，像素数组替换为 1D 样本序列。

Value 布局（同 TemperatureFrameHeader_t，但 Width=点数，Height=1）：

```
[TemperatureFrameHeader_t] 18 字节
    ├─ Width:  实际有效样本点数 N
    ├─ Height: 1
    └─ Is2D:   0

[样本数组] N × 4 字节
    每个样本（TempPoint1D_t）：
    ├─ TimeOffset:  uint16_t LE — 相对采集开始的 ms 偏移
    └─ Temperature: uint16_t LE — 对应时刻温度（0.1°C/LSB）
```

**Python 解析示例**：

```python
def parse_1d_frame(data: bytes):
    hdr_fmt = '<IHHhhhhhBBBB'
    hdr_size = struct.calcsize(hdr_fmt)
    frame_num, n, _, min_t, max_t, avg_t, _, _, ft, st, is2d, _ = struct.unpack_from(hdr_fmt, data)
    points = []
    for i in range(n):
        t_off, temp = struct.unpack_from('<HH', data, hdr_size + i*4)
        points.append({'time_ms': t_off, 'temp_c': temp * 0.1})
    return {'frame_num': frame_num, 'points': points}
```

---

## 5. 检测结果下发与 NG 输出

### 5.1 下发检测结果

Server 在图像处理完成后，通过**控制流（5511）**发送 `TYPE_DETECTION_RESULT(0x40)`（Class=CLASS_CONTROL=0x01）。

Value 结构（DetectionResult_t，8 字节）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `FrameNumber` | uint32_t LE | 对应触发该结果的帧号 |
| `Result` | uint8_t | **0=NG（不合格），1=OK（合格）** |
| `Reserved[3]` | uint8_t[3] | 填 0 |

### 5.2 MCU NG 动作

收到 `Result=0`（NG）时：
- `PA8` 输出高电平
- 持续 `Config2D.NGioDelay`（默认 200 ms）后自动恢复低电平
- `NGioDelay` 可通过 Config2D 配置调整（1D 模式使用 Config1D.NGioDelay）

> 外部报警装置应接在 PA8，高电平有效，持续时间可配置。

---

## 6. TEMP_REQ 按需截图

Server 可随时通过控制流请求当前热场快照，无需等待触发。

**请求帧**：TYPE_CONFIG_COMMON（0x20，Class=CLASS_CONTROL=0x01）中包含 TEMP_REQ 字段，或通过专用命令触发（具体字段由 `TcpLogic` 内部解析），携带 `is2dRequest` 标志（1=请求 2D 帧，0=请求 1D 帧）。

**MCU 响应**：
- 下一个业务循环取当前 FrameBuffer 的最新帧
- `is2d=1`：执行 `Preprocess_Execute`，返回 ROI 裁切后的 2D 温度矩阵（FrameType=0x02）
- `is2d=0`：返回中心行 **30 个等间距采样点**，时间偏移仿真 0~600 ms（非真实时间序列）
- 仅在对应模式（`Config2D.Enabled` / `Config1D.Enabled`）为 1 时响应，否则忽略

---

## 7. 错误码参考

| 错误码 | 值 | 触发场景 | 建议处理 |
|--------|-----|---------|---------|
| `ERR_CRC` | `0x1001` | 帧 CRC 校验失败 | 检查发送数据是否正确，重发 |
| `ERR_VERSION` | `0x1002` | 协议版本不匹配（非 0x20） | 检查 Version 字段 |
| `ERR_LENGTH` | `0x1003` | FrameHeader.Length 与实际帧长不符 | 检查帧构造逻辑 |
| `ERR_AUTH` | `0x2001` | AuthToken 不匹配 | 当前版本 AuthToken 全零，不应触发 |
| `ERR_BUSY` | `0x2002` | 设备忙，拒绝处理 | 等待 100 ms 后重试 |
| `ERR_DEV_ID_CONFLICT` | `0x2003` | DevID 与已注册设备冲突 | 检查 DevID 分配 |
| `ERR_PARAM` | `0x3001` | 配置字段值非法 | 检查配置结构体字段范围 |

---

## 8. 对接故障排查

### 8.1 MCU 上电后无连接

- 检查 MCU IP 是否为 `192.168.7.10`，Server 是否在 `192.168.7.50`
- 确保 Server 在 5511 和 5512 端口上已 Listen
- 检查以太网连接（MCU 使用 1000M RGMII，需 1 Gbps 交换机或兼容网卡）
- 调试串口（USART3，921600）会打印 `TCP Connected, socket X` 确认连接

### 8.2 握手成功但无数据帧

- 确认已通过控制流下发 `Config2D`（`Enabled=1`）或 `Config1D`（`Enabled=1`）
- 查看调试串口是否打印 `TRIGGER frm=N`（2D 模式）或 `1D: internal trigger start`（1D 模式）
- 若无触发，检查 `TriggerTemperatureThreshold` 是否过高

### 8.3 数据帧偶发丢失

- 检查 Server 是否及时 ACK，TCP 窗口是否足够
- 调试串口打印 `2D TX fail` 或 `1D SEND ... ret=-1` 表示 MCU 侧发送失败（队列满或连接异常）

### 8.4 温度值异常（偏高或偏低约 10 倍）

- 确认传感器已配置为 **TMP 模式**（非 Y16 模式）。参见 `Doc/Mini212G2预配置指南.md`
- TMP 模式输出值已是 0.1°C/LSB，解析时乘以 0.1 即为摄氏度

### 8.5 NG 输出不动作

- 确认发送的 DetectionResult.Result = 0（NG），而非 1（OK）
- 检查 `Config2D.NGioDelay` 是否已配置（0 时默认 200 ms）
- 核查 PA8 GPIO 连接是否正确

---

## 9. 相关文档

| 文档 | 内容 |
|------|------|
| [系统总览.md](系统总览.md) | MCU 固件架构总览 |
| [QDX协议设计.md](QDX协议设计.md) | 帧结构详细说明（供深度对接参考） |
| [TCP通信模块设计.md](TCP通信模块设计.md) | MCU 侧连接管理实现细节 |
| [Mini212G2预配置指南.md](../Mini212G2预配置指南.md) | 传感器 TMP 模式配置 |