Crate ados_swarm

Expand description

§ados-swarm

Swarm control laws for multirotors: separation, braking-aware barriers, alpha-lattice flocking, formations, CBBA task allocation and a deterministic point-mass simulator.

Flying several multirotors near each other needs three things at once: never let two aircraft close inside a safety floor, keep the group moving together or holding a shape, and agree on who does which task without a central coordinator. This crate is those control laws as plain Rust, plus a deterministic simulator to test them on a laptop. Reach for it when you are building swarm autonomy on top of any autopilot that accepts position or velocity setpoints.

use ados_swarm::separation::SEPARATION_HARD_M;
use ados_swarm::sim::{SimDrone, SimWorld};
use ados_swarm::{GeoOrigin, Ned, SwarmControlConfig};

// Three drones in flocking mode, launched 12 m apart at 30 m altitude.
let cfg = SwarmControlConfig {
    enabled: true,
    mode: "flocking".into(),
    ..Default::default()
};
let slots = [1, 2, 3];
let drones = vec![
    SimDrone::new(1, Ned::new(0.0, 0.0, -30.0), &cfg, &slots),
    SimDrone::new(2, Ned::new(12.0, 0.0, -30.0), &cfg, &slots),
    SimDrone::new(3, Ned::new(0.0, 12.0, -30.0), &cfg, &slots),
];
let mut world = SimWorld::new(GeoOrigin::new(47.397, 8.545, 0.0), drones);

// 30 simulated seconds at the 10 Hz control rate.
let report = world.run(300);
println!("closest approach: {:.1} m", report.min_pairwise_m);
assert!(report.min_pairwise_m > SEPARATION_HARD_M);

§Highlights

Every control law is a pure function over a slice of neighbours in a local NED frame: no clock, no socket, no radio.
One dependency (serde, for the configuration structs).
Deterministic simulator with a first-order velocity plant, 2 Hz beacon quantisation and dead reckoning; four flight scenarios (collision course, 8-drone flocking to a target, wedge station keeping, beacon loss) run as ordinary tests and as cargo run --example swarm_scenarios.
A fixed precedence ladder decides which law flies, and the active level packs into three bits of a one-byte beacon status field.
Bounded work per tick: nearest-neighbour search is allocation-free and every law weights at most a fixed number of neighbours.

§How it works

§Shape

Every law takes a slice of NeighborState and returns a velocity or position intent. The only stateful piece is SwarmController, which holds the latches a safety layer needs (the hard-override dwell, the staleness deadline, the climb datum) and converts between geodetic coordinates and the local frame at the boundary. Its tick consumes this drone’s own state plus geodetic neighbour fixes and returns at most one Setpoint, the field set of MAVLink SET_POSITION_TARGET_GLOBAL_INT. Encoding and sending it is left to the host.

§Modules

Module	What it holds
`separation`	Repulsive separation and the hard-breach override with a slot-ordered deconfliction climb
`barrier`	Closing-rate barrier on the braking-adjusted margin, so a vehicle with velocity lag still stops outside the floor
`flocking`	Alpha-lattice flocking: cohesion, alignment and a saturating virtual leader
`formation`	Five named formations generated from the slot set, anchored on the centroid or a slot
`cbba`	Consensus-Based Bundle Algorithm: greedy bundle building and the conflict-resolution table
`precedence`	The mode ladder and its beacon encoding
`status`	Beacon status bits: armed, guided, emergency, GPS OK, hero, precedence
`geo`	Flat-earth equirectangular projection around a local origin
`config`	Deserializable gains as integer percentages, converted once to sanitised tunings
`sim`, `scenarios`	The point-mass world and the four reference scenarios

§The precedence ladder

Highest first: hard separation, operator directive, formation, flocking, hold. The ACTIVE level, not the commanded one, is what SwarmController::precedence reports and what ModePrecedence::as_status_bits packs into status bits 5..7. A drone whose separation layer has taken over reads hard-separation, never the mode somebody asked for. Hold is encoding zero, so a node with no control layer running reads hold truthfully.

§Staleness

