DllSimCtrlAPI Interface Documentation¶

Introduction¶

Overview: This file provides the underlying simulation control and data interaction interfaces for the RflySim simulation platform. It encapsulates multiple classes related to simulation control, data management, and model loading, supporting closed-loop co-simulation between third-party code and flight controllers such as PX4.

The RflySim platform requires dynamic link libraries (DLLs) to enable interaction between the Python environment and the simulation core as well as flight controller firmware. This module encapsulates the complete set of interfaces for interfacing with the underlying simulation control library, enabling low-level control and scheduling for various types of UAV simulation tasks. It supports structured management of 3D simulation data and hardware-in-the-loop (HIL) simulation data, and implements RflySim’s proprietary comprehensive model control protocol. This allows adaptation to scenarios such as multi-rotor DLL model loading and custom simulation model scheduling, forming the core foundational module for closed-loop simulation control in RflySimSDK.

Quick Start¶

Minimal working example: copy and modify only the minimal required configuration to run. Ensure that RflySim SDK is correctly installed and the PX4 flight controller has been started.

from RflySimSDK.ctrl.DllSimCtrlAPI import ModelLoad
import time

# 1. Initialize the model loading object, load the simulation control interface, use the default grassland map, local IP, and the first UAV
sim_ctrl = ModelLoad(
    dll_name=None,  # Use the built-in simulation DLL by default
    CopterID=1,     # UAV ID, default is 1
    MapName="Grasslands",  # Use the default grassland map
    ip="127.0.0.1" # Local simulation address
)

# 2. Create a UAV, default initial position (0, 0), initial yaw 0 degrees, no GPS
sim_ctrl.CreateVehicle(
    CopterID=1,
    useGPS=False
)

# 3. Start the simulation loop, periodically updating the 3D simulation view
for i in range(100):
    # Update UAV state output
    sim_ctrl.Updata3Doutput()
    # Send update information to the 3D visualization interface
    sim_ctrl.SendUpdate3DMap()
    # Control simulation frame rate, approximately 50Hz
    time.sleep(0.02)

Environment and Dependencies¶

Python Environment: >= 3.8.10
Dependencies: EarthModel, UE4CtrlAPI, UEMapServe, copy, ctrl.IpManager, ctypes, cv2, math, numpy, os, pymavlink, pymavlink.dialects.v20, shutil, socket, struct, sys, threading, time
Prerequisites: Before calling this interface, ensure that RflySimSDK is correctly installed and environment configuration is completed.

Core Interface Description¶

The module DllSimCtrlAPI.py includes configuration variables, helper functions, and core business classes.

Global Constants and Enumerations¶

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

Standalone Constants¶

None

Global/Standalone Functions¶

None

`Data3D` Class¶

Stores state data related to 3D UAV simulation, supports parsing and updating various UAV state information from raw data, suitable for managing and maintaining UAV state data in RflySim simulations.

`init(copter_data=None, CopterID=-1, ClassID=-1)`¶

Function Description: Initializes a Data3D object. If raw UAV data is provided, it automatically calls the update method to parse the data; otherwise, all state members are initialized to default values. The stored states include aircraft ID, 3D style, runtime, velocity, position, attitude (Euler angles and quaternions), motor speeds, acceleration, angular velocity, GPS position, and reserved data.

Parameters (Args):

Parameter Name	Type	Required	Default	Description
`copter_data`	`Any`	No	`None`	Raw UAV state data; if provided, state will be automatically parsed and updated
`CopterID`	`Any`	No	`-1`	UAV’s numeric ID
`ClassID`	`Any`	No	`-1`	UAV’s class ID

Returns:

Data3D instance object

Raises: - None

`update(copter_data, CopterID=-1, ClassID=-1)`¶

Function Description: Updates all stored UAV state information in the Data3D object based on the provided UAV ID, class ID, and raw data, including runtime, velocity, position, attitude, motor speeds, and other state data.

Parameters (Args):

Parameter Name	Type	Required	Default	Description
`copter_data`	`Any`	Yes	-	Raw UAV state data to be parsed
`CopterID`	`Any`	No	`-1`	UAV’s numeric ID
`ClassID`	`Any`	No	`-1`	UAV’s class ID

Returns: - None
Raises: - None

Example:

# Initialize an empty Data3D object
drone_data = Data3D()
# Update state with raw data
drone_data.update(raw_copter_data, CopterID=1, ClassID=0)

`updateUdp(UIV)`¶

Function Description: Updates UAV state information from UDP-received data. Parameters (Args):

Parameter Name	Type	Required	Default	Description
`UIV`	`Any`	Yes	-	Raw state data received via UDP to be parsed

Returns: - None
Raises: - None

Example:

drone_data = Data3D()
# Update state from received UDP data
udp_packet = receive_udp_data()
drone_data.updateUdp(udp_packet)

`DataHIL` Class¶

A top-level data management class for Hardware-in-the-Loop (HIL) simulation. Currently, this class does not define additional member methods or class variables and can serve as a base class for data exchange in HIL simulation.

`init()`¶

Function Description: Initializes an instance of the DataHIL class.
Parameters (Args):
None

Returns:
- An instance of the DataHIL class

