PX4-Autopilot UORB 消息详解：FailureDetectorStatus 故障检测器状态消息

failure_detector_status 是 PX4-Autopilot 中由故障检测器（FailureDetector）周期性发布的 UORB 主题，用于对外报告飞行器在姿态（横滚/俯仰）、高度保持、外部触发、电池、桨叶平衡以及电机等方面的故障检测结果。本文将结合 msg/FailureDetectorStatus.msg 的消息定义，深入解读该消息的全部 12 个字段、底层检测逻辑、关联配置参数以及它在健康检查与失效保护链路中的实际作用，帮助开发者理解、消费并调试这一关键的状态消息。

消息概览：主题名与定位

该消息的 UORB 主题名为 failure_detector_status，对应结构体类型 failure_detector_status_s。它由 src/modules/commander/failure_detector/FailureDetector.cpp 中的 FailureDetector::publishStatus() 发布，被 Commander 模块、健康与上锁检查（HealthAndArmingChecks）以及飞行日志系统共同消费。

从消息定位看，它扮演两个角色：

1. 状态汇报：以一组布尔标志位向外部（MAVLink 遥测、飞行日志、DDS 桥接等）实时汇报各类故障是否被触发；
2. 失效保护输入：为 Commander 的失效保护（failsafe）决策提供输入信号（详见下文“失效保护链路”一节）。

在 src/modules/logger/logged_topics.cpp 中，该主题以 100 Hz 的速率被加入飞行日志，因此可通过 ulog 分析工具直接回放故障检测过程。

字段详解

FailureDetectorStatus 共包含 12 个字段：1 个时间戳、8 个布尔故障标志、1 个浮点度量值以及 2 个电机位掩码。原始定义见 msg/FailureDetectorStatus.msg。

名称	类型	单位	说明
timestamp	uint64	µs	自系统启动以来的时间（微秒），由 hrt_absolute_time() 写入
fd_roll	bool	—	横滚角故障标志（姿态故障：横滚）
fd_pitch	bool	—	俯仰角故障标志（姿态故障：俯仰）
fd_alt	bool	—	高度损失故障标志
fd_ext	bool	—	外部自动触发系统（ATS）触发的故障标志
fd_arm_escs	bool	—	ESC 上锁/电机故障指示（电调处于解锁状态或存在电机故障）
fd_battery	bool	—	电池相关故障标志
fd_imbalanced_prop	bool	—	桨叶不平衡检测标志
fd_motor	bool	—	关键电机故障标志（真实故障或故障注入）
imbalanced_prop_metric	float32	—	桨叶不平衡度量值（低通滤波后）
motor_failure_mask	uint16	—	电机索引位掩码，标记关键电机故障
motor_stop_mask	uint16	—	由故障注入导致的停转电机位掩码

时间戳字段 timestamp

表示该消息发布时刻距系统启动的微秒数。在 FailureDetector.cpp 中，发布时统一写入 hrt_absolute_time()，与 PX4 其他 UORB 消息的时间戳约定一致。

姿态故障标志 fd_roll 与 fd_pitch

这两个标志由 FailureDetector::updateAttitudeStatus() 计算（FailureDetector.cpp）。其核心逻辑为：

• 订阅 vehicle_attitude 主题，将姿态四元数转换为欧拉角；
• 当 |roll| 超过 FD_FAIL_R 或 |pitch| 超过 FD_FAIL_P 时判定为超限；
• 超限状态必须持续 FD_FAIL_R_TTRI / FD_FAIL_P_TTRI 秒（通过迟滞器 Hysteresis 实现）才会真正置位故障标志，避免瞬时扰动误触发；
• 参数设为 0 时对应检测被禁用（见 max_roll > FLT_EPSILON 判断）。

此外，代码对尾座式（tailsitter）飞行器做了特殊处理：过渡阶段跳过姿态检测，固定翼平飞时将姿态绕俯仰轴旋转 90° 后再比较，确保检测基准与飞行形态一致。

高度损失标志 fd_alt

由 FailureDetector::updateAltitudeStatus() 计算（FailureDetector.cpp），仅在多旋翼且高度控制使能时生效：

