NetSimAPIV4 接口文档¶
简介¶
简述：该文件提供了RflySim无人机仿真平台与PX4飞控之间的网络通信核心接口，实现仿真环境下的数据收发交互功能。
该模块是RflySim仿真框架中通信层的核心实现，负责对接仿真端与飞控端的网络连接，支持仿真环境中无人机状态、控制指令等各类数据的稳定交互，是整个仿真任务正常运行的数据传输基础。
它适用于所有基于RflySim平台的无人机仿真任务场景，无论是单无人机还是多无人机集群仿真，都可以通过该模块提供的类完成网络连接建立、飞控数据收发等核心通信操作。
快速开始¶
以下示例将 1 号无人机的状态数据点对点转发给 2 号无人机。运行前需要启动对应的 CopterSim 和 PX4 实例。
参考例程：[RflySim安装路径]\RflySimAPIs\9.RflySimComm\0.ApiExps\e1.RflyNetAPIExps\1.P2PSendData
import time
import NetSimAPIV4
import PX4MavCtrlV4 as PX4MavCtrl
import ReqCopterSim
CopterID = 1
# 获取 1 号 CopterSim 地址，并请求其向本机回传数据
req = ReqCopterSim.ReqCopterSim()
targetIP = req.getSimIpID(CopterID)
req.sendReSimIP(CopterID)
# 创建飞控通信和网络仿真实例
mav = PX4MavCtrl.PX4MavCtrler(CopterID, targetIP)
net = NetSimAPIV4.NetSimAPI(mav)
mav.InitMavLoop()
time.sleep(2)
# 将本机收集到的无人机数据转发给 2 号无人机
net.enUavForward(2)
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
copy、ctrl.IpManager、cv2、math、numpy、os、pymavlink、pymavlink.dialects.v20、socket、struct、sys、threading、time - 前置准备：调用此接口前，必须先完成网络通信相关的环境配置并确保仿真端网络连接就绪。
核心接口说明¶
该模块 NetSimAPIV4.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
无
全局/独立函数¶
无
UAVSendData 类¶
用于无人机数据发送的基础数据类，一般作为网络仿真接口中数据传输的基础类型使用。
__init__()¶
功能说明：初始化 UAVSendData 类实例
参数列表 (Args)：
无参数
返回值 (Returns)：
UAVSendData实例对象
异常 (Raises)： 无
NetSimAPI 类¶
网络仿真API接口类，用于RflySim中网络仿真相关的通信交互。
__init__(MavOrCopterID="1")¶
功能说明：初始化网络仿真API实例，绑定对应的飞行器ID。 参数列表 (Args)：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| MavOrCopterID | Any | "1" | 绑定的MAV或飞行器ID，标识当前实例对应的无人机对象 |
返回值 (Returns)：None 异常 (Raises)：无异常抛出
enUavForward(CopterIDList=[0], Interval=0)¶
功能说明：开启指定无人机的MAVLink数据网络转发 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterIDList | None | 否 | [0] | 需要开启转发的无人机ID列表 |
| Interval | None | 否 | 0 | 转发时间间隔，0表示立即启动持续转发 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
enNetForward(PortList=[60000], targetIP="224.0.0.10", Interval=0)¶
功能说明：开启指定端口和目标地址的网络数据转发 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| PortList | None | 否 | [60000] | 需要开启转发的目标端口列表 |
| targetIP | None | 否 | 224.0.0.10 | 转发目标IP地址，默认使用组播地址 |
| Interval | None | 否 | 0 | 转发时间间隔，0表示立即启动持续转发 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
endNetForward()¶
功能说明：停止所有正在进行的网络转发 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
netResetSendList()¶
功能说明：清空需要转发数据的无人机发送列表 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
netAddUavSendList(uavList=[])¶
功能说明：向需要转发数据的无人机发送列表中添加指定无人机 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| uavList | None | 否 | [] | 需要添加到发送列表的无人机ID列表 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
netResetReqList()¶
功能说明：清空需要请求数据的无人机请求列表 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
netAddUavReqList(uavList=[])¶
功能说明：向需要请求数据的无人机请求列表中添加指定无人机 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| uavList | None | 否 | [] | 需要添加到请求列表的无人机ID列表 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
StartReqUavData(uavList=[])¶
功能说明：启动对指定无人机数据的定时请求任务 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| uavList | None | 否 | [] | 需要请求数据的无人机ID列表 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
EndReqUavData()¶
功能说明：停止所有无人机数据请求任务 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
sendReqUavLoop()¶
功能说明：执行单次无人机数据请求循环，向请求列表中所有无人机发送数据请求 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
netForwardBuf(buf)¶
功能说明：将指定缓冲区的数据转发到所有已配置的网络目标 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| buf | None | 是 | 无 | 需要转发的二进制数据缓冲区 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
getMavEvent()¶
功能说明：获取接收到的MAVLink事件数据 参数列表 (Args)：无参数 返回值 (Returns)：接收到的MAVLink事件对象 异常 (Raises)：无
StartNetRecOwn()¶
功能说明：启动仅接收本机仿真无人机数据的网络接收线程 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
StartNetRec(MultiPort=60000, MultiIP="224.0.0.10")¶
功能说明：在指定组播地址和端口启动网络数据接收线程 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| MultiPort | None | 否 | 60000 | 接收数据的组播端口号 |
| MultiIP | None | 否 | 224.0.0.10 | 接收数据的组播IP地址 |
| 返回值 (Returns) | 无 | |||
| 异常 (Raises)：无 |
endNetLoop()¶
功能说明：停止所有网络接收和数据转发循环线程，关闭网络服务 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
getMavMsgNet()¶
功能说明：获取网络接收到的最新MAVLink消息 参数列表 (Args)： 无参数 返回值 (Returns)：最新接收到的MAVLink消息对象 异常 (Raises)：无
getUavData(CopterID)¶
功能说明：获取指定ID无人机的最新仿真数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | None | 是 | 无 | 目标无人机的ID编号 |
返回值 (Returns)：指定ID无人机的最新仿真数据 异常 (Raises)：无
进阶用法示例¶
以下示例广播 1 号无人机的数据，同时接收并遍历网络中的其他无人机状态。
参考例程：[RflySim安装路径]\RflySimAPIs\9.RflySimComm\0.ApiExps\e1.RflyNetAPIExps\2.BroadSendData
import time
import NetSimAPIV4
import PX4MavCtrlV4 as PX4MavCtrl
import ReqCopterSim
CopterID = 1
req = ReqCopterSim.ReqCopterSim()
targetIP = req.getSimIpID(CopterID)
req.sendReSimIP(CopterID)
mav = PX4MavCtrl.PX4MavCtrler(CopterID, targetIP)
net = NetSimAPIV4.NetSimAPI(mav)
mav.InitMavLoop()
time.sleep(2)
# 不指定目标 ID 时广播本机无人机数据
net.enUavForward()
time.sleep(2)
# 启动网络接收，收到的数据保存在 UavData 中
net.StartNetRec()
while True:
for uav in net.UavData:
print("UAV", uav.CopterID, ":", uav.uavGlobalPos)
time.sleep(1)
注意事项与避坑指南¶
- 转发状态一致性：同时使用
enUavForward和enNetForward开启双向转发后，任务结束必须调用对应endNetForward关闭转发，否则会导致下一回合仿真端口占用冲突，无法正常启动通信。 - 列表修改顺序：添加或修改发送/请求列表前，必须先调用
netResetSendList或netResetReqList清空原有配置，否则会重复添加配置项，导致通信数据重复发送、接收端解析出错。 - 循环请求调用方式：
sendReqUavLoop是阻塞式循环方法，直接在主线程调用会卡住后续任务逻辑，必须将其放到单独的守护线程中异步运行，才能实现主任务与通信的协同。 - 请求生命周期管理：启动批量无人机数据请求前必须调用
StartReqUavData完成初始化，任务结束后调用EndReqUavData终止请求，未配对调用会导致内存泄漏，长时间仿真后会出现帧率下降甚至程序崩溃。
更新日志¶
2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云2025-09-11: fix: 增加Linux端口复用的支持2024-07-18: fix:更新API主页索引2024-06-13: fix: 更新组网接口2024-05-27: fix: 更新通信接口类2024-05-23: 新增Python网络通信接口的API文档2024-05-23: fix: 完善网络通信接口类2024-05-14: fix: 增加缓存，确保通信正常。2024-05-13: fix: 更新数据转发接口，支持广播飞机状态，并被所有飞机订阅2024-03-03: fix: 增加对组播的异常处理，防止断网情况下，初始化报错。2023-10-24: feat: 修复部分bug2023-10-23: feat: Add all Python common labs