问题排查

本文件按现象组织排查步骤，覆盖 Ubuntu 20.04 + ROS 2 Foxy、Ubuntu 22.04 + ROS 2 Humble、Ubuntu 24.04 + ROS 2 Jazzy 三套常见环境。验证环境使用 Ubuntu 24.04.4 + ROS 2 Jazzy，项目包路径为 /home/robot-a/Desktop/drone_training_github_release。

01 Pegasus 插件在 Isaac Sim 里找不到

先检查 extension 路径是不是加错了。应该添加 Pegasus 的 extensions 目录，不是 pegasus.simulator 子目录。

常见路径：


/home/robot-a/Documents/PegasusSimulator/extensions

再检查 Pegasus 是否安装到 Isaac Sim 使用的 Python 环境：


xxxxxxxxxx
export ISAACSIM_PYTHON=/home/robot-a/miniconda3/envs/env_isaacsim/bin/python
$ISAACSIM_PYTHON -m pip show pegasus.simulator

如果没有输出，重新安装：


xxxxxxxxxx
cd /home/robot-a/Documents/PegasusSimulator
/home/robot-a/miniconda3/envs/env_isaacsim/bin/python -m pip install -e extensions/pegasus.simulator

安装 Pegasus 插件时应使用当前 Isaac Sim 环境里的 Python，不应使用系统 Python。

02 Pegasus UI 能打开，但启动 PX4 backend 失败

先看 Pegasus UI 里的 PX4 路径。路径要指向 PX4-Autopilot 根目录，例如：


xxxxxxxxxx
/home/robot-a/PX4-Autopilot

然后在终端检查 PX4 是否能单独编译：


xxxxxxxxxx
cd /home/robot-a/PX4-Autopilot
make px4_sitl_default

如果这里失败，应先处理 PX4 依赖或源码版本，再检查 Pegasus 配置。

03 QGroundControl 连不上 PX4

按这个顺序查：


xxxxxxxxxx
1. Isaac Sim timeline 是否正在播放
2. Pegasus 是否选择了 PX4 backend
3. PX4 SITL 进程是否启动
4. QGC 是否已经打开
5. MAVLink 端口是否被其他程序占用

可以用下面命令看 PX4 进程：


xxxxxxxxxx
ps aux | grep px4 | grep -v grep

如果 PX4 没启动，回到 Pegasus UI 检查 PX4 路径和 backend 配置。

04 QGroundControl 报 Not Ready 或不能 Arm

QGC 的提示通常比终端更直接。常见原因：

仿真 timeline 没播放。
PX4 没有有效位置估计。
机体还在地面穿模或碰撞异常。
电池、传感器或 preflight check 没通过。
当前模式不允许 arm。

不应跳过这些检查。应先确认官方 Iris 可以 arm，再替换为自定义无人机。

05 看不到 `/fmu/*` 话题

先 source ROS 2 和 px4_msgs 工作空间。按系统选择对应版本。

Ubuntu 20.04 + Foxy：


xxxxxxxxxx
source /opt/ros/foxy/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash

Ubuntu 22.04 + Humble：


xxxxxxxxxx
source /opt/ros/humble/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash

Ubuntu 24.04 + Jazzy：


xxxxxxxxxx
source /opt/ros/jazzy/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash

再查话题：


xxxxxxxxxx
ros2 topic list --no-daemon | grep /fmu

如果没有输出，检查 Micro XRCE-DDS Agent：


xxxxxxxxxx
source /home/robot-a/px4_agent_ws/install/setup.bash
MicroXRCEAgent udp4 -p 8888

如果 MicroXRCEAgent 仍不在 PATH，直接使用绝对路径：


xxxxxxxxxx
/home/robot-a/px4_agent_ws/install/microxrcedds_agent/bin/MicroXRCEAgent udp4 -p 8888

