PX4上手记录-VSCode-QGC-PlotJuggler

PX4 开发环境上手记录：VSCode + QGC + PlotJuggler

日期：2026-09-15
环境：Ubuntu 20.04 双系统 · ROS Noetic · PX4 v1.14.3 · Gazebo Classic 11 · QGC v4.2.9
机器：Lenovo V15 G2 ITL（8G 内存）

📋 今日完成概览

项目	状态	备注
VSCode 配置 PX4 开发环境	✅ 部分完成	代码编辑/跳转可用，但不能用它启动仿真
PlotJuggler 安装	✅	用于分析 .ulg 日志
QGC 地面站熟悉	✅	虚拟遥控、航点任务、PID 参数、链路连接
PX4 shell 基本命令	✅	arm / takeoff / land 等
Gazebo 图形界面	❌ 未解决	窗口不显示，改用 headless + QGC 方案

一、VSCode 配置 PX4（含踩坑）

1.1 已完成的配置

# 打开 PX4 项目
code ~/PX4-Autopilot

# 安装必需扩展
code --install-extension ms-vscode.cpptools      # C/C++ 智能提示
code --install-extension ms-vscode.cmake-tools   # CMake 目标选择

PX4 自带 VSCode 配置（PX4-Autopilot/.vscode/），打开项目 + 装扩展即可。

1.2 VSCode 里的"编译目标"（CMake variant）

状态栏会出现 CMake 按钮，可以选：

Variant	对应	说明
SITL	Gazebo Classic	✅ 用这个（已装）
SITL (gz)	新 Gazebo（需 gz-garden）	❌ 会报错，别选

选错的表现：

ERROR [init] Gazebo gz please install gz-garden
ERROR [param] Parameter SIM_GZ_EN not found.

切换方法：Ctrl+Shift+P → CMake: Select Variant → 选不带 gz 的 SITL

1.3 ⚠️ 踩坑记录：无法完全靠 VSCode 启动仿真

问题现象：

1. 点 VSCode 的调试按钮（F5 / SITL 配置）启动
   → 会杀掉之前手动启动的 Gazebo 进程
2. 直接在 VSCode 终端启动 gazebo
   → 卡在 "Waiting for simulator to accept connection on TCP port 4560"

原因分析：

现象	原因
调试启动会杀 Gazebo	VSCode 的调试配置每次都重启整个仿真环境（设计如此）
单独跑 px4 二进制卡住	PX4 SITL 需要 Gazebo 先跑起来（通过 TCP 4560 连接）
直接敲 `gazebo` 也不行	PX4 需要专用的 world + 插件 + 环境变量，空 Gazebo 不认
variant 是 gz 时失败	新 Gazebo（gz-garden）没装（Ubuntu 20.04 装不了）

✅ 结论与正确工作流：

VSCode  → 只用来【看代码 / 改代码】（代码跳转、搜索、编辑）
终端    → 用来【编译 + 跑仿真】：make px4_sitl gazebo

标准循环：

# ① VSCode 里改代码，Ctrl+S 保存
# ② 终端里（先确保上次的仿真已 Ctrl+C 停止）
cd ~/PX4-Autopilot
make px4_sitl gazebo -j$(nproc)    # 自动增量编译 + 启动
# ③ 看效果 → Ctrl+C 停止 → 回到 ①

make 会自动增量编译（只编译改动的文件，几十秒），不用手动先编译。

什么情况需要重新配置：

改动类型	处理
`.cpp` / `.h` 代码	直接 `make` ✅
参数默认值（`*.params`）	直接 `make` ✅
增删源文件（改 CMakeLists.txt）	可能需要重新 cmake

二、PlotJuggler 安装与使用

2.1 安装

# 方式 1：snap（最简单）
sudo snap install plotjuggler

# 方式 2：AppImage（snap 慢时用）
cd ~/下载
wget -O PlotJuggler.AppImage "https://ghfast.top/https://github.com/facontidavide/PlotJuggler/releases/download/3.9.2/PlotJuggler-3.9.2-x86_64.AppImage"
chmod +x PlotJuggler.AppImage
./PlotJuggler.AppImage

2.2 用法（分析离线日志）

PlotJuggler → File → Load data → 选 .ulg 文件
→ 左侧列出所有信号，拖到图上
→ 可缩放、对比、算差值

日志文件位置（PX4 SITL）：

