distSimCtrlAPI 接口文档¶

简介¶

简述：该文件提供了分布式集群仿真的控制接口，定义了分布式仿真所需的数据结构与核心控制类，支持多机集群仿真任务的分布式部署与协同控制。

在多无人机集群仿真任务中，当仿真规模较大、单计算节点算力不足以支撑整网仿真运行时，通常需要将仿真任务拆分到多个计算节点分布式运行，以此提升仿真性能、支撑更大规模的集群任务。本模块作为RflySim平台分布式集群仿真的核心控制接口，既定义了分布式节点信息存储、异步回调处理的基础数据结构，也提供了分布式仿真的核心控制API，可满足不同规模无人机集群仿真的分布式部署需求，帮助开发者快速搭建跨节点协同的无人机集群仿真环境。

快速开始¶

以下示例扫描局域网中的 DistSim 节点，显示节点信息，并在用户确认后向指定节点发送命令。

参考例程：[RflySim安装路径]\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("按 Enter 向所有节点发送测试命令")
status, result = distCtrl.executeCommand("echo Hello world! Every Computer")
print(status, result)

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：ctrl.IpManager、distsim.DistSim_pb2、os、queue、socket、threading、time、typing
前置准备：调用此接口前，需要先完成RflySimSDK的环境配置与相关依赖加载。

核心接口说明¶

该模块 distSimCtrlAPI.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义¶

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量¶

变量名	类型	值	说明
`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`	-

全局/独立函数¶

无

`NodeData` 类¶

用于存储分布式仿真集群中单个节点的连接信息与心跳数据，管理节点基础信息的存储与更新，常用于多机集群分布式仿真的节点管理场景。

`init(nodeIp, nodePort=None)`¶

功能说明：初始化节点数据对象，记录节点的IP地址与端口信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`nodeIp`	`str`	是	-	分布式节点的IP地址
`nodePort`	`int`	否	`None`	分布式节点的通信端口

返回值 (Returns)：

NodeData 实例对象

异常 (Raises)：无

`updateHeartBeat(heartBeatMsgData)`¶

功能说明：更新节点的心跳消息数据，刷新节点的在线状态与最新信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`heartBeatMsgData`	`dict`	是	-	最新的节点心跳消息数据，包含节点系统、名称等信息

返回值 (Returns)：无 异常 (Raises)：无

`getOsTypeName()`¶

功能说明：获取当前节点的操作系统类型名称 参数列表 (Args)：无 返回值 (Returns)：

str: 节点操作系统类型名称，对应OsTypeMap中的定义

异常 (Raises)：无

`getHostname()`¶

功能说明：获取当前节点的主机名 参数列表 (Args)：无 返回值 (Returns)：

str: 节点的主机名字符串

异常 (Raises)：无

`getNodename()`¶

功能说明：获取当前节点的节点名称 参数列表 (Args)：无 返回值 (Returns)：

str: 分布式集群中该节点的名称

异常 (Raises)：无

示例：

from RflySimSDK.swarm import NodeData

# 创建节点数据对象
node = NodeData("192.168.1.100", 8080)

# 更新节点心跳信息
heartbeat_data = {"ostype": 2, "hostname": "sim-node-1", "nodename": "worker-1"}
node.updateHeartBeat(heartbeat_data)

# 获取节点基础信息
os_type = node.getOsTypeName()
host_name = node.getHostname()
node_name = node.getNodename()

类变量说明¶

类变量名	说明
`OsTypeMap`	操作系统类型编码到名称的映射字典，定义了支持的各类节点操作系统类型

`AsyscCallbackItem` 类¶

用于存储异步回调信息的条目类，一般用于无人机群异步消息回调的场景。

`init(msgIdx, callback)`¶

功能说明：初始化异步回调条目对象 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`msgIdx`	任意类型	是	-	回调对应的消息索引
`callback`	任意类型	是	-	需要存储的异步回调函数对象

返回值 (Returns)：

AsyscCallbackItem 实例对象

异常 (Raises)：无

`distSimCtrlAPI` 类¶

分布式仿真控制API，用于通过网络对多节点分布式仿真环境进行节点管理、指令下发和状态监控。

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

功能说明：初始化分布式仿真控制API客户端，设置连接的服务端地址和调试模式 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`ip`	`str`	否	`"127.0.0.1"`	分布式仿真控制服务端的IP地址
`debug`	`bool`	否	`False`	是否开启调试日志输出，开启后会打印更多通信调试信息

