TorqueThrustCtrls 模块文档¶

所属工具箱：RflySim APIs

TorqueThrustCtrls 模块外观

简介¶

一句话描述：该模块可将归一化后的力和力矩控制量发送给PX4飞控，经PX4混控器计算得到电机转速后驱动无人机运动，支持多旋翼、垂直起降无人机等多种构型的离线仿真与真机实飞控制。

该模块是RflySim工具链中Offboard力力矩层级控制的核心接口模块，适配PX4 v1.7至v1.14全版本飞控，可根据PX4版本自动匹配对应uORB消息格式发送控制指令。模块支持自定义力矩维度，还可开启第二控制通道以适配垂直起降无人机（VTOL）这类需要额外控制组的特殊构型，同时提供自动解锁、PX4输出屏蔽、自动切换Loiter模式等功能，可便捷实现Simulink自定义控制器与PX4原生控制器的安全切换。

在RflySim仿真流程中，用户可在Simulink中设计自定义离线控制器，将归一化力力矩输出接入该模块，模块处理后得到的电机控制信号最终会发送给CopterSim的动力学仿真模型，驱动无人机完成仿真运动；在真机实飞场景下，该模块输出的控制指令可直接驱动真实无人机飞行，可无缝对接RflySim3D可视化仿真与PX4飞控工具链。

端口说明¶

输入端口（Inputs）¶

端口名	数据类型	维度	说明
`isEnCtr`	`boolean`	`1×1`	控制使能信号，输入为`true`时发送归一化控制量，输入为`false`时发送全零控制量，同时切换PX4飞行模式
`Ctrls`	`single`	N×1	归一化后的力和力矩控制量，维度由参数配置决定，范围为4/6/8/12，具体协议见参数说明

输出端口（Outputs）¶

端口名	数据类型	维度	说明
`CtrlS`	`double`	`1×16`	经过PX4混控器计算得到的PWM控制信号，可直接输出给CopterSim的inPWMs输入端口

参数配置（Parameters）¶

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

参数名	类型	默认值	可选值/范围	说明
`Thrust dimension`	`int`	`1`	`1/3`	控制信号中推力分量的维度选择，1为单轴推力，3为三轴推力
`Enable 2nd channel`	`bool`	`false`	`true/false`	是否开启第二控制通道，用于VTOL等需要多组混控的场景
`Auto arm`	`bool`	`true`	`true/false`	使能后，当`isEnCtr`输入为`true`时自动发送无人机解锁指令
`Auto block PX4`	`bool`	`true`	`true/false`	使能后，当`isEnCtr`输入为`true`时屏蔽PX4原生控制器输出，启用Simulink自定义控制器
`Auto Loiter`	`bool`	`true`	`true/false`	使能后，当`isEnCtr`输入为`false`时解除PX4输出屏蔽，自动切换PX4到Loiter模式保持无人机悬停
`Sample Time(s)`	`double`	`0.008`	`>0`	模块采样时间，单位为秒

参数设置说明¶

`Thrust dimension`¶

该参数定义单个控制通道中推力分量的维度：

选择1时，单个控制通道包含3个力矩分量（绕X/Y/Z轴）+1个Z轴推力分量，共4维控制量
选择3时，单个控制通道包含3个力矩分量（绕X/Y/Z轴）+3个XYZ轴推力分量，共6维控制量

开启第二控制通道后，总控制量维度会加倍，即4维变为8维，6维变为12维。

`Enable 2nd channel`¶

针对VTOL（垂直起降固定翼）等需要两组独立混控的载具，开启后可输入第二组力和力矩控制量，模块会发送第二组uORB控制消息（actuator_controls_1或vehicle_torque_setpoint1）。

控制量协议说明¶

输入Ctrls端口的控制量均为归一化数值，符合PX4控制量规范，按维度对应关系如下：

未开启第二通道，推力维度=1（总维度4）：[扭矩X, 扭矩Y, 扭矩Z, Z轴推力]
未开启第二通道，推力维度=3（总维度6）：[扭矩X, 扭矩Y, 扭矩Z, X轴推力, Y轴推力, Z轴推力]
开启第二通道，推力维度=1（总维度8）：[第一通道扭矩X, 第一通道扭矩Y, 第一通道扭矩Z, 第一通道Z轴推力, 第二通道扭矩X, 第二通道扭矩Y, 第二通道扭矩Z, 第二通道Z轴推力]
开启第二通道，推力维度=3（总维度12）：[第一通道扭矩X, 第一通道扭矩Y, 第一通道扭矩Z, 第一通道X轴推力, 第一通道Y轴推力, 第一通道Z轴推力, 第二通道扭矩X, 第二通道扭矩Y, 第二通道扭矩Z, 第二通道X轴推力, 第二通道Y轴推力, 第二通道Z轴推力]

