QGroundControl 任务恢复失败排查指南:Resume Mission 对话框与任务重建的完整调试流程
QGroundControl 任务恢复失败排查指南:Resume Mission 对话框与任务重建的完整调试流程
本文围绕 QGroundControl(QGC)中“换电池后继续任务”(Resume Mission)这一功能的两类典型故障——Resume Mission 对话框该出现时不出现、以及恢复任务重建后航点/相机指令不正确——展开。读完后,你将掌握官方推荐的标准化复现与取证流程(开启指定日志类别、收集 App Log / 遥测日志 / 计划文件),并能从源码层面理解 showResumeMission 的判定条件、resumeMissionIndex 的计算逻辑以及 generateResumeMission 重建任务的算法细节,从而在提交 issue 时给出可复现、可定位的完整证据链。
一、Resume Mission 功能与两类典型故障
在 QGC 中,执行换电池等短暂中断后恢复任务是一个相当复杂的流程。原文档(resume_mission.md)指出,最容易出现问题的两个区域是:
- Resume Mission 对话框不显示:载具降落上锁后本应出现 Resume Mission 对话框,却只剩一个 Start Mission 滑块(按钮);
- 恢复任务重建不正确:由 Resume Mission 生成的新任务在航点重建和/或相机指令重建上存在偏差。
文档同时强调:为了让 QGroundControl 开发团队能够调试这些问题,在针对 Resume Mission 提交任何 issue 时,必须提供下文中所述的完整信息。
二、两类问题的通用调试步骤(Common Steps)
无论是对话框问题还是任务生成问题,以下通用步骤都必不可少:
- 重启 QGC(Restart QGC);
- 开启控制台日志(参考 Console Logging),并启用日志类别:
QMLControls.GuidedActionsController; - 启用遥测日志(Settings > General 中的“来自载具的遥测日志”一节,即
#telemetry_logs); - 开始任务(Start the mission);
- 飞行直至需要换电池;
提示(tip):也可以在任务中段手动执行 RTL(Return to Launch)来尝试复现问题,但这不一定总能触发故障;
- 一旦载具降落并上锁(disarm),你应该看到 Resume Mission 对话框。如果没看到,则说明 QGC 中可能存在 bug。
2.1 为什么是 QMLControls.GuidedActionsController 这个日志类别
从源码结构看,这个类别名对应 C++ 侧的日志注册:
// src/QmlControls/QGroundControlQmlGlobal.cc
QGC_LOGGING_CATEGORY(GuidedActionsControllerLog, "QMLControls.GuidedActionsController")
而 QML 侧的 GuidedActionsController.qml 正是控制引导模式所有动作(包括 Resume Mission)是否显示/可执行的“大脑”。它会持续输出内部状态:
// src/FlyView/GuidedActionsController.qml (L196-L200)
function _outputState() {
if (_isGuidedActionsControllerLogEnabled()) {
console.log(qsTr("_activeVehicle(%1) _vehicleArmed(%2) guidedModeSupported(%3) ..."))
}
}
并在关键状态变化时打印 showResumeMission、_resumeMissionIndex 的值(L265-L275):
on_ResumeMissionIndexChanged: {
if (_isGuidedActionsControllerLogEnabled()) {
console.log("_resumeMissionIndex", _resumeMissionIndex)
}
}
onShowResumeMissionChanged: {
if (_isGuidedActionsControllerLogEnabled()) {
console.log("showResumeMission", showResumeMission)
}
_outputState()
}
因此打开该类别后,App Log 中会留下“对话框为何没显示”的完整判定现场——这正是通用步骤第 2 步的价值所在。类别的启用/禁用逻辑由 QGCLoggingCategoryManager 统一管理,QML 侧通过 QGCLoggingCategoryManager.isCategoryEnabled("GuidedActionsControllerLog") 检查开关状态。
三、故障 A:Resume Mission 对话框不显示
对于 Resume Mission 对话框问题,在完成上述通用步骤后,继续执行:
- 将 App Log 保存为文件;
- 将 App Log、Telemetry Log、Plan File 放到可以在 issue 中给出链接的位置;
- 创建 issue,附上详细信息和全部 三个 文件的链接。
3.1 源码级原理:对话框何时会显示
Resume Mission 入口位于任务结束对话框 FlyViewMissionCompleteDialog.qml 中,只有当以下条件同时成立时,"Resume Mission From Waypoint %1" 按钮区域才会可见:
// src/FlyView/FlyViewMissionCompleteDialog.qml (L106)
visible: !_activeVehicle.communicationLost && globals.guidedControllerFlyView.showResumeMission
其中 showResumeMission 的定义在 GuidedActionsController.qml(L149-L150):
// Note: The '_visualItemsCount - 2' is a hack to not trigger resume mission when a mission ends with an RTL item
property bool showResumeMission: _activeVehicle && !_vehicleArmed && _vehicleWasFlying &&
_missionAvailable && _resumeMissionIndex > 0 &&
(_resumeMissionIndex < _visualItemsCount - 2)
由此可以推断出对话框不显示的可能原因,排查时可以逐条对照:
| 判定条件 | 含义 | 不满足的典型情形 |
|---|---|---|
_activeVehicle |
有激活载具 | 通信丢失,communicationLost 同时会让按钮区域隐藏 |
!_vehicleArmed |
载具已上锁 | 载具仍处于解锁状态(如落地未 disarm) |
_vehicleWasFlying |
载具“曾经”飞起过 | 该标志在 on_VehicleFlyingChanged 中由 flying=false 时置位(L332-L339),用于确保只有真正飞过又落地才触发恢复 |
_missionAvailable |
计划中存在航点项 | 车辆端已无任务项(containsItems 为 false) |
_resumeMissionIndex > 0 |
恢复索引有效 | 飞行中 lastCurrentIndex 未被正确跟踪 |
_resumeMissionIndex < _visualItemsCount - 2 |
未临近任务末尾 | 注释中说明:这是为了避免“任务以 RTL 项结束时误触发恢复” |
3.2 resumeMissionIndex 是怎么算出来的
_resumeMissionIndex 绑定到 C++ 侧的 MissionController::resumeMissionIndex(L1735-L1751):
int MissionController::resumeMissionIndex(void) const
{
int resumeIndex = 0;
if (_flyView) {
resumeIndex = _missionManager->lastCurrentIndex() +
(_controllerVehicle->firmwarePlugin()->sendHomePositionToVehicle() ? 0 : 1);
if (resumeIndex > 1 && resumeIndex != _visualItems->value<VisualMissionItem*>(_visualItems->count() - 1)->sequenceNumber()) {
// Resume at the item previous to the item we were heading towards
resumeIndex--;
} else {
resumeIndex = 0;
}
}
return resumeIndex;
}
这里有两个关键点:
lastCurrentIndex的来源:它由 MissionManager 在解析MISSION_CURRENT消息时更新。源码显示(L243-L284),为避免 HEARTBEAT 与 MISSION_CURRENT 的信号时序问题,_lastCurrentIndex的更新会先缓存(_cachedLastCurrentIndex),待下一次 heartbeat 后统一提交并触发lastCurrentIndexChanged信号。遥测日志(第 2 节第 3 步要求开启)正是用来核对这段“载具报告飞到了哪个航点”的原始数据。sendHomePositionToVehicle()的差异:APM 固件插件返回true(Home 位置作为 seq 0 上传给载具,见 APMFirmwarePlugin.h L54),PX4 默认基类返回false(FirmwarePlugin.h L306,PX4 在 PX4FirmwarePlugin.cc L192 有单独实现)。这决定了恢复索引是否要额外偏移 1——不同固件下同一现象可能对应不同的 index 计算路径。
信号链完整走向为:MissionManager::lastCurrentIndexChanged → MissionController::resumeMissionIndexChanged(MissionController.cc L1657 连接)→ QML 的 on_ResumeMissionIndexChanged 打印 _resumeMissionIndex 并参与 showResumeMission 重算。
四、故障 B:恢复任务(Resume Mission Generation)不正确
对于 _Resume Mission 生成_问题,在完成通用步骤后,继续执行:
- 点击 Resume Mission;
- 此时应生成新的任务;
- 进入 Plan View;
- 从 File/Sync 菜单中选择 Download;
- 将 Modified Plan 保存为文件;
- 将 App Log 保存为文件;
- 将 App Log、Telemetry Log、Original Plan 和 Modified Plan 四个文件放到可在 issue 中链接的位置;
- 创建 issue,附上详细信息和全部 四个 文件的链接。
4.1 源码级原理:generateResumeMission 如何重建任务
点击 Resume Mission 后,QML 侧执行 missionController.resumeMission(missionController.resumeMissionIndex)(GuidedActionsController.qml L578-L581),最终进入 MissionManager::generateResumeMission(L71-L211)。其算法可概括为以下几步,理解这些步骤有助于判断“重建结果为何与原计划有出入”:
第 1 步:拒绝含 MAV_CMD_DO_JUMP 的计划(L82-L88)
for (int i=0; i<_missionItems.count(); i++) {
MissionItem* item = _missionItems[i];
if (item->command() == MAV_CMD_DO_JUMP) {
QGC::showAppMessage(tr("Unable to generate resume mission due to MAV_CMD_DO_JUMP command."));
return;
}
}
若计划中含 DO_JUMP,会直接弹出提示并放弃生成——这是“点了 Resume 却没新任务”的一种正常分支。
第 2 步:把恢复索引回退到“基于位置”的命令(L93-L106):如果选中的恢复项不是坐标类命令(如相机指令),则向前回退到载具实际会飞过的最后一个位置型航点。
第 3 步:挑选进入新任务的命令(L108-L142)。核心规则是:原计划中位于 resumeIndex 之后的所有航点都会保留;此外,以下“前缀型”命令即使出现在恢复点之前,也会被重新放到任务开头,并统计进 prefixCommandCount:
includedResumeCommands << MAV_CMD_DO_CONTROL_VIDEO
<< MAV_CMD_DO_SET_ROI
<< MAV_CMD_DO_DIGICAM_CONFIGURE
<< MAV_CMD_DO_DIGICAM_CONTROL
<< MAV_CMD_DO_MOUNT_CONFIGURE
<< MAV_CMD_DO_MOUNT_CONTROL
<< MAV_CMD_DO_SET_CAM_TRIGG_DIST
<< MAV_CMD_DO_FENCE_ENABLE
<< MAV_CMD_IMAGE_START_CAPTURE
<< MAV_CMD_IMAGE_STOP_CAPTURE
<< MAV_CMD_VIDEO_START_CAPTURE
<< MAV_CMD_VIDEO_STOP_CAPTURE
<< MAV_CMD_DO_CHANGE_SPEED
<< MAV_CMD_SET_CAMERA_MODE;
| 命令 | 作用 |
|---|---|
MAV_CMD_DO_CONTROL_VIDEO |
视频流控制 |
MAV_CMD_DO_SET_ROI |
设置感兴趣区域 |
MAV_CMD_DO_DIGICAM_CONFIGURE / MAV_CMD_DO_DIGICAM_CONTROL |
相机配置/控制 |
MAV_CMD_DO_MOUNT_CONFIGURE / MAV_CMD_DO_MOUNT_CONTROL |
云台配置/控制 |
MAV_CMD_DO_SET_CAM_TRIGG_DIST |
相机距离触发 |
MAV_CMD_DO_FENCE_ENABLE |
地理围栏开关 |
MAV_CMD_IMAGE_START/STOP_CAPTURE、MAV_CMD_VIDEO_START/STOP_CAPTURE |
拍照/录像启停 |
MAV_CMD_DO_CHANGE_SPEED |
改变速度 |
MAV_CMD_SET_CAMERA_MODE |
设置相机模式 |
第 4 步:对前缀命令去重、剔除无操作项(L145-L194)。规则包括:SET_CAMERA_MODE 与 DO_SET_ROI 只保留最后一个;DO_SET_CAM_TRIGG_DIST、IMAGE/VIDEO_STOP_CAPTURE、VIDEO_START_CAPTURE 只保留第一个;而 IMAGE_START_CAPTURE 只有在 param3 != 0(按时间触发)时才被移除、否则同样只保留第一个。这正是“相机指令重建不正确”类问题最集中的逻辑——若你在 Modified Plan 中发现相机命令数量、顺序或位置与预期不符,优先对照这一步的取舍规则。
第 5 步:重排序号、标记当前项并上传(L196-L211)。重新从 0 开始编号,若固件需要上传 Home 位置(addHomePosition)则 seq 1 为第一个飞行项并标记为 current;随后将 _resumeMission 置位并调用 _writeMissionItemsWorker() 上传。
上传结果的处理在 PlanManager::_finishTransaction(L809-L867):
if (_resumeMission) {
_resumeMission = false;
if (success) {
emit resumeMissionReady();
} else {
emit resumeMissionUploadFail();
}
}
上传失败时,QGC 会弹出 "Resume FAILED / Upload of resume mission failed. Confirm to retry upload" 确认框(GuidedActionsController.qml L36、L63、L459-L463 与 Connections L350-L353),确认后以同样的 index 重试一次上传。
五、提 issue 前的信息清单速查
| 故障类型 | 必须提供的文件 | 数量 |
|---|---|---|
| Resume Mission 对话框问题 | App Log、Telemetry Log、Plan File(原始计划) | 3 个 |
| Resume Mission 生成问题 | App Log、Telemetry Log、Original Plan、Modified Plan(Resume 后 Download 的计划) | 4 个 |
通用前提:重启 QGC → 开启 QMLControls.GuidedActionsController 控制台日志类别 → 开启遥测日志(Settings > General)→ 完整执行“开始任务 → 飞行至换电池/手动 RTL → 降落上锁”的复现路径。
六、小结与延伸入口
Resume Mission 的行为由“QML 判定层(showResumeMission)+ C++ 索引层(resumeMissionIndex / lastCurrentIndex)+ 重建上传层(generateResumeMission)”三层串联而成,任何一层的时序或条件异常都会表现为文档所述的两大类故障。排查时建议按本文顺序:先确认对话框判定现场(App Log 中的 _outputState 输出),再用遥测日志核对 MISSION_CURRENT 轨迹,最后在 Modified Plan 中比对前缀命令去重规则。
相关仓库入口:
- GuidedActionsController.qml:引导动作显示/执行逻辑与日志输出;
- FlyViewMissionCompleteDialog.qml:任务结束对话框及 Resume 按钮;
- MissionController.cc:
resumeMissionIndex计算与信号桥接; - MissionManager.cc:
generateResumeMission重建算法; - PlanManager.cc:上传事务完成后的
resumeMissionReady/resumeMissionUploadFail分发; - Console Logging 文档:日志类别与
--logging命令行用法; - General 设置文档:遥测日志(Save log after each flight 等)配置。