OffboardPvaCtrlAPI Module Documentation

Toolbox: RflySim APIs

Introduction

One-sentence description: This module serves as the position-velocity-acceleration control interface for PX4 Offboard mode, supporting switching among multiple control modes, and enables sending control commands generated by Simulink to the PX4 flight controller to achieve vehicle motion control.

This module belongs to the RflySim APIs library and is a core component of the RflySim toolchain for custom Offboard control development. It primarily targets simulation development scenarios requiring autonomous development of position, velocity, or acceleration-level controllers. The module supports automatic arming and automatic control mode switching, and allows flexible enabling/disabling of Simulink-based custom control via an enable signal: when control is enabled, the module sends position, velocity, acceleration, yaw angle, and yaw rate commands generated by the custom controller to the PX4 flight controller via the MAVLink protocol, while blocking PX4’s native control outputs to enable vehicle control using the Simulink controller; when control is disabled, the module automatically lifts the block and switches the vehicle to PX4’s Loiter hover mode to ensure flight safety.

The final control signal output by this module is transmitted to the CopterSim DLL interface, enabling interaction with the PX4 flight controller and the RflySim3D visualization environment. This allows users to rapidly validate custom Offboard control algorithms in Simulink without modifying the underlying source code of the PX4 flight controller, facilitating flexible switching among different control modes and adapting to various development scenarios such as trajectory tracking and motion control.

Port Descriptions

Input Ports

Port Name	Data Type	Dimension	Description
isEnCtrl	boolean	1×1	When the input is true, the module sends control data and switches the vehicle to Offboard mode; when the input is false, the module stops sending control data, and PX4 automatically switches to Loiter mode; when the input transitions from false to true, the module automatically arms the vehicle and enters Offboard mode.
PVAYR	single/double	1×11	11-dimensional Offboard control command vector, with dimensions in the following order: NED coordinate system x-position, y-position, z-position, x-velocity, y-velocity, z-velocity, x-acceleration, y-acceleration, z-acceleration, yaw angle, yaw rate. Channels not under control can be set to NaN.
EnList	boolean	1×11	11-dimensional control enable vector, where each dimension corresponds to a control channel in PVAYR. When the corresponding dimension is true, PX4 responds to that channel’s control command; when false, it ignores that channel.

Output Ports

Port Name	Data Type	Dimension	Description
CtrlS	double	1×16	Generated Offboard control command output, which must be connected to the inPWM input port of the CopterSim DLL model.

Parameter Configuration

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

Parameter Name	Type	Default Value	Optional Values / Range	Description
Auto arm	boolean	false	true/false	When checked, the module automatically sends the vehicle arming command when the isEnCtrl input is true.
Auto block PX4	boolean	false	true/false	When checked, the module sends a signal to block PX4’s native output, allowing the Simulink controller output to control the vehicle when isEnCtrl is true.
Auto Loiter	boolean	false	true/false	When checked, the module lifts the block on PX4’s output and automatically switches to PX4’s native Loiter mode when isEnCtrl is false, ensuring the vehicle maintains hover in mid-air.
Sample Time(s)	double	0.01	>0	Module sampling time in seconds.

Parameter Setting Notes

Auto arm

This feature automates the arming process. When enabled, there is no need to add separate arming command blocks in the Simulink model; arming is automatically performed when Offboard control is enabled, simplifying model design.

Auto block PX4

When using a custom controller developed in Simulink for Offboard control, this option must be enabled to block PX4’s native controller output and allow the custom controller output to take effect. If this option is not enabled, PX4’s native controller output will superimpose with the custom controller output, resulting in abnormal control behavior.

Auto Loiter

When Offboard control is disabled (isEnCtrl is false), enabling this option automatically switches the vehicle to PX4’s native Loiter hover mode, preventing the vehicle from descending or losing control due to loss of Offboard command, thereby enhancing simulation safety.

Sample Time(s)

This parameter must match the fixed step size of the Simulink model. Typically, PX4 simulation uses a 10 ms (i.e., 0.01 s) sampling period; if the model step size is modified, this parameter must be updated accordingly.

