# Visual Fixed-Wing Landing

## Introduction

Visual Fixed-wing Landing (FWL) is an AuterionOS application designed for precision landings at a specified location. The application supports two operational modes: landing at a global position (GPS coordinates), or navigating to a landing point using a Line-of-Sight (LOS) rate vector received from the tracking-service app. 

Visual Fixed-wing landing operates as an [external PX4 flight mode](https://docs.px4.io/main/en/concept/flight_modes#internal-vs-external-modes), allowing it to be engaged or disengaged from the AMC ground control station. Upon activation, if neither a landing position nor an LOS rate vector is available, the application will level the aircraft and enter a standby state, waiting for the LOS rate vector to be received. Once the LOS rate vector becomes available, the app will guide the vehicle based on that vector.

## Required inputs

The FWL app primarily consumes a LOS and LOS rate vector - published by the tracking service app, or generated internally when GPS landing is enabled.

From PX4, the app requires the following: 

#### **Required** 

* **Attitude** - PX4 mode requirement. If `attitude_invalid`, PX4 will deactivate the mode
* **Angular velocity -** PX4 mode requirement. If `angular_velocity_invalid`, PX4 will deactivate the mode. 
* **Local position relaxed -** PX4 mode requirement. If `local_position_invalid_relaxed`, PX4 will deactivate the mode. 
* **Filtered accelerometer data** - checked internally by the app.  Supplied by the `VehicleAcceleration.msg`.  If absent or stale, the app returns a safe setpoint until restored. The safe setpoint commands a height rate and a lateral acceleration: 
  * If manual control input is available, the pitch stick maps to height rate and the roll stick to lateral acceleration.
  * Otherwise, the app commands zero height rate and zero lateral acceleration to keep the vehicle level at the current altitude and heading. 

#### **Optional** 

* **Airspeed measurements** - if absent or zero/non-finite, the airspeed controller is disabled and thrust is fixed at 50%. 
* **Manual control input** - used exclusively to populate the safe setpoint. If the app falls back to the safe setpoint (e.g. due to missing accelerometer data), the pilot's pitch stick maps to height rate and roll stick to lateral acceleration. If manual input is also absent, the safe setpoint commands level flight.
* **Local position** - used to hold altitude before the landing approach, and to trigger flare if enabled. 

## Guidance State Machine 

The guidance logic runs as a state machine with three sequential phases. 

**1. Heading alignment**

The initial phase, entered when the mode is activated. If the vehicle is not facing the landing point, the vehicle aligns it's heading while holding altitude. 

**2. Midcourse**

The vehicle enters midcourse guidance, holding altitude while flying towards the landing location. If the approach angle (`FWL_APR_FLT_ANG`) is set to zero, this phase is skipped and the vehicle transitions directly to approach.  

**3. Approach**

The vehicle follows the LOS vector downward to the landing point. This phase persists until landing or mode deactivation.<br>

## Bank-to-turn vs. Skid-to-turn

**Bank-to-Turn** (BTT) is the standard and most efficient way for fixed-wing aircraft to turn. It involves rolling (banking) the aircraft to tilt the wing's lift, creating a horizontal turning force, while the rudder is used to coordinate the turn. BTT is used as the default turning method.&#x20;

**Skid-to-Turn** (STT) uses the rudder to create a sideslip angle, causing the vehicle to skid laterally and change its course without additional bank angle. It allows for wings-level turns, beneficial for video tracking from onboard cameras and for vehicles with high yaw authority. Using only STT requires large vertical surfaces to generate enough lateral acceleration. STT is disabled by default.&#x20;

Visual Fixed-wing Landing allows the use of a mixed BTT and STT approach, enabling control through both skidding and banking. The amount of side acceleration allocated to STT before the vehicle would start to bank can be adjusted using  `FWL_MAX_SIDE_ACC`. The optimal ratio is dependent on the vehicle's ability to skid-to-turn, which can be assessed in flight by attempting yaw-only turns (e.g., maintaining level flight in altitude mode with full yaw stick deflection).

{% hint style="warning" %}
For APX4 versions older than v3.3.3,  `FW_ACRO_YAW_EN` needs to be enabled to allow yaw rate control when the app is active.
{% endhint %}

To enable STT:

* Set `FWL_SF_R_I_GAIN` to 0.&#x20;
* Set `FWL_MAX_SIDE_ACC` to the maximum lateral acceleration you want to generate through STT. Beyond this, the vehicle will BTT.&#x20;
* Tune the lateral acceleration loop: `FWL_ACC_Y_GAIN_P, FWL_ACC_Y_GAIN_I`&#x20;

## Global approach

To tune the application or test the accuracy, it’s possible to set a global landing location using GPS coordinates. To enable GPS-based landing:

1. Disable visual tracking input (`FWL_TRCK_VISUAL: false`) and enable global coordinates landing (`FWL_VIRT_APR_GLB: true`)
2. Set global landing location with parameters `FWL_VIRT_APR_MSL, FWL_VIRT_APR_LAT and FWL_VIRT_APR_LON`.
3. Restart the FWL app.

The vehicle will then approach the global landing location. **It is the pilot's responsibility to abort the approach.**

## Flare

The flare is the phase of flight where the vehicle slightly raises the nose of the aircraft just before touchdown. This maneuver transitions the aircraft from a descent to a level or slightly nose-up attitude, reducing the rate of descent. Flare is disabled by default and can be enabled by setting the `FWL_FLR_LAND` parameter accordingly. The desired pitch angle and transition pitch rate are defined by `FWL_FLR_PITCH` and `FWL_FLR_PRATE` parameters.

## Tuning Guide

The tuning guide relies on the `autotune.py` script that can be found [here](http://github.com/Auterion/Flight_Control_Prototyping_Scripts/tree/master/autotune).

The tuning procedure consists of tuning several control loops in the following order:

<table><thead><tr><th width="50.09375">Step</th><th width="131.4296875">Control loop</th><th>Tuning maneuver</th><th>Autotune script input/output</th><th width="202.5703125">Parameters and notes</th></tr></thead><tbody><tr><td>1</td><td><strong>PX4 Autopilot rate controller</strong></td><td>Tune the PX4 rate controller first. Keep the response smooth. Minimize overshoot and steady-state error.</td><td>Input: <code>vehicle_torque_setpoint/</code><br>Output: <code>vehicle_angular_velocity</code></td><td>For rate controller tuning guidance, refer to <a href="https://docs.px4.io/main/en/config_fw/pid_tuning_guide_fixedwing">PX4 documentation</a> or watch <a href="https://www.youtube.com/watch?v=UQgSk45MXP0">this video</a>.</td></tr><tr><td>2</td><td><strong>Airspeed</strong> </td><td>Perform manual throttle changes while cruising level.</td><td>Input: <code>vehicle_thrust_setpoint/xyz[0].0</code><br>Output: <code>airspeed_validated/true_airspeed_m_s.0</code></td><td>Write the obtained values to <code>FWL_ASPD_GAIN_P</code> and <code>FWL_ASPD_GAIN_I</code>.</td></tr><tr><td>3</td><td><strong>Vertical Acceleration</strong> </td><td>Perform manual sine wave sweeps on the pitch axis while flying in Stabilized mode.</td><td>Input: <code>vehicle_rates_setpoint/pitch.0</code><br>Output: <code>vehicle_acceleration/xyz[2].0</code></td><td>Write the obtained values to <code>FWL_ACC_Z_GAIN_P</code> and <code>FWL_ACC_Z_GAIN_P</code>.</td></tr><tr><td>4</td><td><strong>Roll</strong> </td><td>Perform manual sine wave sweeps on the roll axis while flying in Stabilized.</td><td>Input: <code>vehicle_rates_setpoint/roll.0</code><br>Output: <code>vehicle_acceleration/xyz[1].0</code></td><td>Write the obtained values to <code>FWL_ROLL_GAIN</code> and <code>FWL_SF_R_I_GAIN</code>.</td></tr><tr><td>5</td><td><strong>Lateral Acceleration</strong> </td><td>Perform manual sine wave sweeps on the yaw axis while flying in Stabilized. Then try a full yaw turn by deflecting the yaw stick to one side and waiting.</td><td>Input: <code>vehicle_rates_setpoint/yaw.0</code><br>Output: <code>vehicle_acceleration/xyz[1].0</code></td><td>Write the obtained values to <code>FWL_ACC_Z_GAIN_P</code> and <code>FWL_ACC_Z_GAIN_I</code>. Check the log file for the maximum side acceleration at <code>vehicle_acceleration/xyz[1].0</code>, then write that value to <code>FWL_MAX_SIDE_ACC</code> with some margin.</td></tr></tbody></table>

## Pitch Limitation&#x20;

The app can actively limit the vehicle pitch rate to keep the tracked object within the camera's vertical field of view. To enable the pitch limiter, the following camera parameters must be set:

* `FWL_P_LIM_VFOV` - Camera sensor vertical FOV in which the tracked object should remain. Vertical FOV of the camera sensor. The limiter constrains pitch rate to keep the tracked object within this field of view. Set to 0 or less to disable.
* `FWL_CAM_TILT` - Camera mounting tilt angle relative to the vehicle body (positive = pitched up). Used to correctly offset the FOV boundaries when the camera is not forward-facing.

For a visual representation of the pitch limitation configuration, refer to the image in the [MC Follow](/vehicle-operation/dragon-setup/dragon-sr/mc-follow.md) documentation.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.auterion.com/vehicle-operation/dragon-setup/dragon-mr-lr/visual-fixed-wing-landing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.