NetUavAPI 接口文档

简介

简述：本文件定义了RflySim无人机仿真平台通信模块的核心网络交互类，实现无人机端与仿真地面端之间的网络数据传输与连接状态维护功能。

在RflySim分布式仿真场景中，无人机仿真节点与地面站、外部计算节点通常需要跨进程或跨设备进行通信，本模块提供了标准化的网络交互基础架构，支撑位置、状态等无人机核心数据的稳定传输。它适用于多机协同仿真、外部算法对接仿真、异地分布式仿真等需要网络通信的场景，通过心跳维护、连接校验机制保障通信链路的可靠性，为上层无人机控制、状态监测功能提供稳定的底层网络传输支持。

快速开始

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

from RflySimSDK.comm.NetUavAPI import HeartServer
import time

# 1. 创建心跳服务端实例
heart_server = HeartServer()

# 2. 启动心跳服务
heart_server.startHeartSer()

try:
    # 3. 持续发送心跳，保持连接（这里示例运行10秒）
    for _ in range(10):
        heart_server.SendHeartSer()
        # 心跳一般每秒发送一次，等待1秒
        time.sleep(1)
finally:
    # 4. 停止心跳服务，释放资源
    heart_server.endHeartSer()

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：PX4MavCtrlV4、copy、ctypes、datetime、math、numpy、os、pickle、socket、struct、sys、threading、time、win_precise_time
• 前置准备：调用此接口前，必须先确保网络连接正常并完成相关通信节点的初始化配置。

核心接口说明

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

全局常量与枚举定义

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

独立常量

无

---

全局/独立函数

无

---

CheckInfo 类

该类为RflySimSDK通信模块下的空基类，一般用于存储和校验无人机通信连接相关信息，可根据需求扩展具体功能。

__init__()

功能说明：初始化CheckInfo类实例 参数列表 (Args)： 无参数

返回值 (Returns)：

• CheckInfo 实例对象

异常 (Raises)： 无

---

HeartBeartInfo 类

用于存储无人机心跳相关信息的数据类，在RflySim仿真平台的无人机通信模块中承载心跳状态数据。

__init__()

功能说明：初始化 HeartBeartInfo 类实例 参数列表 (Args)： 无 返回值 (Returns)：

• HeartBeartInfo 实例对象

异常 (Raises)： 无

---

HeartServer 类

用于维护RflySim无人机仿真通信链路的心跳服务，检测并保持客户端与服务端的连接状态，保障通信稳定性。

__init__()

功能说明：初始化心跳服务实例 参数列表 (Args)： 无参数

返回值 (Returns)：

• HeartServer 实例对象

异常 (Raises)： 无

---

startHeartSer()

功能说明：启动心跳服务，开始监听心跳消息并维持连接 参数列表 (Args)： 无参数

返回值 (Returns)：

• 无

异常 (Raises)： 无

示例：

from RflySimSDK.comm import HeartServer
# 创建心跳服务实例并启动
heart_server = HeartServer()
heart_server.startHeartSer()

---

endHeartSer()

功能说明：停止心跳服务，关闭连接并释放相关资源 参数列表 (Args)： 无参数

返回值 (Returns)：

• 无

异常 (Raises)： 无

---

SendHeartSer()

功能说明：主动发送心跳数据包，告知对端本端连接状态正常 参数列表 (Args)： 无参数

返回值 (Returns)：

• 无

异常 (Raises)： 无

---

CheckConnectState()

功能说明：检查当前通信连接的存活状态 参数列表 (Args)： 无参数

返回值 (Returns)：

• bool: 连接状态，True表示连接正常，False表示连接断开

异常 (Raises)： 无

示例：

# 检查当前连接状态
is_connected = heart_server.CheckConnectState()
print(f"当前连接状态: {is_connected}")

---

ReceiveHeartSer()

功能说明：接收对端发送的心跳数据包，更新连接状态 参数列表 (Args)： 无参数

返回值 (Returns)：

• 无

异常 (Raises)： 无

---

GlobalPosData 类

用于存储无人机全局位置相关数据的数据容器类。

__init__(cpID, iv)

功能说明：初始化 GlobalPosData 实例对象 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
cpID	任意类型	是	-	任务点ID相关参数
iv	任意类型	是	-	位置相关数值参数

返回值 (Returns)：

• GlobalPosData 实例对象

异常 (Raises)：

• 无

---

NetTransNode 类

网络传输节点，用于和网络仿真服务建立连接，实现无人机数据的网络收发，一般用于多机网络通信仿真场景。

__init__(mav=PX4MavCtrl.PX4MavCtrler(1))

功能说明：初始化网络传输节点对象，绑定PX4飞控控制实例 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
mav	PX4MavCtrler	否	PX4MavCtrl.PX4MavCtrler(1)	PX4飞控控制实例，用于获取和发送无人机的飞控数据

返回值 (Returns)：

• NetTransNode 实例对象

异常 (Raises)： 无

