distSimCtrlAPI Interface Documentation¶

Introduction¶

Overview: This file provides control interfaces for distributed cluster simulation, defining the data structures and core control classes required for distributed simulation. It supports distributed deployment and coordinated control of multi-machine cluster simulation tasks.

In multi-UAV cluster simulation tasks, when the simulation scale is large and the computational power of a single computing node is insufficient to support the entire network simulation, it is typically necessary to split the simulation task across multiple computing nodes for distributed execution, thereby enhancing simulation performance and enabling support for larger-scale cluster tasks. As the core control interface of the RflySim platform’s distributed cluster simulation, this module defines both foundational data structures for storing distributed node information and handling asynchronous callbacks, as well as core API functions for distributed simulation. It meets the distributed deployment requirements of UAV cluster simulations of varying scales and helps developers quickly build cross-node collaborative UAV cluster simulation environments.

Quick Start¶

The following example scans for DistSim nodes on the LAN, displays node information, and sends a command to the specified node after user confirmation.

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

import ReqCopterSim
import distSimCtrlAPI


req = ReqCopterSim.ReqCopterSim(False)
localIp = req.getLocalIp()
distCtrl = distSimCtrlAPI.distSimCtrlAPI(localIp)

nodes = distCtrl.scan_udp()
for index, node in enumerate(nodes, start=1):
    print(index, node.nodeIp, node.getOsTypeName(), node.getHostname())

input("Press Enter to send test command to all nodes")
status, result = distCtrl.executeCommand("echo Hello world! Every Computer")
print(status, result)

Environment and Dependencies¶

Python Environment: >= 3.8.10
Dependencies: ctrl.IpManager, distsim.DistSim_pb2, os, queue, socket, threading, time, typing
Prerequisites: Before calling this interface, ensure that the RflySimSDK environment has been configured and all required dependencies have been loaded.

Core Interface Description¶

The module distSimCtrlAPI.py includes 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 in the module.

Standalone Constants¶

Variable Name	Type	Value	Description
`MCAST_GADDR`	`str`	`'224.0.0.10'`	-
`MCAST_PORT`	`int`	`9000`	-
`ANY`	`str`	`'0.0.0.0'`	-
`DISTSIM_SUM`	`int`	`12345678`	-
`COMMON_SEND_PORT`	`int`	`8800`	-
`COMMON_BIND_PORT`	`int`	`8801`	-
`MSG_BUFFER_SIZE`	`int`	`2048`	-

Global / Standalone Functions¶

None

`NodeData` Class¶

Used to store connection information and heartbeat data for a single node in a distributed simulation cluster. It manages storage and updates of basic node information, commonly used in node management scenarios for multi-machine cluster distributed simulations.

`init(nodeIp, nodePort=None)`¶

Function Description: Initializes the node data object, recording the node’s IP address and port information.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`nodeIp`	`str`	Yes	-	IP address of the distributed node
`nodePort`	`int`	No	`None`	Communication port of the distributed node

Return Value (Returns):

NodeData instance object

Exceptions (Raises): None

`updateHeartBeat(heartBeatMsgData)`¶

Function Description: Updates the node’s heartbeat message data, refreshing the node’s online status and latest information.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`heartBeatMsgData`	`dict`	Yes	-	Latest node heartbeat message data, including system and name information

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

`getOsTypeName()`¶

Function Description: Retrieves the name of the current node’s operating system type.
Parameters (Args): None
Return Value (Returns):

str: Operating system type name of the node, corresponding to definitions in OsTypeMap

Exceptions (Raises): None

`getHostname()`¶

Function Description: Retrieves the hostname of the current node.
Parameters (Args): None
Return Value (Returns):

str: Hostname string of the node

Exceptions (Raises): None

`getNodename()`¶

Function Description: Retrieves the node name of the current node.
Parameters (Args): None
Return Value (Returns):

str: Name of this node within the distributed cluster

Exceptions (Raises): None

Example:

from RflySimSDK.swarm import NodeData

# Create node data object
node = NodeData("192.168.1.100", 8080)

