Skip to main content

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

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

​
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 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 10 Hz. VIO estimators emit VISION_POSITION_ESTIMATE on MAVLink component 197 at 30 Hz. ArduPilot’s EKF3 or PX4’s EKF2 fuses the matching source set when configured.
Optical flow modes (optical_flow, optical_flow_degraded) are runtime-complete. VIO modes are in development: the Python plumbing, the GCS surfaces, the auto-detect probe, and the build pipeline for the vendor binaries ship today. The vendor-binary upstream integration lands in a follow-up release once it’s validated end-to-end on target hardware. See Visual Inertial Odometry.

​
Hardware auto-detect

The plugin probes the host at start-up and adapts to whatever hardware it finds. On a fresh drone the operator does not need to touch the config:
  • Cameras are enumerated from /dev/video* with a CSI hint when a media controller is present. The wizard picks the right node for the selected mode (downward UVC for OF, CSI for VIO).
  • Rangefinders are probed on every I2C bus for LIDAR-Lite (0x62) and VL53L1X (0x29). The TF-Luna is probed on the standard UART nodes at 115200 baud.
  • IMU sources prefer a direct-I2C BMI088 at ~400 Hz when the bus answers a chip-id handshake, falling back to MAVLink RAW_IMU at the FC’s stream rate when no direct path is present.
  • The detected hardware combination drives a suggestedMode field on the heartbeat. Mission Control’s ModeCard renders a Suggested badge on the mode the agent recommends.
  • If optical_flow is selected but no rangefinder answers the probe, the plugin auto-flips to optical_flow_degraded and logs the flip so the operator sees what happened.
The plugin refuses to enable on ground-station-profile hosts. Vision Navigation is drone-only; a ground station does not have an FC MAVLink channel or a flight-side camera.

​
Supported firmware

FirmwareOptical FlowVIO
ArduPilot 4.5+ (Copter, Plane, Rover)YesYes
PX4 1.14+YesYes
iNav 7.0+Yes (via MAVLink rx)Experimental
BetaflightNoNo
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.

​
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 experimental

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. VIO support on iNav is experimental: iNav has external position-injection hooks but the EKF integration is not as polished as ArduPilot EKF3’s VISION_POSITION_ESTIMATE path, so the plugin disables VIO modes on iNav at install time. 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:
BoardOptical FlowVIO (roadmap)
Radxa ROCK 5C Lite (RK3582)YesYes
Radxa CM4 (RK3588S2)YesYes
Rockchip RK3576YesYes
Raspberry Pi 5 (BCM2712)YesYes
Raspberry Pi CM5 (BCM2712)YesYes
Raspberry Pi CM4 (BCM2711)YesLimited (no NPU)
Raspberry Pi 4B (BCM2711)YesLimited (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 for camera and rangefinder picks.

​
How it sits in the stack

flight controller (UART)
        |
    ados-mavlink  <-- (FC heartbeat, IMU, ATTITUDE, DISTANCE_SENSOR relay)
        |
   ados-supervisor
        |
   ados-plugin-host
        |
   ados-vision-nav (this plugin)
   /             \
USB/CSI camera   UART or I2C rangefinder
The plugin lives inside the agent’s plugin sandbox, talks to the FC through the MAVLink router, and registers itself as MAVLink component 198 on the vehicle bus. Mission Control sees the live optical flow rate and quality through a per-drone Navigation tab on the drone detail panel.

​
Next steps