Magpie360-5S 开发者手册

本手册介绍 Magpie360-5S 的设备连接、飞行控制、传感器数据、激光定位及投放装置接口，面向具备 Linux、ROS 和基础编程知识的开发者。

术语约定：

• 上位机：飞机搭载的板载计算机，型号为 Jetson Orin NANO / NX。
• 飞控：PX6C，负责姿态稳定、飞行状态管理和底层执行。
• 开发电脑：用于 SSH、编辑程序、查看日志或运行地面站的电脑。
• 投放装置下位机：分电板上的控制单片机。
• 设定值（setpoint）：应用程序发送给飞控的期望位置、速度或其他控制量。

除明确标注“开发电脑”外，命令均在上位机的 Bash 终端执行。文中的文件位置使用上位机上的绝对路径，样例代码按文件名索引。

1. 平台概览

1.1 产品定位与开发能力

Magpie360-5S 的应用程序运行在上位机上，通过 ROS 与飞控、传感器和投放装置通信。主要开发方向包括：

本平台主要提供 ROS 接口和应用示例，开发者通过订阅 Topic、发布设定值、调用 Service 和配置 Launch/YAML 实现功能。

1.2 硬件组成与接口总览

1.3 软件架构与数据流

应用给飞控发送期望值，飞控负责底层控制。

vision_pose 只是 MAVROS 的接口名称，输入可以来自激光定位。

---

2. 设备连接与网络配置

图中设备外形参考 Livox MID-360 官方产品图和 Pixhawk 6C 官方资料。分电板以结构框表示，框内展示 USB Hub、USB 转串口芯片和下位机的内部连接。

2.1 飞控 USB 连接与通信配置

PX6C 通过飞控上的 4-pin USB 接口连接分电板内置 USB Hub 的一个下游端口。Hub 的上游通过分电板引出的 USB-A 接头接入上位机的 USB Type-A 口，上位机枚举出的飞控设备为 /dev/ttyACM0。

lsusb
ls -l /dev/ttyACM0

如果遇到权限问题，可将当前用户加入dialout组：

sudo usermod -aG dialout "$USER"

随后重新登录。不要长期使用 chmod 777 或以 root 运行整套 ROS 来绕过权限问题。

/home/jetson/catkin_ws/src/tutorials/tutorial_basic/launch/mavros.launch包含的配置为：

<launch>
  <include file="$(find mavros)/launch/px4.launch">
    <arg name="fcu_url" value="/dev/ttyACM0:57600"/>
  </include>
</launch>

启动入口：

roslaunch tutorial_basic mavros.launch

也可使用 MAVROS 自身的入口指定连接 URL，选择其中一个入口启动：

roslaunch mavros px4.launch fcu_url:=/dev/ttyACM0:57600

注意：/home/jetson/catkin_ws/src/tutorials/tutorial_basic/launch/mavros.launch 没有暴露可覆盖的 fcu_url 参数。需要更换设备路径时，使用上面的 MAVROS 入口，或在自有 Launch 中明确配置。

读取连接状态：

rostopic echo -n 1 /mavros/state

预期有 connected: True，表示 MAVROS 已经连接上飞控。

2.2 MID-360 / MID-360s 直连与局域网配置

激光雷达通过网线直连上位机以太网口。雷达与上位机使用同一 IPv4 子网内的不同地址。

2.2.1 地址规划

随无人机附带的launch文件使用上位机地址 192.168.1.5、雷达地址 192.168.1.1xx。

2.2.2 配置 Livox 驱动

驱动包位置可通过以下命令查询：

rospack find livox_ros_driver2

配置文件为 /home/jetson/ros_libraries_ws/src/livox_ros_driver2/config/MID360_config.json，也可能为 /home/jetson/ros_libraries_ws/src/livox_ros_driver2/config/MID360s_config.json，取决于飞机所配备的雷达型号。当前随附配置采用以下字段：

对当前单网卡直连配置，前四个地址与上位机雷达网口一致。端口沿用配套驱动配置中的值。不同驱动版本的配置结构可能不同，字段名称以对应型号的配置文件为准。