NEIGHBOR_STALE (3 s) is how long a silent neighbour is kept and how long an empty table is tolerated before the controller stops commanding. OWN_STATE_STALE (1 s) is tighter, because a frozen own fix stays plausible while every neighbour is measured from it. A transport that prunes its table or gates its own beacon should use the same constants.

§What is deliberately not here

No leader election. Electing a leader among drones over a lossy broadcast invites a split brain for no benefit; the operator is the single authority.
No failsafe of its own. The autopilot’s own failsafes and geofence are the backstop. When the controller has nothing trustworthy to fly on it emits nothing and lets the flight controller hold.

§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-offload`	Choose where perception runs (onboard, offloaded or hybrid) and hold the vehicle when results go stale.	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-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.

Re-exports§

pub use barrier::BarrierOutcome;
pub use barrier::BARRIER_GAIN_HZ;
pub use cbba::conflicts;
pub use cbba::consensus_reached;
pub use cbba::converge_broadcast;
pub use cbba::BidVector;
pub use cbba::CbbaAgent;
pub use cbba::CbbaTask;
pub use cbba::ConvergenceReport;
pub use cbba::TaskAssignment;
pub use config::SwarmControlConfig;
pub use controller::ControlOutcome;
pub use controller::NeighborFix;
pub use controller::OperatorDirective;
pub use controller::OwnState;
pub use controller::Suppression;
pub use controller::SwarmControlCounters;
pub use controller::SwarmController;
pub use controller::SwarmMode;
pub use controller::CONTROL_HZ;
pub use controller::CONTROL_PERIOD;
pub use controller::OPERATOR_DIRECTIVE_TTL;
pub use flocking::FlockTerms;
pub use flocking::FlockTuning;
pub use formation::Formation;
pub use formation::FormationAnchor;
pub use formation::FormationName;
pub use geo::GeoOrigin;
pub use geo::Ned;
pub use neighbor::NearestSet;
pub use neighbor::NeighborState;
pub use precedence::arbitrate;
pub use precedence::precedence_rank;
pub use precedence::ModePrecedence;
pub use separation::HardBreach;
pub use separation::SeparationTuning;
pub use setpoint::Setpoint;
pub use setpoint::SetpointKind;
pub use setpoint::MAX_COMMAND_SPEED_MPS;
pub use status::STATUS_ARMED;
pub use status::STATUS_EMERGENCY;
pub use status::STATUS_GPS_OK;
pub use status::STATUS_GUIDED;
pub use status::STATUS_HERO;
pub use status::STATUS_PRECEDENCE_MASK;
pub use status::STATUS_PRECEDENCE_SHIFT;

Modules§

barrier: The separation layer’s override half: a braking-aware closing-rate barrier.
cbba: CBBA task allocation across the fleet.
config: The swarm configuration block, and the one place integer percentages become real gains.
controller: Mode arbitration, the 10 Hz loop, and the failsafe gates.
flocking: Olfati-Saber α-lattice flocking.
formation: Named formations.
geo: Local tangent-plane geodesy and the 3-vector the control laws work in.
neighbor: The control laws’ view of a neighbour, and the allocation-free nearest-set search every law shares.
precedence: The mode-precedence ladder, and the three-bit encoding of the active level inside a beacon status byte.
scenarios: The four flight-gate scenarios, as reusable runs.
separation: The separation safety layer.
setpoint: The one command this layer emits: SET_POSITION_TARGET_GLOBAL_INT.
sim: A deterministic point-mass swarm simulator for the four flight-gate scenarios.
status: The beacon status byte: five condition bits and the three-bit active precedence field.

Constants§

NEIGHBOR_STALE: How long a neighbour survives without a beacon, and how long an empty neighbour table is tolerated before the controller stops emitting setpoints.
OWN_STATE_STALE: How stale this drone’s OWN position may be before the controller stops commanding, and before a transport should stop broadcasting it.

Crate ados_swarm

Crate ados_swarm Copy item path

§ados-swarm

§Highlights

§How it works

§Shape

§Modules

§The precedence ladder

§Staleness

§What is deliberately not here

§Part of ADOS

§Other ADOS crates

§ADOS repositories

§License

Re-exports§

Modules§

Constants§

Crate ados_swarm