> ## 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 overview

> GPS-denied navigation: optical flow from a downward camera fed to ArduPilot, PX4 or iNav, or an external pose such as a planar LiDAR SLAM sent to ArduPilot with source-set switching and an obstacle feed.

Navigation is a first-party extension, `com.altnautica.navigation`. It lets a drone hold position when GPS is weak or missing: indoors, under a bridge, between tall buildings. A downward camera tracks the ground, the flight controller's gyro removes the drone's own rotation, and the result reaches the flight controller as an optical-flow measurement about 30 times a second. Position hold, loiter and missions then keep working through the flight controller's own estimator.

In its flow modes the extension does optical flow only: it does not estimate a full pose and does not run visual-inertial odometry. In `external_nav` mode it estimates nothing itself either: it forwards a pose another plugin publishes (for example a planar LiDAR SLAM) to ArduPilot as `ODOMETRY`, switches the EKF source set as tracking comes and goes, and can turn a planar scan into `OBSTACLE_DISTANCE`.

![Mission Control Navigation page with the mode card, sensors, flow health and pre-arm checks for a drone in optical flow mode](https://mintcdn.com/altnautica/DjEFYospgraFUH15/images/extensions/navigation/navigation-page.png?fit=max\&auto=format\&n=DjEFYospgraFUH15\&q=85\&s=a5026ae33c0a9a1448dfda05451c44b6)

The Navigation page on a drone in optical\_flow mode.

## What it is for

Two flights cover what the extension is built for.

* **GPS-denied hover with a rangefinder.** A downward camera plus a rangefinder at low height over textured ground. The rangefinder gives the metric scale, so this is the most accurate setup. Use the `optical_flow` mode.
* **GPS-denied hover without a rangefinder.** The same camera, with scale taken from the flight controller's barometric height instead. It drifts more, and above about 5 m the drift grows quickly. Use the `optical_flow_degraded` mode.

Accuracy depends on the surface, the light, the camera and the airframe. The extension publishes no drift figures; test on your own aircraft before you rely on it.

## Modes

| Mode | What it does |
| - | - |
| `off` | The plugin stays loaded and reports sensor health, but sends nothing to the flight controller. This is the default. |
| `optical_flow` | Downward camera plus a rangefinder. The pre-arm checks expect a fresh rangefinder reading. |
| `optical_flow_degraded` | Downward camera, no rangefinder needed. Scale comes from the flight controller's height, and from GPS height when `outdoor` is on. |
| `external_nav` | ArduPilot only. A shared pose topic sent as `ODOMETRY` on component 197, with EKF source-set switching and an optional planar-scan obstacle feed. See [External nav and obstacles](https://docs.altnautica.com/drone-agent/navigation-external-nav.md). |

The mode is a per-drone config key, not a picker in the Navigation page. See [Modes and fallback](https://docs.altnautica.com/drone-agent/navigation-modes.md).

## How the flow modes work

1. **Capture.** The agent's vision host captures the camera and publishes frames on the shared vision frame bus. The plugin never opens the camera itself.
2. **Flow.** Each new frame is paired with the previous one and with the gyro sample taken at the same instant (from the flight controller's `RAW_IMU`, which the plugin asks for at 100 Hz). A Lucas-Kanade tracker measures how far the ground moved.
3. **Scale.** The rangefinder, or the scale ladder in `optical_flow_degraded`, gives the distance to the ground.
4. **Emit.** The plugin sends the measurement to the flight controller on MAVLink component 198. The message depends on the firmware set in the plugin config:

   * ArduPilot and iNav get `OPTICAL_FLOW` (#100) with the raw angular rate in the `flow_rate_x` and `flow_rate_y` extension fields.
   * PX4 gets `OPTICAL_FLOW_RAD` (#106) with the angle swept over the interval and the gyro rotation over the same interval.

   An unknown distance is sent as `-1`. When the rangefinder is wired to the companion, the plugin also sends `DISTANCE_SENSOR` (#132). It keeps a `TIMESYNC` exchange and a 1 Hz companion `HEARTBEAT` running on the same component.
5. **Report.** Once a second the plugin publishes a `navigation` block on the agent heartbeat: mode, estimator state, flow quality and rate, scale source, sync offset and the pre-arm report. The Navigation page in Mission Control renders it.

The plugin checks itself on every frame. If flow quality drops below the gate, the estimator reports `degraded`; a degraded or failed streak of 2 s turns the companion `CRITICAL`. If no frame arrives for 2 s, the estimator reports `failed` and the companion goes `CRITICAL`. Losing frames or getting them back publishes the `navigation` block at once, so the Navigation page shows the change without waiting for the next 1 s publish.

## Supported hardware and firmware

* **Companion boards:** the boards in the extension's manifest, listed in the [Extensions catalog](https://docs.altnautica.com/drone-agent/extensions-catalog.md#navigation). The agent refuses the install on any other board.
* **Flight controllers:** ArduPilot 4.5 and newer, PX4 1.14 and newer, iNav 7.0 and newer. Betaflight has no position estimator, so it can't use optical flow.
* **Cameras:** a downward USB UVC or CSI camera (global or rolling shutter).
* **Rangefinders:** a TF-Luna on a companion serial port, or any rangefinder the flight controller already publishes as `DISTANCE_SENSOR`.

Details and wiring are on [Hardware](https://docs.altnautica.com/drone-agent/navigation-hardware.md).

## Version requirements

The extension needs Drone Agent 0.99.125 or newer and Mission Control 0.56.0 or newer.

## Next steps

> [card] [Hardware](https://docs.altnautica.com/drone-agent/navigation-hardware.md)
>
> Pick and mount the camera and rangefinder.

> [card] [Install](https://docs.altnautica.com/drone-agent/navigation-install.md)
>
> Install and configure the extension on one drone.


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