QGroundControl 开发者工具实战指南：Mock Link 模拟载具、遥测重放与 MAVLink 调试面板详解-平芜编程栈

无人机
智能硬件

【免费下载链接】qgroundcontrol

Cross-platform ground control station for drones (Android, iOS, Mac OS, Linux, Windows)

项目地址：https://gitcode.com/gh_mirrors/qg/qgroundcontrol

本文面向自动驾驶仪（autopilot）开发者与载具制造商，系统讲解 QGroundControl 提供的四大开发者工具：Mock Link 多模拟载具链接、遥测日志重放、MAVLink Inspector 消息检视与绘图、MAVLink Console 系统 Shell。读完本文，你将掌握这些工具的启用前提、完整操作流程，以及它们背后的源码实现与配置参数，能够独立搭建无硬件的测试环境，快速定位通信与任务问题。

QGroundControl（QGC）是一套跨平台地面站（支持 Android、iOS、macOS、Linux、Windows），其核心交互基于 Qt/QML 实现。除了面向普通用户的飞行与规划功能，它还内置了一系列主要面向自动驾驶仪开发者的工具，用于简化常见开发任务：设置模拟连接以进行测试、重放历史飞行数据、通过 MAVLink 检视通信流量，乃至直接访问 PX4 的系统 Shell。

本文对应的官方开发者指南章节位于 docs/zh/qgc-dev-guide/tools/index.md，是开发者工具的索引页。下面逐一展开四种工具的用法与实现原理，并结合仓库源码（src/Comms/MockLink/、src/Comms/LogReplayLink.h、src/AnalyzeView/MAVLinkInspector/、src/AnalyzeView/MAVLinkConsole/）进行纵深解读。

启用前提：必须在调试版本中构建

:::info重要前提：上述工具仅在**调试模式（debug build）**下生成的地面站中启用。请从源码构建一个调试版本后再使用这些功能，构建方式参见仓库根目录的 README.md。 :::

这意味着：

直接下载的每日构建（Daily Build）或发布版不一定包含全部开发者工具；
需要自行通过 CMake 配置 Debug 构建，才能获得 Mock Link 等入口；
部分工具（如遥测重放、MAVLink Inspector、MAVLink Console）仅在桌面版本（Windows、Linux、macOS）上支持。

工具总览

工具	入口	适用对象	平台限制
Mock Link	顶部工具栏的 Application Settings 图标 → 侧边栏Mock Link	自动驾驶仪开发者（仅调试版本）	无特殊限制
重放飞行数据	应用程序设置 → 常规 → 飞行视图 → 显示 Telemetry 日志重播状态栏	自动驾驶仪开发者 / 载具制造商	仅桌面版
MAVLink Inspector	分析视图（Analyze View）→ 侧边栏MAVLink 检查器	自动驾驶仪开发者 / 载具制造商	仅桌面版
MAVLink Console	分析视图 →MAVLink 控制台（PX4 Only）	PX4 开发者	仅桌面版；不支持 PX4 SITL 与 ArduPilot

下面分别深入介绍。

Mock Link：零硬件创建多个模拟载具

Mock Link 允许在调试版 QGC 中创建和停止指向多个模拟（虚拟）载具的链接，是开发阶段最常用的测试入口，对应文档为 docs/zh/qgc-dev-guide/tools/mock_link.md。

它能测试什么

模拟载具不支持真实飞行，但可以轻松测试以下场景：

任务上传 / 下载（mission upload/download）
查看和更改参数
测试大多数设置页面
多载具用户界面（Multi-Vehicle UI）
对任务上传/下载的单元测试错误情况尤为有用（例如在 MockLinkMissionItemHandler.h 中可通过setMissionItemFailureMode()注入任务确认失败等异常场景）

使用步骤

通过构建源码创建调试版本（见上文“启用前提”）。
点击顶部工具栏的Application Settings图标，然后在侧边栏中选择Mock Link，打开 Mock Link 面板。
点击面板中的按钮创建对应类型的载具链接：
- 每次单击按钮都会创建一个新的连接；
- 当存在多个连接时，界面会切换为多载具 UI。
点击停止一个 Mock 连接（Stop One MockLink）来停止当前正在使用的载具。

之后使用模拟链接与使用任何其他载具基本相同，唯一区别是模拟载具不允许飞行。

