NetSimAPIV4 Interface Documentation¶

Introduction¶

Overview: This file provides the core network communication interface between the RflySim UAV simulation platform and the PX4 flight controller, enabling data exchange and interaction within the simulation environment.

This module serves as the core communication layer implementation within the RflySim simulation framework. It manages network connections between the simulation side and the flight controller side, supporting stable exchange of various data types—including UAV states and control commands—within the simulation environment. It forms the foundational data transmission backbone for the entire simulation task.

It is applicable to all UAV simulation scenarios built upon the RflySim platform, whether for single UAV or multi-UAV swarm simulations. The module’s provided classes can be used to establish network connections and perform core communication operations such as flight controller data transmission and reception.

Quick Start¶

Minimal working example; copy and modify only minimal configuration to run.

from RflySimSDK.comm import NetSimAPI

# Initialize NetSimAPI, set target UAV ID to 1
net_api = NetSimAPI(MavOrCopterID=1)

# Enable UAV-side forwarding, specifying forwarding to UAV ID 1 with a 10ms interval
net_api.enUavForward(CopterIDList=[1], Interval=10)

# Enable network forwarding, sending data to the local multicast address 224.0.0.10, using the default port 60000, with a 10ms interval
net_api.enNetForward(PortList=[60000], targetIP="224.0.0.10", Interval=10)

# The program remains in forwarding mode here; replace with your actual business logic as needed
input("Press Enter to stop forwarding...\n")

# Stop network forwarding and close the channel
net_api.endNetForward()

Environment and Dependencies¶

Python Environment: >= 3.8.10
Dependencies: copy, ctrl.IpManager, cv2, math, numpy, os, pymavlink, pymavlink.dialects.v20, socket, struct, sys, threading, time
Prerequisites: Before calling this interface, network communication environment configuration must be completed, and the simulation-side network connection must be ready.

Core Interface Description¶

The module NetSimAPIV4.py contains configuration variables, helper functions, and core business classes.

Global Constants and Enumerations¶

This section lists all globally accessible constants and enumeration definitions that can be directly referenced within the module.

Standalone Constants¶

None

Global/Standalone Functions¶

None

`UAVSendData` Class¶

A foundational data class for UAV data transmission, typically used as the basic data type for data transfer within the network simulation interface.

`init()`¶

Function Description: Initializes an instance of the UAVSendData class.
Parameters (Args):
None
Returns:
- An instance of UAVSendData

Exceptions (Raises):
None

`NetSimAPI` Class¶

The network simulation API interface class, used for communication and interaction related to network simulation in RflySim.

`init(MavOrCopterID="1")`¶

Function Description: Initializes an instance of the network simulation API and binds it to a specific aircraft ID.
Parameters (Args):

Parameter Name	Type	Default Value	Description
MavOrCopterID	Any	"1"	The MAV or aircraft ID to bind; identifies the UAV object associated with the current instance

Returns: None
Exceptions (Raises): None

`enUavForward(CopterIDList=[0], Interval=0)`¶

Function Description: Enables MAVLink data network forwarding for specified UAVs.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
CopterIDList	None	No	[0]	List of UAV IDs for which forwarding should be enabled
Interval	None	No	0	Forwarding interval (in seconds); 0 indicates immediate start of continuous forwarding
Returns: None
Exceptions (Raises): None

`enNetForward(PortList=[60000], targetIP="224.0.0.10", Interval=0)`¶

Function Description: Enables network data forwarding for specified ports and target addresses.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
PortList	None	No	[60000]	List of target ports to enable forwarding for
targetIP	None	No	224.0.0.10	Target IP address for forwarding; defaults to a multicast address
Interval	None	No	0	Forwarding interval (in seconds); 0 indicates immediate start of continuous forwarding
Returns: None
Exceptions (Raises): None

`endNetForward()`¶

Function Description: Stops all ongoing network forwarding operations.
Parameters (Args): None
Returns: None
Exceptions (Raises): None

`netResetSendList()`¶

Function Description: Clears the UAV send list for data forwarding.
Parameters (Args): None
Returns: None
Exceptions (Raises): None

`netAddUavSendList(uavList=[])`¶

Function Description: Adds specified UAVs to the send list for data forwarding.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
uavList	None	No	[]	List of UAV IDs to add to the send list
Returns: None
Exceptions (Raises): None

`netResetReqList()`¶

Function Description: Clears the UAV request list for data requests.
Parameters (Args): None
Returns: None
Exceptions (Raises): None

`netAddUavReqList(uavList=[])`¶

Function Description: Adds specified UAVs to the request list for data requests.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
uavList	None	No	[]	List of UAV IDs to add to the request list
Returns: None
Exceptions (Raises): None

`StartReqUavData(uavList=[])`¶

Function Description: Starts a scheduled task to periodically request data from specified UAVs.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
uavList	None	No	[]	List of UAV IDs from which to request data
Returns: None
Exceptions (Raises): None

`EndReqUavData()`¶

Function Description: Stops all UAV data request tasks.
Parameters (Args): None
Returns: None
Exceptions (Raises): None

`sendReqUavLoop()`¶

Function Description: Executes a single UAV data request cycle, sending data requests to all UAVs in the request list.
Parameters (Args): None
Returns: None
Exceptions (Raises): None

`netForwardBuf(buf)`¶

Function Description: Forwards data from the specified buffer to all configured network destinations.
Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
buf	None	Yes	None	Binary data buffer to be forwarded
Return Value (Returns): None
Exceptions (Raises): None

`getMavEvent()`¶

