DllSimCtrlAPIROS 接口文档

简介

简述：提供基于UDP的ROS桥接通信类，实现RflySim仿真平台与ROS系统之间的无人机控制数据互联互通。

在基于RflySim的无人机仿真开发中，很多开发者需要结合ROS生态完成路径规划、视觉感知、自主决策等上层算法开发，本模块负责打通RflySim仿真内核与ROS环境的数据交互通道。UdpRosBridge类通过UDP协议实现跨进程甚至跨设备的低延迟数据传输，支持无人机状态、控制指令等仿真数据在RflySim仿真核心和ROS节点之间双向转发，适用于基于ROS开展无人机仿真算法开发、联调测试的场景。

快速开始

最简可用示例，复制后修改最少配置即可运行。

import rospy
from RflySimSDK.ctrl import UdpRosBridge

if __name__ == "__main__":
    # 初始化ROS节点
    rospy.init_node("rflysim_udp_bridge_node")

    # 初始化UdpRosBridge，这里使用默认配置：1号无人机，本机UDP地址，ROS节点用当前已初始化的节点
    # 自动分配监听端口为30100 + 1*2 -1 = 30101，发送端口为30100 + (1-1)*2 = 30100
    udp_bridge = UdpRosBridge(copter_id=1, target_ip="127.0.0.1", ros_node=rospy)

    # 启动UDP监听线程和ROS通信
    udp_bridge.start()

    # 保持节点运行，等待ROS关闭信号
    try:
        rospy.spin()
    except KeyboardInterrupt:
        print("接收到退出信号，准备关闭")
    finally:
        # 停止线程并清理资源
        udp_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()

---

进阶用法示例

展示复杂组合场景（如多类协作、异步控制、批量操作）

import asyncio
from RflySimSDK.ctrl import UdpRosBridge

# 多链路异步协作场景：同时启动多架无人机的仿真通信桥接，实现异构任务协同
async def start_multi_bridge(bridge_configs):
    bridge_list = []
    # 批量初始化并启动多个UDP通信桥接实例
    for config in bridge_configs:
        bridge = UdpRosBridge(config['local_port'], config['remote_ip'], config['remote_port'])
        bridge.start()
        bridge_list.append(bridge)
        print(f"已启动无人机{config['drone_id']}通信桥接，本地端口：{config['local_port']}")
    # 异步等待协同任务执行完成
    await run_cooperative_task(bridge_list)
    # 批量关闭桥接避免资源泄漏
    for bridge in bridge_list:
        bridge.stop()
    print("所有异构无人机协同任务完成，通信桥接已全部关闭")

async def run_cooperative_task(bridge_list):
    # 异步分发不同任务指令，实现多机协作探测
    for idx, bridge in enumerate(bridge_list):
        asyncio.create_task(send_task_command(bridge, idx))
    await asyncio.sleep(30) # 等待任务执行

async def send_task_command(bridge, task_id):
    # 异步周期发送任务指令，不阻塞其他桥接通信
    for _ in range(10):
        # 此处为业务指令发送逻辑，可基于桥接通道转发自定义ROS话题
        await asyncio.sleep(3)

if __name__ == "__main__":
    # 配置3架异构无人机的通信参数
    configs = [
        {"drone_id": 1, "local_port": 5001, "remote_ip": "127.0.0.1", "remote_port": 6001},
        {"drone_id": 2, "local_port": 5002, "remote_ip": "127.0.0.1", "remote_port": 6002},
        {"drone_id": 3, "local_port": 5003, "remote_ip": "127.0.0.1", "remote_port": 6003},
    ]
    asyncio.run(start_multi_bridge(configs))

注意事项与避坑指南

• 端口占用问题：同一端口仅能启动一个UdpRosBridge实例，批量启动多个桥接时需要分配不同的本地端口，否则会启动失败且不会自动释放占用的端口资源。
• 资源释放要求：任务结束后必须手动调用stop方法关闭桥接，否则进程退出后UDP监听线程仍会占用系统网络资源，需要手动结束进程才能释放端口。
• 异步场景调用限制：start和stop方法本身为同步接口，在异步多桥接场景中，不要将start/stop直接放在异步回调中不加保护地调用，避免多线程同时操作端口引发通信混乱。
• 网络兼容性说明：UdpRosBridge仅支持同局域网内的ROS通信转发，跨网段场景需要提前配置路由转发规则，否则无法正常接收仿真端的话题数据。

更新日志

• 2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云
• 2026-01-04: fix