源码视角：MockLink 的构成与配置项

从源码结构看，Mock Link 是一套完整的“虚拟 MAVLink 端”，其核心实现集中在 src/Comms/MockLink/ 目录：

MockLink（MockLink.h）：继承自LinkInterface，模拟一个真实链路。内部以run1HzTasks()、run10HzTasks()、run500HzTasks()等周期任务推进模拟载具的姿态、心跳与遥测数据，并提供setArmed()、setCalibrationPose()、setCommLost()等测试专用 API。
MockLinkWorker（MockLinkWorker.h）：在工作线程中驱动链路收发。
MockConfiguration（MockConfiguration.h）：模拟链接的配置类，定义了固件类型、载具类型、相机/云台能力等一组可调项（详见下文）。
扩展模拟器：MockLinkCamera（相机）、MockLinkGimbal（云台）、MockLinkFTP（MAVLink FTP 文件传输）、MockLinkPX4Calibration（PX4 校准流程）、MockLinkMissionItemHandler（任务协议处理，含失败模式注入）。

关键配置项与默认值

在 MockConfiguration.h 中，模拟载具可通过 Q_PROPERTY 暴露以下配置（以链接配置页形式保存到 QSettings，见 MockConfiguration.cc）：

配置项	含义	默认值（来源：MockConfiguration.cc）
`firmware`	模拟固件类型（PX4 Pro / ArduPilot / Generic MAVLink）	`MAV_AUTOPILOT_PX4`（12）
`vehicle`	模拟载具类型（多旋翼 / 固定翼等）	`MAV_TYPE_QUADROTOR`
`sendStatus`	是否发送 STATUSTEXT 状态文本与语音	可配置
`enableCamera`	是否模拟相机（含视频流、拍照、变焦、跟踪等能力开关）	可配置
`enableGimbal`	是否模拟云台（含滚转/俯仰/偏航轴、锁定/跟随等能力开关）	可配置
`enableProximity`	是否模拟近距离传感器（避障）	可配置
`incrementVehicleId`	每次新建连接是否自动递增载具 ID，用于多载具场景	`true`（默认递增）

界面入口：MockLink 面板与链接配置页

仓库中有两处 QML 实现：

src/AppSettings/MockLink.qml：即“Application Settings → Mock Link”主面板。它提供Vehicle Type下拉框（PX4 Vehicle、APM ArduCopter / ArduPlane / ArduSub / ArduRover、Generic Vehicle），以及Start MockLink / Stop One MockLink按钮；点击按钮时分别调用QGroundControl.startPX4MockLink()、startAPMArduCopterMockLink()、startAPMArduPlaneMockLink()、startAPMArduSubMockLink()、startAPMArduRoverMockLink()或startGenericMockLink()（这些全局接口定义在 QGroundControlQmlGlobal.cc）。此外还可勾选“Send status text + voice”“Enable camera”“Enable gimbal”“Enable proximity sensors”，并选择模拟的视频流类型（Disabled / RTP-UDP H.264 / RTP-UDP H.265 / RTSP H.264 / MPEG-TS UDP / MPEG-TS TCP）。
src/AppSettings/MockLinkSettings.qml：单个 Mock 链接的配置页（MockConfiguration::settingsURL()指向该文件），可更精细地设置相机的CAMERA_CAP_FLAGS_*能力位与云台的GIMBAL_MANAGER_CAP_FLAGS_*能力位，用于验证相机/云台协议的各种分支。

内置参数集

仓库随 Mock Link 提供了开箱即用的参数文件，模拟载具会加载这些参数：

PX4MockLink.params：PX4 Pro（1.17.0）多旋翼机载参数集，包含BAT1_*、CAL_ACC*、ATT_EN等上千个参数；
GenericMockLink.params：通用 MAVLink 参数集；
Mocklink.Arduplane.params.ftp.bin：ArduPilot 固定翼参数（经 FTP 传输）。

这解释了为什么无需任何硬件即可验证“查看和更改参数”“参数下载”等功能。此外，仓库test/目录中大量单元测试（如任务协议、相机控制等）都直接构建在 MockLink 之上，用setMissionItemFailureMode()、sendUnexpectedMissionAck()等 API 注入异常来验证地面站的容错逻辑。

