> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation: hardware

> Pick, mount and wire the downward camera and rangefinder that Navigation needs.

Both optical-flow modes need a **downward-facing camera**. The `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](https://docs.altnautica.com/drone-agent/multi-camera.md).

Set `camera.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:

| Topology | Driver | When to use it |
| - | - | - |
| `fc` (default) | `fc_relay` | The rangefinder is wired to the flight controller, which publishes `DISTANCE_SENSOR`. The plugin asks for that stream at 20 Hz and reads it. Works with any rangefinder the flight controller supports, including I2C sensors. |
| `companion` | `tfluna_uart` | A Benewake TF-Luna on a serial port of the companion computer. The plugin reads it at the configured baud (default 115200) and forwards it to the flight controller as `DISTANCE_SENSOR`. |
| `none` | n/a | No rangefinder. Use `optical_flow_degraded`. |

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 Navigation page.

## 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](https://docs.altnautica.com/drone-agent/navigation-optical-flow.md)).

## Wiring example

A typical layout on a companion board:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
USB or CSI port       -> downward camera
UART TX/RX            -> TF-Luna (companion topology only)
GND                   -> shared ground with the TF-Luna and the flight controller
UART to the FC        -> MAVLink link the agent already uses
```

The plugin needs the `hardware.uart` permission only for a companion-wired TF-Luna.

## Next steps

> [card] [Install](https://docs.altnautica.com/drone-agent/navigation-install.md)
>
> Install the extension and set its per-drone config.

> [card] [Overview](https://docs.altnautica.com/drone-agent/navigation-overview)
>
> What the extension does and which modes it has.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.