RflyRosCtrlApi 接口文档¶

简介¶

简述：该文件提供了用于在RflySim仿真环境中，和无人机ROS控制节点通信的API接口，支持按飞机ID配置通信参数，实现对应无人机的控制数据交互。

在RflySim无人机仿真开发场景中，很多开发者会基于ROS框架实现自主导航、视觉感知等自定义控制算法，需要将算法生成的控制指令传输给PX4仿真飞控。该模块属于RflySimSDK的视觉工具链配套通信接口，适配多无人机仿真场景，开发者可以根据飞机ID自动配置对应的通信端口，快速搭建自定义ROS控制节点和仿真飞控之间的数据传输通道，适用于多机协同、视觉导航控制等需要第三方ROS控制节点对接仿真平台的开发场景。

快速开始¶

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

from RflySimSDK.vision.RflyRosCtrlApi import RflyRosCtrlApi

# 1. 初始化ROS控制API，默认连接本机仿真环境，无人机ID为1
ros_ctrl = RflyRosCtrlApi(CopterID=1, ip="127.0.0.1", Com="udp")

# 2. 解锁无人机
ros_ctrl.arm_px4(isArm=True)
print("无人机已解锁")

# 使用示例：这里可以添加后续控制代码，例如起飞、航线飞行等

# 3. 如果需要锁定无人机，调用如下代码
# ros_ctrl.arm_px4(isArm=False)
# print("无人机已锁定")

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：ctrl.IpManager、geometry_msgs.msg、math、mavros_msgs.msg、mavros_msgs.srv、numpy、os、platform、pymavlink、pymavlink.dialects.v20、sensor_msgs.msg、socket、std_msgs.msg、struct、subprocess、sys、threading、time
前置准备：调用此接口前，需要先配置好ROS相关运行环境并完成RflySimSDK的正确安装。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`fifo` 类¶

先进先出（FIFO）队列，用于在RflySim仿真环境中缓存和传递数据，常见于 vision 模块的异步数据收发场景。

`init()`¶

功能说明：初始化空的先进先出队列 参数列表 (Args)：无参数 返回值 (Returns)：

fifo 实例对象

异常 (Raises)：无

`write(data)`¶

功能说明：向FIFO队列末尾写入数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`data`	`Any`	是	-	需要写入队列的数据

返回值 (Returns)：

无

异常 (Raises)：无

`read()`¶

功能说明：从FIFO队列头部读取并移除最早写入的数据 参数列表 (Args)：无参数 返回值 (Returns)：

Any: 队列头部的数据

异常 (Raises)：无

示例：

from RflySimSDK.vision import fifo
# 初始化fifo队列
f = fifo()
# 写入数据
f.write("仿真图像数据")
# 读取数据
data = f.read()

`RflyRosCtrlApi` 类¶

用于ROS环境下PX4飞控控制的通信API，创建与飞控的通信连接实例，支持UDP网络通信和串口直连两种连接模式。

`init(self, CopterID=1, ip="127.0.0.1", Com="udp", port=0)`¶

功能说明：初始化RflyRosCtrlApi通信实例，根据参数建立与PX4飞控的连接，自动处理端口和波特率的映射规则。 参数列表 (Args)：

参数名	类型	默认值	说明
CopterID	int	1	飞机的ID编号，默认端口会根据该ID按平台规则自动计算
ip	str	"127.0.0.1"	UDP模式下数据发送的目标IP地址。默认发往本机127.0.0.1，分布式仿真可指定局域网IP，也可使用255.255.255.255广播地址
Com	str	"udp"	与Pixhawk飞控的连接模式：`udp`表示UDP网络模式，接收CopterSim转发的MAVLink消息；Windows下填`COMx`（如COM3）、Linux下填`/dev/ttyXXX`（如/dev/ttyUSB0）表示串口连接模式
port	int	0	UDP模式下若赋值大于0，会强制使用该端口；若为0则自动按规则计算端口：`port=20100+CopterID*2-2`。串口模式下表示波特率，若为0则自动设置为默认57600波特率

