【产出】 > 在 Ubuntu 上编译 PX4 软件在环仿真(SITL),用 Gazebo 的 x500 四旋翼模型完成起飞和降落,用 QGroundControl 连上仿真机,并在仿真里安全地演练失控保护。
【版本】 > 依据 PX4 官方文档 main 分支(Gazebo Simulation、Simulation、Ubuntu Development Environment、Building PX4 Software、Simulate Failsafes)和 QGroundControl 用户指南编写。适用 Ubuntu 22.04 / 24.04 与 Gazebo Harmonic 及以后版本,Ubuntu 20.04 不适用。
一、SITL 是什么,为什么先在仿真里飞
SITL(Software In The Loop,软件在环)是把 PX4 飞控程序编译成一个在电脑上运行的普通程序,传感器数据由仿真器提供,电机输出也送回仿真器。飞控代码和真机几乎一样,只是硬件换成了物理仿真。
PX4 官方把仿真定位为"快速、简单,并且最重要的是安全"的测试手段。下面几类事情都应当先在仿真里做一遍:
| 场景 | 在仿真里能验证什么 |
|---|---|
| 学习 QGC 操作 | 解锁、切模式、点地图飞行、上传任务,不用担心炸机 |
| 规划任务 | 航点顺序、高度、任务结束后的行为是否符合预期 |
| 改参数 | 速度、返航高度等参数改完后的实际效果 |
| 失控保护 | 数传断开、电量低、GPS 失效时飞机会怎么做 |
| 改代码 | 自己写的模块或修改过的控制器能不能正常运行 |
PX4 官方支持的仿真器主要有三个:
| 仿真器 | 特点 |
|---|---|
| Gazebo(原名 Gazebo Ignition) | 本文使用。渲染、物理和传感器模型更完整,是 Ubuntu 22.04 及以后唯一支持的 Gazebo 版本 |
| SIH | 物理计算直接跑在 PX4 内部,没有外部依赖,默认无界面,迭代最快 |
| Gazebo Classic | 旧版 Gazebo,已降为社区支持,不再推荐作为默认方案 |
【提示】 > 注意区分名字:现在说的"Gazebo"是新版(命令前缀
gz_),"Gazebo Classic"是旧版(命令前缀gazebo-classic_)。网上很多旧教程用的是 Classic,命令不能照抄。
二、准备开发环境
官方支持的系统是 Ubuntu 24.04(CI 和发布的目标版本)和 Ubuntu 22.04。安装脚本会一并装好 Gazebo Harmonic 和 Pixhawk 的交叉编译工具链。
步骤:
-
下载源码,必须带
--recursive,因为模型、世界文件和很多依赖都以子模块形式存在:git clone https://github.com/PX4/PX4-Autopilot.git --recursive -
运行官方安装脚本,过程中按提示确认:
bash ./PX4-Autopilot/Tools/setup/ubuntu.sh只需要仿真、不需要编译 Pixhawk 固件时,可以加
--no-nuttx;反过来加--no-sim-tools则不装仿真工具。 -
脚本完成后重启电脑。
【注意】 > 官方说明这个脚本是为"干净"的 Ubuntu LTS 安装准备的。在已经装了大量其他软件(尤其是另一套 ROS 或另一个版本的 Gazebo)的系统上运行可能失败。条件允许时,用一台新装的系统或单独的虚拟机来搭环境。
Ubuntu 20.04 无法安装 Gazebo Harmonic,官方建议升级到 22.04;确实要留在 20.04 的只能用 Gazebo Classic。
三、第一次编译并起飞
进入源码目录,用一条命令完成编译、启动 PX4 和启动 Gazebo:
cd PX4-Autopilot
make px4_sitl gz_x500
第一次编译时间较长。成功后会出现两样东西:
- 终端里出现
pxh>提示符,这是 PX4 的控制台(shell)。 - 弹出 Gazebo 窗口,地面上有一架 x500 四旋翼。
在控制台里起飞和降落:
pxh> commander takeoff
pxh> commander land
起飞后飞机升到默认起飞高度(参数 MIS_TAKEOFF_ALT,默认 2.5 m)悬停。降落完成后,按 Ctrl+C 或输入 shutdown 结束整个仿真。
【注意】 > 官方提醒:PX4 的默认配置要求有地面站连接才能起飞。如果
commander takeoff没有反应、控制台提示没有通过起飞前检查,先按下一节打开 QGC 再试。
四、连接 QGroundControl
1. 安装 QGC(Ubuntu)
按 QGC 官方安装说明,第一次安装前先做三件事:
# 把当前用户加入 dialout 组,以后接真实飞控的 USB 串口也需要(重新登录后生效)
sudo usermod -aG dialout "$(id -un)"
# 可选:屏蔽会抢占串口的 ModemManager
sudo systemctl mask --now ModemManager.service
# 安装运行 AppImage 需要的库
sudo apt install -y libfuse2 libxcb-xinerama0 libxkbcommon-x11-0 libxcb-cursor0
然后从 QGC 官网下载对应架构的 AppImage,加执行权限后运行:
chmod +x QGroundControl-x86_64.AppImage
./QGroundControl-x86_64.AppImage
【提示】 > QGC 官方说明当前提供的 AppImage 支持 Ubuntu 24.04 和 26.04。如果你的开发机是 22.04,可以把 QGC 装在另一台电脑上,通过网络连接仿真(见本节第 3 点),或者按官方开发者指南自行编译 QGC。
2. 同一台电脑:自动连接
make px4_sitl gz_x500 启动的仿真会自动配置好端口。先启动仿真、再打开 QGC(顺序反过来也可以),QGC 一般几秒内就会自动连上,左上角显示飞行模式和"Ready To Fly"之类的状态。
自动连接依赖的是 PX4 的默认 MAVLink UDP 端口:
| 端口 | 用途 |
|---|---|
| UDP 14550 | PX4 向地面站发送数据的远端端口,QGC 默认监听它 |
| UDP 14540 | 给 MAVSDK、MAVROS 等外部程序(Offboard API)用;多机仿真时从 14540 到 14549 依次分配 |
| TCP 4560 | 给通过 MAVLink 接仿真器的方案用(Gazebo 不走这个,Gazebo 通过 gz_bridge 通信) |
QGC 的 Application Settings → Comm Links 里默认勾选了 UDP 自动连接,不要把它关掉。
3. 两台电脑:手动建立 UDP 连接
仿真跑在一台电脑上、QGC 在另一台时,在 QGC 的 Comm Links → Add New Link 新建一个 UDP 连接,填写本地端口和仿真机的地址,然后点击连接。仿真机有多块网卡(例如同时有有线、无线和 Docker 网桥)时,可以用环境变量把 MAVLink 绑定到指定网卡:
PX4_NET_INTERFACE=eth0 make px4_sitl gz_x500
不设置时,MAVLink 绑定在所有网卡上。
【注意】 > 虚拟机里的 Ubuntu 默认使用 NAT 网络,宿主机上的 QGC 收不到 UDP 广播。把虚拟机网络改成桥接模式,或者 QGC 也装在虚拟机里。
4. 用 QGC 操作仿真机
连上之后,操作方式和真机一致:
- 在 Fly 视图点击 Takeoff,拖动滑块确认,飞机起飞。
- 飞行中在地图上点一个位置,选择移动到该处并拖动滑块确认,飞机就会飞过去。官方文档也推荐这种方式,因为"用地面站飞仿真更接近真实操作"。
- 点击 Land 或 Return 观察降落和返航过程。
【提示】 > QGC 的 Analyze → MAVLink Console 只能连接真实硬件,官方说明不支持 SITL。仿真时直接在运行
make的终端里的pxh>下输入命令即可。
五、常用启动选项
1. 换机型
所有 Gazebo 目标都以 gz_ 开头,常用的有:
| 机型 | 命令 |
|---|---|
| 四旋翼 x500 | make px4_sitl gz_x500 |
| x500 + 前视深度相机 | make px4_sitl gz_x500_depth |
| x500 + 云台 | make px4_sitl gz_x500_gimbal |
| 标准 VTOL | make px4_sitl gz_standard_vtol |
| 固定翼 | make px4_sitl gz_rc_cessna |
| 差速小车 | make px4_sitl gz_rover_differential |
2. 换世界
把世界名接在机型后面,或者用 PX4_GZ_WORLD 指定:
make px4_sitl gz_x500_windy # 有风的空世界
PX4_GZ_WORLD=baylands make px4_sitl gz_x500
官方支持的世界包括 default(灰色平面)、windy(有风)、baylands(水边场景)、walls(测试避障)、ridge(测试地形跟随)等。
【注意】 > 默认世界不要显式写
_default。make px4_sitl gz_x500_default会导致 PX4 无法启动,应写成make px4_sitl gz_x500。
3. 其他常用环境变量
| 变量 | 作用 | 示例 |
|---|---|---|
HEADLESS=1 | 不开 Gazebo 图形界面,省资源,没有合适显卡时也能跑 | HEADLESS=1 make px4_sitl gz_x500 |
PX4_SIM_SPEED_FACTOR | 仿真倍速,2 为两倍速,0.5 为半速 | PX4_SIM_SPEED_FACTOR=2 make px4_sitl gz_x500 |
PX4_HOME_LAT/LON/ALT | 起飞点经纬度和海拔 | 见下方代码 |
PX4_PARAM_<参数名> | 本次仿真覆盖任意 PX4 参数 | PX4_PARAM_MIS_TAKEOFF_ALT=10 |
PX4_GZ_SIM_RENDER_ENGINE=ogre | 改用 OGRE 1 渲染,虚拟机里画面异常时使用 | |
PX4_GZ_STANDALONE=1 | PX4 不自己启动 Gazebo,等待外部的 gz-server |
设置起飞点(在地图上规划任务时,让仿真机出现在你熟悉的场地附近):
export PX4_HOME_LAT=51.1788
export PX4_HOME_LON=-1.8263
export PX4_HOME_ALT=101
make px4_sitl gz_x500
倍速的上限受 CPU 和 IO 限制。官方给出的经验值是台式机大约 6–10 倍、笔记本大约 3–4 倍。Gazebo 与 PX4 以"锁步(lockstep)"方式同步运行,这是能变速和暂停仿真的前提,而且在 Gazebo 上锁步不能关闭。
六、在仿真里演练失控保护
为了方便使用,SITL 默认对一些失控保护做了处理。想测试真机上的安全行为,需要知道这些差异:
| 项目 | SITL 默认行为 | 怎么测试 |
|---|---|---|
| 数传(地面站)丢失 | 默认开启,所以仿真必须连着 QGC 或其他 MAVLink 程序 | 改 NAV_DLL_ACT 选择动作,设为 0 关闭 |
| 遥控丢失 | 默认开启,所以需要 MAVLink 或遥控连接 | 改 NAV_RCL_ACT |
| 电池 | 永远不会耗尽,默认只降到 50%,不会触发低电量动作 | 用 SIM_BAT_MIN_PCT 设最低电量百分比,SIM_BAT_DRAIN 设从 100% 放到 0% 的秒数(默认 60) |
| 传感器故障 | 需要先打开故障注入 | SYS_FAILURE_EN=1,然后用 failure 命令 |
演练低电量返航:起飞并飞远后,在控制台把最低电量调到低于严重阈值,观察飞机是否按 COM_LOW_BAT_ACT 的设置返航:
pxh> param set SIM_BAT_MIN_PCT 5
官方提示,飞行中修改 SIM_BAT_MIN_PCT 也可以把电量"调回去",用来模拟电量估算不准的情况。
演练 GPS 失效(先设置 SYS_FAILURE_EN 为 1,该参数需要重启生效):
pxh> param set SYS_FAILURE_EN 1
# 重启仿真后
pxh> failure gps off # GPS 完全失效
pxh> failure gps stuck # 位置卡在最后一个值
pxh> failure gps ok # 恢复正常
【注意】 > 官方说明:执行
make clean后,SITL 里的所有参数都会被重置,包括上面改过的失控保护参数。要长期保留的仿真配置,用PX4_PARAM_环境变量写进启动命令或脚本更稳妥。
【注意】 > 仿真里验证通过的行为,到真机上仍要重新验证。真机第一次测试失控保护时必须拆掉螺旋桨,在地面确认动作正确后,再在开阔场地、低高度、有人随时准备切手动的条件下试飞。
七、常见问题
| 现象 | 原因与处理 |
|---|---|
ninja: error: unknown target 'gz_x500' | 编译目录状态不一致。执行 make distclean 后重新 make px4_sitl gz_x500 |
| 各种莫名的编译错误 | 子模块版本不匹配。执行 git submodule update --recursive 和 make distclean |
控制台反复出现 Service call timed out as Gazebo has not been detected | 用了 standalone 模式但还没启动 gz-server;不用 standalone 时检查 Gazebo 是否正常启动 |
| Gazebo 窗口黑屏或闪退 | 显卡或虚拟机 OpenGL 支持不好。试 PX4_GZ_SIM_RENDER_ENGINE=ogre,或用 HEADLESS=1 只跑无界面仿真 |
| QGC 连不上 | 确认 QGC 的 UDP 自动连接没关;跨机器时检查防火墙和网段;虚拟机改桥接网络 |
commander takeoff 不起飞 | 默认需要地面站连接,先打开 QGC;看控制台和 QGC 的起飞前检查提示 |
打开 baylands 世界出现 geometry element of collision ... couldn't be created 警告 | 官方说明这是网格太多导致,可以忽略 |
参考资料
- PX4 Gazebo 仿真:https://docs.px4.io/main/en/sim_gazebo_gz/
- PX4 仿真总览(端口、环境变量):https://docs.px4.io/main/en/simulation/
- PX4 Ubuntu 开发环境:https://docs.px4.io/main/en/dev_setup/dev_env_linux_ubuntu.html
- PX4 编译说明(第一次编译、故障排除):https://docs.px4.io/main/en/dev_setup/building_px4.html
- PX4 仿真失控保护:https://docs.px4.io/main/en/simulation/failsafes.html
- QGC 下载与安装:https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html
- QGC 通信链接设置:https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/comm_links.html
- PX4 源码:https://github.com/PX4/PX4-Autopilot
评价 (0)