Skip to main content
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; 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:
The worked examples are extensions/reconstruct (a main binary plus a declared service through bin:<name>) and extensions/capture (several binaries through bin:<name> 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 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:
The root workspace resolves ados-sdk as a path dependency to a sibling checkout of the agent repository:
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":
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 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.
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:
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. 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<T> (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.

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).
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 navigation, 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.
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. 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<n> 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:
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:<name> with per-architecture binaries. Signing and install are otherwise identical to a Python plugin; see Signing keys. A plugin that bundles a vendor binary sets contains_vendor_binary: true and lists each one under vendor_attribution; see Vendor binaries.

Next steps

Manifest

Every field, including binaries and payloads.

Agent plugin deep dive

How the host runs an agent half.

Vision plugins

Frames, models and detections.

Python SDK

The same surface in Python.
Last modified on November 19, 2026