> ## 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: flight controller setup

> Set the ArduPilot, PX4 or iNav parameters that fuse Navigation's optical flow, set the EKF origin, and run the pre-flight checks.

Navigation sends an optical-flow measurement. The flight controller decides whether to fuse it, so its parameters must accept flow on MAVLink and use it for horizontal velocity. Set them in Mission Control's [parameter editor](https://docs.altnautica.com/mission-control/parameters.md) or your usual ground station.

The Navigation page shows a read-only parameter card for the firmware set in `firmware.type`. It lists the parameters that matter; it does not write them.

> [!WARNING]
>
> Test every change on the ground and in a low hover first, with a way back to GPS. Read [Safety](https://docs.altnautica.com/operations/safety.md) before you fly.

## ArduPilot

ArduPilot receives `OPTICAL_FLOW` (#100) with the raw angular rate in the `flow_rate_x` and `flow_rate_y` fields. It uses those fields once it sees a non-zero value and subtracts its own gyro.

| Parameter | Set to | Why |
| - | - | - |
| `FLOW_TYPE` | `5` | Accept optical flow over MAVLink. |
| `FLOW_ORIENT_YAW` | mount yaw | Camera yaw offset, in centidegrees. `0` when the camera's top faces the nose. |
| `FLOW_FXSCALER`, `FLOW_FYSCALER` | `0` | Scale trims. Leave at `0` unless flow speed reads consistently high or low. |
| `EK3_SRCn_VELXY` | `5` | Optical flow as the horizontal velocity source in the source set you fly on flow. |
| `EK3_SRCn_POSXY` | `0` | No horizontal position source in that set. |
| `EK3_SRCn_POSZ` | `1` or `2` | Barometer (`1`) or rangefinder (`2`) for height. |
| `EK3_SRCn_YAW` | `1` | Compass for yaw. Flow does not measure yaw. |
| `EK3_SRC_OPTIONS` | as needed | Source-set options, for example fusing all velocity sources. |
| `EK3_FLOW_DELAY` | start at `10` | Flow latency in milliseconds. Raise it in 5 ms steps if the drone oscillates in Loiter. |
| `RNGFND1_TYPE` | per sensor | Your rangefinder's type. Use `10` (MAVLink) when the TF-Luna is wired to the companion and the plugin forwards `DISTANCE_SENSOR`. |
| `RNGFND1_ORIENT` | `25` | Rangefinder pointing down. |

Set the rangefinder's minimum and maximum distance parameters to the sensor's range, so the flight controller ignores readings outside it.

### A way back to GPS

Fly flow on its own EKF source set (for example source set 2, with set 1 on GPS). Assign an RC switch to the EKF source-set option (`RCx_OPTION = 90`) so you can return to GPS from the transmitter. Mission Control and the extension do not switch source sets for you.

## PX4

PX4 receives `OPTICAL_FLOW_RAD` (#106): the angle the ground swept over the interval and the gyro rotation over the same interval.

| Parameter | Set to | Why |
| - | - | - |
| `EKF2_OF_CTRL` | `1` | Fuse optical flow (PX4 1.14 and newer). |
| `EKF2_OF_DELAY` | tune | Latency from sample to the estimator, in milliseconds. |
| `EKF2_OF_QMIN` | low value | Minimum flow quality the estimator accepts. |
| `EKF2_OF_POS_X`, `EKF2_OF_POS_Y`, `EKF2_OF_POS_Z` | mount offset | Camera position relative to the IMU, in metres. |
| `EKF2_HGT_REF` | baro or range | Primary height source. |
| `SENS_FLOW_MINHGT`, `SENS_FLOW_MAXHGT` | sensor range | Heights at which flow is trusted. |
| `SENS_FLOW_MAXR` | sensor limit | Maximum angular flow rate the estimator trusts, in rad/s. |

Reboot the flight controller after changing `EKF2_*` parameters. The PX4 card on the Navigation page shows `EKF2_OF_CTRL`, and `EKF2_AID_MASK` for releases before 1.14, only when the flight controller reports them.

## iNav

iNav 7.0 and newer receives `OPTICAL_FLOW` (#100), the same as ArduPilot.

| Parameter | Set to | Why |
| - | - | - |
| `opflow_hardware` | `MAVLINK` | Read optical flow from the MAVLink port. |
| `nav_use_optflow_for_poshold` | `ON` | Use flow for position hold without GPS. |
| `rangefinder_hardware` | your sensor | Flow needs a height reference. |

In iNav's Ports tab, enable MAVLink on the UART that connects to the companion, then reboot the flight controller. The iNav card on the Navigation page lists the related parameters (`opflow_scale`, `nav_extra_arming_safety`, `nav_landing_speed`, `nav_rangefinder_for_terrain`) as a reference.

## Betaflight

Betaflight has no position estimator, so it cannot use optical flow. The plugin's firmware setting offers only ArduPilot, PX4 and iNav. To fly GPS-denied on the same hardware, flash iNav or ArduPilot.

## Set the EKF origin

Without GPS the flight controller has no origin for its local position frame, and ArduPilot reports `AHRS waiting for home`. The extension does not set the origin. Set it before you arm: in Mission Control, right-click the map at the take-off point and choose **Set EKF Origin**. Mission Control sends `SET_GPS_GLOBAL_ORIGIN` with the terrain height at that point; the flight controller does not acknowledge it, so confirm the message clears.

## Pre-flight checks

The Navigation page's **Pre-arm** card shows the extension's checks:

* **Companion process active**
* **Optical flow quality** at or above `flow_quality_min` (default 50)
* **Rangefinder healthy** (`optical_flow`): a fresh reading inside the sensor's range
* **Altitude scale source** (`optical_flow_degraded`): a live height source, not the static fallback

The card is advisory. The plugin reports an `armable` flag and per-check rows, but it does not stop the flight controller from arming. Check that every row is green, that the **Distance** on the Sensors card matches the real height, and that the flight controller's own pre-arm checks pass. Then arm.

## Tuning

* **Flow quality gate.** Feature-poor ground (smooth concrete, snow, water) gives low quality. Lower `flow_quality_min` in the plugin config only for testing over a safe area; below about 20 the tracker reports noise.
* **Latency.** If the drone oscillates in Loiter, tune `EK3_FLOW_DELAY` (ArduPilot) or `EKF2_OF_DELAY` (PX4). The plugin does not measure flow latency.
* **Yaw.** Flow does not measure yaw. Calibrate the compass well.
* **First hops.** Start between 1 and 3 m. Lower is close to the rangefinder's floor; higher has fewer features in view.

## Next steps

> [card] [Modes and fallback](https://docs.altnautica.com/drone-agent/navigation-modes.md)
>
> What each mode checks and how scale falls back.

> [card] [Install](https://docs.altnautica.com/drone-agent/navigation-install.md)
>
> The plugin config keys.


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