重放飞行数据：回看历史遥测日志

重放飞行数据允许用户重新播放遥测日志，从而对过去的飞行或有问题的飞行进行复盘审查。飞行可以启动、暂停、停止、重新启动等，对应文档为 docs/zh/qgc-user-guide/fly_view/replay_flight_data.md。

:::warning 此功能主要适用于autopilot 开发者 / 载具制造商，并且仅在桌面版本（Windows、Linux、macOS）上支持。 :::

:::info QGC 将飞行重放视为活动连接。当暂停/停止播放时，地面站会报告“通信丢失（communication loss）”，并等待断开连接或更多消息。这是排障时的重要行为：暂停≠安静，而是表现为链路中断。 :::

重放操作流程

断开任何活动连接。
选择应用程序设置 → 常规 → 飞行视图。
勾选显示 Telemetry 日志重播状态栏（Show Telemetry log replay status bar），在屏幕底部调出飞行重播栏。
点击Load Telemetry 日志按钮打开文件选择对话框：
- 从可用遥测日志中选择要重播的日志文件；
- QGC 会立即开始播放该日志。
加载日志后，可使用以下控制：
- 暂停/播放按钮：暂停与重启播放；
- 滑块：拖动到日志中的任意新位置（跳转播放进度）；
- 速度选择器：选择播放速度（快进/慢放）。
要停止重播（例如加载新文件）：先暂停飞行，再选择断开连接（当它出现时）。断开后，“Load Telemetry 日志”按钮会重新显示。

:::tip 可结合 MAVLink 检查器更详细地检查正在运行的回放，逐条核对重放过程中的消息内容。 :::

源码视角：LogReplayLink 的实现

重放功能的底层实现在 src/Comms/LogReplayLink.h：

LogReplayConfiguration：重放链路的配置类，仅需一个filename（日志文件路径），并对应LogReplaySettings.qml设置页。
LogReplayWorker：核心工作对象，负责：
- 解析日志格式（_parseTimestamp()：每条记录前置一个quint64时间戳，随后是 MAVLink 报文；_seekToNextMavlinkMessage()跳过无效字节）；
- 以定时器（_readTickTimer）按时间轴驱动_readNextLogEntry()逐条发送消息；
- 对外暴露play()/pause()/setPlaybackSpeed(qreal)/movePlayhead(qreal percentComplete)等槽，正好对应 UI 上的暂停/播放、速度选择器与进度滑块；
- 发出playbackStarted、playbackPaused、playbackAtEnd、playbackPercentCompleteChanged、currentLogTimeSecs等信号驱动界面状态。
LogReplayLink：继承LinkInterface，将重放伪装成一个普通连接——这正是“QGC 将飞行重放视为活动连接”这一行为的源码根源。

MAVLink Inspector：实时消息检视与字段绘图

MAVLink 检查器提供实时信息并绘制由 QGC 接收的 MAVLink 流量图，是分析通信协议与调试遥测数据的高频工具，对应文档为 docs/zh/qgc-user-guide/analyze_view/mavlink_inspector.md。

:::warning 此功能主要适用于autopilot 开发者 / 载具制造商，且仅在桌面版本（Windows、Linux、macOS）上支持。 :::

核心能力

检查器会列出当前载具收到的所有消息，以及其源组件标识（source component ID）和更新频率（Hz）。可以深入查看单条消息，获取消息 ID、源组件 ID 以及所有单个字段的值，并支持实时绘制字段值：可从多条消息中选取多个字段，显示在两个图表之一中。

使用步骤

通过 QGC 应用程序菜单（左上角 “Q” 图标）打开分析视图（Analyze View），在“选择工具”弹窗中选择分析工具。
从侧边栏选择MAVLink 检查器。视图会在收到消息时开始填充消息列表。
选择一条消息，查看其字段及（动态更新的）值。
勾选相邻的复选框，将字段添加到图表（图 1 显示在图 2 下方）：
- 一个字段只能添加到一个图表；
- 一个图表可包含多个字段、甚至多条消息的字段（这些字段会在每个图表上列出），包含正在绘制字段的消息会用星号高亮显示；
- **比例（scale）与范围（range）**已设置为合理值，需要时可以手动修改。

源码视角：检查器与绘图控制器

