PX4-Autopilot LandingTargetPose 消息深度解析：精密着陆目标相对/绝对位姿的发布链路、字段语义与消费方

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件

本篇技术指南以 PX4-Autopilot 的 uORB 消息landing_target_pose为核心，完整解析其 19 个字段的帧系与单位语义、源消息定义（msg/LandingTargetPose.msg）、生产模块landing_target_estimator的卡尔曼滤波发布链路、相关LTEST_*参数，以及 EKF2 辅助速度融合、导航模块精密起飞（Precision Takeoff）、MAVLinkLANDING_TARGET流等消费方。读完本文，你将掌握该消息从传感器原始观测到导航级目标位姿的完整数据流，并能在实际项目中正确解读、调试与扩展精密着陆功能。

消息概览与设计意图

LandingTargetPose是 PX4 精密着陆（Precision Landing）与精密起飞（Precision Takeoff）体系中的核心 uORB 消息，其官方定义为：

Relative position of precision land target in navigation (body fixed, north aligned, NED) and inertial (world fixed, north aligned, NED) frames.

即同时携带两种坐标系下的目标描述：

• 导航坐标系（navigation frame）：目标相对飞行器的相对位置/速度，坐标轴为北（X）、东（Y）、下（Z），即 NED 对齐，方向与地磁北/航向参考一致；
• 惯性坐标系（inertial frame）：目标相对导航原点的绝对位置（x_abs/y_abs/z_abs），同样为北对齐 NED 系。

该消息的发布主题名为landing_target_pose（来自 msg/LandingTargetPose.msg 及 uORB 生成代码ORB_ID(landing_target_pose)）。其设计意图是：将机载传感器（如 IRLOCK 红外相机）或外部定位系统观测到的目标信息，经过滤波估计后，以统一的位姿/速度/协方差结构发布出来，供导航与飞行控制链路消费。

字段逐项详解

LandingTargetPose共 19 个字段，分为时间戳、状态标志、相对状态（位置/速度）、相对协方差、绝对位置五组。下表字段、类型、单位与描述与 docs/en/msg_docs/LandingTargetPose.md 完全一致：

关键字段语义澄清

• rel_vel_ekf2_valid与is_static的耦合：从 LandingTargetEstimator.cpp 的实现可见，生产方以rel_vel_ekf2_valid = is_static && rel_vel_valid的方式赋值。即只有目标被标记为静止（LTEST_MODE=1）时，相对速度才被允许用于 EKF2 辅助速度融合——因为对移动目标而言，相对速度无法直接反推机体地速；
• z_rel的语义：虽然vz_rel/cov_z_rel在消息中存在，但当前landing_target_estimator实现中z_rel直接取自传感器测距（见下文_dist_z），并未经过卡尔曼滤波，vz_rel、cov_z_rel由该模块发布时保持默认零值，主要保留给其他生产方（如视觉目标估计器）使用；
• 相对量与绝对量的关系：绝对位置 = 相对位置 + 机体本地位置（x_abs = x_rel + vehicle_local_position.x等），仅当机体本地位置xy_valid有效时abs_pos_valid才为真。

源消息定义：msg/LandingTargetPose.msg

消息的真实定义位于仓库根目录的 msg/LandingTargetPose.msg，构建时由Tools/msg/px_generate_uorb_topic_files.py生成 C/C++ 头文件与 IDL 定义。其完整内容如下：

# Relative position of precision land target in navigation (body fixed, north aligned, NED) and inertial (world fixed, north aligned, NED) frames uint64 timestamp # [us] Time since system start bool is_static # [-] Flag indicating whether the landing target is static or moving with respect to the ground bool rel_pos_valid # [-] Flag showing whether relative position is valid bool rel_vel_valid # [-] Flag showing whether relative velocity is valid bool rel_vel_ekf2_valid # [-] Flag showing whether relative velocity is valid for EKF2 auxiliary velocity aiding float32 x_rel # [m] X/north position of target, relative to vehicle (navigation frame) float32 y_rel # [m] Y/east position of target, relative to vehicle (navigation frame) float32 z_rel # [m] Z/down position of target, relative to vehicle (navigation frame) float32 vx_rel # [m/s] X/north velocity of target, relative to vehicle (navigation frame) float32 vy_rel # [m/s] Y/east velocity of target, relative to vehicle (navigation frame) float32 vz_rel # [m/s] Z/down velocity of target, relative to vehicle (navigation frame) float32 cov_x_rel # [m^2] X/north position variance float32 cov_y_rel # [m^2] Y/east position variance float32 cov_z_rel # [m^2] Z/down position variance float32 cov_vx_rel # [(m/s)^2] X/north velocity variance float32 cov_vy_rel # [(m/s)^2] Y/east velocity variance float32 cov_vz_rel # [(m/s)^2] Z/down velocity variance bool abs_pos_valid # [-] Flag showing whether absolute position is valid float32 x_abs # [m] X/north position of target, relative to origin (navigation frame) float32 y_abs # [m] Y/east position of target, relative to origin (navigation frame) float32 z_abs # [m] Z/down position of target, relative to origin (navigation frame)