返回值 (Returns)：无 异常 (Raises)：无

`convert_to_payload64(payload_bytes)`¶

功能说明：将输入的载荷字节数组转换为 Mavlink.payload64 格式 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
payload_bytes	Any	是	无	待转换的原始载荷字节数据

返回值 (Returns)：转换后的 Mavlink.payload64 格式数据 异常 (Raises)：无

`convert_to_rosmsg(mavmsg, header)`¶

功能说明：将 pymavlink 消息转换为 Mavlink.msg ROS消息格式，当前仅支持 MAVLink v1.0 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
mavmsg	Any	是	无	输入的 pymavlink 格式消息
header	Any	是	无	ROS消息头信息，用于填充输出ROS消息

返回值 (Returns)：转换后的 Mavlink.msg 格式ROS消息 异常 (Raises)：无

`arm_px4(isArm)`¶

功能说明：对PX4无人机执行上锁/解锁操作 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
isArm	bool	是	无	True为解锁，False为上锁

返回值 (Returns)：无 异常 (Raises)：无

`fillList(data, inLen, fill=0)`¶

功能说明：将输入列表填充至指定长度，使用指定填充值补充空位 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
data	list	是	无	输入待填充的原始列表
inLen	int	是	无	目标输出列表长度
fill	Any	否	0	用于填充空位的值

返回值 (Returns)：填充完成后长度为inLen的列表 异常 (Raises)：无

`InitMavLoop()`¶

功能说明：初始化MAVLink消息循环线程，用于持续处理MAVLink通信 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`SendMavArm(isArm)`¶

功能说明：发送MAVLink上锁/解锁指令到飞控 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
isArm	bool	是	无	True为发送解锁指令，False为发送上锁指令

返回值 (Returns)：无 异常 (Raises)：无

`initOffboard()`¶

功能说明：初始化离板控制（Offboard）模式，准备发送离板控制指令 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`OffboardLoop()`¶

功能说明：启动离板控制循环，持续发送离板控制指令保持模式 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`endOffboard()`¶

功能说明：结束离板控制模式，停止离板控制循环 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`stopRun()`¶

功能说明：停止所有后台运行线程，终止控制循环 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`calcTypeMask(EnList)`¶

功能说明：根据启用字段列表计算MAVLink消息的类型掩码 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
EnList	list[bool]	是	无	各控制字段启用状态列表，True表示对应字段有效

返回值 (Returns)：计算得到的16位类型掩码整数 异常 (Raises)：无

`SendVelNED(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)`¶

功能说明：发送NED坐标系下的速度控制指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vx	float	否	math.nan	NED系北方向速度，单位m/s，nan表示不控制该轴
vy	float	否	math.nan	NED系东方向速度，单位m/s，nan表示不控制该轴
vz	float	否	math.nan	NED系下方向速度，单位m/s，nan表示不控制该轴
yawrate	float	否	math.nan	偏航角角速度，单位rad/s，nan表示不控制

返回值 (Returns)：无 异常 (Raises)：无

`SendVelFRD(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)`¶

功能说明：发送机体FRD坐标系下的速度控制指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vx	float	否	math.nan	FRD系前方向速度，单位m/s，nan表示不控制该轴
vy	float	否	math.nan	FRD系右方向速度，单位m/s，nan表示不控制该轴
vz	float	否	math.nan	FRD系下方向速度，单位m/s，nan表示不控制该轴
yawrate	float	否	math.nan	偏航角角速度，单位rad/s，nan表示不控制

返回值 (Returns)：无 异常 (Raises)：无

`SendPosNED(x=math.nan, y=math.nan, z=math.nan, yaw=math.nan)`¶

