api 接口文档¶
简介¶
简述：本文件是RflySimSDK无人机仿真平台的无人机控制核心模块，提供了无人机控制基类、不同通讯控制模式以及PID控制器实现，支撑各类无人机控制算法的开发与部署。
该模块面向无人机开发与仿真测试场景，是用户实现自定义无人机控制逻辑的基础依赖。其中Ctrl类提供了无人机控制的基础框架，CtMode类支持不同的控制通讯模式选择（其中Redis模式仅企业版提供支持），适配不同版本平台的开发需求；提供的PID类针对控制调用间隔稳定的场景做了适配，不在控制器内部重复计算时间间隔，而是通过PID参数直接完成控制量调整，简化了固定频率控制场景下的参数调试过程，适合无人机位置控制、姿态控制等各类常规固定频率控制任务使用。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
from RflySimSDK.ctrl import Ctrl
import time
# 1. 初始化控制对象，默认使用本机UDP连接，控制ID为1的无人机
copter_ctrl = Ctrl(copter_id=1, ip="127.0.0.1")
# 2. 初始化控制循环，使用位置控制模式(ct_mode=2对应位置控制)，不启用offboard模式
copter_ctrl.init_loop(ct_mode=2, offboard=False)
# 3. 等待解锁和初始化完成
time.sleep(3)
# 4. 命令无人机起飞到NED坐标系下10米高度（NED下高度为负，所以此处填-10）
copter_ctrl.takeoff(height=-10)
# 5. 等待起飞完成
time.sleep(10)
# 6. 保持悬停，循环发送控制指令保持连接
while True:
# 发送空指令保持位置悬停
if copter_ctrl.is_full_send():
time.sleep(0.01)
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
DllSimCtrlAPI、PX4MavCtrlV4、numpy、time - 前置准备：调用此接口前，必须先完成RflySimSDK的初始化并导入RflySimSDK.ctrl模块。
核心接口说明¶
该模块 api.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
无
全局/独立函数¶
无
Ctrl 类¶
PX4 飞控控制类，继承自PX4MavCtrler，提供对无人机的基础控制功能，支持仿真与实物场景连接。
__init__(copter_id=1, ip="127.0.0.1", com="udp", port=0, simulink_dll=False)¶
功能说明：初始化Ctrl对象，建立与PX4飞控（仿真或实物）的连接。 参数列表 (Args)：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| copter_id | 1 | 无人机编号，用于区分多机场景中的不同无人机 | |
| ip | 127.0.0.1 | 飞控连接的IP地址，本地仿真默认使用本地回环地址 | |
| com | udp | 通信协议类型，可选udp（网络通信，仿真常用）或串口通信 |
|
| port | 0 | 通信端口号，0表示自动分配端口 | |
| simulink_dll | False | 是否为Simulink动态链接库仿真模式，True时适配Simulink联合仿真 |
返回值 (Returns)：无 异常 (Raises)：无
init_loop(ct_mode="2", offboard=False)¶
功能说明：初始化控制循环，设置控制模式与offboard选项 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ct_mode | None | 否 | "2" | 控制模式参数 |
| offboard | None | 否 | False | 是否启用offboard模式 |
返回值 (Returns)：无 异常 (Raises)：无
is_full_send()¶
功能说明：检查是否已完成全量指令发送 参数列表 (Args)：无参数 返回值 (Returns)：布尔值，True表示已完成全量发送，False表示未完成 异常 (Raises)：无
takeoff(height=0, pos_x=0, pos_y=0)¶
功能说明：执行无人机起飞操作，该高度为NED坐标系下的高度，PX4版本的固定翼支持指定起飞后位置，综合模型只支持指定高度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| height | None | 否 | 0 | NED坐标系下的起飞目标高度，单位m |
| pos_x | None | 否 | 0 | NED坐标系下起飞目标x坐标，单位m，仅PX4版本固定翼支持 |
| pos_y | None | 否 | 0 | NED坐标系下起飞目标y坐标，单位m，仅PX4版本固定翼支持 |
返回值 (Returns)：无 异常 (Raises)：无
return_home(height=0)¶
功能说明：执行返航操作，水平位置移动到Home点，高度保持当前设置值不变 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| height | None | 否 | 0 | 返航过程的保持高度，单位m |
返回值 (Returns)：无 异常 (Raises)：无
land(height=0)¶
功能说明：执行降落操作，将高度降落到Home点对应高度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| height | None | 否 | 0 | 降落目标高度，单位m |
返回值 (Returns)：无 异常 (Raises)：无
send_pos_ned(pos=None, yaw=None)¶
功能说明：发送NED坐标系下的位置控制指令，PX4版本时每架飞机坐标相对于起飞点，综合模型时坐标相对UE中心；差异来自综合模型使用真实位置控制，PX4使用滤波后位置控制 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| pos | None | 否 | None | NED坐标系下x,y,z方向位置，单位m |
| yaw | None | 否 | None | 目标偏航角，单位rad |
返回值 (Returns)：无 异常 (Raises)：无
send_pos_speed_fw(pos=None, speed=None)¶
功能说明：为固定翼综合模型发送同时包含位置与速度的控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| pos | None | 否 | None | 目标位置，单位m |
| speed | None | 否 | None | 目标飞行速度 |
返回值 (Returns)：无 异常 (Raises)：无
send_pos_global(pos=None, yaw=None)¶
功能说明：发送全局坐标系下的位置控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| pos | None | 否 | None | 全局坐标系下目标位置 |
| yaw | None | 否 | None | 目标偏航角，单位rad |
返回值 (Returns)：无 异常 (Raises)：无
send_vel_ned(vel=None, yaw_rate=None)¶
功能说明：发送NED坐标系下的速度控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vel | None | 否 | None | NED坐标系下x,y,z方向目标速度，单位m/s |
| yaw_rate | None | 否 | None | 目标偏航角速度，单位rad/s |
返回值 (Returns)：无 异常 (Raises)：无
send_vel_body(vel=None, yaw_rate=None)¶
功能说明：发送机体坐标系下的速度控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vel | None | 否 | None | 机体坐标系下x,y,z方向目标速度，单位m/s |
| yaw_rate | None | 否 | None | 目标偏航角速度，单位rad/s |
返回值 (Returns)：无 异常 (Raises)：无
send_acc(acc=None)¶
功能说明：发送加速度控制指令，仅适用于旋翼无人机；NED坐标系下x，y方向响应非常灵敏，z方向为了定高响应缓慢 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| acc | None | 否 | None | NED坐标系下期望加速度，单位m/s² |
返回值 (Returns)：无 异常 (Raises)：无
send_att_thrust(att=None, thrust=None)¶
功能说明：发送姿态与油门控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| att | None | 否 | None | 欧拉角[滚转角、俯仰角、偏航角]，单位rad |
| thrust | None | 否 | None | 油门控制量 |
返回值 (Returns)：无 异常 (Raises)：无
send_att(att=None)¶
功能说明：发送姿态控制指令 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| att | None | 否 | None | 欧拉角[滚转角、俯仰角、偏航角]，单位rad |
返回值 (Returns)：无 异常 (Raises)：无
send_cruise_speed_fw(speed=None)¶
功能说明：设置固定翼巡航速度，仅支持固定翼，对应QGC参数FW_AIRSPD_TRIM，速度限制范围为10-20m/s，默认值为15m/s，速度限制定义在src/modules/fw_pos_control_l1/fw_pos_control_l1_params.c
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| speed | None | 否 | None | 固定翼目标水平巡航速度，单位m/s |
返回值 (Returns)：无 异常 (Raises)：无
send_cruise_radius_fw(radius=None)¶
功能说明：设置固定翼盘旋半径，仅支持固定翼，对应QGC参数NAV_LOITER_RAD；设置超出范围的值在QGC中会显示修改，但实际不会超过范围
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| radius | None | 否 | None | 固定翼盘旋半径，单位m，有效范围25m-1000m，正常误差可达10-20m |
返回值 (Returns)：无 异常 (Raises)：无
get_vehicle_id()¶
功能说明：获取当前控制载具的ID 参数列表 (Args)： 无参数 返回值 (Returns)：返回载具ID，默认从1开始编号 异常 (Raises)：无
get_time_s()¶
功能说明：获取当前仿真时间 参数列表 (Args)： 无参数 返回值 (Returns)：当前仿真时间，单位为秒 异常 (Raises)：无
get_pos_ned()¶
功能说明：获取当前载具在NED坐标系下的位置 参数列表 (Args)： 无参数 返回值 (Returns)：PX4返回局部NED坐标系下的位置，每一架飞机都以起飞点为原点；综合模型返回全局NED(相对UE中心)位置，格式为[north, east, down]，单位为米 异常 (Raises)：无
get_pos_ned_global()¶
功能说明：获取当前载具在全局NED坐标系下的位置 参数列表 (Args)： 无参数 返回值 (Returns)：返回全局NED(相对UE中心)位置，格式为[north, east, down]，单位为米 异常 (Raises)：无
get_pos_global()¶
功能说明：获取当前载具在WGS84坐标系下的经纬度高度 参数列表 (Args)： 无参数 返回值 (Returns)：WGS84坐标系下位置，格式为[纬度, 经度, 高度]，单位为度、度、米 异常 (Raises)：无
get_home_pos()¶
功能说明：获取当前载具Home点在WGS84坐标系下的位置 参数列表 (Args)： 无参数 返回值 (Returns)：WGS84坐标系下Home点位置，格式为[纬度, 经度, 高度]，单位为度、度、米 异常 (Raises)：无
get_vel_ned()¶
功能说明：获取当前载具在NED坐标系下的速度 参数列表 (Args)： 无参数 返回值 (Returns)：NED坐标系下速度，格式为[north速度, east速度, down速度]，单位为m/s 异常 (Raises)：无
get_acc()¶
功能说明：获取当前载具在载体坐标系下的加速度，目前仅综合模型支持该功能 参数列表 (Args)： 无参数 返回值 (Returns)：载体坐标系中加速度，格式为[x轴加速度, y轴加速度, z轴加速度]，单位为m/s² 异常 (Raises)：无
get_euler()¶
功能说明：获取当前载具的欧拉角姿态 参数列表 (Args)： 无参数 返回值 (Returns)：欧拉角姿态，格式为[滚转, 俯仰, 偏航]，单位为弧度 异常 (Raises)：无
get_angular_rate()¶
功能说明：获取当前载具的角速度 参数列表 (Args)： 无参数 返回值 (Returns)：载体坐标系下的角速度，格式为[x轴角速度, y轴角速度, z轴角速度]，单位为弧度/秒 异常 (Raises)：无
get_quaternion()¶
功能说明：获取当前载具姿态的四元数描述，目前仅综合模型支持返回四元数 参数列表 (Args)： 无参数 返回值 (Returns)：四元数描述的姿态，格式为[w, x, y, z] 异常 (Raises)：无
get_actuator_speed()¶
功能说明：获取各电机的转速 参数列表 (Args)： 无参数 返回值 (Returns)：电机转速列表，每个元素单位为转/min，顺序对应电机编号 异常 (Raises)：无
get_max_vel_xy()¶
功能说明：获取载具设置的最大水平速度 参数列表 (Args)： 无参数 返回值 (Returns)：最大水平速度，单位为m/s 异常 (Raises)：无
get_max_vel_z()¶
功能说明：获取载具设置的最大竖直速度 参数列表 (Args)： 无参数 返回值 (Returns)：最大竖直速度，单位为m/s 异常 (Raises)：无
get_max_acc_xy()¶
功能说明：获取载具设置的最大水平加速度 参数列表 (Args)： 无参数 返回值 (Returns)：最大水平加速度，单位为m/s² 异常 (Raises)：无
get_max_acc_z()¶
功能说明：获取无人机最大竖直加速度
参数列表 (Args)：
无参数
返回值 (Returns)：float 最大竖直加速度，单位为 m/s²
异常 (Raises)：无
CtMode 类¶
无人机通信模式管理类，用于定义和判断RflySim平台中无人机与仿真环境的不同通信模式，其中Redis模式仅企业版支持。该类预定义了多种常用通信模式常量，方便开发者直接调用。
__init__()¶
功能说明：初始化 CtMode 类实例
参数列表 (Args)：
无参数
返回值 (Returns)：
CtMode实例对象
异常 (Raises)： 无
set(mode)¶
功能说明：设置当前实例的通信模式 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
mode |
int |
是 | - | 需要设置的通信模式，可使用该类预定义的常量，如 CtMode.UDP_Full、CtMode.MAVLink_Full 等 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
is_udp_full()¶
功能说明：判断当前通信模式是否为UDP全模式 返回值 (Returns)：
bool: 若当前为UDP全模式返回True，否则返回False
异常 (Raises)： 无
is_udp_simple()¶
功能说明：判断当前通信模式是否为UDP简化模式 返回值 (Returns)：
bool: 若当前为UDP简化模式返回True，否则返回False
异常 (Raises)： 无
is_mav_full()¶
功能说明：判断当前通信模式是否为MAVLink全模式 返回值 (Returns)：
bool: 若当前为MAVLink全模式返回True，否则返回False
异常 (Raises)： 无
is_mav_simple()¶
功能说明：判断当前通信模式是否为MAVLink简化模式 返回值 (Returns)：
bool: 若当前为MAVLink简化模式返回True，否则返回False
异常 (Raises)： 无
is_mav_no_send()¶
功能说明：判断当前通信模式是否为MAVLink只接收不发送模式 返回值 (Returns)：
bool: 若当前为MAVLink只接收不发送模式返回True，否则返回False
异常 (Raises)： 无
is_mav_no_gps()¶
功能说明：判断当前通信模式是否为MAVLink无GPS模式 返回值 (Returns)：
bool: 若当前为MAVLink无GPS模式返回True，否则返回False
异常 (Raises)： 无
is_redis_full()¶
功能说明：判断当前通信模式是否为Redis全模式（仅企业版支持） 返回值 (Returns)：
bool: 若当前为Redis全模式返回True，否则返回False
异常 (Raises)： 无
is_redis_simple()¶
功能说明：判断当前通信模式是否为Redis简化模式（仅企业版支持） 返回值 (Returns)：
bool: 若当前为Redis简化模式返回True，否则返回False
异常 (Raises)： 无
is_udp()¶
功能说明：判断当前通信模式是否属于UDP类型（包含全模式和简化模式） 返回值 (Returns)：
bool: 若当前为UDP类型通信模式返回True，否则返回False
异常 (Raises)： 无
is_mav()¶
功能说明：判断当前通信模式是否属于MAVLink类型（包含所有MAVLink相关模式） 返回值 (Returns)：
bool: 若当前为MAVLink类型通信模式返回True，否则返回False
异常 (Raises)： 无
is_redis()¶
功能说明：判断当前通信模式是否属于Redis类型（包含全模式和简化模式，仅企业版支持） 返回值 (Returns)：
bool: 若当前为Redis类型通信模式返回True，否则返回False
异常 (Raises)： 无
is_full()¶
功能说明：判断当前通信模式是否为全量传输模式（包含UDP全模式、MAVLink全模式、Redis全模式） 返回值 (Returns)：
bool: 若当前为全量传输模式返回True，否则返回False
异常 (Raises)： 无
示例：
from RflySimSDK.ctrl import CtMode
# 初始化通信模式实例并设置为MAVLink全模式
mode = CtMode()
mode.set(CtMode.MAVLink_Full)
# 判断通信模式类型
print(mode.is_mav()) # 输出: True
print(mode.is_full()) # 输出: True
print(mode.is_udp()) # 输出: False
预定义类常量¶
| 常量名 | 类型 | 值 | 说明 |
|---|---|---|---|
UDP_Full |
int |
0 |
UDP全通信模式 |
UDP_Simple |
int |
1 |
UDP简化通信模式 |
MAVLink_Full |
int |
2 |
MAVLink全通信模式 |
MAVLink_Simple |
int |
3 |
MAVLink简化通信模式 |
MAVLink_NoSend |
int |
4 |
MAVLink只接收不发送模式 |
MAVLink_NoGPS |
int |
5 |
MAVLink无GPS输入模式 |
Mavlink_Vision |
int |
6 |
MAVLink视觉定位模式 |
Redis_Full |
int |
7 |
Redis全通信模式（仅企业版支持） |
Redis_Simple |
int |
8 |
Redis简化通信模式（仅企业版支持） |
PID 类¶
本控制器适用于调用时间间隔在一个常值附近的情形，在控制器中不计算时间间隔，通过PID参数进行调整，常用于无人机飞行控制中固定周期的偏差调节场景。
__init__(p=0.0, i=0.0, d=0.0)¶
功能说明：初始化PID控制器，设置比例、积分、微分三个系数 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
p |
float |
否 | 0.0 |
比例系数，用于调节比例控制增益 |
i |
float |
否 | 0.0 |
积分系数，用于消除稳态误差 |
d |
float |
否 | 0.0 |
微分系数，用于抑制偏差变化，提高系统稳定性 |
返回值 (Returns)：
PID实例对象
异常 (Raises)：
- 无
pid(err)¶
功能说明：根据输入的偏差值计算PID控制输出量 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
err |
float |
是 | - | 当前控制偏差，即设定值减实际值 |
返回值 (Returns)：
float: 计算得到的PID控制输出量
异常 (Raises)：
- 无
示例：
# 创建比例系数0.5，积分系数0.1的PID控制器
pid_ctrl = PID(p=0.5, i=0.1)
# 输入当前偏差计算控制输出
output = pid_ctrl.pid(err=2.0)
reset()¶
功能说明：重置PID控制器的积分累积项和历史偏差，清除过往控制状态 返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
import RflySimSDK.ctrl as rfly_ctrl
import time
from concurrent.futures import ThreadPoolExecutor
# 多旋翼+固定翼多机编队协同起飞进阶示例
# 1. 初始化多架不同类型无人机的控制与通信模式
vehicles = [
{"id": 1, "type": "multirotor", "ctrl": rfly_ctrl.Ctrl(), "mode": rfly_ctrl.CtMode()},
{"id": 2, "type": "fixedwing", "ctrl": rfly_ctrl.Ctrl(), "mode": rfly_ctrl.CtMode()},
{"id": 3, "type": "multirotor", "ctrl": rfly_ctrl.Ctrl(), "mode": rfly_ctrl.CtMode()},
]
# 批量设置全量UDP通信模式
for veh in vehicles:
veh["mode"].set(veh["mode"].is_udp_full())
veh["ctrl"].init_loop(veh_id=veh["id"])
# 异步批量起飞，避免顺序起飞等待浪费时间
def async_takeoff(veh):
if veh["type"] == "multirotor":
return veh["ctrl"].takeoff(target_alt=5.0)
return True
with ThreadPoolExecutor(max_workers=3) as executor:
results = list(executor.map(async_takeoff, vehicles))
time.sleep(8) # 等待所有无人机稳定达到起飞高度
# 编队位置控制，结合PID修正位置误差
pid_x = rfly_ctrl.PID(kp=1.2, ki=0.1, kd=0.05)
pid_y = rfly_ctrl.PID(kp=1.2, ki=0.1, kd=0.05)
formation_offset = [(0, 2), (-2, 0), (0, -2)]
leader_ned = [0, 0, -5]
for step in range(100):
for idx, veh in enumerate(vehicles):
target_x = leader_ned[0] + formation_offset[idx][0]
target_y = leader_ned[1] + formation_offset[idx][1]
if veh["type"] == "multirotor":
vel_x = pid_x.pid(target_x - veh["current_x"])
vel_y = pid_y.pid(target_y - veh["current_y"])
veh["ctrl"].send_vel_body(vx=vel_x, vy=vel_y, vz=0, yaw_rate=0)
else:
veh["ctrl"].send_pos_speed_fw(north=target_x, east=target_y, down=-5, airspeed=12)
# 更新领机位置后循环
leader_ned[0] += 0.5
time.sleep(0.1)
# 批量返航降落
for veh in vehicles:
veh["ctrl"].return_home()
time.sleep(20)
for veh in vehicles:
veh["ctrl"].land()
注意事项与避坑指南¶
- 初始化必须匹配通信模式：调用
Ctrl.init_loop()前必须先通过CtMode.set()设置对应通信模式，若模式设置不匹配会导致控制指令无法正常下发，仿真中无任何报错但无人机不响应控制。 - 固定翼与多旋翼控制方法不可混用：
send_pos_speed_fw是固定翼专用的位置速度控制接口，直接用于多旋翼不会生效；多旋翼的速度控制接口send_vel_body也不适用于固定翼的定高飞行逻辑。 - PID控制器使用前需重置状态：重复利用同一个PID控制器控制不同无人机或者切换控制任务时，必须调用
PID.reset()清除积分累积项，否则会产生超调量异常增大的问题。 - 满发送模式需匹配链路带宽：若使用
is_udp_full/is_mav_full这类全量数据发送模式，需要保证仿真网络带宽足够，若出现丢包严重可切换为is_udp_simple简化发送模式降低带宽占用。
更新日志¶
2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云2024-09-09: 更新Mavlink_Vision的仿真模式2024-07-18: fix:更新API主页索引2023-11-09: feat: 增加云兼容接口