4. PX4源码结构：顶层目录结构解析
说实话，我第一次打开PX4源码的时候，也有点懵。一堆文件夹，不知道从哪看起。但搞了几年飞控开发后，我发现这个目录结构其实设计得很讲究。今天我就带你捋一遍，哪些是核心，哪些可以暂时忽略。
4.1 顶层目录总览
先看整体。你下载完源码，ls 一下，会看到这些主要文件夹：
Firmware/
├── src/ # 核心源码
├── boards/ # 板级支持
├── msg/ # uORB消息定义
├── platforms/ # 平台抽象层
├── ROMFS/ # 文件系统镜像
├── Tools/ # 工具脚本
├── cmake/ # 构建配置
├── makefiles/ # 编译规则
├── test/ # 测试代码
├── integrationtests/ # 集成测试
└── Docker/ # 容器环境嗯，这里要注意：src、boards、msg 这三个是你最常打交道的。其他文件夹，比如 Docker、test，平时用得少，但关键时刻能救命。
4.2 src/ —— 飞控的大脑
这是整个PX4的核心。所有飞行逻辑、控制算法、传感器处理都在这里。我习惯把它分成三层来看：
| 子目录 | 作用 | 我常改的地方 |
|---|---|---|
| modules/ | 功能模块（姿态估计、位置控制、GPS处理等） | ✅ 经常 |
| drivers/ | 传感器驱动（IMU、磁力计、气压计等） | ✅ 偶尔 |
| lib/ | 通用库（数学工具、滤波算法等） | ❌ 很少 |
| systemcmds/ | 系统命令（参数读写、日志等） | ❌ 几乎不动 |
| examples/ | 示例代码（学习用） | ✅ 新手必看 |
举个例子，src/modules/ekf2 是扩展卡尔曼滤波器，负责融合IMU和GPS数据。我在项目中遇到过，如果GPS信号不好，EKF2的参数调不好，飞机会飘得厉害。说白了，这里就是飞控的「大脑皮层」。
核心建议： 刚开始别贪多。先盯住 src/modules 和 src/drivers 两个目录。其他等遇到具体问题再深入。
4.3 boards/ —— 你的硬件长什么样
这个文件夹定义了PX4支持的所有硬件平台。从Pixhawk 1到CUAV V5+，再到树莓派，都在这里。
每个板子目录下，一般包含：
- board_config.cmake：板子的编译配置（CPU型号、外设映射）
- nuttx-config/：NuttX实时操作系统的配置
- default.px4board：默认的板级参数
我记得有一次，客户要用一个非标飞控板。我直接在 boards/ 下新建了一个目录，复制了Pixhawk 4的配置，然后改引脚映射。前后花了半天，板子就跑起来了。这就是 boards/ 的威力——硬件抽象做得好，移植成本就低。
小技巧： 如果你用的是常见飞控（如Pixhawk 4），直接看 boards/px4/fmu-v5/ 就行。里面包含了所有外设的默认配置。
4.4 msg/ —— 模块间的「悄悄话」
PX4的模块之间怎么通信？靠的就是 msg/ 目录下的uORB消息定义。每个 .msg 文件定义了一种数据结构，比如：
# sensor_combined.msg
uint64 timestamp
float32[3] gyro_rad
float32[3] accelerometer_m_s2
float32[3] magnetometer_ga你想想看，姿态估计模块订阅了这个消息，就能拿到IMU数据。控制模块再订阅姿态估计的输出。整个飞控就像一条流水线，消息就是传送带上的零件。
我曾经踩过一个坑：自己加了一个自定义消息，但忘了在 CMakeLists.txt 里注册。结果编译通过，运行时模块就是收不到数据。查了半天才发现是消息没被生成。所以，加消息一定要改cmake。
避坑指南： 修改 msg/ 下的文件后，一定要重新编译整个工程。只编译单个模块是没用的，因为消息头文件是全局生成的。
4.5 其他重要目录
除了上面三个核心目录，还有几个你迟早会碰到的：
- platforms/：平台抽象层。比如POSIX（Linux仿真）和NuttX（嵌入式）的实现。你在电脑上仿真跑PX4，就是靠这里的代码。
- ROMFS/：文件系统镜像。里面放了启动脚本、默认参数文件。我经常改
ROMFS/px4fmu_common/init.d/下的脚本，来定制飞控的启动流程。 - Tools/：各种工具。比如
setup.sh一键安装环境，jMAVSim仿真器。新手可以先从这里入手。 - cmake/ 和 makefiles/：构建系统的配置。一般不用动，除非你要加新的编译选项。
4.6 一张图看懂整体结构
下面这张SVG图，是我自己梳理的PX4源码顶层结构。你可以把它当成地图，以后迷路了就回来看看。
从这张图能看出来，PX4的架构是分层的。核心层负责飞控逻辑，支撑层提供运行环境，测试层保证质量。你平时开发，主要就在核心层和支撑层之间来回切换。
4.7 我的个人建议
如果你是第一次接触PX4源码，我建议你按这个顺序来熟悉：
- 先看
msg/—— 了解模块之间传递什么数据。这是理解系统架构的钥匙。 - 再看
src/modules—— 挑一个简单的模块，比如land_detector（着陆检测），读一遍代码。 - 最后看
boards/—— 找到你的飞控板，看看它的配置。不需要全懂，知道去哪改引脚就行。
嗯，其实源码结构这东西，看十遍不如动手改一遍。我当年就是硬着头皮改了一个传感器的驱动，才真正搞懂 src/drivers 和 boards/ 是怎么配合的。你也试试看？