OffboardAttCtrlAPI 模块文档¶

所属工具箱：RflySim APIs

OffboardAttCtrlAPI 模块外观

简介¶

一句话描述：该模块用于使PX4飞控进入Offboard模式，支持多种格式的姿态指令输入，实现自定义姿态控制，同时提供自动解锁、模式切换等辅助功能。

该模块属于RflySim APIs工具库，是RflySim工具链中实现自定义上层姿态控制开发的核心接口模块，适用于算法开发者开发自定义Offboard姿态控制算法的仿真验证场景。它可以和CopterSim的物理仿真引擎、PX4飞控程序交互，通过Mavlink协议将Simulink中生成的姿态控制指令发送给PX4飞控，同时可根据使能信号自动完成解锁、Offboard模式切换、PX4输出屏蔽，以及失能时自动切回Loiter模式保航，保障仿真过程的安全性与稳定性。开发者可以基于该模块快速验证自定义的姿态控制算法，不需要额外处理PX4 Offboard通信与模式切换的底层逻辑。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`isEnCtrl`	`boolean`	`1×1`	控制使能信号：输入为`true`时发送控制指令并开启Simulink端控制；输入为`false`时不发送控制指令，PX4将自动切换至Loiter模式
`Ctrls`	`double`	可变[待确认]	Offboard模式姿态控制指令，维度随参数配置变化：总推力+姿态指令形式下，欧拉角模式为1×6，四元数模式为1×7；仅角速率控制时维度等于勾选的角速率通道数加1（推力通道）[待确认]，推力范围1000~2000，对应匹配到CopterSim模型的归一化范围

输出端口（Outputs）¶

本模块无输出端口。

参数配置（Parameters）¶

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

参数名	类型	默认值	可选值/范围	说明
`AttitudeType`	枚举	`Euler`	`Euler`, `Quaternion`	选择姿态控制指令的类型，可选欧拉角或四元数
`RollRate`	`bool`	`false`	`true`, `false`	勾选后开启滚转角速率控制，单位rad/s
`PitchRate`	`bool`	`false`	`true`, `false`	勾选后开启俯仰角速率控制，单位rad/s
`YawRate`	`bool`	`false`	`true`, `false`	勾选后开启偏航角速率控制，单位rad/s
`Auto arm`	`bool`	`false`	`true`, `false`	勾选后，当`isEnCtrl`输入为`true`时模块自动发送载具解锁指令
`Auto block PX4`	`bool`	`false`	`true`, `false`	勾选后，当`isEnCtrl`输入为`true`时模块将屏蔽PX4原生控制器输出，使用Simulink端控制器输出控制载具
`Auto Loiter`	`bool`	`false`	`true`, `false`	勾选后，当`isEnCtrl`输入为`false`时模块将解除PX4输出屏蔽，并自动切换载具到Loiter模式，保证载具稳定悬停
`SampleTime`	`double`	`0.01`	`>0`	模块控制信号发送采样时间，单位s

参数设置说明¶

`AttitudeType`¶

用于选择输入控制指令中姿态信息的格式，选择Euler时，姿态部分为机体坐标系下的三维欧拉角[roll_body, pitch_body, yaw_body]，单位rad；选择Quaternion时，姿态部分为四元数[w, x, y, z]格式。

角速率控制选项（`RollRate`/`PitchRate`/`YawRate`）¶

勾选对应通道后，该通道将改为输入角速率指令（单位rad/s）而非角度/姿态指令，支持单独对一个或多个通道使用角速率控制。

自动功能选项（`Auto arm`/`Auto block PX4`/`Auto Loiter`）¶

三个选项配合isEnCtrl输入实现自动化控制流程：开启后可根据控制使能信号自动完成解锁、PX4输出屏蔽/解除、模式切换的流程，无需用户额外处理模式切换逻辑。

`SampleTime`¶

模块与飞控通信发送控制指令的采样时间，需与Simulink仿真步长匹配，默认值为0.01s对应100Hz控制频率。

