# JetWave ECU 动力模组程序分析计划

**文档版本：** v1.0  
**生成日期：** 2026-05-26  
**代码基线：** `JetWaveECU-master-2d55e90f4a54d61a83efab89195082109acd3472`（commit `2d55e90f`）  
**关联现场数据：** `surf_motion_trajectory_history2.csv`、OSS 轨迹明细、荷兰/全量日志分析报告  

---

## 一、分析背景与目标

### 1.1 业务背景

动力模组（ECU）是 Jetwave 板体上的 **ESP32 主控**，负责：

- 接收遥控器（RC）油门/档位/模式（MAVLink over BLE 或星闪 NearLink）
- 经 **TWAI/CAN（UAVCAN/DroneCAN）** 控制电调（ESC）、读取 BMS
- 融合 **IMU（ICM42688P）** 做姿态与纵向自稳（ALC）
- 以 **500ms 心跳 + 事件通知** 上报 App（`EcuHeatbeatData` / `DeviceEventNotice`）
- 可选 **Ulog** 落盘（ECU/ESC/RC 通道）供售后与研发复盘

近一月现场日志已暴露：**失速保护 STALL（esc 0x20000）**、**ECU↔ESC 通信（ecu 0x40000000）**、**姿态异常（roll±180° 数据特征）**、**荷兰区域 STALL 集中在东部设备** 等现象。本计划用于 **对照源码逐项验证根因与改进点**。

### 1.2 分析目标

| 目标 | 说明 |
|------|------|
| **G1 故障闭环** | 厘清 `esc_event` / `ecu_event` 从 ESC 硬件 → UAVCAN → ECU 聚合 → MAVLink → App 的完整链路 |
| **G2 失速与油门** | 解释「有油门无电机」、STALL 置位/恢复条件，与 `MotorSpeedControlTask` 逻辑对齐 |
| **G3 通信可靠性** | 评估 TWAI 调度、ESC 上报降频、RC 20ms 油门与心跳 500ms 是否导致「假断联」 |
| **G4 姿态可信性** | 分析 IMU→Madgwick→`attitude[]` 为何出现 ±180°，与 `FAULT_BOARD_ATTITUDE` 触发条件 |
| **G5 可测试性** | 输出可 HIL/台架/现场复现的用例清单，并与荷兰等问题 SN 绑定 |

### 1.3 非目标（本期不做）

- 不修改生产固件（除非单独立项「补丁验证」阶段）
- 不重写 ESC 电机控制算法（属电调固件 `SineMotion`/UAVCAN ESC 节点）
- 不替代 App 端 `jetwave-rc-2000/3000` 代码审查（已有独立 CODE_REVIEW，仅做接口对齐）

---

## 二、系统架构（分析前必读）

### 2.1 软件分层

```mermaid
flowchart TB
    subgraph RC["遥控器 App"]
        APP[HomeFragment / MAVLink Parser]
    end
    subgraph LINK["无线链路"]
        BLE[ESP32 BLE]
        NL[NearLink 星闪 UART]
    end
    subgraph ECU["ECU ESP32"]
        MAIN[main.c]
        ECU_M[ecu_manager.c]
        ESC_M[esc_manager.c]
        BMS_M[bms_manager.c]
        PROTO[protocol_common_interface.c]
        MAV[mavlink_ble.c]
        UAV[uavcan_twai.c]
        IMU[icm42688p + MadgwickAHRS]
        ULOG[ulog_logger.c]
    end
    subgraph CAN["TWAI / CAN 总线"]
        ESC_HW[ESC 电调节点]
        BMS_HW[BMS 节点]
    end
    APP <-->|MAVLink| BLE
    APP <-->|MAVLink| NL
    BLE --> PROTO
    NL --> PROTO
    PROTO --> ECU_M
    PROTO --> ESC_M
    ECU_M --> MAV
    ESC_M --> UAV
    ECU_M --> UAV
    UAV <-->|UAVCAN| ESC_HW
    UAV <-->|UAVCAN| BMS_HW
    ESC_M --> IMU
    ECU_M --> ULOG
    ESC_M --> ULOG
```

