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 软件分层
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 |
建议报告存放路径：
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》作为下一文档。