# Update node heartbeat information
heartbeat_data = {"ostype": 2, "hostname": "sim-node-1", "nodename": "worker-1"}
node.updateHeartBeat(heartbeat_data)

# Retrieve basic node information
os_type = node.getOsTypeName()
host_name = node.getHostname()
node_name = node.getNodename()

Class Variable Description¶

Class Variable Name	Description
`OsTypeMap`	A dictionary mapping operating system type codes to their names, defining the supported node OS types

`AsyscCallbackItem` Class¶

A class for storing asynchronous callback information, typically used in scenarios involving asynchronous message callbacks for drone swarms.

`init(msgIdx, callback)`¶

Function Description: Initializes an asynchronous callback item object.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`msgIdx`	Any type	Yes	-	The message index corresponding to the callback.
`callback`	Any type	Yes	-	The asynchronous callback function object to be stored.

Return Value (Returns):

An instance of AsyscCallbackItem.

Exceptions (Raises): - None.

`distSimCtrlAPI` Class¶

Distributed simulation control API, used for node management, command issuance, and status monitoring of multi-node distributed simulation environments over the network.

`init(ip, debug="127.0.0.1")`¶

Function Description: Initializes the distributed simulation control API client, setting the server address and debug mode.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`ip`	`str`	No	`"127.0.0.1"`	IP address of the distributed simulation control server.
`debug`	`bool`	No	`False`	Whether to enable debug logging; when enabled, more communication debugging information will be printed.

Return Value (Returns):

An instance of distSimCtrlAPI.

Exceptions (Raises): - None.

`isRunningAsyscCmd()`¶

Function Description: Determines whether an asynchronous command is currently running, via asynchronous callback.
Parameters (Args): - None.
Return Value (Returns):

bool: Indicates whether an asynchronous command is currently running. True means a command is running; False means no asynchronous command is in progress.

Exceptions (Raises): - None.

`scan_udp(timeout=5)`¶

Function Description: Scans the network for available distributed simulation nodes using the UDP protocol.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`timeout`	`int`	No	`5`	UDP scan timeout duration, in seconds.

Return Value (Returns):

list: A list of information about available distributed simulation nodes discovered.

Exceptions (Raises): - None.

`modifyNodeName(targetNodeId=None, nodeName=None)`¶

Function Description: Modifies the name of a specified distributed node.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`targetNodeId`	`int`	No	`None`	ID of the target node whose name is to be modified.
`nodeName`	`str`	No	`None`	New name for the target node.

Return Value (Returns):

bool: Whether the modification was successful.

Exceptions (Raises): - None.

`executeCommand(command, targetNodeId=0, workdir=None, fileList=None, waitResTimeout=0, output_func=None)`¶

Function Description: Sends an execution command to a specified distributed node.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`command`	`str`	Yes	`None`	The command string to be executed.
`targetNodeId`	`int`	No	`0`	ID of the target execution node; default 0 is the local node.
`workdir`	`str`	No	`None`	Working directory for command execution; default None uses the node's default working directory.
`fileList`	`list`	No	`None`	List of files to be transferred with the command; default None means no additional files.
`waitResTimeout`	`int`	No	`0`	Timeout for waiting for the command execution result; 0 means return immediately without waiting for the result.
`output_func`	`callable`	No	`None`	Callback function for command output, used for asynchronous processing of command output.

Return Value (Returns):

The command execution result; if waitResTimeout>0, returns the execution output result; otherwise, returns the command issuance status.

Exceptions (Raises): - None.

Example:

# Initialize the distributed simulation control API
dist_ctrl = distSimCtrlAPI(ip="127.0.0.1", debug=True)
# Scan for nodes on the network
node_list = dist_ctrl.scan_udp(timeout=5)
# Execute a command on node 0
result = dist_ctrl.executeCommand("pwd", targetNodeId=0, waitResTimeout=10)

Advanced Usage Example¶

The following example asynchronously sends commands to scanned nodes, receives output via callbacks, and waits for all asynchronous tasks to complete.

Reference example: [RflySim installation path]\RflySimAPIs\10.RflySimSwarm\3.CustExps\e5.DSSwarmCtrls\3.CustIPDS8UAVs\4.LanDSUAVsForm

