📚 课程目录第3章开发环境搭建

3. 开发环境搭建

PX4 自定义模块与 uORB 开发的第一步，不是写代码，而是把“能编译、能仿真、能烧录”的闭环环境搭起来。环境搭建的质量直接决定后续调试效率：工具链版本不匹配会导致编译报错，子模块缺失会让 uORB 消息生成失败，仿真环境没配好则无法验证模块行为。本节按“系统 → 工具链 → 源码 → 编译 → 仿真 → 硬件目标”的顺序，给出可复现的搭建路径。

一、核心原理：PX4 构建系统的三层依赖

PX4 的构建不是单一 Makefile，而是由三层依赖共同决定：宿主系统层提供基础编译环境，工具链层提供交叉编译器与 Python 依赖，源码与子模块层提供 uORB 消息定义、驱动和板级配置。三者缺一不可，且版本必须与 PX4 固件版本对齐。

宿主系统层：Ubuntu 20.04/22.04 LTS 是官方推荐版本，内核与 glibc 版本影响工具链兼容性。
工具链层：包括 GCC 交叉编译器、CMake、Ninja、Python3 及 pip 包（如 empy、pyyaml、jinja2）。
源码与子模块层：PX4-Autopilot 主仓库通过 git submodule 引入 mavlink、uORB 消息库、NuttX 等，缺失子模块会导致 uORB 消息无法生成。

关键认知：uORB 消息的 C++ 头文件是在编译时由 msg/ 目录下的 .msg 文件自动生成的。因此，源码下载不完整或子模块未更新，会直接表现为“找不到 uORB 消息头文件”的编译错误。

二、方法流程：从零到可编译的六步操作

以下命令以 Ubuntu 22.04 为例，建议在干净系统中执行，避免旧版本工具链干扰。

# 1. 安装基础依赖
sudo apt update
sudo apt install -y git cmake ninja-build build-essential \
  python3 python3-pip python3-dev

# 2. 克隆 PX4 源码（含子模块）
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot

# 3. 运行官方环境脚本（自动安装工具链与 Python 依赖）
bash Tools/setup/ubuntu.sh

# 4. 更新子模块（若克隆时未加 --recursive）
git submodule update --init --recursive

# 5. 编译 SITL 仿真目标
make px4_sitl_default

# 6. 启动 Gazebo 仿真
make px4_sitl gazebo-classic

执行完第 5 步后，若终端出现 Build finished successfully，说明工具链与源码层已打通。第 6 步会启动 PX4 SITL 与 Gazebo，进入仿真飞行状态。

三、仿真环境与硬件目标配置

PX4 支持多种仿真后端，常见的有 Gazebo Classic、Gazebo（Ignition）和 jMAVSim。选择哪种取决于你要验证的模块类型：

仿真后端	启动命令	适用场景	资源占用
jMAVSim	`make px4_sitl jmavsim`	快速验证 uORB 消息流、简单控制逻辑	低
Gazebo Classic	`make px4_sitl gazebo-classic`	传感器模型、视觉、避障模块	中高
Gazebo (Ignition)	`make px4_sitl gz_x500`	新版本 PX4 推荐，复杂场景	高

硬件目标配置则通过 make 的板级目标实现。例如 Pixhawk 4 对应 px4_fmu-v5_default，Pixhawk 6C 对应 px4_fmu-v6c_default。编译硬件目标前，需确保已安装对应的 ARM 交叉编译器。

# 编译 Pixhawk 4 硬件目标
make px4_fmu-v5_default

# 编译后烧录（需连接飞控）
make px4_fmu-v5_default upload

提示：若只开发 uORB 消息与模块逻辑，优先使用 SITL 仿真目标，编译速度快、无需硬件。硬件目标仅在验证驱动、PWM 输出或真实传感器时使用。

四、误区与复盘：环境搭建中的高频问题

环境搭建阶段的问题往往具有“连锁性”，一个环节出错会导致后续全部失败。以下是三个高频误区及排查思路：

误区一：子模块未更新。表现为编译时提示 uORB/topics/xxx.h: No such file or directory。解决：执行 git submodule update --init --recursive，并检查 msg/ 目录是否存在。
误区二：Python 依赖版本冲突。表现为 empy 或 jinja2 报错。解决：使用 Tools/setup/ubuntu.sh 脚本统一安装，避免手动 pip 安装不同版本。
误区三：仿真启动后无响应。表现为 Gazebo 卡在加载界面。解决：检查显卡驱动与 OpenGL 支持，或改用 jMAVSim 验证基础功能。

复盘建议：每次切换 PX4 版本（如从 v1.13 到 v1.14）后，务必重新执行 make clean 并更新子模块。不同版本的 uORB 消息定义可能不兼容，残留的编译缓存会导致难以定位的错误。

五、环境验证：确认 uORB 与模块编译链路可用

环境搭建完成后，建议用一个最小化验证确认 uORB 消息生成与模块编译链路正常。可以在 src/modules/ 下创建一个临时模块目录，编写一个订阅 sensor_combined 的简单模块，然后编译 SITL 目标。若编译通过且能在 SITL 中通过 uorb top 看到消息频率，说明环境已具备自定义模块开发条件。

# 在 SITL 中查看 uORB 消息
pxh> uorb top
# 输出示例：
# TOPIC                          INSTANCE  RATE
# sensor_combined                0         250.0 Hz
# vehicle_attitude               0         250.0 Hz

至此，Ubuntu 系统、工具链、PX4 源码、编译、仿真环境与硬件目标配置已形成完整闭环。后续章节的自定义模块开发与 uORB 消息定义，都将基于这套环境展开。