/home/jetson/ros_libraries_ws/src/livox_ros_driver2/launch_ROS1/msg_MID360.launch 内部通过 user_config_path 参数选择配置文件，没有暴露同名 Launch 参数。修改配置后重启驱动。

2.3 投放装置连接

分电板内置 USB Hub 的另一个下游端口通过板内 USB 走线连接 CH340 USB 转串口芯片，CH340 再通过板内串口走线与 ATmega328P 下位机通信。下位机通过 PWM 控制投放装置舵机。

投放装置与飞控共用分电板引出的 USB-A 上游连接。官方配置中，CH340 对应 /dev/ttyUSB0，飞控对应 /dev/ttyACM0。投放装置的 ROS 接口见 6.3 节。

多个 USB 串口的编号可能随枚举顺序变化。设备身份可通过 /dev/serial/by-id/ 或已有的 udev 别名区分。

2.4 工作区与软件包位置

工作区环境加载顺序：

source /opt/ros/noetic/setup.bash
source /home/jetson/ros_libraries_ws/devel/setup.bash
source /home/jetson/catkin_ws/devel/setup.bash

---

3. 基础服务与状态读取

3.1 启动基础服务

各终端加载 2.4 节的工作区环境后，分别启动以下服务。已由系统启动的服务沿用现有实例。

终端 A：ROS Master。

roscore

终端 B：飞控通信。

roslaunch tutorial_basic mavros.launch

终端 C：雷达驱动。

roslaunch livox_ros_driver2 msg_MID360.launch

上述入口对应 MID-360；MID-360s 的入口及其加载的 JSON 按交付驱动配置选择。

终端 D：激光定位。

roslaunch tutorial_navigation mapping_mid360.launch rviz:=false

此入口会加载 /home/jetson/catkin_ws/src/tutorials/tutorial_navigation/config/mid360.yaml，启动 fast_lio 包中的 fastlio_mapping，节点名为 /laserMapping。

终端 E：外部位姿转发。

rosrun tutorial_navigation odom_forward_node

该节点默认订阅 Odometry，发布到 mavros/vision_pose/pose，接口与参数见 7.3 节。

3.2 读取飞机与传感器状态

rosnode list
rostopic echo -n 1 /mavros/state
rostopic hz /livox/lidar
rostopic hz /livox/imu

位姿数据：

rostopic echo -n 1 /Odometry/header
rostopic echo -n 1 /Odometry/pose/pose
rostopic echo -n 1 /mavros/vision_pose/pose/header
rostopic echo -n 1 /mavros/local_position/pose

查看点云可运行 rviz，添加 PointCloud2 显示，选择 /cloud_registered。Fixed Frame 使用该消息的 header.frame_id，当前 FAST-LIO 输出为 camera_init。

3.3 基础飞行中的接口分工

起飞、悬停和降落流程涉及以下接口：

对应示例文件为 /home/jetson/catkin_ws/src/tutorials/tutorial_basic/src/takeoff_node.cpp。该文件使用速度接口执行起飞、悬停和下降，并调用模式与解锁服务。完整接口定义见第 5 章。

---

4. 开发基础约定

4.1 坐标系、单位与姿态表示

对 ROS 1 MAVROS 常规局部位置/速度接口，应用侧使用 ROS 坐标约定，由插件进行 ENU/NED 转换。原始设定值接口的转换行为见 5.4 节。

4.2 时间与频率

传感器采样、点云打包、里程计更新和控制发送分别具有自己的频率。多路数据的时间对应关系由设备时钟、驱动时间戳及同步配置共同决定。

4.3 命名空间与 TF 约定

本文以单机、根命名空间为例，例如 /mavros/state。ROS 名称区分大小写，/Odometry 与 /odometry 不相同。ROS 相对名称受节点命名空间影响。

当前相关帧名：

FAST-LIO 发布动态变换 camera_init → body。/home/jetson/catkin_ws/src/tutorials/tutorial_navigation/launch/mid360.launch 中配置了 map → odom → camera_init 和 body → base_link 的单位静态变换，表示这些帧在该配置下重合。

header.frame_id 是帧标签；坐标转换需要同时计算位置和姿态。当前位姿转发节点的字段处理方式见 7.3 节。

4.4 参数与配置位置