Function Description: Retrieves the received MAVLink event data.
Arguments (Args): No arguments.
Return Value (Returns): The received MAVLink event object.
Exceptions (Raises): None.

`StartNetRecOwn()`¶

Function Description: Starts a network reception thread that receives only local simulation UAV data.
Arguments (Args): No arguments.
Return Value (Returns): None.
Exceptions (Raises): None.

`StartNetRec(MultiPort=60000, MultiIP="224.0.0.10")`¶

Function Description: Starts a network data reception thread on the specified multicast address and port.
Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
MultiPort	None	No	60000	Multicast port number for receiving data
MultiIP	None	No	224.0.0.10	Multicast IP address for receiving data
Return Value (Returns): None
Exceptions (Raises): None

`endNetLoop()`¶

Function Description: Stops all network reception and data forwarding loop threads, and shuts down network services.
Arguments (Args): No arguments.
Return Value (Returns): None.
Exceptions (Raises): None.

`getMavMsgNet()`¶

Function Description: Retrieves the latest MAVLink message received over the network.
Arguments (Args): No arguments.
Return Value (Returns): The latest received MAVLink message object.
Exceptions (Raises): None.

`getUavData(CopterID)`¶

Function Description: Retrieves the latest simulation data for the UAV with the specified ID.
Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	None	Yes	None	ID number of the target UAV

Return Value (Returns): The latest simulation data for the UAV with the specified ID.
Exceptions (Raises): None.

Advanced Usage Example¶

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

```python from RflySimSDK.comm import NetSimAPI, UAVSendData import threading

Initialize communication interface and configure multi-UAV task communication¶

net_api = NetSimAPI()

Reset send and request lists to avoid interference from historical data¶

net_api.netResetSendList() net_api.netResetReqList()

Batch-add upstream transmission configurations for 10 UAVs¶

uav_send_list = [UAVSendData(uav_id=i) for i in range(1, 11)] for send_item in uav_send_list: net_api.netAddUavSendList(send_item)

Batch-add UAV status request configurations¶

for uav_id in range(1, 11): net_api.netAddUavReqList(uav_id)

Enable UAV forward forwarding and network forwarding¶

net_api.enUavForward(True) net_api.enNetForward(True)

Asynchronously start periodic request loop to avoid blocking the main task thread¶

req_thread = threading.Thread(target=net_api.sendReqUavLoop, daemon=True) req_thread.start()

Main task executes collaborative mission scheduling, asynchronously retrieving UAV status data¶

while True: # Insert main logic such as mission planning, obstacle avoidance decision-making, etc. pass

After task completion, disable request and communication forwarding¶

net_api.EndReqUavData() net_api.endNetForward()

Notes and Pitfall Avoidance Guide¶

Forwarding State Consistency: After enabling bidirectional forwarding using both enUavForward and enNetForward, the corresponding endNetForward must be called upon task completion to disable forwarding; otherwise, port occupation conflicts will occur in the next simulation round, preventing normal communication startup.
List Modification Order: Before adding or modifying the send/request lists, netResetSendList or netResetReqList must be called first to clear existing configurations; otherwise, duplicate configuration entries will be added, causing communication data to be sent repeatedly and leading to parsing errors on the receiving end.
Loop Request Invocation Method: sendReqUavLoop is a blocking loop method; invoking it directly on the main thread will stall subsequent task logic. It must be executed asynchronously in a separate daemon thread to achieve coordination between the main task and communication.
Request Lifecycle Management: Before initiating a batch of UAV data requests, StartReqUavData must be called to complete initialization, and EndReqUavData must be called after task completion to terminate the request. Unpaired calls will cause memory leaks, resulting in decreased frame rate and potential program crashes after prolonged simulation.

Changelog¶

2026-03-03: feat: SDK adds IP handling mechanism, compatible with local deployment on cloud
2025-09-11: fix: Adds support for Linux port reuse
2024-07-18: fix: Updates API homepage index
2024-06-13: fix: Updates networking interfaces
2024-05-27: fix: Updates communication interface class
2024-05-23: Adds API documentation for Python network communication interfaces
2024-05-23: fix: Improves network communication interface class
2024-05-14: fix: Adds caching to ensure normal communication
2024-05-13: fix: Updates data forwarding interfaces, supports broadcasting aircraft status and subscription by all aircraft
2024-03-03: fix: Adds exception handling for multicast to prevent initialization errors during network disconnection
2023-10-24: feat: Fixes several bugs
2023-10-23: feat: Adds all Python common labs

NetSimAPIV4 Interface Documentation¶

Introduction¶

Quick Start¶

Environment and Dependencies¶

Core Interface Description¶

Global Constants and Enumerations¶

Standalone Constants¶

Global/Standalone Functions¶

UAVSendData Class¶

__init__()¶

NetSimAPI Class¶

__init__(MavOrCopterID="1")¶

enUavForward(CopterIDList=[0], Interval=0)¶

enNetForward(PortList=[60000], targetIP="224.0.0.10", Interval=0)¶

endNetForward()¶

netResetSendList()¶

netAddUavSendList(uavList=[])¶

netResetReqList()¶

netAddUavReqList(uavList=[])¶

StartReqUavData(uavList=[])¶

EndReqUavData()¶

sendReqUavLoop()¶

netForwardBuf(buf)¶

getMavEvent()¶

StartNetRecOwn()¶

StartNetRec(MultiPort=60000, MultiIP="224.0.0.10")¶

endNetLoop()¶

getMavMsgNet()¶

getUavData(CopterID)¶