功能说明：发送NED坐标系下的位置控制指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
x	float	否	math.nan	NED系北方向位置，单位m，nan表示不控制该轴
y	float	否	math.nan	NED系东方向位置，单位m，nan表示不控制该轴
z	float	否	math.nan	NED系下方向位置，单位m，nan表示不控制该轴
yaw	float	否	math.nan	偏航角，单位rad，nan表示不控制

返回值 (Returns)：无 异常 (Raises)：无

`SendPosVelNED(PosE=[math.nan] * 3, VelE=[math.nan] * 3, yaw=math.nan, yawrate=math.nan)`¶

功能说明：发送NED坐标系下同时包含位置和速度的组合控制指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
PosE	list[float]	否	[math.nan] * 3	NED系北、东、下方向位置数组，单位m，元素为nan表示不控制该轴
VelE	list[float]	否	[math.nan] * 3	NED系北、东、下方向速度数组，单位m/s，元素为nan表示不控制该轴
yaw	float	否	math.nan	偏航角，单位rad，nan表示不控制
yawrate	float	否	math.nan	偏航角角速度，单位rad/s，nan表示不控制

返回值 (Returns)：无 异常 (Raises)：无

`local_pose_callback(msg)`¶

功能说明：ROS本地位置话题回调函数，用于接收并存储无人机本地位置位姿信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
msg	Any	是	无	ROS本地位置话题的消息对象，包含无人机的位姿信息

返回值 (Returns)：无 异常 (Raises)：无

`local_vel_callback(msg)`¶

功能说明：ROS本地速度话题回调函数，用于接收并存储无人机本地速度信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
msg	Any	是	无	ROS本地速度话题的消息对象，包含无人机的线速度信息

返回值 (Returns)：无 异常 (Raises)：无

`mavros_state_callback(msg)`¶

功能说明：ROS mavros状态话题回调函数，用于接收并存储PX4飞控的连接与模式状态信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
msg	Any	是	无	ROS mavros状态话题的消息对象，包含飞控的状态信息

返回值 (Returns)：无 异常 (Raises)：无

`imu_callback(msg)`¶

功能说明：ROS IMU话题回调函数，用于接收并存储IMU传感器的姿态与角速度、线加速度信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
msg	Any	是	无	ROS IMU话题的消息对象，包含IMU的测量数据

返回值 (Returns)：无 异常 (Raises)：无

`gps_callback(msg)`¶

功能说明：ROS GPS话题回调函数，用于接收并存储GPS的定位信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
msg	Any	是	无	ROS GPS话题的消息对象，包含GPS的定位测量数据

返回值 (Returns)：无 异常 (Raises)：无

`q2yaw(q)`¶

功能说明：将四元数转换为偏航角（yaw） 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
q	Any	是	无	输入的四元数，包含姿态旋转信息

返回值 (Returns)：float，转换得到的偏航角（弧度制） 异常 (Raises)：无

`q2Euler(q)`¶

功能说明：将四元数转换为滚转、俯仰、偏航欧拉角 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
q	Any	是	无	输入的四元数，包含姿态旋转信息

返回值 (Returns)：tuple(float, float, float)，转换得到的滚转、俯仰、偏航欧拉角（弧度制） 异常 (Raises)：无

`SendMavArm(isArm=0)`¶

功能说明：发送PX4解锁/上锁指令给飞控 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
isArm	Any	否	0	1表示解锁无人机，0表示上锁无人机

返回值 (Returns)：无 异常 (Raises)：无

`arm()`¶

功能说明：便捷接口，发送无人机解锁指令 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`disarm()`¶

功能说明：便捷接口，发送无人机上锁指令 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`offboard()`¶

功能说明：切换PX4飞控到offboard（离岸）控制模式 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`yawSat(yaw)`¶

功能说明：对偏航角进行弧度范围限幅，将其约束到[-π, π]区间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
yaw	float	是	无	输入待限幅的偏航角（弧度制）

返回值 (Returns)：float，限幅后位于[-π, π]区间的偏航角 异常 (Raises)：无

