Skip to main content

​
Hardware

The camera direction depends on the mode:
  • Optical flow always needs a downward-facing camera plus a rangefinder that reports ground distance. The plugin can take the rangefinder from the FC (read by the FC, forwarded over MAVLink) when wiring directly to the companion is impractical.
  • VIO accepts either a forward-facing camera (indoor, corridor, inspection) or a downward-facing camera (over-ground: agriculture, survey, SAR, pipeline patrol). The wizard surfaces an explicit orientation picker; the agent suggests the direction that fits the active suite.
  • Hybrid uses both a downward camera (for optical flow) and a forward camera (for VIO).

​
Camera

Any camera that produces a 30 Hz grayscale or color frame at 320x240 or higher works for optical flow. The tracker downsamples to 320x240 internally, so higher resolutions waste CPU without gaining accuracy.

​
USB UVC

Plug-and-play. The agent’s vision host enumerates /dev/video* nodes and captures the camera; the plugin reads frames from the shared vision bus. Set the camera device path in the plugin’s config. Good picks:
  • Generic USB endoscope or borescope cameras (the kind sold for inspection work). Cheap, mechanically simple, often come with a fixed-focus lens around 60-90 degree FOV.
  • ArduCam or compatible USB UVC modules. M12 lens mounts let you swap the lens for the FOV you want.
  • Webcams with manual focus. Avoid autofocus-only models; the tracker doesn’t like the camera hunting mid-flight.

​
MIPI CSI

CSI cameras are higher quality at lower latency. They cost more in setup but pay off on platforms that have a CSI ISP (the Radxa boards, Raspberry Pi, RK3588S2, RK3576). Good picks:
  • Raspberry Pi Camera Module 3. Wide variant (120 degree FOV) is well-suited to downward optical flow.
  • ArduCam IMX477 or IMX219 modules. Both work on Pi and on Radxa with the right adapter cable.
  • Radxa CSI camera kits. Match the FFC cable pitch to the board (0.5mm vs 1.0mm; the wrong pitch destroys the connector).
The agent’s vision host captures a CSI camera through libcamera or v4l2. Select the camera (device path and kind) in the plugin’s config.

​
Lens FOV

Aim for 60 to 100 degrees diagonal. Narrow lenses (wider zoom) lose features at low altitude; ultra-wide lenses introduce distortion the tracker doesn’t model. The wide-FOV variants of common camera modules are usually a better starting point than the default narrow-FOV variants.

​
Rangefinder

Optical flow needs a height reference. On its own the tracker gives angular velocity (radians per second); a height measurement turns that into linear velocity (meters per second), which is what the EKF wants. The optical_flow mode requires a rangefinder; optical_flow_degraded runs without one by pulling scale from the FC’s altitude instead.

​
FC-relayed (default and universal)

If the rangefinder is wired to the FC (a common starting point for ArduPilot, PX4, or iNav setups), the plugin reads it via the DISTANCE_SENSOR MAVLink message the FC streams. No re-wiring required, and it works for any sensor the FC supports. Set the rangefinder topology to fc (driver fc_relay) and pick which orientation the FC reports as “down” (usually MAV_SENSOR_ROTATION_PITCH_270). For iNav, also set rangefinder_hardware = MSP or nav_rangefinder_for_terrain = ON per the iNav docs. The trade-off is latency: the rangefinder reading travels FC then MAVLink then plugin, adding 50 to 100 ms versus a companion-direct path. Acceptable for most use cases.

​
Companion-owned

The agent talks to the rangefinder directly over a companion bus. The Benewake TF-Luna over UART is the implemented companion-direct driver. The plugin’s manifest declares hardware.uart and hardware.i2c permissions; you grant them at install time. Wiring the TF-Luna is straightforward: 3.3V or 5V power per the datasheet, ground, and the UART pins to a free UART on the companion.

​
Mount placement

The downward camera mounts on the bottom plate of the airframe, lens pointing straight down, with a clear unobstructed view of the ground. A few guidelines:
  • Keep landing gear out of frame. Even thin gear strips appear as strong features and confuse the tracker.
  • Avoid props in frame. A prop guard or a recessed mount usually solves this.
  • Maintain a fixed pose. Foam or rubber mounts isolate vibration but introduce camera lag. A rigid mount is preferred for optical flow; reserve soft mounts for VIO where IMU fusion compensates.
  • Match the rangefinder pose. Mount the rangefinder pointing the same direction as the camera (straight down). Cross-axis offset doesn’t matter at altitude but does matter close to the ground.

​
Ground clearance

The plugin needs the rangefinder reading to fall inside its valid range. ArduPilot’s flow fusion clamps below RNGFND1_MIN_CM and above RNGFND1_MAX_CM; outside those bounds the flow source goes unhealthy.
  • TF-Luna: arm and fly at 0.3 m or higher; the bottom 0.2 m is unreliable.
  • ST VL53L1X: arm at 0.1 m or higher; ceiling at 3 m even though the datasheet says 4 m (signal-to-noise drops sharply).
  • Garmin LIDAR-Lite: arm at 0.1 m or higher; the long ceiling makes it the most forgiving of the three.
Auto-takeoff with vision navigation typically starts from a stationary ground clearance of 0.15 m (props spinning, vehicle on the ground). The plugin reports rangefinder health to Mission Control’s Navigation tab; arm only when that reports OK.

​
Wiring quick reference

A typical setup on a Radxa ROCK 5C Lite:
Wire an I2C rangefinder (VL53L1X, LIDAR-Lite v3) to the flight controller and read it over the FC relay; the companion-direct I2C drivers are not available yet. On a Raspberry Pi 5 the layout is similar (the CSI port speaks to a Pi Camera Module, UART4 on pins 8/10, I2C-1 on pins 3/5). The plugin checks the requested bus is free at install time and refuses to grant hardware.uart or hardware.i2c if another plugin or service already owns the bus.

​
What’s next

Once the hardware is mounted and wired, head to Install on a drone to load the plugin, then Configure optical flow to pick the camera and rangefinder drivers and set the right FC parameters.