ReqCopterSim 接口文档¶

简介¶

简述：UE4 无人机仿真状态同步与请求模块，提供 EKF 初始化检测、时间戳同步及多机仿真状态查询功能。

本模块专为 RflySim 无人机仿真平台 的 UE4 三维场景设计，用于解决多无人机协同仿真中的状态同步难题。核心场景包括：分布式仿真中多机 EKF（扩展卡尔曼滤波）初始化状态检测、UE4 引擎与 CopterSim 的时间戳同步、以及批量查询所有无人机的三维位置固定状态（allCopterSim3DFixed）。模块通过类 Ue4EKFInit 和 GetUe4EKFInit 实现非阻塞式状态轮询，类 RflyTimeStmp 支持向指定远端主机的 20005 端口发送带校验的时间同步消息，而 ReqCopterSim 则封装了与 CopterSim 仿真核心的请求-响应协议，适用于需要精确时序控制的硬件在环（HIL）仿真与视觉-惯性导航算法验证场景。

快速开始¶

以下示例以非阻塞方式创建请求实例并获取本机局域网地址，可作为分布式仿真控制程序的初始化步骤。

参考例程：[RflySim安装路径]\RflySimAPIs\10.RflySimSwarm\3.CustExps\e0.CustApiExps\2.DistSimCommAPIExps\1.HelloWorldTestExp

import ReqCopterSim


# False 表示不持续更新仿真消息，可减少初始化等待
req = ReqCopterSim.ReqCopterSim(False)
localIp = req.getLocalIp()
print("本机 IP:", localIp)

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：copy、os、psutil、re、socket、struct、threading、time
前置准备：调用此接口前，必须先通过 UE4 或 CopterSim 建立仿真环境连接。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`Ue4EKFInit` 类¶

该类用于初始化 UE4 场景中的 EKF（扩展卡尔曼滤波）状态，通常在无人机仿真开始前重置位姿估计。

`init()`¶

功能说明：初始化 Ue4EKFInit 实例，准备 EKF 初始化功能。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
-	-	-	-	无需参数

返回值 (Returns)：

Ue4EKFInit 实例对象

异常 (Raises)：

无

`reset()`¶

功能说明：重置 UE4 场景中的 EKF 状态，将位姿估计恢复至初始值。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
-	-	-	-	无需参数

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

ekf_init = Ue4EKFInit()
# 在仿真开始前重置 EKF
ekf_init.reset()

`GetUe4EKFInit` 类¶

该类用于初始化并持续检测所有 CopterSim 实例的 3D 固定状态。初始化后即开始检测，外部需通过不断查询 allCopterSim3DFixed 属性来获取检测结果。

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

功能说明：初始化检测器，开始对所有指定的 CopterSim 实例进行 3D 固定状态检测。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`expected_copter_ids`	`list`	是	-	需要检测的 CopterSim ID 列表
`localIp`	`str`	否	`"None"`	本地 IP 地址，用于网络通信

返回值 (Returns)：

GetUe4EKFInit 实例对象

异常 (Raises)：

无

`RflyTimeStmp` 类¶

RflyTimeStmp 是用于 RflySim 仿真平台的时间戳数据结构，主要用于心跳包的时间同步。该结构体包含仿真开始时间、当前时间戳以及心跳计数器，通过 UDP 协议发送至指定远端电脑的端口 20005，用于多机协同仿真中的时间同步和心跳检测。

`init(iv)`¶

功能说明：初始化 RflyTimeStmp 实例，根据输入参数初始化时间戳相关的成员变量。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`iv`	`list`	是	-	包含时间戳数据的列表，格式为 `[checksum, copterID, SysStartTime, SysCurrentTime, HeartCount]`

返回值 (Returns)：

RflyTimeStmp 实例对象

异常 (Raises)：

无

`Update(iv)`¶

功能说明：更新 RflyTimeStmp 实例的时间戳数据，用于心跳包数据的动态更新。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`iv`	`list`	是	-	包含更新时间戳数据的列表，格式为 `[checksum, copterID, SysStartTime, SysCurrentTime, HeartCount]`

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

# 创建时间戳实例
timestamp_data = [123456789, 1, 1699123456789, 1699123466789, 100]
rfly_ts = RflyTimeStmp(timestamp_data)

# 更新心跳数据
new_data = [123456789, 1, 1699123456789, 1699123476789, 101]
rfly_ts.Update(new_data)

`ReqCopterSim` 类¶

用于与 RflySim 仿真环境进行通信的请求类，主要负责监听指定端口以获取仿真时间戳信息。

`init(updateMsg=True)`¶

功能说明：初始化 ReqCopterSim 实例，启动对 20005 端口的监听，用于接收 RflyTimeStmp 消息，从而获取指定无人机的仿真时间信息。

参数列表 (Args)：

参数名	类型	默认值	说明
`updateMsg`	`bool`	`True`	是否启用消息更新功能，设置为 `True` 时自动监听并更新消息

返回值 (Returns)：

类型	说明
`None`	构造函数无返回值

异常 (Raises)：

异常类型	说明
`socket.error`	当无法绑定或监听 20005 端口时抛出
`OSError`	当网络接口初始化失败时抛出

`getLocalIp()`¶

功能说明：获取本地 IP 地址。优先尝试连接 8.8.8.8 来获取本地 IP，失败后尝试连接 114.114.114.114，如果都失败则返回 127.0.0.1。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：str - 本地 IP 地址字符串，如 "192.168.1.100"