`sendMavSetParam(param_id_str, param_value, param_type)`¶

功能说明：发送参数设置指令，修改PX4飞控的参数值 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
param_id_str	str	是	无	PX4飞控参数的名称字符串
param_value	float	是	无	需要设置的参数目标值
param_type	Any	是	无	飞控参数的类型

返回值 (Returns)：无 异常 (Raises)：无

`SendMavCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)`¶

功能说明：发送MAVLink长指令给PX4飞控 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
command	int	是	无	MAVLink指令编号，对应具体控制指令
param1	float	否	0	MAVLink指令参数1
param2	float	否	0	MAVLink指令参数2
param3	float	否	0	MAVLink指令参数3
param4	float	否	0	MAVLink指令参数4
param5	float	否	0	MAVLink指令参数5
param6	float	否	0	MAVLink指令参数6
param7	float	否	0	MAVLink指令参数7

返回值 (Returns)：无 异常 (Raises)：无

`SendHILCtrlMsg(ctrls=[0] * 16, idx=0)`¶

功能说明：发送HIL执行器控制指令给PX4，该指令会被转换为PX4 uORB消息rfly_ctrl，用于外部控制量注入。参考MAVLink文档：https://mavlink.io/en/messages/common.html#HIL_ACTUATOR_CONTROLS 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
ctrls	list	否	[0] * 16	16维控制量数组，对应舵机输出控制值
idx	int	否	0	控制分组索引，标识当前发送的控制组编号

返回值 (Returns)：无 异常 (Raises)：无

进阶用法示例¶

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

import RflySimSDK.vision as rv
from threading import Thread
import time

# 多机批量离线航点填充 + 异步offboard控制 多类协作进阶示例
def uav_offboard_task(uav_id, waypoints, frame_buffer):
    # 初始化px4 offboard控制循环
    ros_api = rv.RflyRosCtrlApi()
    ros_api.InitMavLoop(uav_id)
    ros_api.initOffboard(uav_id)
    # 批量填充航点
    ros_api.fillList(uav_id, waypoints)
    # 解锁无人机
    ros_api.arm_px4(uav_id)
    ros_api.SendMavArm(uav_id, True)
    # 异步读取视觉帧做避障调整
    while True:
        if not frame_buffer.read():
            continue
        obstacle_info = frame_buffer.read()
        if obstacle_info is None:
            break
        # 根据 obstacle_info 调整航点后重新进入offboard循环
        ros_api.OffboardLoop(uav_id, 1)
        time.sleep(0.1)
    # 退出offboard模式
    ros_api.endOffboard(uav_id)
    ros_api.stopRun(uav_id)

# 初始化多任务共享的视觉帧缓冲fifo
vision_frame_buf = rv.fifo()
# 批量定义3架无人机的初始航点
uav_waypoints = [
    [(0,0,1), (0,1,1), (1,1,1)],
    [(0,0,2), (1,0,2), (1,1,2)],
    [(0,0,1.5), (-1,0,1.5), (-1,-1,1.5)]
]
# 多线程异步启动多机协作任务
threads = []
for idx, wps in enumerate(uav_waypoints):
    t = Thread(target=uav_offboard_task, args=(idx+1, wps, vision_frame_buf))
    t.start()
    threads.append(t)

注意事项与避坑指南¶

Mav循环初始化顺序：必须先调用InitMavLoop完成飞控通信链路初始化，才能调用解锁、offboard控制等其他方法，否则会出现指令无响应问题。
fifo线程安全限制：fifo类仅提供基础的读写缓存功能，多线程并发读写时需要手动加互斥锁，否则会出现脏读或缓存数据错乱。
offboard模式退出要求：完成offboard任务后必须主动调用endOffboard，否则飞控会一直保持offboard模式，无法响应后续的手动或自动控制指令。
批量航点填充参数要求：调用fillList批量写入航点时，需要确保传入的航点列表格式与方法要求一致，单架无人机单次传入航点数量不可超过飞缓存限制，否则会出现航点丢失问题。

