feat: sensor fusion interface spec v0.2 - complete protocol details

specs/sensor_fusion_action_plan.md

@@ -0,0 +1,69 @@
+# 传感器融合接口规范 - 行动计划
+
+**日期**: 2026-03-07  
+**负责人**: 孙大圣  
+**状态**: 执行中  
+
+## 📋 今日任务清单 (3月7日)
+
+### 高优先级任务
+- [x] 创建传感器融合接口规范框架 (v0.1)
+- [ ] 联系猪小杰确认传感器具体规格
+- [ ] 联系猪小杰确认SoC芯片型号
+- [ ] 确认传感器融合算法详细需求
+
+### 中优先级任务  
+- [ ] 完善接口规范中的数据格式细节
+- [ ] 补充实时性测试方案
+- [ ] 更新硬件抽象层设计
+
+## 📅 后续计划
+
+### 3月8日
+- [ ] 根据猪小杰反馈完善接口规范
+- [ ] 开始设计传感器驱动HAL接口
+- [ ] 制定SPI/UART通信测试方案
+
+### 3月9日  
+- [ ] 完成详细数据格式和算法接口
+- [ ] 编写初步的测试用例
+- [ ] 准备架构评审材料
+
+### 3月10日
+- [ ] 完成最终版接口规范 (v1.0)
+- [ ] 提交架构设计评审
+- [ ] 同步团队成员
+
+## 📞 联系人信息
+
+### 关键联系人
+- **猪小杰** (产品经理): 需要确认传感器规格和SoC型号
+- **徐工** (项目经理): 项目进度汇报和决策
+- **孙凯瑾** (对接人): 协调资源和支持
+
+### 沟通渠道
+- Feishu工作群
+- 项目文档协作
+- 日常站会
+
+## ⚠️ 风险与依赖
+
+### 主要风险
+1. **SoC型号未确认**: 影响HAL层设计和驱动开发
+2. **传感器规格不明确**: 影响数据格式定义和算法设计
+3. **时间紧迫**: 3月15日架构评审，仅剩8天
+
+### 缓解措施
+1. **并行工作**: 在等待硬件确认的同时，完善通用接口设计
+2. **模块化设计**: 采用硬件抽象层，便于后期适配
+3. **每日同步**: 确保信息及时传递，避免阻塞
+
+## 📊 进度跟踪
+
+| 任务 | 状态 | 完成度 | 备注 |
+|------|------|--------|------|
+| 接口规范框架 | ✅ 完成 | 100% | v0.1已创建 |
+| 传感器规格确认 | ⏳ 进行中 | 0% | 需联系猪小杰 |
+| SoC型号确认 | ⏳ 进行中 | 0% | 需联系猪小杰 |
+| 详细接口设计 | ⏳ 待开始 | 0% | 依赖规格确认 |
+| 最终版交付 | ⏳ 待开始 | 0% | 3月10日截止 |

specs/sensor_fusion_interface_spec.md

