MAVROS 使用说明

本文说明本项目将 DJI PSDK 能力转换为 MAVLink 后，在 MAVROS 中通常如何查看、控制和理解这些数据。

• PSDK 侧输出的 MAVLink 数据在 MAVROS 中对应哪些 topic 或服务。
• MAVROS 可以通过哪些入口发送位置、速度、姿态、航点、相机和录像相关命令。
• 哪些能力已经在当前项目代码中有对应的 MAVLink 处理。
• 哪些 topic 名称可能受 MAVROS 版本、插件配置和命名空间影响。

1. 系统链路

当前项目的典型链路如下：

DJI PSDK / M4TD
  -> 项目内 MAVLink 转换模块
  -> UDP 14550
  -> MAVROS
  -> ROS2 topic / service

如果 PSDK 程序和 MAVROS 都运行在妙算 3 本机，常见配置为：

PSDK MAVLink 目标：127.0.0.1:14550
MAVROS 监听地址：udp://:14550@

如果 MAVROS 运行在另一台设备上，PSDK 目标地址不能使用 127.0.0.1，应改为 MAVROS 所在设备的实际 IP。

2. MAVROS 启动示例

ros2 run mavros mavros_node \
  --ros-args \
  -r __ns:=/mavros \
  -p "fcu_url:=udp://:14550@" \
  -p "target_system_id:=3" \
  -p "target_component_id:=1" \
  -p "fcu_protocol:=v2.0"

参数说明：

如果项目中修改了 system_id、component_id 或 camera component id，MAVROS 和其它地面站也应按相同 ID 配置或识别。

3. 快速查看方式

建议优先查看与功能直接相关的 topic，而不是只依赖完整的 ros2 topic list。

ros2 topic echo /mavros/state
ros2 topic echo /mavros/imu/data
ros2 topic echo /mavros/global_position/global
ros2 topic echo /mavros/local_position/pose
ros2 topic echo /mavros/battery
ros2 topic echo /mavros/rc/in

按类别查找扩展 topic：

ros2 topic list | grep -E "setpoint|local_position|global_position|imu|battery|rc"
ros2 topic list | grep -E "camera|image|video|storage|mount|gimbal"
ros2 topic list | grep -E "mission|home|geofence|fence"
ros2 topic list | grep -E "distance|range|obstacle"
ros2 topic list | grep -E "debug|statustext|param"

不同 MAVROS 版本和插件配置会导致 topic 名称略有差异。文档中的 topic 名称以常见 MAVROS 命名为准，现场应以实际 ros2 topic list 输出为准。

4. 飞行器状态与遥测显示

5. 姿态、IMU、本地位置

6. GPS、全局位置与 Home 点

7. 电池、遥控器、动力与避障

如果 MAVROS 日志出现：

DS: Plugin not configured!

表示 MAVLink 距离类消息可能已经进入 MAVROS，但 MAVROS 的 distance_sensor 插件尚未配置，因此不会按预期发布距离 topic。

8. MAVROS 位置、速度和姿态控制

本项目不仅输出遥测，也接收 MAVROS 发送的控制 setpoint。代码中已经处理以下 MAVLink 输入：

项目也会将收到的 setpoint 进行 MAVLink 回显：

8.1 使用条件

位置、速度和姿态 setpoint 类控制通常需要满足以下条件：

• 飞行器已进入项目支持的外部控制或 Offboard 类模式。
• MAVROS 持续发布 setpoint，频率不能过低。
• 项目内 setpoint rate checker 认为输入有效。
• 飞行器当前状态允许 PSDK 控制，例如未处于飞控接管的返航、低电量降落、失控保护等状态。
• 若启用地理围栏或安全区域判断，目标点需要位于允许区域内。

8.2 本地速度控制示例

MAVROS ROS2 中常见消息类型为 mavros_msgs/msg/PositionTarget。下面示例表达“只控制本地 NED 速度，不控制位置和加速度”：

ros2 topic pub /mavros/setpoint_raw/local mavros_msgs/msg/PositionTarget "{
  header: {frame_id: 'map'},
  coordinate_frame: 1,
  type_mask: 3527,
  velocity: {x: 1.0, y: 0.0, z: 0.0},
  yaw_rate: 0.0
}"

说明：

• coordinate_frame: 1 常见含义为 FRAME_LOCAL_NED。
• type_mask 用于指定忽略哪些字段。不同控制需求应按 MAVROS/MAVLink 常量组合。
• NED 坐标中 z 方向向下，使用时要注意与 ROS ENU 坐标的方向差异。

8.3 本地位置控制示例

ros2 topic pub /mavros/setpoint_raw/local mavros_msgs/msg/PositionTarget "{
  header: {frame_id: 'map'},
  coordinate_frame: 1,
  type_mask: 3576,
  position: {x: 2.0, y: 0.0, z: -1.5},
  yaw: 0.0
}"

说明：

• 示例表达本地 NED 目标位置。
• z: -1.5 表示相对本地坐标向上 1.5 m。
• 实际飞行速度、加减速和到点行为由项目飞控控制逻辑和 DJI 飞控接口共同决定。

8.4 全球位置控制

全球位置控制通过 /mavros/setpoint_raw/global 进入，MAVLink 对应 SET_POSITION_TARGET_GLOBAL_INT。常见用途是按经纬度和高度发送目标点。

MAVROS 常见消息类型为 mavros_msgs/msg/GlobalPositionTarget，字段包括：

• latitude
• longitude
• altitude
• velocity
• acceleration_or_force
• yaw
• yaw_rate
• type_mask
• coordinate_frame

项目接收后会保存为 global setpoint，并可回显到 /mavros/setpoint_raw/target_global。

8.5 姿态目标控制