返回值 (Returns)：

distSimCtrlAPI 实例对象

异常 (Raises)：无

`isRunningAsyscCmd()`¶

功能说明：通过异步回调获取当前是否正在运行异步指令 参数列表 (Args)：无 返回值 (Returns)：

bool: 当前是否处于异步指令运行状态，True表示正在运行，False表示无运行中异步指令

异常 (Raises)：无

`scan_udp(timeout=5)`¶

功能说明：通过UDP协议扫描网络中可用的分布式仿真节点 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`timeout`	`int`	否	`5`	UDP扫描超时时间，单位为秒

返回值 (Returns)：

list: 扫描得到的可用分布式仿真节点信息列表

异常 (Raises)：无

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

功能说明：修改指定分布式节点的名称 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`targetNodeId`	`int`	否	`None`	需要修改名称的目标节点ID
`nodeName`	`str`	否	`None`	目标节点的新名称

返回值 (Returns)：

bool: 修改是否成功

异常 (Raises)：无

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

功能说明：向指定分布式节点下发执行指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`command`	`str`	是	`None`	需要执行的指令字符串
`targetNodeId`	`int`	否	`0`	目标执行节点的ID，默认0为本地节点
`workdir`	`str`	否	`None`	指令执行的工作目录，默认None使用节点默认工作目录
`fileList`	`list`	否	`None`	需要随指令传输的文件列表，默认None无额外文件
`waitResTimeout`	`int`	否	`0`	等待指令执行结果的超时时间，0表示不等待结果直接返回
`output_func`	`callable`	否	`None`	指令输出的回调函数，用于异步处理指令输出

返回值 (Returns)：

指令执行结果，若waitResTimeout>0返回执行输出结果，否则返回指令下发状态

异常 (Raises)：无

示例：

# 初始化分布式仿真控制API
dist_ctrl = distSimCtrlAPI(ip="127.0.0.1", debug=True)
# 扫描网络中的节点
node_list = dist_ctrl.scan_udp(timeout=5)
# 向节点0执行指令
result = dist_ctrl.executeCommand("pwd", targetNodeId=0, waitResTimeout=10)

进阶用法示例¶

以下示例为扫描到的节点异步下发命令，通过回调接收输出，并等待全部异步任务结束。

参考例程：[RflySim安装路径]\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("节点:", tag, "退出码:", 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("异步命令执行中...")
    time.sleep(1)

注意事项与避坑指南¶

UDP节点扫描超时参数配置：扫描局域网节点时，若节点分布在跨网段环境，需要将scan_udp的超时参数设置为5秒及以上，否则会出现部分在线节点无法被扫描到的问题。
异步命令状态查询限制：isRunningAsyscCmd方法仅能查询当前接口实例提交的异步任务状态，若创建多个distSimCtrlAPI实例，跨实例查询会得到错误的运行状态结果。
节点心跳更新频率要求：集群运行过程中需要每30秒内调用一次updateHeartBeat更新节点心跳，否则中心控制节点会将该节点判定为离线，自动剔除出集群。
异步命令负载限制：单次提交的异步命令长度不可超过1024字节，过长的命令会直接被接口截断，导致任务执行失败，复杂操作需要拆分多条异步命令依次提交。

更新日志¶

2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云
2025-12-05: feat: 1.添加综合模型的设置NED位置与速度接口 2.添加distSimCtrlAPI的异步指令执行以及消息缓存区大小
2025-11-17: fix: 修复广播时socket句柄提前释放的问题
2025-11-05: feat: 重构distSimCtrlAPI，改用protobuf通信协议，以及distsim进行分布式仿真的一些通用依赖文件
2025-09-11: fix: 增加Linux端口复用的支持
2024-12-10: fix:更新集群控制接口注释

distSimCtrlAPI 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

NodeData 类¶

__init__(nodeIp, nodePort=None)¶

updateHeartBeat(heartBeatMsgData)¶

getOsTypeName()¶

getHostname()¶

getNodename()¶

类变量说明¶

AsyscCallbackItem 类¶

__init__(msgIdx, callback)¶

distSimCtrlAPI 类¶

__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)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`NodeData` 类¶

`init(nodeIp, nodePort=None)`¶

`updateHeartBeat(heartBeatMsgData)`¶

`getOsTypeName()`¶

`getHostname()`¶

`getNodename()`¶

`AsyscCallbackItem` 类¶

`init(msgIdx, callback)`¶

`distSimCtrlAPI` 类¶

`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)`¶