@@ -0,0 +1,207 @@
+# 传感器融合接口规范
+
+**版本**: v0.1  
+**日期**: 2026-03-07  
+**作者**: 孙大圣  
+**状态**: 草稿  
+
+---
+
+## 1. 文档概述
+
+### 1.1 目的
+本文档定义商用车AI-Box Demo中传感器融合模块的接口规范，确保MCU、SoC和传感器之间的数据交互标准化、实时性和可靠性。
+
+### 1.2 适用范围
+- MCU与SoC之间的传感器数据传输接口
+- SoC内部传感器融合算法的输入/输出接口  
+- 传感器数据格式标准化定义
+- 实时性要求和性能指标
+
+### 1.3 参考文档
+- 《商用车AI-Box Demo - 产品需求规格书》v2.0
+- 《智能挂车AI-Box软件架构设计》
+- IPCL通信协议规范
+
+## 2. 系统架构上下文
+
+### 2.1 传感器类型
+根据PRD v2.0，系统需要支持以下传感器类型：
+- **摄像头**: 视频流数据（V4L2接口）
+- **温度传感器**: 环境温度监控
+- **加速度计**: 车辆运动状态检测  
+- **GPS模块**: 位置信息获取
+- **其他车载传感器**: 待确认具体型号
+
+### 2.2 数据流向
+```
+传感器 → MCU采集 → SPI/UART传输 → SoC接收 → 传感器融合算法 → 应用层使用
+```
+
+## 3. MCU-SoC传感器数据接口
+
+### 3.1 SPI接口规范（主传输通道）
+
+#### 3.1.1 基本参数
+- **传输速率**: ≥10Mbps
+- **最大包长**: 512字节
+- **校验机制**: CRC32校验
+- **重传机制**: 最大3次重传
+
+#### 3.1.2 命令格式
+详细协议规范请参考 `spi_protocol_details.md` 文件。
+
+#### 3.1.3 传感器ID定义
+详细传感器数据格式请参考 `spi_protocol_details.md` 文件。
+
+### 3.2 UART接口规范（健康监控通道）
+
+#### 3.2.1 基本参数  
+- **传输速率**: ≥1Mbps
+- **用途**: SoC健康状态报告 + 关键传感器状态
+- **超时机制**: 3秒无响应触发GPIO复位
+
+#### 3.2.2 状态报告格式
+| 字段 | 长度 | 描述 |
+|------|------|------|
+| Header | 2字节 | 0xAA55 |
+| CPU_Load | 1字节 | CPU负载百分比 |
+| Memory_Usage | 1字节 | 内存使用百分比 |
+| Temp_SoC | 2字节 | SoC温度 (℃ × 10) |
+| Critical_Sensors | 4字节 | 关键传感器状态位图 |
+| CRC16 | 2字节 | 校验码 |
+
+## 4. SoC内部传感器融合接口
+
+### 4.1 数据结构定义
+
+#### 4.1.1 通用传感器数据结构
+```c
+typedef struct {
+    uint8_t sensor_id;
+    uint32_t timestamp_ms;
+    uint16_t data_length;
+    uint8_t* data;
+    uint32_t crc32;
+} sensor_data_t;
+```
+
+#### 4.1.2 融合后数据结构
+```c
+typedef struct {
+    uint32_t fusion_timestamp_ms;
+    uint32_t valid_sensors_mask;
+    // 融合后的环境感知数据
+    float temperature_celsius;
+    int16_t acceleration[3];
+    double gps_position[3]; // lat, lon, alt
+    // 其他融合数据...
+    uint32_t fusion_confidence; // 融合置信度 (0-100)
+} fused_sensor_data_t;
+```
+
+### 4.2 API接口定义
+
+#### 4.2.1 数据接收接口
+```c
+// MCU数据接收回调
+int on_sensor_data_received(sensor_data_t* raw_data);
+
+// 传感器数据队列管理
+int sensor_queue_push(sensor_data_t* data);
+sensor_data_t* sensor_queue_pop(void);
+```
+
+#### 4.2.2 融合算法接口
+```c
+// 执行传感器融合
+int perform_sensor_fusion(fused_sensor_data_t* output);
+
+// 获取最新融合结果
+const fused_sensor_data_t* get_latest_fusion_result(void);
+```
+
+## 5. 实时性要求
+
+### 5.1 端到端延迟
+| 传感器类型 | 最大延迟 | 说明 |
+|------------|----------|------|
+| 摄像头 | 100ms | 满足实时视频处理 |
+| 温度传感器 | 500ms | 环境监控足够 |
+| 加速度计 | 50ms | 车辆安全关键 |
+| GPS | 1000ms | 位置更新频率 |
+
+### 5.2 数据吞吐量
+| 传感器类型 | 数据率 | 带宽需求 |
+|------------|--------|----------|
+| 摄像头 (720p) | 30fps | ~8Mbps |
+| 温度传感器 | 1Hz | ~32bps |
+| 加速度计 | 100Hz | ~4.8kbps |
+| GPS | 1Hz | ~64bps |
+
+## 6. 错误处理与恢复
+
+### 6.1 错误类型
+- **通信错误**: CRC校验失败、超时
+- **数据错误**: 无效传感器ID、数据长度异常
+- **硬件错误**: 传感器离线、MCU异常
+
+### 6.2 恢复策略
+- **通信错误**: 自动重传（最多3次）
+- **数据错误**: 丢弃异常数据包，记录错误日志
+- **硬件错误**: 触发系统健康检查，必要时GPIO复位
+
+## 7. 硬件抽象层(HAL)设计
+
+### 7.1 HAL接口定义
+```c
+// MCU通信HAL
+typedef struct {
+    int (*spi_send)(const uint8_t* data, size_t len);
+    int (*spi_receive)(uint8_t* buffer, size_t max_len);
+    int (*uart_send)(const uint8_t* data, size_t len);
+    int (*gpio_reset)(void);
+} mcu_comm_hal_t;
+
+// 传感器驱动HAL  
+typedef struct {
+    int (*init)(void);
+    int (*read_data)(sensor_data_t* data);
+    int (*get_status)(void);
+} sensor_driver_hal_t;
+```
+
+### 7.2 SoC适配策略
+- 采用硬件抽象层设计，便于不同SoC型号适配
+- 预留SoC型号确认后的配置接口
+- 编译时条件编译支持不同硬件平台
+
+## 8. 待确定事项
+
+### 8.1 硬件相关
+- [ ] **SoC具体型号确认** - 需要联系猪小杰确认PRD v2.0中的SoC选型
+- [ ] **传感器具体型号和规格确认** - 需要获取详细的传感器数据手册
+- [ ] **SPI/UART引脚分配确认** - 需要硬件原理图确认
+
+### 8.2 软件相关  
+- [ ] **传感器融合算法详细规格** - 需要与算法团队确认融合策略
+- [ ] **实时操作系统(RTOS)选择确认** - Linux vs RTOS决策
+- [ ] **内存分配策略确认** - 共享内存池大小和管理策略
+
+## 9. 验收标准
+
+### 9.1 功能验收
+- [ ] 所有传感器数据能够正确传输和解析
+- [ ] 传感器融合算法能够正常工作
+- [ ] 错误处理机制有效
+
+### 9.2 性能验收
+- [ ] 端到端延迟满足第5章节要求
+- [ ] 系统资源占用符合预期
+- [ ] 在-40℃~85℃环境下稳定运行
+
+## 10. 后续工作计划
+
+- [ ] 3月8日: 与猪小杰确认传感器具体规格
+- [ ] 3月9日: 完善详细数据格式和算法接口
+- [ ] 3月10日: 完成最终版接口规范并提交评审

