QGroundControl MAVLink 设置详解：地面站标识、链路监控与 PX4 日志流式上传-平芜编程栈

无人机
智能硬件

【免费下载链接】qgroundcontrol

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

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

导读

本文围绕 QGroundControl 的SettingsView > MAVLink设置页展开，逐项讲解地面站 MAVLink 参数（System ID、心跳、协议版本过滤、消息转发）、链路质量监控，以及 PX4 专用的 MAVLink 2 日志流式记录与自动上传到 Flight Review 的完整配置流程。阅读本文后，你可以在多地面站、混合协议版本的网络环境中正确配置 QGC，并能把飞行日志自动化归档到 Flight Review 用于调试分析。

MAVLink 设置页对应源码中的 MavlinkSettings 设置组，所有参数项的元数据（类型、默认值、取值范围）集中定义在 Mavlink.SettingsGroup.json，本文的参数说明均以该文件及对应实现代码为准。

QGroundControl MAVLink 设置页总览，包含地面站参数、链路状态与 PX4 日志管理三个功能区

Ground Station：地面站 MAVLink 属性配置

本区块设置 QGC 自身作为 MAVLink 网络节点时的标识与行为，对应 QML 界面 Telemetry.SettingsUI.json 中绑定的mavlinkSettings.*各项 Fact。

MAVLink System ID（系统 ID）

取值：1～255，默认255（见 Mavlink.SettingsGroup.json 中gcsMavlinkSystemID的min/max/default定义）。
作用：地面站在 MAVLink 网络中的身份标识。飞行器通常从 1 开始分配 ID，因此 255 作为地面站默认值可以避免与绝大多数机载系统冲突。
何时需要修改：当网络中存在多个地面站或其它 MAVLink 应用（如另一台 QGC、MAVProxy、mavlink-router 等）时，需要为每个节点指定互不相同的 System ID，否则会出现消息被错误路由或冲突。
实现层面：MAVLinkProtocol::getSystemId()直接返回该设置值（见 MAVLinkProtocol.cc），它决定 QGC 发出所有消息的 sysid 字段。QGC 启动时还支持通过命令行参数覆盖该值（见 QGCApplication.cc 中的_systemId注入逻辑）。

Emit heartbeat（发送心跳）

默认值：True（sendGCSHeartbeat默认true）。
作用：周期性地向链路发送 MAVLinkHEARTBEAT消息，让飞行器感知到地面站处于在线状态。关闭后飞行器可能因“失去地面站”而触发失控保护（Failsafe）等逻辑。
建议：文档与源码注释均明确强调“一般不应关闭”。除非在做协议调试等特殊场景，否则保持默认开启。

Only accept MAVs with the same protocol version（仅接受同协议版本的飞行器）

默认值：True。
作用：开启后，QGC 只会连接与自己 MAVLink 版本一致（MAVLink 1 或 MAVLink 2）的飞行器，避免混用版本带来的解析问题。关闭后则允许同时接入不同协议版本的设备。
实现佐证：从 MAVLinkProtocol.cc 的协议处理代码可以看到，QGC 内部会对 v1/v2 消息采用不同的序列号计数与兼容策略，混用版本时统计与解析更容易出现偏差，这正是该选项存在的原因。

Enable MAVLink forwarding（启用 MAVLink 转发）

默认值：False。
作用：将已连接飞行器收到的 MAVLink 消息单向转发到指定的 UDP 端点（例如另一个地面站、调试工具或日志采集服务）。转发是单向的：从 QGC 发往指定主机；从该主机收到的消息会被忽略。
配置方式：启用转发后还需填写Host name（forwardMavlinkHostName），格式为主机:端口，默认值localhost:14445（见 Mavlink.SettingsGroup.json）。
实现层面：
- LinkManager::_addMAVLinkForwardingLink()在转发开关开启时检查是否已存在名为 "MAVLink Forwarding Link" 的动态 UDP 链路，不存在则按 Host name 创建（见 LinkManager.cc）；
- LinkManager::_createDynamicForwardLink()会新建一个UDPConfiguration，设置dynamic与forwarding标志并addHost后建立连接（见 LinkManager.cc）；
- 消息转发由MAVLinkProtocol::_forward()执行：会跳过SETUP_SIGNING消息，并在转发前剥离签名（serializeUnsignedCopy），以免外部队列因未知密钥报BAD_SIGNATURE（见 MAVLinkProtocol.cc）。