### 2.2 关键目录与职责

| 路径 | 职责 | 分析优先级 |
|------|------|------------|
| `App/ecu_manager.c` | 心跳 500ms、故障掩码、事件状态机、上报 RC | **P0** |
| `App/esc_manager.c` | 油门→转速、`MotorSpeedControlTask`、ESC 故障二次加工、ALC | **P0** |
| `App/bms_manager.c` | BMS 数据与故障 | P1 |
| `Protocol/uavcan_twai.c` | ESC/BMS UAVCAN 编解码与队列 | **P0** |
| `Protocol/protocol_common_interface.c` | MAVLink 组包、姿态写入心跳 | **P0** |
| `Protocol/mavlink_ble.c` | BLE 收发 MAVLink | P1 |
| `Lib/JetWaveMavlink/xml/JetWave.xml` | **故障码权威定义**（EscFaultMask/EcuFaultMask） | **P0** |
| `Lib/JetWaveDsdl/esc` | ESC UAVCAN DSDL | P1 |
| `Sensors/icm42688p.c` | IMU 驱动 | **P0**（姿态问题） |
| `Lib/MadgwickAHRS` | 姿态解算 | **P0** |
| `Ulog/ulog_logger.c` | 黑匣子 ESC/ECU/RC | P1 |
| `Ota/esc_ota.c` | 电调升级 | P2 |
| `NearLink/*` | 星闪替代 BLE | P1 |

### 2.3 与 App 日志字段对照

| 轨迹字段 | ECU 侧来源 | 说明 |
|----------|------------|------|
| `attitude` | `ecu_manager` → `GetAttitudeRoll/Pitch/Yaw()*10` | 0.1° 精度，App 再 ÷10 |
| `escEventCode` | `(runningError<<16) \| selfcheckError` 或 ESC 原生 event | 需核对 `UpdateEventDataByDevice` |
| `ecuEventCode` | `ecu_manager` 聚合 + 掩码 | `FAULT_ESC_COMMUNICATION = 0x40000000` |
| `motorSpeed` | ESC `SetSpeedResponse.speed` | 与 `SendSetSpeedRequest` 闭环 |
| `throttleLeverQuantity` | RC `ThrottleAndGear.throttle` | 0～1000 |
| `mode` / `gear` | RC 下发 | 关联 `maxSpeedForModes[3][16]` |

---

## 三、现场问题与代码映射（分析输入）

以下条目来自 `history2` / 荷兰报告 / 全量 719 条分析，作为 **必须覆盖的验证项**。

| 现场现象 | 日志特征 | 优先查代码位置 |
|----------|----------|----------------|
| 失速不可控 | `escEventCode & 0x20000`（STALL） | `JetWave.xml` `ESC_FAULT_STALL_PROTECTION`；ESC 固件；`esc_manager` 是否屏蔽/转发 |
| 断联代理 | `ecuEventCode & 0x40000000` | `FAULT_ESC_COMMUNICATION`；`uavcan_twai` 超时；`ESC_FAULT_MASK` |
| 过压 | `escEventCode & 0x400000` | `ESC_FAULT_OVERVOLTAGE_PROTECTION` |
| 姿态 roll≈180° | `attitude` 第一分量跳变 | `icm42688p` + Madgwick + 坐标系定义；非必然翻板 |
| 有油门无电机 | throttle>0, motorSpeed=0 | `MotorSpeedControlTask` 限速/保护/模式；STALL 后是否清零转速指令 |
| 荷兰东部 STALL | SN `231AAAA5C001688` | 区域无关代码，但需排除 ECU 侧地域配置差异 |
| 阿姆斯特丹无 STALL | 仅急弯/长航行 | 验证 STALL 与操控/负载相关，非 GPS 区域逻辑 |

