TorqueThrustCtrls Module Documentation

Toolbox: RflySim APIs

Introduction

One-sentence Description: This module sends normalized force and torque control commands to the PX4 flight controller. After mixing by the PX4 mixer, the resulting motor speeds drive the UAV, supporting offline simulation and real-flight control for various configurations such as multirotors and VTOL (Vertical Take-Off and Landing) aircraft.

This module serves as the core interface for Offboard force/torque-level control within the RflySim toolchain. It is compatible with all PX4 versions from v1.7 to v1.14, automatically selecting the appropriate uORB message format based on the detected PX4 version. The module supports customizable torque dimensions and can enable a second control channel to accommodate special configurations like VTOL aircraft, which require additional control groups. Additionally, it provides features such as automatic arming, PX4 output blocking, and automatic switching to Loiter mode, enabling seamless and safe switching between Simulink custom controllers and PX4 native controllers.

In the RflySim simulation workflow, users can design custom offline controllers in Simulink, connect their normalized force/torque outputs to this module, and the resulting motor control signals will be sent to the CopterSim dynamics simulation model to drive UAV motion during simulation. In real-flight scenarios, the control commands output by this module can directly drive actual UAVs, enabling seamless integration between RflySim3D visual simulation and the PX4 flight control toolchain.

Port Descriptions

Input Ports

Port Name	Data Type	Dimension	Description
isEnCtr	boolean	1×1	Control enable signal. When input is true, normalized control commands are sent; when false, zero control commands are sent, and the PX4 flight mode is switched accordingly.
Ctrls	single	N×1	Normalized force and torque control commands. Dimension depends on parameter configuration (options: 4/6/8/12). See parameter description for protocol details.

Output Ports

Port Name	Data Type	Dimension	Description
CtrlS	double	1×16	PWM control signals computed by the PX4 mixer, directly outputtable to the inPWMs input port of CopterSim.

Parameter Configuration

The following parameters can be configured in the Mask dialog box opened by double-clicking the module:

Parameter Name	Type	Default Value	Available Values/Range	Description
Thrust dimension	int	1	1/3	Selects the dimension of thrust components in a single control channel: 1 for single-axis thrust, 3 for three-axis thrust.
Enable 2nd channel	bool	false	true/false	Enables/disables the second control channel for vehicles (e.g., VTOL) requiring multiple mixing groups.
Auto arm	bool	true	true/false	When enabled, automatically sends the UAV arming command when isEnCtr is true.
Auto block PX4	bool	true	true/false	When enabled, blocks PX4 native controller output and activates the Simulink custom controller when isEnCtr is true.
Auto Loiter	bool	true	true/false	When enabled, unblocks PX4 output and automatically switches PX4 to Loiter mode (hovering) when isEnCtr is false.
Sample Time(s)	double	0.008	>0	Module sample time in seconds.

Parameter Setting Details

Thrust dimension

This parameter defines the dimension of the thrust component within a single control channel:

• When set to 1, a single control channel includes 3 torque components (around X/Y/Z axes) + 1 Z-axis thrust component, totaling 4 dimensions.
• When set to 3, a single control channel includes 3 torque components (around X/Y/Z axes) + 3 XYZ-axis thrust components, totaling 6 dimensions.

When the second channel is enabled, the total control dimension doubles: 4 becomes 8, and 6 becomes 12.

Enable 2nd channel

For vehicles such as VTOL (Vertical Take-Off and Landing fixed-wing aircraft) that require two independent mixing groups, enabling this option allows input of a second set of force and torque control commands. The module then sends a second uORB control message (actuator_controls_1 or vehicle_torque_setpoint1).

Control Command Protocol

All inputs to the Ctrls port are normalized values conforming to PX4 control specifications. The mapping between dimensions and command components is as follows:

• Second channel disabled, thrust dimension = 1 (total dimension = 4): [Torque X, Torque Y, Torque Z, Z-axis Thrust]
• Second channel disabled, thrust dimension = 3 (total dimension = 6): [Torque X, Torque Y, Torque Z, X-axis Thrust, Y-axis Thrust, Z-axis Thrust]
• Second channel enabled, thrust dimension = 1 (total dimension = 8): [Channel 1 Torque X, Channel 1 Torque Y, Channel 1 Torque Z, Channel 1 Z-axis Thrust, Channel 2 Torque X, Channel 2 Torque Y, Channel 2 Torque Z, Channel 2 Z-axis Thrust]
• Second channel enabled, thrust dimension = 3 (total dimension = 12): [Channel 1 Torque X, Channel 1 Torque Y, Channel 1 Torque Z, Channel 1 X-axis Thrust, Channel 1 Y-axis Thrust, Channel 1 Z-axis Thrust, Channel 2 Torque X, Channel 2 Torque Y, Channel 2 Torque Z, Channel 2 X-axis Thrust, Channel 2 Y-axis Thrust, Channel 2 Z-axis Thrust]

