DllSimCtrlAPIROS 接口文档¶
简介¶
简述：提供基于UDP的ROS桥接通信类，实现RflySim仿真平台与ROS系统之间的无人机控制数据互联互通。
在基于RflySim的无人机仿真开发中，很多开发者需要结合ROS生态完成路径规划、视觉感知、自主决策等上层算法开发，本模块负责打通RflySim仿真内核与ROS环境的数据交互通道。UdpRosBridge类通过UDP协议实现跨进程甚至跨设备的低延迟数据传输，支持无人机状态、控制指令等仿真数据在RflySim仿真核心和ROS节点之间双向转发，适用于基于ROS开展无人机仿真算法开发、联调测试的场景。
快速开始¶
以下示例在 ROS1 环境中为 1 号无人机启动 DLL 仿真 UDP/ROS 桥接，并在节点退出时停止桥接线程。
参考例程：[RflySim安装路径]\RflySimAPIs\6.RflySimExtCtrl\0.ApiExps\e21.RosTransExps\2.PythonDemo
import rospy
import DllSimCtrlAPIROS as dll
rospy.init_node("rflysim_dll_bridge", anonymous=True)
bridge = dll.UdpRosBridge(copter_id=1, target_ip="127.0.0.1")
bridge.start()
try:
rospy.spin()
finally:
bridge.stop()
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
DllSimCtrlAPI、ctrl.IpManager、errno、logging、math、socket、struct、sys、threading、time - 前置准备：调用此接口前，必须先正确配置RflySimSDK环境并确保可以正常调用对应动态链接库。
核心接口说明¶
该模块 DllSimCtrlAPIROS.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
| 变量名 | 类型 | 值 | 说明 |
|---|---|---|---|
ROS1 |
bool |
False |
- |
ROS2 |
bool |
False |
- |
全局/独立函数¶
无
UdpRosBridge 类¶
RflySim仿真与ROS之间的UDP通信桥接，用于实现无人机仿真数据和ROS指令的双向转发，自动根据无人机ID分配通信端口，初始化时完成ROS通信对象创建和UDP端口监听准备。
__init__(copter_id=1, target_ip=127.0.0.1, ros_node=None)¶
功能说明：初始化UDP通信端口、创建ROS相关的发布者、订阅者和服务，并启动UDP数据监听线程，会根据传入的无人机ID自动计算本地监听端口和远程发送端口。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
copter_id |
int |
否 | 1 |
无人机ID，用于自动计算UDP通信端口，监听端口为30100 + id*2 - 1，发送端口为30100 + (id-1)*2 |
target_ip |
str |
否 | 127.0.0.1 |
UDP数据发送的目标IP地址，默认指向本地 |
ros_node |
rospy.NodeHandle |
否 | None |
ROS节点句柄，若传入则使用该节点创建通信对象，否则使用默认ROS节点 |
返回值 (Returns)：
UdpRosBridge实例对象
异常 (Raises)：
- 无
start()¶
功能说明：启动UDP桥接的通信线程，开始接收仿真数据并转发至ROS，同时接收ROS指令转发至仿真。 参数列表 (Args)： 无 返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
from RflySimSDK.ctrl import UdpRosBridge
# 创建1号无人机的UDP通信桥
bridge = UdpRosBridge(copter_id=1)
# 启动通信
bridge.start()
stop()¶
功能说明：停止所有UDP监听和数据转发线程，清理占用的通信资源。 参数列表 (Args)： 无 返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
from RflySimSDK.ctrl import UdpRosBridge
bridge = UdpRosBridge()
bridge.start()
# 结束通信时停止并清理资源
bridge.stop()
进阶用法示例¶
以下示例在 ROS2 中为多个 CopterID 创建桥接实例，并用同一个节点和多线程执行器处理消息。
参考例程：[RflySim安装路径]\RflySimAPIs\6.RflySimExtCtrl\0.ApiExps\e21.RosTransExps\2.PythonDemo
import time
import rclpy
from rclpy.executors import MultiThreadedExecutor
from rclpy.node import Node
import DllSimCtrlAPIROS as dll
rclpy.init()
node = Node("rflysim_dll_multi_bridge")
bridges = []
for copterID in [1, 2, 3]:
bridge = dll.UdpRosBridge(
copter_id=copterID,
target_ip="127.0.0.1",
ros_node=node,
)
bridge.start()
bridges.append(bridge)
time.sleep(1)
executor = MultiThreadedExecutor()
executor.add_node(node)
try:
executor.spin()
finally:
for bridge in bridges:
bridge.stop()
executor.shutdown()
node.destroy_node()
rclpy.shutdown()
注意事项与避坑指南¶
- 端口占用问题：同一端口仅能启动一个
UdpRosBridge实例，批量启动多个桥接时需要分配不同的本地端口，否则会启动失败且不会自动释放占用的端口资源。 - 资源释放要求：任务结束后必须手动调用
stop方法关闭桥接，否则进程退出后UDP监听线程仍会占用系统网络资源，需要手动结束进程才能释放端口。 - 异步场景调用限制：
start和stop方法本身为同步接口，在异步多桥接场景中，不要将start/stop直接放在异步回调中不加保护地调用，避免多线程同时操作端口引发通信混乱。 - 网络兼容性说明：
UdpRosBridge仅支持同局域网内的ROS通信转发，跨网段场景需要提前配置路由转发规则，否则无法正常接收仿真端的话题数据。
更新日志¶
2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云2026-01-04: fix