Crate ados_protocol

Expand description

§ados-protocol

Wire contracts for the ADOS Drone Agent: length-prefixed IPC framing, plugin RPC envelope and capability tokens, the vision frame bus, MSP and MAVLink helpers.

The ADOS Drone Agent is a set of cooperating processes that talk over a small number of fixed wire formats. This crate implements each of those formats once, so any Rust program (a plugin, a tool, a test harness or another service) speaks byte-for-byte the same wire as the agent. Reach for it when you need to read or write agent IPC frames directly; to write a plugin, start with ados-sdk, which builds on it.

use ados_protocol::frame::{decode_len, HEADER_SIZE, PLUGIN_MAX_FRAME};
use ados_protocol::plugin::{Envelope, PROTOCOL_VERSION};

let request = Envelope {
    version: PROTOCOL_VERSION,
    kind: "request".into(),
    method: "ping".into(),
    capability: String::new(),
    args: rmpv::Value::Map(vec![]),
    request_id: "r1".into(),
    token: String::new(),
    error: None,
};

// A complete frame: 4-byte big-endian length, then the msgpack body.
let wire = request.encode_frame().unwrap();
let header: [u8; HEADER_SIZE] = wire[..HEADER_SIZE].try_into().unwrap();
let len = decode_len(header, PLUGIN_MAX_FRAME, true).unwrap();
assert_eq!(len, wire.len() - HEADER_SIZE);

let decoded = Envelope::from_msgpack(&wire[HEADER_SIZE..]).unwrap();
assert_eq!(decoded, request);

§Highlights

One implementation of every agent wire contract, shared by the agent’s own Rust services and by third-party plugins.
Frame length limits are enforced on both encode and decode, with a per-contract zero-length policy.
Capability tokens are HMAC-SHA256 signed and verified in constant time, with expiry checks.
Interoperability tests decode fixtures produced by the agent’s Python side, so both languages stay on the same bytes.
Optional features keep the default build small: the MAVLink dialect, a tracing log shipping layer and a TLS crypto provider are opt-in.

§How it works

The crate is a collection of modules, one per wire seam:

frame: 4-byte big-endian length-prefixed framing, shared by the MAVLink socket, the vehicle-state socket and the plugin RPC socket.
plugin: the plugin RPC envelope (a msgpack map with short keys v, t, m, c, a, id, tok, err) and the pipe-delimited HMAC-SHA256 capability token bound to a plugin id, a granted capability set, a session and an expiry.
framebus: the vision frame transport, meaning the frame descriptor shape and the shared-memory ring layout frames travel in.
state: the vehicle-state codec, with a newline-delimited JSON reader and a length-prefixed msgpack codec.
logd: logging and telemetry contracts: versioned ingest frames (logs, telemetry, events, hardware snapshots), the read API envelope and secret-field redaction.
capabilities and dispatch: the generated capability catalog and the table mapping each plugin RPC method to the capability it requires.
contracts and paths: the generated registry of contract version numbers, runtime directory, socket and state file names, and each state file’s freshness window.
sidecar: helpers for on-disk state files: schema version check, atomic writers and a freshness-gated reader.
pairing_posture and dashboard_session: data-plane authentication primitives (constant-time key comparison, loopback trust, access decision) and self-contained HMAC session tokens.
mavlink_ingest: the client for a node’s MAVLink republish seam, through which frames received off-board enter the node’s own frame fan-out.
flight_modes: ArduPilot flight-mode tables keyed by vehicle type.
msp and mavlink: MSP helpers and, with the mavlink feature, the MAVLink codec for the ardupilotmega dialect.
shutdown: a latching shutdown signal, so a loop that was busy when the stop arrived still sees it.

The plugin RPC wire is a sequence of frames over a Unix domain socket. Each frame carries one Envelope; the capability token travels in every envelope and the host verifies it before routing the request.

§Cargo features

Feature	Default	What it enables
`mavlink`	no	The MAVLink codec module for the ardupilotmega dialect
`tracing-layer`	no	A `tracing` layer that ships log events to the agent’s log ingest socket
`tls`	no	A process-default rustls crypto provider for crates that make TLS connections

§Versioning

This crate is versioned in lockstep with the ADOS Drone Agent: version X.Y.Z speaks the wire of agent X.Y.Z.

§Part of ADOS

Used in production by the ADOS Drone Agent, the onboard software of the ADOS software-defined drone platform. All ADOS crates · Docs · Discord

