Skip to content

Configure

This guide walks through configuring a VOXL2 aircraft end to end, in the order you actually do it: from first contact over the aircraft's own LAN, through its network and autopilot wiring, onto your private network, bound to your GCS, and finally the navigation settings — then it hands you off to the mandatory pre-first-flight update.

Install gets the hardware powered, the software on the device, and the web app reachable. This guide picks up there and takes the aircraft from "reachable" to "configured and ready to update."

Configure first, then update, then fly

Configuration does not replace the mandatory update. Finish this guide, run the Mandatory Update, then fly — in that order.

Setting up the GCS is a separate guide

This guide configures the aircraft (VOXL2). Setting up your ground control station (GCS) — the application you bind to and fly from — has its own dedicated guide (a native Windows GCS application is on the roadmap; this page will link to it when it ships). The aircraft-side configuration below is the same regardless of how your GCS is run.

Before you start

  • The aircraft is powered and you have finished Install (the aircraft software is provisioned and the web app answers over the aircraft's LAN).
  • You have a laptop or tablet with a browser on the aircraft's LAN.
  • You have a Starlink dish with an active subscription for the aircraft's WAN.
  • You have an ArduPilot-based autopilot (Cube Orange+, Pixhawk 6X, or similar) wired to the aircraft for the MAVLink link.
  • Your GCS is set up and on a Tailscale or Headscale account you can sign in to.

One-time provisioning needs internet; flight does not

Joining the private network and binding happen once, with internet on both sides. After that the GCS↔aircraft command link runs over Starlink and your private network — there is no cloud dependency in flight.

1. Reach the aircraft over its LAN

A fresh aircraft is not on your private network yet, so you configure it from its own local web app over the aircraft's LAN.

  1. Connect your laptop or tablet to the aircraft's LAN (it serves DHCP, so you'll get an address automatically).
  2. Open https://192.168.2.1 in your browser.