• 以高度设定值为基准，记录一个棘轮式（ratcheting）NED-z 参考高度：只要飞行器低于设定值，参考高度就锁定在历史最高点（即最接近设定值的位置），防止部分爬升后重新累积误差；
• 当 lpos.z - _alt_loss_ref_z 持续超过 FD_ALT_LOSS 阈值、且持续时间达到 FD_ALT_LOSS_T 时置位 fd_alt；
• 飞行器回到设定值以上后参考复位、标志清零；
• 同时处理 EKF 高度复位（z_reset）和设定值跳变，避免误触发。

该行为被一组单元测试完整覆盖，见 src/modules/commander/failure_detector/FailureDetectorAltitudeLossTest.cpp，测试用例包括禁用时不触发、设定值上方不触发、阈值内不触发、持续下降触发、部分恢复时棘轮保持、回到设定值上方复位、EKF 高度复位不触发、设定值跳变不触发等场景。

外部触发标志 fd_ext

由 FailureDetector::updateExternalAtsStatus() 计算（FailureDetector.cpp）：订阅 pwm_input 主题，当 PWM 脉宽大于等于 FD_EXT_ATS_TRIG（默认 1900 µs）且小于 3 ms 时视为外部 ATS 触发，并要求连续 5 个脉冲（50 Hz 下约 100 ms）保持该状态才置位 fd_ext。该功能由 FD_EXT_ATS_EN 参数启用，用于满足 ASTM F3322-18 对外部自动触发系统的要求。

桨叶不平衡标志 fd_imbalanced_prop 与度量 imbalanced_prop_metric

由 FailureDetector::updateImbalancedPropStatus() 计算（FailureDetector.cpp）：

• 订阅 vehicle_imu_status，定位与当前所选加速度计（sensor_selection.accel_device_id）对应的 IMU 实例；
• 取加速度方差的标准差，计算度量值 metric = (std_x + std_y) / 2 - std_z（水平与垂直方向的加速度波动对比，使用标准差而非方差以保证线性）；
• 经时间常数为 5 秒的一阶低通滤波器（AlphaFilter）平滑后写入 imbalanced_prop_metric；
• 当平滑后的度量超过 FD_IMB_PROP_THR 时置位 fd_imbalanced_prop；该参数设为 0 时整个检测关闭。

电机相关字段 fd_arm_escs、fd_motor、motor_failure_mask、motor_stop_mask

这四个字段在 publishStatus() 中统一填充（FailureDetector.cpp）：

• fd_arm_escs = esc_arm_status || (motor_failure_mask != 0)：反映 ESC 解锁状态或存在电机故障；
• fd_motor = (motor_failure_mask != 0) || (injected_motor_failure_mask != 0)：真实电机故障与故障注入（failure injection）的并集；
• motor_failure_mask：由健康检查传入的真实电机故障位掩码与注入故障掩码按位或；
• motor_stop_mask：由故障注入机制（src/lib/failure_injection）产生的停转电机位掩码，主要用于测试与调试。

其中 esc_arm_status 与 motor_failure_mask 由 FailureDetector::publishStatus() 的调用方——Commander.cpp 传入（取自已上锁检查模块），即 fd_arm_escs/fd_motor 是故障检测器与 ESC 检查模块协同的产物。

电池标志 fd_battery

fd_battery 在 publishStatus() 中直接拷贝内部标志位 flags.battery。从源码结构看，该字段预留了电池故障状态的出口，但当前 FailureDetector 内部并未在 update() 主流程中对其进行置位运算，其值与具体电池健康检查（如 battery_warning 失效保护，见 src/modules/commander/failsafe/failsafe.cpp）的联动属于可推断的扩展方向。

关联配置参数

故障检测行为完全由 FD_* 参数族控制，定义于 src/modules/commander/failure_detector/failure_detector_params.yaml，汇总如下：

