# Install the Android GCS
Source: https://docs.altnautica.com/android/install
Build the ADOS Android GCS APK from source, install it on an Android 10 or later device and make the first connection.
The Android GCS is installed from an APK you build from the [ADOSAndroidGCS repository](https://github.com/altnautica/ADOSAndroidGCS). The repository publishes no release APKs, so build it from source. The device needs Android 10 (API 29) or later.
## Build from source
You need JDK 17, the Android SDK with platform 37.0 (`platforms;android-37.0`) and build-tools 37, and NDK 26.3.11579264 for the radio modules.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/altnautica/ADOSAndroidGCS.git
cd ADOSAndroidGCS
cp local.properties.example local.properties # optional build-time endpoints
./gradlew assembleDebug
```
The debug APK is written to `app/build/outputs/apk/debug/`. Add `testDebugUnitTest lintDebug` to the Gradle command to run the unit tests and lint as well.
## Install the APK
With USB debugging enabled on the device:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
Or copy the APK to the device and open it, allowing installs from that source when Android asks. The debug build installs as **ADOS Android GCS** with the package id `com.altnautica.gcs.debug`, alongside any other build.
## First connection
> [tab] Ground station Wi-Fi
>
> 1. Open the app and tap **Connect**.
> 2. Under **Other ways to connect**, choose **Ground station Wi-Fi**.
> 3. Paste the join string the ground station's screen shows, or type its passphrase, and tap **Join**.
> 4. The ground station appears under **On this network**. Pair it with the code it shows (**Enter pairing code**).
> [tab] Agent on your LAN
>
> 1. Put the phone on the same network as the node.
> 2. Tap **Connect**. Nodes found on the network appear under **On this network**; tap one marked **Ready to pair**.
> 3. Or use **Enter pairing code** with the code on the node's screen or dashboard, or **Manual host** with its address (for example `192.168.1.50`). A node already paired with another GCS needs its API key.
> [tab] USB flight controller
>
> 1. Plug the flight controller into the phone with a USB OTG cable.
> 2. Tap **Connect** → **USB flight controller**.
> 3. Tap **Tap to allow USB access** and accept the Android prompt, pick the baud rate and add it.
Use **Demo** to try the app with a simulated drone.
## Permissions
| Permission | Why the app asks |
| - | - |
| USB access | Per device, when you open a USB flight controller or a USB radio |
| Nearby Wi-Fi devices (Android 13 and later) | Only to join a ground station's Wi-Fi |
| Location | The map's my-location marker, reading the joined Wi-Fi network name, and joining a Wi-Fi network on Android versions that require it |
| Notifications | The notification shown while a vehicle link stays open in the background |
The app also uses network, multicast (for mDNS discovery of agents), foreground service, wake lock and vibration permissions, which Android grants at install.
## Next steps
> [card] [Android GCS overview](/android/overview)
>
> Link families, features and the phone radio.
> [card] [Android client on a ground station](/ground-agent/android-client)
>
> Connect a phone to a ground station.
# Android GCS
Source: https://docs.altnautica.com/android/overview
The ADOS Android GCS: a native Kotlin and Jetpack Compose ground control station for Android 10 and later phones, tablets and handheld controllers.
The ADOS Android GCS is a native ground control station for Android, written in Kotlin with Jetpack Compose. It runs on phones, tablets and handheld controllers with Android 10 (API 29) or later, in portrait or landscape. This page describes version 0.2.0. The source is in the [ADOSAndroidGCS repository](https://github.com/altnautica/ADOSAndroidGCS) under GPL-3.0.
Use it when you want a ground station in your hand at the field. For desktop and laptop flying, planning and full flight controller setup, use [Mission Control](/mission-control/overview).
## Link families
The app reaches nodes over every ADOS link family. Pick one on the **Connect** screen.
| Link | How it connects | On the Connect screen |
| - | - | - |
| Agent on the LAN | REST on port 8080, MAVLink over WebSocket on port 8765, WHEP video, ground-station event streams, and the ground station's relay to the drones it carries | **On this network** (discovered nodes), **Enter pairing code**, **Manual host**, **Ground station Wi-Fi** |
| Direct flight controller | USB serial, UDP and TCP | **USB flight controller**, **UDP / TCP** |
| Cloud (opt-in) | Account sign-in, MQTT v5 control, WebRTC over MQTT and the cloud video relay | **Cloud sign-in** |
| Phone radio | A receive-only WFB link through a USB radio plugged into the phone | **Phone radio** |
**Demo** adds a simulated drone so you can try the app without hardware.
## Features
| Area | What it does |
| - | - |
| Connect | Discovers ADOS nodes on the network, pairs with a code, adds a host with its API key, joins a ground station's Wi-Fi, opens USB, UDP, TCP, cloud and phone radio links |
| Fleet | Every drone, ground station and flight controller you have connected, with battery, mode, arm state, the drones a ground station carries, and a video still |
| Node | Status and settings of a node, including the ground station tabs |
| Cockpit | Video with flight controls and the Skills you bind to buttons; warns before you leave while armed |
| Plan | Waypoint missions, survey areas, polygon and circle fences, and rally points on a MapLibre map |
| Configure | Flight controller setup such as motor test, refused while armed or when the link is stale |
| Logs | Flight history recorded automatically from arm to disarm, with telemetry logs and downloaded flight controller logs |
| Settings | Theme (**Dark**, **Light**, **Night vision**), **Glove mode** for larger touch targets, and language |
> [!WARNING]
>
> The cockpit and stick control fly a real aircraft. Read [Safety](/operations/safety) before you arm from the app.
## Video
Agent video plays through a native WebRTC (WHEP) client with hardware decoding. Streams from the phone radio and the relay paths decode with Android's MediaCodec H.264 decoder.
## Gamepad control
With a gamepad connected, the app streams `MANUAL_CONTROL` to the flight controller at 25 Hz while stick control is on. There are no on-screen virtual sticks.
## Phone as a receiver
With a supported USB radio (RTL8812EU or RTL8812AU on a USB OTG adapter) the phone can receive a drone's video and telemetry directly over WFB. It is receive-only: commands still go through the ground station or the network.
The phone needs the fleet's radio keys from a ground station:
1. Pair a ground station on the same network.
2. Open **Phone radio**, choose the ground station and tap **Request keys**.
3. Approve the request whose code matches the one on the phone: in Mission Control on the ground station's **Radio** tab (**Phone receivers** card, see [Ground station node panel](/mission-control/ground-station-panel)), or on the ground station's own dashboard **Pairing** page.
The ground station serves these requests through its `/api/v1/ground-station/wfb/invite` routes. Use **Forget radio keys** to remove them from the phone.
## Next steps
> [card] [Install the Android GCS](/android/install)
>
> Build the APK and make the first connection.
> [card] [Android client on a ground station](/ground-agent/android-client)
>
> Connect a phone to a ground station.
# Agent services architecture
Source: https://docs.altnautica.com/architecture/agent-services
Why the agent runs as many systemd units, how the supervisor gates and retries them, and the IPC sockets and HTTP front they share.
The agent runs each function as its own systemd unit. A supervisor decides which units this node should run, starts them through `systemctl`, and watches them. The units share no memory; they talk over Unix domain sockets in `/run/ados/` and over the HTTP front on port 8080.
This page explains the design. The unit list per profile is on [Systemd services](/drone-agent/systemd-services), the four profiles and how a node picks one are on [Node profiles](/getting-started/node-profiles), and board profiles are on [HAL and tiers](/drone-agent/hal-and-tiers).
## Why multi-process
One process would be simpler, but on an aircraft it fails badly:
* A crash in the video encoder would take the MAVLink link to the flight controller down with it.
* There would be no per-service memory or CPU limit, so one leak starves everything.
* Fixing one service would mean restarting all of them.
With one unit per function, a crashed `ados-video` restarts on its own and the MAVLink router never notices.
## Rust and Python
The long-running and safety-critical services are native Rust binaries in `/opt/ados/bin/`: the supervisor, the MAVLink router, the HTTP front, the cloud relay, the video pipeline, the radio, the ground receiver, the uplink router, the display, the logging daemon and the vision engine. Python, in the virtual environment at `/opt/ados/venv/`, carries the residual API behind the HTTP front, the setup webapp, HAL board detection and profile seeding, and AI sidecars such as the RKNN inference unit.
Many unit names are older than their Rust binaries and stay stable so the commands you type keep working:
| Unit | Binary it runs |
| - | - |
| `ados-mavlink` | `ados-mavlink-router` |
| `ados-wfb` | `ados-radio` |
| `ados-wfb-rx` | `ados-groundlink --role direct` |
| `ados-mediamtx-gs` | `ados-groundlink --ground-video` |
| `ados-oled` | `ados-display` |
| `ados-uplink-router` | `ados-net` |
On a ground station, `ados-net` owns the wired link, the Wi-Fi station and the cellular modem in one process, and `ados-pic` reads the front-panel buttons. There are no separate units for those.
## The supervisor
`ados-supervisor` never spawns service processes itself. It issues `systemctl` against a fixed catalog (`SERVICE_REGISTRY` in `crates/ados-supervisor/src/registry.rs`, derived from the unit table `UNITS` in `crates/ados-protocol/src/units.rs`), so systemd stays the process manager and owns the cgroups, restarts and journald wiring.
Each catalog row has:
* **A category.** Core units start first, then hardware units, then on-demand units. Shutdown runs in reverse.
* **A profile gate.** A row scoped to `drone`, `ground_station` or both is skipped on any other profile. A row with no gate runs everywhere.
* **A role gate.** On a ground station, some rows run only in one distributed-receive role (`direct`, `relay` or `receiver`).
* **A headless flag.** In headless mode only the lean flight core runs: the MAVLink router, the swarm bus, camera encode, the radio, the logging daemon and the HTTP front.
* **An idle rule.** Some units exit 0 on purpose when the node has nothing for them to do (no fleet slot, no LCD, a feature marker absent). The supervisor records these as `idle`, not as a failure, and does not restart them.
The supervisor reports each unit as `stopped`, `starting`, `running`, `failed`, `crash_looping` or `idle`.
### Crash-loop handling
When a unit fails 5 times inside 60 seconds, the supervisor labels it `crash_looping`. The label is for the operator; it never blocks a start. A unit parked in `failed` or `crash_looping` is retried every 5 seconds, so it recovers by itself once the cause goes away (for example a camera plugged back in). The supervisor also clears systemd's `start-limit-hit` latch with `systemctl reset-failed`, so no unit is left permanently stopped.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
running -> failure -> retried every 5 s -> 5 failures in 60 s -> crash_looping (still retried every 5 s) -> running
```
## Systemd unit structure
Unit files ship in the agent's `data/systemd/` and are installed to `/etc/systemd/system/`. This is the MAVLink router's unit, trimmed to the lines that matter:
```ini theme={"theme":{"light":"github-light","dark":"github-dark"}}
[Unit]
Description=ADOS MAVLink Proxy
PartOf=ados-supervisor.service
StartLimitIntervalSec=0
[Service]
Slice=ados.slice
Type=simple
ExecStart=/opt/ados/bin/ados-mavlink-router
Restart=always
RestartSec=3
Environment=ADOS_CONFIG=/etc/ados/config.yaml
SupplementaryGroups=dialout
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/var/ados /var/lib/ados /run/ados /dev /etc/ados
MemoryMax=50M
CPUQuota=25%
[Install]
WantedBy=ados-supervisor.service
```
* `PartOf` stops and restarts the unit with the supervisor.
* `Slice=ados.slice` puts every agent unit in one accounting slice, so per-unit memory and CPU are observable.
* `Restart=always` with `StartLimitIntervalSec=0` keeps the only flight-controller command path retrying instead of giving up.
* `MemoryMax` and `CPUQuota` stop one service from starving the rest. Each unit sets its own limits.
## IPC sockets
All sockets live in `/run/ados/` (override with `ADOS_RUN_DIR`). Every length-prefixed socket uses the same framing primitive: a 4-byte big-endian length followed by that many bytes. The contracts and their version numbers are registered in `crates/ados-protocol/contracts.toml`.
| Socket | Owner | Carries |
| - | - | - |
| `mavlink.sock` | `ados-mavlink-router` | MAVLink frames from the flight controller to every reader; frames written by a client go to the flight controller |
| `msp.sock` | `ados-mavlink-router` | The raw MSP byte stream for a Betaflight or iNav flight controller |
| `state.sock` | `ados-mavlink-router` | The vehicle-state snapshot, described below |
| `mavlink-ingest.sock` | `ados-mavlink-router` (ground station) | MAVLink frames arriving off the radio, merged into the ground station's fan-out |
| `api-internal.sock` | `ados-api` | The residual Python API, reached only through `ados-control` |
| `logd.sock` | `ados-logd` | Black-box ingest from every producer |
| `logd-query.sock` | `ados-logd` | On-box queries, used by `ados logs query` |
### MAVLink socket
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
| LENGTH (4 bytes, big-endian) | MAVLink v1 or v2 frame (LENGTH bytes) |
```
The router fans every frame from the flight controller out to all connected readers, such as the cloud relay and the HTTP front. It is a publish-subscribe socket: every reader gets every frame. Versioning follows MAVLink itself.
### Vehicle-state socket
`state.sock` is the canonical vehicle-state feed. The format is contract `state.v2`, body version 4.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
| LENGTH (4 bytes, big-endian) | msgpack map {"v": 4, "s": { ...state... }} |
```
* The router publishes a snapshot about 10 times a second. A new reader receives the last snapshot as soon as it connects.
* `s` is an open map of telemetry: attitude, position, GPS, battery, mode, armed state and link statistics. Once the flight controller's heartbeat is latched it also carries `fc_system_id` and `fc_component_id`.
* A reading the flight controller has not reported (battery voltage, current, remaining and temperature, GPS `eph` and `epv`, RC RSSI) is `null`, not the MAVLink sentinel value.
* `v` is an exact-match version. A reader skips any frame whose `v` differs from its own and gives up on the connection after 8 mismatched frames in a row. Every change to the body shape bumps the version, including an added field.
* The largest accepted frame is 1 MiB.
The older `state.v1` format (one JSON object per line, no version field) is legacy. The shared readers still decode a stray v1 line, choosing the format per frame from the leading byte, but nothing current produces it.
## HTTP control surface
Port 8080 belongs to the native Rust front, `ados-control`. It answers its own routes directly (including the WebRTC `/whep` endpoint), relays `/hls/*` to MediaMTX on loopback, serves the dashboard and on-box cockpit bundles from disk, and forwards a fixed set of path prefixes to the residual Python API over `api-internal.sock`. Any other `/api` path returns 404.
The forwarded prefixes are `PERMANENT_PYTHON_PREFIXES` in `crates/ados-control/src/routing.rs`:
* `/api/vision`
* `/api/v1/setup`
* `/api/peripherals`
* `/api/v1/peripherals`
* `/api/v1/display`
A client sees one HTTP surface on `:8080`; the split is internal. Native routes go through the front's own rate limiter, pairing gate and MCP scope check. Forwarded routes are authenticated by the front before they are passed on.
Requests authenticate with the `X-ADOS-Key` header. The key is the pairing key in `/etc/ados/pairing.json` (mode 0600), created when the node is paired. The MAVLink WebSocket on `:8765`, served by `ados-mavlink-router`, uses a short-lived single-use HMAC ticket instead. The full route list and auth rules are on [REST API](/drone-agent/rest-api).
## How a node picks its profile
The install-time choice decides. The installer's `--profile` flag, or the role picked in the setup wizard, is written to `/etc/ados/profile.conf`. An explicit `agent.profile` in `/etc/ados/config.yaml` overrides it.
Hardware detection is only a fallback seed. When `agent.profile` is `auto` (or unset) and `profile.conf` names no profile, the residual API runs `profile_detect` at boot and writes the result. Its decision is a strict argmax over hardware probes, with a tie broken by the last saved profile and a final default of `drone`. If the probes keep tying, the seed stops and you set the profile with `ados profile set` or the setup wizard. Details are on [Node profiles](/getting-started/node-profiles).
## Next steps
> [card] [Systemd services](/drone-agent/systemd-services)
>
> Every unit, its profile gate and what it does.
> [card] [Node profiles](/getting-started/node-profiles)
>
> The four profiles and how each one is chosen.
> [card] [Video stack](/architecture/video-stack)
>
> The camera-to-browser path the video units implement.
> [card] [Project structure](/architecture/project-structure)
>
> Where each crate and module lives.
# Cloud infrastructure
Source: https://docs.altnautica.com/architecture/cloud-infrastructure
How a node reaches the optional cloud: HTTPS status and commands to Convex, raw MAVLink over MQTT, and WebRTC signaling. Includes every MQTT topic.
The cloud is optional. Every core ADOS function works without internet. When you want to monitor or fly a node from outside its network, the agent's `ados-cloud` service connects it to two cloud components: a Convex backend and an MQTT broker.
This page explains how those paths work. To run the cloud side yourself, see [Self-hosting overview](/developers/self-hosting/overview). To turn the relay on for a node, see [Cloud relay](/drone-agent/cloud-relay).
## Three paths
```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
%%{init: {'theme': 'dark'}}%%
flowchart LR
subgraph Node["Drone or ground station"]
Cloud["ados-cloud (Rust)"]
Sock["/run/ados/mavlink.sock"]
WHEP["MediaMTX :8889/main/whep"]
Sock <--> Cloud
Cloud <--> WHEP
end
subgraph CloudSvc["Cloud"]
Convex["Convex backend
(HTTP actions)"]
Broker["MQTT broker"]
end
subgraph GCS["Mission Control"]
Queries["Convex reactive queries"]
Mqtt["mqtt-mavlink transport"]
RTC["WebRTC peer connection"]
end
Cloud -->|HTTPS POST /agent/status every 5 s| Convex
Cloud -->|HTTPS GET /agent/commands every 5 s| Convex
Cloud <-->|raw MAVLink frames| Broker
Cloud <-->|SDP offer and answer| Broker
Convex --> Queries
Broker <--> Mqtt
Broker <--> RTC
WHEP -.->|media, peer-to-peer| RTC
```
### Status and commands over HTTPS
Every 5 seconds, while the node is paired, `ados-cloud` POSTs a JSON status document to the Convex HTTP action `/agent/status`, authenticated with the node's `X-ADOS-Key`. The document carries the node's identity, version and board, plus resource use, flight controller link state and service health. Convex stores the latest document per node in the `cmd_droneStatus` table, and Mission Control reads it through reactive queries, so a change appears in the browser as soon as it lands.
Commands go the other way through the `cmd_droneCommands` table. Mission Control enqueues a command; the node polls `GET /agent/commands` every 5 seconds, runs what it finds and acknowledges each one with `POST /agent/commands/ack`.
This path needs only outbound HTTPS. No inbound ports and no broker.
### MAVLink over MQTT
For live telemetry and control, `ados-cloud` relays raw MAVLink frames between the node's `/run/ados/mavlink.sock` and the broker:
* Frames from the flight controller are published to `ados/{deviceId}/mavlink/tx`.
* Frames the browser publishes to `ados/{deviceId}/mavlink/rx` are written back toward the flight controller.
Nothing is converted to JSON. Mission Control's `mqtt-mavlink` transport feeds the payloads to the same MAVLink parser it uses on a LAN link, so the telemetry rate is whatever rate the flight controller streams. Betaflight and iNav flight controllers use the `msp/tx` and `msp/rx` topics the same way.
The relay never lets a slow uplink stall the flight controller link. Frames wait in a bounded queue (2000 frames) that drops the oldest frame when full, and are sent in batches of up to 50 ms or 4096 bytes. After an outage the newest telemetry goes out first.
### WebRTC signaling over MQTT
Live video does not pass through a cloud media server. The browser and the node set up a WebRTC peer connection, and the broker only relays the SDP:
1. The browser publishes `{"sessionId", "sdp"}` to `ados/{deviceId}/webrtc/offer`.
2. `ados-cloud` posts the SDP to the node's local WHEP endpoint, `http://localhost:8889/main/whep`.
3. It publishes MediaMTX's answer to `ados/{deviceId}/webrtc/answer/{sessionId}`, or an error document so the browser fails fast.
4. Media flows peer-to-peer after ICE completes.
5. The browser ends the session with `{"sessionId", "close": true}`. It also registers that close message as its MQTT last will, so a viewer that disappears is cleaned up when the broker notices.
> [!NOTE]
>
> Peer-to-peer WebRTC needs both sides to reach each other after STUN-negotiated NAT traversal. Behind symmetric NAT, which some cellular carriers use, ICE negotiation can fail. Mission Control's transport switcher reports the stage that failed. The video modes are described on [Video stack](/architecture/video-stack#video-transport-modes).
## MQTT topics
This is the complete set of topics a node uses. `{deviceId}` is the node's device id.
| Topic | Direction | QoS | Carries |
| - | - | - | - |
| `ados/{deviceId}/mavlink/tx` | Node to browser | 0 | Raw MAVLink frames from the flight controller, batched |
| `ados/{deviceId}/mavlink/rx` | Browser to node | 0 | Raw MAVLink frames for the flight controller |
| `ados/{deviceId}/msp/tx` | Node to browser | 0 | Raw MSP bytes from a Betaflight or iNav flight controller |
| `ados/{deviceId}/msp/rx` | Browser to node | 0 | Raw MSP bytes for the flight controller |
| `ados/{deviceId}/webrtc/offer` | Browser to node | 1 | JSON envelope: `{"sessionId", "sdp"}` to open, `{"sessionId", "close": true}` to end |
| `ados/{deviceId}/webrtc/answer/{sessionId}` | Node to browser | 1 | The SDP answer for one session, or an error document |
| `ados/{deviceId}/vision/detections` | Node to browser | 0 | Live vision detection batches, in the same shape as the LAN detection stream |
| `ados/{deviceId}/plugin/update_available` | Node to browser | 1 | A plugin update the daily check will not apply on its own (major version, permission change, board dropped, or pinned) |
| `ados/{deviceId}/plugin/{pluginId}/{stream}` | Node to browser | 0 | A plugin's own live stream, which the plugin host hands to `ados-cloud` to publish |
## Broker connection
Which broker the node dials depends on `server.mode` in `/etc/ados/config.yaml`:
| `server.mode` | Broker |
| - | - |
| `local` (default) | None. The node stays local-first and sends nothing to the cloud |
| `cloud` | The managed broker on port 443, MQTT over a TLS WebSocket at path `/mqtt` |
| `self_hosted` | Your broker, from `server.self_hosted.mqtt_broker` and `server.self_hosted.mqtt_port` (default 8883). With no broker set, the node has no relay; it never falls back to the managed broker |
`server.mqtt_transport` picks the wire: `websockets` (the default) is MQTT over a TLS WebSocket, and `tcp` is MQTT over TLS on the configured port. Over WebSockets, a configured port of 8883 is dialed as 443.
Every relay lane authenticates to the broker as `ados-{deviceId}`. Each lane also has its own client ID (`ados-{deviceId}` for MAVLink, with `-msp`, `-webrtc`, `-plugin-update` and `-plugin-publish` suffixes for the others), because a broker disconnects an existing session when a second client presents the same ID.
The full `server` key reference is on [Configuration](/drone-agent/configuration).
## Ground stations
A ground station runs the same `ados-cloud` service. When its uplink router reports an active uplink, it relays the MAVLink it receives from the drone over the radio on to the broker and sends its own status heartbeat, so a drone with no internet connection of its own can still be watched remotely. It reacts to uplink changes and data-cap limits from the uplink router.
## Next steps
> [card] [Cloud relay](/drone-agent/cloud-relay)
>
> Turn on the cloud relay for a node.
> [card] [Self-hosting overview](/developers/self-hosting/overview)
>
> Run Convex, the broker and the video relay yourself.
> [card] [Video stack](/architecture/video-stack)
>
> Where WebRTC fits in the camera-to-browser path.
# Code recipes
Source: https://docs.altnautica.com/architecture/contributing-guide
Step-by-step patterns for common code changes: a flight controller panel, a MAVLink decoder, a Zustand store and an agent service.
These recipes show where code goes for the most common changes. Setting up a development environment, branch names and pull request rules are on [Contributing](/getting-started/contributing). Directory layouts are on [Project structure](/architecture/project-structure). To add a board, follow [HAL and tiers](/drone-agent/hal-and-tiers).
## Test against ArduPilot SITL
Most Mission Control recipes end with a test against a simulated autopilot. The SITL tool in `tools/sitl/` builds ArduPilot and bridges it to a WebSocket:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
cd tools/sitl
npm install
npm run setup # fetch and build ArduPilot into ~/.ardupilot
npm start
```
The bridge binds the IPv6 loopback and accepts only clients that present a per-run token. Copy the `ws://[::1]:5760/?token=...` URL it prints. In Mission Control, open the connect dialog, choose **Flight Controller**, then **WebSocket**, pick the **SITL #1** preset and paste the full URL, token included. The token changes on every start.
> [!WARNING]
>
> SITL accepts arm, takeoff and mission commands like a real autopilot. Before you point the same code at hardware, read [Safety](/operations/safety).
## Add a flight controller panel (Mission Control)
Configuration panels live under `src/components/fc//`. Every panel reads and writes parameters through `usePanelParams`, which works the same for MAVLink parameters and MSP virtual parameters.
**1. Create the component**
```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// src/components/fc/misc/MyNewPanel.tsx
import { usePanelParams } from "@/hooks/use-panel-params";
import { usePanelCommit } from "@/hooks/use-panel-commit";
const paramNames = ["MY_PARAM_1", "MY_PARAM_2"];
export function MyNewPanel() {
const {
params,
loading,
dirtyParams,
setLocalValue,
saveAllToRam,
commitToFlash,
revertAll,
} = usePanelParams({ paramNames, panelId: "my-new-panel", autoLoad: true });
const { saving, save, flash } = usePanelCommit({ saveAllToRam, commitToFlash, revertAll });
// Render inputs bound to params.get(name) and setLocalValue(name, value),
// and the save and flash buttons wired to save() and flash().
}
```
`src/components/fc/safety/FailsafePanel.tsx` is a complete example, including the unsaved-changes guard.
**2. List it in the panel navigation**
Add an entry to `FC_NAV_ITEMS` in `src/components/drone-detail/fc-nav-items.tsx`:
```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ id: "my-new-panel", labelKey: "myNewPanel", icon: , requiredCapability: "supportsParameters", section: "Tuning" },
```
`requiredCapability` hides the panel on firmwares that lack the capability. `vehicleClasses`, `requiredVehicleType` and `excludeFirmware` narrow it further.
**3. Route the id to the component**
In `src/components/drone-detail/FcPanelRouter.tsx`, add a `dynamic()` import for the panel and a `case "my-new-panel":` that returns it.
**4. Add the label**
Add `"myNewPanel"` under the `fcNav` namespace in `locales/en.json`. English is the source locale.
**5. Test with SITL**
Connect to SITL, open the panel, and check that it loads, edits and writes the parameters.
## Add a MAVLink decoder (Mission Control)
**1. Register the message's CRC and length**
In `src/lib/protocol/mavlink-crc-extra.ts`, add the message id to both maps:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// CRC_EXTRA
[999, 0xab], // MY_NEW_MSG, from the MAVLink XML definition
// PAYLOAD_LENGTHS
[999, 24], // MY_NEW_MSG, full (untrimmed) payload length
```
Without a CRC\_EXTRA entry the parser cannot validate the frame.
**2. Write the decoder**
Add a typed `decode*` function to the matching file in `src/lib/protocol/messages/`:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
export interface MyNewMsg {
field1: number;
field2: number;
}
export function decodeMyNewMsg(dv: DataView): MyNewMsg {
return {
field1: dv.getFloat32(0, true),
field2: dv.getUint16(4, true),
};
}
```
**3. Add the callback**
Add a callback type in `src/lib/protocol/types/callbacks.ts`, a `myNewMsgCallbacks` array to `CallbackStore` in `src/lib/protocol/mavlink-adapter-callbacks.ts`, and an `onMyNewMsg` entry in `bindCallbackMethods`. Declare `onMyNewMsg?(callback: MyNewMsgCallback): () => void;` on `DroneProtocol` in `src/lib/protocol/types/protocol.ts`. Making it optional means the MSP and mock adapters do not have to implement it.
**4. Handle and route the frame**
Add a handler to the matching file in `src/lib/protocol/handlers/` that decodes the payload and calls each callback, then add a case to `routeFrame()` in `src/lib/protocol/mavlink-adapter-frame-handlers.ts`:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
case 999: handleMyNewMsg(p, c.myNewMsgCallbacks); break
```
**5. Bridge it into a store**
Subscribe in `bridgeTelemetry()` in `src/stores/drone-manager-bridge.ts` and push the data into a store. Add the returned unsubscribe function to the array the bridge returns.
## Add a Zustand store (Mission Control)
**1. Create the store**
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// src/stores/my-new-store.ts
import { create } from "zustand";
interface MyNewState {
value: number;
setValue: (v: number) => void;
}
export const useMyNewStore = create((set) => ({
value: 0,
setValue: (v) => set({ value: v }),
}));
```
**2. Select specific fields**
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const value = useMyNewStore((s) => s.value);
```
Never subscribe to the whole store.
If the store must survive a reload, wrap it in `persist` with a storage name, a version and a migration:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import { indexedDBStorage } from "@/lib/storage";
export const useMyNewStore = create()(
persist(
(set) => ({
value: 0,
setValue: (v) => set({ value: v }),
}),
{
name: "altcmd:my-new-store",
storage: createJSONStorage(indexedDBStorage.storage),
version: 1,
migrate: (persisted, _version) => persisted as MyNewState,
},
),
);
```
Bump `version` and branch on the old version in `migrate` whenever the stored shape changes.
If the store is fed by live telemetry, do not call `set()` per message. Mutate the data in place and notify through a coalesced version bumper, as `telemetry-store` does:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createVersionBumper } from "./coalesced-version";
const bumper = createVersionBumper(() =>
useMyNewStore.setState((s) => ({ _version: s._version + 1 })),
);
// after each in-place update:
bumper.scheduleVersionBump();
```
A store with a bumper must call `bumper.cancelVersionBump()` from its `clear()` action.
## Add an agent service (Drone Agent)
New long-running services are Rust binaries in the `crates/` workspace, installed to `/opt/ados/bin/`. The supervisor runs every unit through `systemctl`; it never spawns processes itself. The design is explained on [Agent services](/architecture/agent-services).
**1. Create the crate**
Add `crates/ados-my-service/` with a binary target and add it to the workspace members in `crates/Cargo.toml`. Use `ados-protocol` for any socket you read or write, so framing and contract versions stay in one place.
**2. Write the unit file**
Add `data/systemd/ados-my-service.service`, following the existing units:
```ini theme={"theme":{"light":"github-light","dark":"github-dark"}}
[Unit]
Description=ADOS My Service
PartOf=ados-supervisor.service
[Service]
Slice=ados.slice
Type=simple
ExecStart=/opt/ados/bin/ados-my-service
Restart=always
RestartSec=3
Environment=ADOS_CONFIG=/etc/ados/config.yaml
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/run/ados
MemoryMax=50M
CPUQuota=25%
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ados-my-service
[Install]
WantedBy=ados-supervisor.service
```
Set `MemoryMax`, `CPUQuota` and `ReadWritePaths` to what the service really needs.
**3. Register it in the unit table**
Add a `UnitSpec` row to `UNITS` in `crates/ados-protocol/src/units.rs`. The supervisor's catalog, the installer's enable, start, teardown and health lists, the REST restart allowlist and the armed interlock's link-dropping class are all derived from that table, and a test fails if a unit file in `data/systemd/` has no row (or a row has no unit file):
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
UnitSpec {
name: "ados-my-service.service",
category: Some(Hardware),
profiles: DRONE,
..BASE
},
```
Set `idle_ok: true` if the service exits 0 on purpose when the node has nothing for it to do, and `drops_link: true` if restarting it drops a command, telemetry, video, RC, mesh, access-point or cloud link.
**4. Ship the binary**
Add the binary to the installer's prebuilt catalog in `crates/ados-installer/src/binaries.rs` for the profiles that run it. CI publishes every service binary as an asset of the per-commit `rev-` release, and the installer fetches the assets for the active profile from there.
## Next steps
> [card] [Contributing](/getting-started/contributing)
>
> Development setup, branches and pull requests.
> [card] [Project structure](/architecture/project-structure)
>
> Where every module lives.
> [card] [HAL and tiers](/drone-agent/hal-and-tiers)
>
> Add a board profile.
# MAVLink and MSP protocol layer
Source: https://docs.altnautica.com/architecture/mavlink-protocol
How Mission Control parses MAVLink v2 and MSP, the DroneProtocol interface every adapter implements, and the transports that carry the bytes.
Mission Control talks to flight controllers in MAVLink v2 (ArduPilot and PX4) and MSP (Betaflight and iNav). One TypeScript interface, `DroneProtocol`, hides the difference so the rest of the app does not care which firmware is on the other end.
## MAVLink v2 framing
MAVLink v2 is a binary protocol. Every frame has the same layout:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
| STX (0xFD) | LEN | INC_FLAGS | CMP_FLAGS | SEQ | SYSID | COMPID | MSGID (3 bytes) | PAYLOAD | CRC (2 bytes) | SIGNATURE (13 bytes, optional) |
```
* **STX** is `0xFD` for v2.
* **LEN** is the payload length. v2 trims trailing zero bytes from the payload, so the receiver restores the full length before decoding.
* **MSGID** is 3 bytes.
* **CRC** is CRC-16/MCRF4XX over the frame, seeded with a per-message **CRC\_EXTRA** byte.
* **SIGNATURE** is present when bit 0 of `INC_FLAGS` is set: link id, a 48-bit timestamp and a 6-byte signature. `src/lib/protocol/mavlink-signer.ts` builds and checks it.
### CRC\_EXTRA
Every MAVLink message definition has a CRC\_EXTRA constant derived from its field layout. If the sender and the receiver disagree on a message's layout, the CRC fails and the frame is dropped. Mission Control keeps the CRC\_EXTRA value and the full payload length for every message it decodes in `src/lib/protocol/mavlink-crc-extra.ts` (`CRC_EXTRA` and `PAYLOAD_LENGTHS`).
## Parser
`src/lib/protocol/mavlink-parser.ts` is a streaming parser. It accumulates bytes from the transport in whatever chunks they arrive, scans for `0xFD`, reads the header and payload, restores zero-trimmed payloads, checks the CRC and emits a typed `MAVLinkFrame`.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
bytes in -> find 0xFD -> read header -> read payload -> restore trimmed bytes -> check CRC -> emit frame
```
## The DroneProtocol interface
`DroneProtocol` is defined in `src/lib/protocol/types/protocol.ts`. Every adapter implements it: `MAVLinkAdapter`, `MSPAdapter`, and the demo-mode `MockProtocol`. Its methods fall into groups:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
interface DroneProtocol {
readonly protocolName: string;
// Connection
connect(transport: Transport): Promise;
disconnect(): Promise;
// Commands
arm(): Promise;
disarm(): Promise;
setFlightMode(mode: UnifiedFlightMode): Promise;
takeoff(altitude: number): Promise;
returnToLaunch(): Promise;
commitParamsToFlash(): Promise;
// Parameters
getAllParameters(): Promise;
getParameter(name: string): Promise;
setParameter(name: string, value: number): Promise;
// Telemetry subscriptions, each returning an unsubscribe function
onAttitude(callback: AttitudeCallback): () => void;
onPosition(callback: PositionCallback): () => void;
onBattery(callback: BatteryCallback): () => void;
onGps(callback: GpsCallback): () => void;
onHeartbeat(callback: HeartbeatCallback): () => void;
// What this firmware supports
getCapabilities(): ProtocolCapabilities;
}
```
The real interface has many more members, including optional ones (marked `?`) that only some firmwares implement, such as iNav safehomes and geozones or fence and rally upload.
`ProtocolCapabilities` (in `src/lib/protocol/types/core.ts`) is a set of booleans such as `supportsParameters`, `supportsMissionUpload`, `supportsCalibration`, `supportsFailsafe`, `supportsOsd` and `supportsFirmwareFlash`. The UI reads it before showing a feature. A flight controller configuration panel that depends on one names it as its `requiredCapability`, so the panel does not appear for a firmware that lacks it.
## MAVLink adapter
`MAVLinkAdapter` (`src/lib/protocol/mavlink-adapter.ts`) implements `DroneProtocol` for ArduPilot and PX4. Its work is split across sibling files:
| File | Role |
| - | - |
| `mavlink-adapter-frame-handlers.ts` | `routeFrame()`: the switch from message id to handler, plus the stateful parameter, mission and version exchanges |
| `handlers/*.ts` | Stateless decoders grouped by area (telemetry, navigation and safety, calibration, CAN, vision, info, debug) that decode a payload and call the subscribers |
| `messages/*.ts` | The typed `decode*` functions for each message |
| `mavlink-adapter-callbacks.ts` | The subscriber lists behind every `on*` method |
| `mavlink-adapter-commands.ts` | `COMMAND_LONG` and `COMMAND_INT` commands, with acknowledgement tracking |
| `mavlink-adapter-params.ts` | The parameter protocol (`PARAM_REQUEST_LIST`, `PARAM_REQUEST_READ`, `PARAM_SET`, `PARAM_VALUE`) |
| `mavlink-adapter-missions.ts` | The mission protocol (`MISSION_COUNT`, `MISSION_REQUEST_INT`, `MISSION_ITEM_INT`, `MISSION_ACK`) |
| `mavlink-adapter-ftp.ts`, `mavlink-adapter-logs.ts` | MAVLink FTP and onboard log download |
ArduPilot and PX4 share MAVLink but differ in parameter names, mode numbers and some command meanings. The adapter learns the firmware from the heartbeat and from `AUTOPILOT_VERSION`, then applies the matching mode map and parameter metadata.
## MSP adapter
`MSPAdapter` (`src/lib/protocol/msp-adapter.ts`) implements `DroneProtocol` for Betaflight and iNav. MSP is a different kind of protocol:
* Request and response, with one request outstanding at a time. `msp/msp-serial-queue.ts` serializes requests and matches each reply.
* MSPv1 framing with an XOR checksum, and MSPv2 framing with a CRC-8 DVB-S2 checksum. The parser in `msp/msp-parser.ts` also handles jumbo frames.
* No named parameters. Configuration lives in binary blocks (PID profile, rate profile, OSD layout, serial ports and so on).
The adapter delegates to `msp-adapter-telemetry.ts` (polled telemetry), `msp-adapter-commands.ts` (commands) and `msp-adapter-params.ts` (virtual parameters).
### Virtual parameters
Because Betaflight and iNav have no parameter store, the MSP adapter maps fields of the configuration blocks to virtual parameter names such as `BF_RC_RATE`, `BF_RC_EXPO` and `BF_ROLL_RATE`. The definitions live in `src/lib/protocol/msp/virtual-params/`. This lets the `usePanelParams` hook, which every configuration panel uses, read and write Betaflight settings the same way it handles MAVLink parameters.
## Encoders
MAVLink encoding lives in `src/lib/protocol/encoders/`. `index.ts` re-exports every module, and `src/lib/protocol/mavlink-encoder.ts` re-exports the barrel.
| Module | Encodes |
| - | - |
| `frame.ts` | The v2 frame itself: header, sequence numbers and the CRC with CRC\_EXTRA |
| `core.ts` | `HEARTBEAT`, `COMMAND_LONG`, `COMMAND_INT`, `SET_MODE`, `REQUEST_DATA_STREAM`, `SET_GPS_GLOBAL_ORIGIN` |
| `params.ts` | `PARAM_REQUEST_LIST`, `PARAM_REQUEST_READ`, `PARAM_SET` |
| `control.ts` | `MANUAL_CONTROL` stick input |
| `mission.ts` | `MISSION_COUNT`, `MISSION_ITEM_INT`, `MISSION_REQUEST_LIST`, `MISSION_REQUEST_INT`, `MISSION_ACK`, `MISSION_CLEAR_ALL` |
| `peripheral.ts` | `SERIAL_CONTROL` and the onboard log requests (`LOG_REQUEST_LIST`, `LOG_REQUEST_DATA`, `LOG_ERASE`, `LOG_REQUEST_END`) |
| `ekf-source.ts` | EKF source-set selection |
| `can-forward.ts` | CAN forwarding, `CAN_FRAME`, `CANFD_FRAME` and `CAN_FILTER_MODIFY` |
| `ftp.ts` | `FILE_TRANSFER_PROTOCOL`: the 12-byte FTP header and data inside the MAVLink payload |
| `bounds.ts` | Range-checked integer writes, so an out-of-range value raises an error instead of wrapping into a different, valid-looking value on the wire |
## Transports
The adapters do not care how bytes arrive. Each transport implements the `Transport` interface in `src/lib/protocol/types/transport.ts`; the implementations are in `src/lib/protocol/transport/`.
| Transport | File | Use |
| - | - | - |
| WebSocket | `websocket.ts` | The agent's MAVLink WebSocket on `:8765` (HMAC ticket), a local MAVLink router, or the SITL bridge in `tools/sitl/` |
| Web Serial | `webserial.ts` | A flight controller on USB, straight from the browser |
| UDP and TCP | `net-mavlink.ts` | Classic UDP or TCP MAVLink links. The desktop app opens native sockets; in a browser the bytes go through a small local bridge over WebSocket |
| Bluetooth | `ble.ts` | Web Bluetooth to flight controllers with a Nordic UART Service module |
| MQTT (cloud) | `mqtt-mavlink.ts` | Raw MAVLink or MSP frames relayed through the cloud broker on `ados/{id}/mavlink/tx` and `/rx` (or the `msp` lane) when the node is not on your network |
| CAN | `slcan.ts`, `can-transport.ts`, `mavlink-can-forward-transport.ts` | DroneCAN, either over SLCAN on the flight controller's USB port or tunnelled through MAVLink `CAN_FORWARD` |
Demo mode does not use a transport to a real device. `MockProtocol` implements `DroneProtocol` directly and feeds the same stores a real connection would. The demo fleet is described on [Dashboard](/mission-control/dashboard).
## The agent-side router
On a node, MAVLink does not go from the flight controller to the browser directly. The agent's native router (`ados-mavlink-router`, run by the `ados-mavlink` unit) owns the flight controller's serial link, fans frames out on `/run/ados/mavlink.sock` for other agent services, and serves the stream to Mission Control over the WebSocket on `:8765`. A client needs a short-lived HMAC ticket before the router bridges it to the flight controller. See [MAVLink proxy](/drone-agent/mavlink-proxy).
## Message flow example
```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
%%{init: {'theme': 'dark'}}%%
sequenceDiagram
participant FC as Flight controller
participant Agent as Drone Agent
participant GS as Ground Agent
participant Browser as Mission Control
FC->>Agent: UART MAVLink ATTITUDE (msg 30)
Agent->>Agent: Router fans the frame out on /run/ados/mavlink.sock
Agent->>GS: WFB-ng auxiliary lane (binary MAVLink)
GS->>Browser: WebSocket :8765 (binary MAVLink)
Browser->>Browser: mavlink-parser emits a MAVLinkFrame
Browser->>Browser: routeFrame() calls handleAttitude()
Browser->>Browser: onAttitude subscribers fire
Browser->>Browser: bridgeTelemetry() pushes to telemetry-store
Browser->>Browser: React re-renders the subscribed components
```
## Next steps
> [card] [State management](/architecture/state-management)
>
> How decoded telemetry reaches the stores and the UI.
> [card] [Code recipes](/architecture/contributing-guide)
>
> Add a MAVLink decoder or a configuration panel step by step.
# Project structure
Source: https://docs.altnautica.com/architecture/project-structure
Directory maps and key files for the ADOS repositories: Mission Control, the agent, Extensions, the MCP server and the Android GCS.
ADOS spans several repositories. Their licences are listed on [Open source](/getting-started/open-source). This page is the reference for how each one is laid out. Generated output, dependencies and build folders (`node_modules/`, `dist/`, `target/`, virtual environments) are left out.
## Mission Control
**Repository:** [github.com/altnautica/ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl)
**Stack:** Next.js 16, React 19, TypeScript, Zustand 5, Tailwind CSS 4, Leaflet, CesiumJS, Convex, Electron.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ADOSMissionControl/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── page.tsx # Dashboard (home)
│ │ ├── plan/ # Mission planner
│ │ ├── simulate/ # 3D simulation and replay (Cesium)
│ │ ├── flight-logs/ # Flight log review and reports
│ │ ├── mcp/ # MCP server connections
│ │ ├── config/ # App settings (data, firmware, input, notifications, plugins, theme, video, ...)
│ │ ├── pair/ # Add a node over the LAN
│ │ ├── community/ # Changelog and contact
│ │ └── api/ # Route handlers (auth, LAN pairing proxy, firmware and manifest fetch, ...)
│ ├── components/ # React components by area
│ │ ├── dashboard/ # Fleet dashboard
│ │ ├── drone-detail/ # Per-vehicle tabs, FC panel navigation and routing
│ │ ├── fc/ # Flight controller configuration panels
│ │ ├── cockpit/ # Flight cockpit
│ │ ├── flight/ # Flight controls
│ │ ├── planner/ # Mission planning
│ │ ├── simulation/ # Simulation
│ │ ├── map/ # Map layers
│ │ ├── hardware/ # Ground station hardware views
│ │ ├── connect/ # Connect dialog and transport panels
│ │ ├── plugins/ # Extension host and UI slots
│ │ ├── vision/ # Vision views
│ │ ├── shared/, ui/ # Shared components and primitives
│ │ └── ...
│ ├── stores/ # Zustand stores
│ ├── lib/ # Core libraries
│ │ ├── protocol/ # MAVLink and MSP: parser, adapters, encoders, transports
│ │ ├── video/ # WebRTC (WHEP and MQTT-signalled) and MSE playback
│ │ ├── agent/ # Agent client: pairing, status, capabilities
│ │ ├── plugins/ # Extension runtime, capabilities, slot registry
│ │ ├── dronecan/, can/ # DroneCAN
│ │ ├── mission/, patterns/ # Mission model and survey patterns
│ │ └── ...
│ ├── hooks/ # React hooks (use-panel-params.ts and others)
│ ├── mock/ # Demo mode: flight engine, mock protocol, demo fleet
│ ├── i18n.ts # Translation setup
│ └── types/
├── locales/ # Translations, one JSON file per language (en.json is the source)
├── convex/ # Convex backend: schema, HTTP actions, cloud relay tables
├── electron/ # Desktop app (main process, native UDP and TCP sockets, updater)
├── tools/
│ ├── sitl/ # ArduPilot SITL launcher and WebSocket bridge
│ ├── mavlink-bridge/ # Local bridge for UDP and TCP links from a browser
│ ├── mqtt-bridge/ # Mosquitto broker deployment
│ ├── video-relay/ # RTSP to fragmented MP4 over WebSocket
│ ├── selfhost/ # All-in-one self-host stack
│ └── deploy/ # Self-host deploy tool
├── public/ # Static assets
├── scripts/ # Build and maintenance scripts
├── tests/
├── package.json
├── next.config.ts
├── CONTRIBUTING.md
└── SELFHOSTING.md
```
### Key files
| File | What it does |
| - | - |
| `src/lib/protocol/types/protocol.ts` | The `DroneProtocol` interface every adapter implements |
| `src/lib/protocol/mavlink-adapter.ts` | The MAVLink adapter for ArduPilot and PX4 |
| `src/lib/protocol/mavlink-adapter-frame-handlers.ts` | `routeFrame()`: message id to handler |
| `src/lib/protocol/msp-adapter.ts` | The MSP adapter for Betaflight and iNav |
| `src/lib/protocol/mavlink-crc-extra.ts` | CRC\_EXTRA and payload lengths for every decoded message |
| `src/stores/drone-manager.ts` | Connected vehicles, their adapters and the selected vehicle |
| `src/stores/drone-manager-bridge.ts` | `bridgeTelemetry()`: adapter callbacks to stores |
| `src/stores/telemetry-store.ts` | Ring-buffered telemetry |
| `src/hooks/use-panel-params.ts` | The parameter hook every configuration panel uses |
| `src/components/drone-detail/fc-nav-items.tsx` | The list of flight controller configuration panels |
| `src/components/drone-detail/FcPanelRouter.tsx` | Maps a panel id to its component |
| `src/lib/video/webrtc-client.ts` | WHEP and MQTT-signalled WebRTC client |
| `convex/schema.ts` | Convex database schema |
| `convex/http.ts` | Convex HTTP actions the agent calls (`/agent/status`, `/agent/commands`, ...) |
## Drone Agent and Ground Agent
**Repository:** [github.com/altnautica/ADOSDroneAgent](https://github.com/altnautica/ADOSDroneAgent)
**Stack:** Rust (a Cargo workspace in `crates/`, tokio, axum) and Python 3.11 or later, managed by systemd. One codebase serves every profile.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ADOSDroneAgent/
├── crates/ # Rust workspace
│ ├── ados-supervisor/ # Gates, starts and supervises the systemd units
│ ├── ados-mavlink-router/ # FC serial link, MAVLink IPC fan-out, vehicle-state snapshot, :8765 WebSocket
│ ├── ados-control/ # Native HTTP front on :8080
│ ├── ados-cloud/ # Cloud relay: status heartbeat, command poll, MQTT relays, WebRTC signaling
│ ├── ados-video/ # Video pipeline: ffmpeg, MediaMTX and radio tap supervision
│ ├── ados-radio/ # WFB-ng link: adapter selection, monitor mode, TX, frequency hopping
│ ├── ados-groundlink/ # Ground data plane: WFB receive, video fan-out, mesh
│ ├── ados-net/ # Ground uplink matrix: wired, Wi-Fi station, cellular, failover
│ ├── ados-display/ # OLED and LCD rendering, panel probe
│ ├── ados-hid/ # Touch, buttons, gamepads and the front-panel arbiter
│ ├── ados-gpio/ # GPIO output (buzzer, LED) (published)
│ ├── ados-crsf/ # CRSF and ExpressLRS RC control lane
│ ├── ados-config-tunnel/ # Config over radio (MAVLink TUNNEL)
│ ├── ados-swarmbus/ # Swarm state bus (2 Hz position beacons)
│ ├── ados-swarm/ # Swarm control laws, task allocation and simulator (published)
│ ├── ados-vision-engine/ # Vision engine host: frame rings, model registry
│ ├── ados-sensorbus/ # Sensor bus: frame codec, clients, capture-contract types
│ ├── ados-clock-service/ # Host clock service and sensor bus broker
│ ├── ados-sensorhub-service/ # Sensor hub service (USB or TCP packet stream)
│ ├── ados-gnss/ # GNSS service: receivers, RTK base and rover
│ ├── ados-lora-service/ # LoRa beacon and mesh lane service
│ ├── ados-offload/ # Perception offload for drones without an NPU (published)
│ ├── ados-plugin-host/ # Plugin RPC host and capability-token checks
│ ├── ados-logd/ # Black-box log and telemetry store (SQLite), :8090
│ ├── ados-macpin/ # Stable MAC pinning for adapters that randomize it (published)
│ ├── ados-hal-probe/ # Probe-first hardware capability detection (published)
│ ├── ados-config/ # Config loading for the Rust services
│ ├── ados-protocol/ # IPC wire contracts and contracts.toml (published)
│ ├── ados-capabilities-codegen/ # Generates the capability and contract tables for Rust, Python and TypeScript
│ ├── ados-sdk/ # Rust plugin SDK (published)
│ ├── ados-installer/ # Step-graph installer
│ ├── ados-tui/ # Terminal dashboard (`ados` with no subcommand)
│ ├── ados-vision/ # Visual tracker, YOLO decoding and re-identification (published)
│ ├── ados-sensorhub/ # Sensor hub wire protocol (published)
│ ├── ados-lora/ # LoRa airtime and band-plan governor (published)
│ ├── ados-crsf-codec/ # no_std CRSF codec (published)
│ ├── ados-positioning/ # UBX, NMEA and RTCM3 stream splitter, VALSET, survey-in (published)
│ ├── ados-rtcm/ # RTCM3 framing and GPS_RTCM_DATA fragmentation (published)
│ ├── ados-clock/ # Clock fitting and chrony refclock sink (published)
│ ├── ados-mavlink-tunnel/ # MAVLink TUNNEL chunking (published)
│ ├── ados-display-driver/ # OLED and framebuffer output (published)
│ ├── ados-hmi/ # Touch, button and encoder state machines (published)
│ └── README.md # Index of the crates published on crates.io
├── src/ados/ # Python package
│ ├── api/ # Residual FastAPI app, behind ados-control on an internal socket
│ ├── bootstrap/ # profile_detect.py: fallback profile detection
│ ├── cli/ # The `ados` command
│ ├── core/ # Config models, IPC helpers, generated contracts
│ ├── hal/ # Board detection and board profiles (hal/boards/*.yaml)
│ ├── plugins/ # Python plugin runtime support
│ ├── sdk/ # Python plugin SDK
│ ├── services/ # Entry points for Python-backed units
│ ├── setup/ # Setup facade
│ ├── dashboard/, cockpit/ # Built web bundles served by ados-control
│ └── __init__.py # Agent version
├── dashboard/ # Agent dashboard web app (source)
├── cockpit/ # On-box cockpit web app (source)
├── web-shared/ # Code shared by the two web apps
├── data/systemd/ # Unit files
├── schemas/ # Agent config and plugin manifest JSON schemas
├── scripts/ # install.sh bootstrap, build and release helpers
├── vendor/ # WFB-ng and the RTL8812EU driver
├── docs/ # Reference material
├── tests/
├── pyproject.toml
├── CONTRIBUTING.md
└── README.md
```
### Key files
| File | What it does |
| - | - |
| `crates/ados-supervisor/src/registry.rs` | The unit catalog: categories, profile and role gates, crash-loop handling |
| `crates/ados-protocol/contracts.toml` | Every IPC contract and its version |
| `crates/ados-control/src/routing.rs` | Which routes are native and which prefixes go to the residual API |
| `crates/ados-cloud/src/mqtt/mod.rs` | The MQTT topics and broker selection |
| `src/ados/bootstrap/profile_detect.py` | The fallback hardware fingerprint used when no profile is set |
| `src/ados/hal/boards/*.yaml` | Board profiles |
| `data/systemd/*.service` | The unit files |
| `scripts/install.sh` | The installer bootstrap |
| `src/ados/__init__.py` | The agent version |
The unit list is on [Systemd services](/drone-agent/systemd-services).
## Extensions
**Repository:** [github.com/altnautica/ADOSExtensions](https://github.com/altnautica/ADOSExtensions)
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ADOSExtensions/
├── extensions/ # First-party Extensions, one directory each
│ ├── follow-me/
│ ├── mavlink-gimbal-v2/
│ ├── siyi-pod/
│ ├── thermal-camera-flir-lepton-usb/
│ ├── vision-nav/
│ └── world-engine/
├── packages/
│ ├── create-ados-plugin/ # Plugin scaffolder
│ ├── plugin-sdk/ # TypeScript SDK for the Mission Control side
│ └── extension-ui/ # Shared UI primitives for first-party Extensions
├── scripts/ # Lint, pack, sign and submit
├── docs/
├── Cargo.toml, pyproject.toml, package.json
└── README.md
```
## MCP server
**Repository:** [github.com/altnautica/ADOS-MCP](https://github.com/altnautica/ADOS-MCP)
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ADOS-MCP/
├── src/
│ ├── server.ts, cli.ts, index.ts # Server and command-line entry points
│ ├── transport/ # MCP transports
│ ├── auth/, gate/ # Scopes and confirmation for actions that move an aircraft
│ ├── audit/ # Call audit trail
│ ├── discovery/, registry/ # Finding and tracking nodes
│ ├── catalog/ # Tool catalog
│ ├── plane/ # Node and fleet access
│ └── param-metadata/
├── catalog/
├── test/
└── package.json
```
## Android GCS
**Repository:** [github.com/altnautica/ADOSAndroidGCS](https://github.com/altnautica/ADOSAndroidGCS)
**Stack:** Kotlin, Jetpack Compose, Gradle.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ADOSAndroidGCS/
├── app/ # Application module
├── feature/ # Screens: cockpit, configure, connect, fleet, logs, node, plan, settings
├── core/ # Shared modules: agent, cloud, data, database, designsystem, extensions, link, map, mavlink, model, skills, video
├── radio/ # Radio modules: rx, usb
├── build-logic/ # Gradle convention plugins
├── baselineprofile/
└── settings.gradle.kts
```
## Paths on a running node
| Path | Purpose |
| - | - |
| `/etc/ados/config.yaml` | Main agent configuration |
| `/etc/ados/profile.conf` | The node's profile, written at install |
| `/etc/ados/pairing.json` | Pairing state and key (mode 0600) |
| `/opt/ados/bin/` | Rust service binaries |
| `/opt/ados/venv/` | Python virtual environment |
| `/run/ados/mavlink.sock` | MAVLink IPC socket |
| `/run/ados/state.sock` | Vehicle-state socket (length-prefixed msgpack, see [Agent services](/architecture/agent-services#vehicle-state-socket)) |
| `/run/ados/api-internal.sock` | Residual API socket behind `ados-control` |
| `/run/ados/logd-query.sock` | Black-box query socket |
## Next steps
> [card] [Code recipes](/architecture/contributing-guide)
>
> Add a panel, a decoder, a store or a service.
> [card] [Contributing](/getting-started/contributing)
>
> Set up a development environment and open a pull request.
# Mission Control state management
Source: https://docs.altnautica.com/architecture/state-management
How Mission Control keeps state in Zustand stores, buffers telemetry in ring buffers, and moves data from a protocol adapter to the screen.
Mission Control keeps client-side state in Zustand. There are more than 100 stores in `src/stores/`, each a focused slice of state with its own actions. Some larger stores are split into a directory of slices (`agent-connection/`, `agent-capabilities/`, `settings/`, `ground-station/`).
## Why Zustand
A Zustand store is a plain function that returns state and actions. There are no context providers and no reducers. Components subscribe to the fields they read and re-render only when those fields change.
That matters for a ground control station. A MAVLink stream delivers hundreds of decoded frames a second. A React context that re-rendered on every frame would freeze the page; fine-grained subscriptions plus coalesced notifications (below) keep it smooth.
## Store map
These are representative stores, not the full list. Browse `src/stores/` for the rest.
| Area | Stores |
| - | - |
| Live telemetry | `telemetry-store`, `drone-store` (connection, mode and armed state of the selected vehicle), `trail-store`, `swarm-beacon-store`, `vision-detections-store` |
| Vehicles and fleet | `drone-manager`, `fleet-store`, `node-registry/`, `drone-metadata-store`, `local-nodes-store`, `pairing-store` |
| Agent connection | `agent-connection-store`, `agent-capabilities-store`, `agent-system-store`, `agent-peripherals-store`, `ground-station-store` |
| Planning | `mission-store`, `planner-store`, `drawing-store`, `pattern-store`, `geofence-store`, `rally-store`, `plan-library-store` |
| Flying | `cockpit-store`, `guided-store`, `checklist-store`, `armed-confirm-store`, `input-store` |
| Video | `video-store`, `video-streams-store`, `camera-manager-store` |
| Configuration | `param-safety-store`, `panel-cache-store`, `signing-store`, `mixer-store` |
| Simulation and history | `simulation-store`, `simulation-history-store`, `history-store`, `sim-replay-store` |
| App settings and UI | `settings-store`, `ui-store`, `ui-prefs-store`, `changelog-notification-store` |
## Ring buffers for telemetry
`telemetry-store` holds one fixed-capacity ring buffer per telemetry message (`RingBuffer` in `src/lib/ring-buffer.ts`). When a buffer is full the oldest sample is overwritten, so memory stays flat however long the flight is. Most buffers are sized for about 60 seconds at the message's usual rate:
| Buffer | Capacity | Sized for |
| - | - | - |
| `attitude`, `vfr`, `rc` | 600 | 10 Hz for 60 s |
| `position`, `gps`, `localPosition`, `servoOutput` | 300 | 5 Hz for 60 s |
| `battery`, `radio`, `scaledImu`, `navController` | 120 | 2 Hz for 60 s |
| `sysStatus`, `gimbal`, `powerStatus`, `fenceStatus` | 60 | 1 Hz for 60 s |
| `flowQuality`, `flowDistance`, `vioQuality` | 1000 | Optical flow and VIO quality at 10 to 50 Hz |
The full list is in `src/stores/telemetry-store.ts`. A buffer offers `push`, `latest`, `get`, `last(n)`, `nearest(ts)` and `toArray`.
### Coalesced notifications
Pushing a sample mutates the buffer in place and then calls `scheduleVersionBump()` from `src/stores/coalesced-version.ts`. All the pushes inside one animation frame collapse into a single increment of the store's `_version` field. Components select `_version` and re-read the buffers, so the UI updates at most once per display frame however fast the wire runs. Any store fed by live telemetry follows the same rule.
## The drone manager bridge
`drone-manager` (`src/stores/drone-manager.ts`) owns the connected vehicles, their protocol adapters and the selected vehicle. When a vehicle connects, `bridgeTelemetry()` in `src/stores/drone-manager-bridge.ts` subscribes to the adapter's callbacks and routes each one to the stores:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Simplified from bridgeTelemetry() in drone-manager-bridge.ts
export function bridgeTelemetry(droneId: string, droneName: string, protocol: DroneProtocol) {
const telemetry = useTelemetryStore.getState();
const isSelected = () => droneSelection().selectedDroneId === droneId;
return [
protocol.onAttitude((data) => {
if (isSelected()) telemetry.pushAttitude(data);
rec("attitude", data);
}),
protocol.onPosition((data) => {
if (isSelected()) {
telemetry.pushPosition(data);
useTrailStore.getState().pushPoint(data.lat, data.lon, data.relativeAlt);
}
}),
// ...one subscription per callback
];
}
```
The telemetry rings are global, so only the selected vehicle writes to them; otherwise two connected vehicles would interleave their streams in one buffer. Every frame is still recorded for its own vehicle. `bridgeTelemetry()` returns the unsubscribe functions, and they all run when the connection closes.
## Parameters and configuration panels
Every flight controller configuration panel reads and writes parameters through the `usePanelParams` hook (`src/hooks/use-panel-params.ts`). It takes an options object and returns the values, load state and write actions:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const {
params, // Map
loading,
dirtyParams, // Set
setLocalValue,
saveAllToRam,
commitToFlash,
revert,
} = usePanelParams({ paramNames, optionalParams, panelId: "failsafe", autoLoad: true });
```
It handles MAVLink parameters (ArduPilot and PX4) and MSP virtual parameters (Betaflight and iNav) the same way, so panel code never touches the protocol. Writes go to RAM first; `commitToFlash` makes them permanent on the flight controller.
## Demo mode
Demo mode runs a simulated fleet entirely in the browser with no backend. `MockFlightEngine` (`src/mock/engine.ts`) writes synthetic telemetry into the same stores a real link would, and registers a `MockProtocol` per simulated vehicle with the drone manager, so configuration panels, flight logs and sensor health work too. The fleet itself is described on [Dashboard](/mission-control/dashboard).
The first-run welcome modal has a **Demo Mode** switch, on by default. You can also turn Demo Mode on or off in Settings, or with **Toggle Demo Mode** in the command palette (⌘K).
## Persistence
Stores that must survive a reload use Zustand's `persist` middleware with a version number and a migration function. When the stored shape changes, the version goes up in the same change and the migration converts old data. Persisted stores include:
| Store | What it keeps |
| - | - |
| `settings-store` | App settings, including the video transport mode, units, theme and language |
| `plan-library-store` | Saved mission plans |
| `simulation-history-store` | Past simulation runs |
| `local-nodes-store` | Nodes paired over the LAN and their API keys |
| `cockpit-store` | Cockpit preferences |
| `aircraft-registry-store`, `battery-registry-store`, `equipment-registry-store` | Your aircraft, batteries and equipment records |
Live telemetry stores never persist. They start empty on every page load.
## Selectors
Components subscribe to specific fields:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Re-renders only when the selected vehicle's arm state changes
const armState = useDroneStore((s) => s.armState);
// Re-renders on every change to the store: avoid
const everything = useDroneStore();
```
When a component needs several fields at once, wrap the selector in `useShallow` so a new object with equal values does not trigger a render.
## Next steps
> [card] [MAVLink protocol](/architecture/mavlink-protocol)
>
> The adapters that feed the stores.
> [card] [Code recipes](/architecture/contributing-guide)
>
> Add a store, a panel or a decoder.
# ADOS system overview
Source: https://docs.altnautica.com/architecture/system-overview
How the drone, the ground station and the optional cloud fit together, the protocol on every link, and the repositories that hold the code.
ADOS has three tiers: the Drone Agent on the aircraft, a Ground Agent on a nearby single-board computer, and optional cloud services for remote access. Each tier works on its own. You can fly with the first two and no internet at all.
The Drone Agent and the Ground Agent are the same software. The installer's `--profile` choice (`drone` or `ground_station`) decides which services run. See [Node profiles](/getting-started/node-profiles).
## The three tiers
```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
%%{init: {'theme': 'dark'}}%%
flowchart TB
subgraph Drone["Tier 1: Drone"]
FC["Flight controller
(ArduPilot, PX4, Betaflight, iNav)"]
Agent["Drone Agent
(Rust services + Python residual)"]
Camera["Camera
(CSI or USB)"]
WFB_TX["WFB-ng TX
(5 GHz monitor mode)"]
ELRS["ELRS receiver"]
FC <-->|UART MAVLink or MSP| Agent
Camera -->|V4L2| Agent
Agent -->|H.264 RTP, UDP 5600| WFB_TX
ELRS -->|CRSF| FC
end
subgraph Ground["Tier 2: Ground station"]
WFB_RX["WFB-ng RX
(ados-groundlink)"]
MediaMTX["MediaMTX
(RTSP + WHEP)"]
Control["ados-control
(REST + on-box cockpit, :8080)"]
Router["ados-mavlink
(MAVLink WebSocket, :8765)"]
AP["Wi-Fi AP / USB tether / Ethernet"]
HDMI["HDMI kiosk
(on-box cockpit)"]
Panel["OLED or LCD front panel"]
WFB_RX -->|video| MediaMTX
WFB_RX -->|aux lane MAVLink| Router
MediaMTX -->|WebRTC WHEP| AP
Router --> AP
Control --> AP
Control --> HDMI
end
subgraph Cloud["Tier 3: Cloud (optional)"]
Convex["Convex backend
(HTTP actions, reactive queries)"]
MQTT["MQTT broker"]
end
subgraph Clients["Clients"]
Browser["Mission Control"]
Phone["Android GCS"]
Remote["Remote Mission Control"]
end
WFB_TX -->|5 GHz radio link| WFB_RX
AP --> Browser
AP --> Phone
Agent -.->|HTTPS status + command poll| Convex
Agent -.->|raw MAVLink frames, SDP signaling| MQTT
Convex --> Remote
MQTT --> Remote
```
On the ground station the HDMI kiosk opens the on-box cockpit at `/cockpit/` on port 8080. The front panel shows link and node status on the attached OLED or LCD.
## Deployment models
### Field mode (tiers 1 and 2)
The drone and ground station talk directly over the WFB-ng radio. No internet and no cloud. This is the default for field operations and the shortest path ADOS has. The measured latency figures, and what they cover, are on [Video stack](/architecture/video-stack#what-is-measured-and-what-is-not).
### Cloud mode (tiers 1 and 3)
The drone has its own internet uplink (for example a 4G modem) and reaches the cloud directly. A remote operator opens Mission Control in a browser and gets raw MAVLink over MQTT and video over WebRTC. The carrier network and the broker add to the path, so this is the slowest of the three. There is no WFB-ng link in this model.
### Hybrid mode (tiers 1, 2 and 3)
The ground station receives WFB-ng for local flight and, when it has an uplink, relays the drone's MAVLink and video signaling on to the cloud for remote viewers. The ground station's `ados-cloud` service carries that relay; there is no separate relay unit.
### Distributed receive (several tier 2 nodes)
When one ground station cannot see the whole flight area, two or three Ground Agents can work together. They form a small private mesh over batman-adv on a second USB Wi-Fi adapter. One node takes the `receiver` role; every other node is a `relay` that forwards the WFB-ng fragments it heard. The receiver combines the merged stream with WFB-ng's FEC and serves the video through the same downstream path a single node uses. See [Mesh overview](/ground-agent/mesh-overview).
## Protocol stack
| Connection | Transport | Format |
| - | - | - |
| Flight controller to agent | UART | MAVLink v2, or MSP for Betaflight and iNav |
| Agent IPC (MAVLink) | Unix socket `/run/ados/mavlink.sock` | 4-byte big-endian length, then one MAVLink frame |
| Agent IPC (vehicle state) | Unix socket `/run/ados/state.sock` | 4-byte big-endian length, then a msgpack body, about 10 Hz. See [Agent services](/architecture/agent-services#vehicle-state-socket) |
| Encoder to radio | RTP (RFC 6184) on UDP 5600 | H.264 |
| Air to ground, video | WFB-ng radio port 0 | FEC-encoded H.264 RTP |
| Air to ground, telemetry | WFB-ng auxiliary lane (radio ports 2 and 3, UDP 5602/5603) | Multiplexed MAVLink, node status and identity |
| Air to ground, hop control | WFB-ng radio port 1 (UDP 5803/5810) | Frequency-hop announce, presence beacon, hop acknowledge |
| Ground to browser, video | WebRTC WHEP at `:8080/whep` (`ados-control`, relayed to MediaMTX on loopback) | H.264 RTP |
| Ground to browser, telemetry | WebSocket on `:8765` (short-lived HMAC ticket) | Binary MAVLink |
| Client to agent, control | HTTP REST on `:8080` (`ados-control`) | JSON |
| Agent log and telemetry query | HTTP on `:8090` and a Unix socket (`ados-logd`, off by default) | JSON |
| Agent to cloud, status | HTTPS POST `/agent/status` every 5 s | JSON |
| Agent to cloud, commands | HTTPS GET `/agent/commands` every 5 s | JSON |
| Agent to cloud, telemetry | MQTT `ados/{deviceId}/mavlink/tx` and `/rx` | Raw MAVLink frames, batched |
| Agent to cloud, video | WebRTC, SDP relayed over MQTT | H.264 RTP |
The MQTT topics are listed on [Cloud infrastructure](/architecture/cloud-infrastructure#mqtt-topics).
## Repositories
| Repository | What it holds | Licence |
| - | - | - |
| [ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl) | Mission Control: the web and desktop ground control station, its Convex backend and the self-host tools | GPLv3 |
| [ADOSDroneAgent](https://github.com/altnautica/ADOSDroneAgent) | The Drone Agent and Ground Agent (one codebase, selected by profile), the installer and the plugin SDKs | GPLv3 |
| [ADOSExtensions](https://github.com/altnautica/ADOSExtensions) | First-party Extensions and the plugin authoring packages | GPLv3 |
| [ADOS-MCP](https://github.com/altnautica/ADOS-MCP) | The MCP server that lets AI assistants read and command ADOS nodes | MIT |
| [ADOSAndroidGCS](https://github.com/altnautica/ADOSAndroidGCS) | The Android GCS app | GPLv3 |
| [Documentation](https://github.com/altnautica/Documentation) | This documentation site | CC0 1.0 |
Directory layouts for each repository are on [Project structure](/architecture/project-structure).
## Key design decisions
**Multi-process over single-process.** Each agent function runs as its own systemd unit with its own cgroup limits. A crashed video encoder does not take down the MAVLink router. See [Agent services](/architecture/agent-services).
**Rust for the long-running services.** The supervisor, MAVLink router, HTTP front, cloud relay, video pipeline, radio and ground receiver are native Rust binaries. Python remains for the residual API, setup, HAL board detection and AI sidecars.
**Web first for the operator.** Mission Control runs in a browser: WebSerial and WebSocket for the flight controller, WebRTC for video, the Gamepad API for sticks. An Electron build adds native UDP and TCP links on the desktop. See [State management](/architecture/state-management).
**WFB-ng for the air link.** The radio runs in monitor mode and broadcasts FEC-encoded packets. There is no association, no handshake and no retransmission, so nothing waits on a lost packet. See [Video stack](/architecture/video-stack).
**Profile over fork.** The ground station is the same agent with a different profile. One installer, one upgrade path and one test matrix.
## Next steps
> [card] [Agent services](/architecture/agent-services)
>
> The supervisor, the IPC sockets and the HTTP front.
> [card] [MAVLink protocol](/architecture/mavlink-protocol)
>
> How Mission Control parses and sends MAVLink and MSP.
> [card] [Video stack](/architecture/video-stack)
>
> Camera to browser, hop by hop, with the measured latency.
> [card] [Cloud infrastructure](/architecture/cloud-infrastructure)
>
> Convex status, MQTT relay and WebRTC signaling.
# Video stack architecture
Source: https://docs.altnautica.com/architecture/video-stack
The video path from camera sensor to browser, hop by hop: encode, WFB-ng radio, MediaMTX and WebRTC, with the measured latency.
ADOS carries live HD video from the drone's camera to a browser using open-source
parts at every stage: V4L2 for capture, ffmpeg for encode, WFB-ng for the radio
hop, MediaMTX for serving, WebRTC for delivery.
On the aircraft the `ados-video` unit supervises the encoder and the local
MediaMTX instance. On the ground station `ados-groundlink` owns the radio
receiver and the fan-out, and its `--ground-video` mode (the `ados-mediamtx-gs`
unit) runs a second MediaMTX instance that reads the radio stream and serves the
browser.
## The hop map
This is the list to measure against. Numbers in brackets are the hop labels used
by `ados diag video`.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DRONE
[1] camera (/dev/video0, CSI or USB UVC) via V4L2
[2] encoder: one ffmpeg process, H.264, GOP = fps/2
├─ [3] tee branch A: RTSP publish to the drone's own MediaMTX `main` path, :8554
└─ [4] tee branch B: RTP (RFC 6184) to UDP 5600 on loopback
[5] wfb_tx -p 0 -u 5600 (FEC k=8/n=12, 20 MHz)
[6] RTL8812EU in monitor mode, 5 GHz
GROUND
[7] wfb_rx -p 0 -u 5599 -l 1000 decodes and FEC-recovers
[8] fan-out :5599 -> :5600 (MediaMTX ingest) + :5605 (on-box display)
[9] ground MediaMTX reads RTP natively from udp+rtp://127.0.0.1:5600 (no ffmpeg)
[10] ground MediaMTX `main` path
[11] :8080/whep (ados-control, relayed to MediaMTX on 127.0.0.1:8889) -> cockpit or Mission Control
```
Telemetry does not share this path. MAVLink, node status and identity ride the
auxiliary lane (radio ports 2 and 3, UDP 5602 and 5603), separate from video
(radio port 0) and from the frequency-hop control plane (radio port 1, UDP 5803
and 5810). A dark video feed with a live telemetry link is therefore a normal
combination, and it points at hops 2 to 10.
`main` is the canonical path name on both nodes. MediaMTX serves WHEP at
`127.0.0.1:8889/main/whep`, on loopback only; browsers reach it through
`ados-control` at `:8080/whep`. Nothing publishes to `/ados`, so a zero byte count on that
path is not evidence of a video fault.
## Stage 1: Capture
The agent scans `/dev/video*` at boot and supports MIPI CSI cameras and USB UVC
cameras through V4L2. It sets resolution, framerate and pixel format before
starting the encoder. The shipped default is 1280x720 at 30 fps.
The encoder choice comes from the board's HAL profile. Rockchip boards with a
media engine can use `mpph264enc` through GStreamer. Boards exposing a V4L2
hardware encoder use `h264_v4l2m2m` through ffmpeg. Everything else falls back to
`libx264`.
## Stage 2: Encode
One process does the encode and both publishes. The default path (USB and IP
cameras) is a single ffmpeg whose output is ffmpeg's `tee` muxer: branch A is the
RTSP publish into the local MediaMTX, branch B is the RTP copy the radio reads.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ffmpeg -fflags nobuffer -flags low_delay \
-probesize 32 -analyzeduration 0 \
-f v4l2 -input_format mjpeg -video_size 1280x720 -framerate 30 \
-i /dev/video0 \
-c:v libx264 -b:v 4000k \
-pix_fmt yuv420p -profile:v high -level:v 4.1 \
-preset ultrafast -tune zerolatency \
-g 15 -bf 0 -refs 1 -threads 4 -flush_packets 1 \
-x264-params no-mbtree=1:sync-lookahead=0:rc-lookahead=0:sliced-threads=1:slices=4:scenecut=0 \
-bsf:v h264_mp4toannexb,dump_extra=freq=keyframe \
-max_delay 0 -muxdelay 0 -muxpreload 0 \
-map 0:v -f tee \
'[f=rtsp:rtsp_transport=tcp:max_delay=0:flush_packets=1]rtsp://127.0.0.1:8554/main|[f=rtp:payload_type=96:ssrc=0xCAFE:max_delay=0:flush_packets=1]rtp://127.0.0.1:5600?pkt_size=1316'
```
| Flag | Why it is there |
| - | - |
| `-fflags nobuffer -flags low_delay` | No input buffering, minimum encoder delay |
| `-probesize 32 -analyzeduration 0` | Skip format analysis on a source whose format is already known |
| `-preset ultrafast -tune zerolatency` | Fastest x264 path, no B-frames, no lookahead |
| `-profile:v high -level:v 4.1 -pix_fmt yuv420p` | `avc1.640029`, which the browser MSE player pins |
| `-g 15` | GOP is `fps/2`, so an IDR arrives every 500 ms at 30 fps |
| `-threads 4` plus `sliced-threads=1:slices=4` | Sliced threading emits a frame whole. Frame-level threading holds four frames in flight, which is about 133 ms of pure pipeline delay at 30 fps. Boards with fewer than four probed cores keep the two-thread frame-threaded form instead. |
| `-bsf:v ...,dump_extra=freq=keyframe` | Re-inserts SPS/PPS in-band before every IDR |
| `-max_delay 0 -muxdelay 0 -muxpreload 0` | ffmpeg's defaults here are about 0.7 s of mux delay plus 0.5 s of preload, in front of every downstream hop |
| `-map 0:v -f tee` | One encode, two muxers. The RTP copy costs no second encode. |
### Parameter sets repeat before every IDR
The RTSP muxer advertises `AVFMT_GLOBALHEADER`, which makes libx264 put SPS and
PPS only in extradata (the SDP) and never in the stream. A browser that loses
sync then has nothing in-band to re-bootstrap from and freezes on its last
decoded frame while the PeerConnection still reads `connected`.
Every encode arm repeats the parameter sets in-band per IDR to close that:
`dump_extra=freq=keyframe` on `libx264` and `h264_v4l2m2m`, `--inline` on
`rpicam-vid`, `h264parse config-interval=1` on the GStreamer arms plus
`mpph264enc header-mode=1` at the encoder. The ground ingest re-applies the same
bitstream filter, which is a no-op against a current drone and a repair against
an older one.
### There is no keyframe-on-demand, by design
The GOP is the recovery mechanism. A decoder that loses sync re-bootstraps at the
next IDR, which is at most 500 ms away at 30 fps with `-g 15`.
There is no PLI or keyframe-request path.
The shipped encoder leaves (`ffmpeg` CLI, `rpicam-vid`, `gst-launch-1.0`) expose
no runtime control channel an IDR could be requested through, and MediaMTX does
not forward a WebRTC receiver's PLI to an RTSP publisher. The most a request
could save is the 0 to 500 ms a decoder waits, so about 250 ms expected, on an
event that only happens after loss the FEC did not recover. Respawning the
encoder to force an IDR costs a 1 to 2 second blackout, which is strictly worse
than waiting.
### H.264 is the default codec
H.264 is the shipped wire codec. H.265 saves bandwidth at the same quality, and
`video.camera.codec` accepts it, but browser WebRTC support for H.265 is not
consistent enough to ship as a default and Mission Control's player pins
`avc1.640029`. Test your playback path before switching.
## Stage 3: WFB-ng transport
WFB-ng puts an RTL8812EU adapter in monitor mode and injects FEC-encoded packets
on 5 GHz. This is not standard WiFi: no association, no handshake, no
retransmission, no CSMA/CA backoff.
| Property | Value |
| - | - |
| Radio mode | 802.11 monitor mode (injection) |
| Frequency | 5 GHz |
| Channel width | 20 MHz |
| FEC | Reed-Solomon, `k=8` data of `n=12` total by default |
| Encryption | WFB-ng key exchange |
| Adaptive MCS | Capped at MCS 3 (`video.wfb.adaptive_mcs_max`, hard ceiling 5) |
The framing between the encoder and the radio is RTP (RFC 6184), payload type 96,
SSRC `0xCAFE`, `pkt_size` 1316, on UDP 5600. RTP is the contract, not a detail: a
lost RTP packet costs at most one NAL fragment, where a lost chunk of a raw byte
stream corrupts everything up to the next start code. The receiver depayloads
against the SDP in its MediaMTX path config (`rtpSDP`, shown in Stage 4).
> [!NOTE]
>
> On CSI boards the encoder is `rpicam-vid` or `gst-launch-1.0` publishing through a
> shell pipeline, and there the RTP copy is still produced by a separate tap process
> with its own watchdog. Check which encoder is running (the `encoder` field in
> `camera-state.json`, or the `Video` row of `ados status`) before reasoning about
> hop 4.
The MCS ladder cap is a statement of what has been measured, not of what the
radio can do. The rung table is arithmetic from standard 802.11n 20 MHz
required-SNR figures, and nothing in the tree has measured what the vendored
`rtl8812eu` driver actually applies. Raising the cap without a range sweep is how
a link that looks perfect on a bench dies at 150 m.
## Stage 4: Ground receive and serve
`wfb_rx -p 0` decodes the radio packets and FEC-recovers gaps, then the fan-out
forwards them to the ground MediaMTX on UDP 5600 and to the on-box display on
5605\. No ffmpeg sits in between. `ados-groundlink --ground-video` writes a
MediaMTX config whose `main` path has a native UDP RTP source and the SDP that
describes it:
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
paths:
main:
source: udp+rtp://127.0.0.1:5600
rtpSDP: |
m=video 5600 RTP/AVP 96
a=rtpmap:96 H264/90000
```
The same process supervises MediaMTX. It restarts MediaMTX 3 seconds after any
exit, with no attempt cap. A watchdog polls every 2 seconds and restarts
MediaMTX when its inbound byte count stalls for 12 seconds while the radio
statistics (fresh within 10 seconds) show packets still arriving.
| Endpoint | URL | Protocol |
| - | - | - |
| WHEP | `http://:8080/whep` | WebRTC (H.264 RTP), relayed by `ados-control` to MediaMTX on loopback |
| RTSP | `rtsp://:8554/main` | RTSP, for tools like VLC |
MediaMTX does no transcoding. The H.264 stream passes through to WebRTC as it
arrived.
Both MediaMTX instances are rendered from one config generator, so the air and
ground documents cannot drift apart silently. The file is written to
`/etc/ados/mediamtx.yml`.
> [!WARNING]
>
> Do not hand-edit `/etc/ados/mediamtx.yml`. MediaMTX rejects an unrecognised key
> outright, so a typo does not degrade the node, it leaves the node with no media
> server at all. Change `video.*` in `/etc/ados/config.yaml` and let the agent
> regenerate the file.
### WebRTC and ICE
The relevant MediaMTX keys, with the values the LAN profiles get:
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
webrtcLocalUDPAddress: ":8189"
webrtcLocalTCPAddress: "" # LAN profiles offer no TCP ICE candidate
webrtcIPsFromInterfaces: true
webrtcIPsFromInterfacesList: []
webrtcHandshakeTimeout: 10s
webrtcSTUNGatherTimeout: 2s
webrtcICEServers2: [] # LAN profiles gather no STUN
```
UDP ICE is pinned to a single port, 8189, so a firewall rule is one line.
STUN is configured only on the cloud-relay profile. On a LAN session the browser
connects on host candidates, so every STUN entry would be pure handshake latency
before the first frame. The relay profile carries five STUN servers and a TCP ICE
candidate on 8189, because a relay can face a network that blocks UDP.
## Stage 5: Browser decode
The browser receives H.264 RTP over WebRTC and decodes with the platform hardware
decoder. Mission Control's `src/lib/video/webrtc-client.ts` handles WHEP
negotiation, ICE gathering, track attachment and connection health.
Video reaches a browser either from the ground station over the radio hop above,
or over the cloud relay described below.
## Video transport modes
Mission Control's transport switcher offers four modes:
| Mode | How it works | When to use |
| - | - | - |
| `auto` | Tries LAN WHEP first, falls back to MQTT-signalled WebRTC | Default |
| `lan-whep` | WebRTC WHEP straight to the ground station's LAN address | WiFi AP, USB tether, Ethernet |
| `p2p-mqtt` | WebRTC with the SDP exchange relayed over MQTT | Remote access with no port forwarding |
| `off` | No video | Telemetry-only monitoring |
Under `p2p-mqtt` the browser and the agent's `ados-cloud` service exchange SDP
over MQTT:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados/{deviceId}/webrtc/offer browser publishes {"sessionId", "sdp"}, or {"sessionId", "close": true}
ados/{deviceId}/webrtc/answer/{sessionId} agent publishes the SDP answer, or an error document
```
On an offer, the agent posts the SDP to its local WHEP endpoint
(`http://localhost:8889/main/whep`) and publishes MediaMTX's answer on that
session's own answer topic, so concurrent viewers never see each other's SDP.
A close message, or the browser's MQTT last will when it vanishes, ends the WHEP
session. Once the exchange completes the media flows peer-to-peer through
STUN-negotiated NAT traversal; the broker carries signalling only, never video.
The full topic list is on
[Cloud infrastructure](/architecture/cloud-infrastructure#mqtt-topics).
> [!NOTE]
>
> `p2p-mqtt` needs internet access on both sides. Behind symmetric NAT, which some
> cellular carriers use, ICE negotiation can fail outright. The transport switcher
> reports the failing stage.
## What is measured, and what is not
One latency number in this stack has been measured, and it is not the number an
operator means by "latency".
**Publish-side, stamp to readback, sim bench, 2026-09-15.** The SEI probe injects
a timestamp after the encoder and reads it back from the drone's own
`rtsp://localhost:8554/main`.
| Figure | Value |
| - | - |
| Mean | 74 ms |
| Range across samples | 61 to 152 ms |
| Samples | 6 |
| Bench | 1280x720 at 30 fps, 4000 kbps synthetic RTSP source, agent binaries as installed |
That number covers four things: the publish mux, the RTSP publish, MediaMTX on
the drone, and the readback demux.
It excludes capture, encode, the radio hop, the ground receive, the ground
MediaMTX and the browser. Those are most of what an operator experiences.
**There is no glass-to-glass figure for ADOS, and this is not one.** Do not read
the 74 ms as end to end, and do not add per-stage guesses to it to manufacture a
total. A real air-to-ground figure needs the same probe run on the ground node
against its own `rtsp://127.0.0.1:8554/main` with clock-aligned nodes. A real
glass-to-glass figure needs a camera-side marker and a photograph of the viewer.
Neither has been done.
Two things to know before quoting any reading from the probe:
* It is off by default and gated on `video.wfb.sei_latency`, because it splices a
Python stage into the byte path. Bench profiles only.
* `/api/video/latency` reads the tap's sidecar file with no freshness gate, so a
stale reading can look live. Confirm an injector is actually in the byte path
before trusting a number.
For per-hop health rather than latency, `ados diag video` samples the reliable
cumulative counters at each hop twice and attributes a stall to the hop that
stopped. That is the supported first move on a dark feed. See
[Diagnostics](/drone-agent/diagnostics).
## Recording
Recording happens inside MediaMTX, writing fMP4 segments with no extra encode
pass. It is off by default; `video.recording.enabled` turns it on and
`video.recording.retention` bounds how long segments are kept. The segment set on
disk is the pre-roll ring, and clips are cut out of it after the fact with
`ados record clip`. See
[Video pipeline](/drone-agent/video-pipeline#recording).
## Next steps
> [card] [Video pipeline](/drone-agent/video-pipeline)
>
> Configure the camera, encoder and recording on a node.
> [card] [Diagnostics](/drone-agent/diagnostics)
>
> Run the per-hop video verdict with `ados diag video`.
> [card] [Cloud infrastructure](/architecture/cloud-infrastructure)
>
> The MQTT topics and the Convex status path.
# Agent runtime and sandbox
Source: https://docs.altnautica.com/developers/agent-plugin-deep-dive
How the plugin host runs an agent half: unit and log names, environment, IPC frames, capability checks, sandbox and restart policy.
This page is for authors writing non-trivial agent halves. It walks the
runtime path top to bottom: how the plugin host starts your code, what the
unit is called and where it logs, how IPC frames travel, how capabilities
gate every privileged call, and how the sandbox and restart policy behave.
## Subprocess model
Every third-party agent plugin runs as its own process, started by systemd
from a generated unit inside the shared `ados-plugins.slice` cgroup slice.
There is no in-process tier for third parties. Built-in plugins that declare
`isolation: inprocess` run inside the agent and skip everything on this page.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados-plugins.slice
├── ados-plugin-com-example-battery-c2d87e2a.service
├── ados-plugin-com-example-thermal-lepton-1b3dd913.service
└── ados-plugin-com-example-thermal-lepton-1b3dd913-.service
```
The plugin host (`ados-plugin-host.service`) owns the plugin's Unix socket,
renders the unit, and is a hard dependency of every plugin unit.
## Unit name
The unit name is `ados-plugin--<8 hex>.service`.
The 8 hex digits are the first 4 bytes of sha256 of the exact plugin id, so
two ids that sanitize to the same string (`com.example.thermal` and
`com.example-thermal`) never share a unit. `com.example.thermal-lepton`
becomes `ados-plugin-com-example-thermal-lepton-1b3dd913.service`.
Find yours on the node:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
systemctl list-units 'ados-plugin-*'
```
Each service a plugin declares under `agent.contributes.services` gets its
own unit, `ados-plugin--<8 hex>-.service`, in the
same slice and with the same sandbox as the main unit. Units are written to
`/etc/systemd/system/`.
## Logs
The unit appends stdout and stderr to
`/var/log/ados/plugins/-<8 hex>.log`, for example
`/var/log/ados/plugins/com-example-thermal-lepton-1b3dd913.log`. A declared
service logs to `-<8 hex>-.log` in the same
directory. Plugin output does not go to the journal.
`ados plugin logs` asks the agent for the plugin's log path, so you never
build the name yourself:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin logs com.example.thermal-lepton --follow
ados plugin logs com.example.thermal-lepton --service capture --lines 50
```
`--service` reads a declared service's log; an unknown service name exits
with the list of declared services. The supervisor trims any plugin log
past 32 MiB in place, keeping its tail.
## Environment
The unit sets a small, fixed environment:
| Variable | Value |
| - | - |
| `ADOS_PLUGIN_SOCKET` | Host socket, `/run/ados/plugins//host.sock`. |
| `ADOS_NODE_PROFILE` | `drone`, `ground-station`, `workstation` or `compute`. |
| `ADOS_PLUGIN_HTTP_SOCKET` | Only with `agent.http: true`: the socket the plugin serves HTTP on, `/run/ados/plugin-http//http.sock`. |
The capability token, agent id and data directory are not in the
environment. The host writes them to a root-owned `0600` file and the unit
loads it with `LoadCredential=`, so the process reads it as
`$CREDENTIALS_DIRECTORY/ados-plugin-token`, visible to that plugin's user
alone. The host rewrites it on every start and every token rotation. The
Python runner reads it for you; a Rust plugin's SDK runner does the same.
The plugin id is the runner's first positional argument. The paths the
plugin writes to arrive on the `ctx` object (see
[State and storage](/developers/state-and-storage)).
## IPC envelope
The plugin host listens on the socket before the plugin starts. The plugin
connects on startup and speaks length-prefixed msgpack frames: a 4-byte
big-endian length, then the msgpack-encoded envelope. Frames over 4 MiB are
refused.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
+----------------------+----------------------+
| u32 length (big-end) | msgpack envelope |
+----------------------+----------------------+
```
Decoded, an envelope carries these fields (the wire form uses compact
msgpack keys, and the GCS postMessage bridge carries the same logical
fields):
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "r42", # request id, plugin-generated
"type": "request", # request | response | event
"method": "mavlink.send",
"capability": "mavlink.write",
"args": {...},
"token": "...", # capability token on requests
"version": 1,
"error": None, # only on response
}
```
The host never trusts the `capability` field on the wire. It resolves the
required capability from the method name on every request, then checks the
granted set carried by the token. Forging the field fails with a
capability-denied error.
## The plugin class and lifecycle hooks
A plugin's agent half is a class named by the manifest `entrypoint`
(`module:Class`, or a `Plugin` class in a file-path entrypoint). The runner
imports it, constructs it, and calls async lifecycle hooks if they are
defined. The hooks are duck-typed; implement the ones you need:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class MyPlugin:
async def on_start(self, ctx) -> None: ...
async def on_configure(self, ctx, config: dict) -> None: ...
async def on_stop(self, ctx) -> None: ...
```
At start the runner calls `on_install`, `on_enable`, `on_configure` (with
the static config) and then `on_start`, each only if present. `on_stop` and
`on_disable` run when the unit receives `SIGTERM`. See
[Lifecycle](/developers/lifecycle) for the full order.
`ctx` is a `PluginContext` built by the runner. It exposes the
capability-gated facades `ctx.events`, `ctx.mavlink`, `ctx.msp`,
`ctx.peripheral_manager`, `ctx.camera`, `ctx.video`, `ctx.flight`,
`ctx.buttons`, `ctx.vision`, `ctx.telemetry`, `ctx.config_kv` (live
key-value config), `ctx.process`, `ctx.lifecycle` and `ctx.tools`, plus
`ctx.config` (the static config dict), `ctx.plugin_id`, `ctx.agent_id`,
`ctx.data_dir`, `ctx.config_dir`, `ctx.temp_dir` and `ctx.log`. You receive
it as an argument and never construct it; the reference plugins in
`ADOSExtensions/extensions/` are working examples.
## Capability enforcement
Capabilities are enforced in the plugin host, not in the plugin. Each method
maps to a required capability; the host checks the token's granted set
before the handler runs and rejects an ungranted caller before any work
happens. In the plugin, the call raises `CapabilityDenied`:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from ados.plugins.errors import CapabilityDenied
try:
await ctx.mavlink.send(frame_bytes)
except CapabilityDenied:
# the operator did not grant mavlink.write
...
```
Operators can revoke a capability at any time from Mission Control or with
`ados plugin perms --revoke `. A grant or revoke re-renders the
unit and restarts the plugin, so both the wire checks and the sandbox follow
the new set. The capability list and risk levels live in
[Permissions](/developers/permissions).
## Sandbox and identity
Four mechanisms isolate a plugin beyond the wire checks.
* **Its own system user.** Every plugin runs as `ados-plg-<8 hex>` (the same
hash as the unit name) with primary group `ados-plugins`. Distinct users
stop one plugin from reading another's `/proc//environ`, tracing it,
or reaching its socket. The user is created at install and removed with
the plugin.
* **Grant-driven device policy.** With no hardware capability granted the
unit gets `PrivateDevices=yes`, a private `/dev` holding only
pseudo-devices. Each granted hardware capability (`hardware.uart`,
`hardware.i2c`, `hardware.spi`, `hardware.gpio`, `hardware.usb`,
`hardware.usb.uvc`, `hardware.camera.csi`) switches to
`DevicePolicy=closed` with exactly the `DeviceAllow=` lines it names.
A `hardware.uart` grant still cannot open the flight controller's
configured serial port.
* **Network and filesystem.** Without `network.outbound` the unit allows
only `AF_UNIX` sockets and denies all IP addresses. No plugin binds an
inet port unless a declared service holds `network.listen`, and then only
its declared ports. `/run/ados` is an empty read-only tmpfs with only the
plugin's own socket directory and the log socket bound back in, and the
agent's credential files under `/etc/ados` are inaccessible.
`filesystem.host` opens `/srv`, `/mnt`, `/media` and `/boot`.
* **Declared services and HTTP.** `agent.contributes.services` render extra
units that run as the plugin's user under the same sandbox.
`agent.http: true` gives the plugin an HTTP socket the agent proxies.
`shared_topics` and `payloads` are manifest-level declarations; see the
[Manifest reference](/developers/manifest) and
[Contribution points](/developers/contribution-points).
## cgroup limits
The unit carries resource caps from the manifest's `agent.resources` block:
`MemoryMax` from `max_ram_mb`, `CPUQuota` from `max_cpu_percent`, and
`TasksMax` from `max_pids`. The kernel enforces them. A memory breach is
OOM-killed, a CPU breach throttles, and a tasks breach refuses new threads
or processes. The shared slice runs at `IOWeight=10`, so a plugin loses
every contended disk block to the flight services. Budgets and how to read
the live counters are on [Performance and budgets](/developers/performance-and-budgets).
## Restart policy
| Directive | Value |
| - | - |
| `Restart` | `on-failure` |
| `RestartSec` | `2s` |
| `StartLimitIntervalSec` (in `[Unit]`) | `0` |
There is no start-rate limit: a crashing plugin is retried every 2 s
indefinitely and never latches `failed`, so a plugin whose host socket is
not up yet recovers on its own. A clean exit (status 0) is not restarted;
if your plugin should run indefinitely, do not return from `on_start` until
`on_stop` is called. Plugin units carry no watchdog.
## Generated unit
Units are generated at install and re-rendered on every grant and revoke.
This is the pinned unit for a Rust plugin `com.example.rustplug`
granted `hardware.i2c`, `network.outbound` and `filesystem.host`:
```ini theme={"theme":{"light":"github-light","dark":"github-dark"}}
[Unit]
Description=ADOS plugin com.example.rustplug
After=ados-supervisor.service ados-plugin-host.service
Requires=ados-plugin-host.service
PartOf=ados-supervisor.service
# No start rate limit: a plugin whose host socket is not up yet must keep
# retrying rather than land in a failed state an operator has to clear by hand.
StartLimitIntervalSec=0
[Service]
Slice=ados-plugins.slice
Type=simple
Environment=ADOS_PLUGIN_SOCKET=/run/ados/plugins/com.example.rustplug/host.sock
Environment=ADOS_NODE_PROFILE=drone
LoadCredential=ados-plugin-token:/run/ados/plugins/com.example.rustplug.token
BindReadOnlyPaths=/run/ados/plugins/com.example.rustplug
BindPaths=/var/ados/plugin-data/com.example.rustplug
ExecStartPre=+/opt/ados/bin/ados-plugin-host guard-load
ExecStart=/var/ados/plugins/com.example.rustplug/agent/bin/com.example.rustplug com.example.rustplug --socket /run/ados/plugins/com.example.rustplug/host.sock
Restart=on-failure
RestartSec=2s
MemoryMax=96M
CPUQuota=25%
TasksMax=12
StandardOutput=append:/var/log/ados/plugins/com-example-rustplug-3bb2d8d0.log
StandardError=append:/var/log/ados/plugins/com-example-rustplug-3bb2d8d0.log
User=ados-plg-3bb2d8d0
Group=ados-plugins
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
LockPersonality=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
ProtectProc=invisible
RestrictNamespaces=yes
SystemCallArchitectures=native
NoExecPaths=/
ExecPaths=/var/ados/plugins/com.example.rustplug -/lib -/lib64 -/usr/lib -/usr/lib64
# ---- capability sandbox (re-rendered on every grant/revoke) ----
DevicePolicy=closed
DeviceAllow=char-i2c rw
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
SocketBindDeny=any
TemporaryFileSystem=/run/ados:ro
BindReadOnlyPaths=-/run/ados/logd.sock
ReadWritePaths=/var/log/ados/plugins /srv /mnt /media /boot
ProtectHome=read-only
InaccessiblePaths=-/etc/ados/secrets -/etc/ados/plugin-keys -/etc/ados/pairing.json -/etc/ados/config.yaml -/etc/ados/mcp-token.json -/etc/ados/dashboard-pin.json -/etc/ados/wfb -/etc/ados/mesh -/etc/ados/ap-passphrase -/etc/ados/hostapd-gs.conf -/etc/ados/model-registry-auth.json -/etc/ados/plugin-config.json
[Install]
WantedBy=ados-supervisor.service
```
The block after `# ---- capability sandbox` is re-rendered on every grant
or revoke. `ExecStartPre=+... guard-load` runs privileged before the plugin
and fails the start if the guard cannot load. `NoExecPaths=/` with the
`ExecPaths=` allowlist means the plugin can execute only its own install
tree and the shared libraries, never `/bin/sh`.
A Python plugin differs in two lines: `ExecStart=/opt/ados/venv/bin/ados-plugin-runner `,
and `ExecPaths=` also lists the runner's virtualenv. The runner loads the
manifest, puts the plugin source on `sys.path`, imports the entrypoint
class, connects to the socket, and dispatches into your hooks. A
`runtime: rust` plugin's binary is executed directly.
## Updates and restarts
Plugins are not hot-reloaded. Installing a new version stops the old
process, re-renders the unit, and starts fresh. The data directory
survives; see [Versioning and updates](/developers/versioning-and-updates).
## Debugging tips
* `ados plugin logs --follow` tails the plugin's log.
* `systemctl status 'ados-plugin--*'` shows the live unit
state of the main unit and its services.
* `systemctl cat 'ados-plugin--*'` prints the generated units.
* `ados plugin info ` prints granted permissions and install state.
> [!TIP]
>
> For the symptom-to-fix list (install failures, capability denials, IPC
> handshake errors), see [Troubleshooting](/developers/troubleshooting).
## Next steps
> [card] [GCS plugin deep dive](/developers/gcs-plugin-deep-dive)
>
> How the Mission Control half runs, talks to the host and renders.
> [card] [Performance and budgets](/developers/performance-and-budgets)
>
> Resource caps, throttling, memory pressure and profiling.
# Camera driver
Source: https://docs.altnautica.com/developers/camera-driver
Implement a CameraDriver for a visible, thermal, depth or multi-spectral imager in a plugin.
> [!WARNING]
>
> The driver base classes and data types ship in both SDKs (`ados.sdk.drivers` in Python, `ados_sdk::drivers` in Rust), and the method contracts on these pages match them. The agent does not route drivers. It never calls `discover()`, `open()` or the iterators. `register_*_driver` calls return `not_implemented`, and the `sensor.*.register` capabilities are refused at grant time. A driver plugin opens and runs its own device from its lifecycle hooks, as the first-party Gimbal v2 plugin does. No Mission Control panel renders driver output.
A `CameraDriver` reads frames from a physical or networked imaging device. Visible, thermal, depth and multi-spectral devices share this interface.
The worked `CameraDriver` subclass is `LeptonUvcDriver` in the FLIR Lepton plugin ([`extensions/thermal-camera-flir-lepton-usb`](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/thermal-camera-flir-lepton-usb), file `agent/src/altnautica_thermal_camera/driver.py`). The plugin is a development preview: capture needs a libuvc backend the agent does not ship, so it is not published.
## The interface
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from ados.sdk.drivers.camera import (
CameraDriver,
CameraCandidate,
CameraCapabilities,
CameraSession,
FrameBuffer,
)
class MyCameraDriver(CameraDriver):
async def discover(self) -> list[CameraCandidate]:
...
async def open(self, candidate, config) -> CameraSession:
...
async def close(self, session) -> None:
...
def capabilities(self, session) -> CameraCapabilities:
...
async def frame_iterator(self, session):
# async generator yielding FrameBuffer
...
async def set_param(self, session, param, value) -> None:
...
```
> [!NOTE]
>
> Writing the agent half in Rust? Implement `ados_sdk::drivers::CameraDriver` from the `ados-sdk` crate. It has the same methods as the Python base class (discover, open, close, capabilities, frame\_iterator, set\_param). Set `agent.runtime: rust` in the manifest.
## Candidates
`CameraCandidate` carries `driver_id`, `device_id`, `label`, `bus`, and optional `vid_pid` and `metadata`:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
CameraCandidate(
driver_id="com.example.my-camera",
device_id="usb-1.2.3",
label="MyCorp ThermalCam on USB 1.2.3",
bus="usb",
vid_pid=(0x1e4e, 0x0100),
)
```
Keep `device_id` stable across reboots when the bus can produce a stable identifier (USB serial, CSI lane, RTSP URL). Where that is impossible (raw V4L2 indexing), produce an id that is at least deterministic within one boot.
## Capabilities
Returned once per session, after `open`:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
CameraCapabilities(
radiometric=True,
bit_depth=14,
width=160,
height=120,
fps=8.7,
pixel_format="Y16",
streaming_protocol="uvc",
color_spaces=[],
has_audio=False,
)
```
`radiometric=True` means every pixel encodes a temperature and `FrameBuffer.radiometric_k` carries the per-pixel Kelvin matrix.
## Frame buffers
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
FrameBuffer(
timestamp_ns=ns,
sequence=seq,
width=160,
height=120,
pixel_format="Y16",
data=memoryview(raw_bytes),
radiometric_k=memoryview(temp_k_matrix),
metadata={"shutter_open": True},
)
```
`data` is a `memoryview` so your consumers can avoid copies. Put driver-specific fields under `metadata`.
## Opening the driver from your plugin
Your plugin constructs the driver and drives it. This is the shape of the FLIR Lepton plugin's `on_start`:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class Plugin:
async def on_start(self, ctx):
self.driver = MyCameraDriver(self.backend_factory())
candidates = await self.driver.discover()
if not candidates:
await ctx.events.publish("com.example.my-camera.status", {"state": "no_device"})
return
self.session = await self.driver.open(candidates[0], {})
self.task = asyncio.create_task(self.pump(ctx))
async def pump(self, ctx):
async for frame in self.driver.frame_iterator(self.session):
... # process, then publish what your GCS half shows
async def on_stop(self, ctx):
self.task.cancel()
await self.driver.close(self.session)
```
Declare the bus capability the device needs (`hardware.usb.uvc`, `hardware.camera.csi` or `hardware.usb`). The full table is on [Driver layer](/developers/driver-layer#manifest-permissions).
## Testing without hardware
Inject a mock backend that produces synthetic frames through the driver's constructor. The FLIR Lepton plugin ships `MockUvcBackend` in `agent/tests/mock_backend.py` for exactly this. See [Hardware testing](/developers/hardware-testing) for the pattern.
## Next steps
> [card] [Driver layer](/developers/driver-layer)
>
> The shared contract and the manifest table.
> [card] [Vendor binaries](/developers/vendor-binaries)
>
> When libuvc or a vendor library is required.
> [card] [Hardware testing](/developers/hardware-testing)
>
> Mock backends and bench rigs.
> [card] [Gimbal driver](/developers/gimbal-driver)
>
> The next driver kind.
# Plugin CLI reference
Source: https://docs.altnautica.com/developers/cli-reference
Every ados plugin subcommand, its flags, and the exit-code table.
The `ados plugin` subcommand tree is the operator and developer interface
to the agent's plugin host: install, enable, inspect, sign, and lint
plugins. This page documents all 15 subcommands, their flags, and the
exit codes every command shares.
The `plugin` group is not listed in `ados help`, but it is always
available. Run `ados plugin --help` on the agent for the command list,
or `ados plugin --help` for a single command. The lifecycle
commands talk to the local agent's `/api/plugins` routes, so run them on
the node.
## The `--json` flag
Every subcommand accepts `--json`. With it, the command prints a single
machine envelope to stdout instead of human-readable text:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "ok": true, "code": 0, "kind": "ok", "data": ... }
```
On failure the envelope carries the error:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "ok": false, "code": 3, "kind": "signature_invalid", "detail": "...", "hint": "..." }
```
`code` is the process exit code (see [Exit codes](#exit-codes)), `kind`
is the stable string form of that code, `data` is the per-command
payload, and `hint` (when present) is a suggested next step. Use the
JSON form in scripts and CI; parse `.ok` and `.code` rather than the
human text, which is not stable.
## Exit codes
Every `ados plugin` subcommand returns one of these codes. The JSON
envelope's `kind` field carries the same meaning as a string.
| Code | Kind | Meaning |
| - | - | - |
| 0 | `ok` | Success |
| 1 | `generic_failure` | Unclassified failure |
| 2 | `manifest_invalid` | The `manifest.yaml` is missing or fails validation |
| 3 | `signature_invalid` | The archive signature did not verify against an enrolled key, or the archive is unsigned. The hint names `ADOS_PLUGIN_REQUIRE_SIGNED`; see [Bench install and signing](/developers/signing-keys#bench-install-and-signing) |
| 4 | `permission_denied` | A capability change was refused: `--yes` on a high-risk plugin, or a first-party-only gate (`refused: ..._first_party_only`) such as `gcs.isolation: inline` or `resources.class: heavy` from another signer |
| 5 | `plugin_not_found` | No plugin with that id is installed, or a file the command needs is missing |
| 6 | `wrong_state` | The plugin is in a state the command cannot act on |
| 7 | `resource_limit` | A declared resource budget was exceeded |
| 8 | `compatibility_failed` | The plugin does not fit this agent: its `ados_version`, board, tier, target profile or architecture, or `isolation: inprocess`, which is refused for every plugin |
## Lifecycle commands
### `list`
List installed plugins.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin list
ados plugin list --all
ados plugin list --json
```
| Flag | Meaning |
| - | - |
| `--all` | Also list the built-in plugins that ship with the agent but are not installed |
| `--json` | Machine-readable output |
The human table prints `ID`, `VERSION`, `STATUS`, and `SIGNER`. With
`--all`, a built-in that is not installed shows status `available` and
signer `-`; install one with `ados plugin install `. Installed
built-ins show their real status.
### `install`
Install a plugin from a local archive, an archive URL, a built-in plugin
id, or a first-party catalog id. The command drives the agent's native
`/api/plugins` routes: it previews first, asks for approval, then installs
and grants the permissions you approved.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin install dist/com.example.thermal-1.0.0.adosplug
ados plugin install https://github.com/example/thermal/releases/download/v1.0.0/com.example.thermal-1.0.0.adosplug
ados plugin install com.altnautica.world-engine
```
| Argument / flag | Meaning |
| - | - |
| `SOURCE` | A `.adosplug` path that exists, an `https://` URL on the agent's download allowlist, a built-in plugin id, or a catalog plugin id |
| `--yes` | Skip the interactive permission-approval prompt. Refuses high-risk and critical-risk plugins |
| `--json` | Machine-readable output |
The preview verifies the signature and validates the manifest, then prints
the plugin id, its risk level, and the permissions requested, and prompts
for approval. If you decline, nothing is installed and the command exits 0.
The install itself checks compatibility, including the node profile and
the host architecture, before anything is unpacked. A URL install is pinned
to the sha256 of the archive you reviewed; a catalog install is pinned to
the catalog's sha256.
`--yes` approves the listed permissions without a prompt, but it refuses
any plugin whose `risk` is `high` or `critical` (exit 4); re-run those
interactively. A signature failure exits 3, a bad manifest exits 2, a
compatibility mismatch exits 8.
With `--json` and no `--yes`, the plugin installs with no permissions
granted; grant them with `ados plugin perms --grant `, or add
`--yes`.
After a successful install the plugin is installed but stopped.
Enable it next:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin enable com.example.thermal
```
### `enable`
Enable an installed plugin so the host starts it.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin enable com.example.thermal
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--json` | Machine-readable output |
Exits 5 if no plugin with that id is installed.
### `disable`
Disable a plugin. It stays installed, with its grants intact, but the
host stops running it.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin disable com.example.thermal
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--json` | Machine-readable output |
### `remove`
Stop, uninstall, and forget a plugin.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin remove com.example.thermal
ados plugin remove com.example.thermal --keep-data
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--keep-data` | Keep the plugin's log, data directory and system user. Without it, remove deletes all three |
| `--json` | Machine-readable output |
## Inspection commands
### `info`
Print a manifest summary and runtime state for one plugin.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin info com.example.thermal
ados plugin info com.example.thermal --json
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | An installed or built-in plugin id |
| `--json` | Machine-readable output |
The human output lists the version, status, signer, install source, and
each permission with its grant state. Exits 5 if the id is neither
installed nor a built-in.
### `perms`
Show, grant, or revoke permissions on an installed plugin.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# show
ados plugin perms com.example.thermal
# grant a permission the plugin declares
ados plugin perms com.example.thermal --grant mavlink.read
# revoke one capability
ados plugin perms com.example.thermal --revoke mavlink.write
ados plugin perms com.example.thermal --revoke mavlink.write --yes
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--grant ID` | Grant a permission the plugin declares |
| `--revoke ID` | Revoke a specific capability id |
| `--yes`, `-y` | Skip the revoke confirmation prompt |
| `--json` | Machine-readable output |
With neither flag, the command lists each recorded permission as
`GRANTED` or `DENIED`. Pass `--grant` or `--revoke`, not both. A revoke
confirms intent (unless `-y` or `--json`), then takes effect at once:
the host re-mints the plugin's token without the capability, which can
interrupt a running workload. Exits 5 if the plugin is not installed.
### `logs`
Print or follow a plugin's stdout and stderr log.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin logs com.example.thermal
ados plugin logs com.example.thermal --lines 500
ados plugin logs com.example.thermal --follow
ados plugin logs com.example.thermal --service worker
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--lines N` | Number of trailing lines to print (default 100) |
| `--follow` | Follow the log like `tail -f`. Ctrl-C to stop |
| `--service NAME` | Read a declared service's log instead of the main process's |
| `--json` | Machine-readable output (non-follow only) |
The command asks the agent for the log path (`GET /api/plugins/`),
so it always reads the file the host writes:
`/var/log/ados/plugins/-.log`, or
`...--.log` for a declared service. An unknown
`--service` exits 2 and lists the declared services. Exits 5 if the log
file does not exist yet (the plugin may never have started, or its log
was rotated out).
## Update commands
### `pin`
Pin a plugin to a version so auto-update skips it.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin pin com.example.thermal 1.2.0
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `VERSION` | The version to pin to |
| `--json` | Machine-readable output |
### `unpin`
Clear the pinned version so auto-update can run again.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin unpin com.example.thermal
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `--json` | Machine-readable output |
### `auto-update`
Toggle auto-update on or off for one plugin.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin auto-update com.example.thermal on
ados plugin auto-update com.example.thermal off
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_ID` | The installed plugin id |
| `STATE` | `on` or `off` |
| `--json` | Machine-readable output |
## Developer commands
These commands run on a developer workstation against a plugin directory
or a packed archive, not against installed plugins.
### `lint`
Run static analysis on a packed `.adosplug` archive before submission.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin lint dist/com.example.thermal-1.0.0.signed.adosplug
ados plugin lint --json dist/com.example.thermal-1.0.0.signed.adosplug
```
| Argument / flag | Meaning |
| - | - |
| `ARCHIVE_PATH` | Path to the packed `.adosplug` archive (must exist) |
| `--json` | Machine-readable output |
Exits 0 when the report passes, 1 when it carries a finding at severity
`error` or `critical`, 2 when the manifest is invalid. The full rule set
is documented under [Linting](/developers/linting).
### `test`
Run a plugin's pytest suite under the SDK test harness.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin test ./my-extension
ados plugin test ./my-extension --tests-dir tests -k follow
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_DIR` | The plugin directory (must contain a `manifest.yaml`) |
| `--tests-dir DIR` | Subdirectory holding the pytest tests (default `tests`) |
| `-k EXPRESSION` | A pytest `-k` expression passed through to the runner |
| `--json` | Machine-readable output |
The command validates the manifest, sets `ADOS_PLUGIN_ID`,
`ADOS_PLUGIN_VERSION`, `ADOS_PLUGIN_ROOT`, and (when declared)
`ADOS_PLUGIN_TEST_FIXTURES` in the environment, then shells out to
`pytest` so your tests run against the canonical runner. Exits 0 when
pytest passes, 1 when it fails, 2 on a bad manifest, 5 when the tests
directory is missing.
### `sign`
Pack a plugin directory into a signed `.adosplug` archive.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin sign ./my-extension \
--key keys/acme-2026-A.priv.pem \
--signer-id acme-2026-A \
--output dist/com.example.foo-1.0.0.adosplug
```
| Argument / flag | Meaning |
| - | - |
| `PLUGIN_DIR` | The plugin directory (must contain a `manifest.yaml`) |
| `--key PATH` | The Ed25519 private key in PEM format (required) |
| `--signer-id ID` | The signer id written to the `SIGNATURE` file. Must match the public-key filename on the agent (required) |
| `--output PATH` | Output path for the signed archive (required) |
| `--json` | Machine-readable output |
The command packs the directory, computes the canonical payload hash
(SHA-256 over the sorted entry hashes), signs that digest with the
Ed25519 key, and writes a `SIGNATURE` entry into the archive plus a
`.sha256` checksum file next to it. The signing details and the
monorepo-CI alternative (`pack.sh` and `sign.sh`) are covered under
[Signing keys](/developers/signing-keys).
### `keygen`
Generate a fresh Ed25519 keypair for plugin signing.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin keygen acme-2026-A --output-dir keys
ados plugin keygen acme-2026-A --output-dir keys --force
```
| Argument / flag | Meaning |
| - | - |
| `SIGNER_ID` | The signer id; becomes the key filenames |
| `--output-dir DIR` | Directory to write the keypair into (required) |
| `--force` | Overwrite existing key files at the target paths |
| `--json` | Machine-readable output |
Writes `.pem` (the public key, mode 0644) and
`.priv.pem` (the private key, mode 0600) under the output
directory, and prints a SHA-256 fingerprint of the public key for
cross-checking. Install the public PEM on each agent at
`/etc/ados/plugin-keys/.pem` and keep the private half
offline.
> [!WARNING]
>
> `keygen` is a developer aid. Production publisher keys deserve a
> hardware-token or air-gapped workflow, not a one-liner. Never commit a
> `.priv.pem` file.
## Next steps
> [card] [Lifecycle](/developers/lifecycle)
>
> The states these commands move a plugin through.
> [card] [Signing keys](/developers/signing-keys)
>
> Keys for `sign` and `keygen`, and how a node trusts them.
> [card] [Linting](/developers/linting)
>
> The rules `ados plugin lint` applies.
> [card] [Troubleshooting](/developers/troubleshooting)
>
> What to do when a command exits non-zero.
# Plugin concepts
Source: https://docs.altnautica.com/developers/concepts
Manifest, signing, sandboxing and capability tokens: the four primitives every plugin author works with.
A plugin has up to two halves: an **agent half** that runs on the drone
or ground station node, and a **GCS half** that runs in the Mission
Control browser. The agent half is written in **Python** (the `ados.sdk`
package) or **Rust** (the `ados-sdk` crate); the GCS half is written in
**TypeScript** (the `@altnautica/plugin-sdk` package). One signed
archive carries both halves and one `manifest.yaml` describes them.
Four primitives describe every plugin: a **manifest**, a **signature**,
a **sandbox** and a set of **capability tokens**.
## Manifest
A `manifest.yaml` at the root of the archive declares everything the
host needs to install the plugin: the id, the version, which halves
(`agent`, `gcs`, or both), the permissions each half requests, and the
contributions the GCS half mounts. The manifest carries no per-asset
hash list. Asset integrity is bound by the canonical payload hash that
the signing step writes into the separate `SIGNATURE` file.
The agent parses and validates the manifest in memory before unpacking;
a malformed manifest is rejected before any file is written. The strict
schema at `schemas/plugin-manifest.schema.json` is what
`ados plugin lint`, `ados plugin sign` and `ados plugin test` enforce,
so validate with them before you ship.
See the [manifest reference](/developers/manifest) for the full field
list.
## Signature
The archive is an Ed25519-signed zip. Two steps produce it:
1. **Pack.** Zip the plugin tree (manifest plus the agent and GCS
halves) into a `.adosplug`. No hashes are written into the manifest.
2. **Sign.** Compute the canonical payload hash (a SHA-256 over the
path-sorted `\n` of every archive entry except the
signature file), sign that 32-byte digest with an Ed25519 private
key, and write a `SIGNATURE` file into the archive. It has two
lines: the signer id, then the base64 signature.
`ados plugin sign` does both steps from a plugin directory.
On install the agent recomputes the payload hash and verifies the
signature against the public key enrolled for that signer at
`/etc/ados/plugin-keys/.pem`. The first-party signers
(`altnautica-2026-A` and `altnautica-2026-B`) are pinned in the agent
itself. A third-party signer is trusted once its public key is enrolled
on the node.
Unsigned archives install only on an agent whose services run with
`ADOS_PLUGIN_REQUIRE_SIGNED=0`; the agent logs a warning and records the
plugin with no signer, shown as **UNSIGNED**. Use that only on a bench
node; see
[Bench install and signing](/developers/signing-keys#bench-install-and-signing).
## Sandbox
Each half runs in its own sandbox.
* **Agent half**: a systemd unit that the plugin host
(`ados-plugin-host`) serves. A Python plugin runs through the plugin
runner; a Rust plugin (`runtime: rust`) runs its own compiled binary.
Either way the process runs as the plugin's own system user in the
`ados-plugins` group, inside the `ados-plugins.slice` cgroup with its
CPU, memory and process caps, and under systemd hardening such as
`NoNewPrivileges=yes`, `ProtectSystem=strict` and an exec allowlist.
It reaches the host only through its Unix domain socket, and it
cannot open network sockets unless it was granted
`network.outbound`. The [security model](/developers/security-model)
lists the full unit.
* **GCS half**: an `