PX4MavCtrlV4 接口文档¶
简介¶
简述：提供PX4飞控无人机离线控制所需的各类枚举、工具类与核心控制类，实现RflySim平台下与PX4飞控的MAVLink通信对接。
该模块是RflySimSDK中负责PX4无人机通信控制的核心组件，基于MAVLink协议适配了PX4飞控的自定义模式、离线控制消息格式，支持多无人机的ID寻址与端口识别。适配RflySim仿真平台的通信规则，既支持通过飞机ID识别目标无人机，也支持通过自定义端口建立通信连接，可用于各类离线航迹规划、控制算法开发、多无人机协同任务仿真等场景，为上层控制算法提供统一的通信接口与参数定义支撑。
模块内置了各类标准MAVLink离线消息的掩码生成类、飞控自定义模式枚举，还提供了适配平台Redis通信机制的键类型定义，方便开发者快速匹配PX4飞控的控制逻辑，无需手动处理通信协议的底层细节。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
from RflySimSDK.ctrl.PX4MavCtrlV4 import PX4MavCtrler
import time
# 1. 初始化PX4飞控控制器，这里使用本地仿真环境默认配置，无人机ID为1
mav_ctrl = PX4MavCtrler(ID=1, ip="127.0.0.1", Com="udp", port=0)
# 2. 发送全局启动信号，唤醒所有仿真无人机
mav_ctrl.sendStartMsg(copterID=-1)
# 3. 等待启动信号确认，阻塞程序直到准备完成
mav_ctrl.waitForStartMsg()
# 4. 示例：起飞后悬停10秒后退出
print("无人机已启动，开始执行任务")
# 此处可添加你的控制逻辑，例如发送位置控制指令
time.sleep(10)
print("任务执行完成")
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
copy、ctrl.DllSimCtrlAPI、ctrl.IpManager、math、numpy、os、platform、pymavlink、pymavlink.dialects.v20、socket、struct、sys、threading、time - 前置准备：调用此接口前，必须完成RflySimSDK的环境配置并导入对应模块。
核心接口说明¶
该模块 PX4MavCtrlV4.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
无
枚举定义¶
PX4_CUSTOM_MAIN_MODE¶
| 名称 | 类型 | 值 | 说明 |
|---|---|---|---|
PX4_CUSTOM_MAIN_MODE_MANUAL |
int |
1 |
- |
PX4_CUSTOM_MAIN_MODE_ALTCTL |
int |
2 |
- |
PX4_CUSTOM_MAIN_MODE_POSCTL |
int |
3 |
- |
PX4_CUSTOM_MAIN_MODE_AUTO |
int |
4 |
- |
PX4_CUSTOM_MAIN_MODE_ACRO |
int |
5 |
- |
PX4_CUSTOM_MAIN_MODE_OFFBOARD |
int |
6 |
- |
PX4_CUSTOM_MAIN_MODE_STABILIZED |
int |
7 |
- |
PX4_CUSTOM_MAIN_MODE_RATTITUDE |
int |
8 |
- |
PX4_CUSTOM_MAIN_MODE_SIMPLE |
int |
9 |
- |
PX4_CUSTOM_SUB_MODE_AUTO¶
| 名称 | 类型 | 值 | 说明 |
|---|---|---|---|
PX4_CUSTOM_SUB_MODE_AUTO_READY |
int |
1 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_TAKEOFF |
int |
2 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_LOITER |
int |
3 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_MISSION |
int |
4 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_RTL |
int |
5 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_LAND |
int |
6 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_RTGS |
int |
7 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_FOLLOW_TARGET |
int |
8 |
- |
PX4_CUSTOM_SUB_MODE_AUTO_PRECLAND |
int |
9 |
- |
全局/独立函数¶
无
RedisKey 类¶
Redis 通道的 Key 类型，通过类型 ID，可以从redisKey中查出通道的字符串名称。
GetRedisKey(port)¶
功能说明：根据端口号获取对应Redis通道Key名称 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
port |
任意类型 | 是 | - | 端口编号 |
返回值 (Returns)：
str: 对应Redis通道的Key名称
异常 (Raises):
- 无
示例：
类变量¶
| 变量名 | 类型 | 值 | 说明 |
|---|---|---|---|
SIL |
str |
SIL |
软件在环仿真Redis通道Key |
SIL_TRUE |
str |
SIL_TRUE |
真实无人机SIL模式Redis通道Key |
R3D |
str |
RFLYSIM_3D |
RflySim 3D可视化Redis通道Key |
SIL_RECV |
str |
SIL_RECV |
SIL接收通道Redis Key |
SIL_TRUE_RECV |
str |
SIL_TRUE_RECV |
真实无人机SIL模式接收通道Redis Key |
fifo 类¶
先进先出（FIFO）队列，用于存储和访问按顺序添加的数据元素。
__init__()¶
功能说明：初始化一个空的先进先出队列 参数列表 (Args)： 无 返回值 (Returns)：
fifo实例对象
异常 (Raises)： 无
write(data)¶
功能说明：向队列末尾添加新数据元素 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
data |
Any |
是 | - | 需要添加到队列的数据元素 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
read()¶
功能说明：从队列头部取出并返回最早添加的数据元素（遵循先进先出规则） 参数列表 (Args)： 无 返回值 (Returns)：
- 队列头部最早添加的数据元素，类型与添加时一致
异常 (Raises)： 无
示例：
# 创建一个FIFO队列
queue = fifo()
# 写入数据
queue.write(10)
queue.write("test_data")
# 读取数据，按照写入顺序返回
first_data = queue.read()
second_data = queue.read()
PosTypeMask 类¶
用于生成PX4 offboard控制消息中的类型掩码位图，对应MAVLink协议中POSITION_TARGET_TYPEMASK定义，用于指定哪些控制量会被飞控忽略。
__init__(ignore_all=False)¶
功能说明：初始化掩码对象，默认初始化为速度+偏航角速率控制模式，可通过参数设置忽略所有offboard控制量。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ignore_all |
bool |
否 | False |
为True时忽略所有offboard控制量，为False时使用默认的速度+偏置角速率模式 |
返回值 (Returns)：
PosTypeMask实例对象
异常 (Raises)： 无
mask()¶
功能说明：获取计算完成的最终类型掩码值。 参数列表 (Args)： 无
返回值 (Returns)：
int: 最终的offboard控制类型掩码位图，可直接用于生成MAVLink位置控制消息
异常 (Raises)： 无
示例：
from RflySimSDK.ctrl import PosTypeMask
# 创建默认速度+偏航角速率模式的掩码对象
mask_obj = PosTypeMask()
# 获取掩码值
type_mask = mask_obj.mask()
# 创建忽略所有控制量的掩码对象
ignore_all_mask = PosTypeMask(ignore_all=True).mask()
AttTypeMask 类¶
用于生成离线（offboard）控制消息的位掩码，对应MAVLink协议中ATTITUDE_TARGET_TYPEMASK的定义，常用于PX4无人机离线控制场景中标记需要忽略的控制量。
__init__(ignore_all=False)¶
功能说明：初始化位掩码对象，默认初始化为姿态+油门控制模式，当ignore_all为True时会忽略所有离线控制量。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ignore_all |
bool |
否 | False |
是否忽略所有离线控制量，设为True时所有控制位均标记为忽略 |
返回值 (Returns)：
AttTypeMask实例对象
异常 (Raises)： 无
mask()¶
功能说明：获取计算完成的位掩码值，用于发送给飞控的离线控制消息。 参数列表 (Args)： 无 返回值 (Returns)：
int: 计算得到的控制位掩码值
异常 (Raises)： 无
示例：
from RflySimSDK.ctrl import AttTypeMask
# 创建默认姿态油门模式的位掩码
att_mask = AttTypeMask()
mask_val = att_mask.mask()
# 忽略所有控制量的位掩码
ignore_mask = AttTypeMask(ignore_all=True)
ignore_val = ignore_mask.mask()
PX4ExtMsg 类¶
该类用于表示PX4飞控拓展消息，作为RflySimSDK中PX4拓展消息相关数据的基础容器类。
__init__()¶
功能说明：初始化PX4ExtMsg类实例 参数列表 (Args)： 无参数 返回值 (Returns)：
PX4ExtMsg实例对象
异常 (Raises)： 无
PX4MavCtrler 类¶
创建PX4飞控的MAVLink通信控制实例，支持仿真、真机直连、串口连接等多种通信模式。
__init__(ID=1, ip='127.0.0.1', Com='udp', port=0)¶
功能说明：初始化PX4飞控MAVLink通信实例，根据输入参数配置对应通信模式与连接参数。 参数列表 (Args)：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| ID | - | 1 | 飞机ID或端口号：ID≤10000表示飞机的CopterID号；ID>10000表示通信端口号port（兼容旧接口的过渡定义），COM、Direct模式下仅表示飞机ID。 |
| ip | str | 127.0.0.1 | 数据发送的目标IP地址：默认发往本机127.0.0.1；分布式仿真可指定局域网IP，也可设置为广播地址255.255.255.255。Redis模式下为服务器地址。 |
| Com | str | udp | 与飞控的连接模式：udp：默认UDP模式，接收CopterSim转发的MAVLink消息，使用port端口发、port+1端口收；COMx//dev/ttyxxx：串口连接模式，Windows下为COM口名称，Linux下为设备路径，通过USB/数传连接飞控；Direct：UDP直连模式（真机模式），使用同一端口收发数据；redis：Redis通信模式，通过Redis服务器实现数据交互。 |
| port | int | 0 | 端口/波特率配置： UDP模式：0表示自动按规则计算端口 port=20100+CopterID*2-2，大于0则强制使用指定端口；串口模式：表示波特率，0默认映射为57600； Direct模式：指定收发共用的端口号； Redis模式：指定Redis服务器端口，0默认映射为默认端口6379。 |
返回值 (Returns)：无 异常 (Raises)：无
fillList(data, inLen, fill="0")¶
功能说明：对输入列表进行填充，将列表长度调整到指定长度，不足时使用指定值填充 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| data | Any | 是 | 无 | 待处理的输入列表 |
| inLen | Any | 是 | 无 | 目标列表长度 |
| fill | Any | 否 | "0" | 填充使用的值，默认填充0 |
返回值 (Returns)：填充后长度为inLen的列表
异常 (Raises)：无
sendStartMsg(copterID=-1)¶
功能说明：向网络发送启动信号，供调用了waitForStartMsg()的无人机接收并启动运行。当copterID=-1时，所有无人机都会启动运行；当copterID>0时，仅指定ID的无人机会启动运行
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | Any | 否 | -1 | 需要启动的无人机ID，默认-1表示启动所有无人机 |
返回值 (Returns)：无 异常 (Raises)：无
waitForStartMsg()¶
功能说明：程序会阻塞，直到接收到来自sendStartMsg()的启动信号后才继续执行
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
initPointMassModel(intAlt=0, intState=[0, 0, 0])¶
功能说明：初始化并启动无人机质点模型，用于无人机控制。intAlt为UE4地图中飞行器的初始高度（单位：米），可从CopterSim或UE4中获取；intState包含飞行器初始位置的X坐标(米)、Y坐标(米)和偏航角(度)，该初始状态与CopterSim界面上的值一致
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| intAlt | Any | 否 | 0 | 初始高度，单位米，默认值为0 |
| intState | Any | 否 | [0, 0, 0] | 初始状态[X位置, Y位置, 偏航角]，默认值为[0, 0, 0] |
返回值 (Returns)：无 异常 (Raises)：无
EndPointMassModel()¶
功能说明：结束质点模型运行 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
yawSat(yaw)¶
功能说明：将输入偏航角饱和到[-π, π]区间内 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| yaw | Any | 是 | 无 | 输入偏航角，单位弧度 |
返回值 (Returns)：饱和后[-π, π]区间内的偏航角 异常 (Raises)：无
PointMassModelLoop()¶
功能说明：质点模型的死循环运行函数，用于持续更新质点模型状态 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
sendUE4PosNew(copterID=1, vehicleType=3, PosE=[0, 0, 0], AngEuler=[0, 0, 0], VelE=[0, 0, 0], PWMs=[0] * 8, runnedTime=-1, windowID=-1)¶
功能说明：发送位置和姿态信息到RflySim3D，用于创建新的3D模型或者更新已有模型的状态。数据将按照RflySim3D约定结构体格式封装发送 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | Any | 否 | 1 | 无人机ID，默认值为1 |
| vehicleType | Any | 否 | 3 | 载具类型，默认值为3 |
| PosE | Any | 否 | [0, 0, 0] | 地球系NED下的载具位置，单位米，默认值为[0, 0, 0] |
| AngEuler | Any | 否 | [0, 0, 0] | 载具滚转、俯仰、偏航欧拉角，单位弧度，默认值为[0, 0, 0] |
| VelE | Any | 否 | [0, 0, 0] | 地球系下载具速度，默认值为[0, 0, 0] |
| PWMs | Any | 否 | [0] * 8 | 8个电机的PWM/转速信息，默认全为0 |
| runnedTime | Any | 否 | -1 | 当前时间戳，单位秒，默认值为-1表示自动使用当前时间 |
| windowID | Any | 否 | -1 | 目标RflySim3D窗口ID，默认-1表示发送到所有窗口 |
返回值 (Returns)：无 异常 (Raises)：无
InitTrueDataLoop()¶
功能说明：初始化来自CopterSim的UDP真实数据监听循环，使用30100系列端口接收数据 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
EndTrueDataLoop()¶
功能说明：结束真实数据接收模式，停止真实数据监听循环 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
SendOffAll(type_mask=PosTypeMask(), coordinate_frame=1, pos=[0, 0, 0], vel=[0, 0, 0], acc=[0, 0, 0], yaw=0, yawrate=0)¶
功能说明：发送位置控制指令给PX4飞控，通过MAVLink协议 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_mask | Any | 否 | PosTypeMask() | 位置控制类型掩码，用于忽略/使能对应控制量 |
| coordinate_frame | Any | 否 | 1 | 坐标帧编号，默认值为1表示全局系 |
| pos | Any | 否 | [0, 0, 0] | 期望位置，默认值为[0, 0, 0] |
| vel | Any | 否 | [0, 0, 0] | 期望速度，默认值为[0, 0, 0] |
| acc | Any | 否 | [0, 0, 0] | 期望加速度，默认值为[0, 0, 0] |
| yaw | Any | 否 | 0 | 期望偏航角，默认值为0 |
| yawrate | Any | 否 | 0 | 期望偏航角速度，默认值为0 |
返回值 (Returns)：无 异常 (Raises)：无
SendAttAll(type_mask=AttTypeMask(), q=[1, 0, 0, 0], body_rate=[0, 0, 0], thrust=0)¶
功能说明：发送姿态控制指令给PX4飞控，通过MAVLink协议 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_mask | Any | 否 | AttTypeMask() | 姿态控制类型掩码，用于忽略/使能对应控制量 |
| q | Any | 否 | [1, 0, 0, 0] | 期望姿态四元数，默认单位四元数 |
| body_rate | Any | 否 | [0, 0, 0] | 期望机体角速度，默认值为[0, 0, 0] |
| thrust | Any | 否 | 0 | 期望推力，默认值为0 |
返回值 (Returns)：无 异常 (Raises)：无
InitMavLoop(UDPMode=2)¶
功能说明：初始化来自CopterSim的MAVLink监听循环，支持多种工作模式：0和1分别对应UDP_Full和UDP_Simple模式，2和3分别对应MAVLink_Full和MAVLink_Simple模式，4为MAVLink_NoSend模式，5为MAVLink_NoGPS模式，6为MAVLink_NoVision模式，默认模式为2即MAVLink_Full模式 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| UDPMode | Any | 否 | 2 | 工作模式编号，默认值为2即MAVLink_Full模式 |
返回值 (Returns)：无 异常 (Raises)：无
endMavLoop()¶
功能说明：功能与stopRun()相同，停止从20100端口或串口的消息监听
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
SendVisionPosition(x, y, z, yaw)¶
功能说明：发送动捕或视觉测量得到的无人机位置和偏航角给PX4飞控，用于视觉里程计/动捕定位 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | Any | 是 | 无 | 动捕/视觉测量的X方向位置 |
| y | Any | 是 | 无 | 动捕/视觉测量的Y方向位置 |
| z | Any | 是 | 无 | 动捕/视觉测量的Z方向位置 |
| yaw | Any | 是 | 无 | 动捕/视觉测量的偏航角 |
返回值 (Returns)：无 异常 (Raises)：无
SendHILGps(lat=40.1540302, lon=116.2593683, alt=50, vel=0, vn=0, ve=0, vd=0, cog=0, time_usec=-1, eph=0.3, epv=0.4, fix_type=3, satellites_visible=15)¶
功能说明：向PX4发送硬件在环仿真（HIL）模式下的GPS信息 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| lat | None | 否 | 40.1540302 | GPS纬度，单位为度 |
| lon | None | 否 | 116.2593683 | GPS经度，单位为度 |
| alt | None | 否 | 50 | GPS高度，单位为米 |
| vel | None | 否 | 0 | GPS对地速度，单位为m/s |
| vn | None | 否 | 0 | 北向速度，单位为m/s |
| ve | None | 否 | 0 | 东向速度，单位为m/s |
| vd | None | 否 | 0 | 地向向下速度，单位为m/s |
| cog | None | 否 | 0 | 航迹向，单位为度 |
| time_usec | None | 否 | -1 | 时间戳（微秒），为-1时自动使用当前同步时间 |
| eph | None | 否 | 0.3 | 水平精度因子 |
| epv | None | 否 | 0.4 | 垂直精度因子 |
| fix_type | None | 否 | 3 | GPS定位类型，3表示3D定位 |
| satellites_visible | None | 否 | 15 | 可见卫星数量 |
返回值 (Returns)：无 异常 (Raises)：无
SendRedisData(key, buf)¶
功能说明：通过Redis发送指定数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| key | None | 是 | 无 | Redis数据的键名 |
| buf | None | 是 | 无 | 要发送的数据缓存 |
返回值 (Returns)：无 异常 (Raises)：无
SendBuf(buf)¶
功能说明：发送数据缓存到PX4 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| buf | None | 是 | 无 | 要发送的字节数据缓存 |
返回值 (Returns)：无 异常 (Raises)：无
SendBufTrue(buf, port=None)¶
功能说明：通过指定端口发送完整数据缓存 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| buf | None | 是 | 无 | 要发送的字节数据缓存 |
| port | None | 否 | None | 目标端口号，为None时使用默认端口 |
返回值 (Returns)：无 异常 (Raises)：无
sat(inPwm=0, thres=1)¶
功能说明：对输入值进行限幅饱和处理，若输入值超过阈值范围则将其限制在阈值范围内 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| inPwm | None | 否 | 0 | 需要进行饱和处理的输入值 |
| thres | None | 否 | 1 | 饱和阈值，允许输入值的最大绝对值 |
返回值 (Returns)：经过饱和处理后的输入值 异常 (Raises)：无
SendMavCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)¶
功能说明：向PX4发送COMMAND_LONG类型MAVLink命令，MAVLink命令定义可参考官方文档：https://mavlink.io/en/messages/common.html#COMMAND_LONG 和 https://mavlink.io/en/messages/common.html#MAV_CMD 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| command | None | 是 | 无 | MAVLink命令ID，对应MAV_CMD枚举值 |
| param1 | None | 否 | 0 | 命令参数1 |
| param2 | None | 否 | 0 | 命令参数2 |
| param3 | None | 否 | 0 | 命令参数3 |
| param4 | None | 否 | 0 | 命令参数4 |
| param5 | None | 否 | 0 | 命令参数5 |
| param6 | None | 否 | 0 | 命令参数6 |
| param7 | None | 否 | 0 | 命令参数7 |
返回值 (Returns)：无 异常 (Raises)：无
SendMavCmdLongNEW(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0, target_system=None, target_component=1, confirmation=0, force_send=False)¶
功能说明：向PX4发送COMMAND_LONG类型MAVLink命令，PX4会将COMMAND_LONG转换为uORB的vehicle_command并写入ULog。MAVLink命令定义可参考官方文档：https://mavlink.io/en/messages/common.html#COMMAND_LONG 和 https://mavlink.io/en/messages/common.html#MAV_CMD 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| command | None | 是 | 无 | MAVLink命令ID，对应MAV_CMD枚举值 |
| param1 | None | 否 | 0 | 命令参数1 |
| param2 | None | 否 | 0 | 命令参数2 |
| param3 | None | 否 | 0 | 命令参数3 |
| param4 | None | 否 | 0 | 命令参数4 |
| param5 | None | 否 | 0 | 命令参数5 |
| param6 | None | 否 | 0 | 命令参数6 |
| param7 | None | 否 | 0 | 命令参数7 |
| target_system | None | 否 | None | 目标系统ID，为None时使用默认目标系统 |
| target_component | None | 否 | 1 | 目标组件ID |
| confirmation | None | 否 | 0 | 确认序号，用于命令确认 |
| force_send | bool | 否 | False | 是否强制发送，即使未连接也尝试发送 |
返回值 (Returns)：无 异常 (Raises)：无
SendFaultEvent(fault_id, params=None, action=1, seq=0, vehicle_id=None, sim_id=0, command=MAV_CMD_USER_1)¶
功能说明：发送故障事件信息，用于仿真中故障注入的记录 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| fault_id | int | 是 | 无 | 故障ID，标识故障类型 |
| params | None | 否 | None | 故障参数信息 |
| action | int | 否 | 1 | 故障动作，1表示注入故障，0表示清除故障 |
| seq | int | 否 | 0 | 故障事件序号 |
| vehicle_id | int | 否 | None | 目标无人机ID，为None时使用当前无人机ID |
| sim_id | int | 否 | 0 | 仿真ID，区分多机仿真 |
| command | int | 否 | MAV_CMD_USER_1 | 使用的MAVLink命令ID，默认使用MAV_CMD_USER_1 |
返回值 (Returns)：无 异常 (Raises)：无
ClearFault(fault_id, seq=0, vehicle_id=None, sim_id=0, command=MAV_CMD_USER_1)¶
功能说明：清除/结束指定故障，会写入一条action=0的记录，方便后处理划定故障时间窗 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| fault_id | int | 是 | 无 | 需要清除的故障ID |
| seq | int | 否 | 0 | 故障事件序号 |
| vehicle_id | int | 否 | None | 目标无人机ID，为None时使用当前无人机ID |
| sim_id | int | 否 | 0 | 仿真ID，区分多机仿真 |
| command | int | 否 | MAV_CMD_USER_1 | 使用的MAVLink命令ID，默认使用MAV_CMD_USER_1 |
返回值 (Returns)：无 异常 (Raises)：无
SendQgcCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)¶
功能说明：发送COMMAND_LONG命令到QGroundControl地面站 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| command | None | 是 | 无 | MAVLink命令ID，对应MAV_CMD枚举值 |
| param1 | None | 否 | 0 | 命令参数1 |
| param2 | None | 否 | 0 | 命令参数2 |
| param3 | None | 否 | 0 | 命令参数3 |
| param4 | None | 否 | 0 | 命令参数4 |
| param5 | None | 否 | 0 | 命令参数5 |
| param6 | None | 否 | 0 | 命令参数6 |
| param7 | None | 否 | 0 | 命令参数7 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavOffboardCmd(type_mask, coordinate_frame, x, y, z, vx, vy, vz, afx, afy, afz, yaw, yaw_rate)¶
功能说明：向PX4发送离线控制命令，对应MAVLink的SET_POSITION_TARGET_LOCAL_NED消息，消息定义可参考：https://mavlink.io/en/messages/common.html#SET_POSITION_TARGET_LOCAL_NED 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_mask | None | 是 | 无 | 离线控制类型掩码，用于标记哪些控制量生效 |
| coordinate_frame | None | 是 | 无 | 坐标系统，一般为LOCAL_NED |
| x | None | 是 | 无 | X方向位置/速度/加速度指令，取决于type_mask |
| y | None | 是 | 无 | Y方向位置/速度/加速度指令，取决于type_mask |
| z | None | 是 | 无 | Z方向位置/速度/加速度指令，取决于type_mask |
| vx | None | 是 | 无 | X方向速度指令，取决于type_mask |
| vy | None | 是 | 无 | Y方向速度指令，取决于type_mask |
| vz | None | 是 | 无 | Z方向速度指令，取决于type_mask |
| afx | None | 是 | 无 | X方向加速度指令，取决于type_mask |
| afy | None | 是 | 无 | Y方向加速度指令，取决于type_mask |
| afz | None | 是 | 无 | Z方向加速度指令，取决于type_mask |
| yaw | None | 是 | 无 | 偏航角指令 |
| yaw_rate | None | 是 | 无 | 偏航角速度指令 |
返回值 (Returns)：无 异常 (Raises)：无
TypeMask(EnList)¶
功能说明：根据需要启用的控制量生成离线控制消息的type_mask位图，位图定义可参考：https://mavlink.io/en/messages/common.html#POSITION_TARGET_TYPEMASK 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| EnList | None | 是 | 无 | 需要启用的控制量列表，列表中包含需要生效的控制量名称 |
返回值 (Returns)：计算得到的type_mask位图 异常 (Raises)：无
sendMavOffboardAPI(type_mask=0, coordinate_frame=0, pos=[0, 0, 0], vel=[0, 0, 0], acc=[0, 0, 0], yaw=0, yawrate=0)¶
功能说明：封装后的离线控制API，向PX4发送离线控制命令，对应MAVLink的SET_POSITION_TARGET_LOCAL_NED消息，消息定义可参考：https://mavlink.io/en/messages/common.html#SET_POSITION_TARGET_LOCAL_NED 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_mask | None | 否 | 0 | 离线控制类型掩码，用于标记哪些控制量生效 |
| coordinate_frame | None | 否 | 0 | 坐标系统，默认为LOCAL_NED |
| pos | None | 否 | [0, 0, 0] | 位置指令，格式为[x, y, z] |
| vel | None | 否 | [0, 0, 0] | 速度指令，格式为[vx, vy, vz] |
| acc | None | 否 | [0, 0, 0] | 加速度指令，格式为[afx, afy, afz] |
| yaw | None | 否 | 0 | 偏航角指令 |
| yawrate | None | 否 | 0 | 偏航角速度指令 |
返回值 (Returns)：无 异常 (Raises)：无
sendUDPSimpData(ctrlMode, ctrls)¶
功能说明：通过UDP发送简化控制数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ctrlMode | None | 是 | 无 | 控制模式 |
| ctrls | None | 是 | 无 | 控制量数组 |
返回值 (Returns)：无 异常 (Raises)：无
sendPX4UorbRflyCtrl(data=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], modes=1, flags=1)¶
功能说明：发送Rfly定制的PX4 uORB控制消息 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| data | None | 否 | [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] | 16维控制数据数组 |
| modes | None | 否 | 1 | 控制模式标识 |
| flags | None | 否 | 1 | 控制标志位 |
返回值 (Returns)：无 异常 (Raises)：无
SendVelNED(vx, vy, vz, yawrate=math.nan)¶
功能说明：向PX4发送地理北东下（NED）坐标系下的目标无人机速度（单位：m/s）与偏航角速度（单位：rad/s），当无人机向上飞行时，vz < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vx | 浮点型 | 是 | math.nan | NED坐标系下北向速度，NaN表示不控制该轴 |
| vy | 浮点型 | 是 | math.nan | NED坐标系下东向速度，NaN表示不控制该轴 |
| vz | 浮点型 | 是 | math.nan | NED坐标系下向下速度，NaN表示不控制该轴 |
| yawrate | 浮点型 | 否 | math.nan | 目标偏航角速度，NaN表示不控制偏航角速度 |
返回值 (Returns)：无 异常 (Raises)：无
SendVelNEDNoYaw(vx, vy, vz)¶
功能说明：向PX4发送地理北东下（NED）坐标系下的目标无人机速度（单位：m/s），不控制偏航，当无人机向上飞行时，vz < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vx | 浮点型 | 是 | 无 | NED坐标系下北向速度，NaN表示不控制该轴 |
| vy | 浮点型 | 是 | 无 | NED坐标系下东向速度，NaN表示不控制该轴 |
| vz | 浮点型 | 是 | 无 | NED坐标系下向下速度，NaN表示不控制该轴 |
返回值 (Returns)：无 异常 (Raises)：无
SendVelFRD(vx, vy, vz, yawrate=math.nan)¶
功能说明：向PX4发送机体前右下（FRD）坐标系下的目标无人机速度（单位：m/s），并控制偏航角速度（单位：rad/s），当无人机向上飞行时，vz < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vx | 浮点型 | 是 | math.nan | FRD坐标系下前向速度，NaN表示不控制该轴 |
| vy | 浮点型 | 是 | math.nan | FRD坐标系下右向速度，NaN表示不控制该轴 |
| vz | 浮点型 | 是 | math.nan | FRD坐标系下向下速度，NaN表示不控制该轴 |
| yawrate | 浮点型 | 否 | math.nan | 目标偏航角速度，NaN表示不控制偏航角速度 |
返回值 (Returns)：无 异常 (Raises)：无
SendAttPX4(att=[0, 0, 0, 0], thrust=0.5, CtrlFlag=0, AltFlg=0)¶
功能说明：向PX4发送机体前右下（FRD）坐标系下的目标无人机姿态。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| att | 列表/数组 | 否 | [0, 0, 0, 0] | 目标姿态四元数，格式为[w, x, y, z] |
| thrust | 浮点型 | 否 | 0.5 | 推力值，范围通常为0~1 |
| CtrlFlag | 整型 | 否 | 0 | 控制标志位，0表示默认控制模式 |
| AltFlg | 整型 | 否 | 0 | 高度控制标志，0表示默认控制 |
返回值 (Returns)：无 异常 (Raises)：无
EulerToQuat(Euler)¶
功能说明：将欧拉角转换为四元数。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Euler | 列表/数组 | 是 | 无 | 输入欧拉角，格式为[roll, pitch, yaw]（单位：rad） |
返回值 (Returns)：四元数数组，格式为[w, x, y, z] 异常 (Raises)：无
SendAccPX4(afx=math.nan, afy=math.nan, afz=math.nan, yawValue=math.nan, yawType=0, frameType=0)¶
功能说明：向PX4发送目标加速度（单位：m/s²）。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| afx | 浮点型 | 否 | math.nan | x轴目标加速度，NaN表示不控制该轴 |
| afy | 浮点型 | 否 | math.nan | y轴目标加速度，NaN表示不控制该轴 |
| afz | 浮点型 | 否 | math.nan | z轴目标加速度，NaN表示不控制该轴 |
| yawValue | 浮点型 | 否 | math.nan | 目标偏航值，由yawType确定是偏航角还是偏航角速度 |
| yawType | 整型 | 否 | 0 | 偏航控制类型，0表示yawValue为偏航角，1表示yawValue为偏航角速度 |
| frameType | 整型 | 否 | 0 | 坐标系类型，0表示NED地理坐标系，1表示FRD机体坐标系 |
返回值 (Returns)：无 异常 (Raises)：无
SendVelNoYaw(vx=math.nan, vy=math.nan, vz=math.nan)¶
功能说明：向PX4发送机体前右下（FRD）坐标系下的目标无人机速度（单位：m/s），不控制偏航角速度，当无人机向上飞行时，vz < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vx | 浮点型 | 否 | math.nan | FRD坐标系下前向速度，NaN表示不控制该轴 |
| vy | 浮点型 | 否 | math.nan | FRD坐标系下右向速度，NaN表示不控制该轴 |
| vz | 浮点型 | 否 | math.nan | FRD坐标系下向下速度，NaN表示不控制该轴 |
返回值 (Returns)：无 异常 (Raises)：无
SendPosNED(x=math.nan, y=math.nan, z=math.nan, yaw=math.nan)¶
功能说明：向PX4发送地理北东下（NED）坐标系下的目标无人机位置（单位：m），并控制偏航角（单位：rad），当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | 浮点型 | 否 | math.nan | NED坐标系下北向位置，NaN表示不控制该轴 |
| y | 浮点型 | 否 | math.nan | NED坐标系下东向位置，NaN表示不控制该轴 |
| z | 浮点型 | 否 | math.nan | NED坐标系下向下位置，NaN表示不控制该轴 |
| yaw | 浮点型 | 否 | math.nan | 目标偏航角，NaN表示不控制偏航 |
返回值 (Returns)：无 异常 (Raises)：无
SendVelYawAlt(vel=10, yaw=6.28, alt=-100)¶
功能说明：向PX4发送速度、偏航角与高度设定值，当无人机在地面上方飞行时，高度对应NED坐标系下z值满足z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| vel | 浮点型 | 否 | 10 | 目标前向速度大小 |
| yaw | 浮点型 | 否 | 6.28 | 目标偏航角（单位：rad） |
| alt | 浮点型 | 否 | -100 | 目标高度（NED坐标系z值，单位：m） |
返回值 (Returns)：无 异常 (Raises)：无
SendPosGlobal(lat=0, lon=0, alt=0, yawValue=0, yawType=0)¶
功能说明：向PX4发送全球经纬高坐标系下的目标无人机位置，并控制偏航，当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| lat | 浮点型 | 否 | 0 | 目标纬度（单位：度） |
| lon | 浮点型 | 否 | 0 | 目标经度（单位：度） |
| alt | 浮点型 | 否 | 0 | 目标高度（单位：m） |
| yawValue | 浮点型 | 否 | 0 | 目标偏航值，单位rad，由yawType确定是偏航角还是偏航角速度 |
| yawType | 整型 | 否 | 0 | 偏航控制类型，0表示yawValue为偏航角，1表示yawValue为偏航角速度 |
返回值 (Returns)：无 异常 (Raises)：无
SendPosNEDNoYaw(x=math.nan, y=math.nan, z=math.nan)¶
功能说明：向PX4发送地理北东下（NED）坐标系下的目标无人机位置（单位：m），不控制偏航，当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | 浮点型 | 否 | math.nan | NED坐标系下北向位置，NaN表示不控制该轴 |
| y | 浮点型 | 否 | math.nan | NED坐标系下东向位置，NaN表示不控制该轴 |
| z | 浮点型 | 否 | math.nan | NED坐标系下向下位置，NaN表示不控制该轴 |
返回值 (Returns)：无 异常 (Raises)：无
SendPosFRD(x=math.nan, y=math.nan, z=math.nan, yaw=math.nan)¶
功能说明：向PX4发送机体前右下（FRD）坐标系下的目标无人机位置（单位：m），并控制偏航角（单位：rad），当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | 浮点型 | 否 | math.nan | FRD坐标系下前向位置，NaN表示不控制该轴 |
| y | 浮点型 | 否 | math.nan | FRD坐标系下右向位置，NaN表示不控制该轴 |
| z | 浮点型 | 否 | math.nan | FRD坐标系下向下位置，NaN表示不控制该轴 |
| yaw | 浮点型 | 否 | math.nan | 目标偏航角，NaN表示不控制偏航 |
返回值 (Returns)：无 异常 (Raises)：无
SendPosFRDNoYaw(x=math.nan, y=math.nan, z=math.nan)¶
功能说明：向PX4发送机体前右下（FRD）坐标系下的目标无人机位置（单位：m），不控制偏航，当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | 浮点型 | 否 | math.nan | FRD坐标系下前向位置，NaN表示不控制该轴 |
| y | 浮点型 | 否 | math.nan | FRD坐标系下右向位置，NaN表示不控制该轴 |
| z | 浮点型 | 否 | math.nan | FRD坐标系下向下位置，NaN表示不控制该轴 |
返回值 (Returns)：无 异常 (Raises)：无
SendPosNEDExt(x=math.nan, y=math.nan, z=math.nan, mode=3, isNED=True)¶
功能说明：向PX4发送扩展格式的目标无人机位置（单位：m），当无人机在地面上方飞行时，z < 0。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | 浮点型 | 否 | math.nan | x轴目标位置，NaN表示不控制该轴 |
| y | 浮点型 | 否 | math.nan | y轴目标位置，NaN表示不控制该轴 |
| z | 浮点型 | 否 | math.nan | z轴目标位置，NaN表示不控制该轴 |
| mode | 整型 | 否 | 3 | 控制模式，对应PX4位置控制掩码 |
| isNED | 布尔型 | 否 | True | True表示输入为NED地理坐标系，False表示为FRD机体坐标系 |
返回值 (Returns)：无 异常 (Raises)：无
enFixedWRWTO()¶
功能说明：发送指令使能固定翼飞机跑道起飞模式。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
SendCruiseSpeed(Speed=0)¶
功能说明：发送指令修改飞行器的巡航速度，单位为 m/s 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Speed | None | 否 | 0 | 需要设置的目标巡航速度 |
返回值 (Returns)：无 异常 (Raises)：无
SendCopterSpeed(Speed=0)¶
功能说明：发送指令设置多旋翼飞行器的最大速度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Speed | None | 否 | 0 | 需要设置的多旋翼最大速度 |
返回值 (Returns)：无 异常 (Raises)：无
SendGroundSpeed(Speed=0)¶
功能说明：发送指令修改飞行器的地速，单位为 m/s 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Speed | None | 否 | 0 | 需要设置的目标地速 |
返回值 (Returns)：无 异常 (Raises)：无
SendCruiseRadius(rad=0)¶
功能说明：发送指令修改飞行器的巡航转弯半径，单位为 m 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| rad | None | 否 | 0 | 需要设置的目标巡航转弯半径 |
返回值 (Returns)：无 异常 (Raises)：无
sendTakeoffMode(alt=0)¶
功能说明：发送指令控制飞行器起飞 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| alt | None | 否 | 0 | 起飞目标高度 |
返回值 (Returns)：无 异常 (Raises)：无
initOffboard()¶
功能说明：发送指令让PX4飞控进入Offboard模式，并启动30Hz的Offboard消息发送 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
initOffboardAcc()¶
功能说明：发送指令让PX4飞控进入Offboard模式，并启动30Hz的Offboard消息发送（加速度控制类型） 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
initOffboardAtt()¶
功能说明：发送指令让PX4飞控进入Offboard模式，并启动30Hz的Offboard消息发送（姿态控制类型） 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
initOffboard2()¶
功能说明：发送指令让PX4飞控进入Offboard模式，并启动30Hz的Offboard消息发送（扩展版本） 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
sendMavTakeOff(xM=0, yM=0, zM=0, YawRad=0, PitchRad=0)¶
功能说明：发送指令控制飞行器起飞到指定的本地坐标系目标位置，单位为 m 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| xM | None | 否 | 0 | 目标位置X坐标 |
| yM | None | 否 | 0 | 目标位置Y坐标 |
| zM | None | 否 | 0 | 目标位置Z坐标 |
| YawRad | None | 否 | 0 | 目标偏航角，单位为弧度 |
| PitchRad | None | 否 | 0 | 目标俯仰角，单位为弧度 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavTakeOffLocal(xM=0, yM=0, zM=0, YawRad=0, PitchRad=0, AscendRate=2)¶
功能说明：发送指令控制飞行器起飞到指定的本地坐标系目标位置，单位为 m 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| xM | None | 否 | 0 | 目标位置X坐标 |
| yM | None | 否 | 0 | 目标位置Y坐标 |
| zM | None | 否 | 0 | 目标位置Z坐标 |
| YawRad | None | 否 | 0 | 目标偏航角，单位为弧度 |
| PitchRad | None | 否 | 0 | 目标俯仰角，单位为弧度 |
| AscendRate | None | 否 | 2 | 起飞爬升速度 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavTakeOffGPS(lat=None, lon=None, alt=None, yawDeg=0, pitchDeg=15)¶
功能说明：发送指令控制飞行器起飞到指定的全球坐标系目标位置，坐标单位为度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| lat | None | 否 | None | 目标纬度，单位为度 |
| lon | None | 否 | None | 目标经度，单位为度 |
| alt | None | 否 | None | 目标海拔高度，单位为米 |
| yawDeg | None | 否 | 0 | 目标偏航角，单位为度 |
| pitchDeg | None | 否 | 15 | 目标俯仰角，单位为度 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavLand(xM=None, yM=None, zM=None)¶
功能说明：发送指令控制飞行器降落至指定的本地坐标系目标位置，单位为 m 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| xM | None | 否 | None | 目标位置X坐标 |
| yM | None | 否 | None | 目标位置Y坐标 |
| zM | None | 否 | None | 目标位置Z坐标 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavLandGPS(lat=None, lon=None, alt=None)¶
功能说明：发送指令控制飞行器降落至指定的全球坐标系目标位置，坐标单位为度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| lat | None | 否 | None | 目标纬度，单位为度 |
| lon | None | 否 | None | 目标经度，单位为度 |
| alt | None | 否 | None | 目标海拔高度，单位为米 |
返回值 (Returns)：无 异常 (Raises)：无
endOffboard()¶
功能说明：发送指令让PX4飞控退出Offboard模式，并停止Offboard消息发送循环 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
sendMavSetParam(param_id, param_value, param_type)¶
功能说明：向PX4发送指令修改指定参数，采用MAVLink的PARAM_SET消息，参数列表可在QGroundControl中查看。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| param_id | Any | 是 | 无 | 目标参数名称标识 |
| param_value | Any | 是 | 无 | 目标参数的目标值 |
| param_type | Any | 是 | 无 | 参数的MAVLink类型 |
返回值 (Returns)：无 异常 (Raises)：无
SendHILCtrlMsg(ctrls=[0] * 16, idx=0, flags=1)¶
功能说明：向PX4发送HIL_ACTUATOR_CONTROLS指令，该消息会被转换为uORB消息rfly_ctrl。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ctrls | Any | 否 | [0] * 16 | 16维控制量数组 |
| idx | Any | 否 | 0 | 控制组索引 |
| flags | Any | 否 | 1 | 消息标志位 |
返回值 (Returns)：无 异常 (Raises)：无
SendHILCtrlMsg1()¶
功能说明：向PX4发送DEBUG_VECT调试向量消息，该消息会被转换为uORB消息rfly_ctrl。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
SendMavArm(isArm=1)¶
功能说明：向PX4发送指令，控制无人机上锁/解锁。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| isArm | Any | 否 | 1 | 1表示解锁（arm），0表示上锁（disarm） |
返回值 (Returns)：无 异常 (Raises)：无
initRCSendLoop(Hz=30)¶
功能说明：初始化遥控器PWM发送循环，设置发送频率。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Hz | Any | 否 | 30 | 遥控器信号发送频率，单位Hz |
返回值 (Returns)：无 异常 (Raises)：无
endRCSendLoop()¶
功能说明：终止遥控器PWM发送循环。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
RcSendLoop()¶
功能说明：遥控器PWM发送循环的执行函数，持续发送设置好的PWM值。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
SendRCPwms(Pwms)¶
功能说明：设置待发送的遥控器PWM值。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Pwms | Any | 是 | 无 | 各通道PWM值数组 |
返回值 (Returns)：无 异常 (Raises)：无
SendRcOverride(ch1=1500, ch2=1500, ch3=1100, ch4=1500, ch5=1100, ch6=1100, ch7=1500, ch8=1500)¶
功能说明：向PX4发送MAVLink指令，覆盖原有的遥控器通道信号，采用RC_CHANNELS_OVERRIDE消息。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ch1 | Any | 否 | 1500 | 1通道PWM值，范围1000~2000 |
| ch2 | Any | 否 | 1500 | 2通道PWM值，范围1000~2000 |
| ch3 | Any | 否 | 1100 | 3通道PWM值，范围1000~2000 |
| ch4 | Any | 否 | 1500 | 4通道PWM值，范围1000~2000 |
| ch5 | Any | 否 | 1100 | 5通道PWM值，范围1000~2000 |
| ch6 | Any | 否 | 1100 | 6通道PWM值，范围1000~2000 |
| ch7 | Any | 否 | 1500 | 7通道PWM值，范围1000~2000 |
| ch8 | Any | 否 | 1500 | 8通道PWM值，范围1000~2000 |
返回值 (Returns)：无 异常 (Raises)：无
sendMavManualCtrl(x=0, y=0, z=0, r=0)¶
功能说明：向PX4发送MAVLink指令，覆盖手动控制信号，采用MANUAL_CONTROL消息。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| x | Any | 否 | 0 | X轴控制量，范围-1000~1000 |
| y | Any | 否 | 0 | Y轴控制量，范围-1000~1000 |
| z | Any | 否 | 0 | Z轴控制量，范围-1000~1000 |
| r | Any | 否 | 0 | 偏航轴控制量，范围-1000~1000 |
返回值 (Returns)：无 异常 (Raises)：无
SendSetMode(mainmode, cusmode=0)¶
功能说明：向PX4发送MAVLink指令修改飞行模式，采用MAV_CMD_DO_SET_MODE消息。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| mainmode | Any | 是 | 无 | 主模式编号 |
| cusmode | Any | 否 | 0 | 自定义子模式编号，默认为0 |
返回值 (Returns)：无 异常 (Raises)：无
stopRun()¶
功能说明：停止InitMavLoop()启动的MAVLink监听循环，功能与endMavLoop()一致。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
getTrueDataMsg()¶
功能说明：启动循环监听来自端口30100的真实仿真数据。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
getPX4DataMsg()¶
功能说明：启动循环监听来自端口40100的PX4数据。 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无
setMsgDict(stName)¶
功能说明：设置消息字典相关标识。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| stName | Any | 是 | 无 | 消息字典名称标识 |
返回值 (Returns)：无 异常 (Raises)：无
netForwardData()¶
功能说明：网络转发数据 参数列表 (Args)： 无参数 返回值 (Returns)：无 异常 (Raises)：无
GetUDPRedisBuf(sock)¶
功能说明：获取UDP转发缓存数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| sock | None | 是 | 无 | UDP套接字对象 |
返回值 (Returns)：无 异常 (Raises)：无
getMavMsg()¶
功能说明：启动循环，监听来自20100系列端口或串口的mavlink数据 参数列表 (Args)： 无参数 返回值 (Returns)：无 异常 (Raises)：无
OffboardSendMode()¶
功能说明：设置offboard模式发送 参数列表 (Args)： 无参数 返回值 (Returns)：无 异常 (Raises)：无
sendRebootPix(copterID, delay=-1)¶
功能说明：发送重启仿真的消息到指定无人机ID的PX4飞控 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | None | 是 | 无 | 目标无人机的ID |
| delay | None | 否 | -1 | 重启延迟时间，单位为秒 |
返回值 (Returns)：无 异常 (Raises)：无
sendCustomData(CopterID, data=[0] * 16, checksum=123456, port=50000, IP=127.0.0.1)¶
功能说明：发送16维自定义消息到指定IP和端口 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | None | 是 | 无 | 目标无人机ID |
| data | None | 否 | [0] * 16 | 待发送的16个元素数据数组 |
| checksum | None | 否 | 123456 | 数据校验和 |
| port | None | 否 | 50000 | 目标端口号 |
| IP | None | 否 | 127.0.0.1 | 目标IP地址 |
返回值 (Returns)：无 异常 (Raises)：无
setGPSOriLLA(LonLatAlt)¶
功能说明：设置GPS初始经纬度高度 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| LonLatAlt | None | 是 | 无 | 初始经纬度高度数组，格式为[经度, 纬度, 高度] |
返回值 (Returns)：无 异常 (Raises)：无
sendSILIntFloat(inSILInts=[0] * 8, inSILFLoats=[0] * 20, copterID=-1)¶
功能说明：发送 SIL 整数和浮点数数据到PX4飞控 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| inSILInts | None | 否 | [0] * 8 | 待发送的8个整数数组 |
| inSILFLoats | None | 否 | [0] * 20 | 待发送的20个浮点数数组 |
| copterID | None | 否 | -1 | 目标无人机ID，-1表示发送给所有无人机 |
返回值 (Returns)：无 异常 (Raises)：无
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
本示例实现了多无人机集群的点质量模型协同仿真+真实位频数据异步回传的组合场景，通过fifo队列实现不同线程间的控制指令与状态数据交互，同时结合PX4自定义飞行模式完成多机协作任务。
import RflySimSDK.ctrl as rfc
import threading
import time
# 初始化5架无人机的控制器对象队列
px4_ctrl_list = [rfc.PX4MavCtrler() for _ in range(5)]
# 初始化异步通信fifo队列
data_fifo = rfc.fifo()
# 启动所有无人机的真值数据回传线程
for ctrl in px4_ctrl_list:
ctrl.InitTrueDataLoop()
# 批量初始化点质量仿真模型
for ctrl in px4_ctrl_list:
ctrl.initPointMassModel()
# 定义异步位姿数据读取线程函数
def async_read_true_data():
while True:
# 从fifo读取最新多机位姿数据
all_pos_data = data_fifo.read()
if all_pos_data:
# 批量发送位姿数据到仿真可视化端
for idx, pos_data in enumerate(all_pos_data):
px4_ctrl_list[idx].sendUE4PosNew(pos_data, rfc.PosTypeMask.mask(), rfc.AttTypeMask.mask())
time.sleep(0.01)
# 启动异步线程处理数据回传
read_thread = threading.Thread(target=async_read_true_data, daemon=True)
read_thread.start()
# 主循环运行点质量模型控制，实现集群协同航路跟踪
try:
while True:
for ctrl in px4_ctrl_list:
ctrl.PointMassModelLoop(rfc.PX4_CUSTOM_MAIN_MODE, rfc.PX4_CUSTOM_SUB_MODE_AUTO)
# 添加偏航角限制约束
ctrl.yawSat(max_yaw_rate=30.0)
time.sleep(0.01)
finally:
# 结束后批量停止所有线程与模型
for ctrl in px4_ctrl_list:
ctrl.EndPointMassModel()
ctrl.EndTrueDataLoop()
注意事项与避坑指南¶
- 点质量模型启停配对使用：
initPointMassModel和EndPointMassModel必须配对调用，若只初始化不终止，会导致后台仿真线程持续占用资源，下次启动仿真时容易出现模型状态异常的问题。同理InitTrueDataLoop与EndTrueDataLoop也需要配对管理生命周期。 - fifo队列读写权限匹配：多线程协作场景下，fifo队列的读写需要对应不同线程操作，不要在同一个线程内同时进行连续的读写操作，否则容易出现数据阻塞或者空读错误，影响控制链路的实时性。
- 自定义飞行模式参数匹配：调用
PointMassModelLoop等需要传入自定义飞行模式参数时，必须使用本模块提供的PX4_CUSTOM_MAIN_MODE和PX4_CUSTOM_SUB_MODE_AUTO类型参数，传入自定义整数参数会导致PX4飞控无法识别控制指令，触发模式切换失败。 - Redis键获取需对应飞机ID：调用
RedisKey.GetRedisKey获取状态存储键时，需要传入与无人机编号对应的正确ID，错误的ID会导致读取到其他无人机的状态数据，引发集群控制中串扰问题。
更新日志¶
2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云2025-09-19: 兼容WSL22025-09-19: 解决组播失效情况下恢复机制2025-09-11: fix: 增加Linux端口复用的支持2025-08-20: fix:获取故障注入时间戳2025-08-07: 修复direct模式mavlink连真机port变量无效的bug2024-12-18: fix: 增加一个自定义消息发送接口2024-11-22: fix2024-11-22: fix：更新API页面2024-10-23: fix: 更新sendHIl接口2024-09-09: feat: 新增外部发送GPS消息的接口2024-08-30: fix: 删除综合模型控制相关接口，挪到别处2024-08-28: fix: 默认不控制通道2024-08-14: fix:更新HTML版API2024-07-29: fix: 保持旧版的兼容性