# CH32V307 TCPClient — 红外热像采集端固件（MCU 端）

> **MCU**: CH32V307WCU6 (RISC-V, 144 MHz)  
> **协议版本**: QDX v2.0 / 采集端通信协议规范 v2.1.3  
> **固件版本**: v2.0 自主触发架构  
> **最近更新**: 2026-03

---

## 目录

1. [项目简介](#1-项目简介)
2. [硬件配置](#2-硬件配置)
3. [软件架构](#3-软件架构)
4. [目录结构](#4-目录结构)
5. [快速上手](#5-快速上手)
6. [编译期配置](#6-编译期配置)
7. [网络配置](#7-网络配置)
8. [运行时行为](#8-运行时行为)
9. [GPIO 引脚分配](#9-gpio-引脚分配)
10. [已知问题 / TODO](#10-已知问题--todo)
11. [参考文档](#11-参考文档)

---

## 1. 项目简介

本项目是基于 **CH32V307WCU6** 的红外热像**采集端**（MCU 端）嵌入式固件，实现以下核心功能：

- 驱动 **Mini212G2** 红外热像仪（256×192，Y16 原始温度格式）采集帧数据
- 运行 **FreeRTOS** 实时操作系统，多任务并行处理
- 通过 **WCHNET 1000M 以太网** 与**上位机**（ConfigServer，运行于 PC/服务器）进行 TCP 通信
- 使用 **QDX TLV 二进制协议**（帧头 `0x55AA`，协议版本 v2.0）向上位机上报数据
- 支持 **2D 触发连拍**（内部温度触发 / 外部 GPIO 触发）与 **1D 时序采集**
- 支持上位机运行时下发配置，MCU（采集端）**自主驱动**全部业务逻辑

---

## 2. 硬件配置

| 资源 | 规格 |
|------|------|
| MCU | CH32V307WCU6，RISC-V，144 MHz |
| FLASH | 128 KB |
| SRAM | 192 KB（Option Bytes [7:5]=110） |
| 传感器 | Mini212G2，256×192，Y16 原始温度 |
| 网络接口 | 1000M 以太网，RGMII（WCHNET） |
| 串口调试 | USART3，921600 baud（PB10 TX / PB11 RX） |
| 外部触发输入 | PA15 / EXTI15，上升沿 |
| NG 输出 | PA8，推挽，高有效，脉冲宽度可配 |
| DVP 接口 | 传感器图像数据采集（DMA 行搬运） |

---

## 3. 软件架构

```
┌──────────────────────────────────────────────────────┐
│                   FreeRTOS 任务层                     │
│  task_net_entry      — WCHNET 轮询 / TCP 收发        │
│  task_business_entry — 业务主循环（2D/1D 状态机）   │
│  task_test_pattern   — 仅测试模式：模拟帧生成        │
└─────────────────┬────────────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────────────┐
│                   中间件 / 协议层                     │
│  QDX 协议栈     — TLV 编解码、TCP 逻辑封装           │
│  qdx_preprocess — 滑窗 ROI + 温度统计 + 降尺寸       │
└─────────────────┬────────────────────────────────────┘
                  │
┌─────────────────▼────────────────────────────────────┐
│                   驱动 / HAL 层                       │
│  eth_driver     — WCHNET 以太网驱动                  │
│  dvp.c          — DVP + DMA 行采集                   │
│  mini212g2.c    — 传感器控制（当前通过 USB 预配置）  │
│  debug.c        — USART1 调试输出                    │
└──────────────────────────────────────────────────────┘
```

### RTOS 资源

| 组件 | 说明 |
|------|------|
| FreeRTOS v202112.00 | Heap_4，Heap 大小 16 KB |
| WCHNET | 万瑞 TCP/IP 协议栈，2 个 TCP socket |
| QDX 协议栈 | 自定义 TLV 二进制协议，双缓冲零拷贝 TX |
| 预处理模块 | 滑窗 ROI 搜索 + 最大/平均温度统计 + 自动降尺寸 |

---

## 4. 目录结构

```
Project_Ch32v307/
├── User/               # 应用层入口
│   ├── main.c          # 初始化、FreeRTOS 任务创建、业务状态机
│   ├── net_config.h    # WCHNET socket / MAC 参数
│   ├── FreeRTOSConfig.h
│   └── ch32v30x_conf.h
├── Middle/
│   └── QDXnetworkStack/  # QDX TLV 协议栈（端口适配 + 预处理 + TCP 逻辑）
├── Debug/
│   ├── dvp.c/h           # DVP + DMA 传感器图像采集
│   └── mini212g2.c/h     # Mini212G2 传感器驱动
├── NetLib/               # WCHNET 以太网驱动（多 PHY 版本）
├── FreeRTOS/             # FreeRTOS 内核 + portable + MemMang
├── Peripheral/           # CH32V30x 外设库
├── Core/                 # RISC-V 内核支持
├── Startup/              # 启动汇编文件
├── Ld/                   # 链接脚本
└── Doc/                  # 协议规范、用户手册等文档
```

---

## 5. 快速上手

### 5.1 工具链要求

- **IDE**: MounRiver Studio（推荐）或 GCC RISC-V 工具链
- **调试器**: WCH-Link

### 5.2 编译步骤

1. 用 MounRiver Studio 打开 `TCPClient1.wvproj`
2. 根据实际环境修改 `User/net_config.h` 中的 IP 地址（见[网络配置](#7-网络配置)）
3. 按需设置 `User/main.c` 顶部的 `TEST_PATTERN_MODE` 宏
4. 编译并烧录到目标板

### 5.3 两种运行模式

| 项目 | 测试模式 (`TEST_PATTERN_MODE=1`) | 正常模式 (`TEST_PATTERN_MODE=0`) |
|------|------|------|
| 数据来源 | 软件生成模拟热图 (~10 FPS) | Mini212G2 传感器 DVP/DMA 采集 |
| 硬件依赖 | 仅需网口 | 需连接 Mini212G2 + DVP 线缆 |
| 默认配置 | 自动注入（2D Enabled=1，内部触发，80°C 阈值） | 等待服务器下发，默认不使能 |
| 适用场景 | 协议联调、网络测试 | 实际生产部署 |

---

## 6. 编译期配置

所有宏定义位于 `User/main.c` 文件头部。

### 主模式开关

| 宏名 | 默认值 | 说明 |
|------|--------|------|
| `TEST_PATTERN_MODE` | `0` | **唯一编译开关**：`1`=测试模式，`0`=正常模式 |

### 业务常量

| 宏名 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_BURST_COUNT` | `3` | 服务器未配置时的默认连拍帧数 |
| `DEFAULT_BURST_INTERVAL_MS` | `200` | 默认连拍间隔（ms） |
| `MAX_TCP_PAYLOAD_SIZE` | `9216` | TCP 发送缓冲区大小（字节） |
| `NG_PULSE_MS` | `200` | NG 脉冲默认宽度（服务器可通过 `NGioDelay` 覆盖） |
| `MAX_1D_POINTS` | `512` | 1D 采集缓冲最大样本数 |

### 传感器尺寸（`Debug/dvp.h`）

| 宏名 | 值 | 说明 |
|------|-----|------|
| `SENSOR_WIDTH` | `256` | 传感器像素宽度 |
| `SENSOR_HEIGHT` | `192` | 传感器像素高度 |
| `BYTES_PER_LINE` | `512` | 每行字节数（256×2） |

---

## 7. 网络配置

网络参数在 `User/net_config.h` 和 `User/main.c` 中配置：

| 参数 | 说明 |
|------|------|
| 本机 IP | 静态 IP（在 `main.c` 初始化结构体中设置） |
| 控制通道 | TCP，主动连接上位机（ConfigServer）控制端口，接收命令与配置 |
| 数据通道 | TCP，主动连接上位机（ConfigServer）数据端口，上报帧数据 |
| TCP socket 数 | 2（`WCHNET_NUM_TCP=2`） |
| TCP MSS | 1460 字节 |
| KeepAlive | 开启，20 s 空闲 / 15 s 探测 / 9 次 |

通信协议详见 [Doc/采集端通信协议规范.md](Doc/采集端通信协议规范.md)。

---

## 8. 运行时行为

系统行为完全由上位机（ConfigServer）运行时配置驱动，MCU 为采集端，主动连接上位机：

```
上位机下发 Config2D (Enabled=1) → MCU（采集端）自主执行 2D 触发 / 连拍 / 上报
上位机下发 Config1D (Enabled=1) → MCU（采集端）自主执行 1D 时序采集 / 上报
两者互斥：Config2D.Enabled 优先级高于 Config1D.Enabled
```

### 2D 触发状态机

```
IDLE → 检测触发条件（内部温度阈值 or 外部 GPIO）
     → 防抖（DebounceMs）
     → 延迟（DelayMs）
     → 连拍 N 帧（BurstCount × BurstIntervalMs）
     → 每帧：预处理 → TCP 上报 → NG 输出（若 NG 条件满足）
     → IDLE
```

### 1D 采集状态机

```
IDLE → 触发（外部 GPIO 高电平计时 or 内部连续 3 帧超阈值）
     → 防抖（HighTimerLimit）
     → 逐帧采样温度点（中心行最大值）
     → 阈值停止
     → 裁切 [LSizeStart, -RSizeStart]
     → TCP 上报
     → IDLE
```

### TEMP_REQ 辅助通道

服务器可随时发送 `TEMP_REQ` 命令，MCU 立即采集当前帧并上报（`frameType=0x02`），不影响主状态机。

---

## 9. GPIO 引脚分配

| 引脚 | 方向 | 功能 |
|------|------|------|
| PA15 | 输入 | 外部触发（2D/1D，上升沿，EXTI15） |
| PA8  | 输出 | NG 信号（推挽，高有效，脉冲宽度可配） |
| PA2/PA3 | — | USART2（已被 DVP 占用，传感器通过 USB 预配置，**不可复用**） |
| USART1 | 输出 | 921600 baud 调试串口 |

---

## 10. 已知问题 / TODO

- [ ] 需与采集端联调具体业务逻辑
- [ ] 上位机接收上报温度数据后出现卡死/异常，待排查

---

## 11. 参考文档

| 文档 | 说明 |
|------|------|
| [Doc/采集端通信协议规范.md](Doc/采集端通信协议规范.md) | QDX TLV 协议完整规范（v2.1.3） |
| [Doc/函数调用指南.md](Doc/函数调用指南.md) | 主要 API 调用说明 |
| [Doc/模式配置与功能说明.md](Doc/模式配置与功能说明.md) | 编译期/运行时配置详细说明 |
| [Doc/下位机协议实现完备性分析.md](Doc/下位机协议实现完备性分析.md) | 协议实现覆盖度分析 |
| [Doc/CH32二维运行结构概览.md](Doc/CH32二维运行结构概览.md) | 系统状态机全景图 |
| [Doc/TCPClient测试指南.md](Doc/TCPClient测试指南.md) | 测试模式使用说明 |
| [Doc/Mini212G2用户手册.md](Doc/Mini212G2系列用户手册.md) | 传感器硬件手册 |
| [Doc/Mini212G2串口通讯协议.md](Doc/Mini212G2串口通讯协议.md) | 传感器通信协议 |