OffboardPvaCtrlAPI 模块文档¶

所属工具箱：RflySim APIs

OffboardPvaCtrlAPI 模块外观

简介¶

一句话描述：该模块是PX4 Offboard模式下的位置速度加速度控制接口模块，支持多种控制方式切换，可将Simulink生成的控制指令发送给PX4飞控实现载具运动控制。

该模块属于RflySim APIs接口库，是RflySim工具链中用于自定义Offboard控制开发的核心模块，主要面向需要自主开发位置、速度或加速度层级控制器的仿真开发场景。模块支持自动解锁、控制模式自动切换，可通过使能信号灵活开启或关闭Simulink自定义控制：当开启控制时，模块会将自定义控制器生成的位置、速度、加速度、偏航、偏航速率指令通过MAVLink协议发送给PX4飞控，同时屏蔽PX4原有控制输出，使用Simulink控制器实现载具控制；当关闭控制时，模块会自动解除屏蔽并将载具切换到PX4的Loiter悬停模式，保证飞行安全。

该模块最终输出的控制信号会传输给CopterSim DLL接口，通过CopterSim与PX4飞控、RflySim3D可视化环境完成交互，支持用户在Simulink中快速验证自定义Offboard控制算法，无需修改PX4飞控底层源码即可灵活切换不同的控制方式，适配轨迹跟踪、运动控制等多种开发场景。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`isEnCtrl`	`boolean`	`1×1`	当输入为`true`时，模块发送控制数据并使载具进入Offboard模式；当输入为`false`时，模块停止发送控制数据，PX4将自动切换到Loiter模式；当输入从`false`跳变到`true`时，会自动完成解锁并进入Offboard模式。
`PVAYR`	`single`/`double`	`1×11`	11维Offboard控制指令，维度顺序依次为NED坐标系下x位置、y位置、z位置、x速度、y速度、z速度、x加速度、y加速度、z加速度、偏航角、偏航角速度，不需要控制的通道可设置为`NaN`。
`EnList`	`boolean`	`1×11`	11维控制使能向量，每一维对应`PVAYR`中的一个控制通道，对应位置为`true`时PX4将响应该通道的控制量，为`false`时不响应该通道控制。

输出端口（Outputs）¶

端口名	数据类型	维度	说明
`CtrlS`	`double`	`1×16`	生成的Offboard控制指令输出，需要连接到CopterSim的DLL模型的`inPWM`输入接口。

参数配置（Parameters）¶

双击模块打开的 Mask 对话框中可配置以下参数：

参数名	类型	默认值	可选值/范围	说明
`Auto arm`	`boolean`	`false`	`true`/`false`	勾选后，当`isEnCtrl`端口输入为`true`时，模块将自动发送载具解锁指令。
`Auto block PX4`	`boolean`	`false`	`true`/`false`	勾选后，模块将发送信号屏蔽PX4的原生输出，当`isEnCtrl`输入为`true`时，将使用Simulink控制器输出控制载具。
`Auto Loiter`	`boolean`	`false`	`true`/`false`	勾选后，当`isEnCtrl`输入为`false`时，模块将解除PX4输出屏蔽，并自动切换到PX4原生Loiter模式，保证载具保持悬停在空中。
`Sample Time(s)`	`double`	`0.01`	`>0`	模块的采样时间，单位为秒。

参数设置说明¶

`Auto arm`¶

该功能用于自动化解锁流程，开启后无需额外在Simulink模型中添加解锁指令模块，当使能Offboard控制时会自动完成解锁操作，简化模型设计。

`Auto block PX4`¶

当使用Simulink开发的自定义控制器进行Offboard控制时，需要开启该选项屏蔽PX4原生控制器输出，使能自定义控制器的输出。若不开启该选项，PX4原生控制器会输出控制量叠加，导致控制异常。

`Auto Loiter`¶

当关闭Offboard控制（isEnCtrl为false）时，开启该选项可以自动让载具切换到PX4原生Loiter悬停模式，避免因失去Offboard控制指令导致载具降落或失控，提升仿真安全性。

`Sample Time(s)`¶