The aircraft serves on standard HTTPS (https://, port 443). If you type a plain http://192.168.2.1, it redirects to HTTPS automatically.

First visit: trust the aircraft once (expected security warning)

The aircraft serves its web app over HTTPS with its own self-signed certificate, so the very first time your browser opens https://192.168.2.1 it shows a security warning. This is expected and safe on the local aircraft LAN — it just means the certificate is the aircraft's own. You tell the browser to trust this device once per machine; after that the app opens with no warning. The detailed per-browser steps are in the Install guide → "trust the aircraft once".

Expect the 'update required' banner on first boot

On first boot the aircraft shows a non-dismissible "update required before first flight" banner across the top of the app. This is expected — it clears on its own once you run the Mandatory Update (the last step of this guide). You can configure everything below with the banner showing.

Everything in steps 2–7 below is done from the aircraft's own web app, except binding (step 6), which you do from the GCS.

2. Configure the aircraft LAN

On a VOXL2 the aircraft is the router for its LAN — it serves DHCP, is the default gateway for anything connected to its LAN (your autopilot's companion computer, a payload, a laptop), and routes their traffic out through the Starlink uplink. The defaults work out of the box; adjust them here if your install needs different addressing.

Open the Settings tab and scroll to the LAN Settings card.

Configurable before you join the network or bind

The LAN Settings card is fully usable on the aircraft's own UI right now — before you sign in to the private network or bind to a GCS. Set the LAN up first, then move on.

Field What it does
LAN interface Which physical port joins the aircraft LAN. Both VOXL2 NICs are USB and swap names across reboots, so the selection is pinned by MAC address and survives reboots. The picker lists only real physical NICs (with a driver/MAC label and a no-carrier hint) and refuses the active WAN/Starlink port — you cannot accidentally bridge the uplink. "(none — bridge IP only)" is a valid choice.
Gateway IP This device's LAN address, handed to LAN clients as their default gateway. Must be a private (RFC 1918) address; the default is 192.168.2.1.
Subnet mask / prefix Standard mask for the LAN subnet.
DHCP server Enable or disable the built-in DHCP server for LAN devices (on by default).
DHCP range start / end Address pool for leases. Must sit inside the LAN subnet.
Lease time e.g. 12h (a number plus s / m / h / d).
Internet access on LAN Default on: LAN devices reach the internet via the Starlink uplink (NAT). Turn it off to isolate the LAN — the GCS↔aircraft bridge traffic is unaffected.

Save & Apply takes effect immediately, and the same settings are re-applied automatically at every boot. The Starlink dish stays reachable regardless of your LAN choices — the aircraft keeps a dedicated route to it (see the next step).

Manage the LAN from the ground too

Once you bind the aircraft (step 6), the same LAN Settings card appears on the GCS, so you can adjust the aircraft LAN from the ground without going back to the aircraft's local network.

The Starlink dish is the aircraft's WAN — its path to the internet and the source of the GPS positions tl-starnav forwards to your autopilot.

  1. Connect the Starlink dish to the aircraft's WAN port.
  2. Mount the dish with a clear view of the sky (no obstructions above ~25° elevation). It auto-orients — no manual aiming needed.
  3. Power the aircraft and confirm it reaches the internet through Starlink.

The aircraft automatically keeps a route to the dish's management/GPS address (192.168.100.1) out the WAN, even while Starlink hands it a carrier-grade NAT lease — so the dish's GPS feed (gRPC on 192.168.100.1:9200) stays reachable no matter how you configured the LAN above. You do not normally need to touch the dish address.

Internet now, not in flight

Internet through Starlink is needed for the one-time network sign-in and binding below, and for the mandatory update. The GCS↔aircraft command link in flight does not depend on any cloud service.

4. Wire the autopilot and set the ArduPilot parameters

tl-starnav forwards Starlink-derived position to ArduPilot as MAVLink External Nav position aiding. Two things make that work: a MAVLink connection between the autopilot and the aircraft, and a set of EKF source parameters on the autopilot.

  1. Connect the autopilot (or its companion computer) to the aircraft's LAN.
  2. On the autopilot, configure a MAVLink UDP output to the aircraft's LAN gateway address on port 14552 (the aircraft listens on udpin:0.0.0.0:14552 by default — see step 7 if you need to change it).

Set the ArduPilot EK3_SRC parameters

Set these on the autopilot (via Mission Planner / QGroundControl) so the EKF can use Starlink-derived position as a secondary source you switch to in flight:

Parameter Value Purpose
AHRS_EKF_TYPE 3 Use EKF3 (required for source switching).
EK3_SRC1_POSXY 3 (GPS) Primary horizontal position — onboard GPS.
EK3_SRC1_VELXY 3 (GPS) Primary horizontal velocity — onboard GPS.
EK3_SRC1_POSZ 1 (Baro) Primary altitude — barometer.
EK3_SRC2_POSXY 8 (ExtNav) Secondary horizontal position — Starlink via tl-starnav.
EK3_SRC2_VELXY 8 (ExtNav) Secondary horizontal velocity from external nav.
EK3_SRC2_POSZ 1 (Baro) Keep baro for altitude on both source sets.
EK3_EXTPOS_GATE 500 Acceptance gate (large = permissive) so Starlink-accuracy positions are accepted.

Assign an RC switch to select the source

Assign an unused RC channel to option 90 (EKF Source Select), so you can switch the active position source from the transmitter:

# Example: RC channel 7
RC7_OPTION = 90

# Switch positions:
#   Low  (PWM < 1300)  -> EK3_SRC1 (GPS)
#   Mid  (1300-1700)   -> EK3_SRC2 (ExtNav / Starnav)
#   High (PWM > 1700)  -> EK3_SRC3 (if configured)

In flight, flip to SRC2 when GPS is degraded or denied — the EKF begins fusing Starnav positions — and back to SRC1 when GPS is healthy again.

Verifying the source switch lives in the Operate guide

The in-flight verification — confirming the EKF actually switches to ExtNav and the position innovations are reasonable — is covered in the Operate guide. Set the parameters here; verify the switch there.

5. Join the private network (Tailscale / Headscale)

The aircraft connects to your GCS over a private network. You join it with the standard interactive sign-in — there is never a key to paste.

  1. Still on the aircraft's own web app (over its LAN), the "Connect this aircraft to Tailscale" popup appears while the aircraft has not yet joined.
  2. Click "Sign in to Tailscale →". Your browser opens the standard sign-in page in a new tab — sign in and approve the device exactly as you would when adding any machine.
  3. Once you approve, the aircraft joins automatically and reports its private-network address. The popup unlocks, and the bridge/transport dashboard panels and the Binding tab become available.

The login persists on the device, so the aircraft stays joined across reboots, container restarts, and image updates — you only do this once per aircraft.

Self-hosted control server (Headscale)

To use your organization's own Headscale control server instead of Tailscale SaaS, open "Advanced: control server" in the popup and enter its https:// URL before clicking the sign-in link. Switching control servers signs the device out first, then generates a fresh sign-in link for the new server. The appropriate relay configuration arrives automatically — no extra client settings needed.

Never paste a sign-in key

tl-starnav uses the interactive Tailscale / Headscale sign-in, not a key paste. If you are being asked to paste a key into the aircraft, you are off the supported path — use the "Sign in to Tailscale" link in the popup.

Make sure your GCS is signed in to the same Tailscale or Headscale network so the two can find each other in the next step.

6. Bind the aircraft to your GCS

Binding pairs the GCS with the aircraft, exchanges trust material, configures both sides, and brings up the bridge. You do this from the GCS (the aircraft must have joined the private network in step 5 first).

  1. In the GCS web app, open the Binding tab.
  2. Click Scan Network — the GCS discovers aircraft on your private network. Each appears with its name, address, and connection mode (direct peer-to-peer or relay).
  3. Find your aircraft and click Bind. Enter the aircraft's password if prompted (first time only).
  4. A setup window streams live progress and closes itself when the run finishes. When it completes, the bridge is up and the GCS Dashboard shows the aircraft as bound.

Re-running bind on a live link is safe — existing services are stopped and restarted cleanly, so you can re-bind without unbinding first. To switch aircraft, just bind a different one; the previous binding is replaced automatically.

Binding a VOXL2 is the same as any aircraft

From the operator's point of view, binding a VOXL2 is identical to binding any tl-starnav aircraft — the only visible difference is one line in the setup stream noting the aircraft platform.

7. Set the navigation (Starnav) options

Navigation is configured from the Settings tab. Because the GCS web app mirrors the aircraft once bound, you can do this from the GCS or from the aircraft's own UI — the same Settings cards appear on both. Changes are saved with Save & Restart, which writes the config and restarts the navigation service.

The defaults are tuned for Starlink and work out of the box. The options you are most likely to touch:

Setting Default What it does
External Position Estimate (Sending) On When on, tl-starnav forwards Starlink-derived position aiding to ArduPilot. Turn it off for ground testing — all other functions (dish polling, attitude stream, logging) keep running, and the EKF falls back to onboard GPS.
MAVLink Connection udpin:0.0.0.0:14552 Where tl-starnav listens for the autopilot MAVLink link. Match this to the output you configured in step 4.
Target System ID 2 The autopilot's MAVLink system ID.
Dish GPS Mode disable Controls the dish's own built-in GPS. disable is recommended so the dish's GPS does not conflict with the position aiding tl-starnav sends.

Under Advanced Settings you can also tune the quality thresholds and send rates (most operators leave these alone):

Setting Default What it does
Uncertainty Limit (m) 200 Maximum Starlink position uncertainty (99% confidence) the quality gate will accept before it stops sending.
Min Stable Time (s) 3 How long uncertainty must stay below the limit before sending starts.
Staleness Timeout (s) 3 After this long with an unchanged dish position, the state is flagged STALE (possible dish issue).
Send rates (active / passive / degraded) 0.5 / 1.0 / 2.0 s How often position aiding is sent in each state.

How tl-starnav decides what to send: \"always send, never lie, let the EKF decide\"

tl-starnav reports honest uncertainty and only forwards position aiding once the quality gate is satisfied — the uncertainty must stay below the limit for the minimum stable time. When uncertainty is too high it blocks (waits) rather than sending a position it cannot stand behind; if the dish position stops changing it reports stale. This is by design: sending an honest "I'm not confident" lets the autopilot's EKF do the right thing, instead of feeding it a falsely precise fix. You normally don't need to change these thresholds — the defaults reflect Starlink's accuracy.

8. Verify your configuration

On the GCS Dashboard (which mirrors the bound aircraft), confirm:

  • The aircraft shows as bound and online.
  • The bridge link is up and the transport state reads healthy (RTT and loss within range; brief spikes on Starlink handoffs are normal).
  • Navigation reports a position, and the Sending State card is in a sensible state (SENDING once the quality gate is satisfied; a transient BLOCKED while uncertainty settles is fine).
  • The aircraft's LAN Settings, navigation cards, and flight logs all appear on the GCS (confirming the mirror is working over the bridge).

Because the GCS web app mirrors the aircraft, navigation cards, flight logs, and the LAN settings card all appear on the GCS once bound.

Before-you-fly checks live in the Operate guide

The full pre-flight verification — confirming the EKF actually switches to ExtNav on your RC switch, checking innovations, and reading the in-flight dashboard — is in the Operate guide.

Next step

Do not fly before the mandatory update

Configuration is not the same as the required pre-first-flight update. The update brings your aircraft and GCS to a known-good, mutually compatible version — and it is required before your first flight.

Proceed to the Mandatory Update now. No credential or sign-in is needed — open the aircraft web app and click update, on a disarmed, safed airframe.