Exceptions (Raises):
None

`DllSimCtrlAPI` Class¶

A utility class for communicating with the RflySim simulation environment via UDP broadcast to control drones in the simulation.

`init(self, CopterID=1, ip="127.0.0.1")`¶

Function Description: Initializes a DllSimCtrlAPI object, creates a UDP socket supporting broadcast, and stores the drone ID and target IP address.
Parameters (Args):

Parameter Name	Type	Default Value	Description
CopterID	Any	1	ID of the target drone to be controlled, used to distinguish among multiple drones in the simulation environment
ip	Any	"127.0.0.1"	IP address of the server where the simulation environment resides; for local simulation, the loopback address is used by default

Returns:
None

Exceptions (Raises):
None

`fillList(data, inLen)`¶

Function Description: This method accepts an array or list and adjusts its length according to the provided inLen parameter. If the data length is insufficient, it pads with zeros; if too long, it truncates. The logic is as follows: if the input is a NumPy array, it is first converted to a Python list; if it is already a list of the desired length, it is returned directly; if it is a list but of mismatched length, it is padded or truncated accordingly; if the input is not a list, a single value is wrapped into a list and padded to the specified length. Finally, the processed data is returned.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
data	Any	Yes	None	Input data requiring length adjustment; can be a NumPy array, Python list, or a single numeric value
inLen	int	Yes	None	Target length of the output list

Returns:
A list of length inLen after processing

Exceptions (Raises):
None

`sendCustomData(CopterID=0, data=[0] * 16, checksum=123456, port=50000, IP="127.0.0.1")`¶

Function Description: Encapsulates the CustomData structure, packs the data, and sends it via UDP socket to the specified IP address and port. The

`sendInDoubCtrls(inDoubsCtrls=[0] * 28, copterID=-1)`¶

Function Description: Sends 28-dimensional double-precision data via UDP to the DLL model’s inDoubCtrls input interface. The data structure is DllInDoubCtrls, which includes a checksum, aircraft ID, and a 28-dimensional double-precision array. The method performs length correction on the input data, packs it in 2i28d format, and sends it via port 30100 + (copterID - 1) * 2. If the input copterID is greater than 0, the provided ID is used; otherwise, the object’s own CopterID is used. Before calling this method, ensure that the udp_socket object has been created and configured, and that the self.ip attribute has been set.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
inDoubsCtrls	list	No	[0] * 28	28-dimensional double-precision input data to be sent
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object’s own `CopterID` is used

Returns: None
Raises: None

`sendInCtrlExt(inSILInts=[0] * 8, inSILFLoats=[0] * 20, iDxNum=1, copterID=-1)`¶

Function Description: Sends data via UDP to a specified interface among the inCtrlExt 1~5 series of the DLL model. The interface index is determined by iDxNum. Input format consists of 8-dimensional integer data and 20-dimensional single-precision float data, which is ultimately converted into 28-dimensional double format for transmission to the DLL. The checksum is 1234567800 + iDxNum. After length correction, the data is packed in 10i20f format and sent via port 30100 + (copterID - 1) * 2. If the input copterID is greater than 0, the provided ID is used; otherwise, the object’s own CopterID is used.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
inSILInts	list	No	[0] * 8	8-dimensional integer input data
inSILFLoats	list	No	[0] * 20	20-dimensional single-precision float input data
iDxNum	int	No	1	Target `inCtrlExt` interface index (range: 1–5)
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object’s own `CopterID` is used

Returns: None
Raises: None

`sendInCtrlExtDoub(inDoubsCtrls=[0] * 28, iDxNum=1, copterID=-1, update=True)`¶

Function Description: Sends 28-dimensional double-precision data via UDP to a specified interface among the inCtrlExt 1~5 series of the DLL model. The interface index is determined by iDxNum. The checksum is 1234567800 + iDxNum. After length correction, the data is packed in 2i28d format and sent via port 30100 + (copterID - 1) * 2. If the input copterID is greater than 0, the provided ID is used; otherwise, the object’s own CopterID is used. Note: The inCtrlExt interface of the DLL model defaults to float type; using this method requires modifying the interface type to double and regenerating the DLL for it to take effect.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
inDoubsCtrls	list	No	[0] * 28	28-dimensional double-precision input data to be sent
iDxNum	int	No	1	Target `inCtrlExt` interface index (range: 1–5)
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object’s own `CopterID` is used
update	bool	No	True	Whether to immediately update the data; set to `True` only for the final segment in batch/segmented transmission

Returns: None
Raises: None

`sendInCtrlExtAll(inDoubsCtrls=[0] * 140, copterID=-1)`¶

Function Description: Sends data in bulk to all five inCtrlExt 1~5 interfaces of the DLL model, implemented based on sendInCtrlExtDoub. The input data (up to 140 dimensions) is segmented into chunks of 28 elements each, and sequentially transmitted to inCtrlExt 1 through inCtrlExt 5. The update=True flag is set only for the final segment to trigger an immediate update.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
inDoubsCtrls	list	No	[0] * 140	Total data to be sent; supports up to 5 interfaces × 28 dimensions = 140 dimensions
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object’s own `CopterID` is used

