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 relies 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 Simul