ReqCopterSim 接口文档¶
简介¶
简述：UE4 无人机仿真状态同步与请求模块，提供 EKF 初始化检测、时间戳同步及多机仿真状态查询功能。
本模块专为 RflySim 无人机仿真平台 的 UE4 三维场景设计，用于解决多无人机协同仿真中的状态同步难题。核心场景包括：分布式仿真中多机 EKF（扩展卡尔曼滤波）初始化状态检测、UE4 引擎与 CopterSim 的时间戳同步、以及批量查询所有无人机的三维位置固定状态（allCopterSim3DFixed）。模块通过类 Ue4EKFInit 和 GetUe4EKFInit 实现非阻塞式状态轮询，类 RflyTimeStmp 支持向指定远端主机的 20005 端口发送带校验的时间同步消息，而 ReqCopterSim 则封装了与 CopterSim 仿真核心的请求-响应协议，适用于需要精确时序控制的硬件在环（HIL）仿真与视觉-惯性导航算法验证场景。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
# 导入 ReqCopterSim 类，用于与 RflySim 的 CopterSim 进行通信
from RflySimSDK.ctrl import ReqCopterSim
# 创建 ReqCopterSim 实例，默认启动监听 20005 端口接收 RflyTimeStmp
req = ReqCopterSim()
# 获取本机 IP 地址（静态方法，无需实例即可调用）
local_ip = ReqCopterSim.getLocalIp()
print(f"本机IP: {local_ip}")
# 验证 IP 地址是否合法
is_valid = req.isValidIp("192.168.1.1")
print(f"IP验证结果: {is_valid}")
# 获取本机所有网卡的 IP 地址列表
all_ips = req.get_all_ip()
print(f"所有IP: {all_ips}")
环境与依赖¶
- 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)：
- 无
示例：
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)：无
sendReSimMapIdx(CopterID=1, index=-1)¶
功能说明：发送地图索引重配置请求，用于在仿真中切换指定无人机的地图场景。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| index | int | 否 | -1 | 地图索引，-1表示不指定 |
返回值 (Returns)：无 异常 (Raises)：无
sendReSimIP(CopterID=1)¶
功能说明：发送IP重配置请求，用于重新配置指定无人机的通信IP地址。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
返回值 (Returns)：无 异常 (Raises)：无
sendReSimUdpMode(CopterID=1, UDP_mode=-1)¶
功能说明：发送UDP模式重配置请求，用于切换指定无人机的UDP通信模式。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| UDP_mode | int | 否 | -1 | UDP通信模式，-1表示不指定 |
返回值 (Returns)：无 异常 (Raises)：无
sendReSimXYyaw(CopterID=1, xyYaw=[0, 0, 0])¶
功能说明：发送XY平面位置及偏航角重配置请求，用于设置指定无人机在XY平面的位置和偏航角。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| xyYaw | list | 否 | [0, 0, 0] | XY平面位置和偏航角 [x, y, yaw]，单位：米、弧度 |
返回值 (Returns)：无 异常 (Raises)：无
sendReGPSOrin(CopterID=1, LLA=[0, 0, 0])¶
功能说明：发送GPS原点重配置请求，用于设置指定无人机的GPS原点位置（经纬度高度）。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| LLA | list | 否 | [0, 0, 0] | GPS原点 [纬度, 经度, 高度]，单位：度、度、米 |
返回值 (Returns)：无 异常 (Raises)：无
sendReGPSPos(CopterID=1, lat=0, lon=0, yaw=0)¶
功能说明：发送GPS位置重配置请求，用于设置指定无人机的GPS位置和偏航角。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| lat | float | 否 | 0 | 纬度，单位：度 |
| lon | float | 否 | 0 | 经度，单位：度 |
| yaw | float | 否 | 0 | 偏航角，单位：弧度 |
返回值 (Returns)：无 异常 (Raises)：无
sendEnGpsMode(CopterID=1)¶
功能说明：发送启用GPS模式请求，用于启用指定无人机的GPS定位模式。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
返回值 (Returns)：无 异常 (Raises)：无
sendEnXyMode(CopterID=1)¶
功能说明：发送启用XY模式请求，用于启用指定无人机的XY平面定位模式。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
返回值 (Returns)：无 异常 (Raises)：无
sendReSimXyzRPYaw(CopterID=1, Xyz=[0, 0, 0], RPYaw=[0, 0, 0])¶
功能说明：发送完整位姿重配置请求，用于设置指定无人机的三维位置和姿态（滚转、俯仰、偏航）。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标无人机的ID |
| Xyz | list | 否 | [0, 0, 0] | 三维位置 [x, y, z]，单位：米 |
| RPYaw | list | 否 | [0, 0, 0] | 姿态角 [roll, pitch, yaw]，单位：弧度 |
返回值 (Returns)：无 异常 (Raises)：无
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
from RflySimSDK.ctrl.ReqCopterSim import ReqCopterSim, Ue4EKFInit, GetUe4EKFInit, RflyTimeStmp
class MultiCopterManager:
"""多无人机协同管理器：实现批量无人机状态监控与时间同步"""
def __init__(self):
self.sim = ReqCopterSim()
self.ekf_init = GetUe4EKFInit()
self.time_sync = RflyTimeStmp()
self.active_copters = {}
def discover_and_sync(self):
# 批量发现所有仿真无人机
copter_ids = self.sim.getAllCopterID()
ip_list = self.sim.getSimIpList()
for cid in copter_ids:
ip = self.sim.getSimIpID(cid)
self.active_copters[cid] = {
'ip': ip,
'local': self.sim.isIpLocal(ip)
}
# 异步时间同步：更新所有节点时间戳
self.time_sync.Update()
return self.active_copters
def reset_all_ekf(self, copter_subset=None):
"""批量重置指定无人机的EKF状态"""
targets = copter_subset or list(self.active_copters.keys())
for cid in targets:
if cid in self.active_copters:
# 本地仿真直接重置，远程需通过通信
if self.active_copters[cid]['local']:
self.ekf_init.reset()
print(f"已重置 {len(targets)} 架无人机的EKF状态")
# 使用示例
manager = MultiCopterManager()
manager.discover_and_sync()
manager.reset_all_ekf([1, 3, 5]) # 批量重置指定ID的无人机
注意事项与避坑指南¶
-
IP地址验证陷阱：
isValidIp和getLocalIp仅做格式校验，不保证目标主机可达；isIpLocal判断的是网卡归属而非仿真实例运行状态，跨网段部署时需额外心跳检测。 -
CopterID动态变化：
getAllCopterID返回的ID列表随仿真启停实时变化，禁止在循环中缓存旧ID进行控制指令发送；建议每次操作前调用updateSimMsg刷新状态。 -
EKF重置的异步延迟：
Ue4EKFInit.reset()触发后需等待UE4渲染线程完成状态重置（通常50-200ms），立即读取位姿数据可能拿到旧协方差；批量操作时应串行执行并插入固定延时。 -
时间戳跨平台偏差：
RflyTimeStmp.Update()依赖系统时钟，Windows/Linux的计时精度差异（~1ms vs ~10μs）会导致多机协同控制时出现相位抖动；高精度场景建议配合PTP硬件同步。 -
IP列表缓存失效：
getSimIpList和getSimIpID内部维护查询缓存，仿真节点异常退出（如崩溃而非正常关闭）后，缓存条目可能残留，导致getHostIP返回不可达地址；生产环境应设置定期全量刷新机制。
更新日志¶
2026-03-30: fix：修复SITL sh脚本规则，新增git规则，上云sdk修复2026-03-07: fix:请求局域网里CopterSim回传数据的逻辑增加容错机制，保证成功率2025-11-18: feat: ReqCopterSim.py添加新接口get_all_enable_ip，获取本机启用的IP地址 （有线优先、其次wifi、再其他）2025-11-17: fix: 优化机制2025-11-17: fix: 优化IP获取机制2025-11-17: fix：解决Windows下程序报错的bug2025-11-14: 新增NAT模式网络识别，能够正确请求IP地址。2025-11-11: refactor: 同步DistSim最新修改2025-11-05: [feat] 提供检测CopterSim是否达到Fixed状态接口2025-09-11: fix: 增加Linux端口复用的支持2025-07-30: fix： 更新2024-09-29: fix：修复虚拟机模式下NAT无法请求的问题2024-08-16: fix: 更新本地网卡获取机制2024-08-16: fix: 更新获取本地CopterSim的代码2024-07-10: fix: 修复断网情况下，程序报错的bug