zhoujie/ch32v307_camera
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(dvp): 更新传感器预配置文档并修复行数定义

Browse Source 
- 新增 Mini212G2 传感器预配置指南文档，详细说明外部工具配置步骤
- 修复 DVP 头文件中的 SENSOR_TOTAL_LINES 定义，移除冗余行数
- 在 README 和模式配置文档中添加预配置指南的引用链接
- 新增 OpenSpec 变更记录，包含设计文档、提案、规格和任务清单

📦 build(openspec): 新增传感器预配置规范文档结构

- 在 openspec/changes/archive/ 下创建 2026-03-15-dvp-raw-data-pipeline 变更记录
- 包含设计文档、提案、规格说明和任务清单
- 在 openspec/specs/ 下创建 sensor-preconfig-guide 规格文档
This commit is contained in:
zhoujie 2026-03-15 18:03:55 +08:00
parent e885c1b7ea
commit c347c988f2
10 changed files with 347 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Debug/dvp.h
View File

@ -4,7 +4,7 @@
#define SENSOR_WIDTH 256
#define SENSOR_HEIGHT 192
#define SENSOR_TOTAL_LINES (SENSOR_HEIGHT + 1) // +1 参数行
#define SENSOR_TOTAL_LINES (SENSOR_HEIGHT) // TMP 模式无参数行，共 192 行
#define BYTES_PER_LINE (SENSOR_WIDTH * 2) // 每行512字节
#define ALARM_TEMP_RAW 800 // 80.0℃ (raw/10)

1
README.md
View File

@ -253,4 +253,5 @@ IDLE → 触发（外部 GPIO 高电平计时 or 内部连续 3 帧超阈值）
| [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) | 传感器通信协议 |

149
doc/Mini212G2预配置指南.md Normal file
View File

