Crate ados_offload 

ados-offload

Decide where drone perception runs (onboard, offloaded or hybrid) and gate stale or link-lost results so the vehicle holds instead of extrapolating.

A drone without an NPU can still fly autonomous behaviours if a nearby compute node runs detection, tracking and SLAM for it. Remote results arrive late and sometimes not at all, and a control loop that acts on a frozen result follows something that is no longer there. This crate makes the two decisions that keep that safe: where perception runs, and whether the latest result is fresh enough to act on. It does no I/O, so it fits any transport.

use ados_offload::{
    pick_tier, GateState, LockState, OffloadMode, OffloadSession, PerceptionTier, TierInputs,
};

// No accelerator, but a compute node is paired on a fast enough link.
let inputs = TierInputs::for_drone(false, false, true, true);
assert_eq!(pick_tier(&inputs), Some(PerceptionTier::Offload));

// Follow a target with a 300 ms freshness budget on detections.
let mut session = OffloadSession::new(OffloadMode::VisionOnly, 300, 300);
session.designate();
session.on_detection(1_000);
assert!(session.tick(1_100).commanding);

// The node stalls: 500 ms later the result is stale, so the drone holds.
let status = session.tick(1_600);
assert_eq!(status.target, GateState::Stale);
assert!(!status.commanding);
assert_eq!(status.lock, LockState::Lost);

// A fresh result alone does not resume; only an explicit re-designation does.
session.on_detection(1_700);
assert!(!session.tick(1_750).commanding);
session.designate();
assert!(session.tick(1_760).commanding);

Highlights

• Pure decision logic: no I/O, no threads, no clock reads. Every time is passed in by the caller.
• Fail-safe by construction: stale or link-lost means stop and hold, never extrapolate, and a lost lock never re-acquires on its own.
• Freshness is measured on the drone’s own monotonic clock, so a remote node with a skewed clock cannot make a frozen stream look fresh.
• A negative freshness budget is clamped to zero rather than flipping the fail-safe direction.
• One dependency (serde, for the state enums); 30 unit tests.

How it works

The rule the crate is built around: the fast control loop and the control-loop pose stay on the drone; the heavy perception and the drift-corrected map pose may go remote.

• pick_tier chooses a PerceptionTier from TierInputs:
  • a local accelerator that fits the models, or a CPU strong enough for the detector, gives Local;
  • otherwise a paired node on an acceptable link gives Hybrid when the board can run a light local path, else Offload;
  • otherwise a board with a light local path gives degraded Local;
  • otherwise None: no heavy perception, the drone flies on bare odometry.
• FreshnessGate tracks one return stream. It is Fresh when a result arrived within the budget and the link is up, Stale when the last result is too old, and Lost before any result or while the link is down. Only Fresh is usable.
• LockGate is the lock state machine. A lock that has had a usable reading drops to Lost the moment the stream stops being usable. A lock still acquiring (never usable yet) holds in Locked. The only way out of Lost is an explicit lock().
• OffloadSession composes a target gate, a pose gate and a lock gate per OffloadMode: VisionOnly needs fresh detections, SlamOnly fresh poses, Full both. Each tick returns a SessionStatus whose commanding flag is true only when locked and every required stream is fresh.

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-sdk	Write Rust plugins for the ADOS Drone Agent: IPC client, plugin context, driver traits and lifecycle runner.	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-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.

Structs

FreshnessGate

Tracks the freshness of one offloaded result stream.

LockGate

The lock-state safety gate.

OffloadSession

A streaming perception/SLAM offload session with per-stream freshness gates and a lock-state safety gate.

SessionStatus

A snapshot of a session’s safety state for one cycle.

TierInputs

The inputs the agent reads to pick a perception tier.

Enums

GateState

The freshness of one offloaded stream (a detection/target stream, or a pose stream), derived from the last result’s age and the link state.

LockState

The lock-state machine. A behaviour locks onto a target (an operator designate, or an auto-lock). While Locked it is acquiring until the stream first becomes usable; once it has had a usable reading, the stream going stale or the link dropping drops it to Lost. The only way out of Lost is an explicit re-lock, there is no auto-re-acquire. A lock that has never yet had a usable reading does NOT drop to Lost (there is nothing to lose); it stays Locked, holding, until a result arrives or it is released.

OffloadMode

What the node returns for a session.

PerceptionTier

Where the heavy perception (detection / tracking / SLAM) runs.

Functions

pick_tier

Pick the perception tier, or None when no heavy perception is available (an NPU-less board with no usable compute node, it flies on bare odometry, with no detection / tracking / map-based autonomy).