---

## 四、分析阶段与任务拆解

### 阶段 0：环境与基线（0.5 天）

| 任务 | 内容 | 产出 |
|------|------|------|
| 0.1 | 确认 ESP-IDF 版本、`sdkconfig`、与 README 构建步骤一致 | 构建说明附录 |
| 0.2 | 导出 `CONFIG_*`：IMU、NearLink、SD Ulog、TWAI 波特率 | 配置对照表 |
| 0.3 | 锁定 `JetWave.xml` 与 App `EscFaultMask.java` / `EcuFaultMask.java` 一致性 | 故障码对照表（hex） |

### 阶段 1：故障码与上报链路（2 天）— **P0**

| 任务 | 分析要点 | 关键文件 |
|------|----------|----------|
| 1.1 | **ESC 原生故障** vs **ECU 二次故障**（`UpdateESCErrorCodeByRunningStatus`）如何合并进 `esc_event` | `esc_manager.c` 147～248 行 |
| 1.2 | `runningError<<16 \| selfcheckError` 与 App 解析是否一致 | `ecu_manager.c` `UpdateEventDataByDevice` |
| 1.3 | `ESC_FAULT_MASK` 屏蔽了哪些位（PWM 丢失、油门饱和等）对现场的影响 | `ecu_manager.c` 41～42 行 |
| 1.4 | `EventCodeProcessByBit` 状态机：ECU/ESC/BMS 上报顺序与去抖 | `ecu_manager.c` 179～335 行 |
| 1.5 | **STALL 0x20000** 是否在 MASK 后仍上报；恢复条件在 ESC 侧还是 ECU 侧清零油门 | `esc_manager` + ESC DSDL |

**阶段 1 交付：** 《故障码链路说明书》+ 与 49 条荷兰会话的对照表

### 阶段 2：动力控制与失速（2～3 天）— **P0**

| 任务 | 分析要点 | 关键文件 |
|------|----------|----------|
| 2.1 | `MotorSpeedControlTask` 周期（200ms?）与 RC 20ms 油门关系 | `esc_manager.c` `MotorSpeedControlTask` |
| 2.2 | 模式/档位 → `maxSpeedForModes` → `MotorSpeed` 计算链 | 71～76、346～437 行 |
| 2.3 | 俯仰自稳 ALC 如何叠加到转速（`angleKp/Ki/Kd`） | 401～403 行 |
| 2.4 | 空转保护逻辑（已部分注释）与 GPS `vel<=2` 条件 | 206～228 行 |
| 2.5 | `SendSetSpeedRequest` 失败/队列满时行为 | `uavcan_twai.c` |
| 2.6 | **STALL 场景**：有油门时 ECU 是否仍发非零转速 | 台架日志 + Ulog `RC`/`ESC` 通道 |

**阶段 2 交付：** 《油门-转速-失速时序图》+ 建议复现用例（含 15349/15353）

### 阶段 3：通信与实时性（1.5 天）— **P0**

| 任务 | 分析要点 | 关键文件 |
|------|----------|----------|
| 3.1 | ESC 状态上报降频（每 10 帧发 1 次队列）对故障检测延迟的影响 | `uavcan_twai.c` 58～62 行 |
| 3.2 | TWAI 总线错误恢复、与 `FAULT_ESC_COMMUNICATION` 置位条件 | `twai_ops_esp32.c` |
| 3.3 | BLE vs NearLink 初始化分支对 RC 链路的影响 | `main.c` 136～161 行 |
| 3.4 | `throttleLostCnt` / 油门丢失保护（Ulog RC 字段） | `esc_manager` + `mavlink` |

**阶段 3 交付：** 《通信时序与故障延迟评估》

### 阶段 4：姿态与 IMU（1.5 天）— **P0**