Module Characteristics

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

Data Communication Protocol

This module outputs a 16-dimensional CtrlS signal, converting the input control commands into the appropriate format and sending them to the inPWM input port of the CopterSim DLL model. The input PVAYR control command protocol format is as follows:

The input is an 11-dimensional control vector in the NED coordinate system, with the following meanings for each dimension:

1. x: Position control (unit: m)
2. y: Position control (unit: m)
3. z: Position control (unit: m)
4. Vx: Velocity control (unit: m/s)
5. Vy: Velocity control (unit: m/s)
6. Vz: Velocity control (unit: m/s)
7. Ax: Acceleration control (unit: m/s²)
8. Ay: Acceleration control (unit: m/s²)
9. Az: Acceleration control (unit: m/s²)
10. Yaw: Yaw angle control (unit: rad, range: -π to π)
11. Yawrate: Yaw rate control (unit: rad/s)

If a channel is not under control, the corresponding position in PVAYR must be set to NaN, and the corresponding dimension in EnList specifies whether that channel is enabled.

Related Modules

Module Name	Description
SetControlGroupAPI	Configures the enablement status of PX4 flight control channels for Offboard mode control setup
OffboardAttiCtrlAPI	Attitude angle control API module for Offboard mode
OffboardRateCtrlAPI	Angular rate control API module for Offboard mode
VehicleCmdPublisher	API module for publishing general vehicle control commands

Usage Examples

For relevant usage examples, please 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 steps.

Notes and Common Issues

• Initialization Sequence: After simulation startup, isEnCtrl must first be set to false to complete PX4-side initialization, and then switched to true to enable Offboard control; otherwise, PX4 will not correctly respond to Offboard mode switching. If the Auto arm feature is enabled, the disarming command is automatically sent only when isEnCtrl transitions from false to true; directly setting isEnCtrl to true at simulation startup will not trigger automatic arming.
• Control Command Consistency: In the PVAYR input vector, if a dimension’s corresponding control is disabled (i.e., the corresponding bit in EnList is false), the corresponding position in PVAYR must be set to NaN; arbitrarily filling in fixed values will cause abnormal PX4 control logic. When enabling multiple control layers simultaneously (e.g., enabling both position and corresponding-axis velocity control), ensure control commands satisfy kinematic consistency to avoid control conflicts leading to vehicle attitude divergence.
• Sampling Time Matching: The module’s sampling time must match the heartbeat period requirement of PX4 Offboard control. A sampling time greater than 0.2s is not recommended, as PX4 will automatically exit Offboard mode and revert to Loiter mode due to timeout. Additionally, the sampling time must be consistent with the base sampling time of the Simulink model to prevent control command jumps caused by asynchronous data updates.
• Mode-Switching Safety Settings: It is recommended to enable the Auto Loiter option: when isEnCtrl is set to false, the module automatically switches to PX4’s native Loiter mode to maintain hover, preventing vehicle loss of control. If Auto Loiter is disabled, you must implement your own safety handling logic upon Offboard deactivation.
• Coordinate System Convention: The position, velocity, and acceleration inputs in PVAYR use the NED coordinate system. If control commands are in the ENU coordinate system, coordinate transformation must be performed before inputting them into the module; otherwise, control direction reversal will occur. The yaw angle input range is −π to π; values outside this range must be normalized first to avoid abnormal yaw control.
• Enable Bit Configuration: The EnList input vector must correspond to the control requirements: only enable the control channels you need to use; disable (set to false) the enable bits for unused channels to prevent PX4 from responding to invalid control quantities, which may cause flight instability. For example, in pure position control, only enable the xyz position and yaw channels, and set the enable bits for all other channels to false.

Changelog

• v4.1.0 (2024-08-07): Initial release of the PVA multi-mode switchable control interface module for Offboard mode, supporting combination and switching among position, velocity, and acceleration control methods, with automatic arming and automatic mode-switching features.