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.processauthorizes 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
.adosplugat the entrypoint path.
Layout
A Rust agent half is its own crate atagent/ inside the extension
directory:
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 onados-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:
ados-sdk as a path dependency to a sibling
checkout of the agent repository:
An out-of-tree plugin depends on First-party extensions in ADOSExtensions keep the sibling path
dependency above; CI checks ADOSDroneAgent out at the commit recorded in
the
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":ADOS_AGENT_REV file at the workspace root. See
Rust crates for every published ADOS crate.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 thePlugin 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 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).
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
Theados_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 fromados-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 isados-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 setsruntime: 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.