还要确认 PX4 侧 uXRCE-DDS Client 正在运行。没有 Agent，ROS 2 通常收不到 PX4 的 /fmu/out/* 数据，也发不进 /fmu/in/* 控制话题。

06 有 `/fmu/*`，但 `/fmu/out/vehicle_local_position` 没数据

不同 PX4 / px4_msgs 版本的话题名可能不同。先查：


xxxxxxxxxx
ros2 topic list --no-daemon | grep vehicle_local_position

可能出现：


xxxxxxxxxx
/fmu/out/vehicle_local_position
/fmu/out/vehicle_local_position_v1

分别试：


xxxxxxxxxx
ros2 topic echo /fmu/out/vehicle_local_position --once
ros2 topic echo /fmu/out/vehicle_local_position_v1 --once

如果两个都没有数据，通常是 PX4 没有有效 local position，或者 XRCE-DDS 链路还没通。

07 运行 `run_control_menu.sh` 报 Python 或 ROS 2 错误

先退出 conda：


xxxxxxxxxx
conda deactivate

再运行：


xxxxxxxxxx
cd /home/robot-a/Desktop/drone_training_github_release
./run_control_menu.sh

脚本默认使用 /usr/bin/python3。按系统选择对应 ROS 2 setup：


xxxxxxxxxx
/opt/ros/foxy/setup.bash
/opt/ros/humble/setup.bash
/opt/ros/jazzy/setup.bash
/home/robot-a/ros2_ws/install/setup.bash

Jazzy 对应系统 Python 3.12。应避免使用 conda Python 3.13 编译 Jazzy 的 px4_msgs。如果报 libpython3.13.so.1.0 或 UnsupportedTypeSupport，通常是 source 到了 Python 版本不匹配的工作空间。

如果 px4_msgs 不在 /home/robot-a/ros2_ws，可以手动指定：


xxxxxxxxxx
export PX4_ROS_WS=/path/to/ros2_ws
./run_control_menu.sh

08 Offboard 进不去

PX4 不是收到一次目标点就进入 Offboard。它要求外部控制器持续发布 setpoint。

检查三件事：


xxxxxxxxxx
ros2 topic hz /fmu/in/offboard_control_mode
ros2 topic hz /fmu/in/trajectory_setpoint
ros2 topic echo /fmu/out/vehicle_status --once

如果话题频率断断续续，或者先切模式再发 setpoint，PX4 可能拒绝 Offboard。正确顺序是：


xxxxxxxxxx
1. 等待 local position 有效
2. 先持续发布 OffboardControlMode 和 TrajectorySetpoint
3. 再发送切 Offboard 命令
4. 再发送 arm 命令

09 `move 1 0 0` 后无人机不动

move 不是起飞命令。它只是在当前目标点基础上修改目标位置。

先执行：


xxxxxxxxxx
status
takeoff 1.0
status
move 1 0 0

如果无人机已经通过 QGC 起飞，先用：


xxxxxxxxxx
offboard
move 1 0 0

还要确认 PX4 当前已经进入 OFFBOARD，并且 local position 有数据。

10 高度方向反了

move 命令使用世界坐标 / ENU 相对位移：


xxxxxxxxxx
move x = 世界坐标 x 正方向
move y = 世界坐标 y 正方向
move z = 向上

脚本内部会转换为 PX4 local / NED：


xxxxxxxxxx
px4_dx = world_dy
px4_dy = world_dx
px4_dz = -world_dz

所以在 move 命令里，上升是 z 增大。发送给 PX4 时会自动转成 NED 里的 z 减小。

例子：


xxxxxxxxxx
takeoff 1.0       # 目标 z = current_z - 1.0
move 0 0 0.2     # 上升约 0.2m
move 0 0 -0.2    # 下降约 0.2m

如果自定义代码直接发布 /fmu/in/trajectory_setpoint，仍然要使用 PX4 local / NED。把 ENU 的 z=+1 直接发给 PX4，飞机通常会往下走。

11 `px4_msgs` 版本不匹配

典型现象：

话题能看到，但 Python 消息字段报错。
/fmu/out/vehicle_status 变成 /fmu/out/vehicle_status_v3。
/fmu/out/vehicle_local_position 变成 /fmu/out/vehicle_local_position_v1。
控制代码 import 成功，但运行时字段不存在。

验证环境已有 px4_msgs：

Ubuntu 20.04 + Foxy：


xxxxxxxxxx
source /opt/ros/foxy/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash
ros2 interface show px4_msgs/msg/TrajectorySetpoint

Ubuntu 22.04 + Humble：


xxxxxxxxxx
source /opt/ros/humble/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash
ros2 interface show px4_msgs/msg/TrajectorySetpoint

Ubuntu 24.04 + Jazzy：


xxxxxxxxxx
source /opt/ros/jazzy/setup.bash
source /home/robot-a/ros2_ws/install/setup.bash
ros2 interface show px4_msgs/msg/TrajectorySetpoint

如需重新编译验证版：


x
mkdir -p /home/robot-a/px4_install_demo/ros2_ws/src
cd /home/robot-a/px4_install_demo/ros2_ws/src
git clone https://github.com/PX4/px4_msgs.git
cd /home/robot-a/px4_install_demo/ros2_ws
source /opt/ros/jazzy/setup.bash
/usr/bin/python3 -m colcon build --symlink-install --packages-select px4_msgs
source install/setup.bash

如果更换 PX4 版本，px4_msgs 也要一起换到匹配版本。Foxy/Humble/Jazzy 的重新编译流程相同，只需要把 source /opt/ros/jazzy/setup.bash 替换为对应版本的 setup。

12 QGroundControl AppImage 打不开

通用下载方式以 QGroundControl 官方下载页为准：


xxxxxxxxxx
https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html

Ubuntu 20.04 / Ubuntu 22.04 上 AppImage 可能需要 libfuse2：


xxxxxxxxxx
sudo apt update
sudo apt install -y libfuse2

Ubuntu 24.04 上优先安装兼容包：


xxxxxxxxxx
sudo apt update
sudo apt install -y libfuse2t64

然后重新授权并启动下载好的 AppImage：


xxxxxxxxxx
cd ~/Downloads
chmod +x QGroundControl*.AppImage
./QGroundControl*.AppImage

如果仍然打不开，再检查 AppImage 是否有执行权限。

13 Isaac Sim 路径不对

run_import_asset.sh 默认使用验证环境的 Isaac Sim 路径。如果需要手动指定：


xxxxxxxxxx
export ISAACSIM_BIN=/home/robot-a/miniconda3/envs/env_isaacsim/bin/isaacsim
export PEGASUS_EXTENSION=/home/robot-a/Documents/PegasusSimulator/extensions/pegasus.simulator
cd /home/robot-a/Desktop/drone_training_github_release
./run_import_asset.sh

ISAACSIM_BIN 应该指向 Isaac Sim 启动程序，不是 Python，也不是安装目录。

14 自定义无人机 USD 能显示，但不能飞

这通常不是 ROS 2 控制代码的问题。应先用官方 Iris 验证 Pegasus、PX4、QGC 链路。如果 Iris 能飞，但自定义无人机不能飞，重点检查 USD 和 Pegasus 绑定：

/World/quadrotor 是否存在。
/World/quadrotor/body 是否是刚体。
rotor prim 是否能被 Pegasus 找到。
质量和惯量是否合理。
旋翼方向、推力系数、力矩系数是否合理。
PX4 airframe 是否和机体结构匹配。
backend 是否真的绑定到这架无人机。

能显示只说明 USD 加载成功。能飞还需要 Pegasus 找到可控制的机体和旋翼结构。

15 最小排查顺序

出现问题时，不应直接修改代码。可按以下顺序排查：


xxxxxxxxxx
1. Isaac Sim 能否启动
2. Pegasus 插件是否启用
3. 官方 Iris 能否通过 QGC 起飞
4. 是否能看到 /fmu/out/* 话题
5. 是否能读取 local position
6. 控制菜单能否 status
7. takeoff 1.0 是否进入 Offboard 并起飞
8. move 是否改变目标点
9. 再换自定义无人机资产

前一步未通过时，不应跳到下一步。按顺序检查可以更快判断问题所在层级。