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 is the core implementation of the communication layer within the RflySim simulation framework. It is responsible for managing network connections between the simulation side and the flight controller side, supporting stable interaction of various data types—including UAV states and control commands—within the simulation environment. It serves as the data transmission foundation for the normal operation of the entire simulation task.

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

Quick Start¶

The following example forwards the status data of UAV 1 point-to-point to UAV 2. Before running, the corresponding CopterSim and PX4 instances must be started.

Reference example: [RflySim installation path]\RflySimAPIs\9.RflySimComm\0.ApiExps\e1.RflyNetAPIExps\1.P2PSendData

import time

import NetSimAPIV4
import PX4MavCtrlV4 as PX4MavCtrl
import ReqCopterSim


CopterID = 1

# Get the address of CopterSim 1 and request it to send data back to this machine
req = ReqCopterSim.ReqCopterSim()
targetIP = req.getSimIpID(CopterID)
req.sendReSimIP(CopterID)

# Create flight controller communication and network simulation instances
mav = PX4MavCtrl.PX4MavCtrler(CopterID, targetIP)
net = NetSimAPIV4.NetSimAPI(mav)
mav.InitMavLoop()
time.sleep(2)

# Forward the collected UAV data from this machine to UAV 2
net.enUavForward(2)

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):
No parameters
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): No parameters
Returns: None
Exceptions (Raises): None

`netResetSendList()`¶

Function Description: Clears the UAV send list for data forwarding.
Parameters (Args): No parameters
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): No parameters
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): No parameters
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): No parameters
Returns: None
Exceptions (Raises): None

`netForwardBuf(buf)`¶

Function Description: Forwards data from the specified buffer to all configured network destinations.
Parameters (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.
Parameters (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.
Parameters (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.
Parameters (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 closes the network service.
Parameters (Args): No arguments.
Return Value (Returns): None.
Exceptions (Raises): None.

`getMavMsgNet()`¶

Function Description: Retrieves the latest MAVLink message received over the network.
Parameters (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.
Parameters (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 Examples¶

The following example broadcasts the data of UAV 1 while receiving and traversing the status of other UAVs on the network.

Reference example: [RflySim installation path]\RflySimAPIs\9.RflySimComm\0.ApiExps\e1.RflyNetAPIExps\2.BroadSendData

import time

import NetSimAPIV4
import PX4MavCtrlV4 as PX4MavCtrl
import ReqCopterSim


CopterID = 1
req = ReqCopterSim.ReqCopterSim()
targetIP = req.getSimIpID(CopterID)
req.sendReSimIP(CopterID)

mav = PX4MavCtrl.PX4MavCtrler(CopterID, targetIP)
net = NetSimAPIV4.NetSimAPI(mav)
mav.InitMavLoop()
time.sleep(2)

# Broadcast local UAV data when no target ID is specified
net.enUavForward()
time.sleep(2)

# Start network reception; received data is stored in UavData
net.StartNetRec()
while True:
    for uav in net.UavData:
        print("UAV", uav.CopterID, ":", uav.uavGlobalPos)
    time.sleep(1)

Notes and Pitfall 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: Add 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)¶