NetSimAPIV4 接口文档¶
简介¶
简述：该文件提供了RflySim无人机仿真平台与PX4飞控之间的网络通信核心接口，实现仿真环境下的数据收发交互功能。
该模块是RflySim仿真框架中通信层的核心实现，负责对接仿真端与飞控端的网络连接，支持仿真环境中无人机状态、控制指令等各类数据的稳定交互，是整个仿真任务正常运行的数据传输基础。
它适用于所有基于RflySim平台的无人机仿真任务场景，无论是单无人机还是多无人机集群仿真，都可以通过该模块提供的类完成网络连接建立、飞控数据收发等核心通信操作。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
from RflySimSDK.comm import NetSimAPI
# 初始化NetSimAPI，设置目标无人机ID为1
net_api = NetSimAPI(MavOrCopterID=1)
# 启用无人机端转发，指定转发给ID为1的无人机，转发间隔设置为10ms
net_api.enUavForward(CopterIDList=[1], Interval=10)
# 启用网络转发，将数据转发到本地组播地址224.0.0.10，使用默认端口60000，间隔10ms
net_api.enNetForward(PortList=[60000], targetIP="224.0.0.10", Interval=10)
# 程序运行此处保持转发，实际业务代码可替换为你的业务逻辑
input("按回车键停止转发...\n")
# 停止网络转发，关闭通道
net_api.endNetForward()
环境与依赖¶
- 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)：无
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
from RflySimSDK.comm import NetSimAPI, UAVSendData
import threading
# 初始化通信接口，配置多无人机任务通信
net_api = NetSimAPI()
# 重置发送和请求列表，避免历史数据干扰
net_api.netResetSendList()
net_api.netResetReqList()
# 批量添加10架无人机的上行发送配置
uav_send_list = [UAVSendData(uav_id=i) for i in range(1, 11)]
for send_item in uav_send_list:
net_api.netAddUavSendList(send_item)
# 批量添加无人机状态请求配置
for uav_id in range(1, 11):
net_api.netAddUavReqList(uav_id)
# 启用无人机前向转发和网络转发功能
net_api.enUavForward(True)
net_api.enNetForward(True)
# 异步启动循环请求，避免阻塞主任务线程
req_thread = threading.Thread(target=net_api.sendReqUavLoop, daemon=True)
req_thread.start()
# 主任务执行协同任务调度，异步获取无人机状态数据
while True:
# 此处可插入任务规划、避障决策等主逻辑
pass
# 任务结束后关闭请求和通信转发
net_api.EndReqUavData()
net_api.endNetForward()
注意事项与避坑指南¶
- 转发状态一致性：同时使用
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