MAVLinkInspectorController.h /.cc：以QmlObjectListModel维护多系统（system）列表（QGCMAVLinkSystem），通过_receiveMessage()接收链路消息、以_refreshFrequency()定时刷新各消息的更新频率，并提供setActiveSystem()切换检视对象、setMessageInterval(rate)向载具请求调整指定消息的发送间隔（内部经MAV_CMD_SET_MESSAGE_INTERVAL下发）。
MAVLinkMessage / MAVLinkMessageField（MAVLinkMessage.h）：封装单条消息及其字段值。
MAVLinkChartController（MAVLinkChartController.h）：管理两张图表的字段绑定与取值范围，对应 UI 中“图 1 / 图 2”与比例/范围调节。

实际使用中，检查器常与重放飞行数据组合：一边重放日志，一边检视/绘图，从而逐帧排查某个字段的异常跳变。

MAVLink Console：连接 PX4 系统 Shell

MAVLink 控制台（Analyze → MAVLink 控制台）允许连接到 PX4 的**系统控制台（System Console / NSH Shell）**并发送命令，相当于通过 MAVLink 远程操作飞控的命令行，对应文档为 docs/zh/qgc-user-guide/analyze_view/mavlink_console.md。

:::info 仅在桌面版本（Windows、Linux、macOS）上支持；不支持 PX4 SITL 与 ArduPilot。 :::

:::tip 这是开发者非常有用的功能，因为它允许深入访问系统。特别是，如果你通过 Wi-Fi 连接，可以在载具飞行时拥有同样的访问级别，无需物理连接调试串口。 :::

使用方法

除了对命令的响应外，视图不显示任何额外输出。
载具连接后，在提供的输入栏中输入命令；输入?可获得可用命令的完整列表。
命令输出显示在命令栏上方的视图中；点击“显示最新内容”可跳转到命令输出的底部。

典型场景包括：查看top任务负载、list查看文件系统、param show查看参数、手动启停服务等 NSH 命令。

源码视角：控制台控制器

实现位于 src/AnalyzeView/MAVLinkConsole/：

MAVLinkConsoleController（MAVLinkConsoleController.h）：基于QStringListModel的控制器，通过sendCommand()经串口数据通道（_sendSerialData()）把命令发往飞控，_receiveData()接收回显。
- 内置命令历史（CommandHistory，最多保留 100 条），支持historyUp()/historyDown()上下翻阅；
- 支持剪贴板批量粘贴（handleClipboard()：若剪贴板含多行，则逐行执行前 N-1 条，返回最后一行作为待编辑内容）；
- 对回显做ANSI 控制字符处理（_processANSItext()、_transformLineForRichText()），使top等动态刷新输出在界面中正确呈现；
- 输出缓冲上限为500 行（kMaxNumLines，影响 CPU 负载），超出后自动清理。
MAVLinkConsolePage.qml（MAVLinkConsolePage.qml）：基于AnalyzePage的页面实现，负责命令输入、回显滚动与“显示最新内容”按钮，并针对移动端使用独立命令输入框。

组合实战建议

上述工具可以自由组合成一套无硬件的开发/排障工作流：

场景	推荐组合
验证任务协议与容错逻辑	Mock Link 注入失败模式（`setMissionItemFailureMode`）+ 任务上传/下载
排查历史飞行中的通信异常	重放飞行数据 + MAVLink Inspector 检视与绘图
远程调试 PX4 运行时状态	MAVLink Console 输入`top`/`?`查看系统信息
验证多载具 UI 与参数下载	多次点击 Mock Link 创建多连接（`incrementVehicleId`自动分配 ID）

所有工具对应的源码与配置均可继续在仓库中深入阅读：Mock Link 全家桶位于 src/Comms/MockLink/，重放链路见 src/Comms/LogReplayLink.h，检视与控制台分别位于 src/AnalyzeView/MAVLinkInspector/ 与 src/AnalyzeView/MAVLinkConsole/，界面入口集中在 src/AppSettings/MockLink.qml 与 src/AppSettings/MockLinkSettings.qml。需要提醒的是：这些开发者工具以调试构建为启用前提，部分工具仅限桌面平台，PX4 控制台不支持 SITL 与 ArduPilot，使用前请对照各自的前提条件。