RCOverCtrlAPI 模块文档¶

所属工具箱：RflySim APIs

RCOverCtrlAPI 模块外观

简介¶

一句话描述：该模块用于向PX4发送自定义手动控制信号，覆盖原有遥控器手动控制输入，支持灵活配置Offboard控制模式。

本模块属于RflySim APIs工具链，主要用于在Simulink自定义开发控制器时，重发manual_control_setpoint消息，实现对PX4原有手动控制信号的覆盖。它支持自定义选择Offboard姿态控制通道，可配置自动解锁、PX4输出屏蔽、自动Loiter模式切换等功能，当isEnCtrl输入为true时启用Simulink自定义控制并进入Offboard模式，为false时自动切换PX4到Loiter模式保持悬停，保障仿真安全。

该模块通常用于自定义手动控制开发、无人机控制算法仿真验证场景，配合CopterSim完成飞控动力学仿真，可对接RflySim3D实现可视化展示，与PX4飞控通过MAVLink协议交互控制消息，支持手动、定高、定点、特技、自稳多种控制模式自定义切换。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`isEnCtrl`	`boolean`/`double`	`1×1`	使能控制信号，输入为`true`时发送控制数据并进入Offboard模式；输入为`false`时停止发送控制，PX4自动切换至Loiter模式；信号从`false`跳变到`true`时自动执行解锁操作
`Mode`	`uint8`	`1×1`	控制模式选择，1=手动模式，2=定高模式，3=定点模式，5=特技模式，6=自稳模式
`Ctrls`	`single`	N×1 [待确认]	控制信号向量，按顺序对应roll、pitch、yaw、throttle、flaps、aux1~aux6通道信号，所有通道数据范围为`[-1, 1]`，根据选中的控制通道维度可变

输出端口（Outputs）¶

本模块无输出端口。

参数配置（Parameters）¶

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

参数名	类型	默认值	可选值/范围	说明
`Enable roll`	`bool`	`true`	`true`/`false`	是否使能滚转通道控制
`Enable pitch`	`bool`	`true`	`true`/`false`	是否使能俯仰通道控制
`Enable yaw`	`bool`	`true`	`true`/`false`	是否使能偏航通道控制
`Enable throttle`	`bool`	`true`	`true`/`false`	是否使能油门通道控制
`Enable flaps`	`bool`	`false`	`true`/`false`	是否使能襟翼通道控制
`Enable aux1`	`bool`	`false`	`true`/`false`	是否使能辅助通道1控制
`Enable aux2`	`bool`	`false`	`true`/`false`	是否使能辅助通道2控制
`Enable aux3`	`bool`	`false`	`true`/`false`	是否使能辅助通道3控制
`Enable aux4`	`bool`	`false`	`true`/`false`	是否使能辅助通道4控制
`Enable aux5`	`bool`	`false`	`true`/`false`	是否使能辅助通道5控制
`Enable aux6`	`bool`	`false`	`true`/`false`	是否使能辅助通道6控制
`Auto arm`	`bool`	`true`	`true`/`false`	是否开启自动解锁功能
`Auto block PX4`	`bool`	`true`	`true`/`false`	是否开启PX4输出自动屏蔽功能，使能后`isEnCtrl`为`true`时使用Simulink控制器控制载具
`Auto Loiter`	`bool`	`true`	`true`/`false`	是否开启自动Loiter切换功能，使能后`isEnCtrl`为`false`时自动解除PX4输出屏蔽并切换到Loiter模式
`Sample Time(s)`	`double`	`0.01`	`>0`	模块采样时间

参数设置说明¶

控制通道选择参数¶

每个控制通道对应一个使能勾选框，勾选对应通道后，该通道的控制信号将被加入输出的manual_control_setpoint消息中，未勾选的通道将不发送控制信号，输入Ctrls向量的维度和选中的通道数量一致。

Auto arm¶

开启该参数后，当isEnCtrl输入从false变为true时，模块会自动向PX4发送无人机解锁指令，无需额外手动配置解锁逻辑。

Auto block PX4¶

开启该参数后，当isEnCtrl输入为true时，模块会自动发送信号屏蔽PX4原本的控制输出，允许Simulink生成的控制器直接控制无人机。

Auto Loiter¶

开启该参数后，当isEnCtrl输入为false时，模块会自动解除PX4输出的屏蔽，同时将PX4切换到Loiter（悬停）模式，保证无人机在退出Offboard控制后可以自动保持悬停状态，避免失控。

模块特性（Block Characteristics）¶

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

数据通信协议¶

本模块通过MAVLink协议发送manual_control_setpoint消息，基于UDP与PX4飞控进行通信，默认使用MAVLink默认端口进行数据交互，数据格式遵循MAVLink规范：

Mode输入为uint8类型，对应控制模式定义：
`1：手动模式
2：定高模式
3：定点模式
5：特技模式
6：自稳模式
Ctrls[*]输入为single类型向量，各通道数据范围均为[-1, 1]，定义如下：
roll：滚转通道，正向对应向右滚转（右侧向下）
pitch：俯仰通道，正向对应向前移动（机头向下）
yaw：偏航通道，正向对应从上往下顺时针偏航旋转
throttle：油门通道，对应0%~100%油门，正向对应向上移动
flaps：襟翼位置
aux1~aux6：辅助通道1~6

使用示例¶

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

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

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

注意事项与常见问题¶

初始化顺序：本模块依赖PX4飞控与RflySim仿真环境完成启动初始化后才能正常工作，请勿在仿真启动前提前输出使能信号isEnCtrl = true，否则会导致Offboard模式切换失败、飞控不响应控制指令。
通道维度匹配：输入端口Ctrls的维度必须和模块参数中选中的控制通道数量保持一致，否则会出现维度不匹配的仿真错误；控制信号输入必须严格保持在[-1, 1]范围内，超出范围会导致PX4飞控控制异常。
功能勾选冲突避免：不可同时勾选Auto block PX4与Auto Loiter两个功能选项，否则会导致飞控模式切换逻辑冲突，无法正常在Offboard与Loiter模式间切换。
模式输入合法性：Mode端口仅支持文档指定的合法数值（1/2/3/5/6），输入未定义模式值会导致飞控无法识别控制模式，出现无响应或飞控切机故障。
采样时间匹配：模块的Sample Time参数建议和PX4飞控的控制周期保持一致（通常为0.004s~0.01s），采样时间过大会导致控制信号更新不及时，引发载具控制不稳定。
切换逻辑要求：当isEnCtrl从false切换为true时，请确保载具已处于可解锁飞行状态，否则自动解锁功能可能会失败；若无需自动解锁功能，请取消勾选Auto arm参数选项。

更新日志¶

v4.1 (2024-08-07): 初始版本发布，实现通过重发manual_control_setpoint消息覆盖RC遥控器手动控制信号，支持自定义控制通道选择、Auto arm、Auto block PX4、Auto Loiter功能，提供多模式控制与多通道控制信号输入。

模块名	说明
`VehicleStatus`	获取PX4飞控的状态信息输出
`OffboardCtrlAPI`	实现PX4 Offboard模式控制，直接控制无人机运动
`SetPositionAPI`	实现位置控制指令发送
`VehicleCommandAPI`	发送MAVLink的飞行器控制指令