RflyRosStart Interface Documentation

Introduction

Overview: This file provides the RflyRosStart class, used to create ROS communication connection instances adapted to the RflySim platform. It supports two methods for initializing communication: via aircraft ID or custom communication port numbers.

In RflySim drone simulation development, third-party functional development based on ROS, as well as communication and interaction between external nodes and simulated drones on the simulation side, require a standardized communication entry point. This module handles the initialization configuration of communication instances, aligning with the platform's communication rules. It not only allows developers to quickly establish a communication link with a specified simulated drone using the aircraft ID, but also supports flexible configuration of non-standard communication scenarios via custom port numbers, making it suitable for secondary development, ROS node extension, custom external control interaction, and other development scenarios.

Quick Start

The following example discovers the address of CopterSim with ID 1, switches the communication mode to MAVLink Full, and then creates RflyRosStart. The constructor automatically starts MAVROS, so there is no need to call InitRosLoop() again.

Reference example: [RflySim installation path]\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("Unable to obtain CopterSim address:", targetID)
    sys.exit(0)

if not (RflyRosStart.isLinux and RflyRosStart.isRosOk):
    print("Current environment does not have a usable ROS")
    sys.exit(0)

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

Environment and Dependencies

• Python Environment: >= 3.8.10
• Dependencies: ctrl.IpManager, math, os, platform, psutil, pymavlink, socket, struct, subprocess, sys, threading, time
• Prerequisites: Before calling this interface, you must complete the RflySimSDK environment setup and import the corresponding module.

Core Interface Description

The module RflyRosStart.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

None

---

Global/Standalone Functions

None

---

RflyRosStart Class

Creates an instance for communication between the RflySim platform and the ROS environment. Supports multiple connection modes including UDP, direct serial connection to the flight controller, and direct UDP connection, making it adaptable to both simulation and real-aircraft scenarios.

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

Function Description: Initializes the RflyRosStart communication instance and configures different connection modes and communication parameters based on input arguments.

Parameters (Args):

Parameter Name	Type	Required	Default	Description
ID	int	No	1	If ID ≤ 10000, it represents the CopterID of the drone; if ID > 10000, it represents the communication port number port, compatible with the legacy interface rule: port = 20100 + CopterID * 2 - 2
ip	str	No	127.0.0.1	Target IP address for data transmission; defaults to localhost. For distributed simulation, specify a LAN IP or use the broadcast address 255.255.255.255
Com	str	No	'udp'	Connection mode to Pixhawk: udp indicates receiving MAVLink messages forwarded by CopterSim; a serial port address (e.g., COM3 on Windows, /dev/ttyUSB0 on Linux) indicates direct USB/telemetry connection to the flight controller; Direct indicates direct UDP mode, where the same port is used for both sending and receiving data
port	int	No	0	In UDP mode, setting to 0 automatically calculates the port based on CopterID; a value greater than 0 forces usage of the specified port. In serial mode, it specifies the baud rate, with 0 corresponding to the default 57600. In Direct mode, it specifies the send/receive port number. In Redis mode, it specifies the server port, with 0 corresponding to the default 6379
simulinkDLL	bool	No	False	Whether it is the Simulink-generated DLL mode, for compatibility with Simulink co-simulation scenarios

Returns:

• RflyRosStart instance object

Raises:

• None

---

InitRosLoop()

Function Description: Initializes the ROS communication loop and starts MAVLink data reception and ROS node-related processes.

Parameters (Args): - None

Returns:

• None

Raises:

• None

Example:

# Initialize simulation UDP communication mode and start ROS loop
ros_comm = RflyRosStart(ID=1)
ros_comm.InitRosLoop()

---

KillMavRos()

Function Description: Terminates MAVLink and ROS-related processes and closes the communication connection.

Parameters (Args): - None

Returns:

• None

Raises:

• None

---

EndRosLoop()

Function Description: Ends the ROS communication loop and cleans up communication-related resources.

Parameters (Args): - None

Returns:

• None

Raises:

• None

Example:

# Serial connection to real aircraft, initialize and terminate communication
ros_comm = RflyRosStart(ID=1, Com='COM3', port=57600)
ros_comm.InitRosLoop()
# After business logic processing, terminate communication
ros_comm.EndRosLoop()

---

Advanced Usage Example

RflyRosStart manages the MAVROS subprocess. The following example starts a connection in a remote CopterSim scenario and explicitly stops the ROS loop when the task ends.

Reference example: [RflySim installation path]\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 started")
    time.sleep(30)
finally:
    ros.EndRosLoop()

Notes and Pitfall Avoidance Guide

• InitRosLoop Call Order Requirement: This method must be invoked after the RflySim simulation environment and the PX4 flight controller process have been fully started. Calling it prematurely will result in failure to connect to the flight controller, directly throwing a node startup failure exception.
• MavROS Node Resource Release: The EndRosLoop method can only be called after each individual UAV's MavROS node has been closed via KillMavRos. Unreleased nodes will persist as background system processes, consuming port and memory resources.
• Correctness of IDs in Multi-UAV Scenarios: The arguments passed to InitRosLoop and KillMavRos must strictly match the actual UAV IDs. Mismatched IDs may cause unintended shutdown of other UAVs' nodes, leading to complete simulation mission failure.
• Resource Conflicts from Repeated Initialization: Do not invoke InitRosLoop repeatedly for the same UAV ID. Duplicate startups will cause multiple processes to occupy the same ROS port, resulting in node startup failure.

Changelog

• 2026-03-03: feat: SDK adds IP handling mechanism for compatibility with cloud deployment of local versions
• 2024-11-20: Added support for integration with real-world hardware
• 2024-11-19: Updated management of multi-level subprocess calls
• 2024-11-19: Optimized MavROS startup script, primarily in process management; supports ROS1/ROS2 kill operations
• 2024-08-14: fix: Updated HTML version API
• 2024-07-18: fix: Updated API homepage index
• 2024-05-19: fix: Updated
• 2024-05-15: fix: Optimized initialization mechanism
• 2024-04-16: Fixed compatibility issue with ROS1 and ROS2 subprocess starting MavROS child thread blocking
• 2024-03-08: Interface adapted to ROS2, and fixed issues with using subprocess module
• 2024-01-29: fix: Added MavROS control example