Skip to main content
Start with the Vision Nav tab: the estimator state, flow quality, flow rate, the scale source and the pre-arm rows usually point at the problem. Then read the plugin log on the drone:
The plugin’s output goes to its own log file under /var/log/ados/plugins/, not to the journal. ados plugin logs finds the file for you.

​
Low optical-flow quality

Symptom: Flow quality on the Flow health card is below the gate (default 50), or the estimator reports degraded.
  1. Light. The tracker needs both frames bright enough to find corners. Add light, or lower the camera frame rate so each frame gets more exposure. Mono global-shutter sensors cope better in low light.
  2. Texture. Snow, water, fresh asphalt and sand have few features. Fly over textured ground. For testing over a safe area you can lower flow_quality_min in the plugin config; the flight controller still rejects bad samples itself.
  3. Yaw rate. Fast yaw moves features out of view between frames. Slow the yaw, raise the frame rate or use a wider lens.
  4. Motion blur. Fast horizontal flight with long exposure blurs corners. Shorten exposure or slow down.

​
No frames

Symptom: Flow rate on the Flow health card drops to 0 and the estimator reports failed. After 2 s without a frame the plugin marks the estimator failed and the companion CRITICAL, and it sends no flow. The flight controller’s estimator then times the flow source out. Land, or switch back to GPS with your RC source-set switch. On the ground, check that the agent’s vision host still captures the downward camera (see Multi-camera) and look for camera errors in the agent’s video logs.

​
Scale source confusion

Symptom: in optical_flow_degraded the speed the flight controller computes is off by a large factor.
  1. Which rung is active? The Sensors card shows the scale source:
    • rangefinder: a rangefinder reading is in use.
    • baro: GLOBAL_POSITION_INT.relative_alt or VFR_HUD.alt minus take-off.
    • gps: GPS height above the first 3D fix (only with outdoor: true).
    • static: no live height source; the plugin is on the 1.5 m fallback. The estimator is degraded and the Altitude scale source pre-arm row blocks.
  2. Barometer drift. Indoor barometers drift, prop wash makes it worse, and air handling can move the reading by 1 to 2 m. Shield the barometer with foam and wait about 30 s after entering the space before you arm.
  3. GPS indoors. If outdoor is on indoors, GPS height has no physical meaning. Turn outdoor off when you fly indoors.
  4. Static fallback. Fix the height source before you fly. optical_flow_degraded on the static rung is not fit for flight.

​
Rangefinder row blocks

Symptom: the Rangefinder healthy pre-arm row is red in optical_flow.
  • “No fresh rangefinder reading.”: no reading in the last 200 ms. For fc_relay, check that the flight controller publishes DISTANCE_SENSOR. For tfluna_uart, check the device path, the baud rate and the wiring; an open failure also shows as rangefinderError.
  • “Rangefinder reading … outside …”: the drone is below the sensor’s minimum or above its maximum range.
  • “Rangefinder required in this mode.”: the topology is none. Set a topology, or switch the mode to optical_flow_degraded.

​
Config rejected: camera orientation

Symptom: the plugin runs but stays disengaged in an optical-flow mode. Both optical-flow modes need camera.orientation set to downward or auto. A forward or side orientation is rejected and leaves vision navigation disengaged. An unknown mode name does the same. Fix the key in the plugin config; the plugin restarts on the change.

​
Do I need a rangefinder?

For optical_flow, yes: it is the scale source, and the pre-arm check expects a fresh reading. For optical_flow_degraded, no: scale comes from the flight controller’s height, with more drift, especially above about 5 m.

​
Night flight

Optical flow needs visible texture on the ground. In the dark it works only as well as the camera sees: add a downward light, or use an IR-sensitive camera with an IR illuminator, and test before you rely on it.

​
Where do I file a bug?

Open an issue on the ADOSExtensions repository with:
  • the plugin log, from ados plugin logs com.altnautica.vision-nav --lines 500 (the file is /var/log/ados/plugins/com-altnautica-vision-nav-<hash>.log);
  • the output of systemctl status 'ados-plugin-com-altnautica-vision-nav-*';
  • the flight controller log covering the problem;
  • the plugin config (GET /api/plugins/com.altnautica.vision-nav/config).
For problems outside the extension, see Troubleshooting by area.

​
Next steps

Architecture

How the agent half is built.

Modes and fallback

Pre-arm checks and the scale ladder.
Last modified on October 11, 2026