QGroundControl 任务恢复失败排查指南:Resume Mission 对话框与任务重建的完整调试流程

原创2026-10-14 16:48:561,388 阅读
文章标签:无人机

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)

无论是对话框问题还是任务生成问题,以下通用步骤都必不可少:

  1. 重启 QGC(Restart QGC);
  2. 开启控制台日志(参考 Console Logging),并启用日志类别:QMLControls.GuidedActionsController;
  3. 启用遥测日志(Settings > General 中的“来自载具的遥测日志”一节,即 #telemetry_logs);
  4. 开始任务(Start the mission);
  5. 飞行直至需要换电池;

    提示(tip):也可以在任务中段手动执行 RTL(Return to Launch)来尝试复现问题,但这不一定总能触发故障;

  6. 一旦载具降落并上锁(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 对话框问题,在完成上述通用步骤后,继续执行:

  1. 将 App Log 保存为文件;
  2. 将 App Log、Telemetry Log、Plan File 放到可以在 issue 中给出链接的位置;
  3. 创建 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 生成_问题,在完成通用步骤后,继续执行:

  1. 点击 Resume Mission;
  2. 此时应生成新的任务;
  3. 进入 Plan View;
  4. 从 File/Sync 菜单中选择 Download;
  5. 将 Modified Plan 保存为文件;
  6. 将 App Log 保存为文件;
  7. 将 App Log、Telemetry Log、Original Plan 和 Modified Plan 四个文件放到可在 issue 中链接的位置;
  8. 创建 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 中比对前缀命令去重规则。

相关仓库入口:

登录后查看全文
qgroundcontrol