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 规格文档
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
## 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 / 其他）需联调后确认，当前文档提供验证方法但无结论。
|