/home/jetson/catkin_ws/src/tutorials/tutorial_basic/launch/run_vel_control.launch 中的节点名是 takeoff_node，其 hover_x 等私有参数位于该节点名下。

/home/jetson/catkin_ws/src/tutorials/tutorial_basic/launch/mavros.launch 包含 MAVROS 的 px4.launch，未显式加载 /home/jetson/catkin_ws/src/tutorials/tutorial_basic/config/px4_config.yaml。运行配置由实际 Launch 包含关系决定。

---

5. 飞行控制接口参考

5.1 接口总览与样例文件

下表方向以应用程序为参照。“样例文件”列给出使用该接口的代表性文件；完整文件位置列在表后。

样例文件位置：

以上只索引接口的使用文件，不展开任务程序的内部流程。

5.2 状态与遥测

/mavros/state

消息类型：mavros_msgs/State。

样例文件：takeoff_node.cpp、vel_control_node.cpp、circle_node.cpp、fly_path.py。

局部位姿与速度

• header.stamp 是数据时间戳，header.frame_id 描述参考帧。
• PoseStamped.pose.position 单位为 m，姿态为四元数。
• Odometry 的位姿参考 header.frame_id，速度参考 child_frame_id。
• TwistStamped.twist.linear 单位为 m/s，twist.angular 单位为 rad/s。

vel_control_node.cpp 使用 /mavros/local_position/pose 获取当前位置，并依据位置误差计算速度设定值。

电池与着陆状态

BatteryState.voltage 单位为 V；若有有效的 percentage，其范围通常为 0～1。

/mavros/extended_state 使用 mavros_msgs/ExtendedState，其中 landed_state 表示飞控报告的着陆状态。

5.3 模式切换与解锁/上锁

使用自定义模式字符串时，常见请求为 base_mode=0、custom_mode="OFFBOARD"。降落模式字符串为 AUTO.LAND。

mode_sent 描述模式请求的发送结果；模式生效状态通过 State.mode 读取。解锁服务返回请求结果，当前解锁状态通过 State.armed 读取。

样例文件：takeoff_node.cpp、vel_control_node.cpp、circle_node.cpp、fly_path.py。

5.4 位置、速度与航向控制

局部位置接口

/mavros/setpoint_position/local 使用 geometry_msgs/PoseStamped：

• position.x/y/z：局部参考下的位置，单位 m。
• orientation：包含期望航向的有效四元数。纯偏航角 ψ 可写为 (0, 0, sin(ψ/2), cos(ψ/2))。
• header.stamp：当前时间，随设定值更新。

该接口用于位置与航向控制。应用提供已经处于对应参考帧下的数据，header.frame_id 仅为消息帧标签。

样例文件：fly_path.py。

局部速度接口

/mavros/setpoint_velocity/cmd_vel 使用 geometry_msgs/TwistStamped：

ROS 1 MAVROS 的速度插件根据 setpoint_velocity/mav_frame 选择局部或机体解释方式。在默认局部配置下，输入为 ROS ENU，插件转为飞控所需格式。插件实现参考 MAVROS 速度插件。

运行参数位置：

rosparam get /mavros/setpoint_velocity/mav_frame

例如，设置 linear.z=0.4 表示沿当前局部参考的 Z 正方向发送 0.4 m/s 速度目标；设置 angular.z=0.2 表示发送 0.2 rad/s 的偏航角速度目标。

样例文件：takeoff_node.cpp、vel_control_node.cpp、circle_node.cpp。

原始局部设定值接口

/mavros/setpoint_raw/local 使用 mavros_msgs/PositionTarget：

type_mask=0 表示相关字段均未被掩码忽略。组合设定值时按所需控制量设置掩码。

ROS 1 MAVROS 在局部回调中执行对应的 ENU/NED 转换，具体行为见 MAVROS 原始设定值插件。

样例文件：ego_planner_gate.py。

5.5 OFFBOARD 控制流程

PX4 OFFBOARD 文档给出的模式进入条件包括：进入模式前持续提供设定值至少约 1 秒，运行期间保持高于 2 Hz 的控制存活信号。当前基础 C++ 示例采用 20 Hz 控制循环。

