optical_flow mode also needs a rangefinder pointing down; optical_flow_degraded runs without one.
Camera
The plugin does not open a camera. The agent’s vision host captures it and publishes frames on the shared vision frame bus, and the plugin reads those frames. Pick the camera the vision host captures in the agent’s camera settings; see Multi-camera. Setcamera.orientation in the plugin config to downward or leave it at auto. A forward or side orientation in an optical-flow mode is rejected: the plugin starts disengaged and sends nothing.
Frames wider than 640 px are tracked at half resolution, so a 640x480 stream is a good fit. More resolution costs CPU without helping the tracker.
USB UVC
USB UVC cameras work without drivers. Global-shutter mono modules give the cleanest flow; rolling-shutter modules work too. Avoid autofocus-only webcams: a lens that hunts mid-flight breaks tracking.MIPI CSI
CSI cameras exposed through V4L2 work on boards with a CSI port. Match the ribbon cable pitch to the board connector before you plug it in.Lens field of view
Aim for about 60 to 100 degrees diagonal. A narrow lens sees few features at low height. A very wide lens adds distortion the tracker does not model.Rangefinder
On its own the tracker measures angular motion. A distance to the ground turns that into speed. Two sources are supported:
The plugin has no I2C drivers. Wire an I2C rangefinder to the flight controller and use
fc_relay.
A reading counts as fresh for 200 ms. The optical_flow pre-arm check needs a fresh reading inside the sensor’s own minimum and maximum range (0.2 to 8 m for the TF-Luna; the range the flight controller reports for fc_relay). If the TF-Luna port can’t be opened, the plugin retries every 2 s and reports the error as rangefinderError on the Vision Nav tab.
Mount placement
- Point the camera straight down from the bottom plate with a clear view of the ground.
- Keep landing gear and props out of the frame. They show up as strong features that do not move with the ground.
- Mount rigidly. Flow tracking prefers a stiff mount over a soft one.
- Point the rangefinder the same way as the camera, close to it.
Ground clearance
Take off and fly above the rangefinder’s minimum range. For the TF-Luna that means 0.3 m or more, because readings below about 0.2 m are unreliable. The flight controller also ignores flow outside its own height limits, so set those to match the sensor (see Flight controller setup).Wiring example
A typical layout on a companion board:hardware.uart permission only for a companion-wired TF-Luna.
Next steps
Install
Install the extension and set its per-drone config.
Overview
What the extension does and which modes it has.