Crate ados_sdk 

ados-sdk

Build Rust plugins for the ADOS Drone Agent: async IPC client, plugin context, hardware driver traits and lifecycle runner.

A plugin is a separate process the ADOS Drone Agent starts, sandboxes and talks to over a private Unix socket. This crate is everything a Rust plugin needs on its side of that socket: implement the Plugin hooks you care about, hand the type to run_plugin, and use the PluginContext to publish events, read telemetry, send MAVLink or drive hardware. Every call is checked by the host against the capabilities the plugin’s manifest was granted.

use std::collections::BTreeMap;

use ados_sdk::{run_plugin, ClientError, Plugin, PluginContext};
use async_trait::async_trait;
use rmpv::Value;

struct Hello;

#[async_trait]
impl Plugin for Hello {
    fn new() -> Self {
        Hello
    }

    async fn on_start(&mut self, ctx: &PluginContext) -> Result<(), ClientError> {
        ctx.events.publish("hello.started", Value::from("hi")).await?;
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    let shutdown = async {
        let _ = tokio::signal::ctrl_c().await;
    };
    // The host passes the socket path and token on argv and in the environment.
    if let Err(e) = run_plugin::<Hello, _>(env!("CARGO_PKG_VERSION"), BTreeMap::new(), shutdown).await {
        eprintln!("plugin stopped: {e}");
        std::process::exit(1);
    }
}

The example needs async-trait, rmpv and tokio (with the macros, rt-multi-thread and signal features) next to ados-sdk in your Cargo.toml.

Highlights

• Speaks the same wire as the agent’s Python plugin SDK, using the shared ados-protocol codec, so Rust and Python plugins are interchangeable from the host’s point of view.
• Every lifecycle hook has a default no-op: a plugin overrides only what it needs.
• Capability tokens rotated by the host are adopted transparently, so a rotation never costs the plugin a failed call.
• Hardware driver traits for cameras, gimbals, lidars, GPS receivers, ESCs and payload actuators.
• A testing module for exercising a plugin without a running agent.

How it works

• PluginIpcClient: the async client. It connects to the plugin socket, runs the hello handshake, sends requests keyed by a request id, runs the reader loop and dispatches event and MAVLink pushes to topic-matched callbacks.
• PluginContext: the plugin-facing facade, with sub-clients for events, MAVLink, MSP, telemetry, peripherals, camera, config, process, cloud, vision and lifecycle.
• drivers: the hardware driver traits (CameraDriver, GimbalDriver, LidarDriver, GpsDriver, EscDriver, PayloadActuatorDriver) and their candidate, capability and sample types.
• Plugin and run_plugin: the lifecycle trait and the runner. The runner reads --socket, --token and --agent-id from argv or the environment, connects, then calls on_install, on_enable, on_configure and on_start, waits for shutdown, and finishes with on_stop and on_disable. If the host session drops, the runner returns an error so the process exits and the host restarts it with a fresh session.
• http: for plugins that serve their own HTTP pages, the host-provided socket path and a listener bind helper.

The wire is length-prefixed msgpack envelopes over a per-plugin Unix domain socket, each carrying an HMAC-signed capability token. The agent’s capability catalog is re-exported from ados-protocol as capabilities.

Versioning

This crate is versioned in lockstep with the ADOS Drone Agent: version X.Y.Z speaks the wire of agent X.Y.Z. Depend on the version that matches the agent your plugin targets.

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-protocol	Wire contracts of the ADOS Drone Agent: IPC framing, plugin RPC envelope, capability tokens and the vision frame bus.	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.

Re-exports

pub use client::ClientError;

pub use client::EventCallback;

pub use client::OffloadAdvertisement;

pub use client::PluginIpcClient;

pub use client::ToolHandler;

pub use client::WhepAnswer;

pub use context::CameraClient;

pub use context::CloudClient;

pub use context::ConfigClient;

pub use context::EventsClient;

pub use context::LifecycleClient;

pub use context::MavlinkClient;

pub use context::MdnsClient;

pub use context::NodeClient;

pub use context::PeripheralClient;

pub use context::PluginContext;

pub use context::ProcessClient;

pub use context::SensorsClient;

pub use context::TelemetryClient;

pub use context::ToolsClient;

pub use context::VideoClient;

pub use lifecycle::run_plugin;

pub use lifecycle::run_plugin_with;

pub use lifecycle::Plugin;

pub use lifecycle::RunnerArgs;

pub use lifecycle::RunnerError;

pub use vision::Frame;

pub use vision::FrameCallback;

pub use vision::Odometry;

pub use vision::Pose;

pub use vision::VisionClient;

pub use vision::VIO_COMPONENT_ID;

Modules

capabilities

The generated agent capability catalog, re-exported from ados-protocol so a plugin author references one source of truth for capability ids. The source of truth is crates/ados-protocol/capabilities.toml.

client

Async IPC client: the plugin runner side of Contract C.

context

Plugin-facing facade over the IPC client.

drivers

Hardware driver traits for driver-layer plugins.

http

The operator-facing HTTP socket of an agent.http: true plugin.

lifecycle

Plugin lifecycle trait and the runner entry.

mdns

The mdns.advertise / mdns.browse types (MdnsClient), re-exported from ados-protocol, which the host decodes and serializes them with.

msp

Streaming MSP frame reassembly for ctx.msp.subscribe.

node_info

The node.info reply types (NodeClient::info), re-exported from ados-protocol, which the host serializes them from.

testing

Test harness for vision plugins.

vision

Vision surface: frame subscription, model registration, inference, and detection publishing, plus the visual-odometry pose helper.

Structs

CameraControlRequest

The camera.control.set request and reply (CameraClient::set_controls). The reason codes of a refused request are in ados_protocol::camera_control::reason. camera.control.set arguments. An absent field leaves that control as it is. exposure_us implies manual exposure; gain is a multiplier (1.0 is unity gain).

CameraControlResult

The camera.control.set request and reply (CameraClient::set_controls). The reason codes of a refused request are in ados_protocol::camera_control::reason. camera.control.set reply. exposure_us and gain (a multiplier) are the values the driver reads back (None when the camera has no such control, its gain unit is unknown, or it was not reached), not the requested ones.

Constants

NODE_PROFILE_ENV

The env var the host sets on every plugin unit to this node’s profile.

Functions

node_profile

This node’s profile (drone, ground-station, workstation or compute), as the host exported it into the plugin’s environment. drone only when the variable is unset or empty, which a host-started plugin never sees.