CONCEPT AND DEVELOPMENTUNMANNED SPORT · #bezpiLOTa · KAIROS DRONE AGENTDocumentation
#bezpiLOTa→Getting started→How It Works
GETTING STARTED / ARCHITECTURE

The Flight Controller runs the hard real-time flight loop. The companion SBC handles video, routing, APIs and external communications. Mission Control selects direct USB, LAN or remote relay while keeping their responsibilities separate.

CONCEPT

The end-to-end flow is described as a target architecture; latency and rates remain design targets until KairOS measurements are available.

KairOS repository ↗
03connection modes
1 Hzcompanion heartbeat
2 Hztarget cloud telemetry
MAVLINKprimary protocol
01
THE BIG PICTURE

Two onboard computers—different responsibilities

The Flight Controller controls motors, stabilization, GPS and sensors. The companion computer—Raspberry Pi, Radxa, Jetson or another Linux SBC—runs KairOS Drone Agent and does not replace the FC: it adds video, telemetry relay, cloud connectivity, radio, REST APIs and extensions.

On the ground, Mission Control runs in a browser. It can access the FC directly over WebSerial, Drone Agent over LAN, or a remote relay through MQTT/Convex and WebRTC signaling. Ground Agent is added for WFB-ng use cases and turns radio reception into an accessible local web system.

02
DATA FLOW

The full telemetry, command and video round trip

01

FC → Agent

MAVLink UART usually operates at 115200–921600 baud; the agent waits for a heartbeat and identifies the firmware.

02

Agent → local consumers

The router distributes raw MAVLink to the IPC socket, WebSocket, cloud service and health state.

03

Agent → cloud

The target system publishes telemetry at approximately 2 Hz and status through HTTP/MQTT paths.

04

Camera → browser

V4L2 capture passes through H.264 encoding, MediaMTX/RTSP and the selected WHEP, WebRTC or WFB-ng transport.

05

GCS → FC

Arm, mode, mission and other commands return over the same selected path; the FC enforces pre-arm rules.

06

ACK → UI

Command acknowledgements and updated heartbeats/state return, after which the UI updates its status.

03
THREE CONNECTION MODES

Direct USB, LAN and remote P2P

ModeTransportWhen to useDesign target
Direct USBWebSerial → FC, no agent requiredBench, configuration, calibration, firmwareDesign target <10 ms
LAN DirectREST :8080, MAVLink WS :8765, WHEP :8889Indoor, short range, development, field LANTarget: video 50–150 ms; telemetry <100 ms
P2P remote4G/Internet, MQTT SDP signaling, WebRTC, ConvexRemote observation and a secondary pathTarget: video 100–300 ms; telemetry 2–5 Hz

Automatic transport should first search for a LAN path for about four seconds, then move to P2P signaling with a window of about fourteen seconds. These are design intervals: they depend on the network and are not a KairOS SLA.

05
THE VIDEO PIPELINE

From V4L2 capture to native H.264 playback

01

Capture

USB UVC or MIPI CSI is opened through V4L2; available formats and resolutions are checked before startup.

02

Encode

ffmpeg uses H.264 high profile, level 4.1, yuv420p and low-latency flags; a hardware encoder is selected when available.

03

Publish

The encoded stream is published to MediaMTX/RTSP and becomes the source for downstream transports.

04

LAN

WHEP delivers WebRTC directly to the local browser.

05

Remote

MQTT carries SDP signaling, after which media travels over P2P WebRTC or, if needed, a relay.

06

Radio

wfb_tx sends H.264 over WFB-ng; Ground Agent receives it and republishes locally.

The nobuffer and low_delay parameters and a small probe size reduce queues, but actual latency depends on capture, encoder, bitrate, FEC, radio, network and browser decoding. KairOS will publish measurements for specific profiles, not one universal number.

Video cockpit with an H.264 stream: heading, speed, altitude, GPS, battery, minimap, recording indicator and flight commands.
INTERFACE / VISUAL EXAMPLEVideo on the operator surface

The camera image is supplemented by a HUD, minimap, flight mode and recording indicator. H.264 format is separately identified on screen.

06
CLOUD RELAY

MQTT for real-time data, Convex for state and the command queue

The target KairOS Agent publishes MQTT telemetry at about 2 Hz. The MQTT-to-Convex bridge aggregates state with a debounce of about three seconds per device, while the browser receives reactive queries. Commands are written to Convex; agent polling retrieves pending items, converts them to MAVLink and returns an ACK.

textRemote data paths
Telemetry: FC → Agent → MQTT → bridge → Convex → Mission Control
Commands: Mission Control → Convex queue → Agent poll → MAVLink → FC
Video: Camera → Agent → MQTT SDP → P2P WebRTC → Browser
07
GROUND AGENT ROLE

The field node converts radio reception into local interfaces

ClientPath
LaptopWi-Fi AP, Ethernet or USB CDC-NCM tethering
Phone / tabletA browser on the same local network or the KairOS Android track
Field monitorHDMI + Chromium kiosk
Mission ControlGround-station profile with video/telemetry sources

The profile literal is ground-station. It shares one codebase with Drone Agent but enables different services: reception instead of onboard encoding, and AP/tether/kiosk instead of FC-centered onboarding.

08
MISSION CONTROL STATE

Stores separate vehicle, telemetry, mission and transport

StoreResponsibility
drone-managerNodes, connection paths and active vehicle
telemetry-storeLive state and a 300-sample ring buffer
mission-storeWaypoints, patterns, validation, upload state
video-storeSources, transport, playback and errors
settings-storeIndexedDB persistence and migrations
ground-station-storeReceivers, relay paths, sources and field I/O
Overview of a six-agent fleet: cards with video, telemetry and resources, plus online, stale and offline filters.
INTERFACE / VISUAL EXAMPLEIndividual node states in the fleet overview

Each agent has its own video, telemetry and resource metrics. Filters and statuses illustrate why node availability and data freshness must be distinguished.

09
WHAT HAPPENS WHEN YOU ARM

Arming is a confirmed chain, not a local toggle

01

Operator intent

Mission Control calls protocol.arm() after explicit confirmation.

02

Protocol

MAV_CMD_COMPONENT_ARM_DISARM, command #400, is created.

03

Transport

The frame travels over WebSocket/LAN or the Convex/cloud path to the Agent.

04

Serial

The Agent forwards the command to the FC without claiming authority over pre-arm checks.

05

FC validation

Firmware checks sensors, GPS, battery, the safety switch, EKF and configured failsafes.

06

State confirmation

HEARTBEAT base_mode bit 7 and the ACK return through IPC/MQTT; the UI shows ARMED only after confirmation.