zhoujie
c347c988f2
- 新增 Mini212G2 传感器预配置指南文档，详细说明外部工具配置步骤
- 修复 DVP 头文件中的 SENSOR_TOTAL_LINES 定义，移除冗余行数
- 在 README 和模式配置文档中添加预配置指南的引用链接
- 新增 OpenSpec 变更记录，包含设计文档、提案、规格和任务清单
📦 build(openspec): 新增传感器预配置规范文档结构
- 在 openspec/changes/archive/ 下创建 2026-03-15-dvp-raw-data-pipeline 变更记录
- 包含设计文档、提案、规格说明和任务清单
- 在 openspec/specs/ 下创建 sensor-preconfig-guide 规格文档
258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
# 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) | **通过外部工具配置传感器的必要参数说明**（CMOS8 LSB、Y16、帧率等） |
|
||
| [Doc/Mini212G2串口通讯协议.md](Doc/Mini212G2串口通讯协议.md) | 传感器通信协议 |
|