Python SDK

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; 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 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

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.
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:

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 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: <cap>.

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).	`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).

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 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:

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:

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:

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 <dir> runs a plugin’s pytest suite with the manifest validated first; see the Plugin 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

Your first plugin

Build, sign and install a plugin end to end.

Event hooks and bus

Topics and the agent event bus.

Vision plugins

Frames, models and detections.

Rust SDK

The same surface in Rust.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Install

What `ados.sdk` exports

The agent-half plugin shape

The plugin context

A real skeleton

IPC

Resource limits

Testing

Where the rest of the contract lives

Next steps

Your first plugin

Event hooks and bus

Vision plugins

Rust SDK

​Install

​What ados.sdk exports

​The agent-half plugin shape

​The plugin context

​A real skeleton

​IPC

​Resource limits

​Testing

​Where the rest of the contract lives

​Next steps

Your first plugin

Event hooks and bus

Vision plugins

Rust SDK

Install

What `ados.sdk` exports

The agent-half plugin shape

The plugin context

A real skeleton

IPC

Resource limits

Testing

Where the rest of the contract lives

Next steps