ls -lh ~/PX4-Autopilot/build/px4_sitl_default/rootfs/log/*/*.ulg
# 例：./log/2026-09-15/05_31_41.ulg

2.3 补充：三种日志/数据工具对比

工具	安装	用途	推荐
rqt_plot	ROS 自带	实时看 ROS/Mavros 话题曲线	⭐ 实时首选
rqt_multiplot	`sudo apt install ros-noetic-rqt-multiplot`	实时，多图、可配置	⭐⭐
PlotJuggler	snap / AppImage	离线分析 .ulg 日志	⭐⭐
Flight Review	网页 `review.px4.io`	上传 .ulg 自动分析	省事
~~FlightPlot~~	需源码构建	老工具，2021 停更	❌ 不推荐

实时看数据（用 rqt_plot）：

# 确保 MAVROS 在跑后
rqt_plot /mavros/local_position/pose/pose/position/z

常用 mavros 话题：

话题	内容
`/mavros/local_position/pose/pose/position/z`	高度
`/mavros/attitude/roll` `/pitch` `/yaw`	姿态角
`/mavros/battery/voltage`	电池电压
`/mavros/state`	模式 / armed
`/mavros/setpoint_position/local/pose/position/z`	目标位置

三、QGC 地面站（QGroundControl v4.2.9）

3.1 连接 PX4

# 启动 QGC
cd ~/下载 && ./QGroundControl.AppImage

通常自动连接（PX4 SITL 默认往 UDP 14550 发 MAVLink）。连上后顶栏显示 Connected。

手动添加连接：

QGC → Application Settings（齿轮）→ Comm Links → Add
   Name: PX4 SITL
   Type: UDP
   Port: 14550
→ OK → Connect

3.2 虚拟遥控（Virtual Joystick）

不需要真遥控器就能控制仿真飞机：

QGC → Application Settings → General → 勾选 "Virtual Joystick"
→ 回到 Fly 视图 → 屏幕上出现虚拟摇杆
→ 可以推杆控制飞机（同时看到姿态/位置实时变化）

注意：用虚拟摇杆控制前，飞机要已解锁。

3.3 飞固定路径（航点任务）

QGC → Plan 视图（左侧第二个图标）
  → 点地图 + 号添加航点（Waypoint）
  → 可设置每个航点的：高度、悬停时间、速度、航点类型
  → 右上角 "Upload"（上传任务到飞控）
  → 切到 Fly 视图 → 点 "Start Mission"（开始任务）

支持的航点类型：

Waypoint（普通航点）
Takeoff（起飞）
Land（降落）
RTL（返航）
Loiter（盘旋）

3.4 调 PID 参数

QGC → Vehicle Setup（车辆设置）→ Parameters（参数）
  → 搜索框输入参数名，例如：
     MC_ROLL_P     (横滚角速度环 P)
     MC_PITCH_P    (俯仰角速度环 P)
     MC_YAW_P      (偏航角速度环 P)
     MC_ROLLRATE_P (横滚角速率内环 P)
     MC_ROLLRATE_I (积分)
     MC_ROLLRATE_D (微分)
  → 改值 → 点右侧 "Save"（或回车）
  → 参数立即生效，可以再飞一次看效果

💡 调参思路：先调速率环（内环，P→D→I），再调姿态环（外环）。

3.5 机载电脑与飞控的链路连接方式

MAVLink 支持多种物理/网络承载方式：

方式	典型用途	示例 URL
UDP	SITL 仿真、局域网设备间	`udp://:14540@127.0.0.1:14557`
TCP	可靠传输、跨网络	`tcp://192.168.1.10:5760`
串口（UART）	真机飞控 ↔ 机载电脑（最常用）	`/dev/ttyS0`, `/dev/ttyUSB0`, 波特率 921600
串口转 USB	调试用	`/dev/ttyACM0`

典型真机架构：

飞控（Pixhawk）── 串口（UART，MAVLink）──→ 机载电脑（树莓派/Jetson）
     │                                            │
     └── 遥控接收机                          跑 ROS + MAVROS
                                            处理视觉/规划，发控制指令

PX4 默认的 MAVLink 端口（SITL）：

端口	用途
UDP 14550	地面站（QGC）
UDP 14580	Onboard（MAVROS / 机载电脑）
TCP 4560	仿真器（Gazebo）连接

MAVROS 连接（SITL）：

roslaunch mavros px4.launch fcu_url:="udp://:14540@127.0.0.1:14557"

真机连接示例：

# 串口连接（真机，波特率要和飞控配置一致）
roslaunch mavros px4.launch fcu_url:=/dev/ttyUSB0:921600

四、PX4 Shell 基本命令（pxh> 提示符）

在 make px4_sitl gazebo 启动后的终端里，出现 pxh> 提示符，可直接输入命令。

4.1 解锁 / 起飞 / 降落

命令	作用
`commander arm`	解锁（电机可转）
`commander disarm`	上锁（电机停转）
`commander takeoff`	自动起飞（默认到 2.5m）
`commander land`	降落
`commander status`	查看状态（Arm state / 模式 / failsafe）
`commander check`	检查解锁条件

典型流程：

pxh> commander arm            # 解锁
pxh> commander status         # 确认 Arm state: Armed
pxh> commander takeoff        # 起飞到 2.5m
pxh> commander land           # 降落
pxh> commander disarm         # 上锁

状态解读（commander status）：

Arm state: Standby / Armed / Disarmed
  Standby  = 待命（未解锁，等待自动解锁条件）
  Armed    = 已解锁
  Disarmed = 未解锁
navigation mode: AUTO_TAKEOFF / POSCTL / AUTO_LOITER ...
in failsafe: no

4.2 其他常用命令

命令	作用
`param show <前缀>*`	查看参数（如 `param show BAT1_*`）
`param set <名> <值>`	设置参数
`param save`	保存参数（重启后保留）
`listener <topic>`	查看某个 uORB 话题的实时数据
`top`	查看各模块 CPU 占用
`uorb top`	查看各话题发布频率
`help`	查看所有命令

示例：

pxh> listener vehicle_attitude     # 看实时姿态
pxh> listener vehicle_local_position  # 看实时位置
pxh> param show MC_ROLLRATE_P      # 查 PID 参数
pxh> param set MC_ROLLRATE_P 0.15  # 改 PID
pxh> param show CBRK*              # 查断路器参数

⚠️ 注意：PX4 shell 里没有 reboot 命令（SITL 重启就是 Ctrl+C 后重新 make）

五、今日问题与解决汇总

5.1 Battery unhealthy（无法解锁）

现象：

WARN [health_and_arming_checks] Preflight Fail: Battery unhealthy
WARN [failsafe] Failsafe activated
INFO [commander] Disarmed by auto preflight disarming

原因：SITL 模拟电池电量低 → 触发预检失败 → 自动上锁

❌ 试错过的错误参数名（都不存在）：

CBRK_BAT_CHK              ← 不存在
BAT1_VOLTAGE_NOMINAL      ← 不存在
BAT1_VOLTAGE_MIN / MAX    ← 不存在

✅ 正确解决（PX4 v1.14）：

pxh> param set CBRK_SUPPLY_CHK 894281
pxh> param save

894281 是 magic number，PX4 官方文档确认：设为该值可禁用电源检查。
⚠️ 只在 SITL 仿真用！真机绝对不要禁用电池检查（会失去低电量保护）。

备选方案（让模拟电池不掉电）：

pxh> param set SIM_BAT_MIN_PCT 90
pxh> param save

真机的正确做法：配好电源模块 + 电池参数（不推荐禁用检查）

参数	说明
`BAT1_N_CELLS`	电池节数（4S 填 4）← 最常填错的
`BAT1_CAPACITY`	容量 mAh
`BAT1_V_DIV`	电压分压比（电源模块上印着）
`BAT1_A_PER_V`	电流比例
`BAT1_V_EMPTY` / `BAT1_V_CHARGED`	单节空电/满电电压

5.2 Gazebo 图形界面不显示

现象：

make px4_sitl gazebo 能跑（PX4 连上仿真器、能起飞）
但看不到 Gazebo 3D 窗口

排查过程：

echo $XDG_SESSION_TYPE    # x11（正常，不是 Wayland）
echo $DISPLAY             # :0（正常）
ps aux | grep -E "gzserver|gzclient" | grep -v grep
# 只有 gzserver，没有 gzclient  ← GUI 没起来

gzclient 手动启动的结果：

$ gzclient
../src/intel/isl/isl.c:2105: FINISHME: ... CCS for 3D textures is disabled...
已杀死
$ echo $?     → 137（SIGKILL）

已排除的原因：

怀疑	检查结果
内存不足（OOM）	❌ 内存 4.2G 可用、Swap 几乎没用、无 OOM 记录
Wayland 会话	❌ 是 x11
DISPLAY 没设置	❌ 是 `:0`

怀疑方向：笔记本挂起/恢复后 Intel 显卡（i915）状态异常（dmesg 里有 PM: suspend entry/exit）

当前绕过方案（✅ 可用）：

# headless 模式跑仿真（无 3D 界面，但仿真数据完全正常）
cd ~/PX4-Autopilot
HEADLESS=1 make px4_sitl gazebo

# 然后只开 QGC 看状态/操作
cd ~/下载 && ./QGroundControl.AppImage

待验证：重启电脑后再试 make px4_sitl gazebo，看窗口能否出来。

5.3 VSCode 调试与手动启动冲突

现象：VSCode 点调试按钮启动 → 会杀掉手动启动的 Gazebo

原因：VSCode 的调试配置每次都会重启整个仿真环境

解决：别混用 —— 固定用终端 make px4_sitl gazebo，VSCode 只当编辑器

（进阶）以后要打断点：用 Attach 方式（仿真先跑起来，VSCode 连上去）

六、今日工作流总结（推荐固定用法）

┌─────────────────────────────────────────────────────┐
│ ① VSCode：打开 ~/PX4-Autopilot，改代码、看代码       │
│           （Ctrl+点击跳转定义、Ctrl+Shift+F 全局搜索）│
│           ❌ 不用 F5 / 调试按钮                      │
├─────────────────────────────────────────────────────┤
│ ② 终端1：跑仿真                                      │
│    cd ~/PX4-Autopilot                               │
│    make px4_sitl gazebo -j$(nproc)                  │
│    （看不到 3D 界面就加 HEADLESS=1）                 │
├─────────────────────────────────────────────────────┤
│ ③ 终端2：MAVROS                                      │
│    roslaunch mavros px4.launch \                     │
│      fcu_url:="udp://:14540@127.0.0.1:14557"        │
├─────────────────────────────────────────────────────┤
│ ④ QGC：地面站看状态、虚拟遥控、航点、调参            │
│    cd ~/下载 && ./QGroundControl.AppImage            │
├─────────────────────────────────────────────────────┤
│ ⑤ 终端3：实时数据曲线                                │
│    rqt_plot /mavros/local_position/pose/pose/position/z │
└─────────────────────────────────────────────────────┘

七、命令速查卡（贴墙版）

# ===== 启动 =====
cd ~/PX4-Autopilot && make px4_sitl gazebo -j$(nproc)   # 编译 + 启动仿真
HEADLESS=1 make px4_sitl gazebo                          # 无 3D 界面
roslaunch mavros px4.launch fcu_url:="udp://:14540@127.0.0.1:14557"
./QGroundControl.AppImage                                # 地面站

# ===== PX4 shell (pxh>) =====
commander arm          # 解锁
commander takeoff      # 起飞
commander land         # 降落
commander disarm       # 上锁
commander status       # 状态
param set CBRK_SUPPLY_CHK 894281   # SITL 禁用电池检查
param save
listener vehicle_attitude          # 看实时数据

# ===== ROS / 调试 =====
rostopic echo -n1 /mavros/state    # 看连接状态
rostopic hz /mavros/local_position/pose   # 看频率
rqt_plot /mavros/attitude/roll             # 实时曲线
rqt_multiplot                              # 多图实时曲线

# ===== 日志 =====
ls ~/PX4-Autopilot/build/px4_sitl_default/rootfs/log/*/*.ulg
plotjuggler      # 打开 .ulg 分析

八、待办 / 下一步

重启电脑后再试 Gazebo 图形界面（怀疑挂起恢复导致显卡问题）
用 QGC 完整跑一次：虚拟遥控手动飞 → 航点自动飞 → 调 PID
用 rqt_plot 实时观察 offboard 脚本执行时的位置/姿态曲线
用 PlotJuggler 分析一次完整飞行的 .ulg 日志
（进阶）试 VSCode 的 Attach 调试：仿真先跑，再连上去打断点
（进阶）真机链路：飞控串口 ↔ 机载电脑的 MAVLink 配置

本文档记录 2026-09-15 的 PX4 开发环境上手过程，供后续查阅。

posted @ 2026-09-15 22:26 xofitto 阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

xofitto