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

# Vision Navigation Overview

> GPS-denied drone navigation with six modes: optical flow (with or without a rangefinder), monocular VIO via two engines, or a hybrid of both.

# Vision Navigation

Vision Navigation lets a drone fly position-controlled missions without GPS. The companion computer reads a camera and the FC's IMU, derives motion, and feeds that motion into the flight controller's state estimator. The result is stable hover, smooth waypoint flight, and gentle landings indoors, under canopy, in canyons, or anywhere the sky view is poor.

<Note>
  Vision Navigation ships as a first-party plugin in the ADOS extensions catalog. You install it on a single drone from Mission Control's per-drone Plugins tab. Installation is described in [Install on a drone](/drone-agent/vision-nav-install).
</Note>

## Six modes, one plugin

The plugin runs one of six estimator modes, selectable at runtime from Mission Control's mode picker:

* **`off`**. Sensors discovered, no MAVLink emission. Useful for hardware diagnostics and calibration runs.
* **`optical_flow`**. Downward camera plus a rangefinder. The default GPS-denied path for low-altitude hover.
* **`optical_flow_degraded`**. Same tracker, but the scale comes from a baro, GPS, or static fallback ladder instead of a rangefinder. Reduced accuracy; the GCS marks it as degraded.
* **`vio_openvins`**. Monocular visual-inertial odometry via OpenVINS. A forward or downward camera plus FC IMU. Best fit for low-cost NPU boards.
* **`vio_vins_fusion`**. Same role, using VINS-Fusion as the engine. Higher CPU cost than OpenVINS; preferred on RK3582 or RK3588S2 boards. Accepts either a forward camera (indoor / corridor) or a downward camera (over-ground).
* **`hybrid_of_plus_vio`**. Both estimators running on separate cameras: a downward camera feeds optical flow and a forward camera feeds VIO. The EKF fuses both inputs.

## VIO direction is a choice

Optical flow is always downward. VIO is not. Both forward and downward cameras work with the same VIO engines; the right pick depends on the mission profile.

* **Forward camera**. Indoor flight, corridor inspection, urban canyon, warehouse aisles. Forward translation through the scene gives the estimator rich depth parallax. Default for indoor inspection suites.
* **Downward camera**. Over-ground low-altitude flight: agriculture spray, survey grid, search and rescue, pipeline patrol. Ground texture is dense and reliable, and scale ambiguity is easier to resolve when the camera is staring at a near-flat plane. Default for over-ground suites.

The wizard surfaces an explicit orientation picker under any VIO mode. The agent suggests the orientation that matches the active suite; the operator confirms.

See [Modes](/drone-agent/vision-nav-modes) for the full per-mode breakdown including pre-arm check matrix and fallback ladder.

## How it works

The agent reads the active camera at 30 frames per second, pairs each frame with the closest IMU sample, and runs the selected estimator. Optical-flow estimators emit `OPTICAL_FLOW_RAD` on MAVLink component 198 at the camera frame rate (around 30 Hz). VIO estimators emit `VISION_POSITION_ESTIMATE` on MAVLink component 197 at the same rate. ArduPilot's EKF3 or PX4's EKF2 fuses the matching source set when configured.

<Note>
  All six modes ship. The optical-flow modes (`optical_flow`, `optical_flow_degraded`) run on light hardware. The VIO modes (`vio_openvins`, `vio_vins_fusion`, `hybrid_of_plus_vio`) run the bundled OpenVINS or VINS-Fusion engines, need a one-time camera-IMU calibration, and want a board with an NPU or a strong multicore CPU. See [Visual Inertial Odometry](/drone-agent/vision-nav-vio).
</Note>

## Hardware and configuration

The plugin reads frames from the agent's shared vision bus. The
agent's vision host owns the camera; the plugin subscribes to the
normalized frame stream rather than opening a device itself. The mode,
the camera orientation, the rangefinder topology and driver, and the
firmware target are per-drone config fields you set in Mission
Control:

* **Camera.** The configured camera feeds the agent's vision host
  (USB UVC or CSI via V4L2). The plugin consumes the resulting frames.
* **Rangefinder.** The default and universal path is the FC relay:
  the flight controller already publishes `DISTANCE_SENSOR` and the
  plugin reads it (no extra wiring). A companion-direct Benewake
  TF-Luna over UART is also supported. I2C sensors (LIDAR-Lite,
  VL53L1X) wire to the FC and ride the relay path.
* **IMU.** The plugin reads the FC's IMU over MAVLink `RAW_IMU`, the
  universal path every FC publishes. A higher-rate direct-I2C path is
  a planned addition.