| 任务 | 分析要点 | 关键文件 |
|------|----------|----------|
| 4.1 | IMU 安装轴向与 `GetAttitudeRoll/Pitch/Yaw` 定义 | `icm42688p.c`、`protocol_common_interface.c` 668～670 |
| 4.2 | 欧拉角 ±180° 跳变：是否需改用四元数或约束 roll 展示 | Madgwick |
| 4.3 | `FAULT_BOARD_ATTITUDE` 触发条件（ECU 侧，非仅 App） | `ecu_manager` / `JetWave.xml` |
| 4.4 | 与现场「pitch 小、roll 跳 180」会话对照（如 15410） | 日志 + Ulog |

**阶段 4 交付：** 《姿态数据可信性说明》+ App/云端展示建议

### 阶段 5：日志、配置与 OTA（1 天）— **P1**

| 任务 | 分析要点 |
|------|----------|
| 5.1 | Ulog 字段与 OSS 轨迹字段是否一一对应 |
| 5.2 | `SaveAutoLevelControlParamsToFile` / Flash 参数是否会错机型 |
| 5.3 | `esc_ota` / `ecu_ota` 版本与 `esc_version` 0551/0542 关系 |

### 阶段 6：与 App / 云端交叉验证（1 天）— **P0**

| 任务 | 内容 |
|------|------|
| 6.1 | 对照 `jetwave-rc-2000/3000`：`HomeFragment` 故障 `==` vs 位运算 |
| 6.2 | 抽 3 条 P0 会话：拉 Ulog + OSS + 后台轨迹，做时间轴对齐 |
| 6.3 | 更新 `CODE_REVIEW` 与荷兰报告中「固件侧待确认」项 |

---

## 五、分析方法

### 5.1 静态分析

- **调用链追踪**：`ThrottleAndGear` → `MotorSpeedControlTask` → `SendSetSpeedRequest` → `HandleEscSetSpeedResponse` → `UpdateEcuHeatbeatDataByDevice` → MAVLink 发送
- **故障位图**：以 `JetWave.xml` 为源，生成 C/Java/日志三方对照表
- **配置审查**：`ESC_FAULT_MASK`、`FAULT_DURATION_CYCLES`（12s）、温度/电流阈值

### 5.2 动态分析（建议）

| 手段 | 用途 |
|------|------|
| ESP32 JTAG + 日志 | 观察 `ESC_MANAGER` / `ECU_MANAGER` 故障状态变化 |
| TWAI 抓包（CAN 分析仪） | 验证 STALL 时 ESC 节点实际上报 |
| Ulog 回放 | 对齐 `history2` 问题时刻的 RC/ESC 曲线 |
| 台架 | 复现 STALL：负载/堵转/低电压 |

### 5.3 与数据团队协同

- 使用已有脚本：`analysis/esc_fault_analysis.py`、`attitude_turn_analysis.py`
- 对 **荷兰 49 条**、**STALL 全量 49 条** 输出「建议查 ECU 版本 + esc 固件版本」分布

---

## 六、交付物清单

| 序号 | 交付物 | 格式 | 阶段 |
|------|--------|------|------|
| D1 | 故障码三方对照表（XML / ECU / App / 日志） | Markdown + Excel | 1 |
| D2 | 动力控制时序图（油门→转速→ESC 反馈） | Mermaid + PNG | 2 |
| D3 | 《ECU 动力模组代码审查报告》 | Markdown | 1～4 汇总 |
| D4 | 台架/现场测试用例集（含荷兰 P0 SN） | Markdown 表格 | 2、6 |
| D5 | 问题单列表（代码位置 + 建议修改方向） | 表格 | 全程 |
| D6 | 可选：Ulog 与 OSS 对齐工具说明 | 补充 `analysis/README` | 6 |

建议报告存放路径：

