Skip to main content

​
WFB Pairing

WFB-ng pairing in ADOS is local-first by design. A drone and a ground station that boot near each other for the first time pair automatically over the local radio, no internet required. The cloud relay is a secondary path that takes over when local pairing isn’t possible. This page covers the pairing protocol. For the radio link itself (channel, FEC, antennas), see WFB-ng.

​
Why local-first

A radio link is a local thing. The pair key only needs to be known by the two endpoints that share air time. Routing pairing through a cloud round-trip adds latency, points of failure, and an internet dependency the radio link itself does not have. The agent generates and exchanges the WFB pair key on the local radio whenever it can. The cloud relay learns about the pair after the fact and uses it for the higher-level fleet-management features (status, command queues, video relay), not for the link itself.

​
First-boot auto-bind

A fresh drone agent and a fresh ground agent that come online on overlapping channels go through this sequence without any operator action:
1

Key generation

The first node to come up runs wfb_keygen and produces a libsodium keypair. The keys are written to the local pair store under /etc/ados/wfb/ (mode 0600): the drone keeps tx.key, the ground station keeps rx.key.
2

Local advertisement

The node advertises a pair offer over the configured WFB channel. The advertisement carries the key and a role tag (drone or ground station).
3

Adoption

An unpaired peer that sees the advertisement and matches the complementary role adopts the matching key. It writes its half into /etc/ados/wfb/ locally and confirms back over the radio.
4

Bind complete

Both nodes flip from unpaired to paired in their state. WFB-ng RX and TX start with the shared key. Video and MAVLink flow.
The whole sequence runs in seconds on hardware that’s already up. From the operator’s perspective, the OLED or LCD goes from “waiting for pair” to “linked” without anyone touching a setup webapp.

​
The auto-pair supervisor

Auto-bind is driven by an auto-pair routine inside the Rust ados-supervisor. The supervisor owns the bind orchestrator and always runs, which makes it the right host: the radio service must not be the thing that restarts the radio, otherwise a pairing-driven service restart would tear down the very channel it is trying to bind. The supervisor sits above the radio and orchestrates the bind without owning the link. It is armed by default (video.wfb.auto_pair_enabled). The supervisor watches:
  • Pair-store state (paired / unpaired).
  • Radio carrier state from the WFB service.
  • Pair-offer messages on the air.
It writes:
  • The shared key into the pair store on adoption or generation.
  • A pair-confirmation event that lights up the OLED, the LCD, and the cloud heartbeat.

​
Role-aware key handling

Drone profile and ground-station profile each handle the key set with role-specific semantics:
  • Drone profile: at most one current pair key. A new pairing replaces the current key only after explicit operator confirmation (or a clean unpaired state on first boot).
  • Ground-station profile: can hold multiple pair keys (one per paired drone) so a single ground station can swap between drones without re-pairing each time. The active key is selected by the GCS or by the OLED menu.
The role is known at boot from the agent profile (profile: drone or profile: ground-station).

​
Manual pairing

Auto-bind covers the common path. Manual pairing is the right move when:
  • A drone needs to be re-keyed after a security event.
  • A ground station needs to switch which paired drone it’s listening to.
  • A multi-aircraft setup wants explicit pair-key control.
  • The operator is staging multiple drones and ground stations near each other and needs to be sure the right pair forms.
Manual flows live in two places:
  • OLED menu on the ground station: Pair with drone. Opens an explicit pair window with a code on the panel.
  • Setup webapp and Mission Control: explicit pair, unpair, and re-key buttons under Radio. The same /api/wfb/pair/* REST routes back both surfaces.
Pair codes generated for the manual flow are short (six characters), readable on a small panel, and time-boxed (default 60 seconds).

​
Cloud-relay fallback

If the two nodes can’t see each other on the radio (different sites, different channels, or one is offline), the cloud relay covers the gap. In that mode the operator pre-pairs through Mission Control and the cloud relay (HTTPS heartbeat plus MQTT pairing topics). Each side fetches the pair key from the relay on next boot, writes it locally, and starts the radio. From that point the link runs over the radio whenever the two are within range. The cloud relay path is documented in detail under Cloud relay. The pairing topics are part of the relay protocol; the local pair-store layout is identical regardless of how the key arrived.

​
REST surface

All routes carry the X-ADOS-Key header. The pair-state route is read-only and safe to poll from the GCS.

​
Diagnostics

A quick smoke test for the fresh-pair path: factory-reset both nodes, power them on within ten seconds, watch the panel transition from “waiting for pair” to “linked” without touching a webapp.

WFB-ng

The radio link itself: channel, FEC, antennas, monitor mode, hardware.

Cloud relay

The secondary path. Used when local pairing isn’t possible, plus higher-level fleet features.

REST API

Full route surface including authentication.

Field pairing

The mesh-side pairing flow. Distinct from the WFB pair, but shares the panel’s screen language.