PX4 V6X + ROS1/MAVROS + Gazebo 部署教学
面向空白 Ubuntu 20.04 / Jetson 环境的安装、启动、验证和排障说明
编写日期：2026-06-15
0. 教学目标
本教程的目标是把一台空白计算端配置成 PX4 仿真与 ROS1/MAVROS 控制环境。
完成后应具备以下能力：
- 能准备 PX4 SITL + Gazebo Classic 仿真环境。
- 能准备 ROS1 Noetic + MAVROS 控制环境。
- 能编译并运行 px4_control_ros1 控制包。
- 能通过 MAVROS 让 PX4 SITL 进入 OFFBOARD、解锁并起飞。
- 能判断系统是否真正跑通，而不是只看窗口是否打开。
- 能整理提交代码包和补充说明。
本教程不把计算端当作地面站使用。QGroundControl、LGC、Mission Planner 等地面站软件建议放在独立的 x86_64 Ubuntu 或 Windows 设备上运行。
1. 路径约定
为了避免暴露任何个人目录，全文使用变量表示路径。
建议在新机器上采用下面的通用路径变量：
export WORKSPACE="$HOME/v6x_px4_ws"
export RUN_DIR="$WORKSPACE/PX4_Gazebo_ROS1_V6X"
export ROS1_WS="$WORKSPACE/ros1_ws"
export PX4_DIR="$HOME/PX4-Autopilot"
export DELIVERY_DIR="$WORKSPACE/delivery"
export SMOKE_LOG_DIR="/tmp/px4_ros1_smoke_test"
含义如下：
WORKSPACE：项目总工作目录。
RUN_DIR：一键启动脚本、说明文档和 ROS1 控制包所在目录。
ROS1_WS：ROS1 catkin 工作区。
PX4_DIR：PX4-Autopilot 源码目录。
DELIVERY_DIR：最终交付包目录。
SMOKE_LOG_DIR：自动联调日志目录。
后续命令默认已经设置这些变量。若新开终端，需要重新执行上面的 export 命令。
2. 系统组成
整套系统分成五部分：
PX4
飞控固件和飞控软件栈。真机中运行在 V6X-V2 飞控上；仿真中运行为 PX4 SITL 进程。
Gazebo Classic
仿真器，负责无人机模型、地面、物理和传感器仿真。
MAVROS
ROS1 与 PX4 之间的 MAVLink 桥接层。
ROS1 Noetic
控制节点运行环境。
px4_control_ros1
ROS1 + MAVROS 控制包，用于发送 setpoint、切 OFFBOARD、解锁和起飞。
仿真链路如下：
px4_control_ros1
↓ ROS topic / service
MAVROS
↓ MAVLink UDP
PX4 SITL
↓ Gazebo Classic 插件
Gazebo Classic iris 模型
真实飞控链路如下：
ROS1 / MAVROS 计算端
↓ USB 或串口
V6X-V2 PX4 飞控
SITL 仿真不需要连接真实飞控。只有真机飞行、HITL 或真实 V6X-V2 链路检查时，才需要接入飞控硬件。
3. 为什么计算端不安装地面站
计算端的主要任务是运行 ROS、MAVROS、Gazebo、PX4 SITL 和控制算法。
QGroundControl、LGC、Mission Planner 等地面站更适合放在独立 x86_64 Ubuntu 或 Windows 设备上，用来完成：
刷 PX4 固件
飞控校准
参数配置
地面站监控
日志查看
安全检查
如果计算端是 Jetson/aarch64，不建议为了运行 QGC 强行升级 glibc。glibc 是系统 ABI 的底层依赖，改动后可能影响 ROS、Gazebo、驱动和桌面环境。
推荐分工：
Jetson / 计算端：
ROS、MAVROS、PX4 SITL、Gazebo、控制算法。
独立地面站设备：
QGC / LGC / MP、刷固件、校准、参数、监控。
4. 空白系统准备
4.1 系统版本
推荐环境：
Ubuntu 20.04
ROS Noetic
Gazebo Classic 11
MAVROS
PX4-Autopilot v1.14.x 或与课程要求一致的版本
Jetson/aarch64 和 x86_64 Ubuntu 都可以作为计算端，但依赖安装方式可能略有差异。
4.2 基础工具
先更新软件源并安装基础工具：
sudo apt update
sudo apt install -y \\
git \\
wget \\
curl \\
unzip \\
build-essential \\
cmake \\
python3-pip \\
python3-rosdep \\
python3-catkin-tools \\
python3-vcstool \\
gnome-terminal
初始化 rosdep：
sudo rosdep init 2>/dev/null || true
rosdep update
如果 rosdep update 网络较慢，需要根据所在网络环境处理代理或镜像源。
5. 安装 ROS Noetic
如果系统已经安装 ROS Noetic，可以跳过本章，直接检查：
source /opt/ros/noetic/setup.bash
echo "$ROS_DISTRO"
期望输出：
noetic
如果没有安装 ROS Noetic，按 Ubuntu 20.04 的 ROS Noetic 安装流程安装。安装完成后执行：
source /opt/ros/noetic/setup.bash
建议把 ROS 环境加入 shell 配置：
echo 'source /opt/ros/noetic/setup.bash' >> "$HOME/.bashrc"
6. 安装 MAVROS
安装 MAVROS 和常用扩展：
sudo apt update
sudo apt install -y \\
ros-noetic-mavros \\
ros-noetic-mavros-extras \\
geographiclib-tools
安装 MAVROS 地理数据：
if command -v geographiclib-get-geoids >/dev/null 2>&1; then
sudo geographiclib-get-geoids egm96-5
else
sudo /opt/ros/noetic/lib/mavros/install_geographiclib_datasets.sh
fi
检查 MAVROS：
source /opt/ros/noetic/setup.bash
rospack find mavros
rospack find mavros_msgs
能输出包路径即表示 ROS 能找到 MAVROS。
7. 准备 PX4 源码
创建工作目录：
mkdir -p "$WORKSPACE"
获取 PX4 源码：
cd "$HOME"
git clone https://github.com/PX4/PX4-Autopilot.git –recursive
cd "$PX4_DIR"
如果课程或项目要求指定 PX4 版本，需要切换到对应版本，例如：
git checkout v1.14.3
git submodule update –init –recursive
安装 PX4 依赖：
cd "$PX4_DIR"
bash ./Tools/setup/ubuntu.sh
脚本执行后通常需要重启或重新登录终端。
8. 构建 PX4 SITL + Gazebo Classic
进入 PX4 源码目录：
cd "$PX4_DIR"
构建 SITL 和 Gazebo Classic：
GIT_SUBMODULES_ARE_EVIL=1 make px4_sitl_default sitl_gazebo-classic
成功后应存在：
$PX4_DIR/build/px4_sitl_default/bin/px4
$PX4_DIR/build/px4_sitl_default/build_gazebo-classic/libgazebo_mavlink_interface.so
检查命令：
ls -l "$PX4_DIR/build/px4_sitl_default/bin/px4"
ls -l "$PX4_DIR/build/px4_sitl_default/build_gazebo-classic/libgazebo_mavlink_interface.so"
如果普通 iris 模型可以使用，gazebo_aruco_plugin 相关缺失通常不影响基础 SITL 起飞验证。
9. 准备项目文件
在空白机器上，需要先准备项目文件。项目目录建议如下：
$WORKSPACE/
└── PX4_Gazebo_ROS1_V6X/
├── check_env.sh
├── setup_env.sh
├── build_px4_sitl_gazebo_classic.sh
├── smoke_test_all.sh
├── run_all.sh
├── stop_all.sh
├── monitor_topics.sh
├── check_real_v6x_v2_mavros.sh
├── px4_control_ros1/
├── px4_control_ros1.zip
└── docs/
如果已有项目压缩包，解压到 $WORKSPACE：
mkdir -p "$WORKSPACE"
unzip 项目包.zip -d "$WORKSPACE"
如果没有项目包，需要至少准备 px4_control_ros1 控制包和启动脚本。
进入运行目录：
cd "$RUN_DIR"
给脚本执行权限：
chmod +x *.sh
10. 准备 ROS1 工作区
创建 catkin 工作区：
mkdir -p "$ROS1_WS/src"
复制控制包：
rm -rf "$ROS1_WS/src/px4_control_ros1"
cp -a "$RUN_DIR/px4_control_ros1" "$ROS1_WS/src/"
编译：
cd "$ROS1_WS"
source /opt/ros/noetic/setup.bash
catkin_make
加载工作区：
source "$ROS1_WS/devel/setup.bash"
检查包是否可见：
rospack find px4_control_ros1
能输出包路径即表示控制包已经进入 ROS 环境。
11. 环境检查
进入运行目录：
cd "$RUN_DIR"
执行：
bash ./check_env.sh
期望结果包括：
ROS_DISTRO=noetic
mavros: OK
mavros_msgs: OK
PX4 dir: OK
px4_control_ros1: OK
如果 mavros 或 mavros_msgs 缺失，回到 MAVROS 安装步骤。
如果 px4_control_ros1 缺失，回到 ROS1 工作区编译步骤。
如果 PX4 目录缺失，回到 PX4 源码准备步骤。
12. 一键安装脚本的用途
如果项目里提供 setup_env.sh，可以用它自动安装 MAVROS 并编译 ROS1 工作区：
cd "$RUN_DIR"
bash ./setup_env.sh
脚本一般会执行：
安装 MAVROS
安装 MAVROS extras
安装 GeographicLib 数据
创建 ROS1 catkin 工作区
复制 px4_control_ros1
执行 catkin_make
检查 PX4 源码目录
脚本不能替代所有 PX4 官方依赖安装。PX4 源码和系统依赖仍需按 PX4 安装步骤准备。
13. 自动联调
在打开 Gazebo GUI 之前，先跑自动联调。
命令：
cd "$RUN_DIR"
bash ./smoke_test_all.sh
自动联调应完成：
停止旧进程
启动 PX4 SITL + Gazebo Classic headless
启动 MAVROS
启动 px4_control_ros1/offboard_takeoff
等待 MAVROS connected=True
等待 PX4 armed=True
等待 mode=OFFBOARD
读取 /mavros/local_position/pose
确认高度 z > 0.5 m
清理测试进程
成功标志：
[OK] smoke test passed
日志目录：
$SMOKE_LOG_DIR
如果自动联调失败，先看：
$SMOKE_LOG_DIR/px4_gazebo_classic.log
$SMOKE_LOG_DIR/mavros.log
$SMOKE_LOG_DIR/offboard_takeoff.log
$SMOKE_LOG_DIR/final_state.txt
$SMOKE_LOG_DIR/final_pose.txt
14. 多终端启动
需要展示 GUI 或观察 Gazebo 时，执行：
cd "$RUN_DIR"
GAZEBO_GUI=1 bash ./run_all.sh
不需要 GUI 时，执行：
cd "$RUN_DIR"
bash ./run_all.sh
脚本通常会启动：
PX4_SITL_GAZEBO
MAVROS_PX4
PX4_ROS1_CTRL
PX4_TOPIC_MONITOR
各终端作用：
PX4_SITL_GAZEBO：启动 PX4 SITL 和 Gazebo Classic。
MAVROS_PX4：启动 MAVROS 并连接 PX4。
PX4_ROS1_CTRL：启动 Offboard 控制节点。
PX4_TOPIC_MONITOR：显示 /mavros/state 和 /mavros/local_position/pose。
常用参数：
TAKEOFF_HEIGHT=3.0 GAZEBO_GUI=1 bash ./run_all.sh
SETPOINT_RATE=20.0 GAZEBO_GUI=1 bash ./run_all.sh
START_MONITOR=0 GAZEBO_GUI=1 bash ./run_all.sh
停止：
cd "$RUN_DIR"
bash ./stop_all.sh
15. 手动分终端启动
一键脚本失败时，可以手动分终端启动，便于定位问题。
15.1 终端 1：PX4 SITL + Gazebo
export ROS_MASTER_URI=http://127.0.0.1:11311
export ROS_IP=127.0.0.1
unset ROS_HOSTNAME
cd "$PX4_DIR"
PX4_NO_FOLLOW_MODE=1 NO_PXH=1 GIT_SUBMODULES_ARE_EVIL=1 make px4_sitl gazebo-classic
headless 模式：
HEADLESS=1 PX4_NO_FOLLOW_MODE=1 NO_PXH=1 GIT_SUBMODULES_ARE_EVIL=1 make px4_sitl gazebo-classic
期望看到：
Simulator connected on TCP port 4560
udp port 14580 remote port 14540
15.2 终端 2：MAVROS
export ROS_MASTER_URI=http://127.0.0.1:11311
export ROS_IP=127.0.0.1
unset ROS_HOSTNAME
source /opt/ros/noetic/setup.bash
source "$ROS1_WS/devel/setup.bash"
roslaunch mavros px4.launch fcu_url:=udp://:14540@127.0.0.1:14557
期望看到：
CON: Got HEARTBEAT, connected. FCU: PX4 Autopilot
15.3 终端 3：控制节点
export ROS_MASTER_URI=http://127.0.0.1:11311
export ROS_IP=127.0.0.1
unset ROS_HOSTNAME
source /opt/ros/noetic/setup.bash
source "$ROS1_WS/devel/setup.bash"
roslaunch px4_control_ros1 offboard_takeoff.launch takeoff_height:=3.0 setpoint_rate:=20.0
15.4 终端 4：状态监视
export ROS_MASTER_URI=http://127.0.0.1:11311
export ROS_IP=127.0.0.1
unset ROS_HOSTNAME
source /opt/ros/noetic/setup.bash
source "$ROS1_WS/devel/setup.bash"
rostopic echo /mavros/state
查看位置：
rostopic echo /mavros/local_position/pose
16. 跑通判据
不能只用“Gazebo 窗口打开了”判断跑通。
需要检查：
/mavros/state connected=True
/mavros/state armed=True
/mavros/state mode=OFFBOARD
/mavros/local_position/pose 中 z > 0.5 m
检查 MAVROS 状态：
source /opt/ros/noetic/setup.bash
source "$ROS1_WS/devel/setup.bash"
rostopic echo -n 1 /mavros/state
检查高度：
rostopic echo -n 1 /mavros/local_position/pose
如果 z 大于 0.5 m，说明无人机已经起飞。
17. 控制包逻辑
核心文件：
px4_control_ros1/src/offboard_takeoff.cpp
订阅：
/mavros/state
/mavros/local_position/pose
发布：
/mavros/setpoint_position/local
服务：
/mavros/set_mode
/mavros/cmd/arming
程序流程：
1. 等待 MAVROS 连接 PX4。
2. 先发布 100 个位置 setpoint。
3. 调用 /mavros/set_mode 切 OFFBOARD。
4. 调用 /mavros/cmd/arming 解锁。
5. 发布目标位置 (0, 0, takeoff_height)。
6. 到达起飞高度后执行航点任务。
默认起飞高度通常由启动脚本传入，例如：
TAKEOFF_HEIGHT=3.0
默认航点可设置为方形轨迹：
( 5, 5, takeoff_height)
( 5, -5, takeoff_height)
(-5, -5, takeoff_height)
(-5, 5, takeoff_height)
该控制包用于证明 ROS1 + MAVROS 能控制 PX4 SITL 进入 OFFBOARD、解锁、起飞和飞航点。它不是完整自主避障算法。
18. 真实 V6X-V2 链路检查
真实飞控链路检查只验证 MAVROS 能否连接 V6X-V2 PX4 飞控。
该步骤不应解锁、不应切 OFFBOARD、不应发布飞行 setpoint。
先列串口：
ls -l /dev/serial/by-id/* 2>/dev/null
ls -l /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
示例检查命令：
cd "$RUN_DIR"
FCU_URL=/dev/ttyACM0:921600 bash ./check_real_v6x_v2_mavros.sh
/dev/ttyACM0:921600 只是示例。实际串口和波特率必须以飞控枚举设备和 PX4 MAVLink 参数为准。
可能的串口形式：
/dev/ttyACM0:921600
/dev/ttyUSB0:57600
/dev/ttyUSB0:921600
成功标志：
[OK] MAVROS connected to V6X-V2 PX4 flight controller
真机飞行前还需要单独确认：
桨叶安全
电池状态
遥控器或急停功能
PX4 参数
传感器校准
飞行模式
failsafe
场地安全
19. 常见问题排查
19.1 环境检查失败
执行：
cd "$RUN_DIR"
bash ./check_env.sh
如果 MAVROS 缺失，重新安装 MAVROS。
如果 px4_control_ros1 缺失，重新编译 ROS1 工作区。
如果 PX4 缺失，重新准备 PX4 源码。
19.2 Gazebo 没有窗口
默认可能是 headless 模式。
需要 GUI 时执行：
GAZEBO_GUI=1 bash ./run_all.sh
如果 headless 模式下自动联调能通过，说明核心控制链路正常。
19.3 MAVROS 没连接
检查 PX4 是否已经启动并输出 UDP 信息。
SITL 默认 FCU_URL：
udp://:14540@127.0.0.1:14557
检查状态：
rostopic echo -n 1 /mavros/state
成功时应有：
connected: True
19.4 不能进入 OFFBOARD
PX4 要求进入 OFFBOARD 前持续收到 setpoint。
检查 setpoint 频率：
rostopic hz /mavros/setpoint_position/local
应接近：
20 Hz
19.5 能 OFFBOARD 但不能解锁
先看：
rostopic echo -n 1 /mavros/state
再检查控制节点日志。
如果是真飞控，不能解锁还可能与安全开关、传感器校准、EKF、遥控器 failsafe、电池状态等有关。
19.6 残留进程冲突
执行：
cd "$RUN_DIR"
bash ./stop_all.sh
检查残留：
pgrep -af '[r]oscore|[r]osmaster|[r]oslaunch|[r]osout|[m]avros|[g]zserver|[g]zclient|[g]azebo|/PX4-Autopilot/build/px4_sitl_default/bin/[p]x4' || true
没有输出表示相关进程已清理。
19.7 ROS 日志过大
清理：
rosclean purge
如需保留历史日志，先备份再清理。
20. 交付包整理
建议交付包结构：
V6X_PX4_作业交付包/
├── README_提交说明.md
├── 代码/
│ ├── 01_px4_msgs.zip
│ └── 02_px4_control_ROS2原始包.zip
└── 补充_ROS1_MAVROS版本/
└── px4_control_ros1_MAVROS.zip
说明：
01_px4_msgs.zip
PX4 ROS2 消息包。
02_px4_control_ROS2原始包.zip
原始 ROS2 控制包。
px4_control_ros1_MAVROS.zip
Ubuntu 20.04 + ROS Noetic 环境下的 ROS1 + MAVROS 补充控制包。
校验压缩包：
cd "$WORKSPACE"
unzip -t "$DELIVERY_ZIP"
成功标志：
No errors detected in compressed data
21. 从空白环境到跑通的最短流程
export WORKSPACE="$HOME/v6x_px4_ws"
export RUN_DIR="$WORKSPACE/PX4_Gazebo_ROS1_V6X"
export ROS1_WS="$WORKSPACE/ros1_ws"
export PX4_DIR="$HOME/PX4-Autopilot"
export DELIVERY_DIR="$WORKSPACE/delivery"
export SMOKE_LOG_DIR="/tmp/px4_ros1_smoke_test"
准备系统依赖：
sudo apt update
sudo apt install -y git wget curl unzip build-essential cmake python3-pip python3-rosdep python3-catkin-tools python3-vcstool gnome-terminal
sudo rosdep init 2>/dev/null || true
rosdep update
准备 ROS 和 MAVROS：
source /opt/ros/noetic/setup.bash
sudo apt install -y ros-noetic-mavros ros-noetic-mavros-extras geographiclib-tools
准备 PX4：
cd "$HOME"
git clone https://github.com/PX4/PX4-Autopilot.git –recursive
cd "$PX4_DIR"
git checkout v1.14.3
git submodule update –init –recursive
bash ./Tools/setup/ubuntu.sh
构建 PX4：
cd "$PX4_DIR"
GIT_SUBMODULES_ARE_EVIL=1 make px4_sitl_default sitl_gazebo-classic
准备项目包：
mkdir -p "$WORKSPACE"
unzip 项目包.zip -d "$WORKSPACE"
cd "$RUN_DIR"
chmod +x *.sh
编译 ROS1 控制包：
mkdir -p "$ROS1_WS/src"
cp -a "$RUN_DIR/px4_control_ros1" "$ROS1_WS/src/"
cd "$ROS1_WS"
source /opt/ros/noetic/setup.bash
catkin_make
source "$ROS1_WS/devel/setup.bash"
检查：
cd "$RUN_DIR"
bash ./check_env.sh
自动联调：
bash ./smoke_test_all.sh
带 GUI 启动：
GAZEBO_GUI=1 bash ./run_all.sh
停止：
bash ./stop_all.sh
22. 命令速查
检查环境：
cd "$RUN_DIR"
bash ./check_env.sh
自动联调：
cd "$RUN_DIR"
bash ./smoke_test_all.sh
启动 GUI：
cd "$RUN_DIR"
GAZEBO_GUI=1 bash ./run_all.sh
停止：
cd "$RUN_DIR"
bash ./stop_all.sh
查看 MAVROS 状态：
source /opt/ros/noetic/setup.bash
source "$ROS1_WS/devel/setup.bash"
rostopic echo -n 1 /mavros/state
查看位置：
rostopic echo -n 1 /mavros/local_position/pose
查看 setpoint 频率：
rostopic hz /mavros/setpoint_position/local
真实飞控链路检查：
cd "$RUN_DIR"
FCU_URL=/dev/ttyACM0:921600 bash ./check_real_v6x_v2_mavros.sh
交付包校验：
cd "$WORKSPACE"
unzip -t "$DELIVERY_ZIP"
23. 结论
这套教学流程分成两条路线：
提交路线：
保留原始 ROS2 代码包，例如 px4_msgs 和 px4_control。
仿真验证路线：
使用 Ubuntu 20.04 + ROS Noetic + MAVROS + PX4 SITL + Gazebo Classic + px4_control_ros1。
关键边界：
SITL 不需要真实飞控。
真实 V6X-V2 只在链路检查或真飞时接入。
计算端不做地面站。
地面站放到独立 x86_64 Ubuntu 或 Windows 设备。
ROS1 + MAVROS 包用于验证控制链路。
原始 ROS2 包用于保留任务代码材料。
部署完成后，优先用下面两步确认基础链路：
cd "$RUN_DIR"
bash ./check_env.sh
bash ./smoke_test_all.sh