姿态目标通过 /mavros/setpoint_raw/attitude 进入，MAVLink 对应 SET_ATTITUDE_TARGET。项目代码中已有解码、缓存、频率检测和目标回显。

需要注意：

• DJI 飞控可开放的姿态控制能力和 PX4 Offboard 不完全一致。
• 当前项目中更建议优先使用位置/速度 setpoint 做无人机移动控制。
• 姿态目标适合做高级控制接口预留或特定场景调试，使用前需要确认飞行模式和安全条件。

9. 起飞、降落、返航、任务与模式

MAVROS 可通过 command 或 mode 相关服务发送标准 MAVLink 命令。项目代码中已处理多种常用命令：

任务状态输出：

10. 云台、相机、拍照、录像与视频

当前项目代码中已经处理了多类相机和云台 MAVLink 能力。

10.1 云台控制与状态

10.2 相机信息与状态

说明：

• MAVROS 对 camera/video/storage topic 的支持依赖版本和插件配置。
• 如果 topic 名称不同，请使用 ros2 topic list | grep -E "camera|image|video|storage" 查找实际名称。
• VIDEO_STREAM_INFORMATION 只是视频流元信息，真正的 H264/RTP/UDP 视频流不一定通过 MAVROS 转发。

10.3 切换拍照和录像模式

项目已处理：

MAV_CMD_SET_CAMERA_MODE 的关键参数：

10.4 拍照

项目已处理两类拍照命令：

单张拍照示例：

ros2 service call /mavros/cmd/command mavros_msgs/srv/CommandLong "{
  broadcast: false,
  command: 2000,
  confirmation: 0,
  param1: 0.0,
  param2: 0.0,
  param3: 1.0,
  param4: 1.0,
  param5: .nan,
  param6: .nan,
  param7: .nan
}"

说明：

• param3: 1.0 表示拍 1 张。
• param4 可作为 capture sequence number。
• 命令成功后，可观察 camera capture/status、camera trigger、image captured 相关 topic。

10.5 开始录像与停止录像

项目已处理：

开始录像示例：

ros2 service call /mavros/cmd/command mavros_msgs/srv/CommandLong "{
  broadcast: false,
  command: 2500,
  confirmation: 0,
  param1: 0.0,
  param2: 1.0,
  param3: .nan,
  param4: .nan,
  param5: .nan,
  param6: .nan,
  param7: .nan
}"

停止录像示例：

ros2 service call /mavros/cmd/command mavros_msgs/srv/CommandLong "{
  broadcast: false,
  command: 2501,
  confirmation: 0,
  param1: 0.0,
  param2: .nan,
  param3: .nan,
  param4: .nan,
  param5: .nan,
  param6: .nan,
  param7: .nan
}"

10.6 请求相机状态消息

项目已处理 MAV_CMD_REQUEST_MESSAGE，可请求以下消息：

请求示例：

ros2 service call /mavros/cmd/command mavros_msgs/srv/CommandLong "{
  broadcast: false,
  command: 512,
  confirmation: 0,
  param1: 262.0,
  param2: 0.0,
  param3: 0.0,
  param4: 0.0,
  param5: 0.0,
  param6: 0.0,
  param7: 0.0
}"

其中 command: 512 为 MAV_CMD_REQUEST_MESSAGE，param1 为请求的 MAVLink message id。

11. 参数、日志、调试与扩展消息

面向客户说明时，建议优先使用标准 MAVROS topic 和服务表达功能；DEBUG、NAMED_VALUE_* 更适合作为工程辅助信息。

12. 常见现象说明

12.1 /mavros/state 已连接，但某些 topic 不存在

可能原因：

• MAVROS 对应插件未启用。
• 当前 MAVROS 版本未发布该 topic。
• 项目只在特定设备状态下发送该类 MAVLink 消息。
• camera、gimbal、distance、video 等扩展 topic 名称与文档示例不同。

建议先按关键字搜索：

ros2 topic list | grep -E "camera|image|video|storage"
ros2 topic list | grep -E "mount|gimbal"
ros2 topic list | grep -E "distance|range|obstacle"
ros2 topic list | grep -E "setpoint|target"

12.2 setpoint 已发布，但无人机没有动作

可能原因：

• 当前模式不是项目支持的 Offboard/外部控制模式。
• setpoint 频率过低，被 rate checker 判定为无效。
• 飞控处于返航、低电量降落、失控保护等安全接管状态。
• 目标点不在允许区域内。
• type_mask 配置不符合预期，导致位置或速度字段被忽略。
• 坐标系理解错误，例如 ROS ENU 与 MAVLink NED 的方向差异。

12.3 相机命令有 ACK，但 MAVROS 中看不到相机 topic

可能原因：

• MAVROS camera 插件或当前版本不发布对应 topic。
• 相机状态只通过 COMMAND_ACK、CAMERA_CAPTURE_STATUS 或 CAMERA_IMAGE_CAPTURED 返回。
• 需要主动发送 MAV_CMD_REQUEST_MESSAGE 请求某些状态消息。
• 相机 component id 与 MAVROS/地面站识别的 component 不一致。

12.4 视频流与 MAVROS 的关系

VIDEO_STREAM_INFORMATION 可以通过 MAVLink/MAVROS 表达视频流元信息，但实际 H264/RTP/UDP 视频流通常直接由项目推送到指定 IP/端口，不一定经过 MAVROS topic。

如果 MAVROS 中能看到视频流信息，但播放器或 QGC 无画面，应检查：

• 视频目标 IP 是否为接收端实际 IP。
• UDP/RTP 端口是否一致。
• 防火墙是否允许 UDP。
• QGC 或播放器视频协议是否与项目输出一致。
• PSDK Liveview 是否成功启动。

13. 推荐给用户展示的 MAVROS 入口