异常 (Raises)：无

`isValidIp(address)`¶

功能说明：验证给定的字符串是否为有效的 IP 地址（IPv4）。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
address	`str`	是	-	待验证的 IP 地址字符串

返回值 (Returns)：bool - 如果 address 是有效的 IPv4 地址则返回 True，否则返回 False

异常 (Raises)：无

`get_all_ip()`¶

功能说明：获取本机所有网络接口的 IPv4 地址列表，包括 127.0.0.1。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：list[str] - 包含所有 IPv4 地址的列表

异常 (Raises)：无

`get_all_enable_ip()`¶

功能说明：获取本机所有启用的（活动的）网络接口的 IPv4 地址列表。过滤掉禁用或未连接的接口。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：list[str] - 包含所有启用的 IPv4 地址的列表

异常 (Raises)：无

`isIpLocal(IP)`¶

功能说明：判断给定的 IP 地址是否为本机地址（包括 127.0.0.1 和所有本地网络接口的 IP）。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
IP	`str`	是	-	待检查的 IP 地址字符串

返回值 (Returns)：bool - 如果 IP 是本机地址则返回 True，否则返回 False

异常 (Raises)：无

`getAllCopterID()`¶

功能说明：获取当前系统中所有已注册/活动的 Copter（无人机）ID 列表。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：list[int] - 包含所有 Copter ID 的列表

异常 (Raises)：无

`updateSimMsg()`¶

功能说明：更新（接收并处理）来自 CopterSim 的仿真消息。该方法会接收 UDP 数据包并更新内部的仿真状态信息。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：无

异常 (Raises)：无

`getSimIpList()`¶

功能说明：获取当前所有已注册仿真的 IP 地址列表。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：list[str] - 包含所有仿真 IP 地址的列表

异常 (Raises)：无

`getSimIpID(CopterID=1)`¶

功能说明：根据 Copter ID 获取对应仿真的 IP 地址。如果找不到对应 ID，则返回空字符串。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	1	要查询的无人机 ID

返回值 (Returns)：str - 对应仿真的 IP 地址，未找到时返回空字符串

异常 (Raises)：无

`getHostIP()`¶

功能说明：获取主机（Host）IP 地址。与 getLocalIp 类似，但可能在特定网络配置下有不同的获取策略。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明

无参数

返回值 (Returns)：str - 主机 IP 地址字符串

异常 (Raises)：无

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

功能说明：向 CopterSim 发送请求消息，用于重新配置仿真参数，包括请求 IP、设置初始位置、修改 UDP 模式等。支持多种高级配置如 GPS 原点设置、GPS 位置设置等。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	1	目标无人机 ID，用于验证请求
isReqIP	`int`	否	1	是否请求 IP。>0 时勾选联机并将飞控数据发送给本电脑
UDP_mode	`int`	否	-1	UDP 传输模式。<0 不响应，>=0 修改为指定模式
isXyYaw	`int`	否	0	是否设置 XY 位置和偏航角。>0 使用 xyYaw 值重新部署飞机位置。特殊值：2 设置 GPS 原点（lat/lon/alt），3 设置 GPS 位置（lat/lon/yaw）
xyYaw	`list[float]`	否	[0, 0, 0]	XY 位置和偏航角 [x, y, yaw]，单位米和度。isXyYaw=2 时：[lat, lon, alt]；isXyYaw=3 时：[lat, lon, yaw]
isZRP	`int`	否	0	是否设置 Z 高度和滚转俯仰角。>0 使用 zRollPitch 值，否则 Z 贴合地形、滚转俯仰角为 0
zRollPitch	`list[float]`	否	[0, 0, 0]	Z 高度、滚转角、俯仰角 [z, roll, pitch]，单位米和度，Z 向下为正
otherParams	`list[int]`	否	[0, 0, 0, 0]	保留的其他参数，共 4 个字节，留给将来使用

返回值 (Returns)：无

异常 (Raises)：无

`sendReDllMap(CopterID=0, dllOrMap=-1, index=-1, name="")`¶

功能说明：请求改变 CopterSim 的 DLL 模型或地图。可以向指定飞机、所有飞机或广播发送切换指令。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	0	目标飞机 ID。0 不响应；-1 广播给所有飞机；>0 指定飞机
dllOrMap	`int`	否	-1	切换选项。<=0 不响应；1 修改 DLL 模型；2 修改地图
index	`int`	否	-1	选项 ID 序号。<0 不响应，使用 name 确定选项；>=0 用序号而非 name 确定选项
name	`str`	否	""	DLL 模型或地图的名字，最大 48 字节

返回值 (Returns)：无

异常 (Raises)：无

`sendReSimDllName(CopterID=1, name="")`¶

功能说明：请求设置指定 CopterSim 的 DLL 模型名称。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	1	目标无人机 ID
name	`str`	否	""	DLL 模型的名称

返回值 (Returns)：无

异常 (Raises)：无

`sendReSimDllIdx(CopterID=1, index=-1)`¶

功能说明：请求设置指定 CopterSim 的 DLL 模型索引。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	1	目标无人机 ID
index	`int`	否	-1	DLL 模型的索引序号，<0 表示使用名称方式设置

返回值 (Returns)：无

异常 (Raises)：无

`sendReSimMapName(CopterID=1, name="")`¶

功能说明：请求设置指定 CopterSim 的地图名称。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`int`	否	1	目标无人机 ID
name	`str`	否	""	地图的名称

返回值 (Returns)：无

异常 (Raises)：无