📝 docs(dvp): 更新传感器预配置文档并修复行数定义
- 新增 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:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-15
|
||||
@@ -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 / 其他）需联调后确认，当前文档提供验证方法但无结论。
|
||||
@@ -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
@@ -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 有注释或链接指向预配置指南
|
||||
@@ -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 不一致，在预配置指南中补充实测结论及换算公式
|
||||
@@ -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 有注释或链接指向预配置指南
|
||||
Reference in New Issue
Block a user