更新日志¶

2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云
2025-03-31: fix: 修复1.13之后版本，Offboard无法起飞的问题。
2024-08-05: fix：增加HTML版API注释
2024-07-17: fix：更新VisionCaptureApi接口API
2024-06-05: fix：更新ROS接口
2024-06-04: fix: 更新库文件
2024-05-27: fix：兼容ROS1、ROS2的多机控制框架。
2024-05-26: fix: ROS1/2多节点兼容。
2024-05-26: fix:更新部分问题
2024-05-25: fix:增加ROS2多机的兼容
2024-05-25: fix：增加注释
2024-05-25: 新增ROS2兼容，并增加和底层飞控通信的接口。
2024-05-22: fix: 增加一个mavros控制的接口

RflyRosCtrlApi 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

fifo 类¶

__init__()¶

write(data)¶

read()¶

RflyRosCtrlApi 类¶

__init__(self, CopterID=1, ip="127.0.0.1", Com="udp", port=0)¶

convert_to_payload64(payload_bytes)¶

convert_to_rosmsg(mavmsg, header)¶

arm_px4(isArm)¶

fillList(data, inLen, fill=0)¶

InitMavLoop()¶

SendMavArm(isArm)¶

initOffboard()¶

OffboardLoop()¶

endOffboard()¶

stopRun()¶

calcTypeMask(EnList)¶

SendVelNED(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)¶

SendVelFRD(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)¶

SendPosNED(x=math.nan, y=math.nan, z=math.nan, yaw=math.nan)¶

SendPosVelNED(PosE=[math.nan] * 3, VelE=[math.nan] * 3, yaw=math.nan, yawrate=math.nan)¶

local_pose_callback(msg)¶

local_vel_callback(msg)¶

mavros_state_callback(msg)¶

imu_callback(msg)¶

gps_callback(msg)¶

q2yaw(q)¶

q2Euler(q)¶

SendMavArm(isArm=0)¶

arm()¶

disarm()¶

offboard()¶

yawSat(yaw)¶

sendMavSetParam(param_id_str, param_value, param_type)¶

SendMavCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)¶

SendHILCtrlMsg(ctrls=[0] * 16, idx=0)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`fifo` 类¶

`init()`¶

`write(data)`¶

`read()`¶

`RflyRosCtrlApi` 类¶

`init(self, CopterID=1, ip="127.0.0.1", Com="udp", port=0)`¶

`convert_to_payload64(payload_bytes)`¶

`convert_to_rosmsg(mavmsg, header)`¶

`arm_px4(isArm)`¶

`fillList(data, inLen, fill=0)`¶

`InitMavLoop()`¶

`SendMavArm(isArm)`¶

`initOffboard()`¶

`OffboardLoop()`¶

`endOffboard()`¶

`stopRun()`¶

`calcTypeMask(EnList)`¶

`SendVelNED(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)`¶

`SendVelFRD(vx=math.nan, vy=math.nan, vz=math.nan, yawrate=math.nan)`¶

`SendPosNED(x=math.nan, y=math.nan, z=math.nan, yaw=math.nan)`¶

`SendPosVelNED(PosE=[math.nan] * 3, VelE=[math.nan] * 3, yaw=math.nan, yawrate=math.nan)`¶

`local_pose_callback(msg)`¶

`local_vel_callback(msg)`¶

`mavros_state_callback(msg)`¶

`imu_callback(msg)`¶

`gps_callback(msg)`¶

`q2yaw(q)`¶

`q2Euler(q)`¶

`SendMavArm(isArm=0)`¶

`arm()`¶

`disarm()`¶

`offboard()`¶

`yawSat(yaw)`¶

`sendMavSetParam(param_id_str, param_value, param_type)`¶

`SendMavCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)`¶

`SendHILCtrlMsg(ctrls=[0] * 16, idx=0)`¶