Driver layer

The driver base classes and data types ship in both SDKs (ados.sdk.drivers in Python, ados_sdk::drivers in Rust), and the method contracts on these pages match them. The agent does not route drivers. It never calls discover(), open() or the iterators. register_*_driver calls return not_implemented, and the sensor.*.register capabilities are refused at grant time. A driver plugin opens and runs its own device from its lifecycle hooks, as the first-party Gimbal v2 plugin does. No Mission Control panel renders driver output.

The driver layer is a set of typed base classes for hardware-driver plugins. A driver plugin is an ordinary agent plugin: same manifest, same lifecycle, same sandbox. The base classes give every device kind the same shape, so a driver written against them is easy to test with a mock backend and easy to read. Python drivers subclass the abstract base classes in ados.sdk.drivers. Rust drivers implement the matching trait in ados_sdk::drivers. The two are method-for-method equivalents. Set agent.runtime in the manifest to python or rust to pick the language.

The six driver kinds

Kind	Base class	Page
Camera (visible, thermal, depth, multi-spectral)	`CameraDriver`	Camera driver
Gimbal	`GimbalDriver`	Gimbal driver
LiDAR	`LidarDriver`	LiDAR driver
GPS (including RTK)	`GpsDriver`	GPS driver
ESC telemetry	`EscDriver`	ESC driver
Payload actuator (sprayer, dropper, claw, sampler)	`PayloadActuatorDriver`	Payload actuator driver

All six share the same preamble in both languages:

from abc import ABC, abstractmethod

class XDriver(ABC):
    async def discover(self) -> list[XCandidate]: ...
    async def open(self, candidate: XCandidate, config: dict) -> XSession: ...
    async def close(self, session: XSession) -> None: ...
    def capabilities(self, session: XSession) -> XCapabilities: ...
    # plus kind-specific I/O methods

#[async_trait]
pub trait XDriver: Send + Sync {
    type Session: Send + Sync;
    async fn discover(&self) -> DriverResult<Vec<XCandidate>>;
    async fn open(&self, candidate: &XCandidate, config: &BTreeMap<String, Value>)
        -> DriverResult<Self::Session>;
    async fn close(&self, session: Self::Session) -> DriverResult<()>;
    fn capabilities(&self, session: &Self::Session) -> XCapabilities;
    // plus kind-specific I/O methods
}

The kind-specific methods carry the data. A CameraDriver yields FrameBuffers, a GpsDriver yields GpsFixes, a GimbalDriver takes attitude commands. In Python the stream methods return an AsyncIterator. In Rust they return a SampleStream (a boxed Stream), and the opaque Python *Session class becomes the Session associated type.

Running a driver from your plugin

Your plugin owns the driver from start to finish:

In on_start, construct the driver with its backend (a serial port, a USB handle, a MAVLink router handle).
Call discover() and pick a candidate. If there is none, report the failure and return.
Call open(candidate, config). config is your plugin’s operator config, validated against config-schema.json.
Consume the kind-specific stream (frame_iterator, fix_iterator, state_iterator, telemetry_iterator) in a task you start.
Publish what Mission Control should see with ctx.telemetry.extend or ctx.events.publish. Your plugin’s GCS half renders it.
In on_stop, cancel the task and call close(session).

The MAVLink Gimbal v2 plugin follows this pattern in agent/src/altnautica_gimbal_v2/plugin.py, and the FLIR Lepton plugin does the same in agent/src/altnautica_thermal_camera/plugin.py.

Manifest permissions

Declare only the hardware and data capabilities your driver actually uses. sensor.camera.register, sensor.depth.register, sensor.lidar.register, sensor.imu.register and sensor.payload.register are in the capability catalog, but this agent refuses to grant them (“not supported by this agent runtime”) because the host method they gate is not implemented. Declaring one buys nothing.

Kind	Typical capabilities
Camera	`hardware.usb.uvc` (USB UVC), `hardware.camera.csi` (MIPI CSI), `hardware.usb` (raw USB behind a vendor SDK)
Gimbal	`mavlink.read`, `mavlink.write`, `mavlink.component.gimbal` (MAVLink gimbals); `hardware.uart` (serial gimbals)
LiDAR	`hardware.uart`, `hardware.usb`, or `hardware.i2c`, matching the sensor’s bus
GPS	`hardware.uart` or `hardware.i2c`; `mavlink.read` to receive RTCM from the flight controller link
ESC telemetry	`hardware.uart` (KISS or BLHeli32 telemetry wire), or `mavlink.read` for `ESC_TELEMETRY_*` messages
Payload actuator	`hardware.gpio_out`, `hardware.uart`, or `mavlink.write` for servo and relay commands
Any kind	`telemetry.extend` and `event.publish` to send readings to your GCS half

Risk levels and the full catalog are on Permissions.

Errors

Python drivers raise from ados.sdk.drivers.errors. Rust drivers return the DriverError enum from ados_sdk::drivers (every driver method returns DriverResult<T>).

from ados.sdk.drivers.errors import (
    DriverError,
    DriverDeviceNotFound,
    DriverPermissionDenied,
)

use ados_sdk::drivers::{DriverError, DriverResult};

// DriverError variants:
//   DriverError::DeviceNotFound(String)
//   DriverError::PermissionDenied(String)
//   DriverError::InvalidParam(String)
//   DriverError::NotSupported(String)
//   DriverError::Other(String)

In Python, DriverError is the base. DriverDeviceNotFound means the candidate disappeared between discover and open. DriverPermissionDenied means the device exists but the plugin process cannot open it (a missing udev rule, a locked USB device, an undeclared capability). The Rust enum mirrors these. InvalidParam is returned for an unknown set_param name or an unknown actuate action, and NotSupported for an optional capability the device lacks (a rate command on a position-only gimbal, RTCM injection on a non-RTK GPS). Other carries any recoverable condition that does not fit a named kind. Raise these from your own driver code and handle them in your plugin. A plugin that raises an unhandled exception out of a lifecycle hook is handled per Lifecycle.

Next steps

Camera driver

The worked example, with the FLIR Lepton driver.

Gimbal driver

The MAVLink Gimbal v2 reference driver.

Vendor binaries

Ship a closed-source library or per-architecture binary.

Hardware testing

Mock backends, SITL and bench rigs.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

The six driver kinds

Running a driver from your plugin

Manifest permissions

Errors

Next steps

Camera driver

Gimbal driver

Vendor binaries

Hardware testing

​The six driver kinds

​Running a driver from your plugin

​Manifest permissions

​Errors

​Next steps

Camera driver

Gimbal driver

Vendor binaries

Hardware testing

The six driver kinds

Running a driver from your plugin

Manifest permissions

Errors

Next steps