Returns: None
Raises: None

`sendModelInParams(Bitmask, InParams, copterID=-1)`¶

Function Description: Injects parameters into the DLL model’s FaultParamAPI.FaultInParams interface via the PX4ModelInParams structure. A 32-bit unsigned bitmask specifies which parameters are active. After length correction, the data is packed in iI32d format and sent via port 30100 + (copterID - 1) * 2. If the input copterID is greater than 0, the provided ID is used; otherwise, the object’s own CopterID is used. The checksum is fixed at 1234567891.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
Bitmask	int	Yes	N/A	32-bit unsigned bitmask indicating which bits in `InParams` are active (e.g., `0b01` means only the first bit is valid)
InParams	list	Yes	N/A	Up to 32-dimensional double-precision parameters to be injected
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object’s own `CopterID` is used

Returns: None
Raises: None

`sendInitInParams(Bitmask=0, InParams=[0] * 32, copterID=-1)`¶

Function Description: Injects initialization parameters into the DLL model's FaultParamAPI.InitInParams interface by packaging them into the PX4ModelInParams structure and sending them. A 32-bit unsigned bitmask specifies which parameters are active; input parameters are length-adjusted and packed in iI32d format, then transmitted via port 30100 + (copterID - 1) * 2. If the input copterID is greater than 0, the provided ID is used; otherwise, the object's own CopterID is used. The fixed checksum is 1234567892.

Parameters (Args):

Parameter Name	Type	Required	Default	Description
Bitmask	int	No	0	32-bit unsigned bitmask indicating which bits in the input parameters are active; e.g., `0b01` means only the first bit is valid
InParams	list	No	[0] * 32	Up to 32-dimensional double-type initialization parameters to be injected
copterID	int	No	-1	Target aircraft ID; if ≤ 0, the object's own `CopterID` is used

Return Value (Returns): None
Exceptions (Raises): None

`sendDynModiParams(Bitmask=0, InParams=[0] * 64, copterID=-1)`¶

Function Description: Injects dynamic modification parameters into the DLL model's FaultParamAPI.DynModiParams interface by packaging them into the PX4DynModiParams structure and sending them

Parameter Name	Type	Required	Default Value	Description
Coll20d	`List[float]`	No	[0] * 20	20-dimensional collision data, length is 20
copterID	`int`	No	-1	Target drone ID; -1 indicates the command applies to all drones

Return Value (Returns): No return value
Exceptions (Raises): None

`sendTerrIn15d(TerrIn15d=[0] * 15, copterID=-1)`¶

Function Description: This method encapsulates 15-dimensional terrain data for the drone and sends it via UDP to the specified simulator port. Based on the provided terrain data and drone ID, it packages the data using struct.pack in the format ii15f (two integers followed by fifteen floats) before transmission.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
TerrIn15d	`List[float]`	No	[0] * 15	15-dimensional terrain data, length is 15
copterID	`int`	No	-1	Target drone ID; -1 indicates the command applies to all drones

Return Value (Returns): No return value
Exceptions (Raises): None

`sendDllTakeoff(takeoffHeight=-10)`¶

Function Description: Sends a takeoff command to the PX4 simulator, specifying the target takeoff altitude.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
takeoffHeight	`float`	No	-10	Target takeoff altitude, in meters

Return Value (Returns): No return value
Exceptions (Raises): None

`sendDllPosNeD(x=0, y=0, z=0, yaw=0)`¶

Function Description: Sends position setpoints and desired yaw angle in the North-East-Down (NED) coordinate system to the flight controller for position control.
Parameters (Args):

Parameter Name	Type	Required	Description
x	`float`	No	Position along the x-axis (East direction) in the NED coordinate system, in meters
y	`float`	No	Position along the y-axis (North direction) in the NED coordinate system, in meters
z	`float`	No	Position along the z-axis (Down direction) in the NED coordinate system, in meters
yaw	`float`	No	Desired yaw angle, in radians

Return Value (Returns): No return value
Exceptions (Raises): None

`sendDllPosNedNoYaw(x=0, y=0, z=0)`¶

Function Description: Sends position setpoints in the North-East-Down (NED) coordinate system to the flight controller without specifying a desired yaw angle, maintaining the current yaw angle, for position control.
Parameters (Args):

Parameter Name	Type	Required	Description
x	`float`	No	Position along the x-axis (East direction) in the NED coordinate system, in meters
y	`float`	No	Position along the y-axis (North direction) in the NED coordinate system, in meters
z	`float`	No	Position along the z-axis (Down direction) in the NED coordinate system, in meters

Return Value (Returns): No return value
Exceptions (Raises): None

`sendDllVelFRD(vx=0, vy=0, vz=0, yawRate=0)`¶

Function Description: Sends velocity setpoints and desired yaw rate in the Front-Right-Down (FRD) body-fixed coordinate system to the flight controller for velocity control.
Parameters (Args):

Parameter Name	Type	Required	Description
vx	`float`	No	Velocity along the x-axis (Forward direction) in the FRD coordinate system, in m/s
vy	`float`	No	Velocity along the y-axis (Right direction) in the FRD coordinate system, in m/s
vz	`float`	No	Velocity along the z-axis (Down direction) in the FRD coordinate system, in m/s
yawRate	`float`	No	Desired yaw rate, in rad/s