所有力矩均基于机体坐标系，推力沿Z轴正方向表示向上，符合多旋翼飞行习惯。

模块特性（Block Characteristics）¶

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

数据通信协议¶

本模块通过uORB与PX4飞控进行通信：

协议格式：输入Ctrls控制量按维度划分规则如下：
第1控制通道（不开启第2通道）：
- 4维格式：[X轴力矩, Y轴力矩, Z轴力矩, Z轴推力]（1D推力模式）
- 6维格式：[X轴力矩, Y轴力矩, Z轴力矩, X轴推力, Y轴推力, Z轴推力]（3D推力模式）
开启第2控制通道后（针对VTOL载具）：
- 8维格式：在第1通道4维格式后追加第二通道数据：[X1轴力矩, Y1轴力矩, Z1轴力矩, Z1轴推力]
- 12维格式：在第1通道6维格式后追加第二通道数据：[X1轴力矩, Y1轴力矩, Z1轴力矩, X1轴推力, Y1轴推力, Z1轴推力]
uORB消息规则：
PX4 v1.7~v1.13版本：第1控制通道发送actuator_controls_0消息，第2控制通道发送actuator_controls_1消息
PX4 v1.14及以上版本：第1控制通道发送vehicle_torque_setpoint和vehicle_thrust_setpoint消息，第2控制通道发送vehicle_torque_setpoint1和vehicle_thrust_setpoint1消息

使用示例¶

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

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

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

注意事项与常见问题¶

初始化顺序：该模块依赖PX4飞控与CopterSim完成初始化后才能正常发送控制消息，请确保仿真启动时先完成飞控与可视化引擎的连接，再使能Simulink侧控制输出，否则可能出现控制消息丢失导致无人机无响应的问题。
PX4版本匹配：不同PX4版本对应不同的uORB消息格式，模块会自动适配对应版本的消息，但使用自定义PX4固件时需确认固件中已使能对应版本的actuator_controls_0/1（v1.7~v1.13）或vehicle_torque/thrust_setpoint（v1.14及以上）消息，否则会出现控制指令不生效。
控制维度匹配：输入Ctrls信号的维度必须和模块参数中选择的力矩维度、是否开启第二通道的配置一致，例如开启第二通道且选择3D推力时输入维度必须为12，维度不匹配会导致控制量解析错误，出现飞机偏航或失控问题。
采样时间匹配：模块设置的Sample Time(s)需要和PX4飞控的控制周期匹配，建议设置为0.001s~0.005s，过大的采样时间会导致控制输出不连续，引发无人机震荡。
Auto功能逻辑：勾选Auto Loiter后，当isEnCtr输入为false时模块会自动切换PX4到Loiter悬停模式，若不需要该功能请不要勾选，否则会导致手动飞行模式异常；同时勾选Auto block PX4和Auto arm时，仅当isEnCtr为true时才会自动解锁并启用Simulink控制，无需手动在QGroundControl中解锁。
控制量归一化要求：输入的力矩和推力均为归一化后的值，范围需要保持在[-1, 1]之间，推力为正表示沿对应Z轴向上，超出范围后经过PX4混控会输出异常电机转速，导致仿真或真机飞行失控。
第二通道使用场景：第二控制通道仅适用于VOTL等特殊构型无人机，普通多旋翼/固定翼无需开启，误开启会导致多余控制量占用混控通道，引发飞机输出异常。
输出端口对接：模块输出的CtrlS[16]必须完整对接给CopterSim DLL模型的inPWMs输入端口，不能只截取部分通道，否则会导致混控后的电机转速传输错误。

更新日志¶

v4.20 (2024-08-07): 新增支持PX4 v1.14版本的vehicle_torque/thrust_setpoint消息支持，新增第二控制通道功能，支持VTOL多控制通道应用，完成初始版本发布。

模块名	说明
`SendPWMs`	输出归一化PWM信号发送给PX4飞控，直接控制电机输出
`SetOffboardMode`	控制PX4飞控切换到Offboard飞行模式
`VehicleAttitudeGetter`	从PX4飞控获取无人机当前的姿态信息
`VehicleStateGetter`	从PX4飞控获取无人机当前的位置、速度等状态信息