# 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 ` ``` The host loads the bundle from a `blob:` URL and injects the CSP as a `` at the top of the frame document; a blob document would otherwise inherit the app's CSP. The empty `allow` attribute grants no device or browser features. The sandbox flags that are deliberately absent: * `allow-same-origin`: the frame cannot read host cookies, local storage or the host document. * `allow-top-navigation`: the plugin cannot redirect the parent window. * `allow-forms`: no browser-native form submission. * `allow-popups`: no new windows. > [!NOTE] > > First-party plugins signed by a trusted first-party key may set `gcs.isolation: inline` (module in the host page). Third-party plugins are always iframe. ## Frame CSP Every plugin frame carries the same policy, whatever capabilities the plugin holds: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'; webrtc 'block'; form-action 'none'; base-uri 'none' ``` `connect-src 'none'`: the frame cannot open any network connection, not even to the GCS origin. All I/O goes through bridge methods; images arrive as data/blob URLs. WebRTC is removed from the frame. A guard script runs before the bundle, deletes every `RTC*` interface from the frame's global and refuses nested frames, which would otherwise hand the plugin a fresh global with those interfaces restored. `script-src` has no `'unsafe-eval'`. Ship the bundle as a single-file ES module with no `eval`, `new Function` or dynamic `import()`. If the plugin needs outbound network access, put that work in the agent half under the `network.outbound` capability. ## postMessage RPC envelope The frame and the host exchange envelopes through `window.parent.postMessage`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} interface RpcEnvelope { id: string; // correlates request with response type: "request" | "response" | "event"; method: string; capability: string; // the capability the caller claims args: unknown; version: 1; error?: { code: string; message: string }; token?: string; // per-RPC capability token } ``` When the host bridge runs with a token validator, every envelope carries a `token` (base64-encoded JSON claims). The validator checks expiry, plugin id, agent id, capability membership and signature before the call dispatches. The SDK hides the envelope. You write: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const state = await ctx.mission.read("active"); ``` and the SDK builds the envelope, generates the id, awaits the correlated response and throws `HostError` on an error envelope. For methods without a facade, call `ctx.client.request(method, capability, args)`. ## Capability checks The host bridge re-resolves the required capability from `method` and `args` and checks it against the plugin's granted set. It ignores the envelope's `capability` field for authorization, so a plugin cannot claim its way past a missing grant. When a token is present, its `grantedCapabilities` claim is authoritative, and the in-memory granted set must also include the capability, so a revocation in Mission Control applies before a fresh token is minted. A capability outside the token claim returns `capability_denied`; one outside the in-memory set returns `permission_denied`. Operator-confirmed methods (`command.send`, `mission.write`) add their own gates after the capability check. See [Mission plugins](/developers/mission-plugins) for the mission write gates. ## UI slots There are 13 slots: 7 fleet-scoped and 6 per-node. A per-node contribution is bound to the selected node and is torn down and re-mounted when the operator switches nodes. Its capability token carries an `agentId` claim for that node, so the bridge rejects cross-node calls. | Slot id | Scope | Where it renders | | - | - | - | | `fc.tab` | Fleet | Tab inside the flight controller view. | | `hardware.tab` | Fleet | Tab on the Hardware page. | | `mission.template` | Fleet | Entry in the planner's pattern editor. | | `map.overlay` | Fleet | Layer drawn on the map view. | | `video.overlay` | Fleet | Layer on top of the live video pane. | | `notification.channel` | Fleet | Channel in the notification center. | | `settings.section` | Fleet | Section on the Settings page. | | `node.detail.tab` | Per-node | Tab in the node detail panel. | | `cockpit.panel` | Per-node | Panel in the cockpit quick-settings surface. | | `cockpit.widget` | Per-node | Iframe in a cockpit widget zone. | | `flight.skill` | Per-node | Skill in the cockpit Skill Bar, bindable to a hotkey or gamepad button. No iframe. | | `node.agent.page` | Per-node | Page in a node's Agent sidebar. | | `node.surface` | Per-node | Top-level node-detail surface. | `node.detail.tab`, `node.agent.page` and `node.surface` are narrowed by node profile: a contribution with a `profile` list mounts only on nodes of those profiles. An absent or empty list means every profile. `flight.skill` registers a Skill keyed to the active drone; the cockpit's arm and confirmation gates still apply when it runs. Declare contributions under `gcs.contributes` in the manifest. The full set of keys and their fields is in [Contribution points](/developers/contribution-points). ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} gcs: contributes: panels: - id: power-tab slot: fc.tab title: "Power" icon: "zap" order: 30 ``` Several plugins can target the same slot. `order` is a sorting hint the slot applies where it sorts. ## Slot orchestrator The host reads the enabled plugins, collects each plugin's contributions and mounts the bundle into the matching slot. The manifest decides which panel renders in which slot; the plugin cannot choose at runtime. Before a contribution mounts, the slot checks that the plugin holds the matching `ui.slot.` capability (for example `ui.slot.fc-tab`). A contribution without that grant is dropped, the operator sees a one-time warning toast, and the denial is logged. The bundle's entry point is `definePlugin`. The SDK calls `mount` once the frame document is ready, with a `PluginContext` and the plugin's id and version: ```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; import { mountUI } from "./ui"; definePlugin({ id: "com.example.battery", version: "0.1.0", mount(ctx, info) { // ctx exposes client, telemetry, perception, command, notifications, // recording, mission, config, events, records, theme and i18n. // info carries id and version. mountUI(ctx); }, unmount(ctx) { // optional teardown }, }); ``` ## Theming The host pushes a flat record of CSS variables on mount and on every theme change. Apply them where your UI needs them: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} ctx.theme.onChange((vars) => { for (const [k, v] of Object.entries(vars)) { document.documentElement.style.setProperty(k, v); } }); ``` The SDK does not apply them for you, so you choose the scope (whole document, one panel, or none). ## Error codes The SDK throws `HostError` with a machine-readable `code`. Branch on `code`, not on `message`. | Code | Meaning | | - | - | | `method_unknown` | The host has no handler for the method. | | `permission_denied` | The plugin's granted set does not include the required capability. | | `capability_denied` | The capability token's claim does not include the required capability. | | `handler_error` | The handler threw while running the call. | | `handler_unset` | The method exists but no handler is attached on this host. | | `refused` | The host refused the action: the operator denied a `command.send` or `mission.write`, a notification was rate-limited, or `recording.mark` ran with nothing recording. | | `timeout` | Raised by the client when the host does not answer in time. Operator-confirmed calls wait for the operator instead. | | `disposed` | Raised by the client when it is torn down with calls in flight. | ## Local iteration Build the GCS half against the harness in `@altnautica/plugin-sdk/harness`. It drives your `mount`, injects telemetry, applies the granted-capability check and records every RPC your bundle sends, without a running Mission Control. See the [TypeScript SDK](/developers/sdk-typescript) for the harness API. ## Next steps > [card] [Multi-component plugins](/developers/multi-component-plugins) > > Ship an agent half and a GCS half in one plugin. > [card] [Contribution points](/developers/contribution-points) > > Every `contributes` key and its fields. > [card] [GCS bridge methods](/developers/event-hooks) > > The methods a GCS half can call on the host. > [card] [Permissions](/developers/permissions) > > Capabilities, risk levels and the install grid. # Gimbal driver Source: https://docs.altnautica.com/developers/gimbal-driver Implement a GimbalDriver that moves a stabilised mount and reports its pointing state. > [!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 `GimbalDriver` moves a stabilised mount to a commanded attitude or rate, and reports the current pointing state. The first-party reference is `MavlinkGimbalDriver` in the MAVLink Gimbal v2 plugin ([`extensions/mavlink-gimbal-v2`](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/mavlink-gimbal-v2)). It drives any gimbal that speaks the MAVLink Gimbal Manager Protocol v2 (ArduPilot or PX4 forwarding; Storm32 NT and Gremsy in MAVLink mode). It ships no serial SimpleBGC, Storm32 or Gremsy drivers. ## The interface ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.drivers.gimbal import ( GimbalDriver, GimbalCandidate, GimbalCapabilities, GimbalSession, GimbalState, ) class MyGimbalDriver(GimbalDriver): async def discover(self) -> list[GimbalCandidate]: ... async def open(self, candidate, config) -> GimbalSession: ... async def close(self, session) -> None: ... def capabilities(self, session) -> GimbalCapabilities: ... async def command_attitude( self, session, pitch_deg, yaw_deg, roll_deg=0.0 ) -> None: ... async def command_rate( self, session, pitch_rate_dps, yaw_rate_dps, roll_rate_dps=0.0 ) -> None: ... def get_state(self, session) -> GimbalState: ... async def state_iterator(self, session): # async generator yielding GimbalState at the gimbal's update rate ... ``` > [!NOTE] > > Writing the agent half in Rust? Implement `ados_sdk::drivers::GimbalDriver` from the `ados-sdk` crate. It has the same methods as the Python base class (discover, open, close, capabilities, command\_attitude, command\_rate, get\_state, state\_iterator). Set `agent.runtime: rust` in the manifest. In Rust the angles are `f32`, and `command_rate` returns `DriverError::NotSupported` on a position-only mount. ## Capabilities ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} GimbalCapabilities( has_pitch=True, has_yaw=True, has_roll=False, pitch_min_deg=-135.0, pitch_max_deg=45.0, yaw_min_deg=-180.0, yaw_max_deg=180.0, roll_min_deg=0.0, roll_max_deg=0.0, max_rate_dps=120.0, supports_follow_mode=True, supports_lock_mode=True, ) ``` Limits are degrees from neutral. `max_rate_dps=None` means the gimbal is position-controlled only. ## State ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} GimbalState( timestamp_ns=ns, pitch_deg=-22.5, yaw_deg=10.0, roll_deg=0.0, pitch_rate_dps=0.0, yaw_rate_dps=0.0, roll_rate_dps=0.0, mode="follow", metadata=None, ) ``` Drivers that cannot report rates leave `*_rate_dps` at `0.0`. Put driver-specific status (fault codes, mount temperature, firmware version) under `metadata`. Your plugin's GCS half renders this data; publish it with `ctx.telemetry.extend` or `ctx.events.publish`. ## Region of interest ROI is not part of the `GimbalDriver` contract. A driver that supports it adds its own methods. The reference driver adds `set_roi_location` and `clear_roi`, which map to `MAV_CMD_DO_SET_ROI_LOCATION` (195) and `MAV_CMD_DO_SET_ROI_NONE` (197). ## Opening the driver from your plugin The reference plugin builds its driver in `on_start` around a router handle for the agent's MAVLink link, registers its MAVLink component, and feeds incoming `GIMBAL_DEVICE_ATTITUDE_STATUS` messages to `driver.on_attitude_status(...)`. See `agent/src/altnautica_gimbal_v2/plugin.py`. For MAVLink gimbals declare `mavlink.read`, `mavlink.write` and `mavlink.component.gimbal`; the full table is on [Driver layer](/developers/driver-layer#manifest-permissions). ## Testing without hardware Construct the driver against a mock MAVLink router. The reference plugin's `agent/tests/test_mavlink_driver.py` shows the round trip: command pitch -30 and yaw 45, capture the encoded `COMMAND_LONG`, feed a `GIMBAL_DEVICE_ATTITUDE_STATUS` sample through `driver.on_attitude_status(...)`, and assert the state updates. ## Next steps > [card] [Driver layer](/developers/driver-layer) > > The shared contract and the manifest table. > [card] [MAVLink extensions](/developers/mavlink-extensions) > > Own a MAVLink component id from a plugin. > [card] [Hardware testing](/developers/hardware-testing) > > Mock routers and SITL. > [card] [LiDAR driver](/developers/lidar-driver) > > The next driver kind. # Plugin glossary Source: https://docs.altnautica.com/developers/glossary The vocabulary the plugin system uses, in one page. Site-wide terms are in the main glossary. This page covers plugin and SDK terms. For nodes, profiles, roles, pairing and the other site-wide terms, see the [Glossary](/getting-started/glossary). | Term | Meaning | | - | - | | **Plugin** | A signed `.adosplug` archive that adds code or UI to ADOS. It has up to two halves, agent and GCS. Operators see installed plugins as **Extensions**. | | **Extension** | The operator-facing name for an installable plugin, used in Mission Control and the agent dashboard. First-party extensions are published from the public `ADOSExtensions` repo in the same archive format as a third-party plugin. | | **Manifest** | The `manifest.yaml` at the root of the archive. Declares the id, version, halves, permissions and contributions. It carries no asset-hash list; integrity comes from the canonical payload hash in the separate `SIGNATURE` file. | | **Half** | The part of a plugin that runs on one side of the system. The `agent` half runs on the node and is written in Python or Rust (`agent.runtime`); the `gcs` half runs in Mission Control and is written in TypeScript. | | **Slot** | A named mount point in the Mission Control UI, such as `fc.tab`, `node.detail.tab`, `cockpit.widget` or `flight.skill`. The full list is in [Contribution points](/developers/contribution-points#the-slot-taxonomy). | | **Capability** | A runtime grant derived from a manifest permission the operator granted. Required for every privileged call. | | **Capability token** | The signed string that carries a plugin's granted capabilities on the wire. HMAC-SHA256 under the host's issuer key, 10-minute lifetime, re-minted by the host. | | **Risk band** | `low`, `medium`, `high` or `critical`. The plugin's band is the manifest's declared top-level `risk` (default `medium`); each capability also carries its own risk badge in the install dialog. | | **Sandbox** | The isolation boundary a half runs inside: a hardened systemd unit and cgroup on the agent, a null-origin iframe on the GCS. | | **Bridge** | The host code between a sandbox and the rest of the application. It validates the envelope, resolves the required capability and routes the call to a handler. | | **Bundle** | The built JavaScript for the GCS half: a single ESM file the host loads into the iframe from a `blob:` URL. | | **Entrypoint** | What the agent half launches, from `agent.entrypoint`. Python: `module:Class`, or a file path such as `agent/plugin.py` that defines a class `Plugin`. Rust: a binary path, or `bin:` resolved through `agent.binaries`. | | **Vendor binary** | A third-party executable or library bundled in the agent half. With `agent.contains_vendor_binary: true` the manifest must list at least one `agent.vendor_attribution` entry, or it fails validation. See [Vendor binaries](/developers/vendor-binaries). | | **Per-drone plugin** | A plugin with `agent.per_drone_config: true`: one install runs one process per connected drone, each with its own `ctx.agent_id` and its own config. The default is one process for the node. | | **Permission** | A request for one slice of authority, declared in the manifest and granted by the operator. | | **Operator** | The person running ADOS. Grants and revokes permissions from the node's **Extensions** tab or with `ados plugin perms`. A grant or revoke takes effect at runtime, with no agent restart. | | **Publisher** | Whoever holds the Ed25519 private key a plugin is signed with. | | **Signer id** | The name of a publisher key. It is the file stem of the enrolled public key on the agent (`.pem`) and the first line of the archive's `SIGNATURE` file. The first-party signers are `altnautica-2026-A` and `altnautica-2026-B`. Create a key with `ados plugin keygen `. | | **Trust list** | The public keys a node accepts, as PEM files under `/etc/ados/plugin-keys/`, keyed by signer id. See [Signing keys](/developers/signing-keys). | | **Revocation list** | `/etc/ados/plugin-revocations.json`: signer ids and archive digests the node refuses. See [Revocation and incidents](/developers/revocation-and-incidents). | | **Two-stage install** | The install flow: `parse` returns a manifest preview without writing anything; `install` commits only after the operator approves the permissions. | | **`.adosplug`** | The file extension of a plugin archive: a zip with `manifest.yaml` at the root and a `SIGNATURE` entry. | | **PluginContext** | The object an SDK hands plugin code. In TypeScript it has `telemetry`, `perception`, `command`, `notifications`, `recording`, `mission`, `config`, `events`, `records`, `theme` and `i18n`. The Python and Rust contexts are listed on their SDK pages. | | **PluginHarness** | The synthetic host from `@altnautica/plugin-sdk/harness`. Unit tests push telemetry into the plugin and assert on the calls it made, with no Mission Control running. | ## Next steps > [card] [Concepts](/developers/concepts) > > How the manifest, signature, sandbox and tokens fit together. > [card] [Your first plugin](/developers/your-first-plugin) > > Build and install a working plugin. # GPS driver Source: https://docs.altnautica.com/developers/gps-driver Implement a GpsDriver that decodes fixes from a GNSS receiver and accepts RTCM corrections. > [!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 `GpsDriver` decodes a position-fix stream from a u-blox, NMEA, RTK or vendor-specific receiver into `GpsFix` samples. Drivers for RTK receivers also accept RTCM correction payloads. ## The interface ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.drivers.gps import ( GpsDriver, GpsCandidate, GpsCapabilities, GpsSession, GpsFix, ) class MyGpsDriver(GpsDriver): async def discover(self) -> list[GpsCandidate]: ... async def open(self, candidate, config) -> GpsSession: ... async def close(self, session) -> None: ... def capabilities(self, session) -> GpsCapabilities: ... async def fix_iterator(self, session): # async generator yielding GpsFix ... async def inject_rtcm(self, session, payload: bytes) -> None: ... ``` Receivers without RTK must raise `NotImplementedError` (Python) or return `DriverError::NotSupported` (Rust) from `inject_rtcm`. Never drop corrections silently. > [!NOTE] > > Writing the agent half in Rust? Implement `ados_sdk::drivers::GpsDriver` from the `ados-sdk` crate. It has the same methods as the Python base class (discover, open, close, capabilities, fix\_iterator, inject\_rtcm). Set `agent.runtime: rust` in the manifest. The Rust trait uses an associated `Session` type and returns a `SampleStream` (a boxed async stream) from `fix_iterator`: ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} use std::collections::BTreeMap; use async_trait::async_trait; use rmpv::Value; use ados_sdk::drivers::{ DriverResult, GpsCandidate, GpsCapabilities, GpsDriver, GpsFix, SampleStream, }; struct MySession; struct MyGpsDriver; #[async_trait] impl GpsDriver for MyGpsDriver { type Session = MySession; async fn discover(&self) -> DriverResult> { todo!() } async fn open( &self, candidate: &GpsCandidate, config: &BTreeMap, ) -> DriverResult { todo!() } async fn close(&self, session: Self::Session) -> DriverResult<()> { todo!() } fn capabilities(&self, session: &Self::Session) -> GpsCapabilities { todo!() } async fn fix_iterator( &self, session: &Self::Session, ) -> DriverResult> { todo!() } async fn inject_rtcm( &self, session: &Self::Session, payload: &[u8], ) -> DriverResult<()> { todo!() } } ``` `GpsFix` and `GpsCapabilities` carry the same fields in both languages. ## Capabilities ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} GpsCapabilities( protocol="ubx", constellations=["GPS", "GLONASS", "Galileo", "BeiDou"], max_update_hz=10.0, supports_rtk=True, supports_dual_band=False, supports_heading=False, ) ``` ## Fix samples ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} GpsFix( timestamp_ns=ns, latitude_deg=-33.8568, longitude_deg=151.2153, altitude_msl_m=12.0, fix_type=3, satellites_used=14, hdop=0.9, vdop=1.4, speed_mps=0.0, heading_deg=None, ) ``` `fix_type` follows the common convention: 0 no fix, 2 2D, 3 3D, 4 DGPS, 5 RTK float, 6 RTK fixed. `horizontal_accuracy_m`, `vertical_accuracy_m`, `course_deg` and `metadata` are optional. ## Opening the driver from your plugin Your plugin calls `discover()`, `open()` and consumes `fix_iterator` itself, and calls `inject_rtcm` with corrections it receives. The pattern is on [Driver layer](/developers/driver-layer#running-a-driver-from-your-plugin). A serial or USB-CDC receiver needs `hardware.uart`. `inject_rtcm` writes over the link the driver already opened, so it needs no extra capability. ## Next steps > [card] [Driver layer](/developers/driver-layer) > > The shared contract and the manifest table. > [card] [Hardware testing](/developers/hardware-testing) > > Test with a mock serial backend. > [card] [ESC driver](/developers/esc-driver) > > The next driver kind. # Hardware testing Source: https://docs.altnautica.com/developers/hardware-testing Test a plugin with mock backends, the SDK harnesses, ArduPilot SITL and a bench rig. A plugin's tests run on four surfaces, in order of cost and fidelity. All three SDKs ship a test harness: `ados.sdk.testing` in Python, `ados_sdk::testing` in Rust, and `@altnautica/plugin-sdk/harness` in TypeScript. ## 1. Agent-side unit tests with a mock backend The cheapest pass. Driver plugins ship a mock backend that the driver constructor accepts in place of the real device: the FLIR Lepton plugin ships `MockUvcBackend`, and the MAVLink Gimbal v2 plugin ships a mock router. For a Python agent half, `ados.sdk.testing` adds `PluginTestHarness`, `FakeVisionEngine` and `load_fixture`. `PluginTestHarness` wires an in-process plugin context to a fake IPC client, so lifecycle hooks run under `pytest` without the plugin host, sockets or subprocesses. Grant capabilities explicitly and assert against captured events. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import pytest @pytest.mark.asyncio async def test_open_yields_correct_capabilities(): backend = MockUvcBackend(width=160, height=120) driver = LeptonUvcDriver(backend) candidate = (await driver.discover())[0] session = await driver.open(candidate, {}) caps = driver.capabilities(session) assert caps.width == 160 assert caps.radiometric is True ``` Run the suite through the agent CLI, which validates the manifest first and sets the harness environment: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin test ./my-plugin ados plugin test ./my-plugin --tests-dir tests -k capabilities --json ``` For a Rust agent half, `ados_sdk::testing::FakeVisionEngine` emits synthetic frames through the same callback a plugin registers with `ctx.vision.subscribe_frames`, and captures the detections the plugin publishes: ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} use ados_sdk::testing::FakeVisionEngine; use ados_protocol::framebus::FrameFormat; #[tokio::test] async fn detects_a_solid_frame() { let mut engine = FakeVisionEngine::new("uvc-0", 64, 48, FrameFormat::Rgb24); engine.push_solid(0x80); engine.deliver_all(); // assert against the captured detection sink } ``` See the `FakeVisionEngine` tests in `crates/ados-sdk/src/testing/mod.rs` for a worked example. ## 2. The plugin harness, GCS side `@altnautica/plugin-sdk/harness` mounts your plugin against an in-memory transport, captures every RPC, and lets you inject telemetry, events, config changes and theme updates without running Mission Control. ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { createPluginHarness } from "@altnautica/plugin-sdk/harness"; const harness = createPluginHarness({ grantedCapabilities: ["telemetry.subscribe.battery"], mount: async (ctx) => { await ctx.telemetry.subscribe("battery", store.ingest); }, }); await harness.start(); harness.pushTelemetry("battery", mockSample); expect(harness.notifications).toMatchObject([{ severity: "warning" }]); await harness.teardown(); ``` The full harness reference is on [TypeScript SDK](/developers/sdk-typescript). ## 3. SITL (software in the loop) ArduPilot SITL covers the flight-controller side: arming, modes, missions, parameters, mount commands and ROI. The agent binds TCP 5760 itself, so SITL on the same host at 5760 collides. Run SITL (`sim_vehicle.py`) on another machine, or expose it on another port, then point the agent at it: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} mavlink: source: tcp serial_port: "tcp:192.168.1.50:5770" ``` SITL does not simulate cameras, LiDARs, payloads or vendor serial protocols. For those, use the mock backend. > [!WARNING] > > SITL tests that arm, take off or upload missions use the same commands as a real vehicle. Read [Safety](/operations/safety) before pointing a test at real hardware. ## 4. Hardware in the loop on a bench rig The full pass: a real board with the agent installed, the real device on USB or serial, and your plugin packed and installed with `ados plugin install `. Bench testing closes the loop on accuracy, timing jitter, hotplug behaviour and vendor-binary integration. Run it before you tag a release. A good bench session captures: * The plugin's log while you exercise the device: `ados plugin logs --follow`. The file lives at `/var/log/ados/plugins/-.log`; find the unit with `systemctl list-units 'ados-plugin-*'`. * A telemetry log over the test window. * A photo or short video of the rig and the device under test. Attach them to your release notes. ## What the reference plugins ship | Plugin | Mock backend | Harness | SITL | Bench | | - | - | - | - | - | | FLIR Lepton USB UVC | `MockUvcBackend` | yes | n/a | not published (no UVC backend) | | MAVLink Gimbal v2 | mock router | yes | no (mock router) | before each release tag | ## Next steps > [card] [Linting](/developers/linting) > > Analyze the packed archive. > [card] [Python SDK](/developers/sdk-python) > > The `ados.sdk.testing` reference. # Legal and licensing Source: https://docs.altnautica.com/developers/legal-and-licensing Plugin ownership, licence declaration, how each SDK licence interacts with yours, vendor binaries, trademarks and warranty. You wrote your plugin and you keep the rights to it. The registry is one distribution channel among several and does not change who owns or licenses what. How you sell, support or license your plugin is between you and your users. ## Declare a licence Declare the licence in the manifest with an SPDX identifier or expression: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} license: "GPL-3.0-or-later" # or license: "Apache-2.0" # or license: "LicenseRef-MyProductEULA-1.0" ``` For SPDX ids see [spdx.org/licenses](https://spdx.org/licenses/). For a custom licence use the `LicenseRef-` form and ship the full text in the archive as `LICENSE.txt`. The agent does not gate installs by licence; operators see the declared string in the install review. ## SDK licences The agent is GPL-3.0-or-later and Mission Control is GPL-3.0-only. The SDKs differ: * The Rust crates `ados-sdk` and `ados-protocol` are `MIT OR Apache-2.0`. A Rust agent half that statically links them may use any licence, including a proprietary one. * `@altnautica/plugin-sdk` and the Python `ados.sdk` are GPL-3.0-or-later. A GCS bundle built with `@altnautica/plugin-sdk` contains SDK code, and a Python agent half imports `ados.sdk` inside the agent's GPL plugin runner. For those two GPL SDKs the licence matters more than the process boundary. The agent runs every agent half as its own subprocess over a defined IPC surface, and Mission Control runs plugins in a sandboxed iframe that talks over `postMessage`. No plugin runs in-process. Even so, get legal advice before shipping a plugin that uses a GPL SDK under a licence that is not GPL-compatible. Altnautica is not your lawyer. A proprietary vendor library loaded by your plugin runs inside your plugin's process. You are responsible for whether its licence allows distribution with your plugin; see [Vendor binaries](/developers/vendor-binaries). ## Distribution channels | Channel | Hosting | Licence requirement | | - | - | - | | Local file install | The operator copies a `.adosplug` to the node. | Any licence. | | URL install | Archive on a GitHub release (or another allowlisted host). | Any licence. The agent verifies the signature, not the licence. | | Registry | The registry hosts the archive. | You grant the registry operator the right to redistribute it. | Every registry submission is reviewed. OSS-licensed, clean-scanning submissions are marked ready for review; everything else is queued for closer review. See [Catalog and registry](/developers/distribution-registry#submit-a-plugin). ## Vendored binaries Declare vendor binaries on the agent half with `contains_vendor_binary` and `vendor_attribution` (full schema on [Vendor binaries](/developers/vendor-binaries)): * Each attribution entry carries its own required `license`. Ship the full licence text in the archive too. * Your plugin's own `license` is independent of the vendor's. * `ados plugin lint` does not inspect vendor binaries; you are responsible for what you ship. * Operators see the attribution in the install review. If a vendor licence forbids redistribution, the registry cannot host the plugin. ## Trademarks The names "ADOS" and "Altnautica" and the Altnautica, Mission Control and Drone Agent logos are reserved. Do not use them in a plugin name, description or icon. You may state compatibility ("Works with the ADOS Drone Agent", "for ADOS Mission Control"), link to the docs, and declare `compatibility.ados_version` in your manifest. Your reverse-DNS plugin id (`com.your-name.something`) makes namespace ownership explicit. ## The registry's role The registry redistributes signed archives that publishers upload and does not modify their bytes. Its submission scan is a defense-in-depth measure, not a quality endorsement or a security audit. A plugin's runtime behavior is its publisher's responsibility. ## No warranty The agent (GPL-3.0-or-later) and Mission Control (GPL-3.0-only) carry no warranty. Plugins distributed through the registry come with no warranty from Altnautica; your plugin's licence governs what you warrant. Verified-publisher status is set by the registry operator and is not a warranty. The catalog is served from the Convex backend; a self-hosted backend serves its own catalog. No availability terms are published for the hosted registry. Security reporting is on [Revocation and incidents](/developers/revocation-and-incidents#reporting-a-security-issue). Give your own users a private reporting channel in your plugin's README. ## Next steps > [card] [Publish to ADOSExtensions](/developers/contributing-repos) > > Contribute a plugin to the first-party repo. > [card] [Revocation and incidents](/developers/revocation-and-incidents) > > Report a security issue. # LiDAR driver Source: https://docs.altnautica.com/developers/lidar-driver Implement a LidarDriver that yields point-cloud frames from a ranging sensor. > [!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 `LidarDriver` yields point-cloud frames from a spinning, solid-state or single-line ranging device. ## The interface ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.drivers.lidar import ( LidarDriver, LidarCandidate, LidarCapabilities, LidarSession, LidarFrame, LidarPoint, ) class MyLidarDriver(LidarDriver): async def discover(self) -> list[LidarCandidate]: ... async def open(self, candidate, config) -> LidarSession: ... async def close(self, session) -> None: ... def capabilities(self, session) -> LidarCapabilities: ... async def frame_iterator(self, session): # async generator yielding LidarFrame ... async def set_param(self, session, param, value) -> None: # rpm, scan rate, filter mode ... ``` > [!NOTE] > > Writing the agent half in Rust? Implement `ados_sdk::drivers::LidarDriver` 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. ## Capabilities ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} LidarCapabilities( min_range_m=0.1, max_range_m=40.0, horizontal_fov_deg=360.0, vertical_fov_deg=1.0, points_per_frame=1024, fps=10.0, has_intensity=True, has_dual_return=False, ) ``` ## Frames Each `LidarFrame` holds `timestamp_ns`, `sequence`, optional `metadata`, and `points`, a tuple of `LidarPoint` in the sensor body frame: `+x` forward, `+y` left, `+z` up, in metres. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} LidarPoint( x=2.13, y=-0.42, z=0.05, intensity=0.74, return_index=0, ) ``` Drivers that get no return at some angles skip those points rather than emit zeros. ## Single-line and spinning sensors The driver layer does not distinguish single-beam rangefinders from 3D LiDARs. A 1D rangefinder yields frames with `points_per_frame=1`. ## Opening the driver from your plugin Your plugin calls `discover()`, `open()` and consumes `frame_iterator` itself, then publishes what it derives (nearest obstacle, a downsampled scan) with `ctx.telemetry.extend` or `ctx.events.publish`. The pattern is on [Driver layer](/developers/driver-layer#running-a-driver-from-your-plugin). Most LiDARs need `hardware.uart` or `hardware.usb`. ## Next steps > [card] [Driver layer](/developers/driver-layer) > > The shared contract and the manifest table. > [card] [Hardware testing](/developers/hardware-testing) > > Replay recorded data when no sensor is on the bench. > [card] [GPS driver](/developers/gps-driver) > > The next driver kind. # Plugin lifecycle Source: https://docs.altnautica.com/developers/lifecycle Parse, install, enable, disable and remove: the states a plugin moves through, the hooks each half gets, and how config reaches a running plugin. A plugin moves through a small set of recorded states. The agent's plugin host is the state machine; the plugin reacts to the lifecycle hooks its runtime calls. ## States The host records one status per installed plugin in `/var/ados/state/plugin-state.json`. The record describes the agent half; the GCS half has no recorded state of its own. | State | Meaning | | - | - | | `installed` | Archive unpacked, manifest validated, signature accepted. The plugin is dormant. | | `enabled` | The operator switched it on; the unit is being started. | | `running` | The agent half's unit was started. | | `disabled` | The operator switched it off, or the host disabled it because its signer, archive or release was revoked (the reason is recorded). The unit is stopped; data on disk is kept. | Grants are recorded per permission and are independent of enable and disable. `failed` and `incompatible` are reserved states the current host does not assign. Removal deletes the install record rather than moving it to a state. ## Parse before install The install flow is two-stage: 1. **Parse**: the agent opens the archive in memory, validates the manifest, verifies the Ed25519 signature, and returns a summary. Nothing is written to disk. 2. **Install**: only after the operator approves does the agent commit. It checks compatibility (`ados_version`, board, tier, `target_profiles` against the node's profile, and a binary for the host architecture), downloads and verifies any `payloads`, then unpacks the archive into `/var/ados/plugins//`. Previewing an archive leaves no trace. See [Permissions](/developers/permissions#two-stage-install) for what the operator sees. ## Enable and disable Enable is the first time the plugin runs. For an agent half the host writes a service unit and starts it. On Linux that is a systemd unit named `ados-plugin--.service` (dots in the id as hyphens, `` the first 8 hex digits of the SHA-256 of the id), plus one `ados-plugin---.service` per declared service, in the shared `ados-plugins.slice`. On macOS it is a per-user LaunchAgent named `co.ados.plugin.-`; because launchd provides no sandbox, only first-party plugins install there. Mission Control mounts the GCS half in each slot it contributes to: in an iframe, or inline for a first-party `gcs.isolation: inline` module. Disable stops the unit. Data on disk persists, and re-enable resumes from where it left off. ## Restarts A plugin unit restarts on failure every 2 s with no start limit (`Restart=on-failure`, `RestartSec=2s`, `StartLimitIntervalSec=0`). A crash-looping plugin stays `running` in the record; check `systemctl status` and the plugin log (see [Troubleshooting](/developers/troubleshooting#the-agent-half-crashes-or-restarts)). ## Lifecycle hooks (agent half) Every hook is optional. The runner looks each one up on your plugin instance and awaits it if it returns a coroutine; a hook you do not define is skipped. The runner is one process per plugin (one per drone with `per_drone_config: true`). Each time the unit starts, the runner calls the startup hooks in a fixed order, waits for the stop signal, then calls the teardown hooks. It keeps no marker across restarts, so the full sequence runs on every process start. | Hook | When the runner calls it | | - | - | | `on_install(ctx)` | First, on every process start. Keep the body idempotent. | | `on_enable(ctx)` | Second, after `on_install`. | | `on_configure(ctx, config)` | Third, with the static config loaded at start (an empty dict when none is on disk). | | `on_start(ctx)` | Fourth. The usual place to subscribe to events and begin work. | | `on_stop(ctx)` | On shutdown (SIGTERM or SIGINT, or the host connection dropping), before the process exits. | | `on_disable(ctx)` | On shutdown, right after `on_stop` (skipped when the process stops because the host connection dropped). | Most plugins only need `on_start` and `on_stop`. An agent plugin is a plain class with no base class to subclass, named by a `module:Class` entrypoint; a file-path entrypoint loads a class named `Plugin`. The `ctx` argument is the plugin context; see the [Python SDK](/developers/sdk-python). ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} class TelemetryLoggerPlugin: async def on_start(self, ctx) -> None: self._ctx = ctx await ctx.events.subscribe("vehicle.armed", self._on_armed) ctx.log.info("started") async def on_stop(self, ctx) -> None: ctx.log.info("stopped") async def _on_armed(self, event: dict) -> None: self._ctx.log.info("armed_event", payload=event) ``` A Rust plugin implements the same hooks on the `Plugin` trait; see the [Rust SDK](/developers/sdk-rust). ## Lifecycle hooks (GCS half) The GCS half exposes `mount` and `unmount` through `definePlugin`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; definePlugin({ id: "com.example.lifecycle", version: "0.1.0", async mount(ctx, info) { console.info(`mounted ${info.id} v${info.version}`); }, async unmount(ctx, info) { console.info(`unmounting ${info.id}`); }, }); ``` `mount` runs once the bundle loads. When the operator closes the surface, switches drone, disables or removes the plugin, Mission Control asks the frame to unmount, waits up to 500 ms, and then destroys the iframe. Keep `unmount` short and do not rely on it to persist state; write state as it changes. For your own teardown, call the `unmount()` of the instance `definePlugin` returns; it runs your `unmount`. ## Remove `ados plugin remove ` (or **Uninstall** on the **Extensions** tab) tears the plugin out: 1. Stop the unit if running. 2. Delete the unit file and any declared service units, then reload the service manager. 3. Remove the install directory `/var/ados/plugins//`. 4. Drop the install record from the state file. Without `--keep-data`, remove also deletes the plugin's log, its data directory `/var/ados/plugin-data//` and its system user. `--keep-data` keeps all three, so a reinstall picks up where it left off. ## Configuration changes On the agent side, `ctx.config` is the static dict loaded when the process starts and passed to `on_configure`. To pick up a later edit without a restart, read live values with `await ctx.config_kv.get(key, default)` at the point of use rather than caching the dict. On the GCS side, `ctx.config.onChange` delivers the plugin's config on mount and after every accepted write. See [GCS bridge methods](/developers/event-hooks#host-pushed-events). ## State observability `ados plugin info ` prints the record, and `ados plugin logs ` prints the agent half's log. In Mission Control the **Extensions** tab shows each plugin's status. ## Next steps > [card] [Plugin CLI reference](/developers/cli-reference) > > Drive the lifecycle from a shell. > [card] [Troubleshooting](/developers/troubleshooting) > > When a plugin will not install or will not stay up. # Linting Source: https://docs.altnautica.com/developers/linting Run the local static analyzer on a packed plugin and the manifest-versus-code check before you release. `ados plugin lint` is a local, advisory analyzer. It unpacks a packed archive and checks every entry against a fixed rule set. The registry runs its own, narrower scan at submission, and every submission is reviewed before it is published (see [Catalog and registry](/developers/distribution-registry#submit-a-plugin)). ## Quickstart ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin lint extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug ``` Output: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} plugin com.example.my-plugin 1.0.0 archive size: 18432 bytes score: 100/100 verdict: pass no findings. ``` JSON form for CI: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin lint --json extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug \ | jq '.data.score, .data.passed' ``` Exit code 0 means pass. Exit code 1 means at least one finding at severity `error` or `critical`. The other exit codes are on the [Plugin CLI reference](/developers/cli-reference). ## What it checks Findings are keyed by rule id, with a severity and the source location. ### Python rules | Rule | Severity | What it flags | | - | - | - | | PY001-os-system | error | `os.system()` call | | PY002-os-popen | error | `os.popen()` call | | PY003-eval | error | `eval()` call | | PY004-exec | error | `exec()` call | | PY005-subprocess-shell | error | `subprocess` call with `shell=True` | | PY006-raw-socket | error | `socket.socket(...)` | | PY007-pickle-load | error | `pickle.load()` or `pickle.loads()` | | PY008-marshal-loads | error | `marshal.load()` or `marshal.loads()` | | PY009-ctypes-load | error | Native library load via `ctypes.CDLL` and friends | | PY020-requests | warn | `requests`, `httpx`, `aiohttp`, `urllib3` or `urllib.request` used without `network.outbound` | | FS001-open-write | info | File opened for writing (check the path is under the plugin's data, config or temp dir) | | FS002-shutil-rmtree | info | `shutil.rmtree()` (check the scope is the plugin's own directory) | ### GCS bundle rules | Rule | Severity | What it flags | | - | - | - | | GCS001-top-location | warn | Reads `top.location` or `parent.location` | | GCS002-document-cookie | warn | Reads `document.cookie` | | GCS003-localstorage | warn | Reads `localStorage` or `sessionStorage` | | GCS004-eval | warn | `eval()` call in the bundle | | GCS005-function-ctor | warn | `new Function(...)` | | GCS006-fetch-direct | warn | Direct `fetch()` call (use the host bridge) | | GCS007-xhr-direct | warn | Direct `XMLHttpRequest` | | GCS008-websocket-direct | warn | Direct `WebSocket` | ### Manifest and archive rules | Rule | Severity | What it flags | | - | - | - | | ARC001-archive-size | error | Archive exceeds the 50 MB archive cap | | ARC002-entry-size | error | A single entry exceeds the 25 MB per-entry cap | | ARC003-read-fail | error | An archive entry could not be read | | SIG001-unsigned | warn | Archive carries no `SIGNATURE` file | | VND001-vendor-binary | info | The manifest sets `agent.contains_vendor_binary` (see [Vendor binaries](/developers/vendor-binaries)) | | PERM001-high-risk | info | The manifest declares any capability rated high or critical, for example `mavlink.write`, `process.spawn`, `estimator.pose.inject`, `flight.rate_setpoint` | `info` findings are advisory. `warn` findings show in the report but still pass. `error` and `critical` findings fail. Risk ratings come from the capability catalog on [Permissions](/developers/permissions). ## Score Each finding deducts points, with a floor of 0: | Severity | Penalty | | - | - | | info | 0 | | warn | 2 | | error | 10 | | critical | 25 | The score is for your own tracking. The verdict, not the score, sets the exit code. ## Network imports and permissions If your plugin uses `requests`, `httpx`, `aiohttp`, `urllib3` or `urllib.request`, the linter warns unless the manifest declares `network.outbound`. The host enforces the capability at runtime either way. ## False positives The rules are plain pattern matches. A finding can fire on a comment or a data file. If a finding is wrong for your case, open an issue on the agent repo with the archive and the finding. ## Manifest-versus-code check (monorepo) Inside the ADOSExtensions monorepo, each extension's GCS package has a `lint:manifest` script that checks the manifest against the code it describes: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pnpm -C extensions/my-plugin/gcs lint:manifest ``` It runs `node scripts/lint-manifest.mjs ../manifest.yaml` and exits 1 with one `FAIL` line per disagreement: 1. A `telemetry.subscribe.` permission with no matching `ctx.telemetry.subscribe("")` call, or a subscribe call with no matching permission. 2. A host-surface permission with no call site, on either half. On the agent half this includes every `hardware.*` permission. 3. A `contributes` slot with no implementation. 4. A version that disagrees across `manifest.yaml`, the extension `package.json`, `gcs/package.json`, the `definePlugin({ version })` literal, and the agent half's `pyproject.toml` or `Cargo.toml`. 5. A permission id that is neither in the capability catalog nor scoped to the plugin as `plugin..<...>`, where `` is the last segment of the manifest id. 6. A `documentation_url` on the docs site whose page does not exist in a sibling `Documentation` checkout. The check is skipped with a note when no checkout is present; `ADOS_DOCS_ROOT` overrides the path. 7. An agent config read of a key that is in neither `config-schema.json`, a manifest `config_key:`, nor an agent write of that key. `node scripts/lint-manifest.mjs --self-test` runs every case under `scripts/lint-fixtures/`. The repo's `extensions.yml` workflow runs the manifest lint for each extension, together with a manifest schema check against the agent's schema and the extension's tests. ## Run before every release ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ./scripts/pack.sh my-plugin ADOS_SIGNING_KEY=keys/acme-2026-A.priv.pem ADOS_SIGNING_KEY_ID=acme-2026-A \ ./scripts/sign.sh extensions/my-plugin/dist/com.example.my-plugin-1.0.0.adosplug ados plugin lint \ extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug ``` Run the same steps in your release workflow before the GitHub Release upload, and let a failing lint block the release. ## Next steps > [card] [Local install](/developers/distribution-local-install) > > Pack, sign and install the archive. > [card] [Signing keys](/developers/signing-keys) > > Generate and enrol your publisher key. > [card] [Permissions](/developers/permissions) > > Capability risk levels. # Plugin manifest reference Source: https://docs.altnautica.com/developers/manifest Every field of a plugin's manifest.yaml, in dependency order. The manifest is the entire contract between a plugin and the host. Get it right and everything else (install, permission grants, slot mounting, capability checks) falls into place automatically. ## File location `manifest.yaml` lives at the root of the `.adosplug` archive. The host opens the archive, reads the manifest first, and refuses to unpack anything else if the manifest fails validation. ## Top-level shape Identity and configuration live as flat top-level keys. There is no `plugin:` wrapper. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} schema_version: 1 # 1, 2, or 3 id: com.example.thermal version: "1.0.0" name: "Example Thermal" description: "One sentence." author: "Example Author" homepage: "https://example.com/thermal" license: "GPL-3.0-or-later" risk: medium # low | medium | high | critical compatibility: # required agent: # optional, agent half gcs: # optional, GCS half ``` At least one of `agent` or `gcs` must be present. The host accepts plugins that ship only one half; the `com.example.hello-panel` plugin in [Your first plugin](/developers/your-first-plugin), for example, is GCS-only. | Field | Type | Notes | | - | - | - | | `schema_version` | int | `1` baseline. `2` unlocks the v2 agent fields (`vendor_attribution`, `subprocess_spawn`, `per_drone_config`, `target_profiles`). `3` unlocks the MCP `tools` / `resources` / `prompts` contributions on both halves. Values outside 1 to 3 are rejected. Every version parses an identical-shape older manifest, so the field is informational: it lets tooling route on schema generation. | | `id` | string | Reverse-DNS, lowercase, dotted. Validated against the plugin-id pattern. | | `version` | string | Semver. | | `name` | string | Operator-facing display name. | | `description` | string | One short sentence. | | `author` | string | Free-form. | | `homepage` | url | Optional. | | `license` | string | SPDX expression. `GPL-3.0-or-later` recommended. | | `risk` | enum | `low`, `medium`, `high`, `critical`. Defaults to `medium`. | The manifest also accepts optional install-dialog content fields the GCS renders for a richer pre-install summary (`description_long`, `features`, `hardware_requirements`, `resource_impact`, `required_fc_parameters`, `telemetry_fields`, `documentation_url`, `screenshots`). The agent does not interpret any of them. ## `compatibility` | Field | Notes | | - | - | | `ados_version` | Required. Semver range. Checked by the agent at install for every plugin, including GCS-only ones. | | `gcs_version` | Optional. Semver range matched against the running Mission Control build. | | `supported_boards` | Optional list of board tokens. Each entry is a board id (the HAL profile stem, such as `cm4` or `rock-5c-lite`) or a SoC (such as `rk3588s2`), compared case-insensitively, or `"*"` for any board. An empty list (the default) also means any board. The agent refuses install or enable on a board that matches no entry. The tokens for each board are listed on [Supported hardware](/drone-agent/supported-hardware). | | `min_tier` | Optional integer 1 to 4. Minimum compute-class tier the plugin needs. The supervisor refuses install or enable on a board whose detected tier is below this; a board with an unknown tier is never blocked. | Node profiles are declared on the agent half (`agent.target_profiles`), not here. ## `agent` ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: entrypoint: "agent/plugin.py" isolation: "subprocess" # the only mode the agent runs runtime: "python" # python (default) or rust permissions: - id: event.publish - id: mavlink.read resources: class: standard # standard (default) or heavy (first-party only) max_ram_mb: 96 # default 96, range 8 to 4096 (heavy: 65536) max_cpu_percent: 25 # default 25, range 1 to 100 (heavy: 3200) max_pids: 12 # default 12, range 1 to 256 (heavy: 4096) target_profiles: ["drone"] # subset of drone, ground-station, workstation, compute http: false # serve an HTTP API under /api/plugins//x/ binaries: {} # per-architecture binaries, referenced as bin: payloads: [] # files fetched at install instead of packed declared_capabilities: [] # capabilities this plugin defines for its own data contributes: services: [] # optional extra service units shared_topics: [] # event-bus topics this plugin owns ``` `entrypoint` is a relative path inside the archive (no absolute paths, no `..`). For a file-path entrypoint like `agent/plugin.py` the runner loads a class named `Plugin`. A `module:Class` entrypoint is also accepted and is how built-in plugins declare themselves. A `runtime: rust` entrypoint may instead be `bin:`, resolved through [`binaries`](#per-architecture-binaries). `isolation: subprocess` is the default and the only mode the agent runs. An `inprocess` manifest parses but is refused at install, whoever signed it: every plugin runs as its own unit. `runtime: rust` runs the entrypoint as its own binary. ### Agent field reference | Field | Type | Default | Notes | | - | - | - | - | | `entrypoint` | string | required | A `module:Class` id (built-in plugins), a relative path to the half's entrypoint inside the archive, or `bin:` naming a `binaries` entry (`runtime: rust` only). No `..`, no absolute path. | | `isolation` | enum | `subprocess` | `subprocess` is the only mode the agent runs. `inprocess` is refused at install. | | `runtime` | enum | `python` | `python` runs the entrypoint under the shared Python runner; `rust` execs the plugin's own cross-compiled binary directly under the service manager. Older manifests without the field load as `python`. | | `permissions` | list | `[]` | Capability requests. See [permission shape](#permission-shape). | | `resources` | object | see below | Hard limits the supervisor enforces, and the resource `class`. | | `contributes` | object | `{}` | Agent-side contributions: `services`, `shared_topics`, `drivers`, `vision`, and the MCP lists. | | `mavlink_components` | list | `[]` | MAVLink components the plugin registers. | | `target_profiles` | list | `["drone"]` | Subset of `drone`, `ground-station`, `workstation`, `compute` (`ground_station` reads as `ground-station`). Must list at least one. `drone` is an aircraft node, `ground-station` a ground node, `workstation` the operator's own machine (a GPU box or a Mac), `compute` a headless worker. The agent refuses to install the agent half on a node whose profile is not listed (`incompatible: target_profiles excludes `). A GCS-only plugin has no agent half and is not gated. See [Node profiles](/getting-started/node-profiles). | | `binaries` | map | `{}` | Per-architecture binaries, `{: {-: }}`. See [Per-architecture binaries](#per-architecture-binaries). | | `payloads` | list | `[]` | Files the agent downloads at install instead of shipping them in the archive. See [Install-time payloads](#install-time-payloads). | | `http` | bool | `false` | Serve an HTTP API for the operator. See [Plugin HTTP](#plugin-http). | | `declared_capabilities` | list | `[]` | Capabilities the plugin defines for its own shared data. See [Shared topics and declared capabilities](#shared-topics-and-declared-capabilities). | | `contains_vendor_binary` | bool | `false` | Set true when the archive ships a pre-compiled vendor binary; requires `vendor_attribution`. Schema v2. | | `vendor_attribution` | list | `[]` | Source-offer records. Required (non-empty) when `contains_vendor_binary` is true. Schema v2. | | `subprocess_spawn` | list | absent | Allowlist of binary basenames the plugin may exec via `ctx.process.spawn`. Requires the `process.spawn` permission. Schema v2. | | `per_drone_config` | bool | `false` | Run one process instance per connected drone with a distinct `ctx.agent_id` and a per-drone config file. Schema v2. | | `test_fixtures` | map | `{}` | Map of friendly name to fixture YAML path, replayed by the SDK test harness. | #### `agent.resources` | Field | Default | Range (`standard`) | Range (`heavy`) | | - | - | - | - | | `class` | `standard` | | | | `max_ram_mb` | `96` | 8 to 4096 | 8 to 65536 | | `max_cpu_percent` | `25` | 1 to 100 | 1 to 3200 | | `max_pids` | `12` | 1 to 256 | 1 to 4096 | `class: heavy` is for a workload such as reconstruction or accelerator inference that needs most of a node. Only a first-party signer may declare it; any other signer is refused with `refused: heavy_resources_first_party_only`. A value outside its class's range fails manifest validation. #### Per-architecture binaries A Rust plugin that ships for more than one architecture maps a binary name to one path per `-` host. The keys are `aarch64-linux`, `x86_64-linux` and `aarch64-macos`. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: runtime: rust entrypoint: "bin:example-link" binaries: example-link: aarch64-linux: bin/aarch64-linux/example-link x86_64-linux: bin/x86_64-linux/example-link aarch64-macos: bin/aarch64-macos/example-link example-worker: aarch64-linux: bin/aarch64-linux/example-worker contributes: services: - name: worker command: "bin:example-worker --serve" profiles: [workstation, compute] ``` `bin:` works as the `entrypoint` and as the first word of a service `command`, and resolves to this host's path when the unit is written. Names match `[a-z0-9][a-z0-9_-]{0,63}`. Every binary a node would run (the entrypoint, plus each service whose `profiles` include this node) must have an entry for the node's architecture, or the install is refused with `incompatible: no binary for ` before anything is unpacked. The file itself must be in the archive or in an applicable payload. #### Install-time payloads Large files (per-architecture binaries, models, a wasm asset) can stay out of the archive. The agent downloads each payload that applies to the node during the install, after the signature and compatibility checks. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: payloads: - path: bin/aarch64-linux/example-worker source: "https://github.com/example/example/releases/download/v1.0.0/example-worker-aarch64-linux" sha256: "<64 lowercase hex>" size_bytes: 8912344 arch_os: aarch64-linux profiles: [workstation, compute] ``` | Field | Required | Notes | | - | - | - | | `path` | yes | Destination inside the plugin's install directory. A relative path; each `path` appears once. | | `source` | yes | An `https://` URL. It must be on the same host allowlist as a URL install (GitHub release hosts, S3, the cloud relay's archive hosts, `localhost`), and every redirect hop is checked. | | `sha256` | yes | 64 lowercase hex characters. | | `size_bytes` | yes | The exact size, 1 byte to 1 GiB. | | `profiles` | no | Node profiles that fetch it. Absent means every profile. | | `arch_os` | no | The one `-` host that fetches it. Absent means any. | Because the payload list lives in `manifest.yaml`, the archive signature covers every `source`, `sha256` and size. The agent hashes while it streams, refuses the install on a mismatch, and only then moves the file into place. Payloads do not count toward the archive size caps. The install attestation lists each applied payload with its pinned sha256. #### Plugin HTTP `http: true` asks the host for an HTTP socket. The host creates a private directory for the plugin under the agent's run directory, passes the socket path in `ADOS_PLUGIN_HTTP_SOCKET`, and the plugin serves HTTP on it. The agent's control surface then forwards `/api/plugins//x/` (`GET`, `POST`, `PUT`, `PATCH`, `DELETE` and WebSocket upgrades) to the plugin as `/`, with the query string kept. The control surface authenticates the operator first, so a request that reaches the socket is already an operator request. When nothing is listening the route answers `503`. See the [REST API](/drone-agent/rest-api#extension-http-passthrough). Every plugin process also receives `ADOS_NODE_PROFILE` (`drone`, `ground-station`, `workstation` or `compute`), so a plugin that behaves per profile never reads the agent's config files. #### Services `contributes.services` declares extra service units beside the main process. A bare string is a service whose name is its command. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: network.outbound - id: network.listen contributes: services: - name: node command: "bin:example-node --port 8092" restart: always # on-failure (default), always, or no ready_check: "http://127.0.0.1:8092/healthz" profiles: [workstation, compute] listen_ports: [8092] ``` | Field | Notes | | - | - | | `name` | Lowercase alphanumeric plus `._-`, starting with an alphanumeric. The unit is `ados-plugin---.service`: dots in the id become hyphens, and `` is the first 8 hex digits of the SHA-256 of the id. `GET /api/plugins/` reports each service's log path. | | `command` | The argv. The first word may be `bin:`. | | `restart` | `always`, `on-failure` or `no`. | | `ready_check` | An `http(s)://127.0.0.1:/...` URL or a command, probed by `GET /api/plugins//readiness`. | | `profiles` | Node profiles the service runs on. Absent means every profile the plugin installs on. | | `listen_ports` | TCP ports this service may bind, 1024 to 65535, at most four. Declaring any needs both `network.listen` and `network.outbound`. The service unit gets `SocketBindAllow` for exactly these ports; every plugin unit carries `SocketBindDeny=any`, and the main process never listens. | #### Shared topics and declared capabilities A plugin can own event-bus topics and share them with other plugins. Its topics live under `plugin..`, where `` is the last segment of the plugin id (`com.example.mapper` owns `plugin.mapper.*`). ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} id: com.example.mapper agent: permissions: - id: event.publish declared_capabilities: - id: plugin.mapper.map.read risk: low description: "Read the occupancy maps this plugin publishes." contributes: shared_topics: - topic: plugin.mapper.pose subscribe_capability: telemetry.read - topic: plugin.mapper.occupancy subscribe_capability: plugin.mapper.map.read ``` * **`shared_topics[].topic`** must be `plugin..` over `[a-z0-9._-]`, at most 128 characters, each listed once. The owner may `event.publish` it. Two installed plugins cannot claim the same namespace. * **`shared_topics[].subscribe_capability`** is what a subscriber needs on top of `event.subscribe`: a catalog capability, or one this plugin declares. * **`declared_capabilities[]`** entries take an `id` of the form `plugin..`, a `risk` (`low`, `medium`, `high` or `critical`) and a `description`. Another plugin requests one like any catalog capability, and the install dialog shows it with the declared risk and description. #### `agent.mavlink_components` Each entry registers a MAVLink component so the router claims its id and answers component-info on the plugin's behalf. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} mavlink_components: - component_id: 100 # 0 to 255 component_kind: camera # camera | gimbal | payload | peripheral | generic | vio sub_id: 1 # optional, 0 to 255 ``` #### Permission shape A permission entry is either a bare string (which means required) or an object with `id`, `required`, and an optional `degraded_behavior`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} permissions: - id: mavlink.read # required (bare string also works: "mavlink.read") - id: hardware.i2c required: false # optional; the plugin degrades gracefully without it degraded_behavior: "Falls back to MAVLink-only telemetry" ``` Unknown permission ids load with a warning rather than a hard failure, so an experimental manifest still parses. See the [Permissions reference](/developers/permissions). #### Schema-2 agent fields `contains_vendor_binary`, `vendor_attribution`, `subprocess_spawn`, and `per_drone_config` are schema-2 fields. A `schema_version: 1` manifest gets the defaults. * **`per_drone_config: true`** runs one process per connected drone, each with its own `ctx.agent_id` and config at `/var/ados/plugin-data//config/.yaml`. * **`subprocess_spawn`** is an allowlist of binary basenames the plugin may exec. The plugin host rejects any spawn whose basename is not on the list, and the manifest validator requires the `process.spawn` permission whenever the list is non-empty. * **`contains_vendor_binary` plus `vendor_attribution`** travel together: the flag must be set when (and only when) at least one attribution record is present. Each `vendor_attribution` entry takes `license` (required) plus optional `name`, `source_url`, `source_offer_url`, `upstream_repo`, `upstream_version`, `commit_sha`, and `notice`. See [Vendor binaries](/developers/vendor-binaries). ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: runtime: rust entrypoint: "bin/example-detector" isolation: subprocess per_drone_config: true contains_vendor_binary: true vendor_attribution: - name: "example-upstream" license: "GPL-3.0-only" source_url: "https://github.com/example-oem/example-upstream" upstream_version: "v2.7" notice: "Used by the detector mode." permissions: - id: vision.frame.read - id: process.spawn subprocess_spawn: - ados_example_shim ``` #### Schema-3 fields: MCP tools, resources and prompts Schema 3 adds three contribution lists, on `agent.contributes` and on `gcs.contributes`. They are what makes a plugin reachable by an AI agent through the MCP surface. A schema-2 manifest with no `tools` block loads exactly as before, so the platform stays inert for every existing plugin. Exposure requires the `mcp.expose` capability. Without it the lists parse and nothing is registered. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: mcp.expose contributes: tools: - name: "example_read_state" description: "Read the current detector read-back." safety_class: read inputSchema: type: object properties: {} - name: "example_stop" description: "Stop the behaviour." safety_class: safe_write inputSchema: type: object properties: {} resources: [] prompts: [] ``` The entries are free-form maps and additive. The agent reads `name`, `inputSchema` and `safety_class` to build the tool registry and to route a host-to-plugin `tool.invoke`; it does not interpret the rest of the body. Be conservative with what you expose: a tool that commands the aircraft should be the operator's decision, not an assistant's, so first-party plugins expose a stop tool and no start tool. See [MCP server](/developers/mcp-server) for the scopes an assistant's token carries and how they gate a tool call. ## `gcs` ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} gcs: entrypoint: "gcs/plugin.bundle.js" isolation: "iframe" # iframe (default) or inline (first-party only) permissions: - id: ui.slot.fc-tab - id: ui.slot.notification-channel - id: telemetry.subscribe.battery contributes: panels: - id: power-tab slot: fc.tab title: "Power" icon: "zap" order: 30 notifications: - id: power-alert title: "Power alert" locales: - "en" ``` | Field | Notes | | - | - | | `entrypoint` | The built bundle inside the archive. Required only when the half contributes `panels`, `tabs`, `agent_pages` or `node_surfaces`; a parameters- or skills-only half needs no bundle. | | `isolation` | `iframe` (default) or `inline`. See below. | | `permissions` | GCS capability requests, same [shape](#permission-shape) as the agent half. Mounting in a slot requires the matching `ui.slot.*` permission. | | `contributes` | What the half adds to Mission Control. Every key, its fields and its slot are on [Contribution points](/developers/contribution-points). Keys are snake\_case (`mission_templates`, `map_overlays`, `target_actions`); Mission Control also reads the camelCase spelling, but the agent's validator rejects it. | | `locales` | Locale codes the half ships under `locales/.json`. A sibling of `contributes`. The agent serves an installed bundle at `GET /api/plugins/{plugin_id}/locales/{lang}`. | ### `gcs.isolation` | Value | Who may use it | How the half runs | | - | - | - | | `iframe` | Everyone (default) | A sandboxed iframe with no same-origin access, talking to Mission Control over the postMessage bridge. | | `inline` | First-party signers only | An ES module Mission Control imports into its own page. The agent refuses the install from any other signer, and Mission Control verifies the module before loading it. | An inline module exports `mount(root, host)` and returns a disposer. The types are in `@altnautica/plugin-sdk/inline`; the host passes its own React, and the `inlineSharedExternals()` esbuild plugin from `@altnautica/plugin-sdk/esbuild` points the module's `react`, `react-dom/client` and `react/jsx-runtime` imports at it. The `host` gives the module the same capability-gated context an iframe half gets, plus `agent.fetch` and `agent.websocket` against the plugin's own [HTTP passthrough](#plugin-http), `assetUrl` for files in `gcs/`, the plugin's cloud records, and navigation between its pages. Before importing, Mission Control fetches the node's `GET /api/plugins//attestation` and `GET /api/plugins//manifest` and loads the module only when all of these hold: the signature verifies over the attested file list, the signer is an enrolled first-party key, the manifest's hash matches its attested digest and it declares `isolation: inline`, and the module's hash matches the digest listed for `gcs.entrypoint`. A module that fails any check shows an error card; it never falls back to an iframe. An inline half loads from the node over the LAN or the relay proxy, not from a cloud-stored bundle. ## All fields The table below is generated from the strict schema that `ados plugin lint`, `sign` and `test` enforce. The agent applies the same shape rules at install: a key that is not in this table, in any block, refuses the manifest. | Field | Type | Required | Default | Description | | - | - | - | - | - | | `agent.binaries` | object | No | n/a | Binaries | | `agent.contains_vendor_binary` | boolean | No | `false` | Contains Vendor Binary | | `agent.contributes.drivers` | array | No | n/a | Drivers | | `agent.contributes.prompts` | array | No | n/a | Prompts | | `agent.contributes.resources` | array | No | n/a | Resources | | `agent.contributes.services` | array | No | n/a | Services | | `agent.contributes.services[].command` | string | Yes | n/a | Command | | `agent.contributes.services[].listen_ports` | array | No | n/a | Listen Ports | | `agent.contributes.services[].name` | string | Yes | n/a | Name | | `agent.contributes.services[].profiles` | array\|null | No | n/a | Profiles | | `agent.contributes.services[].ready_check` | string\|null | No | n/a | Ready Check | | `agent.contributes.services[].restart` | string | No | `"on-failure"` | Restart One of: `"always"`, `"on-failure"`, `"no"`. | | `agent.contributes.services[].slice` | string | No | `"ados-plugins.slice"` | Slice | | `agent.contributes.shared_topics` | array | No | n/a | Shared Topics | | `agent.contributes.shared_topics[].subscribe_capability` | string | Yes | n/a | Subscribe Capability | | `agent.contributes.shared_topics[].topic` | string | Yes | n/a | Topic | | `agent.contributes.tools` | array | No | n/a | Tools | | `agent.contributes.vision.behaviors` | array | No | n/a | Behaviors | | `agent.contributes.vision.detectors` | array | No | n/a | Detectors | | `agent.contributes.vision.models` | array | No | n/a | Models | | `agent.declared_capabilities` | array | No | n/a | Declared Capabilities | | `agent.declared_capabilities[].description` | string | No | `""` | Description | | `agent.declared_capabilities[].id` | string | Yes | n/a | Id | | `agent.declared_capabilities[].risk` | string | Yes | n/a | Risk One of: `"low"`, `"medium"`, `"high"`, `"critical"`. | | `agent.entrypoint` | string | Yes | n/a | Entrypoint | | `agent.http` | boolean | No | `false` | Http | | `agent.isolation` | string | No | `"subprocess"` | Isolation One of: `"subprocess"`, `"inprocess"`. | | `agent.mavlink_components` | array | No | n/a | Mavlink Components | | `agent.mavlink_components[].component_id` | integer | Yes | n/a | Component Id | | `agent.mavlink_components[].component_kind` | string | Yes | n/a | Component Kind One of: `"camera"`, `"gimbal"`, `"payload"`, `"peripheral"`, `"generic"`, `"vio"`. | | `agent.mavlink_components[].sub_id` | integer\|null | No | n/a | Sub Id | | `agent.payloads` | array | No | n/a | Payloads | | `agent.payloads[].arch_os` | string\|null | No | n/a | Arch Os | | `agent.payloads[].path` | string | Yes | n/a | Path | | `agent.payloads[].profiles` | array\|null | No | n/a | Profiles | | `agent.payloads[].sha256` | string | Yes | n/a | Sha256 | | `agent.payloads[].size_bytes` | integer | Yes | n/a | Size Bytes | | `agent.payloads[].source` | string | Yes | n/a | Source | | `agent.per_drone_config` | boolean | No | `false` | Per Drone Config | | `agent.permissions` | array | No | n/a | Permissions | | `agent.permissions[].degraded_behavior` | string\|null | No | n/a | Degraded Behavior | | `agent.permissions[].id` | string | Yes | n/a | Id | | `agent.permissions[].required` | boolean | No | `true` | Required | | `agent.resources.class` | string | No | `"standard"` | Class One of: `"standard"`, `"heavy"`. | | `agent.resources.max_cpu_percent` | integer | No | `25` | Max Cpu Percent | | `agent.resources.max_pids` | integer | No | `12` | Max Pids | | `agent.resources.max_ram_mb` | integer | No | `96` | Max Ram Mb | | `agent.resources_by_profile` | object | No | n/a | Resources By Profile | | `agent.runtime` | string | No | `"python"` | Runtime One of: `"python"`, `"rust"`. | | `agent.subprocess_spawn` | array\|null | No | n/a | Subprocess Spawn | | `agent.target_profiles` | array | No | n/a | Target Profiles | | `agent.test_fixtures` | object | No | n/a | Test Fixtures | | `agent.vendor_attribution` | array | No | n/a | Vendor Attribution | | `agent.vendor_attribution[].commit_sha` | string\|null | No | n/a | Commit Sha | | `agent.vendor_attribution[].license` | string | Yes | n/a | License | | `agent.vendor_attribution[].name` | string\|null | No | n/a | Name | | `agent.vendor_attribution[].notice` | string\|null | No | n/a | Notice | | `agent.vendor_attribution[].source_offer_url` | string\|null | No | n/a | Source Offer Url | | `agent.vendor_attribution[].source_url` | string\|null | No | n/a | Source Url | | `agent.vendor_attribution[].upstream_repo` | string\|null | No | n/a | Upstream Repo | | `agent.vendor_attribution[].upstream_version` | string\|null | No | n/a | Upstream Version | | `author` | string | No | `""` | Author | | `compatibility.ados_version` | string | Yes | n/a | Ados Version | | `compatibility.gcs_version` | string\|null | No | n/a | Gcs Version | | `compatibility.min_tier` | integer\|null | No | n/a | Min Tier | | `compatibility.supported_boards` | array | No | n/a | Supported Boards | | `description` | string | No | `""` | Description | | `description_long` | string\|null | No | n/a | Description Long | | `documentation_url` | string\|null | No | n/a | Documentation Url | | `extra` | object | No | n/a | Extra | | `features` | array | No | n/a | Features | | `gcs.contributes.agent_pages` | array | No | n/a | Agent Pages | | `gcs.contributes.agent_pages[].after` | string\|null | No | n/a | After | | `gcs.contributes.agent_pages[].icon` | string\|null | No | n/a | Icon | | `gcs.contributes.agent_pages[].id` | string | Yes | n/a | Id | | `gcs.contributes.agent_pages[].order` | integer\|null | No | n/a | Order | | `gcs.contributes.agent_pages[].profile` | array\|null | No | n/a | Profile | | `gcs.contributes.agent_pages[].section` | string\|null | No | n/a | Section | | `gcs.contributes.agent_pages[].setup_for` | string\|null | No | n/a | Setup For | | `gcs.contributes.agent_pages[].title` | string | Yes | n/a | Title | | `gcs.contributes.map_overlays` | array | No | n/a | Map Overlays | | `gcs.contributes.mission_templates` | array | No | n/a | Mission Templates | | `gcs.contributes.models` | array | No | n/a | Models | | `gcs.contributes.node_surfaces` | array | No | n/a | Node Surfaces | | `gcs.contributes.node_surfaces[].group` | string\|null | No | n/a | Group One of: `"status"`, `"vehicle"`, `"link"`, `"device"`, `"compute"`. | | `gcs.contributes.node_surfaces[].id` | string | Yes | n/a | Id | | `gcs.contributes.node_surfaces[].order` | integer\|null | No | n/a | Order | | `gcs.contributes.node_surfaces[].profile` | array | Yes | n/a | Profile | | `gcs.contributes.node_surfaces[].title` | string | Yes | n/a | Title | | `gcs.contributes.notifications` | array | No | n/a | Notifications | | `gcs.contributes.overlays` | array | No | n/a | Overlays | | `gcs.contributes.panels` | array | No | n/a | Panels | | `gcs.contributes.parameters` | array | No | n/a | Parameters | | `gcs.contributes.prompts` | array | No | n/a | Prompts | | `gcs.contributes.resources` | array | No | n/a | Resources | | `gcs.contributes.settings` | array | No | n/a | Settings | | `gcs.contributes.skills` | array | No | n/a | Skills | | `gcs.contributes.smart_functions` | array | No | n/a | Smart Functions | | `gcs.contributes.tabs` | array | No | n/a | Tabs | | `gcs.contributes.target_actions` | array | No | n/a | Target Actions | | `gcs.contributes.tools` | array | No | n/a | Tools | | `gcs.entrypoint` | string\|null | No | n/a | Entrypoint | | `gcs.isolation` | string | No | `"iframe"` | Isolation One of: `"iframe"`, `"inline"`. | | `gcs.locales` | array | No | n/a | Locales | | `gcs.permissions` | array | No | n/a | Permissions | | `gcs.permissions[].degraded_behavior` | string\|null | No | n/a | Degraded Behavior | | `gcs.permissions[].id` | string | Yes | n/a | Id | | `gcs.permissions[].required` | boolean | No | `true` | Required | | `hardware_requirements.boards` | array | No | n/a | Boards | | `hardware_requirements.cameras` | string\|null | No | n/a | Cameras | | `hardware_requirements.fc_firmware` | string\|null | No | n/a | Fc Firmware | | `hardware_requirements.optional` | array | No | n/a | Optional | | `homepage` | string\|null | No | n/a | Homepage | | `id` | string | Yes | n/a | Id | | `license` | string | No | `""` | License | | `name` | string | Yes | n/a | Name | | `required_fc_parameters.ardupilot` | array | No | n/a | Ardupilot | | `required_fc_parameters.ardupilot[].note` | string\|null | No | n/a | Note | | `required_fc_parameters.ardupilot[].param` | string | Yes | n/a | Param | | `required_fc_parameters.ardupilot[].value` | string\|number\|integer\|null | No | n/a | Value | | `required_fc_parameters.inav` | array | No | n/a | Inav | | `required_fc_parameters.inav[].note` | string\|null | No | n/a | Note | | `required_fc_parameters.inav[].param` | string | Yes | n/a | Param | | `required_fc_parameters.inav[].value` | string\|number\|integer\|null | No | n/a | Value | | `required_fc_parameters.px4` | array | No | n/a | Px4 | | `required_fc_parameters.px4[].note` | string\|null | No | n/a | Note | | `required_fc_parameters.px4[].param` | string | Yes | n/a | Param | | `required_fc_parameters.px4[].value` | string\|number\|integer\|null | No | n/a | Value | | `resource_impact.cpu_percent_peak` | number\|null | No | n/a | Cpu Percent Peak | | `resource_impact.output_rate_hz` | number\|null | No | n/a | Output Rate Hz | | `resource_impact.pids` | integer\|null | No | n/a | Pids | | `resource_impact.ram_mb` | number\|null | No | n/a | Ram Mb | | `resource_impact.startup_time_seconds` | number\|null | No | n/a | Startup Time Seconds | | `risk` | string | No | `"medium"` | Risk One of: `"low"`, `"medium"`, `"high"`, `"critical"`. | | `schema_version` | integer | No | `1` | Schema Version | | `screenshots` | array | No | n/a | Screenshots | | `screenshots[].caption` | string\|null | No | n/a | Caption | | `screenshots[].url` | string | Yes | n/a | Url | | `telemetry_fields` | array | No | n/a | Telemetry Fields | | `version` | string | Yes | n/a | Version | ## Signing and the archive The `.adosplug` archive is a zip. There is no per-asset hash list in the manifest and no `signing:` block. Instead the archive carries a separate top-level `SIGNATURE` file with two lines: the signer key id, then the base64 Ed25519 signature over a canonical payload hash (the SHA-256 of the sorted `\n\n` lines for every entry except `SIGNATURE`). Because the hash covers every entry, any tampering after signing fails verification. Archives are size-bounded (50 MB per archive, 25 MB per entry) and reject path-traversal entries (`..`, absolute paths, symlinks). [Payloads](#install-time-payloads) do not count toward these caps. A manifest that fails validation raises a manifest error; a signature from an unknown or revoked signer is rejected (see [Signing keys](/developers/signing-keys)). At install the agent writes an attestation beside the unpacked plugin: the archive's `SIGNATURE` text and the sha256 of every attested file, payloads marked. `GET /api/plugins//attestation` serves it. ## Next steps > [card] [Contribution points](/developers/contribution-points) > > Every `contributes` key and the slot it mounts in. > [card] [Permissions](/developers/permissions) > > The capabilities a manifest can request. > [card] [Lifecycle](/developers/lifecycle) > > What happens after install. > [card] [Signing keys](/developers/signing-keys) > > Sign the archive the manifest ships in. # MAVLink extensions Source: https://docs.altnautica.com/developers/mavlink-extensions Read and send MAVLink, register as a MAVLink component, inject visual odometry, talk MSP, and send guided setpoints from an agent plugin. The agent already speaks MAVLink to the flight controller and routes it to the GCS. An agent plugin extends that through these facades: * `ctx.mavlink`: subscribe to messages, send frames, register a MAVLink component. * `ctx.vision`: register as the visual-odometry source and inject pose. * `ctx.msp`: the raw MSP byte plane to Betaflight, iNav and KISS flight controllers. * `ctx.flight`: scoped guided-mode and attitude/rate setpoint senders. > [!WARNING] > > `mavlink.write`, `msp.write`, `flight.guided_setpoint` and `flight.rate_setpoint` can move the aircraft. Bench-test with props off and read [Safety](/operations/safety) before flying a plugin that uses them. ## Capabilities | Capability | Lets the plugin | | - | - | | `mavlink.read` | Subscribe to MAVLink messages from the link. | | `mavlink.write` | Send MAVLink frames to the flight controller. | | `mavlink.component.{camera,gimbal,payload,peripheral,vio}` | Register as a MAVLink component of that kind. | | `mavlink.tunnel` | Exchange application payloads over MAVLink `TUNNEL` frames. | | `msp.read`, `msp.write` | Receive and send MSP bytes. | | `flight.guided_setpoint` | Send guided-mode position, velocity or acceleration setpoints. | | `flight.rate_setpoint` | Send attitude and body-rate setpoints with thrust. | Risk levels and the install-dialog badges for each are on [Permissions](/developers/permissions). ## Subscribing to messages `ctx.mavlink.subscribe` registers a callback for one message name. The callback receives the message name, the raw frame bytes and a timestamp. Decode the frame with your own MAVLink library: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: async def on_battery(msg: dict) -> None: # msg["msg_name"], msg["frame"] (raw bytes), msg["timestamp_ms"] self.decode_and_store(msg["frame"]) await ctx.mavlink.subscribe("BATTERY_STATUS", on_battery) ``` The host reads each inbound frame once and fans it out to every subscriber; no per-plugin parser runs on the link. ## Sending frames `ctx.mavlink.send` writes an encoded frame to the flight controller. Pass `component_id` to send under a component the plugin has registered: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} frame = encode_command_long( target_system=1, target_component=1, command=203, # MAV_CMD_DO_DIGICAM_CONTROL params=[0, 0, 0, 0, 1, 0, 0], ) await ctx.mavlink.send(frame) ``` ## Registering as a component A plugin that should appear on the MAVLink bus as a camera, gimbal, payload, peripheral or visual-odometry source registers a component id. Declare it in the manifest so the host reserves the id, and hold the matching `mavlink.component.` capability: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: mavlink.component.camera mavlink_components: - component_id: 100 component_kind: camera sub_id: 1 ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: await ctx.mavlink.register_component(100, "camera") ``` The kinds are `camera`, `gimbal`, `payload`, `peripheral`, `vio` and `generic`. The first five map to `mavlink.component.`. The SIYI pod extension registers camera 100 and gimbal 154; the Follow-Me and MAVLink Gimbal v2 extensions declare component 191 as `generic`. ### Visual odometry A visual-odometry plugin registers the `vio` component once, then sends pose estimates. The helpers are on `ctx.vision` and need the `mavlink.component.vio` grant: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: self.ctx = ctx await ctx.vision.register_vio_component() async def on_pose(self, pose) -> None: await self.ctx.vision.inject_pose(pose) # VISION_POSITION_ESTIMATE ``` `inject_odometry(odometry)` sends an `ODOMETRY` message (pose plus body-frame twist) under the same component. A bad pose stream feeds the flight controller's estimator and can produce unsafe position control. ## Re-publishing decoded data A common pattern decodes one message and re-publishes a clean event, so raw MAVLink stays in one plugin. Publish on your own namespace for your own use, and declare a shared topic for other plugins: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} id: com.example.rangefinder agent: permissions: - id: mavlink.read - id: event.publish contributes: shared_topics: - topic: plugin.rangefinder.reading subscribe_capability: mavlink.read ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: async def on_distance(msg: dict) -> None: distance_m = self.decode_distance(msg["frame"]) await ctx.events.publish(f"plugin.{ctx.plugin_id}.reading", {"distance_m": distance_m}) await ctx.events.publish("plugin.rangefinder.reading", {"distance_m": distance_m}) await ctx.mavlink.subscribe("DISTANCE_SENSOR", on_distance) ``` Another plugin with `event.subscribe` and `mavlink.read` then subscribes to `plugin.rangefinder.reading` without touching MAVLink. Your `plugin.com.example.rangefinder.*` topics stay private to your plugin. See [Agent event bus](/developers/event-hooks-and-bus#plugin-to-plugin). ## MSP flight controllers For Betaflight, iNav and KISS flight controllers, `ctx.msp` moves raw MSP bytes. The host moves bytes only; build and parse frames with `ados.plugins.msp`. `send` needs `msp.write` and `subscribe` needs `msp.read`. MSP has no per-message topic, so the callback receives every chunk the flight controller sends: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: async def on_bytes(chunk: dict) -> None: self.parser.feed(chunk["bytes"]) # chunk["timestamp_ms"] too await ctx.msp.subscribe(on_bytes) await ctx.msp.send(self.build_request()) ``` ## Guided setpoints A flight-behavior plugin commands the vehicle in guided mode through `ctx.flight` instead of raw MAVLink writes, so one capability gates the flight-command surface. `guided_setpoint` needs `flight.guided_setpoint`; the host encodes the matching `SET_POSITION_TARGET_*` message: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await ctx.flight.guided_setpoint( kind="local_ned", # or "global_int" (lat/lon in 1e7, alt in m) coordinate_frame=1, # MAV_FRAME_LOCAL_NED type_mask=0b0000_1101_1100_0111, # velocity only vx=2.0, vy=0.0, vz=0.0, ) ``` `kind` picks the frame family, `coordinate_frame` is a `MAV_FRAME_*` value and `type_mask` is the ignore-axis bitmask. Unset axes default to zero. The call returns `{"ok": bool, ...}`, or a `not_available` shape when the MAVLink router is unreachable. `rate_setpoint` sends `SET_ATTITUDE_TARGET` (attitude quaternion and/or body rates plus normalized thrust) and needs `flight.rate_setpoint`. A GCS half does not send MAVLink. It calls `ctx.command.send` with one of the host's named commands (`takeoff`, `land`, `rtl`), gated on `command.send`; the operator approves each command in a dialog before it reaches the vehicle. ## Next steps > [card] [Vision plugins](/developers/vision-plugins) > > Frames, inference and detections on the vision engine. > [card] [Agent event bus](/developers/event-hooks-and-bus) > > Publish and subscribe rules and shared topics. > [card] [Permissions](/developers/permissions) > > Every capability and its risk level. > [card] [Safety](/operations/safety) > > Pre-flight checks before flying a plugin that commands the aircraft. # MCP server and AI control Source: https://docs.altnautica.com/developers/mcp-server Give an AI client scoped, revocable, audited control of a node or a fleet. Token acceptance is off until you turn it on. ADOS ships a Model Context Protocol connector so an MCP-capable client (Claude Code, Claude Desktop, Cursor, VS Code, or a plain HTTP client) can read a node, administer it, and, when you explicitly grant it, fly it. Two halves, and they are separate decisions: 1. **The connector** is a Node server you run on your own machine, from the [ADOS-MCP](https://github.com/altnautica/ADOS-MCP) repo. It is the MCP server your AI client talks to, and a client of the agent's HTTP API. 2. **The agent-side token edge** is the scoped credential an agent will accept in place of the full pairing key. It is **off by default** and stays inert until you set `mcp.token_accept_enabled`. No model runs on the drone. The connector holds no telemetry buffers and runs no inference; it calls interfaces that already exist and presents them through MCP. > [!WARNING] > > Token acceptance ships off. `mcp.token_accept_enabled` defaults to `false`, and > `ados mcp status` reports the posture. A token you mint before flipping the flag > is valid, but the auth edge refuses it until the flag is on. ## The trust boundary The agent's auth edge accepts three credentials on the LAN: the pairing key (`X-ADOS-Key`), a dashboard-PIN session, and, behind the accept flag, a scoped MCP token on the `x-ados-mcp-token` header. | Property | Behaviour | | - | - | | Default posture | Acceptance off. The whole surface is inert until the flag flips. | | Token store | `/etc/ados/mcp-token.json`, mode `0600`. | | What the store holds | The bulk-revocation salt, a per-token denylist, and a registry of minted tokens for the status view. The secret is **not** stored. | | When the store is read | Only on a would-be `401`. An authenticated request never touches the record. | | Route classification | Fail-closed. Every `GET` needs `read`; a write with no explicit class is denied to a token, so the caller must fall back to the full pairing key. | | Scope stamping | The front strips `x-ados-mcp-scopes` from every inbound request, then sets it only for a verified token, so a client cannot spoof its own scopes in. | | Relay posture | `POST /api/mcp/tokens` and `POST /api/mcp/revoke` are relay-forbidden: they are refused when the request arrives through a ground station's relay proxy. | A new agent route is unreachable by token until it is classified, which is the intended direction: an unclassified route is denied rather than silently over-granted. ## Scopes Six scope groups. A token carries one or more; a route carries exactly one required class. | Scope | Covers | | - | - | | `read` | Every `GET`. | | `safe_write` | Writes that do not move an aircraft or destroy state. | | `admin` | Platform administration: rename, update, service restart, pairing and network writes. | | `flight` | Arm, mode change, goto, mission run, land, return, stop. | | `destructive` | Actions that discard state or stop an aircraft abruptly. | | `secret_read` | Reads that would return secret material. | `flight` and `destructive` are never granted implicitly. On the connector side, a tool whose class is `flight` (or that otherwise affects flight) is refused outright while the MAVLink proxy enforce flag is off. ## Enable the token edge on a node `ados mcp enable` writes the config key and restarts the control front so the new posture takes effect. It is a local root operation, not a REST call, so it needs `sudo`. Never hand-edit `/etc/ados/config.yaml` for this; the command is the sanctioned path. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sudo ados mcp enable ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Write the flag but leave the control front alone (restart it yourself later). sudo ados mcp enable --no-restart ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sudo ados mcp disable ``` Check the posture and the minted tokens at any time: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados mcp status ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} MCP access token acceptance: disabled (tokens can be minted but are not honored at the edge yet) no tokens minted ``` `ados mcp status --json` prints the raw `/api/mcp/status` body, which carries `accept_enabled` and a `tokens` array. Each token entry carries `token_id`, `label`, `scopes`, and the `revoked` / `expired` flags. ## Mint a scoped token ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados mcp mint --label "fleet-readonly" --scope read --ttl-days 30 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Repeat --scope to grant more than one group. ados mcp mint --label "bench-ops" --scope read --scope safe_write --scope admin \ --ttl-days 7 ``` | Flag | Default | Meaning | | - | - | - | | `--label ` | empty | A human label carried in the status view. | | `--scope ` | **required**, repeatable | One of `read`, `safe_write`, `admin`, `flight`, `destructive`, `secret_read`. An unknown value is rejected by the CLI choice list. | | `--ttl-days ` | `30` | Lifetime in days. Converted to a millisecond TTL on the wire; a value below 1 is clamped to 1. | | `--node ` | none, repeatable | An **advisory** node allowlist carried inside the token. The token is already bound to the issuing node; this list is a hint for a fleet connector, not an extra agent-side restriction. | The command prints a "shown once" banner followed by the token on its own line. The secret is never written to the store, so if you lose it you mint a new one. Store it in your MCP client's environment, not in your shell history. On-box, the mint / status / revoke routes are admitted without a key because loopback is inside the trust boundary; off-box they take the front's normal auth lane. ## Revoke ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # One token by id. ados mcp revoke ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Every token, by rotating the store salt. ados mcp revoke --all ``` A single revoke adds the id to the denylist. `--all` rotates the 128-bit salt folded into every derived token key, so every previously-minted token fails verification at once. That is the incident response: rotate, then re-mint the tokens you still want. See [Revocation and incidents](/developers/revocation-and-incidents) for the wider playbook. ## Agent routes | Method | Path | Notes | | - | - | - | | `GET` | `/api/mcp/status` | The acceptance posture plus the minted-token registry. | | `POST` | `/api/mcp/tokens` | Mint. Authorized on-box or with a valid key. Relay-forbidden. | | `POST` | `/api/mcp/revoke` | Revoke one id or all. Needs the `admin` scope class. Relay-forbidden. | ## Run the connector The connector ships as a container image, or you can clone and build it. To build from source: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/altnautica/ADOS-MCP.git cd ADOS-MCP ./scripts/setup.sh # installs, builds, prints the exact client add command ``` Prerequisites: Node 20 or newer, git, and pnpm. `pnpm install && pnpm build` is the manual equivalent. Three deployment modes, selected with `--target`. All three expose the identical tool set; only the reach differs. | Mode | Invocation | Reaches | Needs | | - | - | - | - | | Agent | `--target agent ` | one node on your LAN | that node's pairing key | | Local fleet | `--target local-fleet []` | many LAN nodes, no cloud | each node's host and key, inline in one env var or in a file | | Fleet | `--target fleet --gcs prod` | your fleet from anywhere, through Mission Control | a signed-in operator and a minted machine credential | Add one LAN node to Claude Code, with the key in the client environment rather than your shell: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} claude mcp add ados -e ADOS_MCP_AGENT_KEY= -- \ node "$(pwd)/dist/index.js" --target agent 192.168.1.50 ``` Check reach without starting a server. `--verify` connects, checks auth and reachability, prints the result, and exits `0` or `1`: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ADOS_MCP_AGENT_KEY= node dist/index.js --target agent 192.168.1.50 --verify ``` ### Run with Docker The connector also ships as a multi-arch image, `ghcr.io/altnautica/ados-mcp` (`linux/amd64`, `linux/arm64`). Tags are `X.Y.Z`, `X.Y` and `latest` for releases, and `edge` for the main branch. Pin `X.Y.Z` for a reproducible setup. Create the data folder and pull the image: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p ~/.ados/mcp && docker pull ghcr.io/altnautica/ados-mcp:latest ``` Add it to Claude Code. The key stays in the client's environment; `-e NAME` forwards it into the container, so it never appears in the `docker` arguments: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} claude mcp add ados -e ADOS_MCP_AGENT_KEY= -- docker run -i --rm -e ADOS_MCP_AGENT_KEY -v "$HOME/.ados/mcp:/home/node/.ados/mcp" ghcr.io/altnautica/ados-mcp:latest --target agent 192.168.1.50 ``` Check reach with a one-shot run: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker run --rm -e ADOS_MCP_AGENT_KEY= ghcr.io/altnautica/ados-mcp:latest --target agent 192.168.1.50 --verify ``` For a client that reads `.mcp.json` (the key is read from your environment, so the file holds no secret): ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "mcpServers": { "ados": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "ADOS_MCP_AGENT_KEY", "-v", "${HOME}/.ados/mcp:/home/node/.ados/mcp", "ghcr.io/altnautica/ados-mcp:latest", "--target", "agent", "192.168.1.50"], "env": { "ADOS_MCP_AGENT_KEY": "${ADOS_MCP_AGENT_KEY}" } } } } ``` To run it as a long-lived Streamable HTTP service, start the `mcp` service from a checkout. It listens on `127.0.0.1:8091`, mounts `~/.ados/mcp` and passes `--transport http`, which a service needs because `auto` picks stdio whenever stdin is not a terminal: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cp .env.example .env docker compose up -d claude mcp add --transport http ados http://127.0.0.1:8091/mcp --header "Authorization: Bearer " ``` Behind your own reverse proxy, run with `--trust-proxy --http-host 0.0.0.0` and leave the port unpublished. > [!WARNING] > > The image runs as user id 1000. On Linux, if your user id differs, add > `--user "$(id -u):$(id -g)"` after `docker run`. Create `~/.ados/mcp` before the > first run: otherwise Docker creates it owned by root, the audit sink cannot > write, and write tools refuse. Docker limits: * LAN auto-discovery and mDNS advertising need `--network host`, on Linux. * `.local` names may not resolve inside a container. Use the drone's IP address. * `--gcs local` inside a container points at the container itself. Use `--convex-url http://host.docker.internal:3210`, and on Linux also add `--add-host host.docker.internal:host-gateway`. * The on-box Unix socket does not apply, so a warning about it is expected. * Through Docker Desktop's port publishing, tokens pinned to a source IP see the Docker gateway address. * Never pass `-t` to a stdio run. * cmd.exe does not expand `$HOME`. Use PowerShell or a POSIX shell. In Git Bash, put `MSYS_NO_PATHCONV=1` in front of the command: without it Git Bash rewrites the container side of the `-v` mount, the server still connects, and the audit trail silently stays inside the container. ### Connector flags | Flag | Default | Meaning | | - | - | - | | `--target ` | required | Deployment mode. | | `--transport ` | `auto` | `auto` picks stdio when a client launched the process. | | `--http-port ` | `8091` | Streamable HTTP port in agent mode. | | `--http-host ` | `::` | HTTP bind address. `127.0.0.1` with `--trust-proxy`; an explicit value always wins. | | `--fleet-file ` | `~/.ados/mcp/fleet.json` | The local-fleet file. | | `--gcs ` | none | The Mission Control Convex backend, fleet mode. | | `--token ` | none | The bearer for the launch principal. | | `--convex-url ` | none | An explicit Convex deployment URL, fleet mode. `--gcs` is the shortcut. | | `--mqtt-url ` | none | The MQTT broker URL for live streams, fleet mode. | | `--fleet-endpoint ` | none | The hosted endpoint name, fleet mode. | | `--node-id ` | none | This node's device id, agent mode. | | `--audit-path ` | `~/.ados/mcp/audit.ndjson` | Local audit file. | | `--sim` | off | Opt in to the SITL safety waiver. | | `--flight-enforced` | off | Declares the MAVLink proxy enforce flag is confirmed on. | | `--discover` | off | Local fleet: browse the LAN and auto-adopt unpaired nodes. | | `--no-mdns` | off | Disable mDNS advertisement in agent mode. | | `--trust-proxy` | off | HTTP only. The listener sits behind a trusted reverse proxy: it binds `127.0.0.1` and takes the client IP from `cf-connecting-ip`, else the right-most `X-Forwarded-For` hop. Without it the listener binds `::` and uses the socket peer address. Fleet mode does not imply it. | | `--verify` | off | Check and exit without serving. | | `--help` | off | Print usage and exit. | | `--version` | off | Print the version and exit. | Environment equivalents include `ADOS_MCP_AGENT_KEY`, `ADOS_AGENT_HOST`, `ADOS_NODE_ID`, `ADOS_MCP_HTTP_PORT`, `ADOS_MCP_HTTP_HOST`, `ADOS_MCP_FLEET`, `ADOS_MCP_FLEET_PATH`, `ADOS_MCP_DISCOVER`, `ADOS_MCP_OWNER`, `ADOS_MCP_TOKEN`, `ADOS_CONVEX_URL`, `ADOS_MQTT_URL`, `ADOS_MCP_AUDIT_PATH` and `ADOS_MCP_LOG_LEVEL`. ### Transports * **Streamable HTTP**: one endpoint, `POST /mcp`, with an SSE upgrade for streams. The primary networked transport. * **stdio**: the local one-liner a client launches. Its principal holds every scope except `flight` and `destructive`, passes the scope check like any other token, and declares that a human must be present. Presence on your laptop is not presence on the aircraft, so reaching the flight tools needs a flight-scoped `--token`. * **Unix socket**: `/run/ados/mcp.sock`, on-box in agent and local-fleet modes. Presence on that socket is the credential, so this principal skips the scope check. It does **not** skip the safety gate. ### The safety gate Every principal passes the class-specific safety gate, including the on-box socket principal. Presence on a socket is not a human confirming an action, so an `admin` call still needs its confirmation and a `flight` call still needs a fresh operator-present signal or a signed confirm bound to that call. Every call, allowed or denied, produces one redacted audit event. `--sim` only opts in to the SITL waiver. The server asks the target whether its flight controller is a simulator and refuses to start if it is not, so the waiver cannot be asserted onto real hardware. `readOnlyHint` and `destructiveHint` annotations are advertised honestly, but they are hints. The server is the enforcement point. ## Tools > [!WARNING] > > The `flight.*` tools arm, take off, change mode, land and return a real > aircraft. Read [Safety](/operations/safety) before you grant a `flight` scope. The connector exposes 48 tools at MCP protocol revision `2025-06-18`. Every deployment mode exposes the same set. The tools are grouped by prefix: | Group | What it covers | | - | - | | `status.*` | Node health, identity and live state. | | `telemetry.*` | Telemetry snapshots. | | `params.*` | Flight controller parameters. | | `config.*` | Agent configuration. | | `services.*` | Agent service state and restarts. | | `logs.*` | Agent logs. | | `plugins.*` | Installed plugins and their lifecycle. | | `admin.*` | Platform administration. | | `audit.*` | The connector's audit trail. | | `flight.*` | Flight actions, behind the `flight` scope and the safety gate. | | `vision.*` | Vision engine status, the latest detections, and target designation. | | `nav.*` | The navigation read-back: lidar pose and scan, navigation source, follow phase and range, live map session. | | `fleet.*` | Fleet listing in the fleet modes. | ### Vision and navigation tools | Tool | Class | Agent route | What it does | | - | - | - | - | | `vision.detections` | read | `GET /api/vision/detections/latest` | The latest detection batch per camera: boxes, labels, confidence and track ids. | | `nav.status` | read | `GET /api/v1/nav/status` | The latest `pose`, `scan`, `nav`, `follow` and `map` entries, each `{ts_ms, age_ms, data}` or `null` when nothing publishes that kind. See [Navigation and map routes](/drone-agent/rest-api#navigation-and-map). | | `vision.designate` | flight | `POST /api/vision/designate` | Locks a camera's tracker onto a box given in normalized `0..1` frame coordinates (`camera_id`, `bbox {x, y, width, height}`, optional `class_label` and `confidence`). | All three talk to the drone directly; they are not relayed through a ground station. `vision.designate` is a `flight`-class tool: an active follow retargets to the designated box, so it needs the `flight` scope and passes the safety gate (a `confirm_id` or simulation). No tool starts a follow; a follow begins only when an operator designates a subject and turns the Follow-Me Skill on. The full list, with each tool's scope class and annotations, is in [`catalog/tools-catalog.json`](https://github.com/altnautica/ADOS-MCP/blob/main/catalog/tools-catalog.json). A tool contributed by a plugin is floored at the scope its granted capabilities imply. Every non-read flight-control capability (for example `mavlink.write`, `msp.write`, `mission.write`, `estimator.pose.inject` and `vision.track.designate`) floors the tool at `flight`, and every `hardware.*` capability floors it at `admin`. A capability that is neither in the generated floor nor on the read and safe-write allowlist is treated as `admin`. See [Permissions](/developers/permissions) for the capability catalog. The [Mission Control MCP tab](/mission-control/mcp) has a guided wizard with a Docker / From source toggle. It fills in a node's host and pairing key, generates the `claude mcp add` command for the runtime you pick, builds the inline local-fleet blob for every node you own, and mints the machine credential for fleet mode. ## Extensions that contribute MCP tools An extension can contribute MCP `tools`, `resources` and `prompts` on both its agent and GCS halves. That contribution class needs `schema_version: 3` in `manifest.yaml`; `1` is the baseline and `2` unlocks the additional agent fields. See the [manifest reference](/developers/manifest). ## Next steps > [card] [MCP in Mission Control](/mission-control/mcp) > > Use the setup wizard to generate the add command and the fleet blob. > [card] [Security model](/developers/security-model) > > How credentials, scopes and capabilities fit together. > [card] [Revocation and incidents](/developers/revocation-and-incidents) > > Rotate and revoke credentials after an incident. > [card] [Hardening](/operations/hardening) > > Lock a node down before it leaves the bench. # Mission plugins Source: https://docs.altnautica.com/developers/mission-plugins Read the mission, replace it with operator approval, and contribute a mission template to the planner from a GCS plugin. A GCS plugin can read the mission in Mission Control, replace it on its own drone after the operator approves, and contribute a mission template to the planner. > [!WARNING] > > `mission.write` uploads a mission that the drone flies in an autonomous mode. Test generated missions in simulation first and read [Safety](/operations/safety) before flying one. ## Capabilities | Capability | Lets the plugin | | - | - | | `mission.read` | Read the mission, its progress and the current waypoint. | | `mission.write` | Replace the mission on the plugin's own drone, with operator approval. | | `ui.slot.mission-template` | Mount a template in the planner's pattern editor. | Risk levels are on [Permissions](/developers/permissions). ## Reading the mission `ctx.mission.read` takes a mission id argument but ignores it, and returns the planner's current state: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} const state = await ctx.mission.read("active"); // { // waypoints: Waypoint[], // the planner's waypoints // activeMission: { ..., waypoints: Waypoint[] } | null, // progress: ..., // currentWaypoint: ..., // } ``` The returned objects are copies; changing them does not change the planner. ## Writing the mission `ctx.mission.write` replaces the mission. The payload is `{ waypoints: [...] }` and must hold at least one waypoint: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} await ctx.mission.write({ missionId: "active", payload: { waypoints: [ { id: "wp1", lat: 12.97, lon: 77.59, alt: 30, frame: "relative" }, { id: "wp2", lat: 12.971, lon: 77.591, alt: 30, frame: "relative", holdTime: 5 }, ], }, }); ``` Each waypoint needs a string `id` and finite `lat`, `lon` and `alt`. Optional fields: | Field | Values | | - | - | | `command` | A navigation command the planner accepts. Anything else is rejected. | | `frame` | Altitude frame: `relative`, `absolute` or `terrain`. Defaults to the planner's frame. | | `speed`, `holdTime`, `param1`, `param2`, `param3` | Finite numbers. | The host rebuilds every waypoint from these fields, so unknown fields are dropped and a malformed waypoint rejects the whole write with the first problem it found. The write targets the plugin's own drone, is refused unless the drone is disarmed with a live FC link, shows the operator a confirmation dialog, and rejects with code `refused` if denied. In order, the host: 1. Validates the waypoints. 2. Refuses if the plugin is not bound to a connected drone, or the drone is armed, its arm state is unknown, or its flight controller link is down. 3. Runs the planner's own mission validator (geofence, zones, rally and the default altitude frame). An invalid mission is rejected with its errors. 4. Shows the operator a dialog naming the drone, the waypoint count, the altitude frame and any advisory issues. 5. After approval, reads the drone's state again and refuses if the arm state, link or flight controller changed while the dialog was open. The operator is notified of an approved write that was not uploaded. 6. Replaces the planner's waypoints (undoable) and uploads them to that drone. The SDK waits for the operator's answer instead of timing out. Geofence and rally points are not writable through `mission.write`. ## Contributing a mission template A template is a GCS bundle that mounts in the `mission.template` slot, inside the planner's pattern editor. It renders its own form, generates waypoints from the operator's input and writes them with `ctx.mission.write`, which shows the same confirmation dialog. Declare the template under `gcs.contributes.missionTemplates` (`mission_templates` is accepted too) along with the capabilities: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} gcs: permissions: - id: ui.slot.mission-template - id: mission.read - id: mission.write contributes: missionTemplates: - id: grid-survey title: "Grid survey" entrypoint: "gcs/grid-survey.bundle.js" ``` The full field list is on [Contribution points](/developers/contribution-points). ## Testing Run the mission path against the harness from `@altnautica/plugin-sdk/harness`. It applies the granted-capability check and records every RPC the plugin sends: ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} import { createPluginHarness } from "@altnautica/plugin-sdk/harness"; const harness = createPluginHarness({ grantedCapabilities: ["mission.read", "mission.write"], mount: async (ctx) => { await ctx.mission.write({ missionId: "active", payload: { waypoints: [{ id: "wp1", lat: 12.97, lon: 77.59, alt: 30, frame: "relative" }], }, }); }, }); await harness.start(); expect(harness.calls).toContainEqual( expect.objectContaining({ method: "mission.write" }), ); await harness.teardown(); ``` The harness does not run the host's waypoint checks or the confirmation dialog; test those against a simulated drone in Mission Control. ## Next steps > [card] [GCS plugin deep dive](/developers/gcs-plugin-deep-dive) > > The iframe sandbox, RPC and UI slots. > [card] [Contribution points](/developers/contribution-points) > > Every `contributes` key and its fields. > [card] [Safety](/operations/safety) > > Pre-flight checks before flying a plugin-generated mission. # Multi-component plugins Source: https://docs.altnautica.com/developers/multi-component-plugins Ship an agent half and a GCS half in one plugin: when to split, how the halves exchange state, shared manifest and failure modes. A plugin can ship two halves in one archive: * An **agent** half: a subprocess on the node, written in Python or Rust. * A **GCS** half: a TypeScript bundle that Mission Control runs in a sandboxed iframe. Each half has its own runtime, SDK and sandbox. The shared manifest, id, version and install state make them one plugin. The agent half declares its language with `agent.runtime: python` (the default) or `agent.runtime: rust`. A Python half uses the `ados.sdk` package; a Rust half links the `ados-sdk` crate. Both speak the same length-prefixed msgpack wire to the agent's plugin host. The GCS half uses `@altnautica/plugin-sdk` whatever language the agent half is written in. ## When to ship two halves Ship two halves when the plugin needs both: * Hardware or system access on the node. * An operator-facing UI in Mission Control. The panel in [Your first plugin](/developers/your-first-plugin) is GCS-only because it reads normalized telemetry and renders a readout. The first-party Vision Navigation extension is hybrid: a Rust agent half reads camera frames and writes MAVLink, and a GCS half renders the **Vision Nav** tab. Keep work in one half when it fits there. A plugin that only reads telemetry and renders a panel is GCS-only. A plugin that runs background work with no operator UI is agent-only. ## Lifecycle Both halves install from one `.adosplug` archive, and the operator approves both halves' permissions in one grid. The agent half runs under the agent's supervisor as its own sandboxed unit; the unit and sandbox names are on [Agent runtime and sandbox](/developers/agent-plugin-deep-dive). The GCS half mounts whenever a slot it contributes to renders in Mission Control. The halves start and stop independently. A GCS half can mount while its agent half is stopped, so render an offline state until state arrives. ## Cross-half communication The halves never call each other. The agent half publishes events on its own topics; the plugin host keeps the latest event per topic in the plugin's state sidecar, and Mission Control reads that sidecar. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Agent plugin (subprocess) | unix-socket IPC: event.publish v Plugin host (agent) -> state sidecar, latest event per topic | LAN: HTTP poll of /api/plugins//state (750 ms); cloud: heartbeat slice v Mission Control host | postMessage event v GCS plugin (iframe): ctx.events.subscribe ``` The GCS sees the latest payload per topic, not every event; carry a sequence or timestamp if you need ordering. Mission Control forwards a topic only when its timestamp changes, so a steady value does not replay. Publish on your plugin's own `plugin..` prefix from the agent half: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # agent half await ctx.events.publish( f"plugin.{ctx.plugin_id}.frame.ready", {"seq": 42, "ts_ms": now_ms()}, ) ``` ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}} // GCS half of the same plugin ctx.events.subscribe("plugin.com.example.thermal.frame.ready", (evt) => { redrawOverlay(evt.seq); }); ``` Publishing under your own `plugin..` prefix needs no capability. Reserved, never publishable: `vehicle.`, `mavlink.`, `mission.`, `safety.`, `agent.`, `swarm.`, `gps.`, `vision.`, `telemetry.`, and any `plugin.` topic outside your own `plugin..` prefix or your declared shared topics. Other topics need `event.publish`. The full rules are on [Agent event bus](/developers/event-hooks-and-bus). The GCS half reads these events through `ctx.events.subscribe`; it never opens a network connection of its own. ## Shared manifest One manifest with an `agent` block and a `gcs` block. The field reference is [Manifest](/developers/manifest). ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} schema_version: 1 id: com.example.thermal name: "Thermal overlay" version: "0.1.0" description: "Thermal readout on the video pane and a flight controller tab." license: "GPL-3.0-or-later" risk: medium compatibility: ados_version: ">=0.10.0" agent: entrypoint: "agent/plugin.py" isolation: subprocess permissions: - id: hardware.usb.uvc resources: max_ram_mb: 192 max_cpu_percent: 35 max_pids: 16 gcs: entrypoint: "gcs/plugin.bundle.js" isolation: iframe permissions: - id: ui.slot.video-overlay - id: ui.slot.fc-tab contributes: panels: - id: thermal-overlay slot: video.overlay - id: thermal-tab slot: fc.tab ``` The top-level fields (`id`, `name`, `version`, `license`, `risk`) are flat. Permissions are `- id: ` entries. Both halves share one `id` and `version`, so they form one install row. ## Version compatibility between halves Both halves ship in the same archive, so they always carry the same version. What can drift between releases is the shape of the data they exchange: * Event payloads published by the agent and read by the GCS. Put a `schema_version` field in each payload and branch on it in the GCS. * Stored data written by one half and read by the other. Carry a `data_version` in each record. See [State and storage](/developers/state-and-storage). The SDKs do not inspect payload schemas; keeping them backward compatible within a major version is your job. ## Driver code in the agent half Driver code lives in the agent half. In Python, subclass one of the driver base classes (`CameraDriver`, `GimbalDriver`, `LidarDriver`, `GpsDriver`, `EscDriver`, `PayloadActuatorDriver`); in Rust, implement the matching trait. The facade is `ctx.peripheral_manager`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: await ctx.peripheral_manager.register_camera_driver(ThermalCameraDriver()) ``` The agent does not route drivers today: `register_*_driver` calls return `not_implemented`. A driver plugin opens and runs its own device from its lifecycle hooks. See [Driver layer](/developers/driver-layer). ## Worked example: hybrid plugin skeleton ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} com.example.thermal/ ├── manifest.yaml ├── agent/ │ ├── plugin.py │ └── thermal_driver.py ├── gcs/ │ ├── plugin.bundle.js │ └── overlay.tsx └── locales/ └── en.json ``` For a file-path entrypoint such as `agent/plugin.py`, the runner loads the file directly and puts its directory on `sys.path`. Import sibling modules by name, not with a relative import: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from thermal_driver import ThermalDriver class Plugin: async def on_start(self, ctx) -> None: self.driver = ThermalDriver() await self.driver.open() await ctx.events.publish(f"plugin.{ctx.plugin_id}.status", {"online": True}) ``` The GCS half sets up its UI from the single `mount` call; the manifest decides which slot each panel renders in: ```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; import { mountUI } from "./ui"; definePlugin({ id: "com.example.thermal", version: "0.1.0", mount(ctx) { mountUI(ctx); }, }); ``` ## Failure modes | Scenario | What happens | | - | - | | Agent half stopped or crashed while the GCS half is mounted | The GCS half stays mounted and keeps the last payload per topic. Watch the payload timestamp and render an offline state when it stops moving. | | GCS half fails to load | The agent half keeps running. The slot shows an error tile for that contribution. | | Operator revokes a capability used by one half | Calls in that half that need it fail with `permission_denied`; the other half is unaffected. | ## Next steps > [card] [State and storage](/developers/state-and-storage) > > Where each half keeps data and how it survives updates. > [card] [Agent event bus](/developers/event-hooks-and-bus) > > Topics, publish and subscribe rules, and shared topics. # Developers overview Source: https://docs.altnautica.com/developers/overview Build plugins for ADOS Mission Control and the ADOS Drone Agent: one signed archive, two sandboxed halves. A plugin adds code, hardware support, UI panels and flight behaviors to ADOS without forking the core projects. One signed `.adosplug` archive installs on a drone or ground station node; from there each half runs in isolation with the capabilities the operator granted. Operators see installed plugins as **Extensions**. ## Two halves, one plugin A single `manifest.yaml` declares up to two halves. Either half is optional, so a plugin can ship agent-only, GCS-only, or both. * **Agent half** runs as its own systemd unit on the node, under a dedicated system user, inside the `ados-plugins.slice` cgroup with CPU, memory and process limits. It talks to the plugin host over a Unix domain socket using length-prefixed msgpack frames, gated by an HMAC capability token. Write it in **Python** (`runtime: python`) or **Rust** (`runtime: rust`); both speak the same wire to the same host. * **GCS half** runs in a sandboxed iframe inside Mission Control (`sandbox="allow-scripts"`, no same-origin, no network egress). It talks to the host over `postMessage`, and the host checks every call against the granted capabilities. Write it in **TypeScript**. The host gates every privileged call against the grants. A plugin that did not declare `mavlink.write` cannot write to the flight controller, and the operator approves each declared permission at install time. ## Pick your SDK All three SDKs speak the same capability-token contract to the same host, so the choice is the language you want to write in. > [card] [Python (agent)](/developers/sdk-python) > > `ados.sdk`: the plugin context, driver base classes, vision client > and test harness for a Python agent half. > [card] [Rust (agent)](/developers/sdk-rust) > > The `ados-sdk` crate: the same agent surface, compiled to a native > binary that runs directly under systemd. > [card] [TypeScript (GCS)](/developers/sdk-typescript) > > `@altnautica/plugin-sdk`: the browser-side SDK for a GCS half that > mounts panels in Mission Control. ## The four primitives Every plugin is described by four things: a **manifest** (what it is and what it asks for), a **signature** (who built it, verified before install), a **sandbox** (the isolation it runs inside), and a set of **capability tokens** (the only privileges it gets at runtime). Read [Concepts](/developers/concepts) for how they fit together. ## How plugins reach a node Plugin authors ship signed `.adosplug` archives. A node installs one from: * **A local file.** Choose **Install from file** on the node's **Extensions** tab in Mission Control, or run `ados plugin install .adosplug` on the node. * **A URL.** Install from a hosted archive, for example a GitHub Releases asset. See [Install from a URL](/developers/distribution-url-install). * **The first-party catalog.** First-party extensions and the built-in plugins install by id (`ados plugin install `, or from the list on the **Extensions** tab). Signing and key enrolment are covered in [Signing keys](/developers/signing-keys#bench-install-and-signing). ## License Plugins are independent works. GPL-3.0-or-later matches the host, but any [OSI-approved license](https://opensource.org/licenses) works. Closed-source plugins are allowed; they cannot link against ADOS GPL code at the source level. ## Next steps > [card] [Your first plugin](/developers/your-first-plugin) > > Scaffold, test, sign and install a GCS-only tab that reads battery > telemetry. > [card] [Concepts](/developers/concepts) > > Manifest, signature, sandbox and capability tokens. > [card] [Manifest](/developers/manifest) > > Every field the host reads. > [card] [Permissions](/developers/permissions) > > The capability catalog and its risk levels. # Parameter schema Source: https://docs.altnautica.com/developers/parameter-schema The schema subset, the ui widgets (including bitmask and camera) and the bindings for a plugin's native parameters, with worked examples. A plugin declares parameters under `gcs.contributes.parameters[]` (or nested inside a `settings` section). The GCS renders each as a native, dark-themed control, validates and clamps the committed value against the schema, and writes it to the binding you name. No iframe, no custom form code. A parameter has three parts: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} - key: standoff_distance_m # the config key the value is written under schema: { ... } # the JSON-Schema data contract (what is valid) ui: { ... } # how it renders (widget, label, grouping) binding: plugin.config # where the committed value is written ``` `schema` is the only required part beyond `key`. A missing or malformed `schema` drops the parameter at parse time (with a console warning); the rest of the manifest still loads. ## `schema`: the data contract `schema` is a Draft-07 JSON-Schema subset, deliberately scoped to what a drone-plugin parameter needs. Unknown keywords are ignored (forward-compatible), never an error. | Field | Type | Applies to | Notes | | - | - | - | - | | `type` | enum | all | `number`, `integer`, `boolean`, or `string`. Required. | | `minimum` | number | number, integer | Inclusive lower bound. | | `maximum` | number | number, integer | Inclusive upper bound. Must be `>= minimum`. | | `step` | number | number, integer | Quantization / UI step. Must be positive. | | `enum` | array | any scalar | Allowed values. When present, the value must be one of these. Pairs with the `enum` widget. | | `pattern` | string | string | Regex source applied to string values. Must be a valid regex. | | `default` | scalar | all | Applied when no stored value exists. Must itself be valid against the schema. | **Validation and clamping.** On every commit the host validates the value against the schema. Numbers are clamped to `[minimum, maximum]` and quantized to `step`; an `integer` is rounded. A string is checked against `pattern`. An `enum` value must be a member. An invalid value is rejected and the control reverts; a clampable value is clamped silently. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # An integer with bounds and a step - key: max_targets schema: type: integer minimum: 1 maximum: 16 step: 1 default: 4 # A pattern-validated string - key: camera_name schema: type: string pattern: "^[a-zA-Z0-9_-]{1,32}$" default: "front" # An enum (string members) - key: follow_mode schema: type: string enum: ["chase", "orbit", "lead"] default: "chase" ``` > [!NOTE] > > `integer` is a schema `type`, not a widget. Both `number` and `integer` > render with the `number` (or `range`) widget; `integer` adds the > round-to-whole rule on commit. ## `ui`: the presentation layer `ui` never affects validation. It only controls how a parameter is shown and grouped. | Field | Type | Notes | | - | - | - | | `widget` | enum | The control to render. Inferred from `schema.type` when omitted; `range`, `model`, `model_upload` are always explicit. | | `label` | string | The control label. Defaults to `key`. | | `group` | string | Section grouping in the rendered panel. | | `help` | string | Helper text under the control. | | `visible_if` | object | Conditional reveal: `{ key, equals }`. Shows the control only when another parameter's committed value equals `equals`. | | `task` | string | For `model` / `model_upload`: the vision task the picker lists (`detection`, `reid`, `depth`). | | `order` | number | Sort hint within a group. | | `bits` | list | For `bitmask`: the bit table, `[{ bit, label }]`. Labels are presentation only. | | `purpose` | string | For `camera`: the camera roster purpose (for example `detect`) whose cameras the picker lists first. | ### Widgets | Widget | Renders | Default for | | - | - | - | | `number` | A numeric input that clamps and quantizes on commit. | `type: number` / `integer` | | `range` | A slider between `minimum` and `maximum` stepping by `step`, with a live value readout. | (always explicit) | | `boolean` | A toggle. | `type: boolean` | | `enum` | A dropdown of the `enum` members, mapping the chosen string back to the typed value. | a schema with `enum` | | `bitmask` | An integer value edited as labelled bits. Set `ui.bits`. | (always explicit) | | `string` | A text input validated against `pattern`. | `type: string` | | `model` | The board-filtered model picker bound to the engine's active detector. | (always explicit) | | `model_upload` | The model picker with upload enabled. | (always explicit) | | `camera` | A camera picker. The value is a camera id or `auto`; `ui.purpose` orders matching cameras first. | (always explicit) | | `group` | A grouping marker (rare; prefer `ui.group` on each field). | (always explicit) | When `ui.widget` is omitted, the host infers: an `enum` schema becomes the `enum` widget, a `boolean` becomes `boolean`, a number/integer becomes `number`, and everything else becomes `string`. ### Grouping and conditional reveal Parameters are grouped by `ui.group` (groups order by first appearance, controls within a group by `ui.order` then declaration order). A control with `visible_if` shows only when the referenced parameter's committed value matches. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} contributes: parameters: - key: track_enabled schema: { type: boolean, default: false } ui: widget: boolean label: "Enable tracking" group: "Tracking" # Only shown when track_enabled is true - key: track_mode schema: type: string enum: ["center", "lead"] default: "center" ui: widget: enum label: "Tracking mode" group: "Tracking" visible_if: { key: track_enabled, equals: true } ``` ## `binding`: where the value is written The `binding` field routes the committed value. It defaults to `plugin.config` when absent. | Binding | Writes to | Read-back | | - | - | - | | `plugin.config` | The per-drone plugin config, over the LAN agent (local-first). | Mission Control reads the plugin's effective config from the agent (`GET /api/plugins//config`) when the panel opens, and falls back to the schema default only when the node is unreachable. | | `engine.detector` | The shared, engine-wide vision detector. Every vision consumer on that drone shares one detector. | The model picker owns the write and reports the new active model back, so the form tracks the live detector. | | `agent.config` | A whitelisted system config key on the agent. | Read-only on this surface; its write router is a separate surface. | ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # Default: per-drone plugin config - key: standoff_distance_m schema: { type: number, minimum: 2, maximum: 60, step: 0.5, default: 8 } ui: { widget: range, label: "Standoff distance" } binding: plugin.config # A whitelisted system key, shown read-only here - key: video_bitrate_kbps schema: { type: integer, minimum: 500, maximum: 20000, default: 4000 } ui: { widget: number, label: "Video bitrate" } binding: agent.config ``` > [!WARNING] > > On a `plugin.config` commit the host writes optimistically and rolls the > control back if the agent does not accept the write, so the surface never > shows a value the agent rejected. ## The `model` parameter: switch the vision detector A `model` (or `model_upload`) parameter binds to `engine.detector` and renders the board-filtered model picker. Selecting a model switches the drone's active vision detector engine-wide; every vision consumer on that drone then runs against the new model. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} gcs: permissions: - id: ui.slot.node-detail-tab contributes: # Register the models the picker can offer (per-board variants). models: - id: coco-yolov8n task: detection board_variants: - board_match: "rk3588" runtime: "rknn" input: "640x640" min_tops: 3 source: "https://example.com/models/coco-yolov8n-rk3588.rknn" sha256: "" - board_match: "cpu" runtime: "onnx" input: "640x640" source: "https://example.com/models/coco-yolov8n.onnx" sha256: "" # A model parameter that lets the operator switch the active detector. parameters: - key: detector schema: type: string default: "coco-yolov8n" ui: widget: model # render the model picker label: "Detector model" task: detection # the picker lists detection models group: "Vision" binding: engine.detector # switch the engine-wide detector ``` When the operator picks a model, the picker writes the engine-wide detector on the agent directly and reports the new active id back, so no second write happens and there is no optimistic rollback for this widget. Use `model_upload` instead of `model` when you want the operator to be able to upload their own model file. > [!NOTE] > > A `model` widget needs a drone context to write to. On a detached > preview (no selected drone) it falls back to a read-only display of the > current value rather than rendering a picker with nowhere to write. ## Full worked example A small follow-behavior plugin's parameter block, mixing a range, a toggle, a conditional enum, and a model switch: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} gcs: permissions: - id: ui.slot.settings-section - id: ui.slot.node-detail-tab - id: command.send contributes: settings: - id: follow-tuning title: "Follow tuning" icon: "sliders" parameters: - key: standoff_distance_m schema: { type: number, minimum: 2, maximum: 60, step: 0.5, default: 8 } ui: { widget: range, label: "Standoff distance", help: "Meters behind the subject." } - key: standoff_height_m schema: { type: number, minimum: 2, maximum: 40, step: 0.5, default: 6 } ui: { widget: range, label: "Standoff height" } - key: gimbal_track schema: { type: boolean, default: true } ui: { widget: boolean, label: "Point gimbal at subject" } - key: lost_behavior schema: { type: string, enum: ["hover", "rth"], default: "hover" } ui: { widget: enum, label: "On lost", visible_if: { key: gimbal_track, equals: true } } models: - id: coco-yolov8n task: detection board_variants: - board_match: "cpu" runtime: "onnx" input: "640x640" source: "https://example.com/models/coco-yolov8n.onnx" sha256: "" parameters: - key: detector schema: { type: string, default: "coco-yolov8n" } ui: { widget: model, label: "Detector model", task: detection } binding: engine.detector ``` ## Next steps > [card] [Contribution points](/developers/contribution-points) > > The `settings` and `parameters` contributions in context. > [card] [Scaffolder walkthrough](/developers/scaffolder-walkthrough) > > A plugin that contributes parameters end to end. > [card] [Vision plugins](/developers/vision-plugins) > > How the engine detector is consumed on the agent. > [card] [Lifecycle](/developers/lifecycle) > > How the agent half reads live config. # Payload actuator driver Source: https://docs.altnautica.com/developers/payload-actuator-driver Implement a PayloadActuatorDriver to control a sprayer, dropper, claw or sampler. > [!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 `PayloadActuatorDriver` controls a non-imaging payload: a sprayer, dropper, claw, sampler, winch, or any other actuator your plugin triggers. ## The interface ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.drivers.payload_actuator import ( PayloadActuatorDriver, PayloadCandidate, PayloadCapabilities, PayloadSession, PayloadCommand, PayloadState, ) class MyPayloadDriver(PayloadActuatorDriver): async def discover(self) -> list[PayloadCandidate]: ... async def open(self, candidate, config) -> PayloadSession: ... async def close(self, session) -> None: ... def capabilities(self, session) -> PayloadCapabilities: ... async def actuate(self, session, command: PayloadCommand) -> None: ... def get_state(self, session) -> PayloadState: ... ``` > [!NOTE] > > Writing the agent half in Rust? Implement `ados_sdk::drivers::PayloadActuatorDriver` from the `ados-sdk` crate. It has the same methods as the Python base class (discover, open, close, capabilities, actuate, get\_state). Set `agent.runtime: rust` in the manifest. In Rust, `actuate` returns `DriverError::InvalidParam` when `command.action_id` is not in `PayloadCapabilities::actions`, and `args` and `metadata` are msgpack value maps. ## Capabilities ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} PayloadCapabilities( actions=("arm", "trigger", "stop", "set_flow_rate"), has_position_feedback=False, has_flow_feedback=True, metadata={"max_payload_kg": 2.5, "update_hz": 10.0}, ) ``` `actions` is the tuple of `action_id` strings the driver accepts in `PayloadCommand`. `metadata` holds driver-specific values (maximum payload mass, refill volume, firmware version). ## Commands ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} PayloadCommand( action_id="trigger", args={"duration_s": 1.5, "intensity": 0.8}, ) ``` `action_id` is mandatory. `args` is a free-form dict the driver validates; raise `ValueError` on unknown keys. ## State ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} PayloadState( timestamp_ns=ns, last_action_id="trigger", busy=False, metadata={"flow_lpm": 0.0, "tank_pct": 65.0, "armed": True}, ) ``` `busy=True` while an action is in flight. Your plugin calls `actuate` itself; serialise calls per session in your plugin. A driver that sees a sustained fault reports it under `metadata["error"]` and raises `DriverError` on the next `actuate` call. ## Opening the driver from your plugin Your plugin opens the driver in `on_start` and calls `actuate` when its GCS half or a mission action asks for it. The pattern is on [Driver layer](/developers/driver-layer#running-a-driver-from-your-plugin). A GPIO-driven actuator needs `hardware.gpio_out`; a serial one needs `hardware.uart`. Risk levels are on [Permissions](/developers/permissions). > [!WARNING] > > A payload that moves or releases mass in flight is a flight-safety action. Read [Safety](/operations/safety) before you fly it. ## Next steps > [card] [Driver layer](/developers/driver-layer) > > The shared contract and the manifest table. > [card] [Permissions](/developers/permissions) > > The capability catalog and risk levels. > [card] [Hardware testing](/developers/hardware-testing) > > Test with a mock backend before the bench. # Performance and budgets Source: https://docs.altnautica.com/developers/performance-and-budgets Plugin resource budgets, cgroup throttling, memory pressure, and how to profile agent and GCS halves. A plugin runs on a small SBC alongside the rest of the agent. The plugin host budgets resources through systemd and the shared `ados-plugins.slice` cgroup. This page covers the budgets, how to spot when you blow them, and how to profile. Unit, cgroup and log names are explained on [Agent runtime and sandbox](/developers/agent-plugin-deep-dive#unit-name). ## Default budgets When a plugin's manifest does not declare resources, it gets: | Resource | Default cap | | - | - | | RAM | 96 MB | | CPU | 25% of one core | | PIDs | 12 | | Event-bus queue | 256 events per subscriber (drop-newest on overflow) | Declare different caps in the manifest: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: resources: max_ram_mb: 256 # 8 to 4096 max_cpu_percent: 30 # 1 to 100 max_pids: 8 # 1 to 256 ``` `class: heavy` (first-party only) raises the ceilings to 65536 MB, 3200 % and 4096 PIDs. A third-party manifest that sets it is refused at install. Honest declarations matter. The operator sees the requested budget in the install dialog. Asking for far more than you use is a bad signal; asking for too little ends with the kernel killing your process. The caps map straight to the plugin's unit: `max_ram_mb` to `MemoryMax`, `max_cpu_percent` to `CPUQuota`, `max_pids` to `TasksMax`. ## Find the plugin's cgroup The unit name carries an 8-hex hash, so ask systemd for the cgroup path rather than building it: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} systemctl show -p ControlGroup 'ados-plugin-com-example-battery-*' # ControlGroup=/ados.slice/ados-plugins.slice/ados-plugin-com-example-battery-c2d87e2a.service ``` Prefix that path with `/sys/fs/cgroup` in the commands below. ## Spotting cgroup throttling `max_cpu_percent` is enforced by the cgroup CPU controller. A plugin that breaches it does not crash; it gets throttled. The symptom is "everything got slower for no reason." ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cat /sys/fs/cgroup/cpu.stat ``` The interesting field is `nr_throttled`. If it climbs every second, your plugin is over budget. Optimize the code or declare a higher `max_cpu_percent`. ## Memory pressure `max_ram_mb` is enforced by `MemoryMax`. A breach OOM-kills the process. The unit restarts 2 s after each kill, indefinitely, so a plugin stuck over its cap loops rather than stopping; watch `oom_kill` in `memory.events` climb. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cat /sys/fs/cgroup/memory.current cat /sys/fs/cgroup/memory.events ``` `memory.events` shows `low`, `high`, `max`, `oom` and `oom_kill` counters. Any non-zero `high` or `max` means the kernel started applying pressure. To stay under the cap: * Process events on a bounded queue, not an unbounded list. * For ML models, prefer quantized weights (int8 over fp32). * Stream files; do not load whole logs into RAM. * Use `array.array` or `numpy` over a Python list of floats. ## Inspecting a running plugin `ados plugin info ` shows the plugin's recorded state and granted permissions. Pair it with the cgroup counters above and the plugin's log: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin info com.example.battery ados plugin logs com.example.battery --follow ``` A plugin running consistently near any cap is one bad input away from a throttle stall or an OOM kill. ## Profiling Python plugins The SDK does not bundle a profiler; use `cProfile` or `pyinstrument` inside your own start path: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import cProfile, pstats def on_start_profiled(self, ctx): pr = cProfile.Profile() pr.enable() try: return self._real_on_start(ctx) finally: pr.disable() pstats.Stats(pr).sort_stats("cumulative").print_stats(30) ``` Plugin stdout and stderr append to the plugin's log file, so profiler output lands there; read it with `ados plugin logs `. ## Profiling TypeScript plugins Open Mission Control, pick the plugin's iframe in browser devtools (Sources tab), and use the Performance recorder. The iframe is a real browsing context with the standard devtools surface. Common GCS hot paths: * React re-renders triggered by every telemetry event. Coalesce with `requestAnimationFrame` and a local ref. * Heavy SVG redraws. Switch to canvas past a few hundred paths. * Synchronous JSON parse in the message handler. Move it off the main thread. ## Event-loop discipline The biggest cause of agent-plugin stalls is a blocked event loop. A blocked loop stalls every IPC call and subscription; nothing restarts it for you. Don't: * `time.sleep(...)` in async code. * Heavy CPU work directly in `on_start`. * Synchronous I/O on a slow disk. Do: * `await asyncio.sleep(...)`. * `await asyncio.to_thread(heavy_work)`. * `aiofiles` or chunked reads for slow I/O. ## Disk and network discipline The plugin slice runs at a low I/O weight, so a plugin that writes hard loses every contended block to the flight services and stalls itself. A plugin writing a megabyte of samples per second to an SD card is already at the sustained-write ceiling for cheap cards. Batch writes (one `fsync` per second is plenty) and keep your own files bounded. Plugins with `network.outbound` share the drone's link with telemetry and video. Pull large payloads during ground time and cache them. ## Thermal behavior Sustained high CPU on a small SoC raises its temperature, and the kernel eventually throttles the whole package, which shows up as throttle events on every plugin, not just yours. A well-behaved plugin watches the system telemetry and backs off before the kernel forces the issue. ## Next steps > [card] [Versioning and updates](/developers/versioning-and-updates) > > Semver, compatibility ranges and automatic updates. > [card] [Agent runtime and sandbox](/developers/agent-plugin-deep-dive) > > Unit names, sandbox, restart policy and logs. # Plugin permissions Source: https://docs.altnautica.com/developers/permissions The capability catalog for both plugin halves, the risk levels, how each capability is enforced, and the install dialog flow. A plugin can only do what its manifest declares and the operator grants. The capability catalog is generated from one source (`capabilities.toml`) into the agent (Python and Rust) and Mission Control (TypeScript), so the halves cannot drift. This page is the canonical list of capabilities, their counts and their risk levels. There are 53 agent capabilities and 26 GCS capabilities. The GCS set is 13 UI slot capabilities plus 13 data, command, cloud and bus capabilities. A plugin can also define capabilities of its own for the data it shares (see [Plugin-declared capabilities](#plugin-declared-capabilities)). ## Risk levels Every capability carries a risk level. The install dialog badges each requested capability by its level. The manifest also declares a top-level `risk` for the whole plugin (`low`, `medium`, `high` or `critical`, default `medium`). | Level | Meaning | | - | - | | **Low** | Sandboxed or read-only. No flight or hardware effect. | | **Medium** | Touches shared hardware, opens the network, reads frames, or registers a sensor. | | **High** | Can command the vehicle, inject into the estimator, drive output hardware, accept inbound connections, or spawn subprocesses. | | **Critical** | Direct attitude and rate control of the aircraft (`flight.rate_setpoint`). | ## Declaring permissions Permissions go in the `agent.permissions` and `gcs.permissions` lists. Each entry is an object with an `id`, an optional `required` flag and an optional `degraded_behavior`; a bare string means required. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: telemetry.read required: true - id: recording.write required: false degraded_behavior: "Runs without saving clips." ``` Required permissions are pinned on in the install dialog. Optional permissions are shown with a toggle the operator sets. An id that is not in the catalog is a warning, not an error: the manifest loads, but the permission grants nothing. ## How capabilities are enforced 44 of the 53 agent capabilities are enforced, by one of three mechanisms: * **The dispatch gate** re-resolves the required capability from the method on every request and rejects an ungranted call. * **A handler-side check** covers what a method alone cannot classify, such as an event topic or a MAVLink message id. * **The generated unit's sandbox** covers the rest: the device policy, the socket address families and bind ports, and the mount namespace. See the [security model](/developers/security-model). The other nine are advisory metadata: `mavlink.component.camera`, `mavlink.component.gimbal`, `mavlink.component.payload`, `mavlink.component.peripheral`, `sensor.camera.register`, `sensor.depth.register`, `sensor.lidar.register`, `sensor.imu.register` and `sensor.payload.register`. GCS capabilities are enforced by the Mission Control bridge, which resolves the capability each call needs and checks it against the grant. ## The catalog The table covers both halves. Rows whose **Enforced** column reads `n/a` are GCS capabilities; an id listed twice (such as `event.publish` or `mission.write`) exists on both halves, one row for each. | Capability | Category | Risk | Enforced | Description | | - | - | - | - | - | | `button.subscribe` | hardware | medium | Yes | Lets the plugin receive press events (short, long, chord) from the host's front-panel buttons. Used by node plugins that drive an on-device workflow from physical buttons. Read-only; it does not remap or consume the buttons from other consumers. | | `camera.control.write` | hardware | medium | Yes | Lets the plugin set the exposure time, gain and auto-exposure mode of a capture camera (one configured for capture, which the vision engine streams from), and read back the values the camera actually took. Other cameras, including the video pipeline's own, are refused; simulated and network cameras answer that nothing was applied. | | `capture.storage.write` | data\_network | medium | Yes | Lets the plugin read the capture-storage state and write capture session directories under the agent's capture root, and raise the capture-active marker that switches the flight controller to its capture sensor rates. The agent's storage janitor still owns the budget, admission and eviction. | | `cloud.publish` | data\_network | medium | Yes | Lets the plugin publish small messages (at most 64 KiB each) on its own cloud stream through the agent's cloud relay, so a signed-in operator can receive them off the local network. Publishing detections onto the shared detection topic additionally needs vision.detection.publish. | | `cloud.read` | data\_network | low | n/a | Lets the plugin read shared fleet data from the cloud backend (drone status rows, paired devices, fleet roster). | | `cloud.records` | data\_network | medium | Yes | Lets the plugin write small JSON records (at most 64 KiB each) into its own collection in the operator's cloud account, where the plugin's GCS half can read them back. | | `cloud.records` | data\_network | low | n/a | Lets the plugin list, read, write and delete records in its own cloud collection for the signed-in operator (for example job history). Records are keyed by plugin, so a plugin can never read another plugin's records. Each record is capped at 64 KiB and each plugin at 5000 records. | | `command.send` | flight\_control | medium | n/a | Lets the plugin ask the GCS to send takeoff, land or return-to-launch to the drone it is bound to, or retarget that drone's follow tracker. The operator confirms every one of these in a prompt that names the drone. Arming, mode changes and every other command are refused. The same grant lets the plugin write its own per-drone configuration without a prompt. | | `display.oled.page` | hardware | low | Yes | Lets the plugin register a page (its rendered content and touch or hit zones) on the host's onboard display, so a plugin can present status without recompiling the display service. The host owns page switching and arbitration between contributed pages. | | `estimator.pose.inject` | flight\_control | high | Yes | Lets the plugin push pose samples (position, attitude, or both) directly into the autopilot state estimator. A bad pose stream produces unsafe position commands and fly-aways. | | `event.publish` | data\_network | low | Yes | Lets the plugin emit events on topics it has been granted access to. Other plugins and host services that subscribe to the same topic will receive the payload. | | `event.publish` | data\_network | low | n/a | Lets the plugin emit events on the in-memory GCS event bus other installed plugin panels subscribe to. The bus never leaves the browser tab; it carries no host authority of its own. | | `event.subscribe` | data\_network | low | Yes | Lets the plugin subscribe to topics it has been granted access to. The plugin sees payloads from other plugins and from host services that publish on those topics. | | `event.subscribe` | data\_network | low | n/a | Lets the plugin subscribe to topics on the in-memory GCS event bus and see payloads other installed plugin panels publish. | | `filesystem.host` | compute\_process | medium | Yes | Lets the plugin read and write files outside its own data directory. Required by plugins that ingest logs, maps, or other host-provided files. | | `flight.guided_setpoint` | flight\_control | high | Yes | Lets the plugin command the flight controller with guided-mode position or velocity setpoints (and the guided-mode entry and exit handshake) through a scoped sender, instead of raw MAVLink writes. The setpoint stream is the only flight-command surface this capability grants. | | `flight.rate_setpoint` | flight\_control | critical | Yes | Lets a plugin command the flight controller with SET\_ATTITUDE\_TARGET setpoints (an attitude quaternion and/or body rates, plus collective thrust) through a scoped sender, for GUIDED-mode vehicles that accept attitude/rate offboard control. This is a second flight-command surface alongside guided-mode position/velocity setpoints; the setpoint stream is the only flight-command surface this capability grants. | | `hardware.camera.csi` | hardware | medium | Yes | Lets the plugin capture video frames from CSI-attached cameras on the SBC's camera connector. Required by native camera drivers. | | `hardware.gpio` | hardware | medium | Yes | Lets the plugin read input pins and drive output pins on the SBC. Used by switches, LEDs, and discrete peripheral control. | | `hardware.gpio_out` | hardware | high | Yes | Lets the plugin drive a host GPIO output line high or low and play a bounded buzzer or LED beep pattern through the agent's GPIO-output service. Output-only; it does not read input pins. | | `hardware.gpu` | hardware | medium | Yes | Lets the plugin open the host's GPU and neural-accelerator device nodes (DRM render nodes, Mali, RKNPU, NVIDIA) for inference or rendering. Without it the plugin runs in a private /dev with no accelerator. | | `hardware.i2c` | hardware | medium | Yes | Lets the plugin talk to I2C devices on the SBC's I2C buses. Used by sensor drivers and small peripherals. | | `hardware.spi` | hardware | medium | Yes | Lets the plugin talk to SPI devices on the SBC's SPI buses. Used by displays and high-rate sensor drivers. | | `hardware.uart` | hardware | medium | Yes | Lets the plugin open and exchange data over UART serial ports. Required by GPS, range-finder, and modem drivers. | | `hardware.usb` | hardware | medium | Yes | Lets the plugin attach to and exchange bulk transfers with USB devices. Required by vendor SDK drivers that talk to specific USB peripherals. | | `hardware.usb.uvc` | hardware | medium | Yes | Lets the plugin capture video frames from USB Video Class cameras. Required by webcam and machine-vision drivers. | | `mavlink.component.camera` | flight\_control | medium | No | Lets the plugin register itself as a MAVLink camera component and respond to camera-related MAVLink messages from the GCS and the autopilot. | | `mavlink.component.gimbal` | flight\_control | medium | No | Lets the plugin register itself as a MAVLink gimbal manager or device and handle gimbal control messages. Required by gimbal driver plugins. | | `mavlink.component.payload` | flight\_control | medium | No | Lets the plugin register itself as a MAVLink payload component for actuators, droppers, and other mission-specific hardware. | | `mavlink.component.peripheral` | flight\_control | medium | No | Lets the plugin claim a MAVLink component id for a peripheral that does not fit the camera, gimbal, or payload categories. Used by sensor bridges and experimental devices. | | `mavlink.component.vio` | flight\_control | high | Yes | Lets the plugin register as a VIO source that publishes pose estimates over MAVLink. The autopilot can fuse these directly into the EKF, so a faulty source can cause unsafe flight behavior. | | `mavlink.read` | flight\_control | low | Yes | Lets the plugin observe the live MAVLink message stream, including telemetry, mode changes, and status text. Useful for analytics, logging, and dashboards. | | `mavlink.tunnel` | flight\_control | high | Yes | Lets the plugin exchange application payloads over MAVLink TUNNEL frames (a private payload\_type) on the existing link, without the full MAVLink write surface. Used for plugin-to-plugin or node-to-node application data carried inside the MAVLink stream. | | `mavlink.write` | flight\_control | high | Yes | Lets the plugin inject MAVLink commands to the autopilot, including mode changes, arming, and parameter writes. An untrusted plugin with this capability can take control of the aircraft. | | `mcp.expose` | data\_network | medium | Yes | Lets the plugin publish its declared tools, resources, and prompts to an MCP client, and lets the host route a tool invocation into the plugin. Exposure alone grants no host authority: each tool acts only through the plugin's OTHER granted capabilities, so a tool can never do anything the plugin could not already do. | | `mcp.expose` | data\_network | medium | n/a | Lets the plugin publish its declared GCS-half tools, resources, and prompts to an MCP client. A GCS-only tool routes through the GCS bridge (command / mission), so its effect is still bounded by the plugin's other GCS capabilities and the MCP token's scope. | | `mission.read` | flight\_control | low | Yes | Lets the plugin read the active mission, waypoints, fences, and rally points stored on the agent. | | `mission.read` | flight\_control | low | n/a | Lets the plugin read the active mission, waypoints, fences, and rally points that the operator has loaded into the GCS planner. | | `mission.write` | flight\_control | high | Yes | Lets the plugin upload new missions, edit waypoints, or change fence and rally definitions. Used by mission-planner and pattern-generator plugins. | | `mission.write` | flight\_control | high | n/a | Lets the plugin upload, edit, or replace missions in the GCS planner. Used by pattern generators and mission-template plugins. | | `msp.read` | flight\_control | low | Yes | Lets the plugin observe the raw MSP byte stream from a Betaflight / iNav / KISS flight controller, so it can decode telemetry, sensor, and status replies. Read-only on the MSP stream; the sibling of mavlink.read for an FC that speaks MSP instead of MAVLink. | | `msp.write` | flight\_control | high | Yes | Lets the plugin write raw MSP commands to a Betaflight / iNav / KISS flight controller, including MSP\_SET\_RAW\_RC (the RC channel values that fly the aircraft in a rate mode). An untrusted plugin with this capability can command the aircraft, exactly like mavlink.write on a MAVLink FC. | | `network.listen` | data\_network | high | Yes | Lets a declared plugin service bind the TCP ports it lists in its manifest (listen\_ports) so other nodes on the network can reach it, and advertise those ports on the local network over mDNS through the agent. Every other port stays closed to the plugin, and the plugin's main process never listens. | | `network.outbound` | data\_network | medium | Yes | Lets the plugin make outbound TCP, UDP, and HTTP connections from the agent host, and find services on the local network over mDNS through the agent. Required by plugins that talk to external services. | | `node.info.read` | hardware | low | Yes | Lets the plugin read what kind of node it runs on: the node profile, the board and whether it has a neural accelerator, the ground-station role, whether the camera pipeline is up, and the main video stream's size and frame rate. Read-only facts; no telemetry, imagery, credentials or configuration values. | | `perception.read` | data\_network | low | n/a | Lets the plugin read the drone's perception state: where detection runs (on the drone or offloaded to a compute node), the bound compute node, and the live session health (feed freshness, throughput). Read-only on derived data; it does not open or read the camera. | | `perception.subscribe` | data\_network | low | n/a | Lets the plugin subscribe to the live detection stream (bounding boxes, classes, track ids) for the drones the operator has paired, the same detections the cockpit already renders. Read-only; the detections are derived data, not the raw camera feed. | | `process.spawn` | compute\_process | high | Yes | Lets the plugin launch helper subprocesses listed in its manifest's spawn allowlist. Required to ship vendor-binary drivers and language runtimes outside the Python plugin host. | | `radio.aux_stream` | data\_network | high | Yes | Lets the plugin open a dedicated auxiliary stream on the radio link (a separate radio-port from the data and control planes) managed by the radio service, and read or write application frames on it. Used by plugins that need an isolated low-rate channel between nodes. | | `recording.write` | data\_network | low | Yes | Lets the plugin save video, telemetry, or analysis outputs into the agent's recording store so the GCS and post-flight tools can find them. | | `recording.write` | data\_network | low | n/a | Lets the plugin write recordings (video, telemetry CSV, analysis output) into the GCS recording library so the operator can replay them later. | | `sensor.camera.register` | hardware | medium | No | Lets the plugin declare a camera device the rest of the agent and the GCS can address (live preview, recording, mission usage). | | `sensor.depth.register` | hardware | medium | No | Lets the plugin declare a depth-camera or stereo sensor. Downstream services can consume depth maps for obstacle avoidance and SLAM. | | `sensor.imu.register` | hardware | medium | No | Lets the plugin declare a secondary IMU device the rest of the agent can address. Often paired with VIO and odometry workflows. | | `sensor.lidar.register` | hardware | medium | No | Lets the plugin declare a LiDAR device. Downstream services can consume point clouds for mapping and obstacle avoidance. | | `sensor.payload.register` | hardware | medium | No | Lets the plugin declare a payload device (sprayer, dropper, sampler) so missions and the GCS can address it. | | `sensor.stream.read` | data\_network | medium | Yes | Lets the plugin subscribe to the agent's sensor bus: timestamped IMU batches, raw GNSS receiver bytes, camera trigger records, barometer, magnetometer and clock samples, plus the clock state file. Used by capture and odometry plugins that need every sample on the host timebase. | | `sensors.rig.write` | hardware | medium | Yes | Lets the plugin store the rig document (sensor roles, intrinsics and extrinsics) the agent validates and the sensor hub fuses with, through the same validation the operator's rig write runs. An invalid document is refused and the stored one kept. | | `telemetry.extend` | data\_network | low | Yes | Lets the plugin add new fields to the telemetry stream that ships to the GCS. Used by sensor plugins that surface custom readings on the dashboard. | | `telemetry.read` | data\_network | low | Yes | Lets the plugin read the same telemetry feed the GCS consumes (battery, GPS, attitude, mode). Useful for logging and analytics. | | `telemetry.subscribe` | data\_network | low | n/a | Lets the plugin subscribe to live telemetry streams (attitude, GPS, battery, mode) for the drones the operator has paired with the GCS. | | `ui.slot.cockpit-panel` | ui\_slot | low | n/a | Lets the plugin add a panel to the in-flight cockpit quick-settings surface, scoped to the currently selected drone. | | `ui.slot.cockpit-widget` | ui\_slot | low | n/a | Lets the plugin place a small widget in one of the cockpit's corner zones over the live video, scoped to the drone the cockpit is flying. The widget renders inside a sandboxed iframe with no host DOM access. | | `ui.slot.fc-tab` | ui\_slot | low | n/a | Lets the plugin add a tab to the per-drone flight controller area. The tab renders inside a sandboxed iframe with no host DOM access. | | `ui.slot.flight-skill` | ui\_slot | medium | n/a | Lets the plugin register a flight skill that appears in the cockpit Skill Bar, can be bound to a hotkey or gamepad button, and activated by the operator. Activation flips the plugin's per-drone config; the cockpit's arm and confirmation gates still apply. | | `ui.slot.hardware-tab` | ui\_slot | low | n/a | Lets the plugin add a tab on the Hardware page so the operator can inspect or configure devices the plugin manages. | | `ui.slot.map-overlay` | ui\_slot | low | n/a | Lets the plugin draw geometry on the map view (polygons, markers, heatmaps). The overlay is rendered in a sandboxed canvas. | | `ui.slot.mission-template` | ui\_slot | low | n/a | Lets the plugin add a new entry to the mission template picker so the operator can start missions with the plugin's parameters. | | `ui.slot.node-agent-page` | ui\_slot | low | n/a | Lets the plugin add a page to the sectioned Agent sidebar of a node's detail panel, next to the built-in companion and configuration pages. The page is scoped to the selected node. | | `ui.slot.node-detail-tab` | ui\_slot | low | n/a | Lets the plugin add a per-node tab inside the node detail panel on any node profile (drone, ground station, compute). The tab is scoped to the currently selected node. | | `ui.slot.node-surface` | ui\_slot | low | n/a | Lets the plugin add a top-level surface to the node detail tab strip for the node profiles it declares (for example a workstation overview). The surface is scoped to the selected node. | | `ui.slot.notification-channel` | ui\_slot | low | n/a | Lets the plugin push notifications into the GCS notification center so it can surface alerts and status changes to the operator. | | `ui.slot.settings-section` | ui\_slot | low | n/a | Lets the plugin add its own section to the GCS Settings page so the operator can configure the plugin from a single place. | | `ui.slot.video-overlay` | ui\_slot | low | n/a | Lets the plugin draw overlays on top of the live video feed (detection boxes, telemetry HUDs). The overlay is rendered above the player. | | `video.source.set` | data\_network | medium | Yes | Lets the plugin declare the camera and stream sources the agent's video pipeline should serve (one primary plus optional secondary legs), so a smart-camera or pod driver can auto-configure its own feeds without an operator hand-typing them. Applying a new source list restarts the video pipeline. | | `video.whep.relay` | data\_network | medium | Yes | Lets the plugin open and close WebRTC playback (WHEP) sessions on the agent's live camera streams on behalf of a viewer it serves: it hands the agent a viewer's SDP offer for a camera and relays the answer back. The agent only plays out streams it already publishes; the plugin cannot change them or reach the media server directly. | | `vision.detection.publish` | data\_network | low | Yes | Lets the plugin publish detection results (bounding boxes, class labels, confidence, track ids) that other plugins, overlays, and mission logic can consume. Detections are derived data; they do not command the vehicle. | | `vision.detection.subscribe` | data\_network | low | Yes | Lets the plugin receive the detection batches the vision engine publishes (bounding boxes, class labels, confidence, and the tracker's stable track id and lock state on the locked object). Detections are derived data; subscribing does not command the vehicle or open the camera. | | `vision.frame.read` | compute\_process | medium | Yes | Lets the plugin subscribe to normalized camera frames the vision engine publishes (resolution and pixel format set by the engine). Frames are shared read-only; the plugin does not open the camera itself. | | `vision.model.read` | compute\_process | low | Yes | Lets the plugin read the resolution of its own declared models: for each model the state (resolved, needs-model, verify-failed), the resolved on-disk path and runtime when resolved, and the reason otherwise. This is how a plugin finds where its delivered model was cached so it can load it. Reads only this plugin's own resolution; it does not read frames, other plugins' models, or command the vehicle. | | `vision.model.register` | compute\_process | medium | Yes | Lets the plugin register an inference model (and its input format and output classes) so the vision engine can load and run it, or so the plugin can run it against shared frames. Registered models appear to detection consumers. | | `vision.offload.advertise` | compute\_process | medium | Yes | Lets the plugin report the perception offload link it holds (whether a compute node is paired, whether the bearer to it is good enough, its address and the model it runs). The node's perception tier and status read it. The agent counts the node as paired only when the advertised address answers, and only one plugin owns the link at a time. | | `vision.track.designate` | flight\_control | medium | Yes | Lets the plugin choose which object the vision engine's single-object tracker locks onto (the follow target), by naming the box to track. This selects a target for downstream follow / framing logic; designation alone does not command the vehicle. | | `vision.track.designate` | flight\_control | medium | n/a | Lets the plugin ask the GCS to set the vision engine's follow target on the drone it is bound to, by naming the detection box to track. Designation selects a target for downstream follow and framing logic; it does not command the vehicle. | ### Telemetry topics On the GCS half, declare one `telemetry.subscribe.` per stream you read (for example `telemetry.subscribe.battery`). The bridge checks the topic-scoped id exactly; the bare `telemetry.subscribe` grants no stream. ### Commands and designation `command.send` lets a GCS half ask for takeoff, land or return-to-launch on its bound drone; the operator confirms each one and every other command is refused. Retargeting the drone's follow tracker (`command.send` with `vision.designate`) needs the separate `vision.track.designate` capability. ### Node-scoped UI slots `ui.slot.node-detail-tab`, `ui.slot.node-agent-page`, `ui.slot.node-surface`, `ui.slot.cockpit-panel`, `ui.slot.cockpit-widget` and `ui.slot.flight-skill` are scoped to the selected drone; the other seven are fleet-level. Where each slot renders is on [Contribution points](/developers/contribution-points#the-slot-taxonomy). ## Plugin-declared capabilities A plugin that shares data on the event bus can define a capability for it under `agent.declared_capabilities`, with an id of the form `plugin..` (the leaf is the last segment of the plugin id), a risk and a description. Its `shared_topics` name that capability as the one a subscriber needs. Another plugin requests it like any catalog capability, and the install dialog shows it with the declared risk and description. The World Engine, for example, declares `plugin.world-engine.world.read` for its point cloud, occupancy, splat and mesh topics. See [Shared topics and declared capabilities](/developers/manifest#shared-topics-and-declared-capabilities). ## Two-stage install 1. The operator opens the drone's **Extensions** tab and chooses **Install from file**, or picks an extension from the list. 2. The agent parses the archive in memory: it validates the manifest, verifies the Ed25519 signature, checks compatibility, and returns a summary with the requested permissions, the signer and the risk. Nothing is written to disk. 3. The review shows the summary, the board compatibility and the permission grid grouped by category, with required permissions pinned. The operator sets the optional toggles and chooses **Install**, a button that names how many permissions it grants. 4. Only then does the agent unpack the archive and write the install record, and Mission Control grants the approved permissions. A plugin that never gets past step 3 leaves no trace. From a shell, `ados plugin install` shows the same summary and asks for approval; see the [Plugin CLI reference](/developers/cli-reference#install). ## Permissions on update Auto-update does not apply a version that asks for new permissions; the node reports `update_available` with the new permissions, and the operator reinstalls to approve them. Grants are recorded per permission, independent of enable and disable. An operator can grant or revoke a declared permission at any time from Mission Control or with `ados plugin perms`; the change takes effect at once, with no restart. ## Capability tokens on the wire Every plugin process runs with a capability token the host mints, bound to the plugin id, the granted capability set, a session id and an expiry. The host checks the token and the required capability before routing each request. A plugin cannot claim a capability by lying in the envelope: the host re-resolves the required capability from the method (and, for the event bus, from the topic) and rejects an ungranted call. The agent replies `capability_denied: `; the Mission Control bridge replies `permission_denied`. ## Next steps > [card] [Manifest](/developers/manifest) > > Where permissions are declared, and every other field. > [card] [Security model](/developers/security-model) > > What each capability exposes if a plugin misbehaves. # Revocation and incidents Source: https://docs.altnautica.com/developers/revocation-and-incidents Revoke a plugin signer, archive or release on the agent, what happens to installed plugins, and how to report a security issue. Revocation is the response when a signing key, a published archive or a plugin release turns out to be unsafe. The agent enforces a local revocation list: plugins signed by a revoked key, installed from a revoked archive, or at a revoked version are stopped and disabled, and cannot be installed or enabled again. Files are not deleted. ## The revocation list ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} /etc/ados/plugin-revocations.json ``` The installer writes an empty list when the file is absent and never overwrites an existing one: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} {"signers": [], "archives": []} ``` * `signers` holds revoked signer ids. It covers every plugin signed by that key. * `archives` holds lowercase sha256 hex digests of `.adosplug` files. It covers one exact archive. * `versions` holds `@` entries, for example `com.example.my-plugin@1.0.3`. It covers one release of one plugin, whatever archive it came from. The key is optional. A bare JSON array of signer ids (`["example-2025-X"]`) is also accepted, and so is the registry's own shape (`signer_keys`, `plugin_versions`, `generated_at`). An entry in `versions` that is not `@` makes the file unreadable. A file that exists but cannot be read or parsed is treated as fail-closed: signed plugins are refused install and enable with `revocation_list_unreadable` until it reads, and the plugin host keeps enforcing the last good list. ## Where entries come from * **You.** Edit the file directly or distribute it through your own configuration management. * **The registry.** About a minute after start and then once a day, the agent fetches the registry's `/v1/revoked.json` (see [Catalog and registry](/developers/distribution-registry#registry-api)) and merges it into the local list: `signer_keys` into `signers`, `plugin_versions` into `versions`. The merge is add-only: it never removes an entry you or an earlier fetch added. A failed fetch is logged and retried at the next cycle. ## What happens when the list changes The plugin host checks the file every 5 seconds and at start. No restart is needed. Within about 5 seconds of a change: | Surface | Behavior | | - | - | | Installed plugins | Every plugin signed by a revoked id, installed from a revoked archive, or at a revoked version is stopped and disabled, with `failure_reason` `signer_revoked`, `archive_revoked` or `version_revoked`. `GET /api/plugins` and `GET /api/plugins/{id}` return the `failure_reason`. | | Armed vehicle | If the vehicle counts as armed (unknown or stale state counts as armed), the disable is deferred and applied on disarm. | | Enable and install | `ados plugin enable` is refused with `refused: signer_revoked` (or `archive_revoked`, `version_revoked`). A new install of a revoked signer, archive or version is refused, even in unsigned bench mode. | | Logs | The plugin host logs `plugin_disabled_revoked` to the journal: `journalctl -u ados-plugin-host \| grep revoked` (or `ados logs query` when the log store is enabled). | | Files | The install directory under `/var/ados/plugins//` stays in place, so you can take a forensic copy before removal. | > [!WARNING] > > A revocation disables plugins as soon as the vehicle is disarmed. Plan a replacement before you revoke a key that a fleet depends on in flight. See [Safety](/operations/safety). Your options for a disabled plugin: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin info ados plugin logs ados plugin remove ``` ## Issuing a revocation When a key is compromised or a publisher leaves your trust set: 1. Add the signer id, the archive digest or the `@` release to `/etc/ados/plugin-revocations.json` on every agent. 2. Generate a fresh key, enrol its public key, and re-sign your current releases (see [Signing keys](/developers/signing-keys)). 3. Tell operators which plugins are affected and which releases replace them. The registry also records signer-key and plugin-version revocations, hides a revoked version from the catalog, and publishes the list at `/v1/revoked.json`. ## Operator checklist 1. Read the reason. A safety reason means ground the affected vehicles first. 2. Run `ados plugin list` on every node to find affected plugins. 3. Install the replacement release. 4. `ados plugin remove ` for the revoked install. 5. Confirm the refusal and removal in `journalctl -u ados-plugin-host`. ## Reporting a security issue This page is the one home for security reporting across the agent, Mission Control and extensions. If you believe a plugin or an ADOS component is malicious, broken in a way that affects flight safety, or leaking data, report it privately: use the contact channel on [altnautica.com](https://altnautica.com) and mark the message as a security report. Do not open a public issue. Include: 1. The plugin id and version, or the component and version. 2. The signer id (from `ados plugin info ` or the archive's `SIGNATURE` file). 3. What happens, with reproduction steps where possible. 4. The operator-facing impact (data loss, vehicle behavior, information disclosure). 5. Whether you have already disclosed publicly, with a link if so. 6. Logs, captures or analysis output that support the report. 7. How you would like to be credited, if at all. We acknowledge and triage, investigate, revoke the affected signer or archive and ship a fix, then coordinate disclosure with you and publish what changed. We default to coordinated disclosure and ask for a heads-up if you disclose on your own timeline. Plugin authors should give their own users the same: a private reporting channel stated in the plugin's README. ## Next steps > [card] [Signing keys](/developers/signing-keys) > > Generate and enrol a replacement key. > [card] [Legal and licensing](/developers/legal-and-licensing) > > Licences and distribution channels. # Rust crates Source: https://docs.altnautica.com/developers/rust-crates ADOS libraries on crates.io: what each does, how to add it, and how they are versioned. The ADOS Drone Agent publishes its reusable Rust code as separate crates on crates.io. All of them live in the [`crates/` workspace](https://github.com/altnautica/ADOSDroneAgent/tree/main/crates#published-crates) of the agent repository. The platform crates speak the agent's wire or read its board profiles; the standalone crates have no ADOS dependency and work in any project. **Platform (versioned with the ADOS Drone Agent)** | Crate | What it does | Add it | Docs | | - | - | - | - | | [`ados-protocol`](https://crates.io/crates/ados-protocol) | Wire contracts of the ADOS Drone Agent: IPC framing, plugin RPC envelope, capability tokens and the vision frame bus. | `cargo add ados-protocol` | [docs.rs](https://docs.rs/ados-protocol) | | [`ados-sdk`](https://crates.io/crates/ados-sdk) | Write Rust plugins for the ADOS Drone Agent: IPC client, plugin context, driver traits and lifecycle runner. | `cargo add ados-sdk` | [docs.rs](https://docs.rs/ados-sdk) | | [`ados-vision`](https://crates.io/crates/ados-vision) | Single-object visual tracker: Kalman motion model, appearance re-identification and YOLOv8 head decoding. | `cargo add ados-vision` | [docs.rs](https://docs.rs/ados-vision) | | [`ados-gpio`](https://crates.io/crates/ados-gpio) | Drive status buzzers and LEDs on Linux GPIO lines, with bounded software-PWM beep patterns. | `cargo add ados-gpio` | [docs.rs](https://docs.rs/ados-gpio) | | [`ados-hal-probe`](https://crates.io/crates/ados-hal-probe) | Find out what a board's hardware can really do by probing it, plus bundled board profiles. | `cargo add ados-hal-probe` | [docs.rs](https://docs.rs/ados-hal-probe) | **Standalone** | Crate | What it does | Add it | Docs | | - | - | - | - | | [`ados-sensorhub`](https://crates.io/crates/ados-sensorhub) | Sensor hub wire protocol: COBS framing, CRC-16 and fixed-layout IMU, baro, mag and GNSS packets. no\_std. | `cargo add ados-sensorhub` | [docs.rs](https://docs.rs/ados-sensorhub) | | [`ados-offload`](https://crates.io/crates/ados-offload) | Choose where perception runs (onboard, offloaded or hybrid) and hold the vehicle when results go stale. | `cargo add ados-offload` | [docs.rs](https://docs.rs/ados-offload) | | [`ados-macpin`](https://crates.io/crates/ados-macpin) | Stable MAC addresses for Linux network adapters that randomize theirs every boot. | `cargo add ados-macpin` | [docs.rs](https://docs.rs/ados-macpin) | | [`ados-lora`](https://crates.io/crates/ados-lora) | LoRa transmit governor with cited regional band plans, duty cycle, dwell time and airtime accounting. | `cargo add ados-lora` | [docs.rs](https://docs.rs/ados-lora) | | [`ados-crsf-codec`](https://crates.io/crates/ados-crsf-codec) | no\_std CRSF / ExpressLRS codec for RC channels, telemetry and parameter frames. | `cargo add ados-crsf-codec` | [docs.rs](https://docs.rs/ados-crsf-codec) | | [`ados-positioning`](https://crates.io/crates/ados-positioning) | Split mixed UBX, NMEA and RTCM3 GNSS streams, configure u-blox receivers and run an RTK base survey-in. | `cargo add ados-positioning` | [docs.rs](https://docs.rs/ados-positioning) | | [`ados-rtcm`](https://crates.io/crates/ados-rtcm) | RTCM3 framing, CRC-24Q and MAVLink GPS\_RTCM\_DATA fragmentation for RTK corrections. | `cargo add ados-rtcm` | [docs.rs](https://docs.rs/ados-rtcm) | | [`ados-clock`](https://crates.io/crates/ados-clock) | Map remote clocks onto the host clock: least-squares and envelope fits, TIMESYNC and a chrony sink. | `cargo add ados-clock` | [docs.rs](https://docs.rs/ados-clock) | | [`ados-swarm`](https://crates.io/crates/ados-swarm) | Swarm control laws: separation, flocking, formations, CBBA task allocation and a point-mass simulator. | `cargo add ados-swarm` | [docs.rs](https://docs.rs/ados-swarm) | | [`ados-mavlink-tunnel`](https://crates.io/crates/ados-mavlink-tunnel) | Send large messages over MAVLink TUNNEL frames with chunking and bounded reassembly. | `cargo add ados-mavlink-tunnel` | [docs.rs](https://docs.rs/ados-mavlink-tunnel) | | [`ados-display-driver`](https://crates.io/crates/ados-display-driver) | Small-display output on Linux: SSD1306/SH1106 OLED over I2C, pixel packers and a framebuffer writer. | `cargo add ados-display-driver` | [docs.rs](https://docs.rs/ados-display-driver) | | [`ados-hmi`](https://crates.io/crates/ados-hmi) | Front-panel input: touchscreen calibration and gestures, button presses and rotary encoders. | `cargo add ados-hmi` | [docs.rs](https://docs.rs/ados-hmi) | ## Versioning * **Platform crates move in lockstep with the agent.** `ados-protocol`, `ados-sdk`, `ados-vision`, `ados-gpio` and `ados-hal-probe` carry the agent version, so `ados-sdk` X.Y.Z speaks the wire of agent X.Y.Z. Pin the major.minor of the agent you target. * **Standalone crates follow their own semver.** They started at 0.1.0 and bump only when they change. Any change to a published crate's packaged files ships with a version bump. To build an agent plugin, start with the [Rust SDK guide](/developers/sdk-rust). ## License Every crate is licensed under either of Apache License 2.0 or MIT at your option, except `ados-sensorhub`, which is MIT. The agent services themselves stay GPL-3.0-or-later. See [Legal and licensing](/developers/legal-and-licensing). # Scaffolder walkthrough: a hybrid plugin Source: https://docs.altnautica.com/developers/scaffolder-walkthrough Scaffold a hybrid plugin with create-ados-plugin: a flight skill, a node-detail tab, native parameters, a click-to-follow target action and a Python agent half. This walkthrough scaffolds one hybrid plugin and reads through what the template gives you: a **flight skill** in the cockpit Skill Bar, a **node-detail tab**, native **parameters** (including a model picker), and a Python **agent half** that reads the live config and publishes its state. It then adds a **target action**, so the operator can click a detected person in the cockpit and follow it. By the end you have a signed archive that installs on a drone. The pattern matches the [Follow-Me extension](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/follow-me), trimmed to the parts that matter here. ## Prerequisites * Node.js 20+ and pnpm 9+. * Python 3.11+ and [uv](https://docs.astral.sh/uv/) for the agent-half tests, plus the `cryptography` package for signing. * bash with `rsync` and `zip` for `scripts/pack.sh` (Linux or macOS; on Windows use WSL). * Mission Control connected to a drone that runs the ADOS Drone Agent. ## 1. Clone and scaffold ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/altnautica/ADOSExtensions.git cd ADOSExtensions pnpm install pnpm --filter @altnautica/plugin-sdk build node packages/create-ados-plugin/bin/cli.mjs \ --target extensions/track-follow \ --id com.example.track-follow \ --half hybrid \ --author "Your Name" \ --signer my-publisher-2026-A pnpm install ``` The hybrid template lays out both halves with their tests: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} extensions/track-follow/ ├── manifest.yaml ├── package.json ├── README.md ├── .gitignore ├── locales/en.json ├── agent/ │ ├── plugin.py │ ├── pyproject.toml │ └── tests/test_plugin.py └── gcs/ ├── package.json ├── tsconfig.json ├── vitest.config.ts ├── src/plugin.ts └── tests/plugin.test.ts ``` ## 2. The manifest The generated `manifest.yaml` declares both halves. The parts that matter, with the template's `__PLUGIN_ID__` already filled in: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} schema_version: 2 id: com.example.track-follow name: "Hello Hybrid Plugin" version: "0.1.0" risk: low compatibility: ados_version: ">=0.95.0" gcs_version: ">=0.34.0" agent: runtime: python entrypoint: "plugin:HelloPlugin" isolation: subprocess per_drone_config: true permissions: - id: event.publish resources: max_ram_mb: 64 max_cpu_percent: 10 max_pids: 4 gcs: entrypoint: "gcs/plugin.bundle.js" isolation: iframe permissions: - id: ui.slot.flight-skill - id: ui.slot.node-detail-tab - id: command.send contributes: skills: - id: hello label: "skill.label" icon: "sparkles" category: utility toggle: true confirm: false arm_requirement: any default_binding: key: "h" activation: via: config config_key: active state: via: event topic: "hello.state" tabs: - id: hello-tab slot: node.detail.tab profile: ["drone"] title: "tab.title" icon: "sparkles" order: 90 parameters: - key: rate_hz binding: plugin.config schema: { type: number, minimum: 1, maximum: 20, step: 1, default: 5 } ui: { widget: range, label: "settings.rate", group: "settings.group", order: 10 } - key: greeting binding: plugin.config schema: { type: string, enum: ["hello", "namaste", "hola"], default: "hello" } ui: { widget: enum, label: "settings.greeting", group: "settings.group", order: 20 } - key: detector binding: engine.detector schema: { type: string, default: "coco-person" } ui: { widget: model, task: detection, label: "settings.detector", group: "settings.group", order: 30 } locales: - en ``` Labels such as `skill.label` are keys into `locales/en.json`. There is no `supported_boards`, so the plugin installs on any board; to restrict it, list board ids or SoCs from [Supported hardware](/drone-agent/supported-hardware), or `"*"` for any board. **1. skills: the Skill Bar** `ui.slot.flight-skill` puts the entry in the cockpit Skill Bar, bound to `h`. Toggling it writes the per-drone config key `active`; the bar reads the live state from the `hello.state` event topic. **2. tabs: the node-detail tab** `ui.slot.node-detail-tab` mounts the GCS bundle as a tab on the drone's detail panel. The bundle renders the agent's read-back. **3. parameters: the native form** Mission Control renders these controls itself; the bundle does not draw them. `binding: plugin.config` writes the value to the plugin's per-drone config, which the agent half reads live. The `detector` parameter binds to `engine.detector`, so picking a model switches the drone's shared vision detector. The template also carries a commented-out `models` block with per-board variants. Enable it only once `source` points at a real artifact and `sha256` is that file's digest; see [Contribution points](/developers/contribution-points#models). ## 3. The agent half `agent/plugin.py` defines a plain class with the lifecycle hooks the runner calls. It reads its per-drone config live on every cycle and publishes the read-back the Skill Bar and the tab consume: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from typing import Any STATE_TOPIC = "hello.state" class HelloPlugin: def __init__(self) -> None: self._ctx: Any = None self._task: asyncio.Task[None] | None = None async def on_start(self, ctx: Any) -> None: self._ctx = ctx ctx.log.info("hello_plugin_started") self._task = asyncio.create_task(self._loop()) async def on_stop(self, ctx: Any) -> None: if self._task is not None: self._task.cancel() self._task = None async def _loop(self) -> None: while True: active = bool(await self._ctx.config_kv.get("active", False)) rate_hz = float(await self._ctx.config_kv.get("rate_hz", 5) or 5) await self._ctx.events.publish(STATE_TOPIC, {"active": active}) await asyncio.sleep(1.0 / max(rate_hz, 1.0)) ``` `activation.via: config` means the Skill toggle is a config write the host routes to the agent; the plugin sees it on its next `ctx.config_kv.get`. `ctx.config` is the static config loaded at start; use `ctx.config_kv` for values that change while the plugin runs. See the [Python SDK](/developers/sdk-python) for the full context. ## 4. Follow a clicked target To make the plugin follow a person the operator clicks in the cockpit video, the agent half subscribes to detections and the GCS half declares a target action. Add `vision.detection.subscribe` to `agent.permissions`, then subscribe in `on_start`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx: Any) -> None: self._ctx = ctx await ctx.events.publish(STATE_TOPIC, {"active": False}) await ctx.vision.subscribe_detections(self._on_batch) self._task = asyncio.create_task(self._loop()) async def on_configure(self, ctx: Any, config: dict) -> None: # Called once, before on_start, with the static config. ctx.log.info("hello_configured", keys=sorted(config)) async def _on_batch(self, batch: Any) -> None: if not bool(await self._ctx.config_kv.get("active", False)): return # Steer toward the tracked subject here. ``` Then add a `target_actions` block under `gcs.contributes`: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} target_actions: - id: follow label: "Follow this target" icon: crosshair order: 20 applies_to_class: person designate: true config_key: active config_value: true default_key: "f" - id: stop-follow label: "Stop following" icon: circle-stop order: 21 applies_to_class: person designate: false config_key: active config_value: false default_key: "x" ``` When the operator clicks a person and picks **Follow this target**, Mission Control designates that box to the drone's vision tracker and writes `active: true` to the plugin's config. The action inherits the confirm and arm gates of any skill that writes the same `config_key`. Mission Control performs both steps, so a target action needs no extra GCS permission. A GCS half that designates from its own UI instead calls `ctx.command.send("vision.designate", { camera_id, bbox: { x, y, width, height } })`. That needs `vision.track.designate` under `gcs.permissions`; `command.send` alone does not allow designation, and the operator confirms every designation. > [!WARNING] > > A plugin that steers the vehicle needs flight capabilities on its agent > half (`mavlink.write`, `flight.guided_setpoint`) and a `risk` of at least > `high`. Read [Safety](/operations/safety) and test on a simulator before > any flight. ## 5. Test From the plugin folder, the template's `test` script runs both halves: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd extensions/track-follow pnpm test ``` That runs `vitest` in `gcs/` and then `uv run pytest` in `agent/`. ## 6. Pack, sign and install From the monorepo root: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} scripts/pack.sh track-follow ADOS_SIGNING_KEY=keys/my-publisher-2026-A.priv.pem \ ADOS_SIGNING_KEY_ID=my-publisher-2026-A \ scripts/sign.sh extensions/track-follow/dist/com.example.track-follow-0.1.0.adosplug ``` `pack.sh` builds the GCS bundle, checks that the declared entrypoints are present, and zips the result. `sign.sh` writes `com.example.track-follow-0.1.0.signed.adosplug`. The drone must trust `my-publisher-2026-A`: enrol its public key as described in [Bench install and signing](/developers/signing-keys#bench-install-and-signing). Open the drone from the fleet, switch to its **Extensions** tab, choose **Install from file** and drop in the `.signed.adosplug`. Approve the permissions and enable the extension. ## Verify each contribution **1. Skill Bar** Open the drone's cockpit. The **Hello** skill is in the Skill Bar, bound to `h`. Press it; the per-drone config key `active` flips. **2. Node-detail tab** Open the drone's detail panel. The **Hello** tab shows the live read-back from the agent half. **3. Parameters** The **Behavior** group shows the rate slider, the greeting dropdown and the detector picker. Edits clamp to the schema bounds. **4. Target action** With a detector running, click a person in the cockpit video. The popup offers **Follow this target**. ## Next steps > [card] [Contribution points](/developers/contribution-points) > > Every contribution kind in detail. > [card] [Parameter schema](/developers/parameter-schema) > > Widgets, bindings and validation. > [card] [Python SDK](/developers/sdk-python) > > The agent-half context. > [card] [Vision plugins](/developers/vision-plugins) > > Detectors, models and the vision engine. # Python SDK Source: https://docs.altnautica.com/developers/sdk-python The ados.sdk reference: the plugin context, driver base classes, vision client and test harness for a Python agent half. A plugin's agent half can be written in Python or Rust. This page covers the Python SDK, `ados.sdk`. The other option is the [`ados-sdk` crate](/developers/sdk-rust); both speak the same length-prefixed msgpack wire and capability-token handshake to the plugin host. Python suits a plugin that leans on the Python ecosystem (inference, scripting, fast hardware bring-up); Rust suits a tight, long-running service. A Python agent half runs in its own systemd unit, started by the plugin runner. Import the author surface from `ados.sdk`, not from internal agent modules. ## Install There is no PyPI package. Develop against a checkout of [`altnautica/ADOSDroneAgent`](https://github.com/altnautica/ADOSDroneAgent) installed in your environment (`pip install -e .` in the checkout) so `import ados.sdk` resolves. On a node, the runner provides the same package. ## What `ados.sdk` exports ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk import ( # Driver base classes (one per hardware kind) CameraDriver, GimbalDriver, LidarDriver, GpsDriver, EscDriver, PayloadActuatorDriver, # Per-kind data types (candidate / capabilities / session / samples) CameraCandidate, CameraCapabilities, CameraSession, FrameBuffer, GimbalCandidate, GimbalCapabilities, GimbalSession, GimbalState, LidarCandidate, LidarCapabilities, LidarSession, LidarFrame, LidarPoint, GpsCandidate, GpsCapabilities, GpsSession, GpsFix, EscCandidate, EscCapabilities, EscSession, EscTelemetry, PayloadCandidate, PayloadCapabilities, PayloadSession, PayloadCommand, PayloadState, # Driver errors DriverError, DriverDeviceNotFound, DriverPermissionDenied, # Vision-engine client and types VisionClient, Frame, FrameDescriptor, FrameFormat, RingLayout, Detection, DetectionBatch, BoundingBox, ModelKind, ModelExecution, ModelMetadata, Pose, Odometry, # Camera selection helpers CAMERA_SELECTOR_AUTO, CAMERA_SELECTOR_BINDING, CAMERA_SELECTOR_CONTROL, primary_camera_id, resolve_camera_selection, # Perception offload gates FreshnessGate, GateState, LockGate, LockState, ExecutionTier, ResolvedTier, # Target lock tracking LockedTargetTracker, LockedTarget, EffectiveLock, LOCK_LOCKED, LOCK_UNCERTAIN, LOCK_LOST, DEFAULT_COAST_WINDOW_S, # Testing PluginTestHarness, FakeVisionEngine, load_fixture, ) ``` * **Driver layer.** The base classes hardware-driver plugins subclass, plus the dataclasses they exchange with the host. See the [driver layer](/developers/driver-layer). * **Vision.** `VisionClient` and the frame, detection and model types a plugin uses to read frames and publish detections. * **Camera selection.** Helpers that resolve a camera parameter (a camera id or `auto`) to the camera the plugin should use. * **Offload gates and lock tracking.** The freshness and lock gates and `LockedTargetTracker` that a behavior plugin uses to act only on a fresh, locked target. * **Testing.** `PluginTestHarness`, `FakeVisionEngine` and `load_fixture` exercise a plugin in-process with no agent. `ados.sdk` does not export a context class. The runner hands `ctx` to your hooks at call time; a plugin that wants static typing declares a local `Protocol` for the parts of `ctx` it uses, as the reference extensions do. ## The agent-half plugin shape An agent half is a plain Python class with no base class. The manifest's `agent.entrypoint` points the runner at it: * `module:Class`, for code packaged as an importable module (`follow_me:FollowMePlugin`). * A path inside the archive (`agent/plugin.py`), in which case the class must be named `Plugin`. The runner constructs the class with no arguments, then calls the hooks it finds. Every hook is optional and may be sync or async: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} class Plugin: async def on_start(self, ctx): # Open subscriptions, start work. ... async def on_stop(self, ctx): # Release anything on_start acquired. ... ``` The hook order is `on_install`, `on_enable`, `on_configure(ctx, config)`, `on_start`, then the runner waits for shutdown, then `on_stop` and `on_disable`. See [Lifecycle](/developers/lifecycle) for when each runs. ## The plugin context Every facade call is gated on a capability; a call whose capability was not granted is rejected with `capability_denied: `. | Member | What it does | Capability | | - | - | - | | `ctx.plugin_id`, `ctx.plugin_version`, `ctx.agent_id` | Identity; `agent_id` is the bound drone for a per-drone plugin. | none | | `ctx.data_dir`, `ctx.config_dir`, `ctx.temp_dir` | The plugin's writable directories. | none | | `ctx.config` | The static config dict loaded at start. | none | | `ctx.config_kv` | Live config: `await get(key, default)`, `await set(key, value, scope)`, `static(key)`. | none | | `ctx.log` | Structured logger. | none | | `ctx.events` | `publish(topic, payload)` and `subscribe(pattern, callback)` on the agent event bus. | `event.publish`, `event.subscribe` | | `ctx.mavlink` | `subscribe`, `send` and `register_component`. | `mavlink.read`, `mavlink.write`, `mavlink.component.*` | | `ctx.msp` | The raw MSP byte plane to a Betaflight, iNav or KISS flight controller: `send`, `subscribe`. | `msp.write`, `msp.read` | | `ctx.flight` | `guided_setpoint(...)` and `rate_setpoint(...)`, scoped setpoint senders. | `flight.guided_setpoint`, `flight.rate_setpoint` | | `ctx.vision` | The `VisionClient`: frames, models, inference, `subscribe_detections`, `designate_track`, detection publishing. | `vision.*` | | `ctx.camera` | `claim(device_path, exclusive)`, `release`, and `get_frame` for the latest frame from a claimed camera. | The camera hardware capabilities | | `ctx.video` | `set_source(cameras)`: declare the video pipeline's stream sources. | `video.source.set` | | `ctx.buttons` | Front-panel button press events. | `button.subscribe` | | `ctx.telemetry` | `extend(channel, payload)`: add fields to the telemetry sent to the GCS. To read vehicle state, use `subscribe_telemetry()` on the IPC client (`PluginIpcClient`), gated on `telemetry.read`. | `telemetry.extend` | | `ctx.peripheral_manager` | `claim_camera` and the `register_*_driver(...)` calls (the agent does not route drivers; see the [driver layer](/developers/driver-layer)). | `sensor.*.register` | | `ctx.process` | `spawn(...)` from the manifest's `subprocess_spawn` allowlist. | `process.spawn` | | `ctx.lifecycle` | `on_pause` and `on_resume` callbacks, fired when the operator switches away from and back to the drone hosting the plugin's UI. | `event.subscribe` | | `ctx.tools` | Register MCP tool handlers with `register(name, handler)` or the `@ctx.tools.tool()` decorator. | `mcp.expose` | ### A real skeleton This is the Follow-Me reference plugin, trimmed to its lifecycle shape. Each subscription matches a manifest permission (`mavlink.read`, `event.subscribe`, `vision.detection.subscribe`). ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import asyncio from typing import Any class FollowMePlugin: def __init__(self) -> None: self._ctx: Any = None self._loop_task: asyncio.Task | None = None async def on_start(self, ctx: Any) -> None: self._ctx = ctx await ctx.mavlink.subscribe("ATTITUDE", self._on_attitude) await ctx.mavlink.subscribe("GLOBAL_POSITION_INT", self._on_global_position) await ctx.vision.subscribe_detections(self._on_batch) self._loop_task = asyncio.create_task(self._follow_loop()) ctx.log.info("follow_me_started") async def on_stop(self, ctx: Any) -> None: if self._loop_task is not None: self._loop_task.cancel() ctx.log.info("follow_me_stopped") ``` The complete plugin lives in [`altnautica/ADOSExtensions`](https://github.com/altnautica/ADOSExtensions) under `extensions/follow-me/`. ## IPC The unit passes the Unix socket path in `ADOS_PLUGIN_SOCKET` and the node profile in `ADOS_NODE_PROFILE`. The token, the bound agent id and the data dir arrive in a systemd credential at `$CREDENTIALS_DIRECTORY/ados-plugin-token`, never in the environment; the runner reads it for you. If the socket or the credential is not there yet, the runner keeps retrying until the plugin host accepts the connection. It then speaks msgpack RPC: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} plugin -> {"id": "...", "type": "request", "method": "event.publish", "args": {...}} host -> {"id": "...", "type": "response", "args": {...}} host -> {"id": "...", "type": "event", "method": "...", "args": {...}} ``` Every privileged method is checked against the granted capability set before it reaches a handler. ## Resource limits The plugin host enforces the manifest's resource block: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: resources: max_ram_mb: 96 # default 96, range 8 to 4096 max_cpu_percent: 25 # default 25, range 1 to 100 max_pids: 12 # default 12, range 1 to 256 ``` On Linux these become `MemoryMax`, `CPUQuota` and `TasksMax` on the plugin's unit in `ados-plugins.slice`. An OOM kill ends the process and systemd restarts it after 2 s, with no start limit. ## Testing `PluginTestHarness` wires a real plugin context to fake host stubs, so a `pytest` run drives your hooks with no agent and no hardware: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import pytest from ados.sdk import PluginTestHarness from plugin import Plugin @pytest.mark.asyncio async def test_plugin_publishes_on_low_battery(): async with PluginTestHarness( plugin_id="com.example.hello", granted_capabilities={"event.publish", "event.subscribe"}, ) as harness: plugin = Plugin() await plugin.on_start(harness.context) await harness.publish_event("battery.status", {"remaining_percent": 18}) events = harness.published_events() assert any(topic == "battery.low" for topic, _ in events) ``` The harness: * exposes `harness.context`, the context to pass to your hooks; * delivers events with `await harness.publish_event(topic, payload)` and captures the plugin's output with `harness.published_events()`, a list of `(topic, payload)` tuples; * replays recorded scenarios with `await harness.replay_fixture(name_or_path)` (load files with `load_fixture`); * grants and revokes capabilities with `harness.grant(...)` and `harness.revoke(...)`. `FakeVisionEngine` stands in for the vision engine and pushes synthetic frames into a `VisionClient`. `ados plugin test ` runs a plugin's pytest suite with the manifest validated first; see the [Plugin CLI reference](/developers/cli-reference). ## Where the rest of the contract lives * `src/ados/plugins/manifest.py`: the strict manifest model the CLI's `lint`, `sign` and `test` enforce. * `src/ados/plugins/runner.py`: the process entrypoint that loads a plugin and calls its hooks. * `crates/ados-plugin-host/src/{signing,state,supervisor,archive}.rs`: signature verification and the revocation list, persistent install and grant state, the install and enable lifecycle, and archive unpacking with traversal protection. ## Next steps > [card] [Your first plugin](/developers/your-first-plugin) > > Build, sign and install a plugin end to end. > [card] [Event hooks and bus](/developers/event-hooks-and-bus) > > Topics and the agent event bus. > [card] [Vision plugins](/developers/vision-plugins) > > Frames, models and detections. > [card] [Rust SDK](/developers/sdk-rust) > > The same surface in Rust. # Rust SDK Source: https://docs.altnautica.com/developers/sdk-rust The ados-sdk crate: the Rust agent-half SDK for plugins that run a tight, long-running service on the node. A plugin's agent half can be written in Python or Rust. This page covers the Rust SDK, the `ados-sdk` crate. The other option is [`ados.sdk`](/developers/sdk-python); both speak the same length-prefixed msgpack wire and capability-token handshake to the plugin host. The wire lives in `ados-protocol` and is reused unchanged on both sides. The crate mirrors the Python surface: the IPC client, the plugin context, the six driver traits, the vision client, a test harness, and the agent capability catalog re-exported from `ados-protocol`. ## When to pick Rust Python suits a plugin that leans on the Python ecosystem. Reach for Rust when: * **The plugin is a tight, long-running service.** A Rust binary has no interpreter to start and a small idle footprint. * **You ship a vendor binary.** A Rust agent half is one binary at the manifest entrypoint. The host execs it directly under systemd with no Python environment, and `ctx.process` authorizes any extra vendor binary the plugin spawns. * **You want a single artifact.** The pack step cross-compiles the crate and places the binary in the `.adosplug` at the entrypoint path. ## Layout A Rust agent half is its own crate at `agent/` inside the extension directory: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} extensions// manifest.yaml # agent.runtime: rust, agent.entrypoint: bin/ agent/ Cargo.toml # the crate src/main.rs # impl Plugin + run_plugin locales/ ... # optional assets, same as any extension ``` The worked examples are [`extensions/vision-nav`](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/vision-nav) (one binary) and [`extensions/world-engine`](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/world-engine) (several binaries through `bin:` and declared services). ## Depending on the SDK The crate depends on `ados-sdk`, which brings the IPC client, the context, the driver traits and the lifecycle runner. It pulls in `ados-protocol` (the frame, envelope and capability-token wire, including the vision framebus contract) transitively. In the [`altnautica/ADOSExtensions`](https://github.com/altnautica/ADOSExtensions) monorepo, the Rust agent halves form a cargo workspace. The SDK dependency is declared once in the root `Cargo.toml` and a member crate inherits it: ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} # extensions//agent/Cargo.toml [dependencies] ados-sdk = { workspace = true } tokio = { workspace = true } rmpv = { workspace = true } # The Plugin trait uses async methods, so implementing it needs the same # attribute the trait was declared with. async-trait = { workspace = true } ``` The root workspace resolves `ados-sdk` as a path dependency to a sibling checkout of the agent repository: ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} # Cargo.toml (workspace root) [workspace.dependencies] ados-sdk = { path = "../ADOSDroneAgent/crates/ados-sdk" } ados-protocol = { path = "../ADOSDroneAgent/crates/ados-protocol" } ``` > [!NOTE] > > An out-of-tree plugin depends on `ados-sdk` from crates.io. Its version > tracks the agent release it speaks to, so pin the agent's major.minor, > for example `ados-sdk = "0.106"`: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > cargo add ados-sdk > ``` > > First-party extensions in ADOSExtensions keep the sibling path > dependency above; CI checks ADOSDroneAgent out at the commit recorded in > the `ADOS_AGENT_REV` file at the workspace root. See > [Rust crates](/developers/rust-crates) for every published ADOS crate. A vision plugin also names `ados-protocol` directly for the framebus value types the SDK does not re-export (`FrameDescriptor`, `FrameFormat`, `Detection`, `BoundingBox`, `ModelMetadata`). It is the same crate the SDK already pulls in. ## The plugin shape A Rust plugin implements the `Plugin` trait and hands the type to `run_plugin` from `main`. The trait has one required method, `new`; every lifecycle hook defaults to a no-op. ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} use std::collections::BTreeMap; use ados_sdk::{run_plugin, Plugin, RunnerError}; use ados_sdk::context::PluginContext; use ados_sdk::ClientError; use async_trait::async_trait; /// A plugin holds whatever state its hooks share. struct MyPlugin; #[async_trait] impl Plugin for MyPlugin { fn new() -> Self { MyPlugin } /// Open subscriptions and start work. Each call on `ctx` is gated /// on a granted capability. async fn on_start(&mut self, ctx: &PluginContext) -> Result<(), ClientError> { ctx.events .subscribe("vehicle.*", std::sync::Arc::new(|_args| { /* ... */ })) .await?; Ok(()) } /// Release anything on_start acquired. async fn on_stop(&mut self, _ctx: &PluginContext) -> Result<(), ClientError> { Ok(()) } } /// Resolve when the process is asked to stop. The host stops the unit /// with SIGTERM; SIGINT covers a foreground run. async fn shutdown_signal() { use tokio::signal::unix::{signal, SignalKind}; let mut term = signal(SignalKind::terminate()).expect("SIGTERM handler"); let mut int = signal(SignalKind::interrupt()).expect("SIGINT handler"); tokio::select! { _ = term.recv() => {} _ = int.recv() => {} } } #[tokio::main] async fn main() { let static_config: BTreeMap = BTreeMap::new(); match run_plugin::( env!("CARGO_PKG_VERSION"), static_config, shutdown_signal(), ) .await { Ok(()) => {} // Running the binary by hand (no host) lands here: no socket or // token to connect to. Report and exit non-zero rather than panic. Err(RunnerError::NoBridge) => { eprintln!("no plugin host socket/token supplied"); std::process::exit(1); } Err(err) => { eprintln!("{err}"); std::process::exit(1); } } } ``` The entry is a plain generic function, not a proc-macro, so the call site stays explicit. ### The runner `run_plugin` connects the IPC client, builds the `PluginContext` and drives the hooks. It reads `--socket`, `--token` and `--agent-id` from the command line, falling back to the values in the `ados-plugin-token` systemd credential under `$CREDENTIALS_DIRECTORY`, and to the `ADOS_PLUGIN_*` environment only when there is no credential. A lost host session ends the run with an error, so the binary exits non-zero and systemd restarts it with a fresh session. The hook order matches the Python runner: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} on_install -> on_enable -> on_configure(ctx, config) -> on_start -> (wait for shutdown) -> on_stop -> on_disable ``` `run_plugin_with` takes pre-parsed `RunnerArgs`, for a test or harness that supplies arguments without touching the process environment. ## `PluginContext` The object handed to every hook. Each field is a small capability-gated facade over one IPC client; the host enforces the capability before the call reaches a handler. | Field | What it does | Capability | | - | - | - | | `ctx.events` | `publish(topic, payload)` and `subscribe(pattern, cb)` on the event bus | `event.publish` / `event.subscribe` | | `ctx.mavlink` | `send(...)`, `subscribe(msg_name, cb)`, `register_component(id, kind)` | `mavlink.read` / `mavlink.write` / `mavlink.component.*` | | `ctx.msp` | Raw MSP to a Betaflight, iNav or KISS flight controller: `send`, `send_raw_rc`, `send_sticks`, `subscribe` | `msp.read` / `msp.write` | | `ctx.telemetry` | `extend(channel, payload)` to add a channel to the telemetry the GCS reads | `telemetry.extend` | | `ctx.flight` | `guided_setpoint(args)` and `rate_setpoint(args)` | `flight.guided_setpoint` / `flight.rate_setpoint` | | `ctx.peripheral_manager` | `register_*_driver(ref)`, `unregister(handle)`, `claim_camera(...)` | `sensor..register` | | `ctx.camera` | `claim(path, exclusive)`, `release(path)`, `get_frame(...)` | The camera hardware capabilities | | `ctx.vision` | Frame subscription, model registration, inference, detection publishing and subscription, designation, pose injection | `vision.*`, `estimator.pose.inject` | | `ctx.buttons` | Front-panel button presses; quiet on a board with no panel | `button.subscribe` | | `ctx.gpio` | `set(chip, pin, high)` and `beep(...)` | `hardware.gpio_out` | | `ctx.display` | `set_page(...)`: the plugin's page on the onboard display | `display.oled.page` | | `ctx.radio` | `open_aux_stream`, `send_aux`, `subscribe_aux`, `close_aux_stream` | `radio.aux_stream` | | `ctx.cloud` | `publish(stream, payload)` and `put_record(...)` | `cloud.publish` / `cloud.records` | | `ctx.node` | `info()`: the node's profile, board, ground-station role and camera | `node.info.read` | | `ctx.mdns` | `advertise(...)` and `browse(...)` on the local network | `network.listen` / `network.outbound` | | `ctx.config` | `static_get(key)` (static config, sync), `get(key, default)` and `set(key, value, scope)` (live) | none | | `ctx.process` | `spawn(basename, args, env)` to launch an allowlisted vendor binary | `process.spawn` | | `ctx.lifecycle` | `on_pause(cb)` and `on_resume(cb)` for GCS-side mount events | `event.subscribe` | `ctx.peripherals` is an alias for `ctx.peripheral_manager`. `ctx.ping_supervisor()` is a health probe, and `ctx.client()` returns the shared IPC client for a method no facade covers. A subscription callback runs on the IPC reader task, so it must not block. Do cheap work in the callback and move heavy work (an async RPC, inference) to a spawned task. ## Driver traits For a hardware-driver plugin, the SDK ships six object-safe async traits, one per kind, each mirroring the Python base class method for method: `CameraDriver`, `GimbalDriver`, `LidarDriver`, `GpsDriver`, `EscDriver` and `PayloadActuatorDriver`. The Python `AsyncIterator` return becomes a `SampleStream` (a boxed `Stream`), and a `Session` associated type stands in for the Python session object. The agent does not route drivers: a driver plugin opens and runs its own device from its lifecycle hooks. See the [driver layer](/developers/driver-layer). ## Vision `ctx.vision` is the engine facade. Frames never ride the RPC envelope: the engine writes normalized frames into a shared-memory ring and publishes a small descriptor, and the SDK memory-maps the `/dev/shm` ring read-only and reads each slot through the per-slot seqlock the framebus contract defines, dropping any torn or stale read (latest wins). ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} use std::sync::Arc; use ados_sdk::vision::Frame; // In on_start: let vision = ctx.vision.clone(); // a cheap clone shares the one IPC client ctx.vision .subscribe_frames(None, Arc::new(move |frame: Frame| { // frame.descriptor + frame.pixels (resolved from the ring) let vision = vision.clone(); tokio::spawn(async move { // run inference, publish a detection ... }); })) .await?; ``` The vision client also offers `register_model`, `resolved_model`, `infer`, `publish_detection` and `publish_one`, `subscribe_detections`, `designate_track`, `advertise_offload`, and the pose helpers `register_vio_component`, `inject_pose` and `inject_odometry`. The pose helpers build a `VISION_POSITION_ESTIMATE` (from a `Pose`) or an `ODOMETRY` message (from an `Odometry`) and send it under the visual-odometry component id (`VIO_COMPONENT_ID`), so a plugin never hand-builds a MAVLink frame. `Frame`, `Pose`, `Odometry`, `VisionClient` and `VIO_COMPONENT_ID` are re-exported from the crate root; the framebus value types come from `ados-protocol`. The worked vision plugin is [`vision-nav`](https://github.com/altnautica/ADOSExtensions/tree/main/extensions/vision-nav), which reads frames from the frame bus, computes optical flow and sends it to the flight controller. ## Testing The `ados_sdk::testing` module mirrors the Python harness for vision plugins. `FakeVisionEngine` emits synthetic frames into the same `FrameCallback` a plugin registers with `ctx.vision.subscribe_frames`, and captures the detection batches the plugin publishes, with no host, vision engine, shared memory or socket. ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} use ados_sdk::testing::FakeVisionEngine; use ados_protocol::framebus::FrameFormat; let mut engine = FakeVisionEngine::new("uvc-0", 64, 48, FrameFormat::Rgb24); engine.on_frame(|frame| { assert_eq!(frame.descriptor.camera_id, "uvc-0"); }); engine.push_solid(0x80); // one grey frame engine.deliver_all(); ``` `push_frame`, `push_solid` and `push_dir` enqueue frames (the last reads `*.bin` and `*.raw` files in name order); `deliver_one` and `deliver_all` drive them through the resolver; `detection_sink` and `captured_detections` collect what the plugin published. The module's own tests in `crates/ados-sdk/src/testing/` are a worked example. ## Capabilities The SDK re-exports the generated agent capability catalog from `ados-protocol` as `ados_sdk::capabilities`, so a plugin references one source of truth for capability ids. The catalog, its risk levels and which capabilities are enforced are on [Permissions](/developers/permissions). A call whose capability was not granted is rejected before it runs; the SDK surfaces it as `ClientError::CapabilityDenied` naming the missing capability. A vendor-binary spawn the manifest allowlist refuses surfaces as `ClientError::AllowlistViolation`. ## IPC The wire is `ados-protocol` unchanged: length-prefixed msgpack envelope frames over the per-plugin Unix domain socket, gated by an HMAC capability token. The handshake presents the token the host minted; the client then serves requests and responses on one flow (each call gets a fresh `r` request id) and event, MAVLink and vision pushes on the other, dispatched to the matching callbacks. The per-request timeout defaults to five seconds. ## Manifest A Rust agent half sets `runtime: rust` and points the entrypoint at the binary path inside the installed plugin tree: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: runtime: rust entrypoint: "bin/" isolation: subprocess permissions: - id: vision.frame.read - id: vision.detection.publish resources: max_ram_mb: 32 max_cpu_percent: 10 max_pids: 4 ``` `scripts/pack-rust.sh` cross-compiles the crate and places the binary at `agent.entrypoint` in the archive. The host execs that binary directly under systemd, passing the plugin id and `--socket` on the command line; the token, agent id and data dir arrive in the `ados-plugin-token` systemd credential. A plugin that ships binaries for several architectures uses `bin:` with [per-architecture binaries](/developers/manifest#per-architecture-binaries). Signing and install are otherwise identical to a Python plugin; see [Signing keys](/developers/signing-keys). A plugin that bundles a vendor binary sets `contains_vendor_binary: true` and lists each one under `vendor_attribution`; see [Vendor binaries](/developers/vendor-binaries). ## Next steps > [card] [Manifest](/developers/manifest) > > Every field, including `binaries` and `payloads`. > [card] [Agent plugin deep dive](/developers/agent-plugin-deep-dive) > > How the host runs an agent half. > [card] [Vision plugins](/developers/vision-plugins) > > Frames, models and detections. > [card] [Python SDK](/developers/sdk-python) > > The same surface in Python. # TypeScript SDK Source: https://docs.altnautica.com/developers/sdk-typescript The @altnautica/plugin-sdk reference: definePlugin, the typed PluginContext, the RPC client, the test harness and the other exports. `@altnautica/plugin-sdk` (v1.3.0, GPL-3.0-or-later) is the GCS-half SDK: the package a plugin's Mission Control side imports. A plugin's GCS half always uses it; its agent half uses the [Python SDK](/developers/sdk-python) or the [Rust SDK](/developers/sdk-rust). The SDK hides the `postMessage` envelope and gives you a typed `PluginContext`. ## Install The package is not published to npm. Develop your plugin inside the [`altnautica/ADOSExtensions`](https://github.com/altnautica/ADOSExtensions) monorepo as a pnpm workspace member; the scaffolder pins the SDK to `workspace:^` against the in-tree [`packages/plugin-sdk`](https://github.com/altnautica/ADOSExtensions/tree/main/packages/plugin-sdk). [Your first plugin](/developers/your-first-plugin) walks through the clone and scaffold flow. The package ships ESM only, with no runtime dependencies, and four entry points: | Import | What it holds | | - | - | | `@altnautica/plugin-sdk` | `definePlugin`, the context, the client, the parameter helpers and the types. | | `@altnautica/plugin-sdk/harness` | `createPluginHarness`, the synthetic host for unit tests. | | `@altnautica/plugin-sdk/inline` | The types for a first-party `gcs.isolation: inline` module. | | `@altnautica/plugin-sdk/esbuild` | `inlineSharedExternals()`, the esbuild plugin an inline module builds with. | ## `definePlugin` The single entry point: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; definePlugin({ id: "com.example.my-plugin", version: "1.0.0", locale: { "hello.title": "Hello" }, async mount(ctx, info) { // wire up subscriptions, render the panel }, async unmount(ctx, info) { // optional teardown }, }); ``` `mount` is called once the bundle loads. A throw is not reported to the host, so catch errors and render your own error state. `info` is `{ id, version }` from your `definePlugin` call. Before Mission Control destroys the frame it asks the plugin to unmount and waits up to 500 ms; keep `unmount` short and do not rely on it to persist state. See [Lifecycle](/developers/lifecycle#lifecycle-hooks-gcs-half). `definePlugin` returns a `PluginInstance` with `info`, `ctx` and an `unmount()` you can call for your own teardown. ## `PluginContext` The argument the SDK hands to `mount`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} interface PluginContext { client: PluginClient; telemetry: { subscribe(topic: string, handler: (args: T) => void): Promise<() => void>; }; perception: { readTier(): Promise; subscribeDetections(handler: (batch: PerceptionDetectionBatch) => void): Promise<() => void>; readSessionHealth(): Promise; }; command: { send(command: string, args?: unknown): Promise; }; notifications: { publish(payload: NotificationPayload): Promise; }; recording: { mark(payload: RecordingMark): Promise; }; mission: { read(missionId: string): Promise; write(update: MissionUpdate): Promise; }; config: { onChange(handler: (next: T) => void): () => void; }; events: { subscribe(topic: string, handler: (args: T) => void): () => void; listen(topic: string, handler: (args: T) => void): Promise<() => void>; publish(topic: string, payload: unknown): Promise; }; records: PluginRecordsApi; theme: { onChange(handler: (vars: Record) => void): () => void; }; videoOverlay: { onProps(handler: (props: VideoOverlayHostProps) => void): () => void; }; i18n: { t(key: string, params?: Record): string; }; } ``` `command.send` and `mission.write` wait for the operator's decision rather than a fixed deadline. A denial, a command the host does not allow, or a rate limit rejects with a `HostError` whose code is `refused`. `events.subscribe` reads one-way host pushes (an agent plugin's state read-back, for example) and needs no grant. `events.listen` and `events.publish` use the GCS plugin bus between installed plugin panels and need `event.subscribe` and `event.publish`. ### Video overlay host props A frame mounted in the `video.overlay` slot reads its host props with `ctx.videoOverlay.onProps`. The host pushes them on load and on every material change (a detection batch lands or ages out, the video resizes or changes resolution, the camera switches), never per video frame. A payload that is not an object with a rendered rect is dropped. The call returns an unsubscribe function. Mission Control and the agent cockpit push the same shape, so one overlay bundle draws the same on both hosts. ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} interface VideoOverlayHostProps { droneId: string; cameraId: string; // the camera the video shows streamWidth: number; // the stream's intrinsic resolution streamHeight: number; renderedRect: { left: number; top: number; width: number; height: number }; frameTimestampMs: number; // host-clock ms of the batch shown; 0 with none frameAgeMs: number | null; // null when the host has no estimate attitude: { rollDeg: number; pitchDeg: number; yawDeg: number } | null; attitudeAtFrameTime: boolean; // attitude sampled at the frame's capture time detections: { frameWidth: number; frameHeight: number; frameId: number; receivedAt: number; items: { bbox: { x: number; y: number; width: number; height: number }; classLabel: string; confidence: number; trackId: number | null; lockState: "locked" | "uncertain" | "lost" | null; }[]; } | null; // null once the batch is stale: drop your boxes } const unsubscribe = ctx.videoOverlay.onProps((p) => { const sx = p.renderedRect.width / p.streamWidth; const sy = p.renderedRect.height / p.streamHeight; draw(p, sx, sy); }); ``` Draw inside `renderedRect`, which is the letterboxed video area, not the whole frame. `attitude` is `null` when the telemetry is unknown or stale: raise your own failure state rather than assuming level flight. `frameAgeMs` is `null` where the host has no frame-age estimate (the agent cockpit has none), and then `attitudeAtFrameTime` is `false`. `records` reads and writes the plugin's own cloud collection: `list(opts)`, `get(collection, key)`, `put(collection, key, data)` and `remove(collection, key)`. `definePlugin` builds the context for you. To build one by hand (in a test, for example), use `createPluginContext`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { createPluginContext } from "@altnautica/plugin-sdk"; const ctx = createPluginContext({ locale: { "hello.title": "Hello" } }); await ctx.telemetry.subscribe("battery", (s) => store.ingest(s)); ``` ### Wrappers and the bridge methods they call Each wrapper delegates to one `PluginClient` call. The wire methods and their capabilities are on [GCS bridge methods](/developers/event-hooks). | Wrapper | Bridge method | Capability | | - | - | - | | `ctx.telemetry.subscribe(topic, h)` | `telemetry.subscribe` | `telemetry.subscribe.` | | `ctx.perception.readTier()` | `perception.read` | `perception.read` | | `ctx.perception.subscribeDetections(h)` | `perception.subscribe` | `perception.subscribe` | | `ctx.perception.readSessionHealth()` | `perception.health` | `perception.read` | | `ctx.command.send(command, args)` | `command.send` | `command.send`, or `vision.track.designate` for `vision.designate` | | `ctx.notifications.publish(payload)` | `notification.publish` | `ui.slot.notification-channel` | | `ctx.recording.mark(payload)` | `recording.mark` | `recording.write` | | `ctx.mission.read(id)` | `mission.read` | `mission.read` | | `ctx.mission.write(update)` | `mission.write` | `mission.write` | | `ctx.events.listen(topic, h)` | `events.subscribe` | `event.subscribe` | | `ctx.events.publish(topic, payload)` | `events.publish` | `event.publish` | | `ctx.records.list/get/put/remove` | `records.list/get/put/remove` | `cloud.records` | | `ctx.config.onChange(h)` | host-pushed `config.changed` | none | | `ctx.theme.onChange(h)` | host-pushed `theme.changed` | none | | `ctx.videoOverlay.onProps(h)` | host-pushed `video.overlay.props` | `ui.slot.video-overlay` | For any other method, call `ctx.client.request(method, capability, args)`. ## `PluginClient` The lower-level RPC client: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { PluginClient } from "@altnautica/plugin-sdk"; const client = new PluginClient(); const result = await client.request<{ ok: boolean }>( "telemetry.subscribe", "telemetry.subscribe.battery", { topic: "battery" }, { timeoutMs: 3000 }, ); ``` * `request(method, capability, args, options?)`: send a request and await the response. Default timeout 5 s. * `on(method, handler)`: subscribe to host-pushed events. * `subscribeTelemetry(topic, handler)`: does both the subscribe request and the `telemetry.` listener. * `dispose()`: tear down listeners and reject in-flight requests. The client caches the capability token Mission Control pushes on the `capability.token` event (`CAPABILITY_TOKEN_EVENT`), so token rotation needs no plugin code. A request the host refuses with `capability_denied:token_missing` is held and sent again once the first token arrives. The `capability` argument is typed with the `CapabilityId` union of every known id. ## `HostError` Thrown when the host returns an error envelope: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { HostError } from "@altnautica/plugin-sdk"; try { await ctx.command.send("land"); } catch (err) { if (err instanceof HostError && err.code === "permission_denied") { // show a banner } else { throw err; } } ``` Branch on `code`; the `message` is for humans. The codes are listed on [GCS bridge methods](/developers/event-hooks#error-envelopes). ## Other exports * `contributesModel`: an identity helper that types a `contributes` literal (editor autocomplete and a compile-time shape check) and returns it unchanged, for manifest fixtures and codegen. * `validateValue`, `clampValue`, `inferWidget`, `resolveBinding`, `defaultFor`, `PARAMETER_WIDGETS`, `PARAMETER_BINDINGS`: the parameter schema helpers. See [Parameter schema](/developers/parameter-schema). * `createWindowTransport`, `MemoryTransport`: the transports under `PluginClient`. * `PROTOCOL_VERSION`, `TELEMETRY_TOPICS` and the envelope, telemetry, perception, records and contribution types. ## Test harness ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { createPluginHarness } from "@altnautica/plugin-sdk/harness"; const harness = createPluginHarness({ grantedCapabilities: ["telemetry.subscribe.battery"], mount: async (ctx) => { await ctx.telemetry.subscribe("battery", (s) => store.ingest(s)); }, }); await harness.start(); harness.pushTelemetry("battery", mockSample); expect(harness.calls.map((c) => c.method)).toContain("telemetry.subscribe"); await harness.teardown(); ``` The harness: * mounts the plugin against an in-memory transport (no real iframe); * records every request in `harness.calls`, with `harness.notifications` and `harness.recordingMarks` as shortcuts; * pushes host traffic with `pushTelemetry`, `pushEvent`, `pushConfig`, `pushTheme` and `pushPerceptionDetection`, and stubs reads with `stubPerceptionTier` and `stubPerceptionHealth`; * simulates host failures with `failNext(method, code, message)`; * gates calls by capability like the bridge: a telemetry subscription needs its topic grant (`telemetry.subscribe.`), and a `ui.slot.*` RPC needs that slot's capability. ## Building the bundle The SDK has no build step of its own. The `create-ados-plugin` templates use esbuild: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} esbuild src/plugin.ts --bundle --format=esm --target=es2022 --outfile=plugin.bundle.js --minify ``` Run from `gcs/`, the output is `gcs/plugin.bundle.js`, the path the manifest's `gcs.entrypoint` names. The bundle is not hashed in the manifest; the archive signature covers it. ## Next steps > [card] [Your first plugin](/developers/your-first-plugin) > > Build, test, sign and install a GCS-only tab. > [card] [GCS bridge methods](/developers/event-hooks) > > The wire methods, pushed events and error codes. # Plugin security model Source: https://docs.altnautica.com/developers/security-model What a plugin can and cannot do, the blast radius of each sandbox, and the trust boundary between first-party and third-party signers. A plugin runs third-party code next to a flying vehicle. Every plugin is sandboxed, every privileged call is gated by a capability the operator granted, and every archive is signed and checked before a file lands on disk. This page is the threat-model summary: what each half can reach, what it cannot, and the worst case if a plugin turns out to be malicious or buggy. The mechanics live in [Concepts](/developers/concepts), [Permissions](/developers/permissions), the [agent plugin deep dive](/developers/agent-plugin-deep-dive) and the [GCS plugin deep dive](/developers/gcs-plugin-deep-dive). ## The two sandboxes at a glance | | Agent half | GCS half | | - | - | - | | Where it runs | The drone or ground station node, as its own systemd unit | The Mission Control browser, in an iframe | | Language | Python (`ados.sdk`) or Rust (`ados-sdk`) | TypeScript (`@altnautica/plugin-sdk`) | | Isolation primitive | Per-plugin system user, hardened unit, `ados-plugins.slice` cgroup | ` ``` The frame document carries a CSP with `connect-src 'none'`, and a guard script removes WebRTC and nested frames, so the iframe has no network egress at all. | The plugin CAN | The plugin CANNOT | | - | - | | Run JavaScript and render its own UI in the iframe | Read host cookies, `localStorage` or the host DOM (no `allow-same-origin`, so it runs in a null origin) | | Call the host over `postMessage` for capabilities it was granted | Fetch from any network origin, open a WebSocket or a WebRTC connection | | Mount into a UI slot it holds the matching `ui.slot.*` grant for | Redirect the parent window (no `allow-top-navigation`) | | Receive theme variables and apply them to its own root | Open new windows or submit forms (no `allow-popups`, no `allow-forms`) | | | Get past a missing grant (the host re-resolves the required capability and ignores the one the envelope claims) | ### Blast radius if the GCS half is malicious A compromised GCS half is trapped in a null-origin iframe that cannot read the host session, cannot reach any network, and cannot navigate the parent page. Its only output is `postMessage` envelopes, and the bridge checks the capability each one actually needs. The damage ceiling is the set of GCS capabilities the operator granted (for example `command.send` to its drone, or `mission.write` to edit a plan). Route any network I/O through the agent half. ## Capability least privilege Declare the smallest permission set that makes your plugin work, mark only the load-bearing ones `required: true`, and leave the rest optional so an operator can run a reduced version. The catalog, the risk levels and which capabilities are enforced where are on [Permissions](/developers/permissions); tokens are described in [Concepts](/developers/concepts#capability-tokens). ## The trust boundary: first-party and third-party signers Every `.adosplug` is an Ed25519-signed zip, verified before anything is unpacked. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} /etc/ados/plugin-keys/.pem # enrolled third-party public keys /etc/ados/plugin-revocations.json # revoked signer ids and archive digests ``` | Tier | How it is recognized | What it unlocks | | - | - | - | | First-party | Signer `altnautica-2026-A` or `altnautica-2026-B`, verified against the key pinned in the agent | `gcs.isolation: inline`, `agent.resources.class: heavy`, and installing an agent half on a host whose service manager has no sandbox (macOS) | | Trusted third-party | Signature verifies against a key enrolled under `/etc/ados/plugin-keys/`, signer not revoked | Normal install with `subprocess` and `iframe` isolation | | Unsigned | No signature, or one that does not verify against an enrolled key | Refused, unless the agent runs with `ADOS_PLUGIN_REQUIRE_SIGNED=0`; then it installs with no signer, shown as **UNSIGNED**, and never gets first-party status | A revoked signer or a revoked archive digest is refused in every mode, including with signature enforcement relaxed. First-party status is granted only to the ids on the in-code allowlist, and only when the archive's signature verifies against the key pinned in the agent for that id. A key file planted under a first-party name in `/etc/ados/plugin-keys/` verifies only as a third party. Write access to `/etc/ados/plugin-keys/` is still root-equivalent trust for third-party code: whoever can add a key file can make the node accept archives that key signs, so protect that directory like root. > [!WARNING] > > `isolation: inprocess` (agent) parses but is refused at install for > every plugin, first-party included. `gcs.isolation: inline` runs the GCS > half in Mission Control's own page, outside the iframe sandbox, so it is > first-party only. A third-party archive that declares it is refused at > install. Signature enforcement can only be relaxed on the agent itself, for a bench node. The procedure and its limits are in [Bench install and signing](/developers/signing-keys#bench-install-and-signing). ## The operator install gate No plugin installs silently. The install is two-stage: the host parses the archive in memory, verifies the signature and returns a summary (the requested permissions, the signer and the risk); only after the operator approves does it unpack, generate the unit and write the install record. A plugin that never gets past review leaves no trace. The dialog is described in [Permissions](/developers/permissions#two-stage-install). Auto-update does not apply a version that asks for new permissions; the node reports `update_available` with the new permissions, and the operator reinstalls to approve them. An operator can revoke any granted capability at any time from Mission Control or with `ados plugin perms --revoke `; the host re-mints the plugin's token at once without it. ## Why each layer exists The layers are independent. If one fails, the next still holds. * **Signing** stops a tampered or unknown-origin archive from installing. It is the supply-chain wall. * **The sandbox** (hardened unit plus cgroup, or null-origin iframe plus CSP) bounds a plugin that installed but turns out to be buggy or hostile. It is the runtime wall. * **Capabilities** make the plugin's reach explicit and operator-approved. They are the authority wall. * **The install gate** keeps a person in the loop for every grant. ## Next steps > [card] [Permissions](/developers/permissions) > > The full capability catalog with risk levels. > [card] [Signing keys](/developers/signing-keys) > > Generate, enrol and rotate a publisher key. > [card] [Revocation and incidents](/developers/revocation-and-incidents) > > Pull a signer, an archive or a release from the field. > [card] [Agent plugin deep dive](/developers/agent-plugin-deep-dive) > > How the plugin host runs an agent half. # Self-hosting: the agent Source: https://docs.altnautica.com/developers/self-hosting/agent Install the ADOS Drone Agent and point it at your own Convex backend and MQTT broker instead of the managed cloud. The ADOS Drone Agent runs on the companion computer of a drone or ground station. A fresh install is **local**: it talks to Mission Control directly over the LAN and never reaches out to a backend. Self-hosting changes one thing. You point the agent at your own Convex deployment and MQTT broker, so a Mission Control on any network can find and command the drone through your relay. This page assumes your Convex backend and broker are already up. See [Mission Control and Convex](/developers/self-hosting/mission-control-and-convex) and [Self-hosting: MQTT broker](/developers/self-hosting/mqtt-bridge). ## Install the agent ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -sSL https://raw.githubusercontent.com/altnautica/ADOSDroneAgent/main/scripts/install.sh | sudo bash ``` The installer detects the board, applies board-specific overrides and brings up the services. No follow-up commands are needed for a working local agent. Every installer flag, including `--pair`, is listed on [Drone Agent installation](/drone-agent/installation). > [!NOTE] > > Pairing by code only reaches your backend once the agent knows where that > backend lives. Set the server mode first (next section), or pair over the LAN > from the Add-a-Node card in Mission Control, which needs no backend at all. ## Switch the agent to self-hosted mode The agent reads `/etc/ados/config.yaml`. Set `server.mode` to `self_hosted`, fill in `server.self_hosted`, and set `pairing.convex_url` to the same site origin. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} server: mode: "self_hosted" # cloud | self_hosted | local mqtt_transport: "websockets" # or tcp (MQTT over TLS on mqtt_port) self_hosted: url: "https://convex.example.com:3211" mqtt_broker: "mqtt.example.com" mqtt_port: 8883 pairing: convex_url: "https://convex.example.com:3211" ``` `pairing.convex_url` wins. In `self_hosted` mode the relay falls back to `server.self_hosted.url` when `pairing.convex_url` is empty. Set both so every component agrees on one origin. Only `cloud` and `self_hosted` turn the relay on. `local`, a missing value or a misspelt mode all keep the agent local and silent. ### Server keys | Key | Type | Default | Allowed | Description | | - | - | - | - | - | | `server.cloud.mqtt_broker` | string | `"mqtt.altnautica.com"` | n/a | Mqtt Broker | | `server.cloud.mqtt_port` | integer | `443` | 0 to 65535 | Mqtt Port | | `server.cloud.url` | string | `"https://convex-site.altnautica.com"` | n/a | Url | | `server.cloud_logs_enabled` | boolean | `false` | n/a | Cloud Logs Enabled | | `server.mode` | string | `"local"` | `"cloud"`, `"self_hosted"`, `"local"` | Mode | | `server.mqtt_transport` | string | `"websockets"` | n/a | Mqtt Transport | | `server.self_hosted.api_key` | string | Secret, not shown | n/a | Api Key | | `server.self_hosted.mqtt_broker` | string | `""` | n/a | Mqtt Broker | | `server.self_hosted.mqtt_port` | integer | `8883` | 0 to 65535 | Mqtt Port | | `server.self_hosted.url` | string | `""` | n/a | Url | ### Pairing keys | Key | Type | Default | Allowed | Description | | - | - | - | - | - | | `pairing.beacon_enabled` | boolean | `true` | n/a | Beacon Enabled | | `pairing.beacon_interval` | integer | `30` | 0 to 4294967295 | Beacon Interval | | `pairing.convex_url` | string | `""` | n/a | Convex Url | | `pairing.heartbeat_interval` | integer | `60` | 0 to 4294967295 | Heartbeat Interval | | `pairing.state_path` | string | `"/etc/ados/pairing.json"` | n/a | State Path | ### The :3210 and :3211 origins A self-hosted Convex deployment serves two origins on the same host: | Port | Origin | Serves | | - | - | - | | `3210` | Client API | Browser client functions. `NEXT_PUBLIC_CONVEX_URL` for Mission Control points here. | | `3211` | Site (HTTP actions) | The agent's `/pairing/register`, `/agent/status` heartbeat and `/agent/commands` poll. | The agent talks to the **site origin on `:3211`**. > [!WARNING] > > Point the agent at `:3211`, not `:3210`. A `:3210` URL sends the register and > heartbeat calls to the wrong origin, where they return 404. The setup and > pairing writers rewrite a pasted `:3210` URL to `:3211`, but a hand edit of > `config.yaml` is used as written. ## How the agent reaches the broker The agent always dials the broker over TLS. There is no plaintext path. * With the default `server.mqtt_transport: websockets`, it connects to `wss://:/mqtt`. A `mqtt_port` of `8883` is rewritten to `443`, so put a TLS-terminating proxy or tunnel on 443 that forwards `/mqtt` to Mosquitto's WebSocket listener on 9001. * With `server.mqtt_transport: tcp`, it speaks MQTT over TLS on `mqtt_port`. Add a TLS listener to Mosquitto (for example 8883 with `certfile` and `keyfile`) and set `mqtt_port` to it. Every relay connection authenticates as `ados-` with the pairing key as the password, which is the same key the agent sends as `X-ADOS-Key`. There are no separate MQTT username, password or plaintext settings. The broker carries the MAVLink and MSP byte planes, WebRTC signaling, vision detections and plugin streams. Fleet status goes to Convex separately, as an HTTPS POST to `/agent/status` every 5 seconds. The topic list is on [Cloud infrastructure](/architecture/cloud-infrastructure). ## Apply the change After editing `/etc/ados/config.yaml`, restart the supervisor so the new server mode takes effect: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sudo systemctl restart ados-supervisor ``` Confirm the agent picked up the mode and is reaching your backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados status ``` If the agent does not appear, check `journalctl -u ados-cloud -o json` (or `ados logs query` if you enabled the logging store). A register or heartbeat call that lands on the wrong origin logs the URL it tried. ## Server modes | Mode | Behaviour | | - | - | | `local` | The default on a fresh install. No backend. Mission Control reaches the agent directly over the LAN, hotspot or USB tether. | | `self_hosted` | Uses your own Convex deployment and MQTT broker. This page. | | `cloud` | Uses the managed backend. | > [!NOTE] > > Local mode is not a misconfiguration. On a single LAN bench or field setup you > do not need self-hosting. Self-hosting is for cross-network access, where the > agent and the GCS need a relay in between. For the video path, see [Self-hosting: video relay](/developers/self-hosting/video-relay). Every port in the stack is on [Self-hosting: ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports). ## Next steps > [card] [MQTT broker](/developers/self-hosting/mqtt-bridge) > > Stand up Mosquitto with per-device auth and the TLS front the agent dials. > [card] [Video relay](/developers/self-hosting/video-relay) > > Play the drone's stream in a browser through your own relay. # Self-hosting: all-in-one stack Source: https://docs.altnautica.com/developers/self-hosting/all-in-one Bring up the Convex backend, the web GCS, the Mosquitto broker and the video relay on one host with a single Docker Compose file. One Docker Compose file at `tools/selfhost/` in [ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl) (GPL-3.0) brings up the whole cloud relay on a single host: a self-hosted Convex backend and its dashboard, the Mission Control web GCS, the Mosquitto broker with its auth sync, and the video relay. The [`ados-deploy` tool](/developers/self-hosting/deploy-tool) runs every step on this page for you; follow this page when you want to run them by hand or change the stack. > [!NOTE] > > You do not need any of this to fly on the LAN. Served over plain HTTP, Mission > Control connects straight to the agent and pairs over the local network with no > backend. The cloud relay is the opt-in path for reaching a drone across > networks. ## Services The compose project directory is `selfhost`, so Compose names the containers `selfhost--1`. Published host ports are listed once, in the [port table](/developers/self-hosting/troubleshooting-and-ports#ports). | Service | Image or build | Role | | - | - | - | | `convex-backend` | `ghcr.io/get-convex/convex-backend` | Auth, fleet data and the cloud command queue. Serves the client API and the site (HTTP actions) origin. | | `convex-dashboard` | `ghcr.io/get-convex/convex-dashboard` | Admin dashboard UI for the backend. | | `mission-control` | built from the repo root `Dockerfile` | The web GCS. | | `mosquitto` | `eclipse-mosquitto:2` | MQTT broker on TCP and WebSocket listeners, with password file and ACL. | | `mqtt-auth-sync` | built from `tools/mqtt-bridge/deploy/auth-sync.Dockerfile` | Every 30 seconds rewrites the broker's `passwd` and `acl.conf` from Convex and reloads Mosquitto. No published port. | | `video-relay` | built from `tools/video-relay` | RTSP to fragmented MP4 over WebSocket for browser video. | `mqtt-auth-sync` shares the broker's PID namespace so it can send Mosquitto a `SIGHUP` after each rewrite. No Docker socket is mounted. The broker itself is covered on [Self-hosting: MQTT broker](/developers/self-hosting/mqtt-bridge). ## The two Convex origins A self-hosted Convex backend exposes two origins, and they are not interchangeable: * The **client API** origin (`:3210`) is what the GCS browser bundle talks to (`NEXT_PUBLIC_CONVEX_URL`). `npx convex deploy` and `npx convex env set` also target it. * The **site** origin (`:3211`) serves HTTP actions. The drone agent heartbeat and pairing, and `mqtt-auth-sync` (`CONVEX_URL`), talk to it. Cross the two and the GCS loads but no drone ever appears, or sign-in works while commands never reach the agent. ## Environment Copy the example file and edit it before bringing anything up. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ADOSMissionControl/tools/selfhost cp .env.example .env ``` **CONVEX\_INSTANCE\_NAME** `string` A short instance name for the self-hosted backend, for example `ados-selfhost`. **CONVEX\_INSTANCE\_SECRET** `string` *required* A long random secret for the backend. Generate one with `openssl rand -hex 32`. **CONVEX\_CLOUD\_ORIGIN** `string` The client API origin the backend advertises, for example `http://192.168.1.50:3210`. Use your LAN IP or hostname. **CONVEX\_SITE\_ORIGIN** `string` The site (HTTP actions) origin the backend advertises, for example `http://192.168.1.50:3211`. **NEXT\_PUBLIC\_CONVEX\_URL** `string` The client API origin (`:3210`) baked into the GCS build. This is a build argument, inlined when the image is built, not read at runtime. **CONVEX\_URL** `string` The site origin (`:3211`). `mqtt-auth-sync` fetches broker credentials from it. **MQTT\_USERNAME** `string` (default: ados) The broker service principal. **MQTT\_PASSWORD** `string` *required* The password for that principal. You also write it into the broker password file in the setup steps below. **MQTT\_AUTH\_RELAY\_SECRET** `string` *required* The bearer `mqtt-auth-sync` presents to Convex to fetch broker credentials. Generate with `openssl rand -hex 32` and set the same value on Convex. Without it the broker never learns about paired devices. **RTSP\_URL\_PATTERN** `string` (default: rtsp\://host.docker.internal:8554/\{deviceId}) The RTSP source the video relay pulls from. `{deviceId}` is replaced with the drone's device ID. **VIDEO\_RELAY\_SECRET** `string` *required* The secret the relay verifies viewer tokens with. Generate with `openssl rand -hex 32` and set the same value on Convex, which mints the tokens. The relay refuses to start while it is empty. > [!WARNING] > > `NEXT_PUBLIC_CONVEX_URL` and `CONVEX_URL` are different values. The first is > the `:3210` client API for the browser; the second is the `:3211` site origin. > Swapping them is the most common setup mistake. ## Setup The backend needs its functions and auth keys before the rest of the stack is useful, so the order matters. Run every command from `tools/selfhost`. **1. Load the environment into your shell** Later steps read values from `.env`. Export them into the current shell: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} set -a; . ./.env; set +a ``` **2. Start the backend** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose up -d convex-backend ``` **3. Generate the admin key** The admin key is generated inside the backend container: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose exec convex-backend ./generate_admin_key.sh ``` Store it in a secrets manager. The commands below use it as ``. **4. Push Convex functions and schema** From a machine with the repo checked out, deploy the functions to your `:3210` origin: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex deploy --url http://192.168.1.50:3210 --admin-key ``` > [!WARNING] > > On a self-hosted backend every Convex CLI call needs your own `--url` and > `--admin-key`. Without them the functions land on another deployment and > sign-in fails with no visible error. **5. Generate and set the auth keys and secrets** The helper script prints `JWT_PRIVATE_KEY` and `JWKS` lines. Evaluate them into the shell, then set them, the GCS origin and both relay secrets on the backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} eval "$(node ../../scripts/generate-auth-keys.mjs | grep -E '^(JWT_PRIVATE_KEY|JWKS)=')" npx convex env set JWT_PRIVATE_KEY "$JWT_PRIVATE_KEY" \ --url http://192.168.1.50:3210 --admin-key npx convex env set JWKS "$JWKS" \ --url http://192.168.1.50:3210 --admin-key npx convex env set SITE_URL "http://192.168.1.50:4000" \ --url http://192.168.1.50:3210 --admin-key npx convex env set VIDEO_RELAY_SECRET "$VIDEO_RELAY_SECRET" \ --url http://192.168.1.50:3210 --admin-key npx convex env set MQTT_AUTH_RELAY_SECRET "$MQTT_AUTH_RELAY_SECRET" \ --url http://192.168.1.50:3210 --admin-key ``` `SITE_URL` is the origin the browser loads the GCS from, not a Convex origin. **6. Seed the broker credential files** The broker mounts its password file and ACL as files, so both must exist before its first start. Otherwise Docker creates directories at those paths. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cp ../mqtt-bridge/deploy/acl.conf ./acl.conf docker run --rm -v "$PWD:/work" eclipse-mosquitto:2 \ mosquitto_passwd -b -c /work/passwd "${MQTT_USERNAME:-ados}" "$MQTT_PASSWORD" ``` From then on `mqtt-auth-sync` keeps both files current: it adds every paired agent and every live operator grant, so a newly paired agent can connect with no manual step. **7. Bring up everything** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose up -d ``` Compose builds the GCS, auth-sync and relay images on first run, then starts every service. ## Publish the relay URLs The GCS reads the broker and relay addresses from Convex at runtime. Set them to however you expose Mosquitto's WebSocket listener and the relay: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex env set MQTT_BROKER_URL "wss://mqtt.cloud.example.com" \ --url http://192.168.1.50:3210 --admin-key npx convex env set VIDEO_RELAY_URL "wss://video.cloud.example.com" \ --url http://192.168.1.50:3210 --admin-key ``` Without these the GCS uses the managed broker and relay, which do not know your devices. ## Point the agent at the stack Set the drone's `server.mode` to `self_hosted` and point both `server.self_hosted.url` and `pairing.convex_url` at the site origin (`:3211`). The full procedure is on [Self-hosting: Drone Agent](/developers/self-hosting/agent). ## Expose the stack through a Cloudflare tunnel Browser cloud mode needs HTTPS. A Cloudflare tunnel gives each service a TLS hostname with no inbound port open on the host: `cloudflared` keeps outbound connections to Cloudflare's edge. Any TLS reverse proxy that forwards WebSocket upgrades works the same way. **1. Install cloudflared** On a Debian or Ubuntu host: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare.gpg echo "deb [signed-by=/usr/share/keyrings/cloudflare.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list sudo apt update && sudo apt install cloudflared ``` **2. Create a tunnel** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cloudflared tunnel login cloudflared tunnel create ados-relay ``` **3. Route a hostname to each service** Create `~/.cloudflared/config.yml`. Each hostname maps to one published port: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} tunnel: YOUR_TUNNEL_ID credentials-file: /root/.cloudflared/YOUR_TUNNEL_ID.json ingress: - hostname: gcs.cloud.example.com service: http://localhost:4000 - hostname: convex.cloud.example.com service: http://localhost:3210 - hostname: convex-site.cloud.example.com service: http://localhost:3211 - hostname: mqtt.cloud.example.com service: http://localhost:9001 - hostname: video.cloud.example.com service: http://localhost:3001 - service: http_status:404 ``` Add a DNS route for each hostname with `cloudflared tunnel route dns ados-relay `. **4. Start the tunnel** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cloudflared tunnel run ados-relay ``` **5. Use the HTTPS origins everywhere** Rebuild the GCS with `NEXT_PUBLIC_CONVEX_URL=https://convex.cloud.example.com`, set `SITE_URL` to `https://gcs.cloud.example.com`, set `MQTT_BROKER_URL` and `VIDEO_RELAY_URL` to the `wss://` hostnames, and point the agent at `https://convex-site.cloud.example.com`. ## Verify * `curl http://192.168.1.50:3210/version` returns a version, so the backend answers on the client API origin. * `docker compose logs mqtt-auth-sync` shows no `sync failed; retrying` lines, so `MQTT_AUTH_RELAY_SECRET` matches on both sides. * `docker compose logs video-relay` shows `Video relay listening on port 3001`, so `VIDEO_RELAY_SECRET` is set. * Sign-in works in the GCS, so the auth keys are on the right deployment. * A paired drone appears in the fleet, so its heartbeat reached the `:3211` site origin. Over plain HTTP the GCS stays local and talks to drones on the LAN. Serve it behind TLS to use the cloud relay. Functions are pushed with `npx convex deploy` on every upgrade; the GCS image does not push them on boot. ## Next steps > [card] [Mission Control and Convex](/developers/self-hosting/mission-control-and-convex) > > Build the GCS image and run the Convex backend on their own. > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > The port table and the common failure modes. # Self-hosting: the ados-deploy tool Source: https://docs.altnautica.com/developers/self-hosting/deploy-tool A guided deployer for the tools/selfhost Compose stack: wizard, dry-run plan, upgrade, status and teardown. `ados-deploy` is a Rust terminal tool in the Mission Control repo at `tools/deploy/`. It brings up the self-hosted stack (Convex backend and dashboard, the Mission Control web GCS, Mosquitto with its auth sync, and the video relay) through a guided flow, then keeps the lifecycle commands in one place. It is not a second stack. It drives the same Compose project documented on [All-in-one stack](/developers/self-hosting/all-in-one), `tools/selfhost/docker-compose.yml`. It adds the ordering, the generated config, the secret handling and the verification. ## When to use which path | Use | When | | - | - | | `ados-deploy` | You want the admin key, the pushed Convex functions, the Convex env vars, the relay secrets and the broker credential files handled and verified in one ordered pass. | | Hand-run Compose | You are changing the stack itself, debugging one service, or want to understand each step. Start from [All-in-one stack](/developers/self-hosting/all-in-one). | `ados-deploy` works on a repo checkout, because it builds the Mission Control image from the repo and pushes Convex functions from it. ## Invoke it From a checkout, through the npm script: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm run deploy -- deploy --host 192.168.1.50 ``` Everything after `--` goes to `ados-deploy`. The script runs `cargo run --release --quiet --manifest-path tools/deploy/Cargo.toml --`. Directly with cargo: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cargo run --manifest-path tools/deploy/Cargo.toml -- status ``` Through the bootstrap, which fetches a checkout if you do not have one: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ./tools/deploy/deploy.sh ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -sSL https://raw.githubusercontent.com/altnautica/ADOSMissionControl/main/tools/deploy/deploy.sh | sh ``` The bootstrap uses the current checkout when it finds `tools/selfhost/docker-compose.yml`, otherwise it clones to `$HOME/ADOSMissionControl`. Override with `ADOS_DIR` and `ADOS_REPO_URL`. It then launches, in order of preference, a cached or committed `./ados-deploy` binary, the matching release asset, or a `cargo` build. Extra arguments pass through. With no action the tool opens an interactive menu. On a non-terminal (CI, or a piped invocation) it asks you to pass an action instead. ## Actions | Action | What it does | | - | - | | `deploy` | Run the wizard (or build the config from flags), then execute the deploy plan. | | `reconfigure` | Re-open the wizard pre-filled from an existing deploy: host, ports, secrets and Convex provisioning recovered from the generated `.env`. | | `upgrade` | Pull newer images, then re-run the idempotent deploy plan so the image is rebuilt, functions are re-pushed and env vars are re-set. | | `restart` | `docker compose restart`. | | `teardown` (alias `down`) | `docker compose down`, with an opt-in volume purge. | | `status` | Print the deployed stack's status and its reach links. | An unrecognised action falls through to the menu. ## Dry-run first ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm run deploy -- deploy --host 192.168.1.50 --plan ``` `--plan` (alias `--dry-run`) prints the files the deploy would write and the commands it would run, in order, then exits without touching anything. Secrets are redacted in the plan output. The order is the same one the real run executes. ## Flags ### Rendering and interactivity | Flag | Meaning | | - | - | | `--no-color` | Disable ANSI colour. | | `--ascii` | ASCII glyphs, no Unicode box drawing or spinner. | | `--plain` | Escape-free line output, for a non-tty or CI log. | | `--quiet` | Only the final summary. | | `--json` | Machine output, no UI. | | `--non-interactive` | Never prompt. Use flags, environment and defaults. | | `--yes`, `-y` | Accept the detected default at every prompt. | | `--plan`, `--dry-run` | Print the plan and exit. | ### Deploy answers Supply these to run the whole flow without prompts. | Flag | Meaning | | - | - | | `--host ` | The address browsers and agents reach the stack at. | | `--mqtt-password ` | The broker service principal password. Generated when omitted. | | `--convex-managed-url ` | Use an existing Convex deployment instead of starting one. | | `--mqtt-managed-url ` | Use an existing MQTT broker. | | `--video-managed-url ` | Use an existing video relay. | | `--no-video` | Do not deploy the video relay. | | `--no-mqtt` | Do not deploy the MQTT broker. | An unknown flag is ignored rather than rejected, so a newer wrapper script stays compatible with an older binary. `ados-deploy` does not set up TLS or a tunnel; see [Expose the stack through a Cloudflare tunnel](/developers/self-hosting/all-in-one#expose-the-stack-through-a-cloudflare-tunnel). ## What a deploy runs The plan is ordered and idempotent. For a full self-hosted deploy: 1. Preflight: Docker running, ports free, Node present. 2. Write the generated config files. 3. Start the Convex backend and dashboard. 4. Wait for Convex to answer on `/version`. 5. Retrieve the admin key (`docker compose exec -T convex-backend ./generate_admin_key.sh`). 6. Push the Convex functions. 7. Generate and set the auth keys (`JWT_PRIVATE_KEY`, `JWKS`). 8. Set the Convex env vars: `SITE_URL`, plus `MQTT_BROKER_URL` and `VIDEO_RELAY_URL` when those services exist. 9. Set the relay secrets on Convex: `MQTT_AUTH_RELAY_SECRET` and `VIDEO_RELAY_SECRET`, for each service this deploy starts. 10. Create the broker password file. 11. Seed the broker ACL from `tools/mqtt-bridge/deploy/acl.conf`, only when absent. 12. Build and start the remaining services. 13. Verify the GCS, the video relay and the MQTT port are reachable. With `--convex-managed-url`, steps 3 to 9 are skipped. With `--mqtt-managed-url` or `--no-mqtt`, steps 10 and 11 are skipped. On a plain-HTTP host the plan ends with a note that browser cloud mode needs HTTPS. Because the plan is idempotent, `upgrade` reconstructs the config from the deployed `.env` and runs it again. ## Files it writes Paths are relative to the repo root; commands run from the root. | Path | What it is | | - | - | | `tools/selfhost/docker-compose.yml` | The Compose file it drives. The repo's own, not generated. | | `tools/selfhost/.env` | The generated environment for the stack, secrets included. | | `tools/selfhost/docker-compose.override.yml` | Host port remaps. Written only when you change a default port. | | `tools/selfhost/passwd` | The Mosquitto password file. `mqtt-auth-sync` adds every paired device. | | `tools/selfhost/acl.conf` | The broker ACL, seeded once and kept current by `mqtt-auth-sync`. | ## Services The tool starts the services in `tools/selfhost/docker-compose.yml`: `convex-backend`, `convex-dashboard`, `mission-control`, `mosquitto`, `mqtt-auth-sync` and `video-relay`. What each one does is on [All-in-one stack](/developers/self-hosting/all-in-one#services). It checks for port conflicts before it starts anything; the default ports are in the [port table](/developers/self-hosting/troubleshooting-and-ports#ports). ## Check and tear down ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm run deploy -- status ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm run deploy -- restart ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm run deploy -- teardown ``` `teardown` runs `docker compose down`. Purging volumes is a separate opt-in, so a teardown does not destroy your Convex data. To roll back a bad upgrade, check out the previous commit of the repo and run `upgrade` again. The image is rebuilt and the functions re-pushed from the checkout, so the checkout is the version you run. ## Next steps > [card] [All-in-one stack](/developers/self-hosting/all-in-one) > > Every step the tool runs, by hand. > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > The port table and the common failure modes. # Self-hosting: Mission Control and Convex Source: https://docs.altnautica.com/developers/self-hosting/mission-control-and-convex Build the Mission Control web GCS as a Docker image and stand up a self-hosted Convex backend for auth, fleet data and cloud commands. Mission Control is a Next.js app you can build into a single Docker image and run on your own host. It talks to a Convex backend for sign-in, fleet management and the cloud command queue. Both halves live in [ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl) under GPL-3.0: the root `Dockerfile` builds the GCS, and `convex/` holds the functions and schema you push to the backend. > [!NOTE] > > You do not need Convex to fly on the LAN. Served over plain HTTP, Mission > Control connects straight to the agent and pairs over the local network with no > backend. Convex is for the cloud relay (cross-network access) and for auth. ## The two Convex origins A self-hosted Convex backend exposes two origins that are not interchangeable: * The **client API** origin (`:3210`) serves the GCS browser bundle (`NEXT_PUBLIC_CONVEX_URL`) and every `npx convex deploy` and `npx convex env set` call. * The **site** origin (`:3211`) serves HTTP actions: the agent heartbeat and pairing (`server.self_hosted.url`, `pairing.convex_url`) and the broker auth sync. Cross the two and the GCS loads but no drone ever appears, or sign-in works while commands never reach the agent. All published ports are in the [port table](/developers/self-hosting/troubleshooting-and-ports#ports). ## Build and run the GCS image The `Dockerfile` is a multi-stage build that produces a Next.js standalone server listening on port `4000`. `NEXT_PUBLIC_*` values are inlined at build time, so pass the Convex client API origin the browser will reach as a build argument. **1. Build the image** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ADOSMissionControl docker build \ --build-arg NEXT_PUBLIC_CONVEX_URL=https://convex.cloud.example.com \ -t ados-mission-control . ``` Build arguments the `Dockerfile` accepts: | Build arg | Purpose | | - | - | | `NEXT_PUBLIC_CONVEX_URL` | Convex client API origin (`:3210`). Required for cloud mode. | | `NEXT_PUBLIC_CESIUM_ION_TOKEN` | 3D terrain tiles. Optional. | | `NEXT_PUBLIC_DEMO_MODE` | `true` ships the build with the demo fleet. | | `NEXT_PUBLIC_PLUGIN_REGISTRY_URL` | Plugin registry origin. Optional. | | `ADOS_MANIFEST_URL` | Agent install manifest origin. Optional. | | `NEXT_PUBLIC_ANALYTICS_SCRIPT_URL` | Analytics script URL. Optional. | | `NEXT_PUBLIC_ANALYTICS_WEBSITE_ID` | Analytics site ID, used with the script URL. Optional. | **2. Run the container** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker run -d \ --name ados-mission-control \ -p 4000:4000 \ ados-mission-control ``` The GCS is now at `http://localhost:4000`. The container sets `PORT=4000` and `HOSTNAME=0.0.0.0`; map `-p` to any host port you want. > [!TIP] > > Cloud mode (relay through Convex and MQTT) only activates when the GCS is > served over HTTPS. Over plain HTTP the GCS stays local and connects directly to > agents on the LAN. Put the container behind a TLS proxy or a > [Cloudflare tunnel](/developers/self-hosting/all-in-one#expose-the-stack-through-a-cloudflare-tunnel) > to reach a drone across networks. ## Stand up a self-hosted Convex backend You have two routes: * **Convex Cloud** is a hosted backend. In the `ADOSMissionControl` directory run `npx convex dev` to create and link a deployment, then `npx @convex-dev/auth` to set up its auth keys. * **Self-hosted** runs the open-source backend image [`ghcr.io/get-convex/convex-backend`](https://github.com/get-convex/convex-backend) in Docker. The rest of this page covers that route. The [all-in-one stack](/developers/self-hosting/all-in-one) bundles the backend with its dashboard, the GCS and the relay layers in one compose file. To run the backend on its own: **1. Start the backend** Start the `convex-backend` service from the all-in-one compose file, or your own compose file using the same image: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose up -d convex-backend ``` **2. Generate the admin key** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose exec convex-backend ./generate_admin_key.sh ``` Store the key in a secrets manager. The commands below use it as ``. **3. Push functions and schema** From a machine with the repo checked out, point the CLI at your own client API origin and admin key: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ADOSMissionControl npx convex deploy \ --url https://convex.cloud.example.com \ --admin-key ``` > [!WARNING] > > On a self-hosted backend every Convex CLI call needs your own `--url` and > `--admin-key`. Without them the functions land on another deployment and > sign-in fails with no visible error. **4. Generate the auth keys** A fresh backend has no signing keys. Convex Auth signs session JWTs with RS256. The helper script prints `JWT_PRIVATE_KEY` and `JWKS` lines; evaluate them into your shell: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} eval "$(node scripts/generate-auth-keys.mjs | grep -E '^(JWT_PRIVATE_KEY|JWKS)=')" ``` **5. Set the auth environment** Set the keys plus the GCS origin. `SITE_URL` is the origin the browser loads the GCS from, not a Convex origin: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex env set JWT_PRIVATE_KEY "$JWT_PRIVATE_KEY" \ --url https://convex.cloud.example.com --admin-key npx convex env set JWKS "$JWKS" \ --url https://convex.cloud.example.com --admin-key npx convex env set SITE_URL "https://gcs.cloud.example.com" \ --url https://convex.cloud.example.com --admin-key ``` ## Relay environment on Convex Convex carries auth, fleet state and the cloud command queue. Live telemetry and browser video go through the MQTT broker and the video relay, and Convex needs four values for them: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Public broker WebSocket URL the GCS connects to npx convex env set MQTT_BROKER_URL "wss://mqtt.cloud.example.com" \ --url https://convex.cloud.example.com --admin-key # Public video relay URL the GCS opens streams on npx convex env set VIDEO_RELAY_URL "wss://video.cloud.example.com" \ --url https://convex.cloud.example.com --admin-key # Signs five-minute viewer tokens; same value as the relay's VIDEO_RELAY_SECRET npx convex env set VIDEO_RELAY_SECRET "" \ --url https://convex.cloud.example.com --admin-key # Bearer the broker auth sync presents; same value as in the broker's env npx convex env set MQTT_AUTH_RELAY_SECRET "" \ --url https://convex.cloud.example.com --admin-key ``` Without `VIDEO_RELAY_SECRET` the GCS reports the relay as not configured. Without `MQTT_AUTH_RELAY_SECRET` the broker credential endpoint answers `503` and no device can log in to the broker. ## Point the agent at the backend Set the drone's `server.mode` to `self_hosted` and point both `server.self_hosted.url` and `pairing.convex_url` at the site origin (`:3211`). The full procedure is on [Self-hosting: Drone Agent](/developers/self-hosting/agent). ## Verify * `curl https://convex.cloud.example.com/version` returns a version, so the backend answers on the client API origin. * Sign-in works in the GCS, so the auth keys are on the right deployment. * A paired drone appears in the fleet, so its heartbeat reached the site origin. Over plain HTTP the GCS stays local; serve it behind TLS to use the cloud relay. If the GCS loads but no drone appears, recheck the `:3210` versus `:3211` wiring above. ## Next steps > [card] [Drone Agent](/developers/self-hosting/agent) > > Install the agent and point it at your backend. > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > The port table and the common failure modes. # Self-hosting: MQTT broker Source: https://docs.altnautica.com/developers/self-hosting/mqtt-bridge Run Mosquitto for the ADOS cloud relay with per-device auth, a deny-by-default ACL and credentials synced from Convex. The MQTT broker is the live-data layer of the cloud relay. The agent and the Mission Control browser meet on it: the agent publishes the MAVLink and MSP byte planes, answers WebRTC signaling and publishes vision detections and plugin streams, and the browser subscribes and sends its uplink. You only need this layer when the GCS and the drone are not on the same LAN. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} agent (drone) ──MQTT over TLS / WSS──► TLS front ──► Mosquitto ◄──WSS── GCS browser ▲ mqtt-auth-sync ── passwd, acl ─┘ (pulled from Convex) ``` Fleet status does not go through the broker. The agent POSTs its heartbeat to Convex over HTTPS. The topic list is on [Cloud infrastructure](/architecture/cloud-infrastructure). The broker assets live in the Mission Control repository at `tools/mqtt-bridge/deploy/`: `mosquitto.conf`, `acl.conf`, the auth-sync scripts, and a compose file for a standalone broker. > [!NOTE] > > The [all-in-one stack](/developers/self-hosting/all-in-one) and the > [deploy tool](/developers/self-hosting/deploy-tool) wire the same broker and > auth sync for you. This page is for running the broker on its own. ## Prerequisites * A self-hosted Convex backend. The auth sync reads its site origin (`:3211`). See [Mission Control and Convex](/developers/self-hosting/mission-control-and-convex). * Docker and Docker Compose on the broker host. `mosquitto_passwd` ships inside the `eclipse-mosquitto` image. * A TLS front for the broker: a tunnel or a reverse proxy. The agent never dials plaintext, and an HTTPS GCS needs `wss://`. ## The compose stack `tools/mqtt-bridge/deploy/docker-compose.yml` runs two services: | Service | Image | Purpose | | - | - | - | | `mosquitto` | `eclipse-mosquitto:2` | The broker, with a TCP listener on 1883 and a WebSocket listener on 9001. | | `cloudflared` | `cloudflare/cloudflared:latest` | Optional. Puts the broker behind a Cloudflare tunnel, which terminates TLS. | The repository has no forwarding service between the broker and Convex. Fleet status reaches Convex through the agent's own heartbeat. ## Listeners and TLS `mosquitto.conf` declares two plaintext listeners and no TLS listener: * **1883**, MQTT over TCP. Keep it on the host or the Docker network. The agent does not use it. * **9001**, MQTT over WebSocket (`protocol websockets`). The TLS front forwards to it. The agent always connects over TLS: * With the default `server.mqtt_transport: websockets`, the agent dials `wss://:443/mqtt`. Put a TLS-terminating proxy or tunnel on 443 that forwards `/mqtt` to the 9001 listener. * With `server.mqtt_transport: tcp`, the agent speaks MQTT over TLS on `mqtt_port`. Add a TLS listener to `mosquitto.conf`, for example: ```ini theme={"theme":{"light":"github-light","dark":"github-dark"}} listener 8883 certfile /mosquitto/config/certs/fullchain.pem keyfile /mosquitto/config/certs/privkey.pem ``` and set the agent's `server.self_hosted.mqtt_port` to `8883`. The browser connects over `wss://` through the same front. Tell Mission Control where the broker is by setting `MQTT_BROKER_URL` on the Convex deployment to the full WebSocket URL, for example `wss://mqtt.example.com/mqtt`. The GCS reads it at run time through the public `clientConfig` query. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex env set MQTT_BROKER_URL "wss://mqtt.example.com/mqtt" \ --url http://:3210 --admin-key ``` ## Broker authentication The reference `mosquitto.conf` ships with authentication on: anonymous access is off, and the broker checks a password file and a deny-by-default topic ACL. | Principal | Username | Password | Permissions | | - | - | - | - | | Drone Agent | `ados-` | The device's pairing key, the same value it sends as `X-ADOS-Key` | read and write `ados//#` | | GCS operator grant | `gcs-op-` | Minted per operator by Convex and held in the browser tab's memory | read `ados//#` for each owned device; write only `mavlink/rx`, `msp/rx` and `webrtc/offer` under it | | Service account | `ados` | `MQTT_PASSWORD` | read `ados/#` | An operator grant writes only the three uplink topics. A write grant on the whole subtree would also let a browser publish the agent's own topics and fake telemetry for the aircraft. A publish the ACL refuses at QoS 0 is dropped silently, so confirm a publish by subscribing. The `ados` service account stays in the password file and the ACL. The auth sync writes it on every pass from `BRIDGE_MQTT_USERNAME` and `BRIDGE_MQTT_PASSWORD`. ### Keep the password file and ACL in sync Agent and operator credentials come from Convex, so `passwd` and `acl.conf` are generated, not hand-written. `scripts/regenerate-passwd.sh` fetches them from the `/admin/mqtt-auth-entries` HTTP action with `Authorization: Bearer $MQTT_AUTH_RELAY_SECRET`, rewrites both files in place and sends the broker a `SIGHUP`. It aborts if `MQTT_AUTH_RELAY_SECRET` is unset. `MQTT_AUTH_RELAY_SECRET` is required. Generate it once and set the same value in two places: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openssl rand -hex 32 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex env set MQTT_AUTH_RELAY_SECRET "" \ --url http://:3210 --admin-key ``` and in the broker host's `.env` as `MQTT_AUTH_RELAY_SECRET=`. How the sync runs: * **All-in-one stack.** The `mqtt-auth-sync` service in `tools/selfhost/docker-compose.yml` runs the script every 30 seconds (`SYNC_INTERVAL_SECONDS`). It shares the broker's PID namespace to deliver the reload, so no Docker socket is mounted. A failed pass retries on the same interval, and a newly paired drone connects after the next good pass. * **Standalone broker.** Run `regenerate-passwd.sh` from a systemd timer or cron on the broker host, with `CONVEX_HTTP_URL` set to your site origin and `BROKER_CONTAINER` naming the broker container. Before the broker's first start, create the two files it mounts, or Docker creates directories at those paths. Seed `acl.conf` from `tools/mqtt-bridge/deploy/acl.conf`, then create `passwd` with the service account: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker run --rm -v "$PWD:/work" eclipse-mosquitto:2 \ mosquitto_passwd -b -c /work/passwd ados "$MQTT_PASSWORD" ``` Re-pairing a device rotates its pairing key. The next sync picks up the new value. ### Bench mode (no auth) For a local bench or CI fixtures, `mosquitto.conf` carries a commented bench block that turns anonymous access on. Never run an internet-facing broker with `allow_anonymous true`. ## Verify it works Once the stack is up and `passwd` is populated, check each principal from inside the broker container: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose exec mosquitto sh ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # A device can publish to its own subtree. mosquitto_pub -h localhost -p 1883 \ -u ados- -P \ -t "ados//test" -m "hello" # A device cannot publish to another device's subtree. # The ACL drops it silently; the broker log shows "Denied". mosquitto_pub -h localhost -p 1883 \ -u ados- -P \ -t "ados//test" -m "should fail" # The service account can read every device's MAVLink downlink. mosquitto_sub -h localhost -p 1883 \ -u ados -P \ -t "ados/+/mavlink/tx" -C 1 -W 5 ``` The last command prints one message from a connected agent with a live flight controller, or exits after 5 seconds. Follow the sync from the all-in-one stack with: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose logs -f mqtt-auth-sync ``` ## Next steps > [card] [Video relay](/developers/self-hosting/video-relay) > > Add live video alongside the data planes. > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > Every port in the stack and the common failure modes. # Self-hosting: overview Source: https://docs.altnautica.com/developers/self-hosting/overview Run the ADOS cloud relay on your own hardware: Convex, Mission Control, the MQTT broker and the video relay, all optional. ADOS is open source end to end, and you can run the whole stack on hardware you own. This page maps what is self-hostable, how the pieces connect, and the routes to bringing the cloud relay up. ## What you can self-host > [card] [Drone Agent](/developers/self-hosting/agent) > > The agent on your companion computer, pointed at your own backend. > [card] [Mission Control and Convex](/developers/self-hosting/mission-control-and-convex) > > The web GCS plus a self-hosted Convex backend for auth, fleet data and > cloud commands. > [card] [MQTT broker](/developers/self-hosting/mqtt-bridge) > > Mosquitto with per-device auth and an ACL synced from Convex. > [card] [Video relay](/developers/self-hosting/video-relay) > > RTSP to fragmented MP4 over WebSocket so a browser can play the stream. The agent lives in [github.com/altnautica/ADOSDroneAgent](https://github.com/altnautica/ADOSDroneAgent). Mission Control, the broker assets, the video relay and the deploy tool live in [github.com/altnautica/ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl). Both are GPL-3.0. ## Local-first by default You do not need any cloud infrastructure to fly. The default path is local, over your LAN: * The drone-to-ground link is the WFB-ng radio. * Mission Control reaches an agent directly by hostname or IP. Paste the agent's address into the Add-a-Node card and the GCS pairs with it over the LAN. No Convex round-trip is involved. A fresh agent install runs with `server.mode: local`, and nothing reaches out to a backend. That is the correct setup for a single-LAN bench or field deployment. > [!NOTE] > > On the LAN, Mission Control talks to the agent over plain HTTP. The cloud > relay path is used only when the GCS is served over HTTPS. See > [Drone Agent configuration](/drone-agent/configuration) for the agent's > `server` block. ## When you want the cloud relay The cloud relay is the opt-in path for reaching a drone across networks: remote sites, mobile data, anywhere the GCS and the agent are not on the same LAN. Each layer is optional. | Layer | What it carries | | - | - | | Convex backend | Auth, fleet records, cloud commands, and the agent's status heartbeat. | | MQTT broker | The live MAVLink and MSP byte planes, WebRTC signaling, vision detections and plugin streams between the agent and the browser. | | Video relay | Live video in the browser, remuxed from RTSP with no transcoding. | Fleet status does not travel over MQTT. The agent POSTs its status heartbeat straight to `{convex}/agent/status` over HTTPS every 5 seconds, authenticated with its `X-ADOS-Key`. The broker carries the live data planes under `ados//...`; the full topic list is on [Cloud infrastructure](/architecture/cloud-infrastructure). To put an agent on a self-hosted backend, set its `server.mode` to `self_hosted`, point `server.self_hosted.url` and `pairing.convex_url` at your Convex site origin, and set `server.self_hosted.mqtt_broker` to your broker. See [Self-hosting: the agent](/developers/self-hosting/agent). ## Routes to deploy > [card] [Deploy tool](/developers/self-hosting/deploy-tool) > > The recommended path. `ados-deploy` is a guided terminal deployer that > drives the `tools/selfhost` Compose stack for you. > [card] [All-in-one stack](/developers/self-hosting/all-in-one) > > One Docker Compose at `tools/selfhost/` runs the Convex backend and > dashboard, Mission Control, Mosquitto with its auth sync, and the video > relay on a single host. To run only the layers you need, the broker and the video relay each ship their own compose file under `tools/mqtt-bridge/deploy/` and `tools/video-relay/deploy/`, so you can add a relay layer beside an existing Convex deployment. ## Convex has two origins A self-hosted Convex backend exposes two origins that are not interchangeable: * **`:3210`** is the client API. The Mission Control browser bundle talks to it (`NEXT_PUBLIC_CONVEX_URL`), and `npx convex deploy` pushes functions to it. * **`:3211`** is the site origin that serves HTTP actions. The agent's pairing register, status heartbeat and command poll go here, and so does the broker auth sync. The agent's `server.self_hosted.url` and `pairing.convex_url` point here. Cross the two and the GCS loads but no drone ever appears. Every port in the stack is listed on [Self-hosting: ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports). ## Resource footprint A small deployment of one to five drones runs on a single 4-core, 8 GB Linux host that runs Convex, Mosquitto and the video relay together. The Convex backend needs the most headroom, because its SQLite store grows with your data. The broker is light. The video relay runs one ffmpeg remux per stream that has viewers. | Component | Bandwidth | | - | - | | Convex (self-hosted) | Under 1 GB/month | | Convex (hosted) | Under 1 GB/month | | MQTT relay | About 100-500 MB/month per drone | | Cloudflare Tunnel | No limit applied by the tunnel | | STUN | Negligible | | Video (peer-to-peer WebRTC) | None through your server | ## Next steps > [card] [Deploy tool](/developers/self-hosting/deploy-tool) > > Bring the stack up with the guided installer. > [card] [All-in-one stack](/developers/self-hosting/all-in-one) > > The one-host Docker Compose runbook. > [card] [Self-hosting: the agent](/developers/self-hosting/agent) > > Point a Drone Agent at your backend. > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > The port table and the common failure modes. # Self-hosting: ports and troubleshooting Source: https://docs.altnautica.com/developers/self-hosting/troubleshooting-and-ports Every port in a self-hosted ADOS stack, the failures that come from crossed wiring, and how to harden what you expose. Most self-host problems are wiring, not bugs: a call sent to the wrong Convex origin, a broker with no TLS front, or a relay pointed at an RTSP source that is not there. This page lists every port, the common failures and their fixes, and a hardening checklist for the day you expose a service beyond your LAN. ## Ports Every default port in the stack, what binds it and who connects to it. | Port | Service | Transport | Who connects | | - | - | - | - | | `3210` | Convex backend, client API | HTTP, WebSocket | The Mission Control browser bundle (`NEXT_PUBLIC_CONVEX_URL`) and `npx convex deploy`. | | `3211` | Convex backend, site (HTTP actions) | HTTP | The agent's pairing register, `/agent/status` heartbeat and `/agent/commands` poll (`server.self_hosted.url`, `pairing.convex_url`), and `mqtt-auth-sync` (`/admin/mqtt-auth-entries`). | | `6791` | Convex dashboard | HTTP | You, in a browser. | | `4000` | Mission Control web container | HTTP | The browser. | | `1883` | Mosquitto, MQTT over TCP | TCP | Local tools on the broker host or Docker network, such as `mosquitto_sub`. No remote client. | | `9001` | Mosquitto, MQTT over WebSocket | WebSocket | The TLS front that serves `wss:///mqtt` to agents and browsers. | | `443` | Your TLS front (tunnel or reverse proxy) | HTTPS, WSS | Agents with the default `mqtt_transport: websockets` (`wss://:443/mqtt`), and browsers reaching every public origin. | | `8883` | Mosquitto TLS listener, if you add one | MQTT over TLS | Agents with `server.mqtt_transport: tcp`. The reference config has no TLS listener. | | `3001` | Video relay | HTTP, WebSocket | The browser, at `/ws/stream/`. `GET /` is the health check. | | `8080` | Drone Agent REST API and dashboard | HTTP | Mission Control over the LAN, and the `ados` CLI on the box. | | `8554` | Drone Agent RTSP (mediamtx) | RTSP | The video relay's `RTSP_URL_PATTERN`. | | `8091` | ADOS MCP connector, Streamable HTTP | HTTP | MCP clients in agent mode. See [MCP server and AI control](/developers/mcp-server). | > [!NOTE] > > `3210` and `3211` are two origins on the **same** Convex host. The browser and > `convex deploy` use `:3210`; the agent and the auth sync use `:3211`. See > [Mission Control and Convex](/developers/self-hosting/mission-control-and-convex). The agent never dials the broker in plaintext. With the default `server.mqtt_transport: websockets` it connects to `wss://:443/mqtt` (a configured `8883` is rewritten to `443`). With `tcp` it speaks MQTT over TLS on `server.self_hosted.mqtt_port`. See [Self-hosting: the agent](/developers/self-hosting/agent#how-the-agent-reaches-the-broker). ## Common failures > [accordion] The GCS loads but no drone ever appears > > The agent's heartbeat is not reaching the backend. The usual cause is a > crossed Convex origin: the agent's `pairing.convex_url` (or > `server.self_hosted.url`) points at the client API origin (`:3210`) > instead of the site origin (`:3211`), so the register and heartbeat calls > return 404. > > * Confirm both agent keys end in `:3211`. > * Confirm `server.mode` is exactly `self_hosted`. Any other value keeps the > agent local and silent. > * On the agent, check `journalctl -u ados-cloud -o json` (or > `ados logs query` if you enabled the logging store) for the failed call > and the URL it tried. > [accordion] Sign-in works but commands never reach the agent > > Auth is wired, so `:3210` is correct for the browser, but the cloud command > path is broken. > > * The agent is not reaching the site origin. `pairing.convex_url` wins; in > `self_hosted` mode the relay falls back to `server.self_hosted.url` when > it is empty. Set both so every component agrees. > * Mission Control was built against the wrong Convex origin. > `NEXT_PUBLIC_*` values are inlined at build time, so a wrong > `NEXT_PUBLIC_CONVEX_URL` cannot be fixed by a run-time env change. > Rebuild the image with the right `:3210` origin. > [accordion] The GCS connects locally but not across networks > > The cloud relay path is used only when Mission Control is served over > HTTPS. On `http://localhost` the GCS connects straight to the agent over > the LAN and does not use Convex, MQTT or the video relay. Put the GCS > container behind a TLS-terminating proxy or tunnel so it is served over > `https://`. > [accordion] The drone shows in the fleet but there is no live data > > Fleet status arrives through the agent's HTTPS heartbeat, so a drone can > appear while the broker path is broken. Live MAVLink, video signaling and > plugin streams need the broker. > > * The agent dials TLS only. With the default `websockets` transport, a TLS > front on 443 must forward `/mqtt` to Mosquitto's 9001 listener. With > `tcp`, Mosquitto needs a TLS listener on the agent's `mqtt_port`. > * The browser needs `wss://` too, through the same front. > * Mission Control reads the broker URL from the `MQTT_BROKER_URL` env var > on your Convex deployment. If it is unset, the GCS falls back to a broker > it cannot reach. Set it to your own `wss://` URL. > * The broker denies anonymous access. An agent missing from `passwd` > cannot connect. Check that `mqtt-auth-sync` is running and that > `MQTT_AUTH_RELAY_SECRET` matches on Convex and on the broker host. See > [Self-hosting: MQTT broker](/developers/self-hosting/mqtt-bridge). > [accordion] The video pane stays black > > The relay spawns an ffmpeg process per stream on the first viewer > connect, and that process needs a live RTSP source. > > * Confirm the relay's `RTSP_URL_PATTERN` resolves to a reachable RTSP > server. The compose default is > `rtsp://host.docker.internal:8554/{deviceId}`; when the source is on a > different host, point the pattern at it. > * Confirm the drone serves RTSP at that stream name. The `{deviceId}` > placeholder is replaced with the WebSocket path segment, which must > match `[a-zA-Z0-9_-]+` or the upgrade is rejected with a `400`. > * `curl http://localhost:3001/` returns a JSON status with > `activeSessions` and a per-device viewer count. A session that never > appears means no viewer reached the relay; one that appears then > vanishes means ffmpeg could not pull the RTSP source. > * Over HTTPS the relay must be reachable over `wss://`, so `3001` needs > TLS in front of it. > [accordion] The agent does not respond on the LAN > > LAN pairing and direct status use the agent REST API on `8080`. > > * From a machine on the same LAN, > `curl http://:8080/api/version` returns the agent version > without a key. A refused connection means the agent is not up; run > `ados status` on the box. > * Mission Control reaches `8080` through its own LAN-pair proxy, so it can > resolve `.local` names server-side. If Add-a-Node pairing fails, confirm > the agent is reachable from the machine running the GCS, not only from > your laptop. ## Connectivity checklist When something does not connect, walk the path one hop at a time: **1. Backend reachable** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://convex.example.com:3210/version ``` A response means the client API origin is up. **2. Site origin reachable** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://convex.example.com:3211/ ``` The agent and the auth sync call this origin. If `:3210` answers and `:3211` does not, your proxy or tunnel forwards only one origin. **3. Broker subscribe over WebSocket** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx mqtt sub -t 'ados/+/mavlink/tx' \ -h mqtt.example.com -p 9001 -l ws \ -u ados -P ``` Press Ctrl-C after the first message. A connection error here is the browser's failure; an empty wait means no agent is publishing. **4. Video relay health** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl http://localhost:3001/ ``` Returns `{"status":"ok",...}`. Anything else means the relay is not up. **5. Agent REST on the LAN** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl http://:8080/api/version ``` Returns the agent version without a key. ## Security hardening The defaults suit a private LAN. Before you expose anything beyond it, work through this list. ### Choose how to expose each service None of these services has to be public. On a single LAN you expose nothing. For cross-network access, a tunnel keeps inbound ports closed and terminates TLS for you, while port forwarding opens a router port and you terminate TLS at a reverse proxy such as nginx or Caddy. Pick one per service and keep the rest LAN-only. ### TLS on every public origin Browsers block mixed content, and the agent dials the broker over TLS only: * Convex behind `https://` on both origins. Forward both `:3210` and `:3211`; forwarding one is a common cause of the no-drone failure above. * Mosquitto's `9001` WebSocket listener behind `wss://`. * The video relay's `3001` listener behind `wss://`. ### MQTT authentication The reference `mosquitto.conf` ships with `allow_anonymous false`, a password file and a deny-by-default ACL. * Keep `allow_anonymous false`. The commented bench block is for a local bench or CI only. * Each device logs in as `ados-` with its own pairing key, scoped to `ados//#`. Never share one broker account across devices. * Keep `mqtt-auth-sync` (or a timer running `regenerate-passwd.sh`) running, so a re-paired device's new key reaches the broker within one interval. ### Firewall rules * Do not publish `1883` to the internet. Nothing remote uses it. * The agent REST API on `8080` is a LAN surface. Cross-network access goes through the cloud relay, not a forwarded `8080`. * Publish only the origins a remote browser or agent needs: the Convex origins, the broker's TLS front, the video relay and Mission Control. ### Rotate the keys you generate * The Convex admin key prints once on first boot. Keep it in a secrets manager, never in a committed file. * The auth signing keys (`JWT_PRIVATE_KEY` and `JWKS`) come from `scripts/generate-auth-keys.mjs`. Keep the private key off shared hosts. * A leaked device pairing key is both its broker password and its HTTP credential. Rotate it by re-pairing the device; the next auth sync replaces its broker entry. * Treat `MQTT_AUTH_RELAY_SECRET` and `VIDEO_RELAY_SECRET` like the admin key. The auth relay secret reads every device credential. ## Next steps > [card] [Self-hosting overview](/developers/self-hosting/overview) > > How the layers fit together. > [card] [MQTT broker](/developers/self-hosting/mqtt-bridge) > > The broker, the ACL and the auth sync. > [card] [Cloud infrastructure](/architecture/cloud-infrastructure) > > The relay architecture and the MQTT topic list. > [card] [Hardening](/operations/hardening) > > Lock down the nodes that join your stack. # Self-hosting: video relay Source: https://docs.altnautica.com/developers/self-hosting/video-relay Run the RTSP-to-WebSocket video relay so a browser can play a drone's live stream as fragmented MP4, with token-scoped access and no transcoding. The video relay takes an RTSP stream (from a camera or from mediamtx on the agent) and re-wraps it into fragmented MP4 (fMP4) over a WebSocket. A browser plays it through Media Source Extensions (MSE). ffmpeg copies the H.264 stream (`-c:v copy`) and only changes the container, so the relay adds little load or latency. It lives in [ADOSMissionControl](https://github.com/altnautica/ADOSMissionControl) under `tools/video-relay/`, GPL-3.0. ## How it works ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} RTSP source (camera / mediamtx on the agent) | v ffmpeg -rtsp_transport tcp -c:v copy -an -f mp4 -movflags frag_keyframe+empty_moov+default_base_moof pipe:1 | v WebSocket binary frames -> browser MSE SourceBuffer ``` * Each device gets one ffmpeg process, started on the first viewer and stopped when the last viewer leaves. An idle relay runs no ffmpeg. * The relay caches the stream's init segment and replays it to a viewer that joins a running session. * A viewer whose send backlog exceeds `VIDEO_RELAY_MAX_BACKLOG` is closed with code `1013` and reconnects. * The GCS player reads the codec from the stream's init segment, so H.264 profiles other than High play without changes. ## Viewer tokens Every WebSocket upgrade needs a token scoped to the device in the path. Without a valid one the relay answers `401` before any ffmpeg process starts. * Convex mints tokens in the `cmdVideoRelayTokens.mint` action. It checks that the signed-in operator owns the paired device, then signs a token with `VIDEO_RELAY_SECRET`. * A token has the form `.`: the expiry in Unix seconds and a hex HMAC-SHA256 of `|`. It lasts five minutes. The relay refuses tokens that are expired, dated more than ten minutes ahead, or scoped to another device. * The token is checked once at upgrade. An open stream keeps running after the token expires. * Pass it as `?token=` (a browser `WebSocket` cannot set headers) or as `Authorization: Bearer `. The relay and Convex must hold the same `VIDEO_RELAY_SECRET`. ## Configuration **VIDEO\_RELAY\_SECRET** `string` *required* The shared secret viewer tokens are verified with. Generate with `openssl rand -hex 32` and set the same value on Convex with `npx convex env set VIDEO_RELAY_SECRET "" --url --admin-key `. The relay exits at start while it is empty. **PORT** `number` (default: 3001) The HTTP and WebSocket listen port. **RTSP\_URL\_PATTERN** `string` (default: rtsp\://localhost:8554/\{deviceId}) The RTSP source template. `{deviceId}` is replaced with the device ID from the WebSocket path. The default works when mediamtx runs on the same host. The compose files default to `rtsp://host.docker.internal:8554/{deviceId}` so a container can reach an RTSP server on the Docker host. **VIDEO\_RELAY\_MAX\_BACKLOG** `number` (default: 4194304) Bytes queued for one slow viewer before it is dropped. ## Endpoints * `ws://:3001/ws/stream/{deviceId}?token=` opens a stream. The device ID must match `[a-zA-Z0-9_-]+`; anything else gets `400`. * A plain `GET` on any path is a liveness probe and returns only: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} {"status":"ok"} ``` The probe carries no session data. Session starts, viewer counts and ffmpeg exits appear in the relay's stdout log (`docker compose logs video-relay`). ## Run locally ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd tools/video-relay npm install VIDEO_RELAY_SECRET="$(openssl rand -hex 32)" npm run dev ``` ## Deploy with Docker The [all-in-one stack](/developers/self-hosting/all-in-one) includes the relay. To run it alone, use the compose file in `tools/video-relay/deploy/`. **1. Copy the env template** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd tools/video-relay/deploy cp .env.example .env ``` **2. Fill in the env file** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} RTSP_URL_PATTERN=rtsp://host.docker.internal:8554/{deviceId} PORT=3001 VIDEO_RELAY_SECRET= CLOUDFLARE_TUNNEL_TOKEN= ``` Compose refuses to start while `VIDEO_RELAY_SECRET` is empty. **3. Bring it up** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker compose up -d ``` **4. Tell Convex where the relay is** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx convex env set VIDEO_RELAY_URL "wss://video.cloud.example.com" \ --url --admin-key npx convex env set VIDEO_RELAY_SECRET "" \ --url --admin-key ``` The compose file runs two containers: 1. **video-relay**: the Node.js relay with ffmpeg. 2. **cloudflared**: a tunnel that exposes the relay on a public hostname. WebSocket upgrades pass through it with no extra configuration. A GCS served over HTTPS needs the relay on `wss://`. The tunnel is one way to get that; any HTTPS reverse proxy that forwards WebSocket upgrades works too. ## Browser client A minimal MSE viewer. Fetch a viewer token from Convex first, then open the stream: ```js theme={"theme":{"light":"github-light","dark":"github-dark"}} const token = await convex.action(api.cmdVideoRelayTokens.mint, { deviceId: "drone1" }); const ws = new WebSocket( `wss://video.cloud.example.com/ws/stream/drone1?token=${encodeURIComponent(token.token)}`, ); const mediaSource = new MediaSource(); const video = document.querySelector("video"); video.src = URL.createObjectURL(mediaSource); mediaSource.addEventListener("sourceopen", () => { // Example codec: H.264 High 4.1. Read the real one from the init segment. const buf = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.640029"'); ws.binaryType = "arraybuffer"; ws.onmessage = (e) => { if (!buf.updating) { buf.appendBuffer(e.data); } }; }); ``` `mint` returns `{ status: "ok", token, expiresAt }`, or `{ status: "not-configured" }` when Convex has no `VIDEO_RELAY_SECRET`. In production, queue frames and append only while the buffer is idle, and prune the buffer as it grows. The GCS player in `src/lib/video/mse-player.ts` (codec parsing in `src/lib/video/fmp4-codec.ts`) is a full reference with queueing, reconnect and buffer management. ## Next steps > [card] [Ports and troubleshooting](/developers/self-hosting/troubleshooting-and-ports) > > The port table and the common failure modes. > [card] [All-in-one stack](/developers/self-hosting/all-in-one) > > Run the relay with the rest of the stack on one host. # Signing keys Source: https://docs.altnautica.com/developers/signing-keys Generate an Ed25519 publisher key, sign plugin archives, enrol the key on an agent, and run a bench in unsigned mode. Every plugin a production agent installs must be signed by an Ed25519 key the agent trusts. This page owns the publisher-side lifecycle: generating a key, signing, enrolling the public key on the agent, and the bench mode for unsigned archives. Revocation is on [Revocation and incidents](/developers/revocation-and-incidents). ## Why Ed25519 Small keys (32 bytes), small signatures (64 bytes), fast constant-time verification, and no parameter choices to get wrong. OTA artifacts are also Ed25519-signed (minisign), so the algorithm is already in use on the agent. ## Generate a key pair > [!WARNING] > > Add `keys/` and `*.priv.pem` to your `.gitignore` before generating keys. In your own repository nothing ignores them for you. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin keygen acme-2026-A --output-dir keys ``` This writes two files under `keys/`: * `acme-2026-A.pem`, the public key (mode 0644). Operators install this at `/etc/ados/plugin-keys/acme-2026-A.pem`. * `acme-2026-A.priv.pem`, the private key (mode 0600). Your signing rig keeps it. Never commit it or copy it across hosts without encrypted transport. The positional argument is the signer id. `--force` overwrites existing files. `keygen` prints a SHA-256 fingerprint of the public key so an operator can cross-check the key they install. > [!NOTE] > > `keygen` is a developer aid. Production publisher keys deserve a hardware-token or air-gapped workflow. See [Key storage](#key-storage). `openssl` produces an equivalent pair: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p keys openssl genpkey -algorithm ed25519 -out keys/acme-2026-A.priv.pem openssl pkey -in keys/acme-2026-A.priv.pem -pubout -out keys/acme-2026-A.pem ``` ## Pick a signer id The signer id is a short, stable label: the first line of the archive's `SIGNATURE` file and the basename of the public key on the agent. Operators see it in the install review. Use a namespace prefix and a generation suffix, for example `acme-2026-A`. It is not a secret. ## Sign an archive `ados plugin sign` packs a plugin directory and signs it in one command: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin sign ./my-plugin \ --key keys/acme-2026-A.priv.pem \ --signer-id acme-2026-A \ --output extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug ``` All four are required: the plugin directory (with a `manifest.yaml`), `--key`, `--signer-id` and `--output`. In the ADOSExtensions monorepo, sign the archive `pack.sh` produced with `sign.sh`: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ADOS_SIGNING_KEY=keys/acme-2026-A.priv.pem \ ADOS_SIGNING_KEY_ID=acme-2026-A \ ./scripts/sign.sh extensions/my-plugin/dist/com.example.my-plugin-1.0.0.adosplug ``` `sign.sh` writes `com.example.my-plugin-1.0.0.signed.adosplug` next to the input. `ADOS_SIGNING_KEY` is the `.priv.pem` from `keygen` (or a raw 32-byte seed); a public key or an encrypted key is refused. `ADOS_SIGNING_KEY_ID` is required and has no default. Set `ADOS_SIGNING_PUBKEY` to your `.pem` to verify the signature right after writing it. Both paths compute the same canonical payload hash (SHA-256 over the sorted `\n\n` lines of every entry except `SIGNATURE`), sign that digest, and write a two-line `SIGNATURE` file: the signer id, then the base64 signature. The hash covers every entry, so the signature protects the manifest and every asset. ### Signing in CI Hold the base64-encoded private key in a repository secret and pass it inline: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} env: ADOS_SIGNING_KEY: ${{ secrets.ADOS_SIGNING_KEY }} ADOS_SIGNING_KEY_INLINE: "1" ADOS_SIGNING_KEY_ID: ${{ secrets.ADOS_SIGNING_KEY_ID }} ``` `ADOS_SIGNING_KEY_INLINE=1` makes `sign.sh` decode the key to a temp file, sign, and delete it. Put a high-value key behind a protected environment with required reviewers. ## Enrol the key on the agent The agent trusts a directory of PEM public keys, one file per signer id: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} /etc/ados/plugin-keys/ acme-2026-A.pem ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sudo install -m 0644 acme-2026-A.pem /etc/ados/plugin-keys/acme-2026-A.pem ``` The agent verifies an archive against the key named by the `SIGNATURE` file's first line. A signer with no matching file is refused with exit code `3`. No restart is needed: keys are read at every install. First-party status is pinned in agent code by signer id and exact key bytes, so a key file planted under a first-party name verifies only as a third party. First-party status unlocks inline GCS isolation, `resources.class: heavy`, and installs on a node without a sandboxing service backend. No plugin runs in-process. ## Bench install and signing On a bench, use one of two paths. **Signed (recommended).** Run the full chain once and every later build installs like production: 1. `ados plugin keygen acme-2026-A --output-dir keys` 2. Copy `keys/acme-2026-A.pem` to `/etc/ados/plugin-keys/acme-2026-A.pem` on the node. 3. Sign with `ados plugin sign` or `sign.sh`, as above. 4. `ados plugin install ./com.example.my-plugin-1.0.0.signed.adosplug` **Unsigned bench mode.** Unsigned archives install only while signature enforcement is relaxed: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} echo 'ADOS_PLUGIN_REQUIRE_SIGNED=0' | sudo tee -a /etc/ados/env sudo systemctl restart ados-control ados-plugin-host ados plugin install ./my-plugin.adosplug ``` `0`, `false`, `no` and `off` all relax enforcement, and the agent logs a warning while it is off. A revoked signer is refused even in this mode. Remove the line and restart both services when you are done. ## Key storage For iteration, a file on disk is fine. Tighten its permissions: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} chmod 0400 keys/acme-2026-A.priv.pem ``` For production keys, keep the private half off general-purpose disks: a hardware security module, a smartcard with an Ed25519 applet, or a TPM-sealed key. The signing input is a 32-byte digest, so any tool that can produce an Ed25519 signature over it can replace `sign.sh`. ## Self-signed closed fleets A fleet can sign and trust end to end with no Altnautica involvement: 1. Generate a key pair. 2. Install the public key at `/etc/ados/plugin-keys/.pem` on every agent. 3. Sign your plugins with the private key. 4. Publish on a GitHub release, or copy the file to each node and run `ados plugin install `. Self-hosted download hosts are not supported for URL install; see [URL install](/developers/distribution-url-install). If a key leaks, follow [Revocation and incidents](/developers/revocation-and-incidents). ## Next steps > [card] [URL install](/developers/distribution-url-install) > > Install from a GitHub release link. > [card] [Revocation and incidents](/developers/revocation-and-incidents) > > Retire a compromised key. # State and storage Source: https://docs.altnautica.com/developers/state-and-storage Where a plugin keeps state: process memory, its data directory and cloud records. Paths, atomicity and cleanup on remove. An agent plugin keeps state in process memory and in its per-plugin data directory, and a plugin granted `cloud.records` can also keep small records in the operator's cloud account. Pick the right one for the data; do not pile everything into one. ## The layers | Layer | Where | Survives | Use for | | - | - | - | - | | Ephemeral | RAM, in your plugin process | Until next restart | Counters, caches, in-flight subscriptions. | | Per-plugin disk | `/var/ados/plugin-data//` | Restarts and upgrades. Deleted on remove unless `--keep-data`. | Local config, calibration, sample files, cached models. | | Cloud records | The operator's cloud account | Until the plugin deletes them | Small JSON shared between the agent half, the GCS half and other devices. | ## Ephemeral state Normal Python module state. The host runs one process per plugin (per drone, for per-drone plugins), so a `dict` or a `list` is your ephemeral store. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} class MyPlugin: def __init__(self) -> None: self._last_voltage: float | None = None ``` This is the fastest layer and the least durable. Use it for anything you can recompute on restart. ## Per-plugin disk Every plugin gets a writable data directory. The runner hands the path to your plugin on the context: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: data_dir = ctx.data_dir # pathlib.Path, /var/ados/plugin-data// sample_log = data_dir / "samples.jsonl" ``` The context also carries `ctx.config_dir` (`/var/ados/plugin-data//config/`) and `ctx.temp_dir`, which is `/tmp/` inside the unit's private `/tmp` and is gone when the process exits. When the plugin is bound to a specific drone, `ctx.data_dir` is scoped per drone (`/var/ados/plugin-data//drones//`), while `ctx.config_dir` stays shared and `ctx.agent_id` carries the drone's id. The unit can write only its own `/var/ados/plugin-data//`, the shared plugin log directory and its private `/tmp`. Another plugin's data directory and `/run/ados` are not writable, and writes elsewhere fail. `filesystem.host` adds `/srv`, `/mnt`, `/media` and `/boot`. The full sandbox is on [Agent runtime and sandbox](/developers/agent-plugin-deep-dive#sandbox-and-identity). ### Atomicity There is no transaction primitive. For a safe single-file write, write to a `.tmp`, fsync, and rename over the target. For anything needing ACID, use a single JSON file you rewrite atomically or SQLite (`sqlite3` is in the Python standard library). There is only one plugin process, so the only concurrency is your own asyncio tasks. Add a lock if you fan out writes. ### Format guidance * Configuration: JSON or YAML, typed keys. * Time-series: append-only `.jsonl` (one JSON object per line). * Binary: plain files. Many small files beat one large blob for the page cache. * Database: SQLite is fine for non-trivial state. ## Configuration The agent context exposes config two ways. `ctx.config` is the static config dict the host delivered at start. `ctx.config_kv` is the live key-value facade. Its read order is drone scope when bound, then global, then your default: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # Live read and write (async). value = await ctx.config_kv.get("threshold_v", default=3.5) await ctx.config_kv.set("threshold_v", 3.4, scope="drone") # Synchronous read of the static dict the host delivered at start. limit = ctx.config_kv.static("threshold_v", 3.5) ``` `set` defaults to `scope="drone"`; pass `scope="global"` to write the fleet-wide value. On the GCS half, subscribe to changes with `ctx.config.onChange`. ### Per-drone plugins Set `per_drone_config: true` in the `agent:` block of `manifest.yaml` and the host runs one process instance per connected drone, each with its own `ctx.agent_id` and its own scoped `ctx.data_dir`. Read each drone's live settings through `ctx.config_kv` and fall back to the static dict for unset keys: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # manifest.yaml (excerpt) agent: runtime: python entrypoint: "follow_me:FollowMePlugin" isolation: subprocess per_drone_config: true ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: # ctx.agent_id is the bound drone; ctx.data_dir is scoped to it. live = {} for key in ("follow_distance_m", "follow_height_m"): value = await ctx.config_kv.get(key, None) if value is not None: live[key] = value static = dict(getattr(ctx, "config", {}) or {}) self._config = {**static, **live} ``` The Follow-Me extension uses this pattern: live per-drone keys override the static defaults each control loop. A write with the default `scope="drone"` updates only the bound drone; `scope="global"` updates the fleet-wide default the other instances fall back to. ## Cloud records Request the `cloud.records` capability to keep small JSON records in the signed-in operator's cloud account. Records are namespaced to your plugin by the host, so no other plugin can read them. A record body is at most 64 KiB of JSON, and a plugin holds at most 5000 records. The GCS half uses `ctx.records`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} await ctx.records.put("surveys", "field-12", { area_m2: 5400 }, { deviceId }); const one = await ctx.records.get("surveys", "field-12"); const page = await ctx.records.list({ collection: "surveys", limit: 50 }); await ctx.records.remove("surveys", "field-12"); ``` Collection names are 1-64 characters of `[a-z0-9_.-]`. Pass `deviceId` to tie a record to one node, and filter `list` by it. A refused call rejects with a `HostError` whose message is `unavailable` (signed out or offline), `invalid_args`, `too_large`, `limit_reached`, `not_permitted` or `failed`. The agent half writes with the `cloud.records.put` host method under the same grant. Each record carries `writtenBy` (`gcs` or `agent`) and `updatedAt`, so either half can tell who wrote last. ## Cleanup on remove `ados plugin remove `: 1. Disables the plugin if it is running or enabled, which stops its units. 2. Deletes the main unit and any declared service units. 3. Removes the install directory `/var/ados/plugins//` and the install entry from the state file. 4. Unless `--keep-data` is passed, deletes `/var/ados/plugin-data//` (including per-drone subdirectories and `config/` files), the plugin's logs, and its system user. Pass `--keep-data` to keep both the data directory and the logs, so a later install of the same plugin id picks up its prior data. ## Migration between versions Plugins own their own data migrations. There is no SDK migration helper, so carry a small version marker in your data directory and migrate forward on start: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: marker = ctx.data_dir / ".data_version" version = int(marker.read_text()) if marker.exists() else 1 if version < 2: await self._migrate_v1_to_v2(ctx) marker.write_text("2") ``` Handle skipped versions; an upgrade can jump more than one version at once. Forward migration is the contract; reading new data with an older plugin is best-effort. ## What not to put on disk * Secrets you did not generate yourself. The host manages pairing keys, MAVLink session keys and signer keys. * Large media. Anything over a gigabyte belongs in a recording, not the data directory. * Operator personal data without consent. The data directory is not encrypted at rest. ## Next steps > [card] [Versioning and updates](/developers/versioning-and-updates) > > Semver, compatibility ranges, automatic updates and rollback. # Plugin troubleshooting Source: https://docs.altnautica.com/developers/troubleshooting Map plugin failures to CLI exit codes and wire errors, then diagnose them with ados plugin logs, systemctl and journalctl. Most plugin failures fall into a handful of categories: a signature the node does not trust, an invalid manifest, an install the agent refuses, a capability that was not granted, the cgroup killing the process, the IPC socket not coming up, or the GCS iframe trying to reach the network. This page maps each one to what you see and the commands that tell you which one you hit. Every `ados plugin` command exits with a code from the [exit-code table](/developers/cli-reference#exit-codes). Pass `--json` in CI and branch on `.code`, not on the human text. ## Signature and trust failures (exit 3) `ados plugin install` checks the signature before anything is written to disk. The detail text names the cause: * **The archive is unsigned.** A default agent refuses it with `archive is unsigned`. Sign it with `ados plugin sign` or `scripts/sign.sh`. * **The signer is not enrolled.** The node has no `/etc/ados/plugin-keys/.pem` for the signer id in the archive. Install the publisher's public PEM there (the file name must equal the signer id), or re-sign with a key the node already trusts. * **The signer, the archive or the release is revoked.** It is listed in `/etc/ados/plugin-revocations.json` (a release as `@`). A revoked signer, archive or release is refused in every mode. Re-sign with a fresh key, or install a release that is not revoked. * **The signature does not verify under the enrolled key.** The archive changed after signing, the wrong key is enrolled for that signer id, or the archive was signed with a different id than you think. Re-pack and re-sign: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin sign ./my-plugin \ --key ./keys/my-2026-A.priv.pem \ --signer-id my-2026-A \ --output ./dist/my-plugin.adosplug ``` Signature enforcement can only be relaxed on the agent itself, by running its services with `ADOS_PLUGIN_REQUIRE_SIGNED=0` on a bench node. The agent then logs a warning, installs unsigned or unverifiable archives with no signer, and never grants them first-party status. The procedure is in [Bench install and signing](/developers/signing-keys#bench-install-and-signing). ## Manifest validation errors (exit 2) `ados plugin lint`, `sign` and `test` validate `manifest.yaml` against the strict schema and exit 2 on failure; the agent rejects a malformed manifest at install the same way. Common causes: * Neither an `agent:` nor a `gcs:` block. At least one half is required. * A resource bound out of range. `agent.resources.max_ram_mb` must be between 8 and 4096 for the `standard` class (default 96). * A missing required field: `id`, `version`, `name`, `compatibility.ados_version`, `agent.entrypoint`, or `gcs.entrypoint` when the GCS half renders `panels`, `tabs`, `agent_pages` or `node_surfaces`. * A camelCase `contributes` key (`missionTemplates`, `mapOverlays`). Use `mission_templates` and `map_overlays`. An unknown permission id is a warning, not an error: the manifest loads, but the permission grants nothing. Check the spelling against [Permissions](/developers/permissions). Run the linter before you install: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin lint ./my-plugin.adosplug ``` `lint` exits 0 when the report passes and 1 when it carries an error or critical finding. ## Install refusals (exit 4 and exit 8) These manifests parse, but the agent refuses to install them: * `agent.isolation: inprocess` is refused for every plugin (exit 8). Use `subprocess`. * `gcs.isolation: inline` and `agent.resources.class: heavy` are refused unless the archive verifies against a first-party key (exit 4, `refused: ..._first_party_only`). * A board, tier, target profile or architecture the manifest does not cover (exit 8, `incompatible: ...`). `supported_boards` takes board ids or SoCs from [Supported hardware](/drone-agent/supported-hardware), or `"*"`. * `ados plugin install --yes` on a plugin whose `risk` is `high` or `critical` (exit 4, `--yes refuses -risk plugins`). Re-run without `--yes` and approve after review. ## Capability denied at runtime The agent re-resolves the required capability from the method on every request and rejects an ungranted call with `capability_denied: `; the handler never runs. On the GCS half the bridge answers `permission_denied`. This happens when the plugin calls a method whose capability was not granted (an optional permission left off, or one revoked while the plugin ran). Check and fix the grant: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin perms com.example.my-plugin ados plugin perms com.example.my-plugin --grant mavlink.read ``` A revoke takes effect at once, so a running plugin can start seeing `capability_denied` mid-session after an operator revokes a permission. ### Token expiry Tokens rotate without plugin action: the agent re-mints a token ahead of expiry and on expiry within a live session, and Mission Control pushes a fresh token into the iframe, which the SDK caches. A persistent `capability_denied:token_expired` on the GCS half means the host stopped pushing tokens; reload the panel. ## The agent half crashes or restarts Each agent half runs as `ados-plugin--.service` inside the shared `ados-plugins.slice`, with the manifest's bounds: ```ini theme={"theme":{"light":"github-light","dark":"github-dark"}} MemoryMax=M CPUQuota=% TasksMax= ``` Find the exact unit name first; the `` suffix comes from the id: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} systemctl list-units 'ados-plugin-*' --all ``` If the plugin's memory crosses `MemoryMax`, the kernel OOM-kills it and systemd restarts it after 2 s. There is no start limit (`StartLimitIntervalSec=0`), so a crash-looping plugin keeps restarting and stays `running` in the plugin record. CPU is throttled, not killed: crossing `CPUQuota` slows the process, so a CPU-starved plugin looks like latency, not a crash. Read the cgroup accounting to tell an OOM from a throttle: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} systemctl show ados-plugin-com-example-my-plugin-.service -p ControlGroup cat /sys/fs/cgroup//memory.events # oom and oom_kill cat /sys/fs/cgroup//memory.peak # high-water mark cat /sys/fs/cgroup//cpu.stat # nr_throttled, throttled_usec ``` A rising `oom_kill` means raise `agent.resources.max_ram_mb` or shrink the working set. A rising `nr_throttled` means raise `max_cpu_percent` or do less work per tick. ## IPC connect and timeout failures The plugin host (`ados-plugin-host`) binds one Unix socket per plugin at `/run/ados/plugins//host.sock`. The unit passes the path in `ADOS_PLUGIN_SOCKET` and delivers the token as a systemd credential at `$CREDENTIALS_DIRECTORY/ados-plugin-token`, never in the environment. The runner connects, sends a `hello` handshake with the token, and only then issues requests. The unit has `Requires=ados-plugin-host.service` and `PartOf=ados-supervisor.service`. * **Socket missing or connection refused.** The plugin host is not serving that plugin yet. The runner keeps retrying, and systemd restarts it with no start limit. Check the host and the socket dir: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} systemctl status ados-plugin-host.service ls -l /run/ados/plugins/com.example.my-plugin/ ``` * **Handshake rejected.** The server closes the connection with `capability token invalid: ` when the token does not verify or names another plugin. The host rewrites the credential on every start, so a restart of the unit picks up a fresh one. * **Host method not ready.** A request for a subsystem that has not come up yet (for example the flight controller link) returns a not-ready error rather than data. Retry once the subsystem reports ready. ## GCS iframe blocked from the network The GCS half runs in `sandbox="allow-scripts"` with no `allow-same-origin`, on a document whose CSP has `connect-src 'none'`. WebRTC and nested frames are removed. So: * A `fetch()`, WebSocket or peer connection from the panel fails with a CSP violation or a missing constructor. Route the work through a bridge method (`command.send`, `mission.write`, `cloud.read`, `records.*`) or through your plugin's agent half. * The iframe cannot read `window.parent`, `localStorage` or the host `document`. Anything you need from Mission Control comes over the bridge under a granted capability. When a GCS panel renders blank, open the devtools console for that iframe and rule out, in order: a CSP block, a `capability_denied` or `permission_denied` from the bridge, and a throw in `mount` (the SDK does not report it to the host, so render your own error state). ## Diagnostic commands **1. Read the plugin's own log** The agent half writes stdout and stderr to `/var/log/ados/plugins/-.log`. `ados plugin logs` asks the agent for that path and reads it: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin logs com.example.my-plugin # last 100 lines ados plugin logs com.example.my-plugin --lines 500 ados plugin logs com.example.my-plugin --follow # like tail -f ados plugin logs com.example.my-plugin --service worker ``` An exit 5 with `no log file at ...` means the plugin never started, or its log was rotated out. Move to the unit status next. **2. Inspect install state and grants** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin info com.example.my-plugin ados plugin perms com.example.my-plugin ados plugin list --all ``` A `DENIED` permission explains a runtime `capability_denied`. A `disabled` plugin with a recorded reason was disabled by a revocation. **3. Read the systemd unit** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} systemctl list-units 'ados-plugin-*' --all systemctl status ados-plugin-com-example-my-plugin-.service systemctl cat ados-plugin-com-example-my-plugin-.service ``` `status` shows the last exit reason and the restart count. `cat` shows the generated unit with its bounds and sandbox. **4. Pull the journal** For crashes before the plugin can log, or the plugin host's view of the start: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} journalctl -u ados-plugin-com-example-my-plugin-.service -n 200 --no-pager journalctl -u ados-plugin-host.service -n 200 --no-pager ``` A `Killed process ... (oom)` line confirms an OOM. **5. Query the Black Box store** When the Black Box store (`ados-logd`) is enabled, query across the whole agent to correlate a plugin failure with the rest of the node: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados logs query --since -10m --text com.example.my-plugin ados logs query --kind events --since -1h ``` The store is off by default; without it, use `journalctl -o json`. See [Black Box](/drone-agent/black-box). ## Next steps > [card] [Plugin CLI reference](/developers/cli-reference) > > Every command and the exit-code table. > [card] [Performance and budgets](/developers/performance-and-budgets) > > Sizing `max_ram_mb` and `max_cpu_percent`. > [card] [Signing keys](/developers/signing-keys) > > Generate, enrol and rotate publisher keys. > [card] [Troubleshooting by area](/operations/troubleshooting) > > Every troubleshooting page across ADOS. # Vendor binaries Source: https://docs.altnautica.com/developers/vendor-binaries Ship a closed-source library, a spawned helper or per-architecture binaries inside a plugin archive. Hardware drivers sometimes need a closed-source library to talk to the device: a camera SDK, a LiDAR decompressor, a mount-control library. A plugin can include these binaries, but the manifest must declare the inclusion so operators see it in the install review. ## Declare the vendor binary The agent half sets `contains_vendor_binary: true` and provides `vendor_attribution`. The two go together: the schema rejects one without the other. Both fields arrived in schema version 2; set `schema_version: 2` or later to mark the manifest generation. `vendor_attribution` is a list, so a plugin can attribute more than one upstream: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} schema_version: 2 agent: runtime: python entrypoint: "agent/src/example_plugin/plugin.py" contains_vendor_binary: true vendor_attribution: - name: "ExampleVIO" license: "GPL-3.0-only" source_url: "https://example.com/examplevio" upstream_version: "v1.0" notice: "The VIO mode uses the ExampleVIO estimator." ``` There is no per-binary `path` or `sha256` field. The archive's `SIGNATURE` covers every entry's hash, so the vendor binary is protected by the same signature as the rest of the archive. `license` is the only required attribution field; the rest are optional provenance (`name`, `source_url`, `source_offer_url`, `upstream_repo`, `upstream_version`, `commit_sha`, `notice`). For a GPL-compatible upstream, set at least one of `source_url` or `source_offer_url` plus a version pin (`upstream_version` or `commit_sha`) so the install review can show a real source offer. `ados plugin lint` reports `VND001` when `contains_vendor_binary` is set, as a reminder to check the attribution. See [Linting](/developers/linting). ## Trust signal in the install review When `contains_vendor_binary` is true, the install review in Mission Control shows the vendor attribution and labels the plugin as carrying a vendor binary. The operator can still install. ## Loading a library in-process The agent unpacks the archive under `/var/ados/plugins//`. Resolve the library relative to your plugin module and load it with `ctypes`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import ctypes from pathlib import Path class FooDriver: def __init__(self) -> None: sdk_path = Path(__file__).parent / "vendor" / "libfoo.so" self._lib = ctypes.CDLL(str(sdk_path)) ``` The library runs inside the plugin's sandbox and cannot exceed the plugin's permissions. A vendor library that opens a USB camera still needs the plugin to declare `hardware.usb.uvc`. Nothing checks that an in-process `.so` matches the board's architecture. If your plugin runs on more than one, ship one subfolder per architecture and pick at runtime: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} agent/src/example_plugin/vendor/ ├── aarch64/ │ └── libfoo.so └── x86_64/ └── libfoo.so ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import platform from pathlib import Path arch = platform.machine() sdk_path = Path(__file__).parent / "vendor" / arch / "libfoo.so" ``` ## Running vendor code as a separate process If the vendor code must run as its own process, the plugin needs the `process.spawn` capability (risk high) plus a `subprocess_spawn` allowlist. Entries are binary basenames, not paths. Any `ctx.process.spawn(...)` whose basename is not on the list is refused, and the manifest fails validation if `subprocess_spawn` is set without `process.spawn` in `permissions`. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: process.spawn subprocess_spawn: - example_vendor_shim ``` Each basename resolves to `/vendor/`. The archive is extracted verbatim, so ship spawned binaries at top-level `vendor/` in the archive; they land at `/var/ados/plugins//vendor/`. Shell metacharacters and path traversal in a basename are refused. ## Per-architecture binaries A Rust agent half declares its compiled binaries per architecture in `agent.binaries`, a map of `{: {-: }}`. The supported keys are `aarch64-linux`, `x86_64-linux` and `aarch64-macos`. `bin:` in `agent.entrypoint` or a service command resolves through the table on the installing host. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: runtime: rust entrypoint: "bin:example-link" binaries: example-link: aarch64-linux: bin/aarch64-linux/example-link x86_64-linux: bin/x86_64-linux/example-link ``` A `bin:` entrypoint requires `agent.runtime: rust` and a matching `binaries` entry. When the table has no entry for the node's `-`, install is refused with `incompatible: no binary for `. Every manifest field is in the [manifest reference](/developers/manifest). ## License note A plugin that wraps a closed-source vendor library stays under the license it declares for its own source files. The install review flags the vendor binary separately. See [Legal and licensing](/developers/legal-and-licensing) for how the SDK licences interact with your own. ## Next steps > [card] [Manifest reference](/developers/manifest) > > The full `agent` block. > [card] [Local install](/developers/distribution-local-install) > > Pack, sign and install the archive. > [card] [Legal and licensing](/developers/legal-and-licensing) > > Licences and vendor binaries. # Versioning and updates Source: https://docs.altnautica.com/developers/versioning-and-updates Semver discipline, compatibility ranges, automatic updates, rollback, and additive versus breaking permission changes. A plugin lives across many host versions and many of its own versions. Semver gives operators a way to predict what an upgrade will and will not change, and the agent's automatic updates rely on it. ## Semver for plugins Use `MAJOR.MINOR.PATCH`: | Bump | When | | - | - | | PATCH | Bug fixes. No new features, no behavior changes operators would notice. | | MINOR | Additive features. New optional permissions are fine; new required permissions are not. New slot contributions, new patterns, new drivers. | | MAJOR | Breaking changes. Removed features, renamed config fields, new required permissions, changed default behavior. | The rule of thumb: an operator running an old config on a new MINOR version should see a working plugin. A new MAJOR version warrants reading the changelog. ## Compatibility ranges The manifest declares which host versions it supports: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} compatibility: ados_version: ">=0.10.0,<1.0.0" gcs_version: ">=0.5.0,<1.0.0" supported_boards: [] ``` The host parses each range as comma-separated atoms, where every atom is an operator followed by a semver: | Operator | Meaning | | - | - | | `=1.2.3` or `==1.2.3` | Exact match. | | `>=1.2.3` | At least 1.2.3. | | `<=1.2.3` | At most 1.2.3. | | `>1.2.3` | Strictly above 1.2.3. | | `<2.0.0` | Strictly below 2.0.0. | Combine atoms with a comma (logical AND): `">=0.10.0,<1.0.0"`. A bare semver with no operator means exact match. Pre-release and build suffixes are stripped before comparison, so `1.2.3-rc.1` compares as `1.2.3`. Caret (`^`) and tilde (`~`) shorthand are not supported; write the bounds out. `supported_boards` is an exact board-id list. An empty list, an absent field or `["*"]` means any board. To restrict the plugin, list the board ids it runs on; the ids are on [Supported hardware](/drone-agent/supported-hardware). The compatibility check runs at install time. If the running agent version is outside `ados_version`, the install (or the install of a newer archive over an existing plugin) is rejected. Mission Control checks `gcs_version` against its own build. ## `ados_version` vs `gcs_version` `ados_version` matches the running ADOS Drone Agent version. `gcs_version` matches the running Mission Control build. They move independently, so a plugin can support a wide agent range and a narrow GCS range or the reverse. The `compatibility` block and its `ados_version` field are required on every manifest, even for a GCS-only plugin; set a wide range if the plugin does not depend on a specific agent. `gcs_version` is optional; omit it for an agent-only plugin. ## Manual update 1. The operator installs a newer `.adosplug` over the installed plugin. 2. The host parses the archive and checks the signature, compatibility and board. A failing check rejects the update and leaves the old version running. 3. Grants the new version still declares carry over, permissions it no longer declares are dropped, and a newly requested permission starts ungranted until the operator approves it. 4. The host stops the running plugin, replaces the install directory, re-renders the units and starts the new version. 5. On start the lifecycle hooks run in order (`on_install`, `on_enable`, `on_configure`, `on_start`). Read your live config through `ctx.config_kv` and migrate your data directory if needed. The install methods are on [Local install](/developers/distribution-local-install). ## Automatic updates Once a day the agent compares every enabled plugin with the newest version the registry publishes and does one of the following: * **Installs it silently** when the update is a patch or minor bump with an unchanged permission set and code surface, still supports the board, and is signed by the same key as the installed version. It goes through the normal install checks; prior grants are restored and the plugin is re-enabled. A refused archive leaves the old version in place. * **Notifies the operator** for a major bump, a permission change, a change to what the plugin can run (risk, declared services, spawn allowlist, binaries, payload files), a dropped board, or a different signer. The operator decides. A signer change is refused as an update; it needs a remove and a fresh install. * **Skips it** when the plugin is pinned, auto-update is off for it, or nothing newer exists. The whole cycle is deferred while the vehicle counts as armed (unknown or stale state counts as armed), because an update stops the plugin. Control it per plugin: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin pin com.example.battery 1.4.2 # stay on this version ados plugin unpin com.example.battery ados plugin auto-update com.example.battery off ``` To get silent updates, keep patch and minor releases additive and sign every release with the same key. ## Additive vs breaking permission changes Additive (MINOR safe): * Adding an optional permission. * Adding a slot contribution. * Adding a config field with a default value. Breaking (MAJOR required): * Adding a required permission. * Removing a slot the operator depends on. * Renaming a config field without a migration. * Changing the wire format of a `plugin..*` event topic. * Changing default behavior in a way the operator would notice. Any permission change, additive or not, turns an automatic update into a notification. ## Config migration Carry a `version` field in your config and migrate forward inside `on_configure`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_configure(self, ctx, new_config): if new_config.get("version", 1) < 2: new_config["new_field"] = derive_from_old(new_config["old_field"]) new_config.pop("old_field", None) new_config["version"] = 2 await ctx.config_kv.set("config", new_config, scope="drone") ``` ## Data migration There is no SDK migration helper. Carry a version marker in your data directory and migrate forward on start, handling skipped versions: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx): marker = ctx.data_dir / ".data_version" v = int(marker.read_text()) if marker.exists() else 1 if v < 3: if v < 2: await self.migrate_v1_to_v2(ctx) await self.migrate_v2_to_v3(ctx) marker.write_text("3") ``` Forward migration is the contract; reading new data with an older plugin is best-effort. ## Rollback Installing an older version over a newer one is refused (rollback protection). To roll back: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin remove com.example.battery --keep-data ados plugin install ./com.example.battery-1.3.0.adosplug ``` Without `--keep-data` the data directory is deleted. With it, your older version reads data a newer version may have migrated, so your code has to tolerate that. Pin the plugin afterwards if auto-update would otherwise bring the newer version back. ## Pre-release versions Pre-releases use semver pre-release identifiers (`1.0.0-rc.1`). Treat a pre-release as older than its equivalent release, so `1.0.0` supersedes `1.0.0-rc.1`. Do not ship `-rc` builds to operators who did not ask for them; the local-install path accepts one. ## Communicating breaking changes A MAJOR version is contract-breaking. Add a migration section to the README, optionally ship a one-shot migration that imports old state into the new format, and raise `ados_version` if the change needs a newer host. The host does not detect lost user data on upgrade; that responsibility is the plugin author's. ## Next steps > [card] [Local install](/developers/distribution-local-install) > > Install and update a packed archive on a node. > [card] [Performance and budgets](/developers/performance-and-budgets) > > Resource caps, throttling and profiling. # Vision plugins Source: https://docs.altnautica.com/developers/vision-plugins Subscribe to engine frames over the shared frame bus, register or run inference models, and publish detections. The agent ships a **vision engine**: a host service that owns the camera(s), captures and normalizes frames, and publishes them on a shared frame bus that plugins read. A vision plugin does not open the camera itself. It subscribes to the normalized frame stream, runs (or asks the engine to run) inference, and publishes detections that overlays and mission logic pick up. This is a host-owned bus, not a per-plugin capture loop. The engine arbitrates the camera and the accelerator across every vision consumer, so two plugins can watch the same camera without fighting over the device or the NPU. The operator manages vision models and watches detections on the drone's **Perception** page in the node's Agent sidebar. ## The frame contract The engine downscales and converts each camera's native format to a normalized frame, writes the pixels into a shared-memory ring (one ring per camera), and publishes a small **frame descriptor** on the `vision.frame` topic. The pixels never ride the RPC envelope. Your SDK resolves a descriptor to pixels for you by mapping the named ring read-only and reading the slot the descriptor points at. A resolved `Frame` carries the descriptor plus the pixel bytes. Descriptor fields: | Field | Meaning | | - | - | | `frame_id` | Monotonic frame counter for this camera, starting at 1. | | `ts_ms` | Capture time in milliseconds. | | `width`, `height` | Frame dimensions. | | `format` | `"rgb24"`, `"nv12"`, or `"yuv420p"`. | | `camera_id` | Source camera id, for filtering. | The `Frame` also gives you the pixel bytes: `len(pixels)` equals the descriptor's `byte_len`, the valid pixel data for `width` x `height` in `format`. Default working resolution is 640x480; the engine downscales further per the active model's input size. Drop policy is **latest-wins**: a slow consumer drops frames, it never blocks the engine. A torn or stale read (the writer recycled the slot mid-copy) is dropped silently and your callback does not fire for it. ### Subscribing to frames In Python, `ctx.vision` is a `VisionClient`. Subscribe with a callback that runs once per resolved frame: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} class MyPlugin: async def on_start(self, ctx) -> None: async def on_frame(frame): # frame.descriptor.width, .height, .format, .camera_id, .ts_ms # frame.pixels is the resolved bytes for this frame detections = self.run(frame) for d in detections: ... await ctx.vision.subscribe_frames(on_frame) ``` `subscribe_frames` is gated on `vision.frame.read`. The callback may be sync or async. Keep it cheap: it runs on the delivery path, so offload heavy inference to a task or queue rather than blocking in the callback. The Rust SDK is the same surface: `ados_sdk::vision::VisionClient`, reached via `ctx.vision`, with `subscribe_frames(camera_id, callback)` and the same `Frame` shape. Types come from `ados_sdk` re-exports backed by `ados_protocol::framebus`, so a Python plugin and a Rust plugin read the same wire byte for byte. A Rust plugin's entry point is `ados_sdk::run_plugin::(...)`. ## Running inference There are two paths, and a plugin can use either. Both share the same accelerator, which the engine arbitrates. **Engine-run.** Register a model file plus its metadata with the engine. The engine loads it, runs it on the shared backend, and publishes detections itself. Your plugin only declares the model and then consumes detections like any other consumer. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.vision import ( ModelMetadata, ModelKind, ModelExecution, FrameFormat, ) await ctx.vision.register_model(ModelMetadata( id="com.example.weeds", kind=ModelKind.DETECTION, execution=ModelExecution.ENGINE_RUN, input_width=640, input_height=480, input_format=FrameFormat.RGB24, output_classes=["weed", "crop"], model_path="/path/on/agent/weeds.onnx", )) ``` `register_model` is gated on `vision.model.register`. **Plugin-side.** Run your own model in the plugin and publish the results. You can also ask the engine to run a registered model against one frame on the shared backend with `ctx.vision.infer(model_id, frame)`, which returns the detections without pixels crossing the RPC envelope. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_frame(frame): boxes = self.session.run(frame) # your own runtime await ctx.vision.publish_one( "com.example.weeds", frame, Detection( bbox=BoundingBox(x=100, y=80, width=40, height=40), class_label="weed", confidence=0.91, ), ) ``` The accelerator is shared. A heavy or runaway model starves other vision consumers, so register honest input sizes and keep your inference cadence below your CPU and NPU budget. On boards with an NPU, load the board's accelerator runtime (TFLite delegates, RKNN and so on) instead of running on the CPU. ## Detections A `Detection` has: * `bbox`: pixel-space box `{x, y, width, height}`, origin top-left, in the frame's own resolution. * `class_label`: the class string. * `confidence`: the model's score. * `track_id`: optional stable id across frames, for tracking models. Detections are published as a `DetectionBatch` on the `vision.detection` topic, labelled by `model_id` plus the source `camera_id`, `frame_id`, and `ts_ms` so a consumer can align the boxes to the exact frame they came from. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await ctx.vision.publish_detection(DetectionBatch( model_id="com.example.weeds", camera_id=frame.descriptor.camera_id, frame_id=frame.descriptor.frame_id, ts_ms=frame.descriptor.ts_ms, detections=[...], )) ``` `publish_detection` (and the `publish_one` convenience) are gated on `vision.detection.publish`. Built-in consumers, the video overlay and mission logic, pick the batches up. The Rust SDK exposes the same `publish_detection` / `publish_one` on `VisionClient`. ### Consuming detections A plugin that acts on detections, rather than producing them, subscribes to the batches the engine publishes. The callback receives a `DetectionBatch`; pass `camera_id` to filter to one camera: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def on_start(self, ctx) -> None: async def on_batch(batch) -> None: for d in batch.detections: self.track(d.class_label, d.bbox, d.track_id) await ctx.vision.subscribe_detections(on_batch, camera_id="uvc-0") ``` `subscribe_detections` is gated on `vision.detection.subscribe`. ### Designating a follow target The engine runs one single-object tracker per camera. `designate_track` sets the box it locks onto, overriding the auto-lock, the same way an operator's click-to-follow does: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.vision import BoundingBox result = await ctx.vision.designate_track( "uvc-0", BoundingBox(x=310, y=200, width=60, height=90), class_label="person", ) # result: {"designated": bool, "track_id": int | None, "camera_id": "uvc-0"} ``` `designate_track` is gated on `vision.track.designate`. Designation alone does not command the vehicle; a follow behavior that flies toward the target uses [guided setpoints](/developers/mavlink-extensions#guided-setpoints). ## Capabilities Declare the ones you use under `agent.permissions` in the manifest. Risk levels are on [Permissions](/developers/permissions). | Capability | What it grants | | - | - | | `vision.frame.read` | Subscribe to normalized engine frames. The plugin never opens the camera itself. | | `vision.model.register` | Register an inference model and run `infer` against shared frames. | | `vision.model.read` | Read the delivery status and cached path of the plugin's own declared models. | | `vision.detection.publish` | Publish detections that overlays and mission logic consume. | | `vision.detection.subscribe` | Receive detection batches through `ctx.vision.subscribe_detections`. | | `vision.track.designate` | Set the engine's follow target through `ctx.vision.designate_track`. | | `vision.offload.advertise` | Report the perception offload link the plugin holds to a paired compute node. The agent counts the node as paired only when the advertised address answers. | ## A worked extension: Vision Navigation The first-party Vision Navigation extension (`vision-nav`) is a reference for frame-bus work. It provides GPS-denied position hold from optical flow: a Rust agent half reads engine frames (`vision.frame.read`) and emits the flow message the configured firmware fuses over MAVLink (`OPTICAL_FLOW` for ArduPilot and iNav, `OPTICAL_FLOW_RAD` for PX4, plus `DISTANCE_SENSOR` when a rangefinder is wired to the companion). It supports ArduPilot 4.5+, PX4 1.14+ and iNav 7.0+. It does not inject pose through the visual-odometry helpers. Look at `extensions/vision-nav/` in the ADOSExtensions repository for a real `manifest.yaml`, config schema and agent/GCS split. Operator setup is in [Vision Navigation](/drone-agent/extensions-catalog#vision-navigation). ## Multiple cameras When more than one camera is attached, the engine publishes a separate ring and descriptor stream per camera. Filter to the one you want by passing `camera_id`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} await ctx.vision.subscribe_frames(on_frame, camera_id="uvc-0") ``` The Rust equivalent passes `Some("uvc-0")` for the `camera_id` argument. A `None` filter receives every camera's frames; tag your detections with the frame's `camera_id` so consumers know which camera each box came from. ## Testing Exercise the frame and detection path without a real host, engine, shared memory, or socket using the real test harness. The fake builds a real frame ring through the same frame-transport contract and resolves each synthetic frame the way the production client does, so your frame-handling path runs end to end; only the host and the OS shared-memory object are faked. In Python, use `ados.sdk.testing.FakeVisionEngine`: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from ados.sdk.testing import FakeVisionEngine from ados.sdk.vision import FrameFormat async def test_my_plugin(): engine = FakeVisionEngine("uvc-0", 64, 48, FrameFormat.RGB24) seen = [] engine.on_frame(lambda frame: seen.append(frame)) engine.push_solid(0x80) # one flat-grey frame await engine.deliver_all() assert len(seen) == 1 ``` For an end-to-end run through the real `VisionClient` (the ring lives in a temp directory the client maps read-only, and the descriptor rides a real delivery event into the client's resolver), build the engine with a file-backed ring and `attach` your callback: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} engine = FakeVisionEngine.with_shm_dir("uvc-0", 64, 48, FrameFormat.RGB24) await engine.attach(on_frame) await engine.deliver_all() ``` Detections your plugin publishes are captured via `engine.captured_detections()`. The Rust harness mirrors this: `ados_sdk::testing::FakeVisionEngine` emits synthetic frames into the same `FrameCallback` your plugin registers and captures the detection batches it publishes. ## Shipping models A plugin gets its model weights onto the node in one of three ways. **Bundled in the archive.** Place the file under the plugin tree (for example `agent/models/weeds.onnx`). The archive's `SIGNATURE` covers every entry, so the weights are protected by the same signature as the rest of the plugin. For an engine-run model, pass the file's path as `model_path` on the model metadata. **By reference.** Declare the model under `agent.contributes.vision.models`. The agent fetches it, verifies it against the pinned `sha256` and caches it. The digest sits in the signed manifest, so a fetched model is as trusted as a bundled one: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} agent: permissions: - id: vision.model.read contributes: vision: models: - id: weeds-detector runtime: rknn # onnx | rknn | hailo | tflite | pytorch board_match: rk3588 # board family this variant targets; default generic sha256: "<64 hex chars>" source: "https://models.example.com/weeds-rk3588.rknn" ``` The plugin reads where each model landed through the `vision.read_model` host method, gated on `vision.model.read`. It returns one entry per declared model with `state` (`resolved`, `needs-model` or `verify-failed`), `model_id`, `runtime`, `path` when resolved, and `reason` otherwise. In Rust it is `vision_read_model()` on the SDK client. **As an install payload.** `agent.payloads` lists files the agent downloads at install instead of shipping them in the archive. Each entry pins `path` (archive-relative destination), `source` (an `https://` URL on the download allowlist), `sha256` and `size_bytes`, and can narrow to node `profiles` or an `arch_os`. See [Manifest](/developers/manifest). Do not fetch weights yourself at runtime; the plugin's `network.outbound` policy blocks that by default. ## Vendor binary models Closed-source vendor binaries (for example, proprietary thermal AGC processing as a `.so`) ship under `vendor/` per the [vendor binaries](/developers/vendor-binaries) doc. The plugin loads them with `ctypes` or `cffi` and calls them from its own inference path, then publishes the results as a `DetectionBatch` like any other plugin-side model. ## Next steps > [card] [MAVLink extensions](/developers/mavlink-extensions) > > Send results to the flight controller and inject visual odometry. > [card] [Performance and budgets](/developers/performance-and-budgets) > > CPU, memory and accelerator limits for vision workloads. > [card] [State and storage](/developers/state-and-storage) > > Where a plugin keeps data on the node. > [card] [Permissions](/developers/permissions) > > Every capability and its risk level. # Your first plugin Source: https://docs.altnautica.com/developers/your-first-plugin Scaffold, test, sign and install a GCS-only node-detail tab that prints a drone's battery pack voltage. This walkthrough builds `com.example.hello-panel`, the smallest useful plugin: a GCS-only tab on a drone's node-detail panel that subscribes to the host's battery telemetry and prints the pack voltage. There is no agent half. The plugin runs inside Mission Control in a sandboxed iframe, and the drone's agent stores and serves it. By the end you have a manifest the host accepts, a bundle that mounts, a unit test that runs without Mission Control, and a signed `.adosplug` installed on a drone. > [!NOTE] > > Battery health (per-cell analysis, sag detection, time-to-reserve and > alerts) is built into the Drone Agent. See > [Battery health](/drone-agent/battery-health). This tutorial uses the > battery topic only because every drone publishes it. ## Prerequisites * Node.js 20+ and pnpm 9+. * bash with `rsync` and `zip` for `scripts/pack.sh` (Linux or macOS; on Windows use WSL). * Python 3.11+ with the `cryptography` package, for signing. * Mission Control connected to a drone that runs the ADOS Drone Agent, and root access on that drone to enrol your signing key. Demo mode does not install extensions. ## 1. Clone and scaffold The SDK and the `create-ados-plugin` scaffolder live in the [`altnautica/ADOSExtensions`](https://github.com/altnautica/ADOSExtensions) monorepo. Neither is published to npm, so develop the plugin as a workspace member there: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/altnautica/ADOSExtensions.git cd ADOSExtensions pnpm install pnpm --filter @altnautica/plugin-sdk build node packages/create-ados-plugin/bin/cli.mjs \ --target extensions/hello-panel \ --id com.example.hello-panel \ --half gcs-only \ --author "Your Name" \ --signer my-publisher-2026-A pnpm install ``` Inside the workspace the scaffolder pins `@altnautica/plugin-sdk` to `workspace:^`, so the plugin builds against the SDK in the tree. The GCS-only template lays out: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} extensions/hello-panel/ ├── manifest.yaml ├── package.json ├── README.md ├── CHANGELOG.md ├── .gitignore ├── locales/en.json └── gcs/ ├── package.json ├── tsconfig.json └── src/plugin.ts ``` The generated `gcs/src/plugin.ts` mounts a one-line greeting from the locale bundle: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; definePlugin({ id: "com.example.hello-panel", version: "0.1.0", async mount(ctx) { const root = document.body; root.style.background = "var(--bg, #0c0c0c)"; root.style.color = "var(--fg, #e6e6e6)"; root.style.font = "12px system-ui, sans-serif"; root.style.padding = "12px"; root.textContent = ctx.i18n.t("hello.title"); }, }); ``` The next steps replace it with a battery tab. ## 2. Manifest Replace the generated `manifest.yaml` with: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} schema_version: 1 id: com.example.hello-panel name: "Hello Panel" version: "0.1.0" description: "Prints the drone's battery pack voltage in a node-detail tab." author: "Your Name" license: "GPL-3.0-or-later" risk: low compatibility: ados_version: ">=0.10.0" gcs_version: ">=0.5.0" supported_boards: ["*"] gcs: entrypoint: "gcs/plugin.bundle.js" isolation: iframe permissions: - id: ui.slot.node-detail-tab - id: telemetry.subscribe.battery contributes: tabs: - id: hello-tab slot: node.detail.tab profile: ["drone"] title: "Hello" icon: "battery" order: 90 locales: - en ``` What each part does: * **No `agent` block.** A manifest needs at least one half; this one ships only the GCS half, so no process runs on the drone. The agent still checks `compatibility` and stores the bundle. * **`tabs`** mounts the bundle as a tab on the node-detail panel. A tab always lives in the `node.detail.tab` slot. `profile: ["drone"]` offers it on drones only; leave `profile` out to offer it on every node profile. * **`ui.slot.node-detail-tab`** lets the tab mount. Every visual contribution needs its matching `ui.slot.*` permission, or the slot skips it. * **`telemetry.subscribe.battery`** is the topic-scoped telemetry grant. The bridge checks it on every subscribe to the `battery` topic; the bare `telemetry.subscribe` grants no stream. * **`risk: low`**: the plugin reads telemetry and draws a tab. It sends no commands and stores nothing. See [Contribution points](/developers/contribution-points) for every contribution kind and [Permissions](/developers/permissions) for the capability catalog. ## 3. The panel Keep the logic in its own module so it can be tested without a browser. Create `gcs/src/panel.ts`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import type { BatterySample, PluginContext } from "@altnautica/plugin-sdk"; export function formatPack(sample: BatterySample): string { return `Pack ${sample.packId}: ${sample.totalVoltageV.toFixed(2)} V`; } export async function mountPanel( ctx: PluginContext, el: HTMLElement, ): Promise<() => void> { el.textContent = "Waiting for battery telemetry"; return ctx.telemetry.subscribe("battery", (sample) => { el.textContent = formatPack(sample); }); } ``` `ctx.telemetry.subscribe` asks the host to open the `battery` stream for the drone the tab is mounted on. It resolves with an unsubscribe function once the host accepts the subscription. If the grant is missing, the promise rejects and no handler is left behind. Every frame on the `battery` topic is a `BatterySample`: | Field | Type | Notes | | - | - | - | | `timestampMs` | number | Sample time in milliseconds. | | `packId` | number | Battery instance reported by the flight controller. | | `cellVoltagesV` | number\[] | Empty when the flight controller does not report cells. | | `totalVoltageV` | number | Pack voltage. | | `currentA` | number or null | | | `consumedAh` | number or null | | | `remainingPercent` | number or null | | | `temperatureC` | number or null | | | `cellCount` | number or null | | Values the flight controller does not report arrive as `null`. ## 4. The entry point Replace `gcs/src/plugin.ts` with: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { definePlugin } from "@altnautica/plugin-sdk"; import { mountPanel } from "./panel"; definePlugin({ id: "com.example.hello-panel", version: "0.1.0", async mount(ctx) { const el = document.createElement("div"); el.style.font = "14px system-ui, sans-serif"; el.style.padding = "12px"; document.body.appendChild(el); await mountPanel(ctx, el); }, }); ``` `definePlugin` is the only call a plugin module must make. The host loads the bundle inside the tab's iframe, and the SDK calls `mount` with a `PluginContext` wired to the host bridge. When the tab closes or the operator switches node, Mission Control destroys the iframe, which ends the subscription with it. See [Lifecycle](/developers/lifecycle) for the teardown rules. ## 5. Test without a host The SDK ships a synthetic host at `@altnautica/plugin-sdk/harness`. It runs the plugin against an in-memory transport and lets you push telemetry frames by hand. Create `gcs/src/panel.test.ts`: ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { describe, expect, it } from "vitest"; import { createPluginHarness } from "@altnautica/plugin-sdk/harness"; import { mountPanel } from "./panel"; describe("hello panel", () => { it("prints the pack voltage", async () => { const el = { textContent: "" } as HTMLElement; const harness = createPluginHarness({ grantedCapabilities: ["telemetry.subscribe.battery"], mount: async (ctx) => { await mountPanel(ctx, el); }, }); await harness.start(); harness.pushTelemetry("battery", { timestampMs: 0, packId: 0, cellVoltagesV: [4.1, 4.1, 4.1, 4.12], totalVoltageV: 16.42, currentA: null, consumedAh: null, remainingPercent: null, temperatureC: null, cellCount: 4, }); expect(el.textContent).toBe("Pack 0: 16.42 V"); await harness.teardown(); }); }); ``` Run it from the GCS package: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd extensions/hello-panel/gcs pnpm test ``` The harness gates most calls by capability like the host, but it does not gate telemetry subscriptions, so this test passes even without the grant. To check the capability your plugin claimed, assert on `harness.calls`: each entry records the method and the capability. ## 6. Pack From the monorepo root: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} scripts/pack.sh hello-panel ``` `pack.sh` builds the GCS bundle (esbuild into `gcs/plugin.bundle.js`), checks that every entrypoint the manifest declares is present, and zips the result into `extensions/hello-panel/dist/com.example.hello-panel-0.1.0.adosplug`. The name comes from the manifest `id` and `version`. ## 7. Sign and enrol your key A default agent installs only archives signed by a key it trusts. Create a key once, sign the archive, and enrol the public key on the drone: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin keygen my-publisher-2026-A --output-dir keys ADOS_SIGNING_KEY=keys/my-publisher-2026-A.priv.pem \ ADOS_SIGNING_KEY_ID=my-publisher-2026-A \ scripts/sign.sh extensions/hello-panel/dist/com.example.hello-panel-0.1.0.adosplug ``` `sign.sh` writes `com.example.hello-panel-0.1.0.signed.adosplug` next to the input, with a `SIGNATURE` entry: the signer id, then the base64 Ed25519 signature over the canonical payload hash. Copy `keys/my-publisher-2026-A.pem` to `/etc/ados/plugin-keys/` on the drone (root). Keep the `.priv.pem` out of git. Where to run `keygen`, how to enrol the key on a node, and the bench-only unsigned mode are covered in [Bench install and signing](/developers/signing-keys#bench-install-and-signing). ## 8. Install In Mission Control, open the drone from the fleet, switch to its **Extensions** tab, and choose **Install from file**. Drop in `com.example.hello-panel-0.1.0.signed.adosplug`. The review shows the signer, the board compatibility and the two permissions; choose **Install**, which reads grants 2 permissions. The **Hello** tab appears on the drone's node-detail panel and updates with every battery frame. On the drone itself, `ados plugin install` does the same from a shell: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ados plugin install ./com.example.hello-panel-0.1.0.signed.adosplug ``` ## What just happened 1. The agent parsed the archive in memory, verified the signature against your enrolled key, checked `compatibility`, and returned a preview. Nothing was written yet. 2. After you approved, the agent unpacked the archive, recorded the install, and granted the two permissions. 3. Mission Control fetched the bundle from the agent, mounted an `