值得注意的编码细节：

• 全部数值字段使用float32：位置、速度、方差各 9 个float32字段，加上 5 个布尔标志与 1 个uint64时间戳。布尔字段在 uORB 序列化中按位打包，整套消息体积很小，适合高频发布与日志记录；
• 单位注释规范：每个字段的# [unit]注释遵循 PX4 uORB 消息惯例，方差字段明确区分m^2（位置方差）与(m/s)^2（速度方差），避免歧义；
• 无 Range/Enum 约束：该消息所有字段均为自由取值，不设范围校验，因此消费方必须依赖各*_valid标志判断数据可用性。

生产方：landing_target_estimator 模块的发布链路

在默认机架配置中，landing_target_pose主要由 src/modules/landing_target_estimator 模块（landing_target_estimator）发布。该模块的类定义与实现分别在 LandingTargetEstimator.h 与 LandingTargetEstimator.cpp 中。

数据流总览

模块update()的典型执行流程如下：

1. 订阅输入（_update_topics）：订阅vehicle_local_position、vehicle_attitude、vehicle_acceleration与irlock_report（IRLOCK 红外传感器报告）；
2. 预测步：若估计器已初始化且未超时，利用机体加速度（经姿态旋转到导航系后取负）对 x/y 两个独立一维卡尔曼滤波器做时间预测；
3. 量测转换：收到新的irlock_report后，将传感器像素坐标先经LTEST_SCALE_X/Y缩放、再按LTEST_SENS_ROT旋转得到机体坐标系下的单位射线，随后用机体姿态旋转到导航系，最后按下视距离dist_bottom缩放成米制相对位置（LandingTargetEstimator.cpp）；
4. 更新步：用相对位置量测更新 x/y 两个卡尔曼滤波器，量测不确定性按LTEST_MEAS_UNC * dist_z²计算；
5. 发布：量测未被拒绝时填充并发布landing_target_pose，同时发布新息到landing_target_innovations。

关键实现细节（可直接在源码中印证）

• 超时重置机制：常量landing_target_estimator_TIMEOUT_US = 2000000（2 秒）。若在 2 秒内未收到新量测，模块打印Lost sight of Marker并重置估计器，等待下一次观测重新初始化（LandingTargetEstimator.h、LandingTargetEstimator.cpp）；
• 量测拒绝与_faulty标志：当任一轴的卡尔曼更新返回失败时，打印Landing target measurement rejected日志；只有两轴都通过才发布位姿（LandingTargetEstimator.cppL123-L182）；
• 初始化逻辑：首次观测时以rel_pos_x/rel_pos_y为位置初值、以机体地速的负值为目标速度初值（vx_init = -vehicle_local_position.vx），并用LTEST_POS_UNC_IN/LTEST_VEL_UNC_IN作为初始方差（L112-L121）；
• 绝对位置合成：在机体本地位置有效（xy_valid）时，x_abs = x_rel + local_pos.x、y_abs = y_rel + local_pos.y、z_abs = rel_pos_z + local_pos.z，并置abs_pos_valid = true；否则置 false（L168-L176）；
• is_static来源：直接取自LTEST_MODE == Stationary（L151）。

卡尔曼滤波器结构

滤波器实现位于 KalmanFilter.h 与 KalmanFilter.cpp。估计器对北向（x）与东向（y）各维护一个独立的一维常量加速度卡尔曼滤波器（状态含位置与速度），因此cov_x_rel/cov_vx_rel与cov_y_rel/cov_vy_rel分别对应两个滤波器输出的协方差，而cov_z_rel、cov_vz_rel不在该模块的滤波范围内。

相关参数：LTEST_* 系列

landing_target_estimator的全部参数定义在 src/modules/landing_target_estimator/landing_target_estimator_params.yaml 中，构建时生成到参数系统。下表完整列出：

参数影响解读：LTEST_MODE直接决定is_static与rel_vel_ekf2_valid的取值；LTEST_SENS_ROT与三个LTEST_SENS_POS_*用于将传感器安装朝向/安装位置造成的偏差在量测进入滤波器之前校正（见 LandingTargetEstimator.cpp）。在 QGroundControl 参数界面或地面站中可通过搜索前缀LTEST过滤查看。

消费方与应用场景

landing_target_pose在仓库中被多个模块订阅，构成精密着陆/起飞的完整消费链路。

1. EKF2 辅助速度融合（速度辅助定位）

src/modules/ekf2/params_aux_velocity.yaml 中定义的EKF2_AVEL_EN参数说明明确指出：

Fuse the landing-target relative velocity as auxiliary velocity … When enabled, EKF2 fuses the relative velocity published in landing_target_pose … only fused when landing_target_pose.rel_vel_ekf2_valid is true.

即当目标静止（LTEST_MODE=1）时，EKF2 可将landing_target_pose中的相对速度作为辅助速度源参与位置/速度估计，这在 GPS 受限场景（如室内、桥下）下可显著改善定位。对应实现位于 src/modules/ekf2/EKF2.cpp，相关延迟参数见EKF2_AVEL_DELAY。