import time

import ReqCopterSim
import distSimCtrlAPI


req = ReqCopterSim.ReqCopterSim(False)
localIp = req.get_all_enable_ip()[0]
distCtrl = distSimCtrlAPI.distSimCtrlAPI(localIp, debug=False)


def command_output(code, output, error, tag=None):
    print("Node:", tag, "Exit code:", code)
    print(output or error)


nodes = distCtrl.scan_udp()
for node in nodes:
    status, result = distCtrl.executeCommand(
        "echo RflySim distributed command ^",
        node.nodeId,
        output_func=lambda code, output, error, tag=node.getNodename(): (
            command_output(code, output, error, tag)
        ),
    )
    print(node.getNodename(), status, result)

while distCtrl.isRunningAsyscCmd():
    print("Asynchronous command executing...")
    time.sleep(1)

Notes and Pitfall Avoidance Guide¶

UDP Node Scan Timeout Configuration: When scanning LAN nodes, if nodes are distributed across different subnets, the scan_udp timeout parameter should be set to 5 seconds or longer; otherwise, some online nodes may not be detected.
Asynchronous Command Status Query Limitation: The isRunningAsyscCmd method can only query the status of asynchronous tasks submitted by the current interface instance. If multiple distSimCtrlAPI instances are created, querying across instances will yield incorrect execution status results.
Node Heartbeat Update Frequency Requirement: During cluster operation, updateHeartBeat must be called at least once every 30 seconds for each node; otherwise, the central control node will mark the node as offline and automatically remove it from the cluster.
Asynchronous Command Load Limitation: The length of a single submitted asynchronous command must not exceed 1024 bytes; commands exceeding this limit will be directly truncated by the interface, causing task execution failure. Complex operations must be split into multiple asynchronous commands and submitted sequentially.

Changelog¶

2026-03-03: feat: SDK adds IP handling mechanism, compatible with local version cloud deployment
2025-12-05: feat: 1. Added interface for setting NED position and velocity for comprehensive models; 2. Added asynchronous command execution and message buffer size configuration for distSimCtrlAPI
2025-11-17: fix: Fixed issue where socket handle was prematurely released during broadcast
2025-11-05: feat: Refactored distSimCtrlAPI, switched to protobuf communication protocol, and updated general dependency files for distributed simulation (distsim)
2025-09-11: fix: Added support for port reuse on Linux
2024-12-10: fix: Updated comments for cluster control interface

distSimCtrlAPI Interface Documentation¶

Introduction¶

Quick Start¶

Environment and Dependencies¶

Core Interface Description¶

Global Constants and Enumerations¶

Standalone Constants¶

Global / Standalone Functions¶

NodeData Class¶

__init__(nodeIp, nodePort=None)¶

updateHeartBeat(heartBeatMsgData)¶

getOsTypeName()¶

getHostname()¶

getNodename()¶

Class Variable Description¶

AsyscCallbackItem Class¶

__init__(msgIdx, callback)¶

distSimCtrlAPI Class¶

__init__(ip, debug="127.0.0.1")¶

isRunningAsyscCmd()¶

scan_udp(timeout=5)¶

modifyNodeName(targetNodeId=None, nodeName=None)¶

executeCommand(command, targetNodeId=0, workdir=None, fileList=None, waitResTimeout=0, output_func=None)¶

Advanced Usage Example¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`NodeData` Class¶

`init(nodeIp, nodePort=None)`¶

`updateHeartBeat(heartBeatMsgData)`¶

`getOsTypeName()`¶

`getHostname()`¶

`getNodename()`¶

`AsyscCallbackItem` Class¶

`init(msgIdx, callback)`¶

`distSimCtrlAPI` Class¶

`init(ip, debug="127.0.0.1")`¶

`isRunningAsyscCmd()`¶

`scan_udp(timeout=5)`¶

`modifyNodeName(targetNodeId=None, nodeName=None)`¶

`executeCommand(command, targetNodeId=0, workdir=None, fileList=None, waitResTimeout=0, output_func=None)`¶