# PX4 源码学习路线

本文面向第一次接触飞控和 PX4 的开发者，结合当前项目使用的 CUAV 7-Nano、PX4 v1.17.0 和尾座式 VTOL，给出一条从基本概念到源码调试的学习路线。

当前 PX4 源码目录：

```text
/home/jiagu/seeker_debug_tool1/simulation_ws/deps/PX4-Autopilot
```

## 1. 学习原则

PX4 包含硬件驱动、状态估计、飞行模式、控制器、通信和安全机制。第一次学习时，不建议直接从 EKF2、寄存器驱动或控制算法细节开始。

建议先沿着下面这条主线建立整体认识：

```text
传感器
  -> 状态估计
  -> 飞行模式与设定值
  -> 姿态/位置控制器
  -> 控制分配
  -> 电机和舵机
```

阅读代码时始终回答三个问题：

1. 这个模块订阅了哪些 uORB 消息？
2. 它根据什么状态或参数进行计算？
3. 它发布了哪些消息，交给哪个下游模块？

实机学习和测试时必须拆下螺旋桨。

## 2. 先掌握 QGroundControl 和飞控基本概念

在深入源码前，先通过 QGroundControl 熟悉：

- 机型和 `SYS_AUTOSTART`
- 参数保存、恢复和重启生效
- 传感器及遥控器校准
- 解锁前检查
- 手动、定高、定点和任务模式
- 多旋翼、固定翼及 VTOL 状态
- failsafe（失效保护）
- 执行器、电机和舵机功能映射
- MAVLink 与地面站通信

当前尾座式 VTOL 的通用实机机型 ID 是：

```text
SYS_AUTOSTART=13200
```

不要选择 `1002`。它是 HIL Standard VTOL QuadPlane，只用于硬件在环仿真。

## 3. 阅读 PX4 启动流程

首先阅读主启动脚本：

```text
ROMFS/px4fmu_common/init.d/rcS
```

重点了解下面的启动顺序：

```text
加载参数
  -> 读取 SYS_AUTOSTART
  -> 加载机型脚本
  -> 启动板载传感器
  -> 启动状态估计器
  -> 启动控制器
  -> 启动 MAVLink 和日志
```

当前尾座式 VTOL 的机型脚本：

```text
ROMFS/px4fmu_common/init.d/airframes/13200_generic_vtol_tailsitter
```

阅读时重点关注：

- `CA_AIRFRAME`：控制分配机型类型
- `CA_ROTOR_COUNT`：电机数量
- `CA_SV_CS_COUNT`：舵面数量
- `MAV_TYPE`：MAVLink 飞行器类型
- `VT_TYPE`：VTOL 类型
- `VT_B_TRANS_DUR`：回到多旋翼模式的过渡时间

通用 `13200` 默认是两电机、两舵面配置。如果实际飞机是四电机、三舵机或四舵面，需要按真实结构重新配置控制分配，不能直接照搬默认值。

## 4. 理解 uORB 消息总线

uORB 是 PX4 内部模块间的消息总线。模块通常通过发布和订阅消息交换数据，而不是直接互相调用。

典型数据流：

```text
传感器驱动
  -> sensor_* 消息
  -> EKF2
  -> vehicle_attitude / vehicle_local_position
  -> 飞行模式和控制器
  -> vehicle_torque_setpoint / vehicle_thrust_setpoint
  -> control_allocator
  -> actuator_motors / actuator_servos
```

消息定义目录：

```text
msg/
```

建议优先了解这些消息：

```text
sensor_combined
vehicle_attitude
vehicle_local_position
vehicle_global_position
vehicle_status
vehicle_control_mode
vehicle_attitude_setpoint
vehicle_rates_setpoint
vehicle_torque_setpoint
vehicle_thrust_setpoint
actuator_motors
actuator_servos
```

可以在 PX4 Shell 中观察消息：

```sh
listener vehicle_attitude
listener vehicle_status
listener actuator_motors
uorb top
```

## 5. 学习 Commander 和飞行模式

### 5.1 Commander

目录：

```text
src/modules/commander
```

Commander 主要负责：

- 解锁和上锁
- 飞行器状态管理
- 健康与解锁前检查
- 飞行模式切换
- failsafe 决策
- 电池、遥控和导航状态处理

遇到“无法解锁”“模式切换失败”或“进入 failsafe”时，优先沿 Commander 和健康检查代码排查。

### 5.2 Flight Mode Manager

目录：

```text
src/modules/flight_mode_manager
```

它根据当前飞行模式生成位置、速度或轨迹设定值。建议先区分：

- 飞行模式负责决定“飞机应该去哪里、以什么状态运动”
- 姿态和位置控制器负责决定“怎样产生对应的力和力矩”

## 6. 沿多旋翼控制链阅读

多旋翼控制链：

```text
mc_pos_control
  -> mc_att_control
  -> mc_rate_control
  -> control_allocator
```

对应目录：

```text
src/modules/mc_pos_control
src/modules/mc_att_control
src/modules/mc_rate_control
src/modules/control_allocator
```

各模块作用：

- `mc_pos_control`：位置和速度控制，输出姿态与推力设定值
- `mc_att_control`：姿态控制，输出角速度设定值
- `mc_rate_control`：角速度控制，输出机体力矩和推力
- `control_allocator`：将期望力和力矩分配给各电机与舵面

尾座式 VTOL 在起飞、悬停和垂直降落阶段主要使用这条控制链。

## 7. 沿固定翼控制链阅读

对应目录：