specs/spi_protocol_details.md

@@ -0,0 +1,128 @@
+# SPI通信协议详细规范
+
+## 1. 物理层参数
+- **时钟频率**: 10MHz (可配置范围: 1-20MHz)
+- **数据位宽**: 8位
+- **时钟极性**: CPOL=0 (空闲时低电平)
+- **时钟相位**: CPHA=0 (第一个边沿采样)
+- **MSB/LSB**: MSB first
+- **最大包长**: 512字节 (包含头部和CRC)
+
+## 2. 协议帧格式
+
+### 2.1 基本帧结构
+| 字段 | 长度 | 描述 |
+|------|------|------|
+| SOF | 1字节 | 起始标志 (0xAA) |
+| Command | 1字节 | 命令类型 |
+| Length | 2字节 | 数据长度 (大端序) |
+| Payload | N字节 | 有效载荷 |
+| CRC32 | 4字节 | CRC32校验 (IEEE 802.3) |
+| EOF | 1字节 | 结束标志 (0x55) |
+
+### 2.2 命令类型定义
+| 命令值 | 命令名称 | 描述 |
+|--------|----------|------|
+| 0x01 | POWER_MODE_REQ | 电源模式请求 |
+| 0x02 | POWER_MODE_ACK | 电源模式确认 |
+| 0x03 | DATA_TRANSFER | 传感器数据传输 |
+| 0x04 | DATA_ACK | 数据接收确认 |
+| 0x05 | STATUS_REPORT | 状态报告 |
+| 0x06 | ERROR_REPORT | 错误报告 |
+| 0x07 | CONFIG_UPDATE | 配置更新 |
+| 0x08 | CONFIG_ACK | 配置确认 |
+
+## 3. 传感器数据传输协议 (DATA_TRANSFER)
+
+### 3.1 数据包格式
+```
+SOF(0xAA) + CMD(0x03) + LEN(2B) + [SensorID(1B) + Timestamp(4B) + DataLength(2B) + SensorData(NB)] + CRC32(4B) + EOF(0x55)
+```
+
+### 3.2 传感器数据结构
+| 字段 | 长度 | 描述 |
+|------|------|------|
+| SensorID | 1字节 | 传感器标识符 |
+| Timestamp | 4字节 | 时间戳 (毫秒, 大端序) |
+| DataLength | 2字节 | 传感器数据长度 (大端序) |
+| SensorData | N字节 | 传感器原始数据 |
+
+### 3.3 传感器ID映射表
+| ID | 传感器类型 | 数据格式 | 更新频率 |
+|----|------------|----------|----------|
+| 0x01 | 摄像头 | JPEG/YUV帧 | 30Hz |
+| 0x02 | 温度传感器 | float32 (℃) | 1Hz |
+| 0x03 | 加速度计 | int16[3] (X,Y,Z) | 100Hz |
+| 0x04 | GPS | struct {double lat, lon; float alt;} | 1Hz |
+| 0x05 | 陀螺仪 | int16[3] (X,Y,Z) | 100Hz |
+| 0x06 | 磁力计 | int16[3] (X,Y,Z) | 10Hz |
+| 0x07 | 气压计 | float32 (hPa) | 1Hz |
+| 0x08 | 湿度传感器 | float32 (%) | 1Hz |
+| 0x09-0xFF | 预留 | - | - |
+
+## 4. 流量控制与错误处理
+
+### 4.1 ACK机制
+- SoC收到DATA_TRANSFER后，必须在10ms内回复DATA_ACK
+- ACK包包含接收到的SensorID和Timestamp用于确认
+
+### 4.2 重传机制
+- 如果MCU在20ms内未收到ACK，则重传数据包
+- 最大重传次数: 3次
+- 重传间隔: 10ms
+
+### 4.3 错误码定义
+| 错误码 | 描述 | 处理方式 |
+|--------|------|----------|
+| 0x01 | CRC校验失败 | 丢弃数据包，记录错误 |
+| 0x02 | 包长度超限 | 丢弃数据包，记录错误 |
+| 0x03 | 无效传感器ID | 丢弃数据包，记录错误 |
+| 0x04 | 内存不足 | 丢弃数据包，触发内存清理 |
+| 0x05 | 通信超时 | 触发UART健康检查 |
+
+## 5. 性能指标
+
+### 5.1 带宽计算
+- 摄像头(720p@30fps): ~8Mbps
+- 其他传感器总和: ~100kbps
+- 总带宽需求: ~8.1Mbps
+- SPI实际带宽(10MHz): 10Mbps
+- 带宽利用率: ~81%
+
+### 5.2 实时性要求
+| 传感器类型 | 最大端到端延迟 | SPI传输延迟 |
+|------------|----------------|-------------|
+| 摄像头 | 100ms | <10ms |
+| 加速度计 | 50ms | <5ms |
+| 温度传感器 | 500ms | <1ms |
+| GPS | 1000ms | <1ms |
+
+## 6. 实现注意事项
+
+### 6.1 MCU端实现
+- 使用DMA传输提高效率
+- 实现双缓冲区避免数据丢失
+- 定期发送心跳包维持连接
+
+### 6.2 SoC端实现
+- 使用中断驱动接收
+- 实现环形缓冲区处理突发流量
+- 定期检查MCU健康状态
+
+## 7. 测试用例
+
+### 7.1 功能测试
+- [ ] 正常数据传输
+- [ ] CRC校验失败处理
+- [ ] 包长度边界测试
+- [ ] 传感器ID有效性验证
+
+### 7.2 性能测试
+- [ ] 最大带宽压力测试
+- [ ] 实时性延迟测试
+- [ ] 长时间稳定性测试
+
+### 7.3 异常测试
+- [ ] 通信中断恢复
+- [ ] MCU复位后同步
+- [ ] SoC内存不足处理