Return Value (Returns): No return value
Exceptions (Raises): None

`sendDllVelNEDNoYaw(vx=0, vy=0, vz=0)`¶

Function Description: Sends velocity setpoints in the North-East-Down (NED) coordinate system to the flight controller without specifying a yaw rate, maintaining the current yaw angle, for velocity control.
Parameters (Args):

Parameter Name	Type	Required	Description
vx	`float`	No	Velocity along the x-axis (East direction) in the NED coordinate system, in m/s
vy	`float`	No	Velocity along the y-axis (North direction) in the NED coordinate system, in m/s
vz	`float`	No	Velocity along the z-axis (Down direction) in the NED coordinate system, in m/s

Return Value (Returns): No return value
Exceptions (Raises): None

`RflySimCP` Class¶

RflySim Comprehensive Model Control Protocol, defining various parameter constants for the RflySim control communication protocol.

`init()`¶

Function Description: Initializes an instance of the RflySim Comprehensive Model Control Protocol.
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`IsBitSet(num, bit)`¶

Function Description: Checks whether a specified bit is set in the given integer.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
num	int	Yes	N/A	Integer to be checked
bit	int	Yes	N/A	Specified bit position

Return Value (Returns): bool: Returns True if the specified bit is set, otherwise returns False.
Exceptions (Raises): None

`IsPosSet(num)`¶

Function Description: Checks whether position control is enabled.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
num	int	Yes	N/A	Integer to be checked

Return Value (Returns): bool: Returns True if position control is enabled; otherwise, returns False.
Exceptions (Raises): None

`getPosNED(x=0, y=0, z=0, yaw=0)`¶

Function Description: Generates a combined position and yaw control command in the North-East-Down (NED) coordinate frame.
Parameters (Args):

Parameter Name	Type	Required	Description
x	float	No	Position in the North direction (origin of NED frame is the reference point)
y	float	No	Position in the East direction
z	float	No	Position in the Down direction
yaw	float	No	Desired yaw angle in radians (0 rad points North, increases clockwise)

Return Value (Returns): Packaged control command values
Exceptions (Raises): None

`getPosLocal(x=0, y=0, z=0, yaw=0)`¶

Function Description: Generates a combined position and yaw control command in the local coordinate frame.
Parameters (Args):

Parameter Name	Type	Required	Description
x	float	No	Position in the X direction (origin of ENU frame is the takeoff point)
y	float	No	Position in the Y direction
z	float	No	Position in the Down direction
yaw	float	No	Desired yaw angle in radians (0 rad points North, increases clockwise)

Return Value (Returns): Packaged control command values
Exceptions (Raises): None

`getVelNedNoYaw(northvel=0, eastvel=0, downvel=0)`¶

**Function Description

Return Value (Returns): None
Exceptions (Raises): None

`SendSynAtt(roll, pitch, yaw)`¶

Function Description: Synchronously sends a desired attitude command with no delay.
Parameters (Args):

Return Value (Returns): None
Exceptions (Raises): None

`TakeoffSyn(height)`¶

Function Description: Synchronously sends a takeoff command with no delay, ascending to the specified height.
Parameters (Args):

Return Value (Returns): None
Exceptions (Raises): None

`ReturnHomeSyn(height)`¶

Function Description: Synchronously sends a return-to-home command with no delay; first flies to the home point while maintaining the specified altitude.
Parameters (Args):

Return Value (Returns): None
Exceptions (Raises): None

`LandSyn(height=0)`¶

Function Description: Synchronously sends a landing command with no delay, descending to the specified height.
Parameters (Args):

| Parameter Name | Type | Required | Default | Description | | :--- | :---: | :--- | :--- | | height | float | No | 0 | Target landing height |

Return Value (Returns): None
Exceptions (Raises): None

`SendPosSpeedFWSyn(x, y, z, speed)`¶

Function Description: Synchronously sends position and velocity commands for the fixed-wing integrated model, specifying both desired position and desired flight speed, with no command delay.
Parameters (Args):

Return Value (Returns): None
Exceptions (Raises): None

`ResetSynCmd()`¶

Function Description: Resets the state of the synchronous command.
Parameters (Args): No arguments
Return Value (Returns): None
Exceptions (Raises): None

`ModelLoad` Class¶

A utility class for loading custom aircraft models into the RflySim simulation environment.

`init(dll_name, CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])`¶

Function Description: Constructs a model loading object, connects to the simulation environment, and loads the specified aircraft model at the designated location.
Parameters (Args):

Parameter Name	Type	Default	Description
dll_name	-	None	Filename of the dynamic-link library (DLL) for the model to be loaded
CopterID	-	1	ID number assigned to the loaded aircraft, used to distinguish between multiple aircraft in multi-vehicle scenarios
ClassID	-	-1	Aircraft class ID; -1 indicates automatic assignment
MapName	-	"Grasslands"	Name of the target simulation scene
ip	-	"127.0.0.1"	IP address where the simulation service is running
LocX	-	0	Initial X-coordinate (east direction) in the local East-North-Up (ENU) coordinate system, in meters
LocY	-	0	Initial Y-coordinate (north direction) in the local East-North-Up (ENU) coordinate system, in meters
Yaw	-	0	Initial yaw angle of the model, in degrees
UdpMode	-	0	UDP communication mode; 0 indicates the default mode
useGPS	-	False	Whether to enable GPS simulation for this model
GpsOrin	-	[0, 0, 0]	Offset of the GPS sensor relative to the body frame origin, in the order of forward/backward, left/right, up/down