图中的 mode 和 armed 均为 /mavros/state 消息的字段。模式和解锁请求分别通过 /mavros/set_mode 与 /mavros/cmd/arming 发送，位置或速度目标通过对应设定值 Topic 持续发布。

---

6. 传感器与投放装置接口

6.1 MID-360 / MID-360s：点云与 IMU

随附 MID-360 驱动入口的主要配置如下；MID-360s 使用其配套入口和型号配置文件。

主要数据接口：

CustomMsg 的主要字段：

CustomPoint 中的 x/y/z 单位为 m，reflectivity 为 0～255 的反射强度，另包含 offset_time、tag、line。逐点时间信息用于运动去畸变等处理。

IMU 的角速度单位为 rad/s，加速度单位为 m/s²；姿态字段及协方差的含义由驱动输出定义。

标准点云转换入口：

rosrun tutorial_navigation custom_to_pc2.py

对应文件为 /home/jetson/catkin_ws/src/tutorials/tutorial_navigation/scripts/custom_to_pc2.py。它把 /livox/lidar 转为 /livox/pointcloud2，类型为 sensor_msgs/PointCloud2。

该脚本保留 Header，不进行坐标变换或去畸变；默认输出 XYZ 和 uint8 类型的强度，逐点时间、tag 和 line 默认不输出。当前 FAST-LIO 配置使用原始 CustomMsg。

6.2 标定与同步参数

FAST-LIO 配置中的 mapping/extrinsic_T、mapping/extrinsic_R 描述算法使用的雷达—IMU 关系；body 与 base_link 的关系描述估计主体与机体的关系。对应配置见 4.3 和 7.2 节。

6.3 投放装置：控制原理与接口简介

投放装置通过分电板上的 ATmega328P 控制舵机，CH340 提供 USB 转串口，并通过板内走线连接分电板内置的 USB Hub。Hub 的上游由分电板引出的 USB-A 接头接入上位机。官方配置使用 /dev/ttyUSB0，通过 rosserial 将上下位机连接到 ROS。

catapult_driver 把舵机角度封装为仓门开关命令，启动时执行初始化及关门动作：

roslaunch tutorial_catapult catapult_driver.launch

常用接口均为 std_msgs/Empty：

发送一次左前仓门开启命令：

rostopic pub -1 /servo/front_left/open std_msgs/Empty '{}'

驱动文件为 /home/jetson/catkin_ws/src/tutorials/tutorial_catapult/src/catapult_driver.cpp，启动配置为 /home/jetson/catkin_ws/src/tutorials/tutorial_catapult/launch/catapult_driver.launch。当前开关命令采用 Topic 发布方式，无服务响应或机械到位反馈。

方向、行程、详细驱动配置及下位机烧录步骤见《投放装置控制原理与软件（Jetson Orin Nano/NX）》。

---

7. 激光定位与建图

7.1 定位链路与数据接口

FAST-LIO 产生局部运动估计和点云地图；转发节点将位姿适配到 MAVROS 输入；飞控估计器融合外部测量，并通过 MAVROS 输出局部状态。

7.2 MID-360 与 FAST-LIO

当前应用配置位于 /home/jetson/catkin_ws/src/tutorials/tutorial_navigation/config/mid360.yaml。

主要输出：

地图保存由 pcd_save/pcd_save_en 和 pcd_save/interval 控制，具体保存位置由所安装 FAST-LIO 版本定义。

样例使用文件：odom_forward_node.cpp 订阅 /Odometry；其上位机位置为 /home/jetson/catkin_ws/src/tutorials/tutorial_navigation/src/odom_forward_node.cpp。

7.3 外部定位接入飞控

/home/jetson/catkin_ws/src/tutorials/tutorial_navigation/src/odom_forward_node.cpp 的接口为：

在根命名空间下，输入和输出分别为 /Odometry 与 /mavros/vision_pose/pose。

该节点只转发 Header 和位姿字段，不执行坐标变换，也不转发原始 Odometry 的速度与协方差。输出的原点、朝向和时间语义沿用输入数据，frame_id 参数用于替换帧标签。

飞控通过 MAVROS 接收外部位姿，并按其估计器配置进行融合。融合后的局部位姿从 /mavros/local_position/pose 读取，局部里程计从 /mavros/local_position/odom 读取。