PX4 CameraTrigger uORB 消息详解：相机触发信号的定义、生成与消费链路

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

CameraTrigger 是 PX4 飞控中用于发布"相机拍摄触发事件"的核心 uORB 主题（TOPIC 名为camera_trigger），它贯穿相机触发驱动的输出、相机热靴反馈的采集以及 MAVLinkCAMERA_TRIGGER消息的下行转发。本文以 docs/en/msg_docs/CameraTrigger.md 中的消息定义为骨架，结合 camera_trigger 驱动、camera_capture 驱动、camera_feedback 模块 与 MAVLink 流 的源码实现，完整说明该消息的每个字段含义、生产/消费链路，以及航测与地理标记（geotagging）场景下的实际配置方法。

CameraTrigger 消息定义总览

消息源文件为 msg/CameraTrigger.msg，其完整定义如下：

uint64 timestamp # time since system start (microseconds) uint64 timestamp_utc # UTC timestamp uint32 seq # Image sequence number bool feedback # Trigger feedback from camera uint32 ORB_QUEUE_LENGTH = 2

消息共包含 4 个数据字段和 1 个队列长度常量，原始字段表格见 docs/en/msg_docs/CameraTrigger.md。

该消息对应的生成头文件为uORB/topics/camera_trigger.h（由构建系统从 .msg 自动生成），uORB 发布端与订阅端分别使用ORB_ID(camera_trigger)引用该主题。

ORB_QUEUE_LENGTH 常量的作用

消息定义中uint32 ORB_QUEUE_LENGTH = 2为 uORB 主题队列深度常量，表示该主题的环形发布队列最多缓存 2 条历史消息。

• 队列深度为 2 意味着即使消费者（如 camera_feedback 模块 与 MAVLink 流）处理稍慢，也仍能读到最近的两条触发事件，降低高触发频率下丢事件的概率；
• 从源码结构看，camera_trigger在定时触发（intervalometer）模式下以TRIG_INTERVAL为周期持续产生消息，较短队列深度配合快速消费端即可满足需求，避免不必要的内存占用。

谁在发布 CameraTrigger：两种生产者

从 PX4 Camera Architecture/Integration 的架构说明可以看出，CameraTrigger主题存在两类生产者，二者的区分标志正是feedback字段。

生产者一：camera_trigger 驱动（指令侧触发，feedback=false）

camera_trigger 驱动 订阅VehicleCommand主题，响应四类 MAVLink 触发命令：

• MAV_CMD_DO_TRIGGER_CONTROL（使能/暂停触发、复位序列号）
• MAV_CMD_DO_DIGICAM_CONTROL（单次拍摄）
• MAV_CMD_DO_SET_CAM_TRIGG_DIST（距离触发）
• MAV_CMD_OBLIQUE_SURVEY（倾斜摄影，CAMPOS 模式）

当按时间间隔或距离阈值判定应触发时，驱动通过engage()回调实际驱动相机接口（GPIO/PWM/Seagull/MAVLink 后端），随后发布camera_trigger消息。关键发布代码（camera_trigger.cpp）体现了几点实现细节：

// Send camera trigger message. This messages indicates that we sent // the camera trigger request. Does not guarantee capture. camera_trigger_s trigger{}; if (trig->_pps_hrt_timestamp > 0) { // Current RTC time (RTC time captured by the PPS module + elapsed time since capture) trigger.timestamp_utc = trig->_pps_rtc_timestamp + hrt_elapsed_time(&trig->_pps_hrt_timestamp); } else { // No PPS capture received, use RTC clock as fallback timespec tv{}; px4_clock_gettime(CLOCK_REALTIME, &tv); trigger.timestamp_utc = ts_to_abstime(&tv); } trigger.seq = trig->_trigger_seq; trigger.feedback = false; trigger.timestamp = hrt_absolute_time(); orb_publish(ORB_ID(camera_trigger), trig->_trigger_pub, &trigger); // increment frame count trig->_trigger_seq++;

该段代码对应的消息字段语义：

• timestamp：使用高分辨率定时器hrt_absolute_time()获取，精度可达微秒级；
• timestamp_utc：优先采用 PPS 捕获模块（pps_capture主题）提供的 RTC 基准时间加上自捕获以来的流逝时间，保证 UTC 时间与真实时刻严格对齐；未收到 PPS 时回退到CLOCK_REALTIME系统时钟；
• seq：使用驱动内部的_trigger_seq计数器，每次发布后自增；通过MAV_CMD_DO_TRIGGER_CONTROL的 param2 可复位为 0；
• feedback：恒为false，表示这是"飞控发出了触发请求"，并不保证相机确实完成了曝光。

此外，驱动还实现了快门激活时间与最小间隔的防护：engage()在距离上次触发不足TRIG_MIN_INTERVA时会直接放弃本次触发（camera_trigger.cpp），避免过快连拍压垮相机。

生产者二：camera_capture 驱动（热靴反馈侧，feedback=true）

camera_capture 驱动 监听飞控上的相机捕获引脚（捕获引脚通过将某个 AUX 输出通道功能配置为Camera_Capture（功能码 2032）来启用，见 camera_capture.cpp）。当相机热靴实际触发（边沿事件）时，该驱动发布CameraTrigger消息并将feedback置为true：