Vision Navigation is a drone-side plugin: it needs an FC MAVLink
channel and a flight-side camera, neither of which a ground station
has.

## Supported firmware

| Firmware                              | Optical Flow         | VIO                   |
| ------------------------------------- | -------------------- | --------------------- |
| ArduPilot 4.5+ (Copter, Plane, Rover) | Yes                  | Yes                   |
| PX4 1.14+                             | Yes                  | Yes                   |
| iNav 7.0+                             | Yes (via MAVLink rx) | No (disabled on iNav) |
| Betaflight                            | No                   | No                    |

The plugin auto-detects which firmware the FC is running and tunes its MAVLink output accordingly. ArduPilot and PX4 consume `OPTICAL_FLOW_RAD` natively. iNav consumes the same message when the FC's serial port is configured as MAVLink rx and `opflow_hardware` is set to `MAVLINK`. The plugin's iNav setup notes list every parameter; see [Optical flow](/drone-agent/vision-nav-optical-flow).

### Why Betaflight is not supported

Betaflight is a flight controller designed for racing and freestyle, not autonomous position-hold. It does not ship a position estimator. Optical flow needs a consumer inside the FC's EKF; without one, there is nothing to fuse the flow samples into. This is an upstream firmware decision, not a limitation we can work around from the companion. Operators who need GPS-denied flight on a small board should run iNav or ArduPilot Copter on the same hardware. Most STM32F405 / F722 / H743 boards run all three firmwares.

### iNav: optical flow yes, VIO not supported

iNav 7.0 and newer accepts MAVLink-injected optical flow via `opflow_hardware = MAVLINK`, drives position hold via `nav_use_optflow_for_poshold = ON`, and can fuse a rangefinder for terrain-following. The plugin emits the same `OPTICAL_FLOW_RAD` message it sends to ArduPilot and PX4. The plugin disables VIO modes on iNav: config validation rejects `vio_openvins`, `vio_vins_fusion`, and `hybrid_of_plus_vio` on an iNav FC because iNav's external position-injection path is not as mature as ArduPilot EKF3's `VISION_POSITION_ESTIMATE` fusion. Operators who want VIO on a small FC should cross-flash ArduPilot Copter.

## Supported boards

Optical flow runs on any board with enough CPU headroom for a 320x240 grayscale tracker at 30 Hz plus a USB or CSI camera. In practice:

| Board                             | Optical Flow      | VIO              |
| --------------------------------- | ----------------- | ---------------- |
| Radxa ROCK 5C Lite (RK3582)       | Yes               | Yes              |
| Radxa CM4 (RK3588S2)              | Yes               | Yes              |
| Rockchip RK3576                   | Yes               | Yes              |
| Raspberry Pi 5 (BCM2712)          | Yes               | Yes              |
| Raspberry Pi CM5 (BCM2712)        | Yes               | Yes              |
| Raspberry Pi CM4 (BCM2711)        | Yes               | Limited (no NPU) |
| Raspberry Pi 4B (BCM2711)         | Yes               | Limited (no NPU) |
| Raspberry Pi Zero 2 W (BCM2710A1) | Yes (tier-1 only) | No               |

The plugin reads the active HAL board profile and refuses to enable on boards that don't meet the minimum. See [Hardware](/drone-agent/vision-nav-hardware) for camera and rangefinder picks.

## How it sits in the stack

```
flight controller (UART)            USB / CSI camera
        |                                  |
   ados-mavlink                       ados-vision (vision host)
   (FC heartbeat, IMU,                     |
    DISTANCE_SENSOR relay)            shared vision frame bus
        \                                  /
         \                                /
          ados-supervisor + ados-plugin-host
                        |
                vision-nav (this plugin) --> TF-Luna over UART (optional)
```

The plugin lives inside the agent's plugin sandbox, talks to the FC through the MAVLink router, reads frames from the shared vision bus, and registers MAVLink components 198 (optical flow) and 197 (VIO) on the vehicle bus. Mission Control sees the live estimator state, flow rate, and quality through a per-drone Navigation tab on the drone detail panel.

## Next steps

* [Hardware: cameras and rangefinders](/drone-agent/vision-nav-hardware)
* [Install on a drone](/drone-agent/vision-nav-install)
* [Modes](/drone-agent/vision-nav-modes)
* [Configure optical flow](/drone-agent/vision-nav-optical-flow)
* [Calibration](/drone-agent/vision-nav-calibration)
* [Troubleshooting](/drone-agent/vision-nav-troubleshooting)
* [Visual Inertial Odometry](/drone-agent/vision-nav-vio)
* [Architecture](/drone-agent/vision-nav-architecture) (developer reference)