specs/uart_protocol_details.md

@@ -0,0 +1,144 @@
+# UART通信协议详细规范
+
+## 1. 协议概述
+
+UART通道主要用于SoC健康状态监控和关键传感器状态报告，作为SPI主通道的补充和备份。
+
+## 2. 物理层参数
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 波特率 | 1000000 | 1Mbps，满足实时性要求 |
+| 数据位 | 8 | 标准8位数据 |
+| 停止位 | 1 | 标准1位停止位 |
+| 校验位 | None | 无校验位 |
+| 流控 | None | 无硬件流控 |
+
+## 3. 帧格式定义
+
+### 3.1 基本帧结构
+```
+[Header: 2B] [Payload: N B] [CRC16: 2B]
+```
+
+### 3.2 Header定义
+- **固定值**: `0xAA55`
+- **用途**: 帧同步和识别
+
+### 3.3 Payload结构
+| 字段 | 长度 | 类型 | 描述 |
+|------|------|------|------|
+| cpu_load | 1字节 | uint8_t | CPU负载百分比 (0-100) |
+| memory_usage | 1字节 | uint8_t | 内存使用百分比 (0-100) |
+| temp_soc | 2字节 | int16_t | SoC温度 (℃ × 10，范围-400~850) |
+| critical_sensors | 4字节 | uint32_t | 关键传感器状态位图 |
+| timestamp_ms | 4字节 | uint32_t | 时间戳 (毫秒) |
+
+### 3.4 CRC16计算
+- **算法**: CRC16-CCITT
+- **初始值**: 0xFFFF
+- **多项式**: 0x1021
+- **输入数据**: Header + Payload
+
+## 4. 通信时序
+
+### 4.1 发送频率
+- **正常状态**: 每100ms发送一次
+- **异常状态**: 每10ms发送一次（CPU负载>90%或内存使用>95%）
+
+### 4.2 超时机制
+- **MCU接收超时**: 300ms（3个周期）
+- **超时处理**: 触发GPIO RESET_N复位信号
+
+### 4.3 状态机
+```
+IDLE → SEND_FRAME → WAIT_ACK → IDLE
+          ↓ (timeout)
+      TRIGGER_RESET
+```
+
+## 5. 关键传感器状态位图
+
+| 位 | 传感器 | 状态值 | 说明 |
+|----|--------|--------|------|
+| 0 | 摄像头 | 0=离线, 1=在线 | 视频流状态 |
+| 1 | 温度传感器 | 0=正常, 1=异常 | 超出工作范围 |
+| 2 | 加速度计 | 0=正常, 1=异常 | 数据异常或离线 |
+| 3 | GPS | 0=无信号, 1=有信号 | 定位状态 |
+| 4-31 | 预留 | - | 未来扩展 |
+
+## 6. 错误处理
+
+### 6.1 CRC校验失败
+- **处理方式**: 丢弃当前帧，记录错误计数
+- **阈值**: 连续5次CRC失败触发告警
+
+### 6.2 帧同步丢失
+- **检测**: 连续3帧Header不匹配
+- **恢复**: 重新同步，从下一个0xAA55开始
+
+### 6.3 数据异常
+- **检测**: CPU负载>100%、内存使用>100%、温度超出范围
+- **处理**: 标记为异常状态，提高发送频率
+
+## 7. MCU端实现要求
+
+### 7.1 接收缓冲区
+- **大小**: 128字节环形缓冲区
+- **处理**: 中断驱动接收，DMA可选
+
+### 7.2 解析逻辑
+```c
+typedef struct {
+    uint8_t header[2];      // 0xAA55
+    uint8_t cpu_load;       // 0-100%
+    uint8_t memory_usage;   // 0-100%
+    int16_t temp_soc;       // ℃ * 10
+    uint32_t critical_sensors;
+    uint32_t timestamp_ms;
+    uint16_t crc16;
+} uart_health_report_t;
+
+int parse_uart_frame(uint8_t* buffer, size_t len, uart_health_report_t* report);
+int validate_health_report(uart_health_report_t* report);
+void handle_health_report(uart_health_report_t* report);
+```
+
+### 7.3 超时监控
+```c
+// 300ms超时定时器
+void start_uart_timeout_timer(void);
+void stop_uart_timeout_timer(void);
+void uart_timeout_handler(void); // 触发GPIO复位
+```
+
+## 8. 性能指标
+
+| 指标 | 要求 | 测试方法 |
+|------|------|----------|
+| 传输延迟 | ≤10ms | 示波器测量 |
+| 误码率 | ≤10⁻⁶ | 长时间压力测试 |
+| CPU占用 | ≤5% | 性能分析工具 |
+| 内存占用 | ≤1KB | 内存分析 |
+
+## 9. 测试用例
+
+### 9.1 正常通信测试
+- 发送标准健康报告帧
+- 验证MCU正确解析和处理
+
+### 9.2 异常处理测试
+- CRC校验失败帧
+- 超时场景模拟
+- 数据异常场景
+
+### 9.3 边界条件测试
+- 最大CPU负载 (100%)
+- 最大内存使用 (100%)
+- 极端温度值 (-40℃, 85℃)
+
+## 10. 与SPI协议的关系
+
+- **主备关系**: SPI为主通道，UART为监控通道
+- **独立性**: UART不依赖SPI状态，独立工作
+- **协同**: UART超时可触发SPI复位，反之亦然