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¶

Minimal runnable example; copy and modify only the minimum required configuration to run.

from RflySimSDK.swarm.distSimCtrlAPI import NodeData

# 1. Initialize the node data object; by default, local machine configuration is used. Custom IP and port can also be provided.
node = NodeData(nodeIp="127.0.0.1", nodePort=12345)

# 2. Update node heartbeat information with custom heartbeat data.
heart_msg = {"node_id": 1, "status": "running", "load": 25.5}
node.updateHeartBeat(heartBeatMsgData=heart_msg)

# 3. Get the current operating system type.
os_type = node.getOsTypeName()
print("Current OS type:", os_type)

# 4. Get the current node's hostname.
host_name = node.getHostname()
print("Current node hostname:", host_name)

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`: Indicates whether the modification was successful.

**Exceptions (Raises)**:
- None.

---

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

**Function Description**: Issues a command to a specified distributed node for execution.  
**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; defaults to `0`, representing the local node. |
| `workdir` | `str` | No | `None` | Working directory for command execution; defaults to `None`, using the node’s default working directory. |
| `fileList` | `list` | No | `None` | List of files to be transmitted along with the command; defaults to `None`, indicating no additional files. |
| `waitResTimeout` | `int` | No | `0` | Timeout duration (in seconds) for waiting for command execution results; `0` means returning immediately without waiting for results. |
| `output_func` | `callable` | No | `None` | Callback function for handling command output, used for asynchronous processing of command output. |

**Return Value (Returns)**:

- Command execution result: if `waitResTimeout > 0`, returns the execution output; otherwise, returns the command submission status.

**Exceptions (Raises)**:
- None.

**Example**:

```python
# Initialize the distributed simulation control API
dist_ctrl = distSimCtrlAPI(ip="127.0.0.1", debug=True)
# Scan for nodes in 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

This example demonstrates a multi-cooperation scenario in a multi-node cluster environment, involving batch scanning of drone nodes and asynchronous execution of batch configuration tasks. It integrates three types of operations: UDP node scanning, asynchronous command execution, and node heartbeat updates, making it suitable for automated cluster management in large-scale cluster simulations.

```python
from RflySimSDK.swarm import distSimCtrlAPI

# Initialize the distributed simulation control interface
ctrl_api = distSimCtrlAPI()
# Step 1: Batch scan all online cluster nodes within the local area network
online_nodes = ctrl_api.scan_udp(timeout=3)
print(f"Scanned {len(online_nodes)} online nodes")

# Step 2: Asynchronously batch modify the names of all scanned nodes to conform to the current simulation task naming convention
for idx, node in enumerate(online_nodes):
    new_name = f"uav-sim-node-{idx:02d}"
    ctrl_api.modifyNodeName(node.node_id, new_name)
    # Submit an asynchronous node heartbeat update task to maintain active node connectivity
    node.updateHeartBeat()
    ctrl_api.executeCommand(f"sync_sim_config {new_name}", is_async=True)

# Step 3: Poll to check the execution status of all asynchronous tasks, ensuring configuration completion
while ctrl_api.isRunningAsyscCmd():
    print("Waiting for asynchronous batch configuration tasks to complete...")
    time.sleep(1)
print("All cluster node configurations completed; multi-drone collaborative simulation tasks can now be initiated")

Notes and Pitfall Avoidance Guide¶

UDP Node Scan Timeout Configuration: When scanning LAN nodes, if nodes are distributed across different subnets, the timeout parameter of scan_udp 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()¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`NodeData` Class¶

`init(nodeIp, nodePort=None)`¶

`updateHeartBeat(heartBeatMsgData)`¶

`getOsTypeName()`¶

`getHostname()`¶

`getNodename()`¶