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.

​

Visual Inertial Odometry

Visual Inertial Odometry (VIO) is the bigger sibling of optical flow. Where optical flow gives you horizontal velocity from a downward camera plus a rangefinder, VIO gives you a full 6-degree-of-freedom pose (position and orientation in three dimensions) from a forward-facing camera fused with the FC’s IMU.

​

What it adds

Optical flow tells the EKF “the drone is moving north at 2.1 m/s.” VIO tells the EKF “the drone is at (12.3, 4.7, 1.8) meters from the origin, rolled 2 degrees, pitched 5 degrees, yawed 18 degrees, and moving at (1.4, 1.0, 0.0) m/s.” The richer state lets the FC do things optical flow can’t:

• Fly at altitudes where the rangefinder can’t see the ground (above 10 m on most sensors).
• Follow corridors and tunnels where the downward camera has nothing to track.
• Maintain heading-relative position over long flights without GPS or compass drift.
• Land on uneven terrain by combining VIO altitude with the IMU’s gravity vector.

The trade-off is compute. A monocular VIO at 30 Hz on a 640x480 camera needs an NPU or a strong CPU. The plugin’s VIO mode will refuse to enable on boards that don’t have one.

​

Two engines, side by side

The plugin ships two VIO modes:

• vio_openvins uses OpenVINS, a filter-based (MSCKF) estimator. Lower CPU cost, strong on fast motion, slightly looser bound on long-flight drift.
• vio_vins_fusion uses HKUST VINS-Fusion, a sliding-window bundle-adjustment estimator. Higher CPU cost, tighter drift bound in feature-rich scenes, stronger in low-feature or texture-poor environments.

OpenVINS is the default. VINS-Fusion is the advanced option for boards with the headroom.

​

Hardware requirements

The plugin’s VIO modes target a monocular forward-facing camera plus the FC IMU. Stereo and full-SLAM (loop-closure) engines are not in the first VIO release; the architecture leaves the seam open. Camera: a forward-facing global-shutter camera at 30 Hz, 640x480 or higher. A rolling-shutter camera works but is more sensitive to fast motion. Global shutter is strongly preferred. IMU: the FC’s IMU, sampled through MAVLink. The plugin prefers SCALED_IMU2 (100 Hz on ArduPilot) and falls back to RAW_IMU (50 to 200 Hz depending on FC config). A higher-rate direct IMU path (I2C or DroneCAN) is a later option.

​

How it plugs in

The VIO engine runs as a vendor binary inside the plugin’s process sandbox, started by the plugin and watched by a heartbeat watchdog. Frames flow into the binary through a shared-memory ring (zero-copy); IMU samples and control messages flow through a Unix-domain socket encoded as length-prefixed msgpack. Pose estimates flow back over the same socket. The plugin then emits VISION_POSITION_ESTIMATE on MAVLink component 197 (MAV_COMP_ID_VISUAL_INERTIAL_ODOMETRY) at 30 Hz. ArduPilot’s EKF3 fuses these messages when EK3_SRC1_POSXY, EK3_SRC1_VELXY, and EK3_SRC1_YAW are set to ExternalNav (6). PX4’s EKF2 fuses them when EKF2_EV_CTRL enables external vision. The IPC protocol is documented in the Architecture page. Adding a third engine (ORB-SLAM3, a future home-grown estimator) is a single subclass of the shim’s engine base class plus a new vendor binary that speaks the same protocol.

​

Calibration

VIO needs calibrated intrinsics and known camera-IMU extrinsics including the static time offset between the two clocks. The plugin accepts Kalibr-compatible camchain.yaml files directly. See Calibration for the full workflow. The pre-arm gate refuses to arm a VIO mode without loaded calibration files. The GCS sensors card surfaces a Calibrate CTA when intrinsics are not yet loaded.

​

GPL §6 compliance

Both OpenVINS and VINS-Fusion are GPL-3.0-licensed. Shipping a pre-compiled binary inside the plugin archive triggers the GPL source-offer obligation. The plugin’s manifest declares a vendor_attribution block for each engine with the upstream repository, the license, the upstream version, and a notice. The install dialog surfaces these blocks during Stage 1 so operators know what they’re installing. The Python plumbing, the GCS surfaces, the pre-arm gate, the estimator card, and the fallback banner all ship today. The vendor binaries land in a follow-up release once they’re validated end-to-end on target hardware.

​

What you can do today

The optical flow release covers the most common indoor and low-altitude GPS-denied use cases. If you’re flying close to the ground (under 8 m), have a downward camera, and need stable hover and waypoint flight, optical flow is enough. See Configure optical flow for the setup. If you’re flying at altitude, in long corridors, or in environments where the downward camera has nothing to track, the optical flow release won’t be sufficient and you’ll want to wait for the VIO release.

​

Stay in the loop

Releases are announced through the standard channels:

• The ADOS Extensions GitHub repository’s release feed.
• The Mission Control update notifier (in-app banner when a new plugin version is published).
• Community channels listed in Open source.

The VIO release date isn’t promised. It lands when it’s validated end-to-end on target hardware, not before.