ReqCopterSim Interface Documentation¶

Introduction¶

Overview: UE4 drone simulation state synchronization and request module, providing EKF initialization detection, timestamp synchronization, and multi-drone simulation state querying capabilities.

This module is specifically designed for the RflySim drone simulation platform's UE4 3D scene, addressing state synchronization challenges in multi-drone collaborative simulations. Core scenarios include: distributed simulation EKF (Extended Kalman Filter) initialization state detection across multiple drones, timestamp synchronization between the UE4 engine and CopterSim, and batch querying of 3D position fix status for all drones (allCopterSim3DFixed). The module implements non-blocking state polling via classes Ue4EKFInit and GetUe4EKFInit. Class RflyTimeStmp supports sending timestamp-synchronization messages with checksums to port 20005 on a specified remote host. ReqCopterSim encapsulates the request-response protocol with the CopterSim simulation core, making it suitable for hardware-in-the-loop (HIL) simulations and visual-inertial navigation algorithm validation scenarios requiring precise timing control.

Quick Start¶

The following example creates a request instance in a non-blocking manner and obtains the local LAN address, which can serve as an initialization step for a distributed simulation control program.

Reference example: [RflySim installation path]\RflySimAPIs\10.RflySimSwarm\3.CustExps\e0.CustApiExps\2.DistSimCommAPIExps\1.HelloWorldTestExp

import ReqCopterSim


# False means simulation messages are not continuously updated, reducing initialization wait time
req = ReqCopterSim.ReqCopterSim(False)
localIp = req.getLocalIp()
print("Local IP:", localIp)

Environment & Dependencies¶

Python Environment: >= 3.8.10
Dependencies: copy, os, psutil, re, socket, struct, threading, time
Prerequisites: Before calling this interface, a simulation environment connection must first be established via UE4 or CopterSim.

Core Interface Description¶

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

Global Constants and Enumerations¶

This section lists all globally accessible constants and enumerations directly referenceable within the module.

Standalone Constants¶

None

Global/Standalone Functions¶

None

`Ue4EKFInit` Class¶

This class initializes the EKF (Extended Kalman Filter) state within the UE4 scene, typically resetting pose estimation before drone simulation begins.

`init()`¶

Function Description: Initializes an Ue4EKFInit instance, preparing EKF initialization functionality.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
-	-	-	-	No parameters required

Returns:

Ue4EKFInit instance object

Raises:

None

`reset()`¶

Function Description: Resets the EKF state in the UE4 scene, restoring pose estimation to its initial values.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
-	-	-	-	No parameters required

Returns:

None

Raises:

None

Example:

ekf_init = Ue4EKFInit()
# Reset EKF before simulation starts
ekf_init.reset()

`GetUe4EKFInit` Class¶

This class is used to initialize and continuously detect the 3D fixed state of all CopterSim instances. Detection starts immediately after initialization; external code must periodically query the allCopterSim3DFixed property to obtain the detection results.

`init(expected_copter_ids, localIp="None")`¶

Function Description: Initializes the detector and begins detecting the 3D fixed state of all specified CopterSim instances.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
`expected_copter_ids`	`list`	Yes	-	List of CopterSim IDs to be detected
`localIp`	`str`	No	`"None"`	Local IP address used for network communication

Returns:

Instance of GetUe4EKFInit

Raises:

None

`RflyTimeStmp` Class¶

RflyTimeStmp is a timestamp data structure for the RflySim simulation platform, primarily used for time synchronization in heartbeat packets. This structure contains the simulation start time, current timestamp, and heartbeat counter, and is transmitted via UDP to port 20005 on a specified remote computer, enabling time synchronization and heartbeat monitoring in multi-machine collaborative simulations.

`init(iv)`¶

Function Description: Initializes an RflyTimeStmp instance, setting up timestamp-related member variables based on the input parameters.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
`iv`	`list`	Yes	-	List containing timestamp data, formatted as `[checksum, copterID, SysStartTime, SysCurrentTime, HeartCount]`

Returns:

Instance of RflyTimeStmp

Raises:

None

`Update(iv)`¶

Function Description: Updates the timestamp data of an RflyTimeStmp instance, enabling dynamic updates for heartbeat packet data.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
`iv`	`list`	Yes	-	List containing updated timestamp data, formatted as `[checksum, copterID, SysStartTime, SysCurrentTime, HeartCount]`

Returns:

None

Raises:

None

Example:

# Create a timestamp instance
timestamp_data = [123456789, 1, 1699123456789, 1699123466789, 100]
rfly_ts = RflyTimeStmp(timestamp_data)

# Update heartbeat data
new_data = [123456789, 1, 1699123456789, 1699123476789, 101]
rfly_ts.Update(new_data)

`ReqCopterSim` Class¶

A request class for communicating with the RflySim simulation environment, primarily responsible for listening on a specified port to obtain simulation timestamp information.

