OffboardAdvCtrlAPI 模块文档¶

所属工具箱：RflySim APIs

OffboardAdvCtrlAPI 模块外观

简介¶

一句话描述：该模块是RflySim工具链用于PX4 Offboard模式的高级控制接口，支持自定义多维度控制指令，可自动完成模式切换、解锁与模式切换逻辑，实现Simulink端对无人机的自定义Offboard控制。

该模块属于RflySim APIs接口库，用于实现Simulink仿真环境与PX4飞控、CopterSim仿真引擎的Offboard控制交互，支持用户自定义选择位置、速度、加速度、偏航角、偏航角速度等不同维度的控制通道，未选择控制的通道可通过NaN设置忽略，满足开发者自定义无人机高级控制器的开发需求，适用于轨迹跟踪控制、视觉伺服控制、编队控制等各类Offboard控制算法的仿真验证场景。

该模块集成了自动解锁、PX4输出自动切换、空闲自动悬停等自动化逻辑：当使能控制输入为真时，可按照配置自动完成解锁、屏蔽PX4原有控制输出，将Simulink端生成的控制指令通过Offboard接口发送给PX4飞控，由CopterSim完成无人机动力学仿真并可同步将飞行状态发送至RflySim3D进行三维可视化展示；当使能控制输入为假时，可自动切换PX4到Loiter悬停模式，保障仿真过程中无人机的状态安全，无需开发者手动处理模式切换与逻辑交互。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	`N×1`，其中N为选中的控制通道数量	说明
`isEnCtrl`	`boolean`	`1×1`	控制使能信号，输入`true`时发送控制指令并启用Offboard控制，输入`false`时停止发送控制指令，PX4将切换至Loiter模式
`Ctrls[*]`	`double`	`N×1`，其中N为选中的控制通道数量	归一化Offboard控制指令，遵循NED坐标系协议，未选中的控制通道不占用输入位，如需不控制对应状态可将对应值设为`NaN`

输出端口（Outputs）¶

本模块无输出端口。

参数配置（Parameters）¶

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

参数名	类型	默认值	可选值/范围	说明
`CopterID`	`int`	`1`	`1~255`	目标无人机的ID编号
`Enable position x`	`bool`	`false`	`true/false`	是否使能x位置控制通道
`Enable position y`	`bool`	`false`	`true/false`	是否使能y位置控制通道
`Enable position z`	`bool`	`false`	`true/false`	是否使能z位置控制通道
`Enable velocity x`	`bool`	`false`	`true/false`	是否使能x速度控制通道
`Enable velocity y`	`bool`	`false`	`true/false`	是否使能y速度控制通道
`Enable velocity z`	`bool`	`false`	`true/false`	是否使能z速度控制通道
`Enable acceleration x`	`bool`	`false`	`true/false`	是否使能x加速度控制通道
`Enable acceleration y`	`bool`	`false`	`true/false`	是否使能y加速度控制通道
`Enable acceleration z`	`bool`	`false`	`true/false`	是否使能z加速度控制通道
`Enable yaw`	`bool`	`false`	`true/false`	是否使能偏航角控制通道
`Enable yaw rate`	`bool`	`false`	`true/false`	是否使能偏航角速度控制通道
`Auto arm`	`bool`	`false`	`true/false`	是否自动发送无人机解锁指令
`Auto block PX4`	`bool`	`false`	`true/false`	是否自动屏蔽PX4原生控制器输出，启用Simulink控制器输出
`Auto Loiter`	`bool`	`true`	`true/false`	控制关闭时是否自动切换PX4到Loiter模式悬停
`Sample Time(s)`	`double`	`0.01`	`>0`	模块采样时间

参数设置说明¶

控制通道选择参数¶

可以根据控制需求自定义选择需要激活的Offboard控制通道，选中的通道会按固定顺序（x位置→y位置→z位置→x速度→y速度→z速度→x加速度→y加速度→z加速度→偏航角→偏航角速度）排列在Ctrls[*]输入端口中，未选中的通道不占用输入位。控制指令使用NED坐标系，单位遵循协议，若不需要控制某个状态可将对应输入设置为NaN。

Auto arm¶

