QUICKSTART / GROUND AGENT

#bezpiLOTa Ground Agent is designed as an adjacent field component using the ground-station profile: it receives WFB-ng, provides Wi-Fi AP and USB tethering, supports an HDMI kiosk and shows status on an OLED with physical buttons.

PLANNED

Ground Agent is not a KairOS product; the shared interaction protocol and ground profile require a separate ecosystem build and validation.

KairOS repository ↗

WFB-NGradio receive

4client paths

OLEDoptional physical UI

GROUNDprofile

On this page +

WHAT IS GROUND AGENT

A bridge between the radio link and operator devices

On the air side, Drone Agent encodes video and transmits the radio stream. Ground Agent uses a compatible Wi-Fi adapter in monitor mode, receives WFB-ng packets, reconstructs the stream with FEC and publishes it to the local network. A laptop or phone connects to the AP/tether and opens Mission Control.

The ground profile does not require a flight controller. Automatic detection uses a reception adapter, absence of an FC, OLED and buttons as role signals. An explicit override is stored in /etc/kairos/config.yaml.

HARDWARE YOU NEED

Minimal bench and standalone field kits

Scenario	Components
Bench minimum	Raspberry Pi 4B 2 GB+; RTL8812EU USB adapter; 2× 5.8 GHz SMA antennas; USB-C data cable; stable external power
Standalone field	Bench kit + 1.3″ SSD1306 I²C OLED; four buttons; HDMI display; USB gamepad
Air side	Drone Agent SBC; WFB-ng TX adapter; camera; matching channel/key; FC link if telemetry/control is needed

INSTALLATION

From a fresh OS to the ground-station profile

Flash OS

Pi 4B: Raspberry Pi OS Lite Bookworm 64-bit. Radxa: vendor Debian/Ubuntu image.

Boot + SSH

Connect networking, find the hostname/IP and log in over SSH.

Attach radio

Connect the RTL8812EU with antennas before switching the interface to monitor mode.

Verify USB

lsusb should show a Realtek device, typically ID 0bda:8812.

Run generated install

Flash Tool selects Ground Agent and the board, then provides the current KairOS command.

Confirm role

Check the ground-station profile and enabled receive/AP/tether services.

bashTarget login and adapter check

ssh pi@kairos-ground.local
# или
ssh pi@192.168.1.XX

lsusb | grep -i realtek

KairOS target interface: the command becomes executable only after the corresponding component is released.

bashVerify agent and services

kairos status

KairOS target interface: the command becomes executable only after the corresponding component is released.

EXPECTED PROJECT STATE

Services and addresses that status should show

Item	Target KairOS literal
Profile	ground-station
Services	kairos-supervisor, kairos-api, kairos-health, kairos-wfb-rx, kairos-hostapd
Access point	SSID KAIROS-GS-abc123
WFB channel	161 / 5805 MHz in the example
AP address	10.0.0.1

CONNECT YOUR DEVICES

Four ways to open Mission Control

01FIELD DEFAULT

Laptop over Wi‑Fi

Connect to SSID KAIROS-GS-abc123 and open http://10.0.0.1:4000.

02WIRED

Laptop over USB

CDC-NCM tethering, open http://192.168.7.1:4000; native support on macOS Sonoma+, Windows 11 and Linux.

03NO LAPTOP

HDMI kiosk

Chromium kiosk on a connected display; the USB gamepad remains attached to Ground Agent.

04MOBILE

Phone or tablet

Browser over Wi-Fi AP; the KairOS Android app is a separate track and is optional.

Windows 10 may require an RNDIS driver instead of native CDC-NCM. On every path, the operator must understand which interface carries video, which carries telemetry and which holds command authority.

PHYSICAL UI

The OLED shows five status groups

Screen	Fields
Link	WFB signal, FEC, packet loss, bitrate
Drone	FC connection, armed, mode, battery, GPS
GCS	Connected clients and video streams
Net	Uplinks, IP addresses and data usage
System	CPU, RAM, temperature, disk, uptime

Control	Short press	Long press
Up / Down	Navigate screens	—
Select	Open detail / confirm	Enter setup mode
Back	Return	Confirmed factory reset flow

SETUP WIZARD

Radio, uplink and local security

WFB channel

Select the same channel as the air-side transmitter; different channels mean no video.

External Wi‑Fi

Optional client network for updates/cloud, without replacing the field AP.

Cloud account

Optional pairing/relay; local reception continues without it.

AP passphrase

The target image creates a unique per-unit passphrase on first boot and shows it to the operator through the local setup flow.

UPLINK MATRIX

Five network paths with observable failover

Uplink	Role
Wi‑Fi AP	Local operator clients
Wi‑Fi client	External network and optional cloud
Ethernet	Wired LAN/backhaul
USB tether	Direct data path to a laptop
SIM7600G-H 4G	Optional cellular backhaul

The target system provides priority failover, health checks and a configurable mobile-data limit. Path ordering, metering and failover must be tested and visible to the operator as explicit state rather than hidden automation.

TROUBLESHOOTING

Diagnose AP, WFB and USB tethering separately

bashWi-Fi AP

sudo systemctl status kairos-hostapd
iwconfig

KairOS target interface: the command becomes executable only after the corresponding component is released.

bashWFB receive and monitor mode

journalctl -u kairos-wfb -n 30 --no-pager
iwconfig wlan1

KairOS target interface: the command becomes executable only after the corresponding component is released.

bashUSB gadget

ls /sys/kernel/config/usb_gadget/kairos-ncm 2>/dev/null
sudo systemctl restart kairos-usb-gadget-setup

KairOS target interface: the command becomes executable only after the corresponding component is released.

If the AP is missing, check hostapd and conflicting interface roles.
If video is missing, compare channel, keys, monitor mode and air-side TX before debugging the browser.
If USB tethering does not appear, check the cable’s data lines, gadget configuration and client OS driver.
Do not restart radio/control services during an active flight without the prescribed fallback.