@ -0,0 +1,149 @@
# Mini212G2 模组预配置指南
> **适用场景**：MCU 端 `SENSOR_UART_ENABLE=0`，传感器通过外部工具（USB/串口调试软件）预先配置并保存到 Flash。
> **配置工具**：可使用厂家上位机软件或通用串口调试工具，连接传感器 USB 接口或 UART 接口（115200 8N1）。
> **参考文档**：`Doc/Mini212G2串口通讯协议.md`、`Doc/Mini212G2系列用户手册.md`
---
## 必须配置的参数（共 4 项）
以下参数与 MCU DVP 驱动强耦合，任意一项配置错误将导致图像数据完全错误。
### 1. 数字口类型 → CMOS
| 属性 | 值 |
|------|-----|
| 设置值 | CMOS |
| 串口命令 | `55 AA 07 02 01 02 00 00 00 02 04 F0` |
| 原因 | MCU 使用 DVP 8-bit 并行接口接收数据，必须选 CMOS 模式 |
---
### 2. CMOS 接口 → **CMOS8(LSB)** ⛔ 关键，必须为 LSB
| 属性 | 值 |
|------|-----|
| **设置值** | **CMOS8(LSB)** |
| 串口命令 | `55 AA 07 02 01 04 00 00 00 02 02 F0` |
| ❌ 禁止设置 | CMOS8(MSB) → `55 AA 07 02 01 04 00 00 00 01 01 F0` |
**原因（字节序）**：
CH32V307 是小端序（Little-Endian）处理器，DVP DMA 按字节顺序依次写入 `FrameBuffer`，代码通过 `(uint16_t*)FrameBuffer` 直接读取 16-bit 温度值：
```
FrameBuffer[row][0] → uint16_t 低字节（bits[7:0]）
FrameBuffer[row][1] → uint16_t 高字节（bits[15:8]）
```
| 传感器模式 | DVP 先收到 | uint16_t 读取结果 |
|---|---|---|
| LSB（低字节先发） | 低字节 | ✅ 正确 |
| MSB（高字节先发） | 高字节 | ❌ 字节反序，温度值完全错误 |
---
### 3. CMOS 内容 → **TMP** ⛔ 关键，必须为 TMP（不是 Y16）
| 属性 | 值 |
|------|-----|
| **设置值** | **TMP** |
| 串口命令 | `55 AA 07 02 01 03 00 00 00 08 0F F0` |
| ❌ 禁止设置 | Y16 → `55 AA 07 02 01 03 00 00 00 02 05 F0` |
> **Mini212G2 是测温型产品，支持 TMP 模式。** 若不确定，使用前请与厂家确认。
**为什么必须选 TMP，不能选 Y16**：
| 模式 | 数据含义 | MCU 是否可直接使用 |
|------|----------|--------------------|
| **TMP（温度矩阵）** | 传感器内部已完成辐射定标，16-bit 值 = 实际温度 × 10（单位 0.1°C/LSB） | ✅ 直接使用，与代码假设完全匹配 |
| Y16（红外辐射原始数据） | 原始 ADC 计数值，不是温度，数值越大表示越热但无对应温度 | ❌ 需要读出厂标定参数 + 手写温度解算公式才能转换为温度 |
MCU 代码（`qdx_preprocess.c`）将像素值直接当 0.1°C/LSB 的温度使用——这正是 **TMP 模式输出的格式**（协议文档等温阈值范围 -400~5500 对应 -40.0~550.0°C 即 0.1°C/LSB）。若配置为 Y16，所有温度判断将得到错误结果，但系统不会报错。
其他禁止选项：
- `TMP+参数行`（参数行会打乱行计数，`SENSOR_HEIGHT=192` 对应到 193 行后中断异常）
- `TMP+YUV422`（YUV 通道数据会覆盖温度帧）
---
### 4. 帧率 → 25Hz 或 30Hz
| 属性 | 值 |
|------|-----|
| 推荐值 | 25Hz |
| 串口命令（25Hz） | `55 AA 07 02 01 05 00 00 00 00 01 F0` |
| 串口命令（30Hz） | `55 AA 07 02 01 05 00 00 00 00 01 F0` *(参见协议文档帧率表)* |
---
## 配置后必须保存
配置完成后发送保存命令，否则断电后配置丢失：
```
保存设置：55 AA 07 01 00 04 00 00 00 01 03 F0
```
> ⚠️ 保存后重新上电，配置才从 Flash 生效。
---
## TMP 模式温度值格式确认
Mini212G2 TMP 模式输出格式（协议文档 §2.4.5 等温阈值范围 -400~5500 对应 -40.0~550.0°C）：
| 参数 | 值 |
|------|----|
| 单位 | 0.1°C/LSB |
| 编码 | 有符号 16-bit（int16_t） |
| 示例 | 25.0°C → 250，-10.0°C → -100，100.0°C → 1000 |
MCU 代码使用方式：
```c
// qdx_preprocess.c 中直接将像素值当温度（0.1°C/LSB）
// 示例：testPattern 阈值
#define TEMP_RAW(deg_c) ((uint16_t)((deg_c) * 10))
// 35.0°C → 350，80.0°C → 800，90.0°C → 900
```
**联调验证步骤**（TMP 模式，首次上电后执行）：
1. 将传感器对准已知温度目标（如室温约 25°C 的平板物体）
2. 通过串口 log 打印 DVP 帧中心像素原始值
3. 确认中心像素值约等于 **250**（25.0°C × 10）
4. 如输出值异常（如约 2980 或约 7450），说明配置的不是纯 TMP 模式，需重新检查步骤 3 的配置
| 实测中心值（约） | 说明 |
|-----------------|------|
| ~250 | ✅ TMP 0.1°C/LSB，与代码一致 |
| ~2980 | ❌ 可能是开尔文模式（K×10），配置错误 |
| ~7450 | ❌ 可能是 Y16 原始 ADC 值，应切换为 TMP 模式 |
---
## 配置命令汇总表
| 步骤 | 功能 | 命令（HEX） |
|------|------|-------------|
| 1 | 数字口 → CMOS | `55 AA 07 02 01 02 00 00 00 02 04 F0` |
| 2 | **CMOS 接口 → CMOS8(LSB)** | `55 AA 07 02 01 04 00 00 00 02 02 F0` |
| 3 | **CMOS 内容 → TMP** | `55 AA 07 02 01 03 00 00 00 08 0F F0` |
| 4 | 帧率 → 25Hz | `55 AA 07 02 01 05 00 00 00 00 01 F0` |
| 5 | **保存设置** | `55 AA 07 01 00 04 00 00 00 01 03 F0` |
> 每条命令发送后等待 ACK：`55 AA 01 00 01 F0`，收到后再发下一条。
---
## 不需要配置的项目
| 参数 | 说明 |
|------|------|
| 外同步 | 保持默认关闭（内同步），MCU DVP 作为接收方 |
| VSYNC/HSYNC 极性 | MCU 侧已配置 `VSYNC active-high`，传感器默认输出一致 |
| 分辨率 | Mini212G2 固定 256×192，无需配置 |
| NUC 快门补偿 | 运行时按需触发（`55 AA 07 02 01 08 00 00 00 01 0D F0`），不属于启动配置 |

1
doc/模式配置与功能说明.md
View File

