QGroundControl ArduPilot 飞控 Failsafes 安全失效保护配置全解析：从参数设置到底层实现-平芜编程栈

无人机
智能硬件

【免费下载链接】qgroundcontrol

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

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

Failsafes（失效保护）是 ArduPilot 机型在关键系统失效（电池告警、地面站失联、RC 信号丢失、导航估计异常等）时自动执行的安全动作配置页。本文以 QGroundControl（QGC）中的ArduPilot Failsafes 设置页面为核心，逐项讲解各失效保护的含义、对应固件参数、默认值，并结合源码剖析该页面的生成机制与底层实现，帮助你在首次飞行前正确配置并理解每一个开关背后对应的 ArduPilot 参数。

本文所述页面仅适用于运行 ArduPilot 固件的机型；PX4 机型的安全配置使用独立的 Safety 页面。

页面入口与适用范围

在 QGC 的Vehicle Setup（机架设置）视图中，ArduPilot 专属配置页列表中包含了 Failsafes 页，具体位置可参考 Vehicle Configuration 总览。页面侧边栏顶部提供搜索框，输入failsafe、voltage、mah、heartbeat、pwm、ekf等关键词即可快速定位本页内的设置项——这些关键词正是由页面定义文件中的keywords字段提供的。

该页面“可用选项随机型不同而变化”，其根本原因在源码中体现得很直接：APMFailsafesComponent::description()和setupSource()根据_vehicle->vehicleType()（MAV_TYPE_*）返回不同的描述文本与界面，见 APMFailsafesComponent.cc：

机型类型	页面描述
Submarine（潜水艇）	配置失效保护动作与漏水检测
Ground Rover（地面车）	配置电池、GCS、油门、EKF 失效保护
Fixed Wing（固定翼）	配置电池、GCS、油门失效保护
多旋翼（Copter/Hexa/Octo 等）	配置电池、GCS、RC、油门、EKF、Dead Reckoning 失效保护

此外，APMFailsafesComponent还声明了两个实用的特性（见 APMFailsafesComponent.h）：allowSetupWhileArmed()与allowSetupWhileFlying()均返回true，即解锁或飞行途中也允许进入本页查看/调整设置（QGC 通常要求安全相关设置在地面完成，此页是特例）；同时requiresSetup()为false，表示本页不参与“未完成设置禁止起飞”的红标判定。

电池失效保护（Battery Failsafe）

电池失效保护是保障飞行安全最基础的一环。页面支持按电池实例分别配置——如果飞控接入了第二块电池（存在BATT2_*参数），配置项会以两组形式重复出现。

可配置项如下：

Low action（低电量动作）：电量降至低阈值时的动作（RTL / Land / SmartRTL 等组合）；
Critical action（严重低电量动作）：电量降至临界阈值时的动作；
Low/Critical voltage thresholds（低/临界电压阈值）：触发对应动作的电压值；
Low/Critical capacity thresholds（低/临界容量阈值）：触发对应动作的剩余电量（mAh）值。

对应的固件参数

页面定义文件 APMFailsafes.VehicleConfig.json 中，该区块使用repeat机制按BATT前缀自动生成两组控件：

"repeat": { "paramPrefix": "BATT", "probePostfix": "MONITOR", "indexing": "apm_battery", "enableParam": "MONITOR", "disabledParamValue": "_monitorParamValueDisabled" }

即以BATT_MONITOR（电池监控是否启用）为探测参数，只要其值不为 0，该电池的失效保护区块就会显示，且第一组使用BATT_*参数、第二组使用BATT2_*参数。具体控件的参数映射为：

页面控件	参数（电池 1）	参数（电池 2）	含义
Low action	`BATT_FS_LOW_ACT`	`BATT2_FS_LOW_ACT`	低电量触发动作
Critical action	`BATT_FS_CRT_ACT`	`BATT2_FS_CRT_ACT`	临界电量触发动作
Low voltage threshold	`BATT_LOW_VOLT`	`BATT2_LOW_VOLT`	低电压阈值（V）
Critical voltage threshold	`BATT_CRT_VOLT`	`BATT2_CRT_VOLT`	临界电压阈值（V）
Low mAh threshold	`BATT_LOW_MAH`	`BATT2_LOW_MAH`	低容量阈值（mAh）
Critical mAh threshold	`BATT_CRT_MAH`	`BATT2_CRT_MAH`	临界容量阈值（mAh）

默认值参考仓库内置参数集（Copter.OfflineEditing.params）：Copter 出厂BATT_LOW_VOLT=10.5V、BATT_CRT_VOLT=0（未启用）、BATT_LOW_MAH=0、BATT_CRT_MAH=0，且BATT_FS_LOW_ACT=0、BATT_FS_CRT_ACT=0（默认不触发动作）；Sub 机型的电压/容量阈值均为 0（见 Sub.OfflineEditing.params）。因此实际使用前必须依据电池电压平台（如 3S/4S/6S LiPo）与容量自行设定。

注意：页面仅在飞控存在BATT_MONITOR且监控已启用（值非 0）时才展示该区块；如果电池模块未配置好，相关阈值也不会生效。