参数	默认值	范围	单位	作用
FD_FAIL_R	60	0–180	deg	触发横滚故障的最大横滚角；0 禁用
FD_FAIL_P	60	0–180	deg	触发俯仰故障的最大俯仰角；0 禁用
FD_FAIL_R_TTRI	0.3	0.02–5	s	横滚超限需持续的时间
FD_FAIL_P_TTRI	0.3	0.02–5	s	俯仰超限需持续的时间
FD_EXT_ATS_EN	0	0/1	—	启用外部 ATS 的 PWM 输入（需要重启）
FD_EXT_ATS_TRIG	1900	—	µs	外部 ATS 触发的 PWM 脉宽阈值
FD_IMB_PROP_THR	30	0–1000	—	桨叶不平衡度量触发阈值；0 禁用
FD_ALT_LOSS	0.0	0.0–200.0	m	允许的最大高度损失；0 禁用
FD_ALT_LOSS_T	1.0	0.02–5.0	s	高度损失需持续的时间

值得注意的细节：

• FD_FAIL_R/FD_FAIL_P 被置 0 时，不仅检测被禁用，还会触发飞行终止或上锁（详见下节）；
• FD_ALT_LOSS 触发后飞行器会终止并展开降落伞（根据 failure_detector_params.yaml 的参数描述）；
• 参数在 FailureDetector 中通过 ModuleParams 机制注册（见 FailureDetector.hpp），运行时通过 param set 或 QGroundControl 即可调整。

下游消费：健康检查与失效保护链路

健康与上锁检查

src/modules/commander/HealthAndArmingChecks/checks/failureDetectorCheck.cpp 中的 FailureDetectorChecks::checkAndReport() 订阅 failure_detector_status，并：

• 将 fd_roll/fd_pitch/fd_ext 映射为 failsafe_flags.fd_critical_failure；
• 将 fd_alt 映射为 failsafe_flags.fd_alt_loss；
• 将 fd_imbalanced_prop 映射为 failsafe_flags.fd_imbalanced_prop，并输出 “Imbalanced propeller detected” 的 MAVLink 日志与事件；
• 对 fd_roll/fd_pitch 的汇报在校准期间（calibration_enabled）自动抑制，避免标定时误报。

失效保护动作

src/modules/commander/failsafe/failsafe.cpp 根据这些标志执行分级动作：

• 飞行中 fd_critical_failure 与 fd_alt_loss → Terminate（终止飞行），不可延迟；
• 起飞阶段两者 → Disarm（解锁断电），不可延迟；
• 地面未起飞状态 → Warn（仅警告）；
• fd_imbalanced_prop → Warn（警告），提示检查桨叶安装与损伤。

由此可见，FailureDetectorStatus 中一个 bool 标志的翻转，会直接决定飞行器是否进入终止/解锁的失效保护流程，是 PX4 安全关键链路中的核心信号之一。

调试与使用建议

1. 回放日志：由于 logged_topics.cpp 以 100 Hz 记录该主题，开发者可用 PX4 日志分析工具检查 fd_* 标志与 imbalanced_prop_metric 的时间序列，判断故障发生在哪一环节；
2. 运行单元测试：高度损失检测的边界行为可通过 make tests TESTFILTER=FailureDetectorAltitudeLossTest 运行（见 FailureDetectorAltitudeLossTest.cpp），覆盖了禁用、阈值、棘轮复位、EKF 复位等关键场景；
3. 参数调优：在 QGroundControl 参数界面搜索 FD_ 前缀即可调整所有阈值；注意 FD_EXT_ATS_EN 修改后需要重启，FD_FAIL_R/FD_FAIL_P 置 0 会禁用对应检测但同时也放弃了相关保护；
4. 消息扩展：如需新增故障类型，可修改 msg/FailureDetectorStatus.msg 并同步更新 FailureDetector 中的 failure_detector_status_u 联合体（FailureDetector.hpp）与 publishStatus() 的填充逻辑，同时保持位域顺序一致。

小结

FailureDetectorStatus 是 PX4-Autopilot 故障检测器对外输出状态的总线：8 个布尔标志覆盖姿态、高度、外部触发、电池、桨叶平衡与电机故障，两个位掩码刻画电机级故障细节，一个低通度量值提供桨叶不平衡的连续量化信息。理解它的字段语义、参数控制逻辑以及与失效保护链路的映射关系，是进行 PX4 安全逻辑开发、故障注入测试与飞行日志分析的基础。