@ -115,6 +115,7 @@
> 当前模组已通过 USB 预配置，MCU UART 配置功能已用 `#if 0` 关闭。
> **USART2 (PA2/PA3) 引脚已被占用，不可用于传感器通信。**
> 预配置必需配置的参数详见：[Doc/Mini212G2预配置指南.md](Mini212G2预配置指南.md)
| 宏名 | 当前值 | 说明 |
|------|--------|------|

2
openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/.openspec.yaml Normal file
View File

@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-03-15

53
openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/design.md Normal file
View File

@ -0,0 +1,53 @@
## Context
**背景**：MCU 固件中 `SENSOR_UART_ENABLE=0`，mini212g2.c 中所有传感器 UART 配置命令均被 `#if` 屏蔽，传感器完全依赖外部工具（USB 串口/厂家上位机）进行预配置。现有代码在以下两处隐含了对传感器输出格式的假设：
1. **字节序假设**：`dvp.c` 对 DMA 采集到的 `uint8_t FrameBuffer[192][512]` 直接强转 `(uint16_t*)` 使用，CH32V307 为小端序（Little-Endian），因此要求传感器以 **LSB 先发**（低字节先到 DVP 数据线）输出 CMOS8 格式。
2. **Y16 单位假设**：`qdx_preprocess.c` 将 Y16 原始值直接当 `int16_t` 使用，在比较和上报时按 0.1°C/LSB 理解，要求传感器输出的 Y16 量纲与此一致。
当前无文档说明这些约束，现场部署时可能因传感器配置错误导致数据完全错误。
**变更范围**：仅新增文档；MCU 代码不变。
## Goals / Non-Goals
**Goals:**
- 明确列出外部工具必须配置的所有 Mini212G2 参数及其原因
- 提供每个配置项的串口命令 HEX，使现场工程师可操作
- 解释字节序原理，防止误选 MSB 模式
- 提供 Y16 单位的现场联调验证方法
**Non-Goals:**
- 不修改 MCU 驱动代码（`SENSOR_UART_ENABLE` 保持 0）
- 不涉及网络协议或上位机修改
- 不提供 Mini212G2 全量功能手册（已有 `Doc/Mini212G2系列用户手册.md`）
## Decisions
### 决策 1：文档形式采用 操作指南（How-to）而非参考文档（Reference）
**理由**：目标读者是现场调试工程师，需要明确的步骤顺序和可操作的命令，而不是完整的参数字典。操作指南格式（按步骤编号）更直接。
**备选方案**：直接在模式配置文档中追加一节 → 拒绝，因为该文档定位是固件变量说明，混入硬件配置步骤会破坏结构。
### 决策 2：将 CMOS8(LSB) 标注为 ⛔ 关键步骤
**理由**：字节序错误会导致所有温度数据完全错误，且表现不明显（不是崩溃，而是系统正常运行但数值错误）。强调标注可防止工程师跳过该步骤。
### 决策 3：Y16 单位列出三种常见格式对照表，而非硬编码结论
**理由**：Mini212G2 不同固件版本可能存在差异，现场联调时工程师需要人工判断。对照表（K×100、K×10、℃×10）让判断有据可查。
### 决策 4：在 README 和模式配置文档中添加指向预配置指南的链接
**理由**：保证文档可达性，防止孤立文件不被发现。两个入口文档均有传感器相关章节，是链接的自然落点。
## Risks / Trade-offs
- **风险**：Mini212G2 固件升级后命令 HEX 可能变化 → **缓解**：文档顶部注明适用固件版本为 V1.x，并要求升级后重新验证。
- **风险**：工程师忽略预配置指南直接上电 → **缓解**：在 README"快速上手"章节前置一条警告，指向预配置指南。
- **权衡**：文档方式无法从固件层面强制约束传感器配置，只能依赖操作规范 → 可接受，因修改驱动增加的复杂度和维护风险更高。
## Open Questions
- Mini212G2 具体 Y16 量纲（K×10 / ℃×10 / 其他）需联调后确认，当前文档提供验证方法但无结论。

27
openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/proposal.md Normal file
View File

@ -0,0 +1,27 @@
# Proposal: DVP 原始数据采集流程验证与传感器预配置规范
## Why
MCU 端驱动不通过 UART 配置传感器（`SENSOR_UART_ENABLE=0`），而是依赖外部工具预先宼入。当前无文档明确说明需要配置哪些参数，导致两个关键风险：
① CMOS8 字节序：传感器必须配置为 **LSB 模式**，否则 CH32V307（小端序）将 `uint16_t` 读到字节完全反序的错误温度值；
② Y16 单位：代码按 0.1°C/LSB 使用，需确认实际传感器输出的温度单位一致。
## What Changes
- 新增 **Mini212G2 预配置指南**（`Doc/Mini212G2预配置指南.md`），明确列出外部工具需要设置的所有参数及原因
- MCU 驱动代码不作任何修改（`SENSOR_UART_ENABLE` 保持为 0）
## Capabilities
### New Capabilities
- `sensor-preconfig-guide`: Mini212G2 预配置指南文档
### Modified Capabilities
(无，MCU 代码不变)
## Impact
- **新增文档**：`Doc/Mini212G2预配置指南.md`
- **不涉及** MCU 代码修改
- 配置错误情况下所有温度判断和上报数据均为错误值