Return Value (Returns): None
Exceptions (Raises): None

`CreateVehicle(CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])`¶

Function Description: Creates a UAV vehicle in the 3D simulation scene.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	Any	No	1	Drone ID number
ClassID	Any	No	-1	Drone model ID; -1 indicates the default model
MapName	Any	No	Grasslands	Name of the loaded scene map
ip	Any	No	127.0.0.1	IP address for connecting to the simulation service
LocX	Any	No	0	Initial X-coordinate of the drone
LocY	Any	No	0	Initial Y-coordinate of the drone
Yaw	Any	No	0	Initial yaw angle of the drone
UdpMode	Any	No	0	UDP communication mode; 0 indicates the default mode
useGPS	Any	No	False	Whether to enable GPS simulation
GpsOrin	Any	No	[0, 0, 0]	Initial GPS offset

Return Value (Returns): None
Exceptions (Raises): None

`Updata3Doutput()`¶

Function Description: Updates output data for the 3D scene
Parameters (Args): No parameters
Return Value (Returns): None
Exceptions (Raises): None

`SendUpdate3DMap(isSetSpeed=False)`¶

Function Description: Sends map update information to the 3D simulation scene; optionally sets the simulation speed
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
isSetSpeed	Any	No	False	Whether to update and set the simulation run speed

Return Value (Returns): None
Exceptions (Raises): None

`get3DDataBuf()`¶

Function Description: Retrieves the 3D scene data buffer
Parameters (Args): No parameters
Return Value (Returns): 3D scene data buffer object
Exceptions (Raises): None

`Send3DData()`¶

Function Description: Sends 3D scene data to the simulation service
Parameters (Args): No parameters
Return Value (Returns): None
Exceptions (Raises): None

`SendSimData()`¶

Function Description: Sends simulation data to the flight controller
Parameters (Args): No parameters
Return Value (Returns): None
Exceptions (Raises): None

`SendHILData()`¶

Function Description: Sends Hardware-in-the-Loop (HIL) simulation data
Parameters (Args): No parameters
Return Value (Returns): None
Exceptions (Raises): None

`SendOutCopter()`¶

Function Description: Sends drone status data output
Parameters (Args): No parameters
Return Value (Returns): None
Exceptions (Raises): None

`fillList(data, inLen, fill=0)`¶

Function Description: Pads a list to a specified length using a specified value
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
data	Any	Yes	None	Original list to be padded
inLen	Any	Yes	None	Target length after padding
fill	Any	No	0

Parameter Name	Type	Required	Default Value	Description
in_floats_collision	None	No	`[0] * 20`	Collision input floating-point data

Return Value (Returns): None
Exceptions (Raises): None

`DllTerrainIn15d(terrain15d)`¶

Function Description: Inputs terrain height data
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
terrain15d	None	No	`[0] * 15`	15-dimensional terrain height data

Return Value (Returns): None
Exceptions (Raises): None

`DllInitGpsPos(gps)`¶

Function Description: Inputs the origin coordinates of the GPS position
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
gps	None	No	`[0] * 3`	GPS origin latitude, longitude, and altitude data

Return Value (Returns): None
Exceptions (Raises): None

`DllInitPosAngState(init_pos_offset, init_ang_offset)`¶

Function Description: Initializes position and attitude angle states
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
init_pos_offset	None	No	`[0, 0, 0]`	Initial position offset
init_ang_offset	None	No	`[0, 0, 0]`	Initial attitude angle offset

Return Value (Returns): None
Exceptions (Raises): None

`DllInputDoubCtrls(in_doub_ctrls)`¶

Function Description: Inputs control command data
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
in_doub_ctrls	None	No	`[0] * 28`	28-dimensional double-precision control command data

Return Value (Returns): None
Exceptions (Raises): None

`DllinSIL28d(in_doub_ctrls)`¶

Function Description: Inputs control command data
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
in_doub_ctrls	None	No	`[0] * 28`	28-dimensional double-precision control command data

Return Value (Returns): None
Exceptions (Raises): None

`DllInCtrlExt(in_ctrl_ext)`¶

Function Description: Inputs fault injection data
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
in_ctrl_ext	None	No	`[0] * 140`	140-dimensional extended control fault injection data

Return Value (Returns): None
Exceptions (Raises): None

`DllInFromUE(in_from_ue)`¶

Function Description: Inputs UE data into the DLL
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
in_from_ue	None	No	`[0] * 32`	32-dimensional input data from UE

Return Value (Returns): None
Exceptions (Raises): None

`DllInputColls(inCll)`¶

Function Description: Inputs collision data into the DLL
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
inCll	None	No	`[0] * 20`	20-dimensional collision input data

