> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation: modes and fallback

> The four Navigation modes, their pre-arm checks, the scale ladder and what happens when flow degrades.

Navigation has four modes. Set the mode with the `mode` key in the plugin's per-drone config (see [Install and configure](https://docs.altnautica.com/drone-agent/navigation-install.md#set-the-per-drone-config)). The Navigation page's mode card is read-only: it lists the modes the agent can run and marks the active one. A config change restarts the plugin on the new mode.

## The four modes

| Mode | Input | Rangefinder | Sends to the flight controller |
| - | - | - | - |
| `off` | optional | optional | nothing |
| `optical_flow` | downward camera | required | flow on component 198, scaled by the rangefinder |
| `optical_flow_degraded` | downward camera | not needed | flow on component 198, scaled by the scale ladder |
| `external_nav` | a shared pose topic (for example a planar LiDAR SLAM) | on the flight controller, for height | `ODOMETRY` on component 197, EKF source-set switching, and optionally `OBSTACLE_DISTANCE` |

### `off`

The default. The plugin stays loaded, reports its sensors and estimator state, and sends nothing. Turning the **Engage** Skill off has the same effect in any mode.

### `optical_flow`

A Lucas-Kanade tracker on the downward camera, with the rangefinder for metric scale. This is the mode to fly at low height over textured ground. With the rangefinder wired to the companion, the plugin also forwards the reading as `DISTANCE_SENSOR`.

### `optical_flow_degraded`

The same tracker, with scale from the scale ladder instead of a rangefinder. It drifts more than `optical_flow`, and the drift grows quickly above about 5 m. Use it when you can't fit a rangefinder.

### `external_nav`

ArduPilot only. A pose another plugin publishes is sent as `ODOMETRY`, and the plugin switches the EKF source set between the external pose and a fallback set as tracking comes and goes. An optional obstacle feed turns a planar scan into `OBSTACLE_DISTANCE`. Its configuration, switching rules and pre-arm checks are on [External nav and obstacles](https://docs.altnautica.com/drone-agent/navigation-external-nav.md).

## Pre-arm checks

The flow modes run these checks. `external_nav` runs its own set: `extnav_source`, `extnav_health`, `ekf_origin`, `fc_params`, `viso_delay` and, with the obstacle feed on, `obstacle_feed` (see [External nav pre-arm checks](https://docs.altnautica.com/drone-agent/navigation-external-nav.md#pre-arm-checks)).

| Check | Card row | `off` | `optical_flow` | `optical_flow_degraded` |
| - | - | - | - | - |
| `companion_active` | Companion process active | n/a | yes | yes |
| `flow_quality` | Optical flow quality | n/a | at or above `flow_quality_min` (default 50) | at or above `flow_quality_min` (default 50) |
| `rangefinder` | Rangefinder healthy | n/a | a fresh reading inside the sensor's range | n/a |
| `scale_source` | Altitude scale source | n/a | n/a | a live height source; the static fallback blocks |

Each check is `ok`, `pending` or `blocking`. The `armable` flag is true only when every check is `ok`; in `off` there are no checks.

> [!WARNING]
>
> The pre-arm card is advisory. The plugin reports `armable` and the check rows on its heartbeat, but it does not stop the flight controller from arming. Check that every row is green before you arm, and read [Safety](https://docs.altnautica.com/operations/safety.md).

## Scale source and fallback

In `optical_flow_degraded` the plugin takes scale from the first healthy rung of a ladder. Each rung multiplies the tracker's quality, so the flight controller gives a weaker rung less weight.

| Rung | Source | Quality multiplier | Shown as |
| - | - | - | - |
| 1 | `GLOBAL_POSITION_INT.relative_alt`, no older than 2 s | ×0.7 | `baro` |
| 2 | `VFR_HUD.alt` minus the take-off altitude, no older than 2 s | ×0.6 | `baro` |
| 3 | GPS height above the first good 3D fix, only with `outdoor: true`, a 3D fix and `GPS_RAW_INT.eph` of 200 or less | ×0.4 | `gps` |
| 4 | Static 1.5 m fallback | ×0.2 | `static` |

Distances are clamped to 0.3 to 50 m. GPS height is never taken from mean sea level, and it's capped at 50 m above the first fix.

On the static rung the estimator reports `degraded` whatever the raw quality, flow quality stays near 51/255 at most, and the `scale_source` pre-arm check blocks. In `optical_flow` the scale source is the rangefinder, shown as `rangefinder`.

## When flow degrades

* **Low quality.** When flow quality falls below `flow_quality_min`, the estimator reports `degraded`. The fallback banner on the Navigation page appears as soon as the estimator reports `degraded` or `failed`, and suggests landing or switching the flight controller back to GPS with your RC source-set switch.
* **Sustained degradation.** A `degraded` or `failed` streak of 2 s turns the companion `CRITICAL`: its `HEARTBEAT` reports `MAV_STATE_CRITICAL`.
* **No frames.** If no camera frame arrives for 2 s, the estimator reports `failed` and the companion goes `CRITICAL`. No frames means nothing is sent, so the flight controller's estimator times the flow source out.

In the flow modes the plugin does not switch the flight controller's EKF source set. Keep an RC switch on the source-set option (see [Flight controller setup](https://docs.altnautica.com/drone-agent/navigation-optical-flow.md#a-way-back-to-gps)) and use it, or land. In `external_nav` the plugin switches the set itself; see [Source-set switching](https://docs.altnautica.com/drone-agent/navigation-external-nav.md#source-set-switching).

## Next steps

> [card] [Calibration](https://docs.altnautica.com/drone-agent/navigation-calibration.md)
>
> Optional camera-IMU time offset.

> [card] [Flight controller setup](https://docs.altnautica.com/drone-agent/navigation-optical-flow.md)
>
> Parameters that fuse the flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.