Link Status：链路质量监控

该区块实时展示 MAVLink 消息在通信链路上的传输状况，界面实现见 MavlinkLinkStatus.qml，显示的指标包括：

指标	说明	数据来源
Total messages sent (computed)	已发送消息总数（估算）	`Vehicle.mavlinkSentCount`
Total messages received	已接收消息总数	`Vehicle.mavlinkReceivedCount`
Total message loss	累计丢失消息数	`Vehicle.mavlinkLossCount`
Loss rate	丢包率（百分比）	`Vehicle.mavlinkLossPercent`
Signing / Signing key / Signing streams	MAVLink 2 签名状态、密钥名、已签名流数	`Vehicle.signingController`

丢包率的计算：MAVLinkProtocol根据 MAVLink 消息序号（seq）的连续性统计丢失数量，并按滑动平均更新_runningLossPercent（见 MAVLinkProtocol.cc）。
高丢包率的影响：文档明确指出，丢包率过高会导致参数下载、任务上传/下载等协议流程出错。实践中应优先检查链路本身的信号强度、带宽与串口波特率，而不是依赖重传。

MAVLink 2 Logging（PX4 专用）：实时日志流式记录

该区块（界面见 PX4LogControl.qml）用于将 PX4 飞行日志实时通过 MAVLink 2 流式传输到 QGC 本地保存，仅对 PX4 固件可用。

前置条件与限制

:::warning 重要限制 MAVLink 2 Logging不适用于“基础（basic）”配置，因为它要求与飞行器保持持续的高速率 MAVLink 连接——在 Wi-Fi 链路上也许可行，但在数传（Telemetry）链路上无法工作。 :::

另外从源码角度看（PX4LogControl.qml），该区块还需要QGroundControl.corePlugin.options.showPX4LogTransferOptions为真，且当前活动飞行器为 PX4 固件时才显示。

日志格式与差异

流式日志与通过 Analyze View > Log Download 从 SD 卡下载的日志格式相同（即 PX4 的 ULog 格式，QGC 侧以logFileExtension设置确定扩展名，见 MAVLinkLogManager.cc），但实际内容可能略有差异：日志起止时间由 QGC 控制，且在有损链路上传输时可能出现部分丢帧。

手动/自动记录

界面提供两类控制：

Manual Start/Stop（手动开始/停止）：点击Start Logging启动、Stop Logging停止。源码中startLogging()会调用Vehicle::startMavlinkLog()，stopLogging()关闭本地日志文件并结束记录（见 MAVLinkLogManager.cc）。
Enable automatic logging（自动记录）：开启后，QGC 在飞行开始（起飞）时自动开始记录、结束时自动停止。
注意：当appSettings.disableAllPersistence开启时（对应“禁用所有持久化”的调试选项），日志控制按钮会被禁用。

MAVLink 2 Logging 区块：手动开始/停止日志与自动记录开关

MAVLink 2 Log Uploads：配置上传到 Flight Review

该区块（界面见 PX4LogUploadSettings.qml）用于把记录到的日志上传到Flight Review（logs.px4.io），支持预先填好所有字段，并选择自动或手动上传。

字段详解

