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 规格文档
3.2 KiB
3.2 KiB
Context
背景：MCU 固件中 SENSOR_UART_ENABLE=0，mini212g2.c 中所有传感器 UART 配置命令均被 #if 屏蔽，传感器完全依赖外部工具（USB 串口/厂家上位机）进行预配置。现有代码在以下两处隐含了对传感器输出格式的假设：
- 字节序假设：
dvp.c对 DMA 采集到的uint8_t FrameBuffer[192][512]直接强转(uint16_t*)使用，CH32V307 为小端序（Little-Endian），因此要求传感器以 LSB 先发（低字节先到 DVP 数据线）输出 CMOS8 格式。 - 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 / 其他）需联调后确认，当前文档提供验证方法但无结论。