`init(updateMsg=True)`¶

Function Description: Initializes a ReqCopterSim instance and starts listening on port 20005 to receive RflyTimeStmp messages, thereby obtaining the simulation time information for a specified UAV.

Arguments (Args):

Parameter Name	Type	Default Value	Description
`updateMsg`	`bool`	`True`	Whether to enable message update functionality; when set to `True`, the class automatically listens and updates messages

Returns (Returns):

Type	Description
`None`	Constructor returns no value

Raises (Raises):

Exception Type	Description
`socket.error`	Thrown when binding or listening on port 20005 fails
`OSError`	Thrown when network interface initialization fails

`getLocalIp()`¶

Function Description: Retrieves the local IP address. It first attempts to connect to 8.8.8.8 to determine the local IP; if that fails, it tries 114.114.114.114; if both fail, it returns 127.0.0.1.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): str — Local IP address string, e.g., "192.168.1.100"

Raises (Raises): None

`isValidIp(address)`¶

Function Description: Validates whether the given string is a valid IPv4 address.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
`address`	`str`	Yes	—	The IP address string to validate

Returns (Returns): bool — Returns True if address is a valid IPv4 address, otherwise False

Raises (Raises): None

`get_all_ip()`¶

Function Description: Retrieves a list of IPv4 addresses for all network interfaces on this machine, including 127.0.0.1.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): list[str] — List containing all IPv4 addresses

Raises (Raises): None

`get_all_enable_ip()`¶

Function Description: Retrieves a list of IPv4 addresses for all enabled (active) network interfaces on this machine. Filters out disabled or disconnected interfaces.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): list[str] — List containing all enabled IPv4 addresses

Raises (Raises): None

`isIpLocal(IP)`¶

Function Description: Determines whether the given IP address is a local address (including 127.0.0.1 and all local network interface IPs).

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
`IP`	`str`	Yes	—	The IP address string to check

Returns (Returns): bool — Returns True if IP is a local address, otherwise False

Raises (Raises): None

`getAllCopterID()`¶

Function Description: Retrieves a list of all registered/active Copter (drone) IDs in the current system.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): list[int] — List containing all Copter IDs

Raises (Raises): None

`updateSimMsg()`¶

Function Description: Updates (receives and processes) simulation messages from CopterSim. This method receives UDP packets and updates the internal simulation state information.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): None

Raises (Raises): None

`getSimIpList()`¶

Function Description: Retrieves a list of IP addresses for all currently registered simulations.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): list[str] — List containing all simulation IP addresses

Raises (Raises): None

`getSimIpID(CopterID=1)`¶

Function Description: Retrieves the simulation IP address corresponding to a given Copter ID. Returns an empty string if the ID is not found.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	`int`	No	1	The UAV ID to query

Returns (Returns): str — Simulation IP address corresponding to the given ID; empty string if not found
Raises (Raises): None

`getHostIP()`¶

Function Description: Retrieves the host (Host) IP address. Similar to getLocalIp(), but may employ different strategies depending on specific network configurations.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description

No parameters

Returns (Returns): str — Host IP address string
Raises (Raises): None

`sendReCopterSim(CopterID=1, isReqIP=1, UDP_mode=-1, isXyYaw=0, xyYaw=[0, 0, 0], isZRP=0, zRollPitch=[0, 0, 0], otherParams=[0, 0, 0, 0])`¶

Function Description: Sends a request message to CopterSim to reconfigure simulation parameters, including requesting IP, setting initial position, modifying UDP mode, etc. Supports multiple advanced configurations such as GPS origin setting and GPS position setting.

Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	`int`	No	1	Target UAV ID for request validation
isReqIP	`int`	No	1	Whether to request IP. >0 enables online connection and sends flight controller data to this computer
UDP_mode	`int`	No	-1	UDP transmission mode. <0: no response; ≥0: change to specified mode
isXyYaw	`int`	No	0	Whether to set XY position and yaw angle. >0 uses xyYaw values to redeploy aircraft position. Special values: 2 sets GPS origin (lat/lon/alt); 3 sets GPS position (lat/lon/yaw)
xyYaw	`list[float]`	No	[0, 0, 0]	XY position and yaw angle [x, y, yaw], in meters and degrees. When isXyYaw=2: [lat, lon, alt]; when isXyYaw=3: [lat, lon, yaw]
isZRP	`int`	No	0	Whether to set Z altitude and roll/pitch angles. >0 uses zRollPitch values; otherwise, Z aligns with terrain and roll/pitch angles are 0
zRollPitch	`list[float]`	No	[0, 0, 0]	Z altitude, roll angle, pitch angle [z, roll, pitch], in meters and degrees; Z direction is positive downward
otherParams	`list[int]`	No	[0, 0, 0, 0]	Reserved parameters, 4 bytes total, for future use