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

2. 开发环境搭建

PX4 Gazebo 仿真与传感器联调的第一步，不是写控制算法，而是把“地基”打牢。一个可复现的开发环境决定了后续仿真能否稳定运行、传感器数据能否被正确订阅、MAVLink 链路能否正常建立。本节围绕 Ubuntu 系统配置、ROS 与 Gazebo 安装、PX4 固件下载编译、QGroundControl 部署四条主线展开，并给出常见环境问题的排查路径。

本节目标：搭建一套可编译、可仿真、可地面站连接、可被 ROS 2 订阅的 PX4 开发环境，并能在出现依赖、版本、权限、网络问题时快速定位。

一、核心原理：工具链的层次与依赖关系

PX4 仿真环境并不是单一软件，而是一条从操作系统到应用层的依赖链。最底层是 Ubuntu 系统与基础编译工具；其上是 Gazebo 仿真引擎，负责物理世界与传感器模型；PX4 固件通过 px4_sitl 目标与 Gazebo 建立桥接；ROS 2 通过 px4_msgs 与 micro-ROS/uxrce-dds 或 px4_ros_com 订阅 uORB 消息；QGroundControl 则通过 UDP 与 PX4 的 MAVLink 端口通信，用于参数配置、任务规划和状态监控。

理解这条链的关键在于：版本匹配。Ubuntu 版本决定 ROS 2 发行版，ROS 2 发行版决定 Gazebo 版本，Gazebo 版本又影响 PX4 的 sitl_gazebo 编译结果。任意一环错位，都会表现为“编译通过但仿真启动失败”或“能起飞但 ROS 收不到话题”。

二、方法流程：四步搭建与验证

第一步：Ubuntu 系统配置。推荐 Ubuntu 22.04 LTS，安装后先更新源并安装基础工具。若使用国内网络，建议替换为清华或阿里镜像源，避免 apt update 长时间卡顿。

sudo apt update && sudo apt upgrade -y
sudo apt install -y git cmake build-essential python3-pip \
  ninja-build exiftool python3-jinja2 python3-pygments gcc \
  g++ clang-format cppcheck
sudo usermod -aG dialout $USER   # 串口权限，重新登录生效

第二步：安装 ROS 2 与 Gazebo。ROS 2 Humble 官方支持 Ubuntu 22.04，安装 ros-humble-desktop 会同时带入 rviz2、rqt 等工具。Gazebo Classic 11 可通过 gazebo11 包安装，也可由 PX4 的 sitl_gazebo 自动拉取。

sudo apt install -y ros-humble-desktop
sudo apt install -y gazebo11 libgazebo11-dev
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

第三步：下载并编译 PX4 固件。务必使用 --recursive 拉取子模块，否则 sitl_gazebo 会缺失。首次编译建议使用 make px4_sitl gazebo-classic，它会自动下载依赖并启动仿真。

git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot
make px4_sitl gazebo-classic
# 若只需编译不启动：
make px4_sitl_default

第四步：部署 QGroundControl。QGC 提供 AppImage 与 deb 两种形式。AppImage 无需安装，但需要赋予执行权限并安装 libfuse2；deb 包更适合长期使用。

chmod +x QGroundControl.AppImage
./QGroundControl.AppImage
# 或
sudo apt install -y ./QGroundControl.deb

三、案例场景：从零到仿真起飞

假设你在一台全新 Ubuntu 22.04 机器上工作。完成上述四步后，打开三个终端：终端 A 运行 make px4_sitl gazebo-classic，Gazebo 中会出现一架 Iris 无人机；终端 B 启动 QGC，自动通过 UDP 14550 连接，显示“Ready to Fly”；终端 C 启动 ROS 2 桥接：

MicroXRCEAgent udp4 -p 8888
ros2 topic list | grep fmu
ros2 topic echo /fmu/out/sensor_combined

若能看到 sensor_combined 数据持续输出，说明 PX4、Gazebo、ROS 2 三者已打通，可以进入传感器联调阶段。

四、常见环境问题排查清单

现象	可能原因	排查与解决
git clone 子模块为空	未加 --recursive 或网络中断	执行 `git submodule update --init --recursive`
Gazebo 启动黑屏/崩溃	显卡驱动或 OpenGL 问题	安装 mesa-utils，检查 `glxinfo`；虚拟机需开启 3D 加速
make 报 Python 依赖缺失	pip 包未安装或版本冲突	运行 `pip3 install --user -r Tools/setup/requirements.txt`
QGC 无法连接	UDP 端口被占用或防火墙	检查 14550 端口，关闭防火墙或改用 TCP
ROS 2 收不到 fmu 话题	MicroXRCEAgent 未启动或版本不匹配	确认 Agent 运行在 8888 端口，px4_msgs 与固件版本一致
串口权限不足	用户不在 dialout 组	`sudo usermod -aG dialout $USER` 后重新登录

常见误区：直接使用 git clone 而不加 --recursive，导致 Tools/sitl_gazebo 为空，编译时报“找不到 gazebo 模型”。另一个误区是混用 ROS 2 与 Gazebo 版本，例如在 Humble 上强行安装 Gazebo Garden，容易造成插件 ABI 不兼容。

建议在环境搭建完成后，用 make px4_sitl gazebo-classic 做一次“冒烟测试”，再启动 QGC 与 ROS 2 桥接，逐层验证。每通过一层，记录版本号与命令，形成自己的环境清单，后续排障可快速回溯。

环境搭建的本质是建立一条可验证的依赖链。只要 Ubuntu、ROS 2、Gazebo、PX4、QGC 五者版本对齐、路径正确、权限到位，后续的传感器联调就会顺畅很多。遇到问题时，优先检查“版本—路径—权限—网络”四个维度，通常能覆盖绝大多数环境故障。