Return Value (Returns): None
Exceptions (Raises): None

`DllGetStep0()`¶

Function Description: Retrieves the simulation step size
Parameters (Args): None
Return Value (Returns): Simulation step size value
Exceptions (Raises): None

`Dllstep()`¶

Function Description: Executes one simulation step
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`ModelUpdate(step_time)`¶

Function Description: Executes simulation for step_time seconds
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
step_time	None	Yes	N/A	Simulation duration to advance, in seconds

Return Value (Returns): None
Exceptions (Raises): None

`DlloutVehileInfo60d()`¶

Function Description: Exports 60-dimensional vehicle information data
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`DllOutCopterData()`¶

Function Description: Exports simulation data for multi-rotor aircraft
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`SendPosNED(x=0, y=0, z=0, yaw=0)`¶

Function Description: Sends position and yaw angle commands in the NED coordinate system
Parameters (Args):

Parameter Name	Type	Required	Description
x	None	No	Position coordinate in the North direction in the NED coordinate system
y	None	No	Position coordinate in the East direction in the NED coordinate system
z	None	No	Position coordinate in the Down direction in the NED coordinate system
yaw	None	No	Yaw angle

Return Value (Returns): None
Exceptions (Raises): None

`SendPosLocal(x=0, y=0, z=0, yaw=0)`¶

Function Description: Sends position and yaw angle commands in the local coordinate system
Parameters (Args):

Parameter Name	Type	Required	Description
x	None	No	Position coordinate in the x-direction in the local coordinate system
y	None	No	Position coordinate in the y-direction in the local coordinate system
z	None	No	Position coordinate in the z-direction in the local coordinate system
yaw	None	No	Yaw angle

Return Value (Returns): None
Exceptions (Raises): None

`SendVelNED(vx=0, vy=0, vz=0, yawRate=0)`¶

Function Description: Sends velocity and yaw rate commands in the NED coordinate system
Parameters (Args):

Parameter Name	Type	Required	Description
vx	None	No	Velocity in the North direction in the NED coordinate system
vy	None	No	Velocity in the East direction in the NED coordinate system
vz	None	No	Velocity in the Down direction in the NED coordinate system
yawRate	None	No	Yaw rate

Return Value (Returns): None
Exceptions (Raises): None

`SendVelFRD(vx=0, vy=0, vz=0, yawRate=0)`¶

Function Description: Sends velocity and yaw rate commands in the body-fixed FRD coordinate system
Parameters (Args):

Parameter Name	Type	Required	Description
vx	None	No	Velocity in the Forward direction in the FRD coordinate system
vy	None	No	Velocity in the Right direction in the FRD coordinate system
vz	None	No	Velocity in the Down direction in the FRD coordinate system
yawRate	None	No	Yaw rate

Return Value (Returns): None
Exceptions (Raises): None

`SendVelNEDNoYaw(northvel=0, eastvel=0, downvel=0)`¶

Function Description: Sends velocity commands in the NED coordinate system (without yaw rate)
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
northvel	None	No	0	Velocity in the North direction in the NED coordinate system
eastvel	None	No	0	Velocity in the East direction

import RflySimSDK.ctrl as rfly_ctrl
import threading

# Example of batch networked asynchronous control for multiple UAVs
def batch_vehicle_control(vehicle_configs):
    # 1. Batch-create multiple UAVs
    model_loader = rfly_ctrl.ModelLoad()
    vehicle_list = []
    for config in vehicle_configs:
        veh = model_loader.CreateVehicle(config["model_path"], config["init_pos"])
        vehicle_list.append(veh)
        # Populate the model input parameter list
        sim_ctrl = rfly_ctrl.DllSimCtrlAPI()
        sim_ctrl.fillList()
        # Send initialization parameters
        sim_ctrl.sendInitInParams(config["init_params"])

    # 2. Asynchronously update 3D scene visualization without blocking control logic
    def async_update_visual():
        data_3d = rfly_ctrl.Data3D()
        while True:
            output_buf = model_loader.get3DDataBuf()
            model_loader.Updata3Doutput(output_buf)
            data_3d.updateUdp()
            model_loader.SendUpdate3DMap()

    update_thread = threading.Thread(target=async_update_visual, daemon=True)
    update_thread.start()

    # 3. Multi-class collaboration for heterogeneous control: fixed-wing and multi-rotor simultaneously send differently formatted control commands
    rfly_cp = rfly_ctrl.RflySimCP()
    for idx, veh in enumerate(vehicle_list):
        if veh.type == "multicopter":
            # Send multi-rotor extended double-precision control commands
            sim_ctrl.sendInCtrlExtDoub(idx, veh.thrust, veh.attitude)
        else:
            # Send fixed-wing mixed integer and floating-point control commands
            sim_ctrl.sendSILIntFloat(idx, veh.mode, veh.aileron, veh.elevator)
        # Synchronize aircraft state data
        pos = rfly_cp.getPosNED(veh.id)
        vel = rfly_cp.getVelNED(veh.id)
        rfly_cp.SendSynFull(veh.id, pos, vel, rpy=veh.attitude)