地面站失效保护（Ground Station Failsafe）

当地面站与飞控之间的遥测链路（心跳 Heartbeat）中断时触发。QGC 作为 GCS 会持续向飞控发送心跳，飞控检测到心跳丢失持续超过设定时间后执行保护动作。

Copter / Rover 版本

Enabled（启用）：开关对应FS_GCS_ENABLE；
Timeout（超时）：心跳丢失后触发保护动作的等待时间，参数为FS_GCS_TIMEOUT，Copter/Rover 默认5 秒（见 Copter.OfflineEditing.params、Rover.OfflineEditing.params）；
Action（动作）：Copter 提供 RTL、Land、SmartRTL or RTL、SmartRTL or Land、Auto DO_LAND_START or RTL、Brake or Land 六个选项，分别对应FS_GCS_ENABLE的取值 1、5、3、4、6、7（常量定义见 JSON 中_copterGcsParamValue*）；
Ignore failsafe if（忽略条件）：通过FS_OPTIONS位掩码设置——Copter 可勾选“In Auto mode（位 2）”“In pilot control（位 16）”，即在这些场景下不触发；Rover 另有“In Hold mode（位 1）”选项。

Plane 版本

Plane 的 GCS 失效保护参数名是FS_GCS_ENABL（注意只有 12 个字符，这是 ArduPilot 参数名 16 字符限制下的截断命名，见 Plane.OfflineEditing.params），其“Trigger method（触发方式）”有三种：

触发方式	`FS_GCS_ENABL`取值
Heartbeat only（仅心跳）	1
Heartbeat + Remote RSSI（心跳 + 遥测 RSSI）	2
Heartbeat + AUTO（心跳 + 处于 AUTO 模式）	3

RSSI 触发要求数传模块能上报接收信号强度；AUTO 触发表示仅在自动驾驶模式下检测心跳丢失。

RC 与油门失效保护（RC / Throttle Failsafe）

Copter 的 RC Failsafe

Copter 的 RC 失效保护默认Always enabled（始终启用），页面仅显示“Ignore failsafe if”条件设置（FS_OPTIONS位掩码）：In Auto mode（位 1）、In Guided mode（位 4）、Landing（位 8）。

Copter 的 Throttle Failsafe

Enabled：对应FS_THR_ENABLE，Copter 默认开启（默认值 1）；
PWM threshold：FS_THR_VALUE，默认975（低于此 PWM 值视为信号丢失，见 Copter 参数集）；
Action：与 GCS 失效保护相同的六种动作（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：可勾选 In Auto mode（位 1）、In Guided mode（位 4）、Landing（位 8）。

Plane 的 Failsafe Triggers（失效保护触发器）

固定翼的油门失效保护参数为THR_FAILSAFE（默认 1，启用）与THR_FS_VALUE（默认950PWM）。页面还额外提供固定翼特有的短/长动作时序设置：

FS_SHORT_ACTN（Short failsafe action）：信号丢失后先执行的短期动作；
FS_LONG_ACTN（Long failsafe action）：信号持续丢失达到长超时后执行的最终动作；
FS_LONG_TIMEOUT（Long failsafe timeout）：默认5 秒；
VTOL 机型额外显示Q_TRANS_FAIL_ACT（VTOL 转换失败动作）与Q_TRANS_FAIL（转换失败超时），仅在存在Q_TRANS_FAIL参数时出现。

Rover 的 Throttle Failsafe

Rover 使用FS_THR_ENABLE（默认 1）+FS_THR_VALUE（默认910）+FS_TIMEOUT（默认1.5 秒），动作由FS_ACTION单选，取值含义：

取值	动作
0	Nothing（无动作）
1	RTL
2	Hold（保持，默认）
3	SmartRTL or RTL
4	SmartRTL or Hold
5	Terminate（终止/锁定）
6	Loiter or Hold

同时可勾选“In Auto mode（FS_ACTION置为忽略 Auto 的值 2 场景）”与“In Hold mode（FS_OPTIONS位 1）”忽略条件。

EKF 失效保护（EKF Failsafe）

当扩展卡尔曼滤波器（EKF）对位置/速度的估计方差超过阈值、导航解不再可信时触发。

Action：FS_EKF_ACTION
- Copter：Land if position required（需要位置时降落，=1，默认）、AltHold if position required（需要位置时切 AltHold，=2）、Land from all modes（任何模式都降落，=3）；
- Rover：Hold（保持，=1，默认）、Report only（仅上报，=2）；
Threshold：FS_EKF_THRESH，默认0.8（Copter/Rover 一致）；
Ignore failsafe if：Copter 可勾选 Landing（FS_OPTIONS位 8）。

其他失效保护（Other Failsafes）

Dead Reckoning（航位推算，Copter）

GPS 丢失后，飞控在短时间内继续依据惯性推算航迹，若仍无法恢复则执行动作。参数为FS_DR_ENABLE与FS_DR_TIMEOUT（默认30 秒，见 Copter 参数集）。动作选项：Land（=1）、RTL（=2）、SmartRTL or RTL（=3）、SmartRTL or Land（=4）、Auto Land/Return or RTL（=6）。该区块仅在多旋翼且飞控存在FS_DR_ENABLE参数时显示。