字段	说明	备注/取值范围
Email address for Log Uploads	上传后 Flight Review 会把日志访问链接发到该邮箱	必填：源码`_sendLog()`在邮箱为空时直接返回失败并告警（见 MAVLinkLogManager.cc）；非公开日志只能靠这个邮件链接访问
Default Description	该日志对应的飞行描述/名称	留空时使用默认描述`"QGroundControl Session"`（常量`kDefaultDescr`，见 MAVLinkLogManager.h）
Default Upload URL	日志/元数据的上传地址	默认即为 Flight Review 的 URL；可改为自建收集服务
Video URL（可选）	与该次飞行关联的视频地址	会显示在 Flight Review 页面辅助分析
Wind Speed	风速等级，用于多航次调试与筛选	可选值：`Calm`/`Breeze`/`Gale`/`Storm`（源码对应数值 0 / 5 / 8 / 10，见 PX4LogUploadSettings.qml）
Flight Rating	飞行评级，用于多航次筛选	可选值：`Crashed (Pilot Error)`/`Crashed (Software or Hardware issue)`/`Unsatisfactory`/`Good`/`Great`（源码对应`crash_pilot`/`crash_sw_hw`/`unsatisfactory`/`good`/`great`，见 PX4LogUploadSettings.qml）
Additional Feedback（可选）	对飞行或行为的更详细描述	多行文本
Make this log publically available	是否公开日志	开启后日志在 Flight Review 上可见、可被搜索；关闭则仅能通过上传邮件中的链接访问
Enable automatic log uploads	记录完成后自动上传	注意：开启时若未填写邮箱，QGC 会弹出提示并要求先填写（见 PX4LogUploadSettings.qml）
Delete log file after uploading	上传完成后自动删除本地日志文件	仅在“自动上传”开启时可勾选（见 PX4LogUploadSettings.qml）

上传请求的构成（实现细节）

从 MAVLinkLogManager::_sendLog 可以看到，上传以 HTTPmultipart/form-data请求完成，包含以下表单字段：email、description、source（固定为QGroundControl）、version（应用版本号）、type（固定为flightreport）、windSpeed、rating、public，外加日志文件本身。因此只要把上文各字段在设置页填好，QGC 即可自动构造出与在网站上手动填写等价的提交。除主字段外，Video URL与反馈信息也随请求一并发送（对应常量kVideoURL等，见 MAVLinkLogManager.h）。

自动上传的触发路径

开启自动上传后，当stopLogging()结束一次记录时，若_enableAutoUpload为真，日志条目会被自动勾选并立即触发uploadLog()（见 MAVLinkLogManager.cc），实现“记录结束 → 上传 → （可选）删除”的全自动闭环。

Saved Log Files：本地日志的批量管理

该区块（界面见 PX4LogFileManager.qml）列出 QGC 已保存的所有 MAVLink 日志文件，用于手动选择、删除或上传：

每条记录显示文件名、文件大小；已上传的文件会显示"Uploaded"标记，正在上传的显示进度条。
上传状态通过同目录下生成的.uploaded旁车文件（sidecar）持久化记录：文件存在即视为已上传（见 MAVLinkLogManager.cc）。
按钮说明：
- Check All / Check None：全选 / 全不选；
- Delete Selected：删除所选日志（需二次确认）；
- Upload Selected：上传所选日志——若邮箱为空会先弹窗提示“请先填写邮箱地址”；
- Cancel：取消正在进行的上传。
这些操作在日志正在记录（logRunning）或正在上传（uploading）时会被禁用，避免并发冲突。

Saved Log Files 区块：日志列表、选择与批量上传/删除操作

实操建议与排查提示

多地面站场景：先确认各节点 System ID 唯一，再考虑是否开启 MAVLink 转发；转发目标地址务必写为IP:端口形式。
日志上传前：先填写邮箱并验证能收到 Flight Review 链接，再启用“自动上传”，否则自动上传会被阻止。
丢包率高：结合 Link Status 的丢包率数值判断链路质量；高丢包会直接拖慢参数与任务传输，且会导致 MAVLink 2 流式日志出现丢帧。
PX4 日志闭环：在数传链路下不建议依赖流式日志记录（应使用 SD 卡日志 + Analyze View > Log Download）；Wi-Fi 环境可开启“自动记录 + 自动上传”，配合“上传后删除”实现无人值守归档。
旧版本迁移：QGC 在启动时会自动把旧版设置键（如QGC_MAVLINK_PROTOCOL/GCS_SYSTEM_ID、gcsHeartbeatEnabled）迁移到新的MavlinkSettings键下，老用户的 System ID 与心跳配置无需手动重填（见 MavlinkSettings.cc）。