模块特性（Block Characteristics）¶

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

数据通信协议¶

本模块基于UDP协议与PX4仿真固件进行Offboard控制指令通信，默认使用RflySim统一UDP通信端口，发送数据格式为：

使能控制位：1字节，isEnCtrl为true时置1，false时置0
模式控制指令：包含Auto arm、Auto block PX4、Auto Loiter对应的配置控制码
姿态控制数据：根据模块参数配置，依次发送对应格式的控制量（欧拉角/四元数/角速率）+推力指令，单精度浮点格式，按顺序传输

使用示例¶

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

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

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

注意事项与常见问题¶

初始化顺序：该模块依赖RflySim仿真环境和PX4固件通信框架初始化完成后才能正常工作，需确保整个仿真模型中RflySim平台的基础初始化模块（如VehicleSimModel）在本模块之前完成初始化，否则会出现Offboard模式使能失败、指令不生效的问题。
采样时间匹配：模块指定的Sample Time(s)需与PX4 Offboard控制的通信周期匹配，建议设置为0.05s（20Hz）或0.1s（10Hz）；若采样时间设置过大，会触发PX4的Offboard模式超时退出机制，导致载具自动切回Loiter模式；若采样时间设置远小于平台通信周期，会造成无效指令重复发送，增加仿真运行负担。
控制指令维度匹配：Ctrls输入端口的维度必须与模块参数配置一致：选择欧拉角姿态控制时需输入4维信号（前3维为姿态指令，第4维为推力指令），选择四元数控制时需输入5维信号（前4维为四元数指令，第5维为推力指令），勾选角速率控制时需对应输入对应数量的角速率+1维推力指令，维度不匹配会导致控制错乱、仿真报错。
单位与推力约定：输入姿态角、角速率的单位必须为rad和rad/s，使用角度输入会导致指令幅值错误，造成载具姿态失控；推力需遵循约定规则：多旋翼仅Thrust[2]为有效负油门请求，固定翼仅Thrust[0]为有效油门需求，错误分配推力通道会导致动力输出异常。
模式切换逻辑：当isEnCtrl输入为false时，模块会自动切出Offboard模式进入Loiter模式，请勿在isEnCtrl持续为false时期望Offboard控制生效；若需要保持Offboard控制，需确保isEnCtrl持续输入true，同时保证控制指令按照约定周期稳定发送。
Auto功能冲突：若勾选了Auto block PX4则不可同时勾选Auto Loiter，二者功能互斥，同时勾选会导致PX4输出控制逻辑混乱，出现载具不受控的问题；若需要Offboard控制时屏蔽PX4输出、退出Offboard时自动Loiter悬停，保持Auto block PX4和Auto Loiter同时勾选为默认配置是错误的，正确配置为开启两个选项，仅当isEnCtrl为true时屏蔽PX4输出、开启Offboard控制，isEnCtrl为false时解除屏蔽进入Loiter，不会产生冲突。
数值范围匹配：输入的控制指令数值范围需要符合约定：对于所有机型，Ctrls控制量输出范围对应1000~2000匹配模型的归一化范围，若指令超出该范围会导致输出饱和，无法达到预期控制效果。

更新日志¶

v4.0 (2024-08-07): 初始版本发布，支持Offboard模式下欧拉角/四元数姿态指令、角速率指令控制，支持Auto arm、Auto block PX4、Auto Loiter功能配置，适配多旋翼与固定翼载具。

模块名	说明
`OffboardPosCtrlAPI`	Offboard模式位置控制模块，用于发送位置和速度指令控制载具运动
`VelocityToPositionAPI`	将期望速度转换为期望位置，辅助实现位置控制闭环
`SetOffboardMode`	控制载具进入或退出Offboard模式
`ReadIMUAPI`	读取仿真中载具的IMU传感器数据，用于控制器反馈
`ReadGNSSAPI`	读取仿真中载具的GNSS位置和速度数据，用于导航反馈