```text
src/modules/fw_mode_manager
src/modules/fw_lateral_longitudinal_control
src/modules/fw_att_control
src/modules/fw_rate_control
```

各模块主要作用：

- `fw_mode_manager`：固定翼飞行模式与设定值管理
- `fw_lateral_longitudinal_control`：横向和纵向制导/控制
- `fw_att_control`：固定翼姿态控制
- `fw_rate_control`：固定翼角速度控制

尾座式 VTOL 完成前向过渡后，主要使用固定翼控制链。

## 8. 重点学习 VTOL 状态与过渡

目录：

```text
src/modules/vtol_att_control
```

对尾座式飞机，这是最需要重点阅读的模块。建议关注：

- 当前处于多旋翼、前向过渡、固定翼还是反向过渡状态
- 多旋翼和固定翼控制输出如何混合
- 过渡完成条件
- 过渡超时和失败处理
- 空速是否参与过渡判断
- `VT_*` 参数如何影响状态机

先理解状态机，再调整过渡参数。不要在不清楚状态转换条件时直接修改控制输出。

## 9. 学习控制分配与执行器

目录：

```text
src/modules/control_allocator
```

控制器输出的是期望力和力矩，控制分配器将其转换成具体电机和舵机命令。

需要结合实际飞机确认：

- 电机数量和物理位置
- 每个电机的推力方向
- 电机旋转方向和反扭矩符号
- 舵面类型、方向和力矩作用
- 输出通道对应关系
- 多旋翼和固定翼模式下哪些执行器参与控制

控制分配错误可能导致飞机一解锁就翻转。执行器检查必须无桨进行。

## 10. 最后学习 EKF2

目录：

```text
src/modules/ekf2
```

EKF2 融合以下数据并估计姿态、位置、速度和传感器偏差：

- IMU（加速度计和陀螺仪）
- GPS/GNSS
- 磁罗盘
- 气压计
- 空速计
- 光流或视觉里程计（如果使用）
- 测距传感器（如果使用）

初学阶段先理解 EKF2 的输入、输出和健康状态，不需要立刻深入协方差矩阵及融合数学。

可先观察：

```sh
listener estimator_status
listener estimator_status_flags
listener vehicle_attitude
listener vehicle_local_position
```

## 11. 学习 CUAV 7-Nano 板级代码

板级目录：

```text
boards/cuav/7-nano
```

主要内容包括：

- `default.px4board`：默认启用的驱动和模块
- `minimal_vtol.px4board`：当前项目的精简 VTOL 配置
- `init/rc.board_sensors`：板载传感器启动
- `src/board_config.h`：GPIO、总线和板级定义
- `src/spi.cpp`：SPI 设备和片选配置
- `src/i2c.cpp`：I2C 总线配置
- `src/can.c`：CAN 板级初始化
- `nuttx-config`：NuttX 系统配置

建议在理解上层数据流之后再深入板级驱动，否则容易陷入引脚、总线和寄存器细节。

## 12. MAVLink、DroneCAN 和 ROS 2 的区别

### MAVLink

主要用于 PX4 与 QGroundControl、数传和伴随计算机通信。当前实机需要保留 MAVLink。

### DroneCAN/UAVCAN

用于连接 CAN GPS、CAN 空速计、CAN 电调等设备。当前固件保留了 DroneCAN 支持。

### Micro XRCE-DDS

用于 PX4 与 ROS 2 交换 uORB/`px4_msgs` 数据。如果实机不使用 ROS 2，可以在精简固件中关闭。

## 13. 推荐的第一个源码练习

第一个练习建议新增一个只读模块：

```text
订阅 vehicle_attitude
  -> 每隔一段时间输出滚转、俯仰和偏航
  -> 不发布控制指令
```

这个练习可以学习：

- PX4 模块基本结构
- CMake/Kconfig 配置
- 编译和刷写
- uORB 订阅
- PX4 Shell 命令
- 日志和调试

它不会直接改变控制器或执行器输出，风险明显低于一开始修改姿态控制、VTOL 状态机或 EKF2。

## 14. 推荐学习阶段

### 第一阶段：会使用和观察

- 完成机型选择和传感器校准
- 会使用 `param show`、`listener`、`uorb top`、`top` 和 `ver all`
- 能看懂启动日志中的模块启动顺序
- 理解 QGC、MAVLink 和 uORB 的职责

### 第二阶段：看懂控制数据流

- 跟踪姿态、位置和执行器消息
- 理解多旋翼、固定翼和 VTOL 控制链
- 理解控制分配参数与实际执行器的关系
- 能从日志判断当前 VTOL 状态

### 第三阶段：进行低风险修改

- 新增只读模块
- 新增参数
- 增加日志和状态检查
- 在 SITL 中验证修改

### 第四阶段：修改飞行行为

- 调整控制器或过渡逻辑
- 修改控制分配
- 增加新的传感器或通信接口
- 完成 SITL、台架和实机分阶段验证

## 15. 安全边界

以下修改不适合作为第一次练习：

- 删除解锁前检查或 failsafe
- 绕过传感器校准
- 直接修改 EKF2 融合逻辑
- 未验证就修改电机混控和旋向
- 在有桨状态进行执行器测试
- 将 SITL 参数整套导入实机
- 未完成悬停验证就尝试 VTOL 过渡

推荐验证顺序：

```text
SITL
  -> 无桨上电检查
  -> 无桨执行器测试
  -> 固定台架测试
  -> 低风险悬停
  -> 固定翼与过渡测试
```