2. 导航模块：精密起飞（Precision Takeoff）

src/modules/navigator/prec_takeoff.cpp 中的PrecTakeoff::update_setpoint订阅该消息，并在满足以下条件时使用其绝对位置修正起飞航点：

• 目标时间戳新鲜（now - timestamp < kTargetTimeoutUs）；
• abs_pos_valid为真且x_abs/y_abs为有限值；
• 目标时间戳晚于本地坐标系原点重置时间（ref_timestamp），且机体位置处于全球坐标系有效状态（xy_global）。

满足条件后，模块将x_abs/y_abs通过_map_ref.reproject反投影为经纬度航点，使飞行器在垂直起飞后保持于着陆坪上方。与之配合的参数为MIS_TKO_PREC、MIS_TKO_PREC_DLY（见 docs/en/advanced_features/precland.md）。

3. MAVLink 外发：LANDING_TARGET 流

src/modules/mavlink/streams/LANDING_TARGET.hpp 定义了MavlinkStreamLandingTarget流，将landing_target_pose的timestamp/x_rel/y_rel/z_rel/rel_pos_valid映射为 MAVLinkLANDING_TARGET消息（MAV_FRAME_LOCAL_NED），供地面站、外部定位系统或 GCS 可视化使用。反向地，外部系统也可通过 MAVLink 注入目标信息（见 src/modules/mavlink/mavlink_receiver.cpp）。

4. 视觉目标估计器（Vision Target Estimator）

src/modules/vision_target_estimator/Position/VTEPosition.h 同样会发布landing_target_pose，用于为视觉目标（ArUco 码、着陆坪图案等）提供滤波后的位姿。它发布的is_static等标志语义与 landing_target_estimator 一致，两类生产方可通过uORB多发布者机制并存，具体选用取决于机架配置（相关说明见 docs/en/advanced_features/vision_target_estimator_advanced.md）。

5. 日志与回放

src/modules/logger/logged_topics.cpp 将landing_target_pose列入默认/可配置日志主题，飞行日志（.ulg）中可直接检索该主题进行事后分析；src/modules/replay/ReplayEkf2.cpp 在回放模式下也会消费该主题，用于复现 EKF2 的辅助速度融合行为。

在精密着陆工作流中的位置

按 docs/en/advanced_features/precland.md 的描述，精密着陆支持多旋翼在静止或移动目标上降落，目标可由机载 IR 传感器+信标或外部定位系统提供。landing_target_pose在此工作流中的角色是目标信息在传感器与导航/控制之间的统一接口：

• 水平接近阶段：导航模块消费相对位置x_rel/y_rel判断目标是否进入水平收敛半径（PLD_HACC_RAD）；
• 目标上方下降与最终进近阶段：持续消费相对位置维持机体居中于目标上方（PLD_FAPPR_ALT以下进入最终进近）；
• 目标丢失处理：若 2 秒内无新位姿（对应估计器超时重置与导航侧kTargetTimeoutUs），精密着陆退化为搜索流程（PLD_SRCH_ALT/PLD_SRCH_TOUT）或常规降落；
• 偏航对齐：可选地通过vte_orientation（另一 uORB 消息）将机体偏航对齐目标朝向，相关参数PLD_YAW_EN、VTE_EN、VTE_YAW_EN见 docs/en/advanced_features/vision_target_estimator_advanced.md。

调试与观测建议

• 实时观测：在 SITL 或真机上运行landing_target_estimator后，可用listener landing_target_pose（PX4 控制台/NSH 命令）实时打印消息字段，重点观察rel_pos_valid、is_static、abs_pos_valid与x_rel/y_rel是否随目标移动合理变化；
• 日志分析：使用 Flight Review 或ulog工具打开.ulg文件中的landing_target_pose主题，对比x_rel与机体本地位置可验证绝对位置合成是否正确（x_abs ≈ x_rel + local_pos.x）；
• 参数排查顺序：若位姿长期无效，依次检查LTEST_SENS_ROT（安装朝向）、LTEST_SCALE_X/Y（像素缩放）、LTEST_SENS_POS_*（安装偏移）是否与实际安装一致，并确认LTEST_MODE与目标运动状态匹配（移动目标用 0，静止目标用 1 才能启用 EKF2 辅助速度）；
• MAVLink 验证：通过地面站查看LANDING_TARGET消息是否持续刷新，可确认从landing_target_pose到外发链路的映射是否正常。

综上，LandingTargetPose虽然只是一条 uORB 消息，但它贯穿 PX4 精密着陆的感知—估计—导航—控制全链路：生产方 landing_target_estimator 负责将传感器原始观测滤波为导航级位姿，消费方则覆盖 EKF2 辅助速度、精密起飞航点修正、MAVLink 外发与日志回放。理解其字段语义与发布/订阅关系，是二次开发精密着陆或自定义目标检测模块的第一步。

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件