Vision Navigation: install and configure

Vision Navigation installs on one drone at a time. Each drone keeps its own permission grants and its own per-drone config, and the plugin runs only on the agent of the drone you picked.

Before you start

Choose a mode. optical_flow if the drone has a downward rangefinder, optical_flow_degraded if it doesn’t. See Modes and fallback.
Mount and wire the hardware. A downward camera, plus the rangefinder for optical_flow. See Hardware.
Check the versions. The drone runs Drone Agent 0.99.125 or newer (check with ados version) and you use Mission Control 0.56.0 or newer.
Check the board. The drone’s board must be in the extension’s board list on the Extensions catalog.

Install from Mission Control

Open the drone, go to Agent, and under Software click Extensions. A drone with nothing installed shows “No extensions installed on this drone yet.”
Pick the source:
- From the registry. Find ADOS Vision Navigation in the list of available extensions and click Install. The drone fetches the signed archive itself, so this needs a LAN path from Mission Control to the drone.
- From a file. Click Install extension on this drone (or Install from file) and choose a downloaded .adosplug. Mission Control sends it over the LAN when it can reach the drone, and through the cloud relay when it can’t.
Read the review page. It shows the description, compatibility, the permissions, the flight controller parameters the extension expects, the publisher and signer, and the resource impact.
Click Install. The button names how many permissions the install grants.

Mission Control install review page for ADOS Vision Navigation with its permissions, details and the Install button that grants 11 permissions — The install review for Vision Navigation.

Progress runs Uploading, Queued, Commanded, Downloading, Verifying, Installing, Enabling, Completed over the cloud relay. A LAN install skips the first four and runs Verifying, Installing, Enabling, Completed. The extension is high risk because it writes MAVLink that the flight controller fuses for position hold. It requests these permissions: Permissions

event.publish
hardware.uart
mavlink.component.vio
mavlink.read
mavlink.write
telemetry.extend
telemetry.subscribe.navigation
ui.slot.flight-skill
ui.slot.node-detail-tab
vision.frame.read

Boards: cm4, cm5, rock-5c-lite, rk3588s2, rk3576, rpi5 If the drone is armed, Mission Control asks you to confirm before it installs, enables, disables or removes an extension.

Install from the agent CLI

On the drone, install the signed archive from its release URL or a local file:

ados plugin install https://github.com/altnautica/ADOSExtensions/releases/download/<tag>/<file>.adosplug
# or
ados plugin install ./<file>.adosplug

The CLI prints the plugin id, version, risk and the requested permissions, then asks once to approve them. Because the extension is high risk, --yes refuses it; approve it interactively. See Extensions on the agent.

Set the per-drone config

A fresh install starts in mode off and sends nothing to the flight controller. Write the config through the agent’s plugin config route. On the drone itself no key is needed:

BASE=http://127.0.0.1:8080/api/plugins/com.altnautica.vision-nav/config

curl -X PUT -H "Content-Type: application/json" $BASE \
  -d '{"key": "mode", "value": "optical_flow"}'
curl -X PUT -H "Content-Type: application/json" $BASE \
  -d '{"key": "firmware", "value": {"type": "ardupilot"}}'
curl -X PUT -H "Content-Type: application/json" $BASE \
  -d '{"key": "rangefinder", "value": {"topology": "fc", "driver": "fc_relay"}}'

curl -s $BASE

From another machine on the LAN, send the same requests to http://192.168.1.50:8080/... with -H "X-ADOS-Key: $ADOS_KEY". An object value such as rangefinder replaces the whole object, so send every field you want to keep.

Key	Default	Meaning
`mode`	`off`	`off`, `optical_flow` or `optical_flow_degraded`.
`active`	`true`	Written by the Engage Skill. `false` idles the plugin: nothing is sent to the flight controller.
`flow_quality_min`	`50`	Flow quality gate, 0 to 255. Below it the estimator reports `degraded` and the flow pre-arm check blocks.
`outdoor`	`false`	Allows the GPS height rung in `optical_flow_degraded`, measured from the first good 3D fix. Leave it off indoors.
`firmware.type`	`ardupilot`	`ardupilot`, `px4` or `inav`. Picks the flow message (`OPTICAL_FLOW` for ArduPilot and iNav, `OPTICAL_FLOW_RAD` for PX4) and the parameter card on the Vision Nav tab.
`rangefinder.topology`	`fc`	`fc`, `companion` or `none`.
`rangefinder.driver`	`fc_relay`	`fc_relay` or `tfluna_uart`.
`rangefinder.device`	none	Serial device for the TF-Luna, for example `/dev/ttyUSB0`.
`rangefinder.baud`	`115200`	TF-Luna baud rate.
`camera.orientation`	`auto`	`downward` or `auto` for both optical-flow modes. `forward` or `side` is rejected and leaves the plugin disengaged.
`camera.device_path`	`/dev/video0`	Reported to the Vision Nav tab as the recommended camera. It does not select the camera; the plugin reads whatever the vision host captures.
`camera.bus_type`	`uvc`	`uvc` or `csi`.
`camera.width`, `camera.height`, `camera.fps`	`640`, `480`, `30`	The expected stream. Frames come from the vision bus at the size the vision host captures.

The plugin checks its stored config once a second. When a value changes, it exits and its unit restarts it on the new config within a few seconds. A config naming an unknown mode or a sideways camera in an optical-flow mode is rejected, and the plugin runs disengaged.

Enable the extension

On the extension’s row on the drone’s Extensions page, click Enable. Within a few seconds a Vision Nav tab appears on the drone. Configure on the same row opens the extension’s detail page (overview, permissions and events). Uninstall is in the row’s menu. The Engage Skill (default key Shift+N) turns vision navigation on and off from the cockpit. It asks for confirmation before it engages, and writes active in the per-drone config.

Engaging Vision Navigation changes how the flight controller estimates position. Read Safety before you fly.

What you have now

The plugin runs as its own sandboxed unit on the drone, with up to 512 MB RAM, 80% of a CPU core and 24 processes.
In an optical-flow mode it sends flow to the flight controller at the camera frame rate once frames and a scale source are available.
The Vision Nav tab shows the mode, the sensors, the estimator state, flow health and the pre-arm checks.

Uninstall

Click Uninstall in the extension row’s menu. The drone stops the plugin, removes it and clears its data on that drone, and the flight controller stops receiving flow. From the CLI, ados plugin remove com.altnautica.vision-nav does the same; add --keep-data to keep the data directory (and any camchain.yaml).

If the install fails

“Not compatible with this drone’s board” or “Requires agent v…”: the drone’s board or agent version does not match the manifest. Upgrade the agent or use a supported board.
Stuck at Downloading: the drone can’t reach the release URL. Check its outbound HTTPS.
Fails at Verifying: the signature does not verify against a trusted key, or the signer is revoked. Download the archive again from the release page.
The tab stays empty after enabling: the plugin sees no frames. Check that the vision host captures the downward camera, then read the plugin log with ados plugin logs com.altnautica.vision-nav.

Use extensions

Extension guides

Vision Navigation: install and configure

Before you start

Install from Mission Control

Install from the agent CLI

Set the per-drone config

Enable the extension

What you have now

Uninstall

If the install fails

Next steps

Flight controller setup

Hardware

​Before you start

​Install from Mission Control

​Install from the agent CLI

​Set the per-drone config

​Enable the extension

​What you have now

​Uninstall

​If the install fails

​Next steps

Flight controller setup

Hardware

Before you start

Install from Mission Control

Install from the agent CLI

Set the per-drone config

Enable the extension

What you have now

Uninstall

If the install fails

Next steps