§Other ADOS crates

Platform (versioned with the ADOS Drone Agent)

Crate	What it does	Docs
`ados-sdk`	Write Rust plugins for the ADOS Drone Agent: IPC client, plugin context, driver traits and lifecycle runner.	docs.rs
`ados-vision`	Single-object visual tracker: Kalman motion model, appearance re-identification and YOLOv8 head decoding.	docs.rs
`ados-gpio`	Drive status buzzers and LEDs on Linux GPIO lines, with bounded software-PWM beep patterns.	docs.rs
`ados-hal-probe`	Find out what a board’s hardware can really do by probing it, plus bundled board profiles.	docs.rs

Standalone

Crate	What it does	Docs
`ados-sensorhub`	Sensor hub wire protocol: COBS framing, CRC-16 and fixed-layout IMU, baro, mag and GNSS packets. no_std.	docs.rs
`ados-offload`	Choose where perception runs (onboard, offloaded or hybrid) and hold the vehicle when results go stale.	docs.rs
`ados-macpin`	Stable MAC addresses for Linux network adapters that randomize theirs every boot.	docs.rs
`ados-lora`	LoRa transmit governor with cited regional band plans, duty cycle, dwell time and airtime accounting.	docs.rs
`ados-crsf-codec`	no_std CRSF / ExpressLRS codec for RC channels, telemetry and parameter frames.	docs.rs
`ados-positioning`	Split mixed UBX, NMEA and RTCM3 GNSS streams, configure u-blox receivers and run an RTK base survey-in.	docs.rs
`ados-rtcm`	RTCM3 framing, CRC-24Q and MAVLink GPS_RTCM_DATA fragmentation for RTK corrections.	docs.rs
`ados-clock`	Map remote clocks onto the host clock: least-squares and envelope fits, TIMESYNC and a chrony sink.	docs.rs
`ados-swarm`	Swarm control laws: separation, flocking, formations, CBBA task allocation and a point-mass simulator.	docs.rs
`ados-mavlink-tunnel`	Send large messages over MAVLink TUNNEL frames with chunking and bounded reassembly.	docs.rs
`ados-display-driver`	Small-display output on Linux: SSD1306/SH1106 OLED over I2C, pixel packers and a framebuffer writer.	docs.rs
`ados-hmi`	Front-panel input: touchscreen calibration and gestures, button presses and rotary encoders.	docs.rs

§ADOS repositories

Repo	Runs on	What it does	Link
ADOS Mission Control	Browser, desktop (Electron)	Ground control station: FC setup, mission planning, flight, 3D simulation, fleet	ADOSMissionControl
ADOS Drone Agent	Companion computer on the drone, or a ground node	Onboard agent: MAVLink routing, HD video, long-range radio link, plugins, remote control	ADOSDroneAgent
ADOS Android GCS	Android phones and tablets	Native ground control app for agents on the LAN, direct flight controllers and the cloud	ADOSAndroidGCS
ADOS Extensions	Drone Agent and Mission Control	First-party signed plugins, each with an agent half and a GCS half	ADOSExtensions
ADOS MCP	Your machine	Model Context Protocol server that lets AI clients operate ADOS drones under scopes and a safety gate	ADOS-MCP
Documentation	docs.altnautica.com	Public docs for every ADOS product	Documentation

§License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules§