---

startNetServ(RecPort=-1, netSimPort=20030, netSimIP=224.0.0.10)

功能说明：启动网络传输服务，方法会阻塞直到接收到来自发送端的启动信号后才会返回 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
RecPort	int	否	-1	本地接收数据的端口号，-1表示自动分配端口
netSimPort	int	否	20030	网络仿真服务的端口号
netSimIP	str	否	224.0.0.10	网络仿真服务的IP地址，默认使用组播地址

返回值 (Returns)：

• 无

异常 (Raises)： 无

示例：

from RflySimSDK.comm import NetTransNode
from RflySimSDK.PX4MavCtrl import PX4MavCtrler
# 初始化飞控控制器和网络传输节点
mav = PX4MavCtrler(1)
net_node = NetTransNode(mav)
# 启动网络服务
net_node.startNetServ()

---

endNetServ()

功能说明：结束网络传输服务，停止收发消息循环 返回值 (Returns)：

• 无

异常 (Raises)： 无

---

ListenMsgLoop()

功能说明：启动网络消息接收循环，持续接收网络中其他节点发送的无人机数据并更新到本地飞控实例 返回值 (Returns)：

• 无

异常 (Raises)： 无

---

SendMsgLoop()

功能说明：启动网络消息发送循环，持续将本地无人机的飞控数据发送到网络中其他节点 返回值 (Returns)：

• 无

异常 (Raises)： 无

示例：

import threading
from RflySimSDK.comm import NetTransNode
from RflySimSDK.PX4MavCtrl import PX4MavCtrler

mav = PX4MavCtrler(1)
net_node = NetTransNode(mav)
net_node.startNetServ()

# 启动发送和接收线程
send_thread = threading.Thread(target=net_node.SendMsgLoop)
recv_thread = threading.Thread(target=net_node.ListenMsgLoop)
send_thread.start()
recv_thread.start()

---

进阶用法示例

展示复杂组合场景（如多类协作、异步控制、批量操作）

以下示例实现了10架无人机集群的异步心跳维护与位置数据收发，通过多线程分离心跳检测和业务消息监听，实现多节点协作飞行的稳定通信：

from RflySimSDK.comm import HeartServer, NetTransNode, GlobalPosData
import threading
import time

# 初始化批量通信节点
uav_num = 10
heart_servers = []
net_nodes = []

# 批量启动心跳服务和网络传输服务
for i in range(uav_num):
    # 为每架无人机分配独立端口
    heart_port = 8000 + i
    msg_port = 9000 + i
    # 启动心跳保活服务
    hs = HeartServer()
    hs.startHeartSer(heart_port)
    heart_servers.append(hs)
    # 启动消息监听收发服务
    node = NetTransNode()
    node.startNetServ(msg_port)
    # 开启异步消息监听循环
    listen_thread = threading.Thread(target=node.ListenMsgLoop, daemon=True)
    listen_thread.start()
    # 开启异步消息发送循环
    send_thread = threading.Thread(target=node.SendMsgLoop, daemon=True)
    send_thread.start()
    net_nodes.append(node)

# 周期性检测连接状态并广播位置数据
try:
    while True:
        # 批量检测所有无人机连接状态
        connect_states = [hs.CheckConnectState() for hs in heart_servers]
        # 若所有无人机连接正常则广播全局位置
        if all(connect_states):
            pos_data = GlobalPosData()
            for idx, node in enumerate(net_nodes):
                # 填充本架无人机当前位置
                pos_data.set_pos(idx, 10*idx, 5*idx, 100 + idx*2)
                # 异步发送位置数据
                node.SendMsgLoop(pos_data.pack())
        # 发送心跳包维持连接
        for hs in heart_servers:
            hs.SendHeartSer()
        time.sleep(0.1)
finally:
    # 退出时批量关闭所有服务
    for hs in heart_servers:
        hs.endHeartSer()
    for node in net_nodes:
        node.endNetServ()

注意事项与避坑指南

• 心跳服务生命周期匹配：需要保证startHeartSer与endHeartSer成对调用，退出程序时必须手动关闭心跳服务，否则会导致端口被持续占用，下次启动时会报端口绑定错误。
• 异步循环的线程处理：ListenMsgLoop和SendMsgLoop都是阻塞式循环方法，必须放在独立的守护线程中运行，若直接在主线程调用会阻塞后续业务逻辑执行，无法实现多节点并行处理。
• 多节点端口冲突避免：批量启动多个HeartServer和NetTransNode实例时，需要为每个实例分配独立的端口号，同一局域网内同一端口无法被多个服务绑定，会导致后续节点启动失败。
• 连接状态检测时机：调用CheckConnectState前必须先启动心跳服务并完成至少两次心跳包交互，未完成初始握手时获取的连接状态不可靠，会误判为断连。

更新日志

• 2025-09-11: fix: 增加Linux端口复用的支持
• 2025-05-29: fix：更新平台协议汇总页面