Crash Check（撞击检测）

Copter：FS_CRASH_CHECK复选框，默认启用（默认值 1）；
Rover：FS_CRASH_CHECK提供 Hold（=1）与 Hold and Disarm（=2，保持并解锁，默认值 0 即关闭）两种动作。

Vibration（振动检测，Copter）

FS_VIBE_ENABLE复选框，默认启用（默认值 1），用于检测过度振动。

Release gripper on any failsafe（Copter）

FS_OPTIONS位 32：任何失效保护触发时释放抓取器（gripper）。

Submarine 专用项

Sub 机型通过APMFailsafesComponentSummarySub.qml与APMFlightSafetyComponentSub.qml（见 APMFailsafesComponentSummarySub.qml、APMFlightSafetyComponentSub.qml）提供以下额外项：

Leak Detection（漏水检测）：FS_LEAK_ENABLE（默认启用）、LEAK1_PIN（检测引脚，默认 -1 即未分配）、LEAK1_LOGIC（干燥时逻辑电平，默认 0）；
Pilot Input（遥控输入）：FS_PILOT_INPUT（默认 2）+FS_PILOT_TIMEOUT（默认3 秒），注意该参数在固件 3.5 以下版本中不存在，页面通过versionCompare(3, 5, 0)判断是否显示；
Internal Temperature（内部温度）：FS_TEMP_ENABLE（默认关闭）+FS_TEMP_MAX（默认62℃）；
Internal Pressure（内部压力）：FS_PRESS_ENABLE（默认关闭）+FS_PRESS_MAX（默认105000 Pa）。

页面背后的实现机制：JSON 驱动的 QML 代码生成

QGC 4.x 之后的 ArduPilot 配置页普遍采用“声明式 JSON + 构建期代码生成”架构，Failsafes 页就是典型代表：

页面所有区块、控件、参数绑定都声明在 APMFailsafes.VehicleConfig.json 中，其中constants定义固件参数取值常量（如_copterGcsParamValueRtl: 1），params声明所需 MAVLink 参数（FS_GCS_ENABLE、THR_FAILSAFE、FS_EKF_ACTION等），bindings定义启停联动表达式，sections则按机型条件（showWhen）组织各分组；
构建时由 tools/generators/config_qml/generate_pages.py 将每个<Name>.VehicleConfig.json转换为同名*Component.qml（生成器机制详见 tools/generators/config_qml/README.md）；
APMFailsafesComponent.cc 的vehicleConfigJson()返回该 JSON 的资源路径，setupSource()返回生成的 QML 页面路径；
组件在 APMAutoPilotPlugin.cc 中被注册进 ArduPilot 插件的组件列表（_failsafesComponent = new APMFailsafesComponent(_vehicle, this)），从而出现在 Vehicle Setup 侧边栏。

这样设计的收益是：修改页面布局与参数映射只需编辑 JSON，无需改 QML，且参数名、选项取值与固件侧保持单一事实来源。

配置摘要（Summary）显示

QGC 的 Summary 页会汇总本页关键状态：APMFailsafesComponentSummary.qml 显示 Throttle failsafe（多旋翼读FS_THR_ENABLE、固定翼读THR_FAILSAFE）、Rover 的FS_ACTION与FS_CRASH_CHECK，以及 Battery 1/2 的低电量与临界电量动作；Sub 机型则通过APMFailsafesComponentSummarySub.qml汇总 GCS、Leak、Battery、EKF、Pilot Input、内部温度/压力失效保护状态。Summary 中的红字状态可帮助你在起飞前快速核对失效保护是否已全部配置到位。

配置建议与注意事项

先配置电池监控，再配置电池失效保护：确认BATT_MONITOR已启用且电压/容量阈值按电池规格设置，否则电池区块与阈值均不生效；
GCS 超时不宜过短：FS_GCS_TIMEOUT默认 5 秒，若数传链路不稳定（如飞行中频繁丢包），可适当调大，避免误触发 RTL/Land；
区分 Copter 的 RC 与 Throttle 失效保护：Copter 的 RC 失效保护始终启用，页面上的“Ignore failsafe if”与 Throttle 失效保护的忽略条件可独立配置，注意FS_OPTIONS各 bit 位含义不同（Auto=1、Guided=4、Landing=8、Pilot control=16、Hold=1、Gripper=32）；
固定翼参数名差异：Plane 的 GCS 失效保护参数是FS_GCS_ENABL（截断名），搜索参数或对照日志时不要写成FS_GCS_ENABLE；
EKF 阈值默认 0.8：若机架振动大、GPS 环境差导致 EKF 频繁告警，可结合振动失效保护与传感器校准排查根本原因，而非一味放宽阈值；
Sub 机型的漏水检测默认启用但引脚未分配（LEAK1_PIN=-1），接入漏水传感器前务必先按实际接线配置引脚与逻辑电平。