OffboardAdvCtrlAPI Module Documentation¶

Toolbox: RflySim APIs

OffboardAdvCtrlAPI Module Appearance

Introduction¶

One-sentence description: This module serves as the advanced control interface for PX4 Offboard mode within the RflySim toolchain. It supports custom multi-dimensional control commands, automatically handles mode transitions, arming/disarming, and mode-switching logic, enabling Simulink-side custom Offboard control of UAVs.

This module belongs to the RflySim APIs library and facilitates Offboard control interaction between the Simulink simulation environment, the PX4 flight controller, and the CopterSim simulation engine. It allows users to selectively enable control channels for position, velocity, acceleration, yaw angle, and yaw rate. Unselected control channels can be ignored by setting their corresponding values to NaN. This meets developers’ needs for designing custom UAV advanced controllers and is suitable for simulation and verification of various Offboard control algorithms, including trajectory tracking control, visual servoing control, and formation control.

The module integrates automated logic such as automatic arming, automatic switching of PX4 outputs, and automatic hover (loiter) when idle: when the control enable input is true, it automatically performs arming, blocks the native PX4 control output, and sends Simulink-generated control commands to the PX4 flight controller via the Offboard interface; CopterSim then performs UAV dynamics simulation and synchronously transmits flight states to RflySim3D for 3D visualization. When the control enable input is false, it automatically switches the PX4 to Loiter mode to ensure UAV state safety during simulation, eliminating the need for developers to manually handle mode transitions and logical interactions.

Port Descriptions¶

Input Ports¶

Port Name	Data Type	Dimension	`N×1`, where N is the number of enabled control channels	Description
`isEnCtrl`	`boolean`	`1×1`	Control enable signal: when input is `true`, control commands are sent and Offboard control is activated; when input is `false`, control command transmission stops and PX4 switches to Loiter mode
`Ctrls[*]`	`double`	`N×1`, where N is the number of enabled control channels	Normalized Offboard control commands, following the NED coordinate system protocol. Unselected control channels do not occupy input slots; set corresponding values to `NaN` if a state is not to be controlled

Output Ports¶

This module has no output ports.

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
`CopterID`	`int`	`1`	`1~255`	ID number of the target UAV
`Enable position x`	`bool`	`false`	`true/false`	Whether to enable the x-position control channel
`Enable position y`	`bool`	`false`	`true/false`	Whether to enable the y-position control channel
`Enable position z`	`bool`	`false`	`true/false`	Whether to enable the z-position control channel
`Enable velocity x`	`bool`	`false`	`true/false`	Whether to enable the x-velocity control channel
`Enable velocity y`	`bool`	`false`	`true/false`	Whether to enable the y-velocity control channel
`Enable velocity z`	`bool`	`false`	`true/false`	Whether to enable the z-velocity control channel
`Enable acceleration x`	`bool`	`false`	`true/false`	Whether to enable the x-acceleration control channel
`Enable acceleration y`	`bool`	`false`	`true/false`	Whether to enable the y-acceleration control channel
`Enable acceleration z`	`bool`	`false`	`true/false`	Whether to enable the z-acceleration control channel
`Enable yaw`	`bool`	`false`	`true/false`	Whether to enable the yaw angle control channel
`Enable yaw rate`	`bool`	`false`	`true/false`	Whether to enable the yaw rate control channel
`Auto arm`	`bool`	`false`	`true/false`	Whether to automatically send the UAV arming command
`Auto block PX4`	`bool`	`false`	`true/false`	Whether to automatically block the native PX4 controller output and enable Simulink controller output
`Auto Loiter`	`bool`	`true`	`true/false`	Whether to automatically switch PX4 to Loiter mode for hover when control is disabled
`Sample Time(s)`	`double`	`0.01`	`>0`	Module sampling time

Parameter Setting Descriptions¶

Control Channel Selection Parameters¶

Users can customize the selection of required Offboard control channels based on control needs. Enabled channels are arranged in a fixed order (x-position → y-position → z-position → x-velocity → y-velocity → z-velocity → x-acceleration → y-acceleration → z-acceleration → yaw angle → yaw rate) in the Ctrls[*] input ports. Unselected channels do not occupy input slots. Control commands use the NED coordinate system, with units conforming to the protocol; set corresponding inputs to NaN if a particular state is not to be controlled.

Auto arm¶