45
openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/specs/sensor-preconfig-guide/spec.md Normal file
View File

@ -0,0 +1,45 @@
## ADDED Requirements
### Requirement: 提供 Mini212G2 传感器预配置操作指南
操作指南文档（`Doc/Mini212G2预配置指南.md`）SHALL 明确说明在使用 MCU 固件采集前，必须通过外部工具完成的所有 Mini212G2 参数配置步骤、对应串口命令 HEX 及原因说明。
#### Scenario: 工程师查阅配置步骤
- **WHEN** 工程师准备部署传感器时
- **THEN** 文档 SHALL 提供编号的步骤列表，包含每步的操作内容和串口命令
#### Scenario: 工程师查找特定参数的命令 HEX
- **WHEN** 工程师需要向传感器发送配置命令时
- **THEN** 文档 SHALL 包含完整的命令 HEX 汇总表，包含参数名称、命令 HEX、说明三列
### Requirement: 强制配置 CMOS 内容为 TMP 模式
指南 SHALL 要求 CMOS 内容配置为 **TMP**（不是 Y16），并说明原因：MCU 代码将像素值直接当温度使用（0.1°C/LSB），这是 TMP 模式输出的格式，而非 Y16 原始 ADC 值。
#### Scenario: 工程师理解为何必须选 TMP 而非 Y16
- **WHEN** 工程师阅读 CMOS 内容配置步骤时
- **THEN** 文档 SHALL 解释：TMP 输出的 16-bit 值直接是温度（传感器内部已完成定标），Y16 是原始 ADC 计数值需另行温度解算；代码假设的 0.1°C/LSB 就是 TMP 格式
#### Scenario: 工程师误选了 Y16 模式
- **WHEN** 工程师将传感器 CMOS 内容配置为 Y16 时
- **THEN** 所有温度判断将得到错误结果（原始 ADC 值被当做温度），但系统不会报错；文档 SHALL 以 ⛔ 警告标注此风险
### Requirement: 提供 TMP 模式温度格式联调验证方法
指南 SHALL 提供至少一种可操作的现场验证方法，使工程师能确认 TMP 模式输出的 16-bit 值就是 0.1°C/LSB 格式。
#### Scenario: 验证 TMP 输出格式正确
- **WHEN** 工程师首次联调时
- **THEN** 文档 SHALL 提供通过已知温度目标对比中心像素原始值的验证步骤，预期中心像素均值约等于实际温度 × 10（如 25°C 对应 250）
#### Scenario: 验证结果与预期不符
- **WHEN** 工程师发现像素值不符合 0.1°C/LSB 预期时
- **THEN** 文档 SHALL 列出常见错误值对应的可能原因（如配置为 Y16 模式，或 MSB 字节序错误）并说明如何排查
### Requirement: 从入口文档链接至预配置指南
`README.md` 和 `Doc/模式配置与功能说明.md` SHALL 包含指向 `Doc/Mini212G2预配置指南.md` 的可导航链接。
#### Scenario: 工程师从 README 进入预配置指南
- **WHEN** 工程师阅读 README 参考文档章节时
- **THEN** 文档列表中 SHALL 存在指向预配置指南的条目
#### Scenario: 工程师从模式配置文档进入预配置指南
- **WHEN** 工程师阅读模式配置文档的传感器相关章节时
- **THEN** 相关位置 SHALL 有注释或链接指向预配置指南

23
openspec/changes/archive/2026-03-15-dvp-raw-data-pipeline/tasks.md Normal file
View File

