Skip to main content
Vision Navigation has three modes. Set the mode with the mode key in the plugin’s per-drone config (see Install and configure). The Vision Nav tab’s mode card is read-only: it lists the modes the agent can run and marks the active one. A config change restarts the plugin on the new mode.

​
The three modes

​
off

The default. The plugin stays loaded, reports its sensors and estimator state, and sends nothing. Turning the Engage Skill off has the same effect in any mode.

​
optical_flow

A Lucas-Kanade tracker on the downward camera, with the rangefinder for metric scale. This is the mode to fly at low height over textured ground. With the rangefinder wired to the companion, the plugin also forwards the reading as DISTANCE_SENSOR.

​
optical_flow_degraded

The same tracker, with scale from the scale ladder instead of a rangefinder. It drifts more than optical_flow, and the drift grows quickly above about 5 m. Use it when you can’t fit a rangefinder.

​
Pre-arm checks

Each check is ok, pending or blocking. The armable flag is true only when every check is ok; in off there are no checks.
The pre-arm card is advisory. The plugin reports armable and the check rows on its heartbeat, but it does not stop the flight controller from arming. Check that every row is green before you arm, and read Safety.

​
Scale source and fallback

In optical_flow_degraded the plugin takes scale from the first healthy rung of a ladder. Each rung multiplies the tracker’s quality, so the flight controller gives a weaker rung less weight. Distances are clamped to 0.3 to 50 m. GPS height is never taken from mean sea level, and it’s capped at 50 m above the first fix. On the static rung the estimator reports degraded whatever the raw quality, flow quality stays near 51/255 at most, and the scale_source pre-arm check blocks. In optical_flow the scale source is the rangefinder, shown as rangefinder.

​
When flow degrades

  • Low quality. When flow quality falls below flow_quality_min, the estimator reports degraded. The fallback banner on the Vision Nav tab appears as soon as the estimator reports degraded or failed, and suggests landing or switching the flight controller back to GPS with your RC source-set switch.
  • Sustained degradation. A degraded or failed streak of 2 s turns the companion CRITICAL: its HEARTBEAT reports MAV_STATE_CRITICAL.
  • No frames. If no camera frame arrives for 2 s, the estimator reports failed and the companion goes CRITICAL. No frames means nothing is sent, so the flight controller’s estimator times the flow source out.
The plugin does not switch the flight controller’s EKF source set. Keep an RC switch on the source-set option (see Flight controller setup) and use it, or land.

​
Next steps

Calibration

Optional camera-IMU time offset.

Flight controller setup

Parameters that fuse the flow.
Last modified on October 11, 2026