- 无人机
- 智能硬件
【免费下载链接】qgroundcontrol
Cross-platform ground control station for drones (Android, iOS, Mac OS, Linux, Windows)
QGroundControl（QGC）为 ArduPilot 固件机型提供独立的Failsafes（失效保护）配置页面，用于在电池电量耗尽、地面站链路丢失、RC 油门信号丢失、EKF 导航估计失效等关键系统故障时自动触发安全动作（RTL、Land、Hold 等）。本文以官方文档 failsafes.md 为主体，结合仓库中驱动该页面的 JSON 配置与 C++/QML 实现，逐项讲解每个失效保护的可用选项、对应 ArduPilot 参数及数值含义，帮助你在飞机、多旋翼、地面车与潜水艇等不同机型上完成安全、正确的失效保护配置。
Failsafes 页面：入口、机型适配与实现骨架
在 QGC 中打开Setup（设置）视图 → Failsafes，即可进入该页面。从源码结构看，该页面由 APMFailsafesComponent.cc 承载：它继承自VehicleComponent，组件名为Failsafes，图标为SafetyComponentIcon.png，并且allowSetupWhileArmed与allowSetupWhileFlying均为true——也就是说，即使飞行器已解锁或正在飞行，你依然可以查看和修改失效保护配置。
该组件最关键的机制是按机型返回不同的页面内容描述与配置数据源：
- 潜水艇（Submarine）：
Configure failsafe actions and leak detection.（失效保护动作与漏水检测） - 地面车（Ground Rover）：
Configure battery, GCS, throttle, and EKF failsafes. - 固定翼（Fixed Wing）：
Configure battery, GCS, and throttle failsafes. - 多旋翼等其他机型：
Configure battery, GCS, RC, throttle, EKF, and dead reckoning failsafes.
页面的实际控件并非手写 QML，而是由一份 JSON 数据文件驱动自动生成：
src/AutoPilotPlugins/APM/VehicleConfig/APMFailsafes.VehicleConfig.json该文件通过vehicleConfigJson()返回（:/qml/QGroundControl/AutoPilotPlugins/APM/VehicleConfig/APMFailsafes.VehicleConfig.json），定义了所有失效保护节的标题、关键字、显示条件（showWhen）、参数绑定与控件类型。setupSource()则根据机型把用户导向APMFailsafesComponent.qml或APMNotSupported.qml（不支持的机型显示"不支持"提示）。理解这份 JSON，就理解了整个 Failsafes 页面的全部可选项——下文每一节的参数细节均可在其中逐条核对。
电池失效保护（Battery Failsafe）
电池失效保护是逐块电池独立配置的：若飞行器挂载了多块电池，每一块都可以拥有自己独立的低电量/临界电量动作与阈值。
可配置项
| 配置项 | 对应 ArduPilot 参数 | 说明 |
|---|---|---|
| 低电量动作（Low action） | BATT_FS_LOW_ACT | 电池到达低电量等级时执行的动作（RTL / Land / SmartRTL 等） |
| 临界电量动作（Critical action） | BATT_FS_CRT_ACT | 电池到达临界电量等级时执行的动作 |
| 低电压阈值（Low voltage threshold） | BATT_LOW_VOLT | 触发低电量动作的电压值（伏特） |
| 临界电压阈值（Critical voltage threshold） | BATT_CRT_VOLT | 触发临界电量动作的电压值（伏特） |
| 低容量阈值（Low mAh threshold） | BATT_LOW_MAH | 触发低电量动作的剩余容量（mAh） |
| 临界容量阈值（Critical mAh threshold） | BATT_CRT_MAH | 触发临界电量动作的剩余容量（mAh） |
多电池支持与前置条件
在 JSON 配置中，电池节使用了"repeat"机制：
"repeat": { "paramPrefix": "BATT", "probePostfix": "MONITOR", "indexing": "apm_battery", "enableParam": "MONITOR", "disabledParamValue": "_monitorParamValueDisabled" }它通过probePostfix: "MONITOR"（即探测BATT_MONITOR、BATT2_MONITOR……）来发现哪些电池槽位存在且被启用，参数名由BATT_前缀派生。QML 侧的 APMBatteryParams.qml 提供了与之一致的命名规则：
- 第 1 块电池：
BATT_ - 第 2～9 块电池：
BATT2_、BATT3_、……、BATT9_ - 第 10～16 块电池：
BATTA_、BATTB_、……、BATTG_
关键前提：只有对应电池的BATT_MONITOR参数不为 0（启用了电池监控）时，该电池的失效保护选项才会显示出来（_monitorParamValueDisabled: 0）。因此，如果页面上看不到某块电池的配置，请先检查BATT_MONITOR是否已启用。另外，FS_LOW_ACT、FS_CRT_ACT、LOW_VOLT、CRT_VOLT、LOW_MAH、CRT_MAH这些控件都标记为"optional": true，并且用showWhen判断参数是否存在——只有固件确实提供对应参数时才显示，保证了对不同 ArduPilot 版本/机型的兼容。
在 APMFailsafesComponentSummary.qml 摘要视图中，会分别显示Batt1 low failsafe、Batt1 critical failsafe、Batt2 low failsafe、Batt2 critical failsafe的当前动作值（通过BATT_FS_LOW_ACT/BATT_FS_CRT_ACT的枚举字符串呈现），便于在页面之外快速核对状态。
地面站失效保护（Ground Station Failsafe）
当地面站（GCS）与飞控之间丢失心跳（heartbeat）超过设定时间时触发。不同机型对该失效保护的配置差异较大。
多旋翼（Copter）
多旋翼的地面站失效保护由FS_GCS_ENABLE控制，启用开关写回的动作值为_copterGcsParamValueRtl（即 1），关闭写回 0。主要配置项：
- 启用（Enabled）：
FS_GCS_ENABLE切换开关 - 超时（Timeout）：
FS_GCS_TIMEOUT，无心跳持续该时间后触发（单位为秒） - 动作（Action）：单选组，可选值与
FS_GCS_ENABLE参数数值对应如下：
| 界面选项 | FS_GCS_ENABLE 数值 |
|---|---|
| RTL | 1 |
| Land | 5 |
| SmartRTL or RTL | 3 |
| SmartRTL or Land | 4 |
| Auto DO_LAND_START or RTL | 6 |
| Brake or Land | 7 |
- 忽略条件（Ignore failsafe if）：基于
FS_OPTIONS位掩码，多旋翼提供两项：- In Auto mode（
bitMask: 2）：处于 Auto 模式时忽略该失效保护 - In pilot control（
bitMask: 16）：飞行员手动操控时忽略
- In Auto mode（
固定翼（Plane）
固定翼使用FS_GCS_ENABL参数（注意 ArduPilot 参数名只有 5 个字符"ENABL"，与多旋翼的FS_GCS_ENABLE不同），配置的是**触发方式（Trigger）**而非动作：
| 界面选项 | FS_GCS_ENABL 数值 |
|---|---|
| Heartbeat（仅心跳丢失） | 1 |
| Heartbeat and Remote RSSI（心跳丢失且遥测 RSSI 过低） | 2 |
| Heartbeat and AUTO（心跳丢失且处于 AUTO 模式） | 3 |
启用开关写回_planeGcsParamValueHeartbeat（1），关闭写回 0。与多旋翼相比，固定翼的触发方式更强调"链路质量"这一维度。
地面车（Rover）
地面车使用FS_GCS_ENABLE，但取值语义与多旋翼不同：
- 启用（Enabled）：写回
_roverFsParamValueEnabled（1） - In Auto mode 忽略：切换为
_roverFsParamValueEnabledIgnoreAuto（2），即在 Auto 模式下不触发 - In Hold mode 忽略：
FS_OPTIONS的bitMask: 1 - Timeout：
FS_GCS_TIMEOUT
油门失效保护（Throttle Failsafe）
当 RC 接收机的油门通道信号丢失时触发，配置随机型差异很大。
多旋翼（Copter）
- Throttle Failsafe 启用：
FS_THR_ENABLE。启用写回_copterThrParamValueRtl（1），关闭写回 0 - PWM 阈值：
FS_THR_VALUE，油门 PWM 低于该值视为信号丢失 - 动作（Action）：单选组，
FS_THR_ENABLE取值：
| 界面选项 | FS_THR_ENABLE 数值 |
|---|---|
| Always RTL | 1 |
| Always Land | 3 |
| Always SmartRTL or RTL | 4 |
| Always SmartRTL or Land | 5 |
| Auto DO_LAND_START or RTL | 6 |
| Always Brake or Land | 7 |
- 忽略条件（Ignore failsafe if）：
FS_OPTIONS位掩码——In Auto mode（bit 1）、In Guided mode（bit 4）、Landing（bit 8，正在降落时忽略）
另外多旋翼还有独立的RC Failsafe节，界面直接标注"Always enabled"（RC 失效保护始终启用），仅提供上述FS_OPTIONS的三个忽略位：In Auto mode（bit 1）、In Guided mode（bit 4）、Landing（bit 8）。
地面车（Rover）
- 启用：
FS_THR_ENABLE，启用写回_roverFsParamValueEnabled（1） - PWM 阈值：
FS_THR_VALUE - 超时：
FS_TIMEOUT - 动作（Action）：
FS_ACTION单选组：
| 界面选项 | FS_ACTION 数值 |
|---|---|
| Nothing（无动作） | 0 |
| RTL | 1 |
| Hold | 2 |
| SmartRTL or RTL | 3 |
| SmartRTL or Hold | 4 |
| Terminate（终止，断开电机/舵机供电） | 5 |
| Loiter or Hold | 6 |
- 忽略条件：In Auto mode（切换
FS_THR_ENABLE为 2，即 Enabled Ignore Auto）、In Hold mode（FS_OPTIONSbit 1）
固定翼（Plane）
固定翼的油门失效保护拆分为"触发"与"短/长失效保护"两级：
- Throttle PWM threshold 启用：
THR_FAILSAFE，启用写回 1，关闭写回 0 - PWM 阈值：
THR_FS_VALUE - 短失效保护动作（Short failsafe action）：
FS_SHORT_ACTN - 长失效保护动作（Long failsafe action）：
FS_LONG_ACTN - 长失效保护超时（Long failsafe timeout）：
FS_LONG_TIMEOUT - VTOL 转换失败动作：
Q_TRANS_FAIL_ACT（仅在存在Q_TRANS_FAIL参数时显示，即 VTOL 机型） - VTOL 转换失败超时：
Q_TRANS_FAIL
EKF 失效保护（EKF Failsafe）
当扩展卡尔曼滤波器（EKF）对位置/速度的估计方差超出阈值、导航估计变得不可靠时触发。
多旋翼（Copter）
- 启用：
FS_EKF_ACTION，启用写回_copterEkfParamValueLandIfPosRequired（1），关闭写回 0 - 阈值（Threshold）：
FS_EKF_THRESH，EKF 方差达到该值即触发 - 动作（Action）：
| 界面选项 | FS_EKF_ACTION 数值 |
|---|---|
| Land if position required（需要位置时降落） | 1 |
| AltHold if position required（需要位置时切 AltHold） | 2 |
| Land from all modes（所有模式下均降落） | 3 |
- 忽略条件：
FS_OPTIONS的Landing位（bit 8）
地面车（Rover）
- 启用：
FS_EKF_ACTION，启用写回_roverEkfParamValueHold（1） - 阈值：
FS_EKF_THRESH - 动作（Action）：
| 界面选项 | FS_EKF_ACTION 数值 |
|---|---|
| Hold（保持） | 1 |
| Report only（仅上报，不执行动作） | 2 |
其他失效保护（Other Failsafes）
依据机型不同，Failsafes 页面还会提供以下附加失效保护。
航位推算失效保护（Dead Reckoning，多旋翼）
当 GPS 丢失后，飞控转入航位推算（Dead Reckoning）维持位置估计，若该状态持续过久则触发。仅在存在FS_DR_ENABLE参数且为多旋翼时显示：
- 启用：
FS_DR_ENABLE，启用写回_drParamValueLand（1），关闭写回 0 - 超时（Timeout）：
FS_DR_TIMEOUT - 动作（Action）：
| 界面选项 | FS_DR_ENABLE 数值 |
|---|---|
| Land | 1 |
| RTL | 2 |
| SmartRTL or RTL | 3 |
| SmartRTL or Land | 4 |
| Auto Land/Return or RTL | 6 |
- 忽略条件：
FS_OPTIONS的Landing位（bit 8）
撞击检测（Crash Check）
- 多旋翼：
FS_CRASH_CHECK复选框，检测并响应飞行器坠毁 - 地面车：
FS_CRASH_CHECK切换开关 + 动作单选组：
| 界面选项 | FS_CRASH_CHECK 数值 |
|---|---|
| Hold（保持） | 1 |
| Hold and Disarm（保持并解锁/断电） | 2 |
振动检测（Vibration，多旋翼）
FS_VIBE_ENABLE复选框，检测过度振动并触发失效保护。
抓取器联动（Gripper，多旋翼）
FS_OPTIONS的Release gripper on any failsafe（bit 32）：任意失效保护触发时释放挂载的抓取器。
潜水艇专用（Submarine）
潜水艇的摘要视图由 APMFailsafesComponentSummarySub.qml 呈现，包含地面站（GCS）、漏水（Leak）、电池（Battery）、EKF、飞行员输入（Pilot Input）、内部温度（Int. Temperature）、内部压力（Int. Pressure）等失效保护的当前状态。对应参数为：
- 漏水检测（Leak Detection）：
FS_LEAK_ENABLE（引脚与逻辑电平配置见潜水艇相关设置） - 内部温度失效保护：
FS_TEMP_ENABLE - 内部压力失效保护：
FS_PRESS_ENABLE - 飞行员输入失效保护：
FS_PILOT_INPUT
值得注意的是，SummarySub 中通过_firmware34判断固件版本：globals.activeVehicle.versionCompare(3, 5, 0) < 0时视为旧固件，此时不显示电池、EKF、Pilot Input 三项（界面标注 "Firmware not supported"）。这提醒我们：失效保护选项的可用性同时受机型与固件版本双重约束。
实现机制：JSON 驱动的失效保护面板如何工作
整个 Failsafes 页面的底层逻辑可以用三块拼图概括：
JSON 定义界面：
APMFailsafes.VehicleConfig.json通过constants（数值常量，如上面各表格中的动作值）、params（界面标识符 → 真实参数名的映射，例如_copterGcsEnable: "FS_GCS_ENABLE"、_planeThrFailsafe: "THR_FAILSAFE"、_roverFsAction: "FS_ACTION"）、bindings（例如"_copterGcsEnabled": "_copterGcsEnable && _copterGcsEnable.rawValue !== 0"，用于驱动开关状态）以及sections（各配置节及其showWhen机型条件、控件与bitMask）完成界面生成。JSON 中"启用/关闭"本质上是向飞控参数写回特定数值（如onChecked: "_copterGcsEnable.rawValue = _copterGcsParamValueRtl"），与 ArduPilot 的参数语义一一对应。C++ 组件装配：APMFailsafesComponent.cc 负责按
MAV_TYPE_*机型分发页面与描述，同时提供iconResource（/qmlimages/SafetyComponentIcon.png）并在 Setup 视图中注册为无需强制 setup 的组件（requiresSetup() == false、setupComplete() == true）。QML 摘要视图：APMFailsafesComponentSummary.qml 为多旋翼/固定翼/地面车显示 Throttle failsafe、Rover 的
FS_ACTION/FS_CRASH_CHECK、以及 Batt1/Batt2 的 low/critical 状态；潜水艇则使用 SummarySub 版本。两者都通过controller.getParameterFact(-1, "<参数名>", false /* reportMissing */)读取参数，参数不存在时安全返回空值。
配置建议与注意事项
- 先确认电池监控已启用：电池失效保护的参数只有在
BATT_MONITOR非 0 时才会出现在页面上，若需要配置电池保护，请先完成电池监控设置。 - 机型差异是常态：同一失效保护在不同机型的参数名、取值语义都可能不同——例如固定翼的 GCS 参数是
FS_GCS_ENABL且配置的是"触发方式"而非"动作"；地面车的FS_GCS_ENABLE取值 2 表示"Auto 模式下忽略"。切换机型后务必重新逐项核对。 - FS_OPTIONS 位掩码的复用：同一个
FS_OPTIONS参数在不同节中承载不同含义的位（bit 1/2/4/8/16/32 分别对应 Auto/Guided/Landing/pilot control/gripper 等场景），修改任意失效保护时注意不要覆盖其他节的位设置。 - 固件版本限制：如潜水艇摘要所示，部分失效保护选项需要较新的固件（如 3.5 及以上）才会暴露，配置前应确认 ArduPilot 固件版本。
- 动作选择宜保守：RTL、Land、Hold 是相对安全的默认选择；
Terminate（地面车）与Brake等动作会带来更强制的物理后果，仅在明确理解其行为后使用。相关飞行安全（RTL 高度、地理围栏、解锁检查）可在同一 Setup 视图下的 Flight Safety 页面 中进一步配置。
总结
QGroundControl 的 Failsafes 页面为 ArduPilot 全机型提供了一套"所见即所得"的失效保护配置入口：电池、地面站、油门/RC、EKF 四大核心失效保护覆盖了绝大多数安全场景，航位推算、撞击检测、振动、抓取器联动与潜水艇专用项则补齐了特定机型的特殊需求。通过 APMFailsafes.VehicleConfig.json 这份 JSON，你可以精确追溯到界面每一个开关、单选按钮背后实际写入的 ArduPilot 参数与数值；结合机型、固件版本与FS_OPTIONS位掩码的约束，即可为你的飞行器构建一套完整、可预期、可维护的自动安全机制。
- 无人机
- 智能硬件
【免费下载链接】qgroundcontrol
Cross-platform ground control station for drones (Android, iOS, Mac OS, Linux, Windows)
相关推荐
ArduPilot在QGroundControl中的高级设置指南：从参数调优到安全配置
ArduPilot在QGroundControl中的高级设置指南：从参数调优到安全配置 QGroundControl 作为一款跨平台的无人机地面站软件，为 Ar
无人机智能硬件QGroundControl ArduPilot 日志设置页详解：LOG_* 参数配置指南
QGroundControl ArduPilot 日志设置页详解：LOG_ 参数配置指南 本文以 QGroundControl（QGC）中 ArduPilot
无人机智能硬件QGroundControl 调参（Tuning）完全指南：PX4 与 ArduPilot 的 PID 调参、自动调参与源码实现解析
QGroundControl 调参（Tuning）完全指南：PX4 与 ArduPilot 的 PID 调参、自动调参与源码实现解析 QGroundContro
无人机智能硬件
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