All torques are defined in the body-fixed coordinate frame. Thrust directed along the positive Z-axis indicates upward force, consistent with multirotor flight conventions.

Module Characteristics

Characteristic	Value
Supported Data Types	double, single
Direct Feedthrough	Yes
Sample Time	Discrete
Code Generation Support	No

Data Communication Protocol

This module communicates with the PX4 flight controller via uORB:

1. Protocol Format: The input Ctrl control quantities are divided by dimension as follows:
2. First control channel (second channel disabled):
   • 4D format: [X-axis torque, Y-axis torque, Z-axis torque, Z-axis thrust] (1D thrust mode)
   • 6D format: [X-axis torque, Y-axis torque, Z-axis torque, X-axis thrust, Y-axis thrust, Z-axis thrust] (3D thrust mode)

3. After enabling the second control channel (for VTOL vehicles):

   • 8D format: Append second channel data after the first channel’s 4D format: [X1-axis torque, Y1-axis torque, Z1-axis torque, Z1-axis thrust]
   • 12D format: Append second channel data after the first channel’s 6D format: [X1-axis torque, Y1-axis torque, Z1-axis torque, X1-axis thrust, Y1-axis thrust, Z1-axis thrust]

4. uORB Message Rules:

5. PX4 v1.7 ~ v1.13: The first control channel sends the actuator_controls_0 message; the second control channel sends the actuator_controls_1 message.
6. PX4 v1.14 and later: The first control channel sends the vehicle_torque_setpoint and vehicle_thrust_setpoint messages; the second control channel sends the vehicle_torque_setpoint1 and vehicle_thrust_setpoint1 messages.

Related Modules

Module Name	Description
SendPWMs	Outputs normalized PWM signals to the PX4 flight controller, directly controlling motor output
SetOffboardMode	Controls the PX4 flight controller to switch to Offboard flight mode
VehicleAttitudeGetter	Retrieves the current attitude information of the UAV from the PX4 flight controller
VehicleStateGetter	Retrieves the current position, velocity, and other state information of the UAV from the PX4 flight controller

Usage Examples

For related usage examples, refer to the following path:

[RflySim installation path]/RflySimAPIs/5.RflySimFlyCtrl/0.ApiExps/17.OffboardCtrlsAPI/Readme.pdf

Please refer to Readme.pdf in the above path for complete example descriptions and operational procedures.

Notes and Common Issues

• Initialization Sequence: This module depends on successful initialization of the PX4 flight controller and CopterSim before it can send control messages properly. Ensure that the flight controller and visualization engine are connected before enabling Simulink-side control output during simulation startup. Otherwise, control messages may be lost, causing the drone to become unresponsive.
• PX4 Version Compatibility: Different PX4 versions correspond to distinct uORB message formats. The module automatically adapts to the message format of the corresponding version; however, when using a custom PX4 firmware, you must confirm that the firmware has enabled the appropriate version’s actuator_controls_0/1 (v1.7–v1.13) or vehicle_torque/thrust_setpoint (v1.14 and above) messages. Otherwise, control commands will not take effect.
• Control Dimension Matching: The dimension of the input Ctrls signal must match the torque dimension selected in the module parameters and whether the second channel is enabled. For example, if the second channel is enabled and 3D thrust is selected, the input dimension must be 12. Dimension mismatch will cause incorrect interpretation of control quantities, potentially resulting in drone yaw or loss of control.
• Sample Time Matching: The Sample Time(s) setting of the module must match the control cycle of the PX4 flight controller. It is recommended to set it between 0.001s and 0.005s. An overly large sample time will result in discontinuous control output, potentially causing drone oscillation.
• Auto Function Logic: After checking Auto Loiter, when the isEnCtr input is false, the module automatically switches PX4 to Loiter hover mode. If this functionality is not needed, do not check this option, otherwise manual flight mode operation may become abnormal. Simultaneously, when both Auto block PX4 and Auto arm are checked, automatic disarming and enabling of Simulink control occur only when isEnCtr is true; manual disarming via QGroundControl is unnecessary.
• Control Quantity Normalization Requirement: The input torque and thrust values must be normalized, with ranges strictly maintained within [-1, 1]. Positive thrust indicates upward direction along the corresponding Z-axis. Values outside this range, after PX4 mixing, will result in abnormal motor speeds, potentially causing simulation or real-world flight instability.
• Second Channel Usage Scenario: The second control channel is intended only for special drone configurations such as VOTL. Standard multirotors or fixed-wing aircraft do not require it; enabling it inadvertently will cause extra control quantities to occupy mixing channels, resulting in abnormal aircraft output.
• Output Port Connection: The module’s output CtrlS[16] must be fully connected to the inPWMs input port of the CopterSim DLL model; partial channel extraction is not allowed, otherwise incorrect motor speed transmission will occur after mixing.

Changelog

• v4.20 (2024-08-07): Added support for vehicle_torque/thrust_setpoint messages in PX4 v1.14; introduced the second control channel feature, supporting VTOL multi-channel applications; initial version released.