if __name__ == "__main__":
    # Configure a networked mission with 3 UAVs
    configs = [
        {"model_path": "copter_x.param", "init_pos": [0,0,0], "init_params": {}},
        {"model_path": "plane_a.param", "init_pos": [5,0,0], "init_params": {}},
        {"model_path": "copter_y.param", "init_pos": [0,5,0], "init_params": {}}
    ]
    batch_vehicle_control(configs)

Notes and Pitfall Avoidance Guide¶

Parameter Initialization Prerequisite: Before calling any control command transmission method of the DllSimCtrlAPI class, the fillList method must be invoked first to initialize the parameter list; otherwise, empty data will be sent, causing simulation anomalies.
3D Visualization Update Timing: To enable automatic 3D scene updates, ModelLoad.StartAutUpdate must be called. If custom asynchronous updates are used, avoid repeatedly calling both Send3DData and StartAutUpdate, as this may result in duplicate data transmission and cause screen lag.
Prerequisite for Pose State Reading: Before invoking state-reading methods such as getPosNED and getVelNED of the RflySimCP class, ensure that simulation data synchronization has been completed; otherwise, erroneous zero-valued state data will be returned.
Memory Management for Batch Operations: After batch-creating multiple UAVs, if the simulation needs to be reloaded, existing instance objects must be cleared and fillList must be called again; otherwise, residual old parameters may mix into new control commands, leading to control errors.

Changelog¶

2026-03-03: feat: SDK adds IP handling mechanism for compatibility with cloud deployment of the local version
2025-12-05: feat: 1. Added NED position and velocity setting interfaces for integrated models; 2. Added asynchronous command execution and message buffer size configuration for distSimCtrlAPI
2024-09-12: feat: Added interface for sending relative positions
2024-09-12: feat: Added SendVelFRD interface
2024-09-06: fix: Added call relationship diagram on API page
2024-09-06: fix: Updated API
2024-08-31: fix: Updated DLL control library
2024-07-26: fix: Updated API homepage
2024-07-24: fix: Refactored DLL model-related function descriptions and introductions
2024-07-23: fix: Fixed bugs
2024-07-22: fix: Fixed broken interfaces
2024-06-18: fix: Adjusted API formatting
2024-06-12: fix: Updated interface comments
2024-06-05: fix: Updated doxygen-generated documentation
2024-06-05: fix: Updated comments for DLLSimCtrlAPI

DllSimCtrlAPI Interface Documentation¶

Introduction¶

Quick Start¶

Environment and Dependencies¶

Core Interface Description¶

Global Constants and Enumerations¶

Standalone Constants¶

Global/Standalone Functions¶

Data3D Class¶

__init__(copter_data=None, CopterID=-1, ClassID=-1)¶

update(copter_data, CopterID=-1, ClassID=-1)¶

updateUdp(UIV)¶

DataHIL Class¶

__init__()¶

DllSimCtrlAPI Class¶

__init__(self, CopterID=1, ip="127.0.0.1")¶

fillList(data, inLen)¶

sendCustomData(CopterID=0, data=[0] * 16, checksum=123456, port=50000, IP="127.0.0.1")¶

sendInDoubCtrls(inDoubsCtrls=[0] * 28, copterID=-1)¶

sendInCtrlExt(inSILInts=[0] * 8, inSILFLoats=[0] * 20, iDxNum=1, copterID=-1)¶

sendInCtrlExtDoub(inDoubsCtrls=[0] * 28, iDxNum=1, copterID=-1, update=True)¶

sendInCtrlExtAll(inDoubsCtrls=[0] * 140, copterID=-1)¶

sendModelInParams(Bitmask, InParams, copterID=-1)¶

sendInitInParams(Bitmask=0, InParams=[0] * 32, copterID=-1)¶

sendDynModiParams(Bitmask=0, InParams=[0] * 64, copterID=-1)¶

sendTerrIn15d(TerrIn15d=[0] * 15, copterID=-1)¶

sendDllTakeoff(takeoffHeight=-10)¶

sendDllPosNeD(x=0, y=0, z=0, yaw=0)¶

sendDllPosNedNoYaw(x=0, y=0, z=0)¶

sendDllVelFRD(vx=0, vy=0, vz=0, yawRate=0)¶

sendDllVelNEDNoYaw(vx=0, vy=0, vz=0)¶

RflySimCP Class¶

__init__()¶

IsBitSet(num, bit)¶

IsPosSet(num)¶

getPosNED(x=0, y=0, z=0, yaw=0)¶

getPosLocal(x=0, y=0, z=0, yaw=0)¶

getVelNedNoYaw(northvel=0, eastvel=0, downvel=0)¶

SendSynAtt(roll, pitch, yaw)¶

TakeoffSyn(height)¶

ReturnHomeSyn(height)¶

LandSyn(height=0)¶

SendPosSpeedFWSyn(x, y, z, speed)¶

ResetSynCmd()¶

ModelLoad Class¶

__init__(dll_name, CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])¶

CreateVehicle(CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])¶

Updata3Doutput()¶

SendUpdate3DMap(isSetSpeed=False)¶

get3DDataBuf()¶

Send3DData()¶

SendSimData()¶

SendHILData()¶

