wifi-densepose-swarm
Drone swarm control system for the RuView wifi-densepose workspace. Implements ADR-148.
Overview
wifi-densepose-swarm provides a hierarchical-mesh drone swarm coordination system
with Raft consensus, MAPPO-based multi-agent reinforcement learning, and tight
integration with the existing WiFi CSI sensing pipeline (wifi-densepose-signal,
wifi-densepose-ruvector).
Features
- Hierarchical-Mesh Topology — cluster heads over Raft consensus; inter-cluster Gossip for map dissemination
- Formation Control — F1 VirtualStructure, F2 LeaderFollower, F3 Reynolds flocking
- 3-Phase Coverage — boustrophedon sweep → Bayesian probability grid → multi-drone triangulation
- RRT-APF Path Planner — RRT* with Artificial Potential Field reactive collision avoidance
- MARL Actor (MAPPO) — 64-dim local observation, 3-layer MLP actor, CTDE training interface
- CSI Sensing Integration — drone payload pipeline (ESP32-S3 → Jetson), multi-drone CSI fusion
- OccWorld Bridge — integrates ADR-147 OccWorld occupancy prior as path planner environment
- Security Hardening — MAVLink v2 HMAC-SHA256 signing, UWB GPS anti-spoofing, onboard geofencing, Remote ID
- Fail-Safe State Machine — 10-state onboard safety system, GCS-independent
- Demo & Training Modes — synthetic CSI generation, Gazebo/PX4 SITL interface, TOML mission configs
ITAR Notice
⚠️ Export-controlled capability. Swarming coordination features (formation control,
Raft consensus, task allocation) are gated behind the itar-unrestricted feature flag
per USML Category VIII(h)(12). Default builds compile only safe stubs.
Do not enable itar-unrestricted for international distribution without export counsel review.
Crate Features
| Feature |
Description |
default |
Core types, sensing, failsafe, config, MARL — no ITAR-gated code |
itar-unrestricted |
Enables formation control, Raft consensus, task allocation |
mavlink |
MAVLink v2 protocol support |
onnx |
ONNX Runtime backend for MARL actor inference (INT8) |
simulation |
Simulation-mode stubs |
demo |
Synthetic CSI generation, scenario runners |
full |
All of the above |
Quick Start
use wifi_densepose_swarm::{config::SwarmConfig, demo::scenario::DemoScenario};
// Load a mission profile
let config = SwarmConfig::sar_default();
// Run a demo scenario
let scenario = DemoScenario::sar_rubble_field(4); // 4-drone SAR
let estimated_secs = scenario.estimate_coverage_time_secs();
// → < 240 s for 4 drones over 400×400 m (beyond Wi2SAR SOTA single-drone baseline)
Mission Profiles
| Profile |
Drones |
Area |
Application |
sar |
6–12 |
400×400 m |
Structural collapse victim search |
inspection |
3–6 |
Linear corridor |
Infrastructure (power lines, bridges) |
agriculture |
4–12 |
Field-configurable |
NDVI mapping, variable-rate spraying |
mine |
2–4 |
Tunnel |
GPS-denied underground exploration |
relay |
6–20 |
Perimeter |
Emergency telecom relay chain |
demo |
Any |
Configurable |
Synthetic CSI, configurable victims |
Module Structure
src/
├── types.rs — NodeId, DroneState, SwarmTask, SwarmError, FailSafeState
├── topology/ — Raft consensus¹, Gossip dissemination, MeshTopology
├── formation/ — VirtualStructure¹, LeaderFollower¹, Reynolds flocking¹
├── planning/ — RRT-APF planner, 3-phase coverage, Bayesian grid, pheromone
├── allocation/ — Auction-based task allocation¹, FNN bid scorer¹
├── sensing/ — CSI payload pipeline, multi-drone fusion, OccWorld bridge
├── marl/ — MAPPO actor, LocalObservation, reward shaping, TrainingConfig
├── security/ — MAVLink signing, UWB anti-spoofing, geofencing, Remote ID
├── failsafe/ — 10-state onboard fail-safe machine
├── config/ — TOML SwarmConfig with mission presets
├── demo/ — Synthetic CSI, DemoScenario runners
├── integration/ — FlightController trait (PX4/ArduPilot/Sim)
└── bench_support.rs — Criterion fixture generators
¹ Requires `itar-unrestricted` feature.
Related ADRs
| ADR |
Title |
Relation |
| ADR-148 |
Drone Swarm Control System |
This crate |
| ADR-147 |
OccWorld Occupancy World Model |
Environment prior via sensing::occworld_bridge |
| ADR-134 |
CSI→CIR ISTA Sparse Recovery |
Drone payload sensing |
| ADR-146 |
RF Encoder Multitask Heads |
Drone payload inference |
| ADR-016 |
RuVector Training Integration |
CrossViewpointAttention |
Performance Targets (vs. Wi2SAR SOTA)
| Metric |
Wi2SAR baseline (1 drone) |
4-drone target |
| Coverage |
160,000 m² |
160,000 m² |
| Time |
13.5 min |
≤ 4 min |
| Localization |
5 m |
≤ 2 m (3-view fusion) |
| MARL inference |
N/A |
≤ 5 ms (INT8, release) |
| Raft election |
N/A |
≤ 300 ms |
aabf7a7c49