When this parameter is enabled, the module automatically sends an arming command to the target UAV when isEnCtrl is true, eliminating the need for users to handle arming logic separately.

Auto block PX4¶

When this parameter is enabled, the module automatically blocks the native PX4 controller output and uses Simulink-generated Offboard control commands to control the UAV when isEnCtrl is true, enabling external controller simulation and verification.

Auto Loiter¶

When this parameter is enabled, the module automatically releases the PX4 output block and switches the UAV to Loiter mode when isEnCtrl is false, allowing the UAV to automatically hover in place, thereby enhancing simulation safety. If disabled, the UAV will not automatically switch modes after Offboard control is disabled, and users must handle mode-switching logic themselves.

Sample Time(s)¶

Specifies the frequency at which the module sends Offboard control commands, in seconds. Typically set to 0.01, corresponding to a 100 Hz control frequency, matching the native PX4 Offboard control frequency.

Block Characteristics¶

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

Data Communication Protocol¶

This block communicates with the PX4 simulation firmware via the UDP protocol, adhering to the MAVLink Offboard control protocol. The input control signal format is described as follows:
All control inputs are based on the NED coordinate system. Valid ranges are: position x/y/z in meters (m), velocity vx/vy/vz in meters per second (m/s), acceleration ax/ay/az in meters per second squared (m/s²), yaw in radians (rad) (range: -π to π), and yaw rate in radians per second (rad/s). Setting an input value to NaN indicates that the corresponding state is not being controlled.

Block Name	Description
`OffboardCtrlAPI`	Base Offboard mode control block, providing fundamental control interfaces for position, velocity, and yaw.
`VehicleCmdAPI`	General-purpose drone command transmission block, capable of sending basic commands such as takeoff, landing, and mode switching.
`SetpointsGenerator`	Generates reference setpoints for drone flight trajectories and can serve as a control input source for this block.

Usage Example¶

For related 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: This module requires integration with the RflySim simulation environment for proper operation. It is essential to ensure that the PX4 flight controller completes power-on initialization before enabling the isEnCtrl input; otherwise, the Offboard mode transition will fail, and the vehicle will not respond to control commands. If the Auto arm feature is enabled, ensure the vehicle meets PX4 arming conditions (e.g., no critical fault warnings,处于 ground takeoff conditions) before asserting isEnCtrl; otherwise, arming will fail.
Input Command Consistency: When customizing control channels, maintain consistency in kinematic relationships. It is not recommended to simultaneously command position, velocity, and acceleration for the same state. If a channel does not require control, its corresponding input must be set to NaN; otherwise, abnormal control of that channel may cause flight instability or even crashes. All position commands follow the NED coordinate system definition, where the z-axis points downward as positive—opposite to the conventional ENU coordinate system. Coordinate transformation must be performed prior to input to avoid incorrect direction of position commands.
Sampling Time Matching: Offboard mode requires stable control command transmission frequency. It is recommended to set the module sampling time to no more than 0.1 s; excessive sampling time may cause PX4 to detect Offboard signal loss and automatically exit Offboard mode, switching to Loiter. The module’s sampling time must match the base sampling time of the Simulink model to prevent delayed command updates.
Mode Switching Safety: If the Auto Loiter feature is not enabled, disabling Offboard control by lowering isEnCtrl will not automatically switch to the safe Loiter mode. Users must manually handle the flight controller’s mode transition after disengagement; otherwise, vehicle loss of control may occur. If custom disengagement logic is used, it is recommended to incorporate fault protection logic to ensure the vehicle automatically enters hover or landing mode upon Offboard signal failure.
Auto block PX4 Usage Note: After enabling Auto block PX4, Offboard control fully takes over vehicle actuator outputs. Ensure the input control commands are valid and satisfy dynamic constraints; overly large commands may cause actuator saturation, leading to vehicle loss of control.
Unit and Range Verification: Yaw angle input range is -π ~ π; inputs outside this range will cause abnormal yaw control. All physical quantity inputs must use correct units: position in meters (m), velocity in meters per second (m/s), acceleration in meters per second squared (m/s²), angle in radians (rad), and angular velocity in radians per second (rad/s). Incorrect units will directly result in abnormal control performance.

Changelog¶

v4.10 (2024-08-07): Initial release. Supports advanced Offboard mode control with customizable channel selection. Includes Auto arm, Auto block PX4, and Auto Loiter features. Supports multiple control command inputs: position, velocity, acceleration, yaw angle, and yaw rate.