> For the complete documentation index, see [llms.txt](https://docs.auterion.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auterion.com/app-development/auterion-sdk/vtol-api.md).

# VTOL API

{% hint style="info" %}
Requires APX4 3.3 or newer
{% endhint %}

{% hint style="info" %}
Related C++ Header in the Auteroin SDK:

`<auterion_sdk/control/vtol/vtol.hpp>`
{% endhint %}

Auterion SDK provides an interface to command a VTOL transition.

## Commanding a transition

Instantiate an `auterion::VTOL` object by passing your `auterion::SDK` instance:

```cpp
auterion::VTOL vtol(*sdk);
```

You can set the desired target state by means of the `set_target_state(auterion::VtolState target_state)` method. For example, if you want to be in fixed-wing mode:

```cpp
vtol.seTargetState(auterion::FIXED_WING); 
```

This will check whether the current state is different than fixed wing, and command a transition if needed.

## Setpoint types when working with VTOLs

{% hint style="warning" %}
During a VTOL transition, use the `auterion::vtol::TransitionSetpoint` .
{% endhint %}

When writing external flight modes using the VTOL API, the right setpoint types need to be returned before, during and after the transition. Meaning:

* When flying as a multicopter, the setpoint type used needs to be compatible with the PX4 multicopter control architecture.
* When flying as a fixed-wing, the setpoint type needs to be compatible with the PX4 fixed wing control architecture.

See the [setpoint types available here.](/app-development/auterion-sdk/flight-mode-api.md) (Note: when a setpoint type is not part of either the multicopter or fixed-wing namespace, it is compatible with both vehicle types).\
\
**During transition,** you should return the `auterion::vtol::TransitionSetpoint` type. This ensures that PX4 receives all the necessary inputs to successfully complete the transition. You can optionally supply a course input to this setpoint. This will realign the vehicle during transition if required.

### Set up mode

In order to prepare your flight mode to accept `TransitionSetpoint`, you need to supply the `auterion::vtol::TransitionSetpoint::Config` object to your mode constructor. Make sure to also pass the objects required for fixed-wing and multicopter control like so:

```cpp
auterion::Mode my_mode(sdk, "My Mode", {
    auterion::vtol::TransitionSetpoint::Config{},
    auterion::fixedwing::DynamicsSetpoint::Config{}, 
    auterion::multicopter::LocalFrameDynamicsSetpoint::Config{}
});
```

### Create setpoint

To create a setpoint, you can use the builder pattern like so:

```cpp
// assuming we have an instance of an auterion::SystemState object called _system_state; 

if ((_system_state.vtolState().last() == auterion::VtolState::TRANSITION_TO_MULTICOPTER) || 
     _system_state.vtolState().last() == auterion::VtolState::TRANSITION_TO_FIXED_WING){
     
     auto setpoint = auterion::vtol::TransitionSetpoint{} 
    .withCourse(course_sp); 
    }
```

Optionally, you can send a deceleration setpoint during the back-transition:

```cpp
auto setpoint = auterion::vtol::TransitionSetpoint{}
.withCourse(course_sp)
.withBackTransitionDeceleration(deceleration_sp); 
```

If no deceleration setpoint is set, a default value of 2 m/s^2 is used.

The SDK will ensure that the required inputs are sent to PX4 for a smooth transition. To ensure the drone follows your setpoints, return these setpoints in the `onUpdateSetpoint` callback method of your mode.

{% hint style="info" %}
You can query the `VtolState` through the `SystemState`API for the current state of the vehicle. See documentation on that [here](/app-development/auterion-sdk/system-state-api.md).
{% endhint %}