• feedback = true的消息代表"相机确认了拍摄动作"，可用于校正记录到的真实曝光时刻，从而提升地理标记（geotagging）精度；
• 该功能由CAM_CAP_FBACK参数控制开关，默认关闭。

谁在消费 CameraTrigger：MAVLink 转发、反馈与日志

MAVLink CAMERA_TRIGGER 消息下行

MAVLink 流 CAMERA_TRIGGER.hpp 订阅camera_trigger主题，并将其映射为 MAVLink 的CAMERA_TRIGGER消息对外发送。其发送逻辑（CAMERA_TRIGGER.hpp）：

/* ensure that only active trigger events are sent and ignore camera capture feedback messages*/ if (camera_trigger.timestamp > 0 && !camera_trigger.feedback) { mavlink_camera_trigger_t msg{}; msg.time_usec = camera_trigger.timestamp; msg.seq = camera_trigger.seq; mavlink_msg_camera_trigger_send_struct(_mavlink->get_channel(), &msg);

两点值得注意：

1. feedback = true的反馈消息不会被转发为CAMERA_TRIGGERMAVLink 消息，即热靴反馈仅用于飞控内部时间校正，不会与下行触发消息混淆；
2. 同一处还会向所有相机组件（MAV_COMP_ID_CAMERA起 6 个保留组件 ID）发送MAV_CMD_IMAGE_START_CAPTURE与MAV_CMD_DO_DIGICAM_CONTROL指令，实现简单 MAVLink 相机的触发协议（Camera Protocol v1）。

camera_feedback 模块：生成地理标记用的 CameraCapture

camera_feedback 模块 订阅camera_trigger主题，无论feedback为false还是true，都会结合全局位置、姿态（以及云台姿态）生成并发布CameraCapture主题（CameraFeedback.cpp），其中：

• CameraCapture.timestamp、timestamp_utc、seq直接透传自CameraTrigger；
• 额外补充纬度/经度/高度、对地距离、四元数姿态，以及result（1 表示成功）等字段，字段定义见 msg/CameraCapture.msg；
• 当CAM_CAP_FBACK >= 1时，模块会忽略feedback = false的指令侧触发，只依据真实的热靴反馈（feedback = true）生成捕获记录（CameraFeedback.cpp）。

CameraCapture会被记录到 ulog 日志（见 logged_topics.cpp 中的add_optional_topic("camera_capture")），航测完成后即可离线将照片与飞行数据对齐。

日志记录

camera_trigger与camera_capture均为可选记录主题（logged_topics.cpp），在正常飞行记录中默认包含，便于事后回放分析触发时序。

完整数据流：从命令到照片

结合 camera_architecture.md 与上述源码，CameraTrigger消息的完整生命周期如下：

1. 地面站下达命令或任务中出现相机航点 → navigator 将任务项转为VehicleCommanduORB 消息发布（参见 navigator_main.cpp 中publish_vehicle_command的实现）；
2. camera_trigger驱动订阅VehicleCommand，按TRIG_MODE（时间/距离/命令模式）计算触发时机并驱动 GPIO/PWM 等接口输出触发信号；
3. 驱动发布CameraTrigger（feedback = false）→ MAVLink 流将其转为下行CAMERA_TRIGGER消息并转发拍摄指令给相机；
4. 若启用CAM_CAP_FBACK，相机热靴触发后camera_capture驱动发布CameraTrigger（feedback = true）；
5. camera_feedback模块消费两类消息，生成带位置/姿态的CameraCapture供日志记录与地理标记。

feedback字段是区分"飞控发出触发请求"与"相机确认完成拍摄"的关键信号，也是各消费端决定是否采信、是否转发、是否生成捕获记录的核心判据。

配套配置参数与模块命令

CameraTrigger消息本身只描述事件，触发行为由 camera_trigger_params.yaml 中的TRIG_*系列参数决定（均在修改后需要重启飞控生效）：

相机反馈侧由 camera_capture_params.yaml 中的CAM_CAP_*参数控制（如CAM_CAP_FBACK启用反馈、CAM_CAP_MODE/CAM_CAP_EDGE配置捕获引脚触发方式）。

模块以标准 PX4 驱动方式启动与查询（命令入口camera_trigger_main，见 camera_trigger.cpp）：

camera_trigger start # 启动触发驱动 camera_trigger status # 打印触发使能/暂停状态、模式、间隔/距离、相机电源与激活时间 camera_trigger test # 触发一张测试图像（不记录日志、不转发给地面站） camera_trigger test_power # 切换相机电源 camera_trigger stop # 停止驱动

更多相机使用与配置说明可参考 docs/en/camera/index.md 与 fc_connected_camera.md。

小结

CameraTrigger是 PX4 相机子系统中承上启下的核心消息：timestamp与timestamp_utc提供微秒级、可对齐到 UTC 的时刻基准，seq维护连续的照片序列号，feedback则明确区分"触发请求"与"拍摄反馈"两种事件来源。理解该消息的定义与生产/消费链路，是掌握 PX4 航拍触发、相机协议转发与航测地理标记数据流的关键一步；如需深入，可直接阅读 CameraTrigger.msg、camera_trigger.cpp、CAMERA_TRIGGER.hpp 与 CameraFeedback.cpp 等源码文件。

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