distSimCtrlAPI 接口文档¶

简介¶

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

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

快速开始¶

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.swarm.distSimCtrlAPI import NodeData

# 1. 初始化节点数据对象，默认使用本机配置，也可传入自定义IP和端口
node = NodeData(nodeIp="127.0.0.1", nodePort=12345)

# 2. 更新节点心跳信息，传入自定义心跳数据
heart_msg = {"node_id": 1, "status": "running", "load": 25.5}
node.updateHeartBeat(heartBeatMsgData=heart_msg)

# 3. 获取当前操作系统类型
os_type = node.getOsTypeName()
print("当前操作系统类型:", os_type)

# 4. 获取当前节点主机名
host_name = node.getHostname()
print("当前节点主机名:", host_name)

环境与依赖¶

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)

进阶用法示例¶

本示例展示多节点集群环境下批量扫描无人机节点+异步执行批量配置任务的多类协作场景，结合了UDP节点扫描、异步命令执行和节点心跳更新三类操作，适合大规模集群仿真的自动化管控场景。

from RflySimSDK.swarm import distSimCtrlAPI

# 初始化分布式仿真控制接口
ctrl_api = distSimCtrlAPI()
# 第一步：批量扫描局域网内所有在线集群节点
online_nodes = ctrl_api.scan_udp(timeout=3)
print(f"扫描得到{len(online_nodes)}个在线节点")

# 第二步：异步批量修改所有扫描到的节点名称，适配当前仿真任务命名规范
for idx, node in enumerate(online_nodes):
    new_name = f"uav-sim-node-{idx:02d}"
    ctrl_api.modifyNodeName(node.node_id, new_name)
    # 提交异步节点心跳更新任务，保持节点连接活跃
    node.updateHeartBeat()
    ctrl_api.executeCommand(f"sync_sim_config {new_name}", is_async=True)

# 第三步：轮询检查所有异步任务执行状态，确保配置完成
while ctrl_api.isRunningAsyscCmd():
    print("等待异步批量配置任务执行完成...")
    time.sleep(1)
print("所有集群节点配置完成，可启动多无人机协同仿真任务")

注意事项与避坑指南¶

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