@ -0,0 +1,23 @@
## 1. 创建预配置指南主体文档
- [x] 1.1 新建 `Doc/Mini212G2预配置指南.md`，列出 4 项必须配置的参数（视频格式 Y16、CMOS8 LSB、帧率、图像尺寸）
- [x] 1.2 在文档中说明 CMOS8(LSB) 的字节序原理（CH32V307 小端序 + DVP 直接强转 `uint16_t*`）
- [x] 1.3 在文档中添加 ⛔ 关键警告：误选 MSB 模式将导致所有温度数据完全错误
- [x] 1.4 提供每个配置步骤对应的串口命令 HEX 汇总表
## 2. TMP 模式温度格式确认（已更新）
- [x] 2.1 在预配置指南中说明 TMP 与 Y16 的本质区别（传感器内部定标 vs 原始 ADC 值）
- [x] 2.2 提供 TMP 模式联调验证步骤（已知温度目标对比，期望中心像素值 ≈ 实际°C × 10）
- [x] 2.3 说明若验证值异常，可能原因（误配为 Y16 或 MSB 字节序）及排查方法
## 3. 更新入口文档链接
- [x] 3.1 在 `README.md` 参考文档表中新增 `Mini212G2预配置指南` 链接条目
- [x] 3.2 在 `Doc/模式配置与功能说明.md` 传感器相关章节添加指向预配置指南的链接注释
## 4. 联调验证（硬件）
- [ ] 4.1 按指南完成传感器外部配置，确认视频格式为 Y16、字节序为 LSB
- [ ] 4.2 上电后检查 DVP 采集的中心像素原始值，与已知温度目标对照，确认 Y16 量纲
- [ ] 4.3 若量纲与 0.1°C/LSB 不一致，在预配置指南中补充实测结论及换算公式

45
openspec/specs/sensor-preconfig-guide/spec.md Normal file
View File

@ -0,0 +1,45 @@
## ADDED Requirements
### Requirement: 提供 Mini212G2 传感器预配置操作指南
操作指南文档（`Doc/Mini212G2预配置指南.md`）SHALL 明确说明在使用 MCU 固件采集前，必须通过外部工具完成的所有 Mini212G2 参数配置步骤、对应串口命令 HEX 及原因说明。
#### Scenario: 工程师查阅配置步骤
- **WHEN** 工程师准备部署传感器时
- **THEN** 文档 SHALL 提供编号的步骤列表，包含每步的操作内容和串口命令
#### Scenario: 工程师查找特定参数的命令 HEX
- **WHEN** 工程师需要向传感器发送配置命令时
- **THEN** 文档 SHALL 包含完整的命令 HEX 汇总表，包含参数名称、命令 HEX、说明三列
### Requirement: 强制配置 CMOS 内容为 TMP 模式
指南 SHALL 要求 CMOS 内容配置为 **TMP**（不是 Y16），并说明原因：MCU 代码将像素值直接当温度使用（0.1°C/LSB），这是 TMP 模式输出的格式，而非 Y16 原始 ADC 值。
#### Scenario: 工程师理解为何必须选 TMP 而非 Y16
- **WHEN** 工程师阅读 CMOS 内容配置步骤时
- **THEN** 文档 SHALL 解释：TMP 输出的 16-bit 值直接是温度（传感器内部已完成定标），Y16 是原始 ADC 计数值需另行温度解算；代码假设的 0.1°C/LSB 就是 TMP 格式
#### Scenario: 工程师误选了 Y16 模式
- **WHEN** 工程师将传感器 CMOS 内容配置为 Y16 时
- **THEN** 所有温度判断将得到错误结果（原始 ADC 值被当做温度），但系统不会报错；文档 SHALL 以 ⛔ 警告标注此风险
### Requirement: 提供 TMP 模式温度格式联调验证方法
指南 SHALL 提供至少一种可操作的现场验证方法，使工程师能确认 TMP 模式输出的 16-bit 值就是 0.1°C/LSB 格式。
#### Scenario: 验证 TMP 输出格式正确
- **WHEN** 工程师首次联调时
- **THEN** 文档 SHALL 提供通过已知温度目标对比中心像素原始值的验证步骤，预期中心像素均值约等于实际温度 × 10（如 25°C 对应 250）
#### Scenario: 验证结果与预期不符
- **WHEN** 工程师发现像素值不符合 0.1°C/LSB 预期时
- **THEN** 文档 SHALL 列出常见错误值对应的可能原因（如配置为 Y16 模式，或 MSB 字节序错误）并说明如何排查
### Requirement: 从入口文档链接至预配置指南
`README.md` 和 `Doc/模式配置与功能说明.md` SHALL 包含指向 `Doc/Mini212G2预配置指南.md` 的可导航链接。
#### Scenario: 工程师从 README 进入预配置指南
- **WHEN** 工程师阅读 README 参考文档章节时
- **THEN** 文档列表中 SHALL 存在指向预配置指南的条目
#### Scenario: 工程师从模式配置文档进入预配置指南
- **WHEN** 工程师阅读模式配置文档的传感器相关章节时
- **THEN** 相关位置 SHALL 有注释或链接指向预配置指南