RflyRosStart 接口文档

简介

简述：该文件提供RflyRosStart类，用于创建适配RflySim平台的ROS通信连接实例，支持通过飞机ID或自定义通信端口号两种方式完成通信初始化配置。

在RflySim无人机仿真开发中，基于ROS的第三方功能开发、外部节点与仿真机端无人机的通信交互需要统一规范的通信入口。该模块负责完成通信实例的初始化配置，适配了平台的通信规则，既支持开发者直接通过飞机ID快速建立与指定仿真无人机的通信链路，也支持自定义端口号灵活配置非标准的通信场景，适用于二次开发、ROS节点拓展、自定义外部控制交互等开发场景。

快速开始

以下示例发现 1 号 CopterSim 的地址，将通信模式切换为 MAVLink Full，然后创建 RflyRosStart。构造函数会自动启动 MAVROS，不需要再次调用 InitRosLoop()。

参考例程：[RflySim安装路径]\RflySimAPIs\6.RflySimExtCtrl\0.ApiExps\e18_MavrosExps

import sys

import ReqCopterSim
import RflyRosStart


req = ReqCopterSim.ReqCopterSim()
targetID = 1
targetIP = req.getSimIpID(targetID)
if targetIP == "":
    print("无法获取 CopterSim 地址:", targetID)
    sys.exit(0)

if not (RflyRosStart.isLinux and RflyRosStart.isRosOk):
    print("当前环境未检测到可用的 ROS")
    sys.exit(0)

req.sendReSimIP(targetID)
req.sendReSimUdpMode(targetID, 2)
ros = RflyRosStart.RflyRosStart(targetID, targetIP)

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：ctrl.IpManager、math、os、platform、psutil、pymavlink、socket、struct、subprocess、sys、threading、time
• 前置准备：调用此接口前，必须先完成RflySimSDK的环境配置并导入对应模块。

核心接口说明

该模块 RflyRosStart.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量

无

---

全局/独立函数

无

---

RflyRosStart 类

创建用于RflySim平台与ROS环境通信的实例，支持UDP、串口直连飞控、UDP直连等多种连接模式，可适配仿真和真机连接场景。

__init__(ID=1, ip=127.0.0.1, Com=udp, port=0, simulinkDLL=False)

功能说明：初始化RflyRosStart通信实例，根据输入参数配置不同的连接模式和通信参数 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
ID	int	否	1	若ID≤10000表示无人机的CopterID号；若ID>10000表示通信端口号port，兼容旧接口规则：port=20100+CopterID*2-2
ip	str	否	127.0.0.1	数据发送目标IP地址，默认本机地址；分布式仿真可指定局域网IP，也可使用广播地址255.255.255.255
Com	str	否	'udp'	与Pixhawk的连接模式：udp表示接收CopterSim转发的MAVLink消息；串口地址（如Windows下COM3、Linux下/dev/ttyUSB0）表示USB/数传直连飞控；Direct表示UDP直连模式，同一端口收发数据
port	int	否	0	UDP模式下设为0会自动根据CopterID计算端口，赋值大于0则强制使用指定端口；串口模式下表示波特率，0对应默认57600；Direct模式下表示收发端口号；redis模式下对应服务器端口，0对应默认6379
simulinkDLL	bool	否	False	是否为Simulink生成的DLL模式，适配Simulink联合仿真场景

返回值 (Returns)：

• RflyRosStart 实例对象

异常 (Raises)：

• 无

---

InitRosLoop()

功能说明：初始化ROS通信循环，启动MAVLink数据接收与ROS节点相关进程 参数列表 (Args)： 无 返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

# 初始化仿真UDP模式通信，启动ROS循环
ros_comm = RflyRosStart(ID=1)
ros_comm.InitRosLoop()

---

KillMavRos()

功能说明：终止MAVLink与ROS相关进程，关闭通信连接 参数列表 (Args)： 无 返回值 (Returns)：

• 无

异常 (Raises)：

• 无

---

EndRosLoop()

功能说明：结束ROS通信循环，清理通信相关资源 参数列表 (Args)： 无 返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

# 串口连接真机，初始化并结束通信
ros_comm = RflyRosStart(ID=1, Com='COM3', port=57600)
ros_comm.InitRosLoop()
# 业务逻辑处理后结束通信
ros_comm.EndRosLoop()

---

进阶用法示例

RflyRosStart 会管理 MAVROS 子进程。以下示例在远程 CopterSim 场景中启动连接，并在任务结束时显式停止 ROS 循环。

参考例程：[RflySim安装路径]\RflySimAPIs\6.RflySimExtCtrl\0.ApiExps\e18_MavrosExps

import time

import ReqCopterSim
import RflyRosStart


targetID = 1
req = ReqCopterSim.ReqCopterSim()
targetIP = req.getSimIpID(targetID)

req.sendReSimIP(targetID)
req.sendReSimUdpMode(targetID, 2)

ros = RflyRosStart.RflyRosStart(
    ID=targetID,
    ip=targetIP,
    Com="udp",
    port=0,
    simulinkDLL=False,
)

try:
    print("MAVROS 已启动")
    time.sleep(30)
finally:
    ros.EndRosLoop()

注意事项与避坑指南

• InitRosLoop调用顺序要求：该方法需要在RflySim仿真环境启动、PX4飞控进程启动完成后再调用，提前调用会导致无法连接飞控，直接抛出节点启动失败异常。
• MavRos节点资源释放：调用KillMavRos关闭单个无人机的MavRos节点后，才可以调用EndRosLoop终止整个ROS循环，未关闭的节点会残留为系统后台进程，占用端口与内存资源。
• 多无人机场景ID正确性：InitRosLoop与KillMavRos的传入参数必须与无人机实际ID严格对应，错配ID会导致错误关闭其他无人机的节点，引发整个仿真任务崩溃。
• 重复初始化资源冲突：不可对同一无人机ID重复调用InitRosLoop，重复启动会导致相同ROS端口被多个进程占用，引发节点启动失败。

更新日志

• 2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云
• 2024-11-20: 增加适配真机上的系统
• 2024-11-19: 更新多级子进程调用管理问题
• 2024-11-19: 优化mavros启动程序，主要体现进程管理方面，支持ros1，ros2 kill等
• 2024-08-14: fix:更新HTML版API
• 2024-07-18: fix:更新API主页索引
• 2024-05-19: fix: 更新
• 2024-05-15: fix: 优化初始化机制
• 2024-04-16: 修复兼容ROS1 与 ROS2 subprocess 启动mavros 子线程阻塞的问题
• 2024-03-08: 接口适配ROS2，并且修复使用subprocess 模块问题
• 2024-01-29: fix: 新增mavros的控制例子