DllSimCtrlAPIROS Interface Documentation

Introduction

Overview: Provides a UDP-based ROS bridge communication class, enabling bidirectional data exchange of drone control information between the RflySim simulation platform and the ROS system.

In drone simulation development based on RflySim, many developers need to integrate the ROS ecosystem for upper-layer algorithm development such as path planning, visual perception, and autonomous decision-making. This module is responsible for establishing the data communication channel between the RflySim simulation kernel and the ROS environment. The UdpRosBridge class achieves low-latency data transmission across processes or even devices via the UDP protocol, supporting bidirectional forwarding of simulation data—including drone states and control commands—between the RflySim simulation core and ROS nodes. It is suitable for scenarios involving ROS-based drone simulation algorithm development and co-simulation testing.

Quick Start

The following example starts the DLL simulation UDP/ROS bridge for Copter ID 1 in a ROS1 environment and stops the bridge thread when the node exits.

Reference example: [RflySim installation path]\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()

Environment and Dependencies

• Python Environment: >= 3.8.10
• Dependencies: DllSimCtrlAPI, ctrl.IpManager, errno, logging, math, socket, struct, sys, threading, time
• Prerequisites: Before calling this interface, ensure the RflySimSDK environment is correctly configured and the corresponding dynamic-link library can be invoked successfully.

Core Interface Description

The module DllSimCtrlAPIROS.py includes configuration variables, helper functions, and the core business class.

Global Constants and Enumerations

This section lists all globally accessible constants and enumerations defined in the module.

Standalone Constants

Variable Name	Type	Value	Description
ROS1	bool	False	-
ROS2	bool	False	-

---

Global / Standalone Functions

None

---

UdpRosBridge Class

UDP communication bridge between RflySim simulation and ROS, enabling bidirectional forwarding of drone simulation data and ROS commands. Automatically assigns communication ports based on drone ID; upon initialization, it creates ROS communication objects (publishers, subscribers, services) and prepares UDP port listening.

__init__(copter_id=1, target_ip=127.0.0.1, ros_node=None)

Function Description: Initializes UDP communication ports, creates ROS-related publishers, subscribers, and services, and starts the UDP data listening thread. The local listening port and remote sending port are automatically calculated based on the provided drone ID. Parameters (Args):

Parameter Name	Type	Required	Default	Description
copter_id	int	No	1	Drone ID used to automatically compute UDP communication ports: listening port = 30100 + id*2 - 1, sending port = 30100 + (id-1)*2
target_ip	str	No	127.0.0.1	Target IP address for UDP data transmission; defaults to localhost
ros_node	rospy.NodeHandle	No	None	ROS node handle; if provided, communication objects are created using this node; otherwise, the default ROS node is used

Return Value (Returns):

• Instance of UdpRosBridge

Exceptions (Raises):

• None

---

start()

Function Description: Starts the UDP bridge communication thread, beginning reception of simulation data and forwarding it to ROS, while simultaneously receiving ROS commands and forwarding them to the simulation. Parameters (Args): - None Return Value (Returns):

• None

Exceptions (Raises):

• None

Example:

from RflySimSDK.ctrl import UdpRosBridge
# Create UDP communication bridge for copter ID 1
bridge = UdpRosBridge(copter_id=1)
# Start communication
bridge.start()

---

stop()

Function Description: Stops all UDP listening and data forwarding threads, and cleans up occupied communication resources. Parameters (Args): - None Return Value (Returns):

• None

Exceptions (Raises):

• None

Example:

from RflySimSDK.ctrl import UdpRosBridge
bridge = UdpRosBridge()
bridge.start()
# Stop and clean up resources when ending communication
bridge.stop()

---

Advanced Usage Examples

The following example creates bridge instances for multiple Copter IDs in ROS2, using the same node and a multi-threaded executor to handle messages.

Reference example: [RflySim installation path]\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()

Notes and Pitfall Avoidance Guide

• Port Occupancy Issue: Only one UdpRosBridge instance can bind to a given local port. When starting multiple bridges in batch, distinct local ports must be assigned; otherwise, startup will fail, and the occupied port resources will not be automatically released.
• Resource Release Requirement: The stop method must be manually invoked after task completion to shut down the bridge; otherwise, the UDP listening thread will continue occupying system network resources after the process exits, requiring manual termination of the process to release the port.
• Asynchronous Invocation Limitation: The start and stop methods are synchronous interfaces. In asynchronous multi-bridge scenarios, avoid directly invoking start/stop within asynchronous callbacks without proper synchronization, to prevent communication chaos caused by concurrent port access across threads.
• Network Compatibility Note: UdpRosBridge supports ROS communication forwarding only within the same local area network (LAN). For cross-subnet scenarios, routing rules must be pre-configured; otherwise, topic data from the simulation side cannot be received properly.

Changelog

• 2026-03-03: feat: SDK adds IP handling mechanism to support local-on-cloud deployment
• 2026-01-04: fix