```text
analysis/reports/
  JETWAVE_ECU_POWERTRAIN_ANALYSIS_PLAN.md          ← 本文
  JETWAVE_ECU_FAULT_CODE_MATRIX.md                  ← 阶段 1
  JETWAVE_ECU_POWERTRAIN_CODE_REVIEW.md             ← 阶段 1～4 汇总
  JETWAVE_ECU_STALL_TEST_CASES.md                   ← 阶段 2、6
```

---

## 七、优先级与排期建议

| 周 |  focus | 对应现场问题 |
|----|--------|--------------|
| 第 1 周 | 阶段 0～1 + 阶段 6.1 | STALL / ECU 通信码澄清 |
| 第 2 周 | 阶段 2 + 阶段 3 | 失速不可控、假断联 |
| 第 3 周 | 阶段 4 + 阶段 5 + 汇总 D3 | 姿态 180°、报告定稿 |

**人力建议：** 固件 1 人主责 + 数据/App 各 0.5 人配合阶段 6。

---

## 八、风险与依赖

| 风险 | 缓解 |
|------|------|
| ESC 固件源码不在本仓库 | 通过 UAVCAN DSDL + 台架 CAN 抓包 + 厂家文档 |
| 无法复现荷兰环境 | 用同 SN 台架 + 同 esc 版本 0551/0542 |
| roll±180° 误判为产品问题 | 分析报告明确「数据表示问题」与「真实倾覆」区分 |
| NearLink/BLE 双链路差异 | 分别记录连接类型再对比日志 |

---

## 九、成功标准（Definition of Done）

- [ ] 现场 TOP3 故障码（STALL、ECU 通信、过压）均有 **端到端链路图** 与代码行号引用  
- [ ] 至少 **2 条** 问题会话（建议 15349、15382）完成 Ulog/OSS/代码三方时间对齐  
- [ ] 明确 **STALL 后 ECU 是否限扭/清零油门** 的结论与建议  
- [ ] 明确 **姿态 roll±180°** 是否为 IMU/算法问题及修复建议（坐标系/四元数/滤波）  
- [ ] 输出 **可执行测试用例 ≥10 条**，研发签字认可  

---

## 十、附录

### A. 核心故障码速查（与 `JetWave.xml` 一致）

| 名称 | 值 | 日志中常见 |
|------|-----|------------|
| `ESC_FAULT_STALL_PROTECTION` | 0x00020000 (131072) | 是 |
| `ESC_FAULT_OVERVOLTAGE_PROTECTION` | 0x00400000 (4194304) | 偶发 |
| `FAULT_ESC_COMMUNICATION` | 0x40000000 (ECU) | 常与 STALL 同会话 |
| `FAULT_BOARD_ATTITUDE` | 0x04000000 (ECU) | App 有，轨迹需结合 pitch |

### B. 关键任务与周期（待实测确认）

| 任务/定时 | 代码线索 | 待验证 |
|-----------|----------|--------|
| ECU 心跳 | `ECU_HEATBEAT_INTERVAL` 500ms | 与轨迹 1Hz 一致 |
| RC 油门 | XML：主界面 20ms 间隔 | 与 `MotorSpeedControlTask` 关系 |
| ESC 上报 | UAVCAN 队列每 10 帧 1 次 | 故障延迟 |
| 电机控制 | `MotorSpeedControlTask` | 周期需读任务创建处 |

### C. 关联报告索引

| 文档 | 路径 |
|------|------|
| 昨日 history2 总报告 | `analysis/reports/HISTORY2_DAILY_REPORT_20260526_092858.md` |
| 荷兰异常报告 | `analysis/reports/NETHERLANDS_ABNORMAL_REPORT_20260526_190035.md` |
| App CODE_REVIEW | `analysis/reports/CODE_REVIEW_jetwave-rc-*.md` |
| 三类故障筛选 | `analysis/reports/FAULT_FILTER_STALL_OV_ECU_REPORT.md` |

---

*本计划为分析工作说明书；阶段 1 完成后可据此生成《JETWAVE_ECU_FAULT_CODE_MATRIX.md》作为下一文档。*