IpManager Interface Documentation

Introduction

Overview: This file defines the IpManager class, used to uniformly manage IP addresses and port configurations required for communication and interaction within the RflySim simulation platform.

In the RflySim UAV simulation framework, components such as the ground station, flight controller, and simulation environment often run on different network nodes or processes. A unified IP address management system is required to ensure proper network communication between modules. This module maintains address configuration information for various communication links and provides a centralized entry point for address querying and management to other communication control modules in the SDK. It is particularly suitable for multi-robot simulation and distributed simulation scenarios where distinct node communication addresses must be distinguished, simplifying IP configuration maintenance and usage.

Quick Start

A minimal working example; copy and modify only the necessary configurations to run.

from RflySimSDK.ctrl.IpManager import IpManager

# Check whether the IP configuration file exists and the path is valid
exists, config_path = IpManager.is_valid()
print(f"IP configuration file status: exists={exists}, path={config_path}")

# Detect whether the current program is running inside a Docker/K8s container
in_container = IpManager.is_container()
print(f"Running inside a container: {in_container}")

# Retrieve the local IP from the configuration file; fallback to default 127.0.0.1 on failure
local_ip = IpManager.get_local_ip()
print(f"Retrieved local IP address: {local_ip}")

# Alternatively, specify a custom default IP to use on failure
custom_default_ip = "192.168.1.100"
local_ip_custom = IpManager.get_local_ip(custom_default_ip)
print(f"Local IP address with custom default: {local_ip_custom}")

Environment and Dependencies

• Python Environment: >= 3.8.10
• Dependencies: json, os
• Prerequisites: Before calling this interface, the IP connection parameters for the RflySim SDK must be correctly configured, and the SDK environment must be initialized.

Core Interface Description

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

---

IpManager Class

A utility class for IP address management, used to retrieve IP addresses for various RflySim platform components (RflySim3D, CopterSim, QGroundControl) from the configuration file. It also supports environment detection and configuration validation, enabling adaptation to both local and distributed simulation scenarios.

---

is_valid()

Function Description: Checks whether the IP configuration file path is valid and whether the configuration file exists. Parameters (Args): - None

Returns: - tuple: The first element is a bool indicating whether the configuration is valid; the second element is a str representing the configuration file path.

Raises: - None

---

is_container()

Function Description: Detects whether the current program is running inside a container environment (e.g., Docker, K8s). Parameters (Args): - None

Returns: - bool: Returns True if running inside a container; otherwise returns False.

Raises: - None

---

get_local_ip(original_ip)

Function Description: Retrieves the local IP address from the configuration file. Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
original_ip	Any	No	127.0.0.1	Default IP address to return if lookup fails or lookup is skipped

Returns: - str: Local IP address as a string.

Raises: - None

Example:

from RflySimSDK.ctrl import IpManager
local_ip = IpManager.get_local_ip()
print("Local IP:", local_ip)

---

get_rflysim3d_ip(original_ip)

Function Description: Retrieves the IP address for RflySim3D. Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
original_ip	Any	No	127.0.0.1	Default IP address to return if lookup fails or lookup is skipped

Returns: - str: RflySim3D IP address as a string.

Raises: - None

Example:

from RflySimSDK.ctrl import IpManager
rflysim3d_ip = IpManager.get_rflysim3d_ip()
print("RflySim3D IP:", rflysim3d_ip)

---

get_coptersim_ip(copter_id, original_ip)

Function Description: Retrieves the CopterSim IP address corresponding to a specified copter ID. When CopterSim and the SDK are not on the same machine, it automatically requests CopterSim to send data to the local host.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copter_id	Any	Yes	None	ID of the target aircraft
original_ip	Any	No	127.0.0.1	Default IP address returned when lookup fails or is unnecessary

Returns:

• str: CopterSim IP address string

Raises:

• None

Example:

from RflySimSDK.ctrl import IpManager
# Get the CopterSim IP corresponding to the drone with ID 1
coptersim_ip = IpManager.get_coptersim_ip(1)
print("CopterSim IP:", coptersim_ip)

---

get_qgc_ip(original_ip)

Function Description: Retrieves the IP address of the QGroundControl (QGC) ground station.

Arguments:

Parameter Name	Type	Required	Default Value	Description
original_ip	Any	No	127.0.0.1	Default IP address returned when lookup fails or is unnecessary

Returns:

• str: QGC IP address string

Raises:

• None

---

Advanced Usage Examples

Demonstrates complex collaborative scenarios (e.g., multi-component coordination, asynchronous control, batch operations)

For networked simulation clusters involving multi-vehicle coordination, IpManager can be combined to perform batch IP validity validation, while simultaneously supporting automatic IP adaptation for heterogeneous simulation components via the multi-vehicle control module. For instance, in a distributed deployment scenario where PX4 simulation, RflySim3D rendering, and QGC ground station run concurrently across multiple nodes, one can batch-fetch IPs for different services and pre-validate connectivity to prevent connection failures after simulation startup. Example code is as follows:

from RflySimSDK.ctrl import IpManager
import concurrent.futures

# Asynchronously validate connectivity of multiple simulation component IPs in batch
def check_ip_valid(service_name, get_ip_method):
    ip = get_ip_method()
    return (service_name, ip, IpManager.is_valid(ip))

# List of services to validate, covering various simulation component types
service_list = [
    ("RflySim3D", IpManager.get_rflysim3d_ip),
    ("CopeliSim Simulation", IpManager.get_coptersim_ip),
    ("QGC Ground Station", IpManager.get_qgc_ip)
]

# Asynchronous batch validation to improve startup efficiency in large-scale cluster scenarios
with concurrent.futures.ThreadPoolExecutor() as executor:
    futures = [executor.submit(check_ip_valid, name, method) for name, method in service_list]
    for future in concurrent.futures.as_completed(futures):
        service_name, ip, is_valid = future.result()
        if is_valid:
            print(f"{service_name} IP {ip} connectivity is normal")
        else:
            print(f"Warning: {service_name} IP {ip} is unreachable; please check network configuration")

# Retrieve local IP for cross-device distributed simulation networking
local_ip = IpManager.get_local_ip()
print(f"Local networking IP: {local_ip}")

This approach enables asynchronous batch IP validation, making it suitable for complex scenarios such as multi-vehicle distributed cluster simulation and heterogeneous component collaboration, while proactively identifying network configuration issues.

Notes and Best Practices

• IP Acquisition Anomalies in Multi-NIC Environments: The get_local_ip() method prioritizes retrieving the IP of an active network interface by default. In devices with multiple physical or virtual NICs (e.g., VPN or Docker virtual interfaces), an incorrect internal IP may be returned; manual filtering based on subnet is required to confirm the correct networking IP.
• Container Deployment Network Detection Failure: The is_container() method only recognizes container environments under default network configurations. It may fail to correctly identify environments using custom bridge or host networking modes, requiring manual configuration of IP mapping rules.
• Limitations of IP Validity Validation: The is_valid() method only checks IP format correctness and basic connectivity. It cannot verify whether the corresponding port is open or whether the simulation service has started successfully. Even after successful connectivity validation, additional logic to confirm service startup status should be added.
• Incorrect Environment Configuration Dependencies: All methods in the IpManager class rely on reading IP information from the RflySim core configuration file. If SDK initialization fails or the configuration file is missing, all IP retrieval methods will return default placeholder addresses. Ensure the SDK is properly initialized before use.

Changelog

• 2026-03-03: feat: Added IP handling mechanism to SDK for compatibility with local-to-cloud migration scenarios