勾选该参数后，当isEnCtrl输入为true时，模块会自动向目标无人机发送解锁指令，无需用户额外处理解锁逻辑。

Auto block PX4¶

勾选该参数后，当isEnCtrl输入为true时，模块会自动屏蔽PX4原生控制器的输出，使用Simulink输出的Offboard控制指令控制无人机，实现外部控制器仿真验证。

Auto Loiter¶

勾选该参数后，当isEnCtrl输入为false时，模块会自动解除PX4输出屏蔽，并将无人机切换到Loiter模式，使无人机可以自动保持在空中悬停，提升仿真安全性。若取消勾选，关闭Offboard控制后无人机不会自动切换模式，需用户自行处理模式切换逻辑。

Sample Time(s)¶

指定模块发送Offboard控制指令的频率，单位为秒，一般设置为0.01对应100Hz的控制频率，与PX4原生Offboard控制频率匹配。

模块特性（Block Characteristics）¶

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

数据通信协议¶

本模块通过UDP协议与PX4仿真固件通信，遵循MAVLink Offboard控制协议，输入控制信号格式说明如下：所有控制输入基于NED坐标系，有效范围为：位置x/y/z单位为m，速度vx/vy/vz单位为m/s，加速度ax/ay/az单位为m/s²，偏航yaw单位为rad（范围：-π~π），偏航速度yawrate单位为rad/s；输入值设为NaN表示不对对应状态进行控制。

使用示例¶

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

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

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

注意事项与常见问题¶

初始化顺序：该模块需要配合RflySim仿真环境初始化才能正常工作，必须确保仿真开始前PX4飞控已经完成上电初始化，再使能isEnCtrl输入，否则Offboard模式切换会失败，载具无法响应控制指令。若启用了Auto arm功能，需要确保载具满足PX4解锁条件（如无危险故障告警、处于地面起飞条件）后再拉高isEnCtrl，否则解锁会失败。
输入指令一致性：自定义选择控制通道时，需要保持运动学关系的一致性，不建议同时控制同一状态的位置、速度、加速度指令；若不需要控制某一通道，必须将对应输入设置为NaN，否则该通道会被异常控制导致飞行不稳甚至撞机。所有位置指令遵循NED坐标系定义，注意z轴向下为正，和常规ENU坐标系定义方向相反，输入指令时需要提前完成坐标转换，避免位置指令方向错误。
采样时间匹配：Offboard模式要求控制指令发送频率稳定，建议设置模块采样时间不大于0.1s，采样时间过大可能导致PX4判定Offboard信号丢失，自动退出Offboard模式切换到Loiter。模块采样时间需要和Simulink模型的基础采样时间匹配，避免出现指令更新不及时的问题。
模式切换安全：若未勾选Auto Loiter功能，当isEnCtrl拉低禁用Offboard控制后，不会自动切换到安全的Loiter模式，需要用户自行处理切出后的飞控模式，否则可能出现载具失控的风险；若使用自定义切出逻辑，建议添加故障保护逻辑，确保Offboard信号失效后载具能够自动进入悬停或降落模式。
Auto block PX4使用注意：勾选Auto block PX4后，Offboard控制完全接管载具输出，需要确保输入的控制指令有效且满足动力学限制，过大的控制指令可能导致执行器饱和，造成载具失控。
单位与范围校验：偏航角输入范围为-pi~pi，输入超出范围会导致偏航控制异常；所有物理量输入需要保证单位正确，位置单位为m、速度单位为m/s、加速度单位为m/s²、角度单位为rad、角速度单位为rad/s，单位错误会直接导致控制效果异常。

更新日志¶

v4.10 (2024-08-07): 初始版本发布，支持可自定义通道选择的Offboard模式高级控制，支持Auto arm、Auto block PX4、Auto Loiter功能，支持位置、速度、加速度、偏航角、偏航角速度多种控制指令输入。

模块名	说明
`OffboardCtrlAPI`	基础Offboard模式控制模块，提供位置、速度、偏航的基础控制接口
`VehicleCmdAPI`	通用无人机指令发送模块，可发送起飞、降落、模式切换等基础指令
`SetpointsGenerator`	生成无人机飞行轨迹参考设定点，可作为本模块的控制输入源