ap_country: The country code the access point advertises.
armed: Whether the vehicle counts as armed, read from the router’s state socket.
aux_egress: Egress client for the auxiliary application stream.
aux_mux: Auxiliary-lane multiplex framing.
aux_ports: The auxiliary lane’s loopback port pair, resolved from operator config.
aux_rpc: Bidirectional RPC frames over the auxiliary lane.
aux_rpc_proxy: Ground-side client for relay-proxy HTTP-over-aux calls.
buttons: Front-panel button events as they reach a plugin.
camera_control: The camera.control.set plugin method: set exposure, gain or the auto-exposure mode of a camera the vision engine owns, and report the values the driver reads back.
capabilities: Generated agent capability catalog.
cloud_link: The cloud-link sidecar: whether this node’s cloud relay is actually talking to the cloud.
cloud_publish: The cloud-publish socket: how a plugin’s agent half sends data off the node through the cloud relay.
config_tunnel: Identifiers of the config-over-radio channel carried in MAVLink TUNNEL frames. The chunking itself is the ados-mavlink-tunnel crate; these are the values that make a TUNNEL frame belong to this channel.
config_tunnel_ingest: The loopback hand-off that gets a config-over-radio frame from the aux plane consumer to the local ados-tunnel-config service.
contracts: Generated IPC contract + sidecar version registry.
dashboard_session: Self-contained dashboard-access session tokens.
dispatch: Generated plugin RPC dispatch table.
fleet_identity: This node’s own fleet slot, read from operator config.
flight_modes: ArduPilot flight-mode tables, keyed by the firmware the FC runs.
frame: 4-byte big-endian length-prefixed framing.
framebus: Vision frame transport contract.
hwcaps: Probed hardware-capability contract.
identity: This node’s device id: one resolver every service reads it through.
ipc: Unix-socket IPC transport for the MAVLink and state sockets.
launchd: launchd job helpers shared by every macOS consumer: the unit-name to reverse-DNS label mapping, the GUI-domain uid, and the property-list renderer.
link_feedback: Ground-measured video-link quality, reported back to the transmitting drone.
logd: Wire contracts for the local logging and telemetry service.
mavlink: MAVLink v2 codec for the ardupilotmega dialect.
mavlink_ingest: Client for a node’s MAVLink republish seam.
mavlink_socket: The MAVLink broadcast socket wire (/run/ados/mavlink.sock, contract mavlink.socket).
mcp_token: Self-contained, scoped ADOS MCP tokens (agent-side verify + on-box mint).
media_relay: The live-video and rig relay plugin methods: video.whep.offer, video.whep.close and sensors.rig.write.
msp: MSP (MultiWii Serial Protocol) v1 + v2 codec.
netif: Which wireless interface is which.
node_info: The node.info plugin method: the node facts a plugin may read without reaching into the agent’s sidecars, which its sandbox hides.
node_presence: The gnss and lora node capability flags, shared by the LAN /api/status/full route and the cloud heartbeat so both transports report the same answer for the same node.
node_status: Compact node status and identity for the auxiliary radio lane.
nonce_cache: A bounded single-use nonce cache for short-lived HMAC tickets.
offload_link: The perception offload-link sidecar: the drone’s live “a workstation is paired + reachable, and I am offloading to it” state.
pair_proof: The WFB pair-proof record: per-key evidence that a radio key has ever actually carried a link.
pairing_posture: Pairing posture: the data-plane auth primitives shared by the agent’s native surfaces.
panel_ui: Front-panel UI defaults shared by every consumer of ground_station.ui.
param_codec: The value encoding of MAVLink PARAM_SET and PARAM_VALUE.
paths: Generated runtime path registry.
plugin: Plugin RPC envelope and capability tokens.
plugin_loopback_guard: The plugin loopback-guard verdict sidecar.
plugin_mdns: The mdns.advertise and mdns.browse plugin methods: DNS-SD on the LAN, done by the host on a plugin’s behalf.
radio_adapters: Per-adapter WFB radio report: the adapters[] + diversity blocks of the wfb-stats sidecar (version 2) and the body of GET /api/v1/radio/adapters.
reach: The node’s resolvable mDNS reach name — one definition for every surface that hands an operator or a GCS a hostname to dial.
relay_ticket: A per-pair credential for relayed requests.
rest: REST client and shared wire types for the agent HTTP API (Contract D, port 8080).
retry: The one pacing primitive for a recovery loop.
secret_gen: Generating operator-facing secrets, unambiguously and fail-closed.
shutdown: A latching, clone-able shutdown signal for a service’s run loops.
sidecar: On-disk state sidecars: the soft schema-version check, the atomic writers, and the one freshness-gated reader.
state: Vehicle-state codec for the state socket (Contract B).
tap: Contract F — the vision-tap wire format.
units: The systemd unit table: every unit the agent ships in data/systemd, with the facts each consumer needs about it.
vision_rpc: The args of the plugin-facing vision requests the engine serves on vision.sock, and the reply vision.infer returns.
vision_status: The vision engine’s work sidecar: proof that the engine is consuming frames.
wfb_status: The one WFB link-status derivation, and the radio block built from it.
wfb_tables: Generated WFB adapter tables.
ws_ticket: Self-contained WebSocket auth tickets.

Functions§

accepts_offboard_setpoints: Whether a flight-mode name is one that accepts offboard position setpoints.