该参数需要和Simulink模型的固定步长保持一致，通常PX4仿真使用10ms（即0.01s）采样周期，若修改了模型步长需要同步修改该参数。

模块特性（Block Characteristics）¶

特性项	值
支持的数据类型	`double`、`single`、`boolean`
直接馈通（Direct Feedthrough）	是
采样时间	离散
代码生成支持	否

数据通信协议¶

本模块输出16维CtrlS信号，将输入控制指令转换为对应格式后发送至CopterSim DLL模型的inPWM接口，输入的PVAYR控制指令协议格式如下：输入为NED坐标系下11维控制向量，各维度含义依次为：

x：位置控制（单位m）
y：位置控制（单位m）
z：位置控制（单位m）
Vx：速度控制（单位m/s）
Vy：速度控制（单位m/s）
Vz：速度控制（单位m/s）
Ax：加速度控制（单位m/s²）
Ay：加速度控制（单位m/s²）
Az：加速度控制（单位m/s²）
Yaw：偏航角控制（单位rad，取值范围-pi ~ pi）
Yawrate：偏航角速度控制（单位rad/s）

若某通道不启用控制，需将对应位置设置为NaN，EnList输入对应维度将指定该通道是否启用。

使用示例¶

相关使用示例请参考以下路径：

[RflySim安装路径]/RflySimAPIs/5.RflySimFlyCtrl/0.ApiExps/17.OffboardCtrlsAPI/Readme.pdf

请在上述路径中查看 Readme.pdf 获取完整的示例说明与操作步骤。

注意事项与常见问题¶

初始化顺序：必须确保仿真启动后isEnCtrl输入为false完成PX4端初始化，再由false切换为true使能Offboard控制，否则PX4无法正确响应Offboard模式切换。若开启Auto arm功能，仅在isEnCtrl从false跳转为true时会自动发送解锁指令，仿真启动直接输入true无法触发自动解锁。
控制指令一致性：PVAYR输入向量中，若某一维度对应控制未使能（对应EnList位为false），必须将PVAYR对应位置设为NaN，不可随意填写固定数值，否则会导致PX4控制逻辑异常。同时开启多层级控制（如同时使能位置和对应轴速度控制）时，需保证控制指令满足运动学一致性，避免出现控制冲突导致载具姿态发散。
采样时间匹配：模块采样时间需和PX4 Offboard控制心跳周期要求匹配，不建议设置大于0.2s的采样时间，否则PX4会因超时自动退出Offboard模式切回Loiter模式。同时采样时间需和Simulink模型基础采样保持一致，避免出现数据更新不同步导致控制指令跳变。
模式切换安全设置：建议勾选Auto Loiter选项，当isEnCtrl置为false时，模块会自动切换到PX4原生Loiter模式保持悬停，避免载具失控。若关闭Auto Loiter选项，需自行设计Offboard失能后的安全处理逻辑。
坐标系约定：模块输入PVAYR的位置、速度、加速度均采用NED坐标系，若使用ENU坐标系的控制指令，必须完成坐标系转换后再输入模块，否则会出现控制方向反向的问题。偏航角输入范围为-pi~pi，超出范围需先做归一化处理，避免偏航控制异常。
使能位配置：EnList输入向量需要和控制需求对应，仅使能你需要用到的控制通道即可，不需要的控制通道必须将对应使能位设为false，避免PX4响应无效控制量导致飞行不稳定。例如纯位置控制时仅需使能xyz位置和偏航通道，其余通道对应使能位设为false。

更新日志¶

v4.1.0 (2024-08-07): 初始发布Offboard模式下PVA多模式可切换控制接口模块，支持位置、速度、加速度控制方式的组合切换，提供自动解锁、模式自动切换功能。

模块名	说明
`SetControlGroupAPI`	配置PX4飞控控制通道启用状态，用于Offboard模式控制配置
`OffboardAttiCtrlAPI`	Offboard模式下姿态角控制API模块
`OffboardRateCtrlAPI`	Offboard模式下角速度控制API模块
`VehicleCmdPublisher`	发布无人机通用控制指令的API模块