PX4 Commander 模块框架

发表于 更新于 分类于 ， ， 阅读次数： 本文字数： 591 阅读时长 ≈ 2 分钟
全面梳理 PX4 Commander 模块的目录结构、类继承关系、主循环执行流程与各子系统的职责划分，建立学习路径全景视图。

一、模块定位

Commander 是 PX4 的飞行状态中央调度器。负责将全系统的输入事件流（RC、MAVLink、健康状态、链路状态、着陆状态、VTOL 状态、电源按钮）转化为三类核心输出：

输出 内容
vehicle_status 当前模式/arming 状态、各类系统状态
vehicle_control_mode 当前模式对应的控制器/控制环开关（谁该运行）
actuator_armed 解锁/预解锁/lockdown/强制 failsafe 等执行器门禁状态

相关上下文：uORB 通信机制（上） — Commander 通过 uORB 订阅/发布与其他模块通信

二、目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
src/modules/commander/
├── CMakeLists.txt
├── Kconfig
├── module.yaml
│
├── Commander.hpp / Commander.cpp         # ★ 核心主类（中央调度器）
├── commander_helper.h / .cpp             # 辅助函数（LED/蜂鸣器/机型判断）
├── commander_params.c                    # 参数定义
├── px4_custom_mode.h                     # PX4↔MAVLink 模式映射
│
├── ModeManagement.hpp / .cpp             # 模式管理（外部模式注册/替换）
├── UserModeIntention.hpp / .cpp          # 用户模式意图管理
├── Safety.hpp / .cpp                     # 安全开关管理
├── HomePosition.hpp / .cpp               # Home 位置管理
│
├── worker_thread.hpp / .cpp              # 后台工作线程（校准/参数操作）
├── calibration_routines.h / .cpp         # 校准通用框架
├── accelerometer_calibration.*
├── gyro_calibration.*
├── mag_calibration.*
├── baro_calibration.*
├── airspeed_calibration.*
├── esc_calibration.*
├── level_calibration.*
├── rc_calibration.*
├── lm_fit.*                              # Levenberg-Marquardt 拟合（磁力计校准用）
│
├── Arming/
│   └── ArmAuthorization/                 # 外部解锁授权（UTM 等）
│
├── failsafe/                             # ★ 故障安全状态机
│   ├── framework.h / .cpp
│   └── failsafe.h / .cpp
│
├── failure_detector/                     # ★ 故障检测器
│   ├── FailureDetector.hpp / .cpp
│   └── failure_detector_params.c
│
├── HealthAndArmingChecks/                # ★ 健康与解锁检查（33+ 个检查项）
│   ├── HealthAndArmingChecks.cpp
│   └── checks/
│
└── ModeUtil/
    ├── mode_requirements.*               # 模式需求位图
    ├── control_mode.*                    # 控制模式标志设置
    └── conversions.hpp

三、架构图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
graph TD
    subgraph Commander主类
        UMI["UserModeIntention<br/>用户模式意图"]
        MM["ModeManagement<br/>外部模式注册"]
        HP["HomePosition<br/>Home位置管理"]
        Safety["Safety<br/>安全开关"]
        
        Core["handleModeIntentionAndFailsafe()<br/>★核心决策函数★"]
        
        UMI --> Core
        MM --> Core
        HP --> Core
        Safety --> Core
        
        FS["Failsafe<br/>故障安全状态机"]
        HAC["HealthAndArmingChecks<br/>健康与解锁检查(33个)"]
        
        Core --> FS
        Core --> HAC
        
        FD["FailureDetector<br/>物理故障检测"]
        FSF["failsafe_flags<br/>故障安全标志"]
        WT["WorkerThread<br/>后台校准/参数"]
        
        FS --> FD
        FS --> FSF
    end

    subgraph uORB输出
        VS["vehicle_status"]
        AA["actuator_armed"]
        VCM["vehicle_control_mode"]
    end

    subgraph 其他模块
        NAV["navigator"]
        POS["mc_pos_control"]
        EKF["ekf2"]
        MAV["mavlink"]
    end

    Core --> VS
    Core --> AA
    Core --> VCM
    VS --> NAV
    VS --> POS
    VCM --> POS
    AA --> EKF

四、主循环 run() 执行流程（100 Hz）

步骤 操作 说明
1 参数更新 检测参数变化并同步
2 电源按钮处理 处理硬件电源按钮事件
3 系统供电检查 监控供电状态
4 着陆检测更新 读取 vehicle_land_detected
5 安全按钮更新 读取 Safety 按钮状态
6 抛飞起飞更新 MulticopterThrowLaunch 状态机
7 VTOL 状态更新 MC/FW/过渡状态
8 Home 位置更新 自动/手动设置 Home
9 自动 Disarm 着陆后/起飞前超时自动锁定
10 电池检查 电池状态监控
11 任务更新 检查任务状态变化
12 手动控制检查 RC Override 逻辑
13 Offboard 检查 Offboard 信号监控
14 数据链路检查 GCS/OBC 连接监控
15 故障检测更新 FailureDetector 物理故障检测
16 模式管理更新 外部模式注册/注销
17 ★ 模式意图与故障安全 核心决策：合并用户意图 + 故障安全 → 最终 nav_state
18 健康检查（10 Hz） HealthAndArmingChecks 全量检查
19 处理命令 vehicle_command / action_request
20 发布状态 vehicle_status、actuator_armed、vehicle_control_mode
21 声光反馈 LED/蜂鸣器更新

五、八阶段学习路径

1
2
3
4
5
6
7
8
9
10
11
flowchart TD
    A["第一阶段：基础概念<br/>CMakeLists → Kconfig → commander_params → px4_custom_mode<br/>问：Commander长什么样？有哪些模式？"]
    B["第二阶段：工具层<br/>mode_requirements → control_mode → commander_helper → worker_thread<br/>问：每个模式需要什么？控制器怎么激活？"]
    C["第三阶段：独立子系统<br/>Safety → HomePosition → FailureDetector → HealthAndArmingChecks<br/>问：谁在做检查？结果存在哪？"]
    D["第四阶段：故障安全<br/>framework.h/.cpp → failsafe.h/.cpp<br/>问：出了问题怎么办？如何逐级降级？"]
    E["第五阶段：模式管理<br/>UserModeIntention → ModeManagement → ArmAuthorization<br/>问：谁在控制？模式怎么切换？"]
    F["第六阶段：核心主类<br/>Commander.hpp → Commander.cpp<br/>问：大脑如何把一切串起来？"]
    G["第七阶段（按需）：校准子系统"]
    H["第八阶段（按需）：特殊功能 MulticopterThrowLaunch"]

    A --> B --> C --> D --> E --> F --> G --> H

六、关键数据流汇总

子系统 输入 输出
HealthAndArmingChecks 大量传感器/估计器/链路话题 failsafe_flags（*_invalid + mode_req_* 位图）、canArm/canRun 结果
ModeUtil/control_mode nav_state、vehicle_type、offboard_control_mode vehicle_control_mode 开关位
UserModeIntention RC mode slot、MAVLink DO_SET_MODE、action_request 用户意图 nav_state
Failsafe 系统状态、failsafe_flags、override request selected action + 改写后的 intended mode
ModeManagement nav_state_user_intention、外部模式执行器信息 replacement 后的实际 nav_state
HomePosition local/global/GNSS + failsafe_flags home_position 话题
最终输出（run() 统一发布） 上述所有子系统结果 actuator_armed → vehicle_control_mode → vehicle_status → failure_detector_status

下一篇：参数系统与 Kconfig
系列总目录：PX4 v1.16 源码解读总目录