SendOutCopter()¶

fillList(data, inLen, fill=0)¶

DllTerrainIn15d(terrain15d)¶

DllInitGpsPos(gps)¶

DllInitPosAngState(init_pos_offset, init_ang_offset)¶

DllInputDoubCtrls(in_doub_ctrls)¶

DllinSIL28d(in_doub_ctrls)¶

DllInCtrlExt(in_ctrl_ext)¶

DllInFromUE(in_from_ue)¶

DllInputColls(inCll)¶

DllGetStep0()¶

Dllstep()¶

ModelUpdate(step_time)¶

DlloutVehileInfo60d()¶

DllOutCopterData()¶

SendPosNED(x=0, y=0, z=0, yaw=0)¶

SendPosLocal(x=0, y=0, z=0, yaw=0)¶

SendVelNED(vx=0, vy=0, vz=0, yawRate=0)¶

SendVelFRD(vx=0, vy=0, vz=0, yawRate=0)¶

SendVelNEDNoYaw(northvel=0, eastvel=0, downvel=0)¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`Data3D` Class¶

`init(copter_data=None, CopterID=-1, ClassID=-1)`¶

`update(copter_data, CopterID=-1, ClassID=-1)`¶

`updateUdp(UIV)`¶

`DataHIL` Class¶

`init()`¶

`DllSimCtrlAPI` Class¶

`init(self, CopterID=1, ip="127.0.0.1")`¶

`fillList(data, inLen)`¶

`sendCustomData(CopterID=0, data=[0] * 16, checksum=123456, port=50000, IP="127.0.0.1")`¶

`sendInDoubCtrls(inDoubsCtrls=[0] * 28, copterID=-1)`¶

`sendInCtrlExt(inSILInts=[0] * 8, inSILFLoats=[0] * 20, iDxNum=1, copterID=-1)`¶

`sendInCtrlExtDoub(inDoubsCtrls=[0] * 28, iDxNum=1, copterID=-1, update=True)`¶

`sendInCtrlExtAll(inDoubsCtrls=[0] * 140, copterID=-1)`¶

`sendModelInParams(Bitmask, InParams, copterID=-1)`¶

`sendInitInParams(Bitmask=0, InParams=[0] * 32, copterID=-1)`¶

`sendDynModiParams(Bitmask=0, InParams=[0] * 64, copterID=-1)`¶

`sendTerrIn15d(TerrIn15d=[0] * 15, copterID=-1)`¶

`sendDllTakeoff(takeoffHeight=-10)`¶

`sendDllPosNeD(x=0, y=0, z=0, yaw=0)`¶

`sendDllPosNedNoYaw(x=0, y=0, z=0)`¶

`sendDllVelFRD(vx=0, vy=0, vz=0, yawRate=0)`¶

`sendDllVelNEDNoYaw(vx=0, vy=0, vz=0)`¶

`RflySimCP` Class¶

`init()`¶

`IsBitSet(num, bit)`¶

`IsPosSet(num)`¶

`getPosNED(x=0, y=0, z=0, yaw=0)`¶

`getPosLocal(x=0, y=0, z=0, yaw=0)`¶

`getVelNedNoYaw(northvel=0, eastvel=0, downvel=0)`¶

`SendSynAtt(roll, pitch, yaw)`¶

`TakeoffSyn(height)`¶

`ReturnHomeSyn(height)`¶

`LandSyn(height=0)`¶

`SendPosSpeedFWSyn(x, y, z, speed)`¶

`ResetSynCmd()`¶

`ModelLoad` Class¶

`init(dll_name, CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])`¶

`CreateVehicle(CopterID=1, ClassID=-1, MapName="Grasslands", ip="127.0.0.1", LocX=0, LocY=0, Yaw=0, UdpMode=0, useGPS=False, GpsOrin=[0, 0, 0])`¶

`Updata3Doutput()`¶

`SendUpdate3DMap(isSetSpeed=False)`¶

`get3DDataBuf()`¶

`Send3DData()`¶

`SendSimData()`¶

`SendHILData()`¶

`SendOutCopter()`¶

`fillList(data, inLen, fill=0)`¶

`DllTerrainIn15d(terrain15d)`¶

`DllInitGpsPos(gps)`¶

`DllInitPosAngState(init_pos_offset, init_ang_offset)`¶

`DllInputDoubCtrls(in_doub_ctrls)`¶

`DllinSIL28d(in_doub_ctrls)`¶

`DllInCtrlExt(in_ctrl_ext)`¶

`DllInFromUE(in_from_ue)`¶

`DllInputColls(inCll)`¶

`DllGetStep0()`¶

`Dllstep()`¶

`ModelUpdate(step_time)`¶

`DlloutVehileInfo60d()`¶

`DllOutCopterData()`¶

`SendPosNED(x=0, y=0, z=0, yaw=0)`¶

`SendPosLocal(x=0, y=0, z=0, yaw=0)`¶

`SendVelNED(vx=0, vy=0, vz=0, yawRate=0)`¶

`SendVelFRD(vx=0, vy=0, vz=0, yawRate=0)`¶

`SendVelNEDNoYaw(northvel=0, eastvel=0, downvel=0)`¶