L.O.C.U.S.T. — ROS2_4817 Bridge

Layered Operational Command for Uncrewed Swarm Tasking

ROS2 in. STANAG 4817 out. MQTT everywhere. Commands back.

A real-time bidirectional bridge that subscribes to ROS2 topics from drones and robots (including PX4 via uXRCE-DDS), records raw data to MCAP, transforms it into STANAG 4817 (CATL HIBW) compliant structures, publishes standardized messages over MQTT, and receives inbound task commands for autonomous execution — orchestrated by 11 durable Rivet actors with KROG governance enforcement, backed by a Convex reactive database for real-time UI state.

---

Architecture

ROS2 Topics              Bridge Node                  Consumers
────────────   ┌──────────────────────────────┐   ────────────
/{ns}/gps  ──▶ │                              │
/{ns}/imu  ──▶ │  Transform → 4817 envelope   │
/{ns}/batt ──▶ │          │                    │
/{ns}/odom ──▶ │          ├── MQTT publish ────┼──▶ C2 map displays
               │          │   (dissemination)  │    Coalition consumers
               │          │                    │    Foxglove dashboards
               │          │                    │
               │          ├── Rivet POST ──────┼──▶ Session state
               │          │   (fire-and-forget)│    Governance audit
               │          │                    │    Contact fusion
               │          │                    │    Geofence monitor
               │          │                    │    Fault tracking
               │          │                    │    Fleet coordination
               │          │                    │
               │          └── MCAP write ──────┼──▶ ReductStore (:8383)
               │                               │    ├ Bucket: mcap-recordings
               └──────────────────────────────┘    ├ Zstd compression
                                                   ├ Time-indexed retrieval
                                                   ├ FIFO quota (10 GB default)
                                                   └ API token auth

Key design decision: MQTT is the primary dissemination channel. Rivet enriches but never gates. If Rivet is down, MQTT continues normally. ReductStore provides durable MCAP persistence with automatic FIFO eviction — old recordings are pruned when the quota is reached.

Core pipeline: Subscribe → Record (MCAP → ReductStore) → Transform (4817) → Validate (JSON Schema) → Govern (KROG) → Publish (MQTT)

Key Features

• 6 ROS2 subscribers: NavSatFix, Imu, Odometry, BatteryState, PoseStamped, Detections (+PX4 VehicleStatus)
• STANAG 4817 compliance: NodeDescription, NodeStatus, DynamicUpdate, TaskAdmin, TaskFeedback, TaskResult, Chat
• MCAP recording: Zstd-compressed recordings with ReductStore integration
• Convex reactive backend: 12-table self-hosted database with real-time subscriptions, HTTP ingest, cron cleanup, and version snapshots
• NIST ALFUS autonomy: 3-axis autonomy evaluation (Mission Complexity, Environmental Complexity, Human Independence)
• Rivet actor runtime: 11 durable stateful actors (Platform, Track, ExternalTrack, ContactFusion, Task, KROG, Fleet, C2Workflow, Experiment, Fault, Geofence) with WebSocket streaming and PostgreSQL-backed persistence
• Mission engine: YAML-defined waypoint missions with state machine, search patterns (lawnmower, expanding square, sector), and geofencing
• Command & Control: Operator commands, authority delegation, and audit logging
• Fault injection: GPS denial, comms loss, low battery, platform failure — YAML-driven CI scenarios
• Inter-platform coordination: Detection relay, fleet management, coordinated search, task redistribution
• Environment simulation: Wind, sea state, current, day/night sensor degradation models
• KROG governance: 9 deontic operators enforced at runtime (obligatory, permitted, prohibited, conditional, waivable, delegated, revocable)
• Regulatory compliance: Mapped to EU AI Act, NATO RAI, NIS2/CRA, Norwegian DIGDIR 2026, NSM
• J.O.S.H.U.A. Monitor: Modular Vite/TypeScript C2 dashboard with Leaflet maps, MQTT live feed, Convex subscriptions, swarm/track/geofence managers, formation preview, connection manager, and scenario selector
• Scenario controller: MQTT-driven hot-switching of simulation scenarios from the monitor UI
• Node-RED flows: Data ingestion, schema validation, and contact fusion pipelines
• Simulation: Single-drone demo, multi-drone swarm, fleet simulation with PX4 SITL
• 3-tier deployment: Local (Docker Compose), Development Lab (Raspberry Pi fleet), Production (RKE2/Kubernetes + Helm)

Project Names

Name	Full Form	Scope
L.O.C.U.S.T.	Layered Operational Command for Uncrewed Swarm Tasking	Project codename for the entire system
ROS2_4817 Bridge	—	Technical name for the core bridge software
J.O.S.H.U.A.	Joint Operations Supervisory Hub for Unified Autonomy	Autonomy engine — the ALFUS-based decision brain

Project Structure

ROS2_4817/
├── .settings/          # 31 documentation files + 1 Mermaid source (see table below)
├── git/                # Bridge source code (ros2_4817_bridge Python package)
│   ├── ros2_4817_bridge/   # Core bridge: subscribers, transformers, models, etc.
│   │   └── sim/            # Simulation: demo, swarm, fleet, scenario_controller
│   ├── config/             # YAML: mappings, platforms, missions, faults, environments
│   ├── test/               # Unit, integration, and fixture tests (757 tests)
│   ├── tools/              # live-monitor.html, reductstore-query.py
│   ├── vendor/             # atak-sidc-server (ATAK SIDC symbol server)
│   ├── Dockerfile          # Bridge container image
│   └── docker-compose.yaml # Local dev stack (core + sim/px4/viz/monitoring/rivet/convex)
├── rivet/              # Rivet engine source (Rust, Apache 2.0 — local build)
├── rivet-actors/       # L.O.C.U.S.T. Rivet actor definitions (TypeScript + rivetkit)
├── joshua-monitor/     # J.O.S.H.U.A. Live Pipeline Monitor (Vite + TypeScript + Convex)
│   ├── convex/             # Convex backend: schema, mutations, queries, crons, HTTP
│   ├── src/                # Frontend source
│   │   ├── convex/         # Convex client, subscriptions, forwarder
│   │   ├── map/            # Leaflet layers, icons, track/geofence/formation drawing
│   │   ├── mqtt/           # MQTT client, handlers, command publishing
│   │   ├── rivet/          # Rivet HTTP client integration
│   │   ├── stores/         # Zustand state management
│   │   └── ui/             # UI panels: swarm, track, geofence, details, connection, feed
│   └── index.html          # Main entry point (single-page app)
├── helm/               # Helm charts for RKE2/Kubernetes deployment
├── docs/               # STANAG 4817 reference docs (EA-IDL, JSON/XSD/Protobuf schemas)
├── flows/              # Node-RED 4817 flows (ingestion, validation, fusion)
├── diagram/            # Mermaid architecture diagrams
├── experiment/         # Autonomous experiment infrastructure
├── memory/             # claude-mem worker (standalone)
└── autoresearch/       # Karpathy's autoresearch pattern (reference)

See .settings/5.SCAFFOLDING.md for the full directory tree and .settings/1.PROMPT.md for the system prompt.

Quick Start

# Clone and enter the bridge source
cd git/

# Create and activate Python virtual environment
python3 -m venv .venv && source .venv/bin/activate

# Install Python dependencies
pip3 install -r requirements.txt

# Run the demo (synthetic telemetry → 4817 → MQTT)
python3 -m ros2_4817_bridge.sim.demo

# Or multi-drone swarm simulation
python3 -m ros2_4817_bridge.sim.swarm_demo

# Or with Docker Compose (bridge + MQTT broker + ReductStore + more)
docker compose up -d

# Add simulation fleet
docker compose --profile sim up -d

# Add Rivet actor engine (first build ~10 min)
docker compose --profile rivet up -d --build

# Full stack (everything)
docker compose \
  --profile sim \
  --profile px4 \
  --profile viz \
  --profile monitoring \
  --profile rivet \
  up -d --build
# Run J.O.S.H.U.A. Monitor (separate terminal)
cd joshua-monitor/
npm install
npm run dev              # → http://localhost:5173

# Run Scenario Controller (MQTT-driven hot-switch)
cd git/
PYTHONPATH=. python -m ros2_4817_bridge.sim.scenario_controller

See .settings/15.DEVSETUP.md for full development environment setup and .settings/22.COMMANDS.md for the complete CLI reference.

Docker Compose Profiles

Profile	Services	Purpose
(core, always on)	mqtt, bridge, reductstore, memory, sidc-server	Minimal stack
sim	ros2-sim, drone-sim	Synthetic fleet simulation
px4	px4-sitl, uxrce-dds-agent	PX4 SITL with Gazebo Harmonic
viz	foxglove-bridge, urdf-viz, urdf-viz-bridge	Foxglove + 3D visualization
monitoring	prometheus, grafana	Metrics and dashboards
rivet	rivet-postgres, rivet-engine, rivet-actors	Durable actor runtime
convex	convex-backend, convex-dashboard	Reactive database + admin UI
video	image2rtsp	RTSP video bridge

Deployment Tiers

Tier	Environment	Orchestration	Details
Local	Single macOS, Docker Desktop	Docker Compose	Synthetic telemetry, full feature set
Dev Lab	4× Raspberry Pi 5 + GCS laptop	Docker Compose per Pi	LAN fleet, centralized MQTT/Grafana/Rivet
Production	Real drones + RKE2 cluster	Helm + Kubernetes	Tactical networking, HA, TLS, TBMQ

See .settings/25.DEPLOYMENT.md for full deployment architecture and checklists.

Convex Reactive Backend

Self-hosted Convex instance providing real-time reactive state for the J.O.S.H.U.A. Monitor.

Setting	Value
Image	ghcr.io/get-convex/convex-backend
Backend port	3210 (HTTP API)
Dashboard port	6791 (Admin UI)
Tables	12 (see below)
Config	joshua-monitor/.env.local

12 Convex Tables

Table	Purpose	Indexed by
platforms	Per-platform telemetry state	platformId
tracks	AIS, ADS-B, detection, fused tracks	trackId, feedType, region
geofences	Polygon boundaries with enforcement	fenceId
breaches	Geofence breach events	fenceId, platformId, resolved
governanceEvents	KROG governance audit trail	decision
faults	Active/cleared fault state	platformId, active
tasks	Task lifecycle (18-state machine)	taskId, platformId
chatMessages	Operator chat messages	(creation time)
plannedTracks	Domain-aware drawn routes (AIR/SURFACE/SUB/GROUND)	trackId, domain, platformId
swarmFormations	Formation definitions (LINE/WEDGE/DIAMOND/CIRCLE/ECHELON)	formationId, state
versionSnapshots	Append-only entity version history	entityType+entityId, version
crons	Stale-data cleanup (platforms 60s, tracks 120s)	(scheduled)

J.O.S.H.U.A. Monitor

Modular Vite/TypeScript C2 dashboard (joshua-monitor/).

Module	File	Purpose
Connection Manager	ui/connection-popup.ts	Service health, endpoint config, admin links
Swarm Manager	ui/swarm-manager.ts	Affiliation-grouped platform selection, formation builder
Track Manager	ui/track-manager.ts	Domain-aware route drawing (AIR/SURFACE/SUB/GROUND)
Geofence Manager	ui/geofence-manager.ts	Polygon drawing, enforcement modes, versioned publish
Details Panel	ui/details-panel.ts	Deep platform inspection, contacts, swarm metadata
Command Panel	ui/command-panel.ts	Operator C2 commands to selected platforms
Scenario Selector	ui/scenarios.ts	Interactive scenario cards with MQTT activation
Live Feed	ui/feed.ts	Real-time MQTT message feed with AIS/ADS-B isolation
Formation Preview	map/formation-preview.ts	Leaflet polygon overlay for swarm formations
Track Drawing	map/track-draw.ts	Interactive multi-waypoint route drawing on map
Geofence Drawing	map/geofence-draw.ts	Interactive polygon drawing on map

Rivet Actor Framework

11 Actors Registered

#	Actor	Keying	Purpose
1	platformActor	per-platform	Telemetry state (pose, battery, velocity)
2	trackActor	per-track	Track lifecycle + classification aging
3	contactFusionActor	per-team	Haversine contact correlation across sources
4	taskActor	per-task	18-state task lifecycle machine
5	krogPolicyActor	per-policy	KROG 9-operator governance + audit
6	experimentActor	singleton	Memory-backed advisor for experiments
7	c2WorkflowActor	per-mission	Durable multi-step mission workflows
8	fleetActor	per-fleet	Heartbeat, detection relay, task redistribution
9	geofenceActor	per-mission	Polygon boundary + altitude ceiling/floor
10	faultActor	per-platform	GPS denial, battery, comms loss, platform loss
11	externalTrackActor	per-feed	AIS/ADS-B/radar ingest from Node-RED

Bridge → Rivet Integration (RivetClient)

Non-blocking HTTP client using ThreadPoolExecutor(max_workers=2) — fire-and-forget, error resilient, throttled logging.

Data	→ Actor	Action
Location (lat/lon/alt)	platformActor	updateLocation
Location	geofenceActor	checkPlatform
Battery (pct/voltage)	platformActor	updateBattery
Battery (pct)	faultActor	updateBattery
Velocity (speed/course)	platformActor	updateVelocity
Heartbeat	fleetActor	heartbeat
Governance audit	krogPolicyActor	evaluate

Rivet Configuration (bridge YAML)

rivet:
  enabled: true
  url: "http://rivet-actors:6430"
  timeout_s: 0.5
  fleet_key: "blue-fleet"     # team isolation key
  policy_key: "blue-policy"   # KROG policy instance
  fence_key: "mission-001"    # geofence instance

Team-vs-Team Topology

For multi-team exercises, configure different keys per side — each team's actors are fully isolated by instance key, zero code changes:

# Blue team                          # Red team
rivet:                               rivet:
  fleet_key: "blue-fleet"              fleet_key: "red-fleet"
  policy_key: "blue-policy"            policy_key: "red-policy"
  fence_key: "blue-geofence"           fence_key: "red-geofence"

ReductStore (MCAP Persistence)

Time-series object storage for MCAP recordings with automatic FIFO disk quota enforcement.

Setting	Value
Image	reduct/store:latest
Container	locust-reductstore
Port	8383 (Web UI + REST API)
Bucket	mcap-recordings
Quota	10 GB (FIFO eviction)
Auth	API token (RS_API_TOKEN)
Data path	/data (Docker volume: locust-reductstore-data)

# Verify ReductStore
curl -sf http://localhost:8383/api/v1/info | jq .

# Query recordings
python3 tools/reductstore-query.py

Testing

cd git/
source .venv/bin/activate

# Run all tests (757 tests)
pytest test/ -v

# With coverage (target: ≥ 80%)
pytest test/ --cov=ros2_4817_bridge --cov-report=html

# Rivet actor tests
cd ../rivet-actors && npm test

Verification

# Health checks
docker compose ps                                    # all containers "Up"
curl -sf http://localhost:9090/metrics | head -5      # bridge Prometheus
curl -sf http://localhost:8383/api/v1/info | jq .     # ReductStore
curl -sf http://localhost:6420/health                  # Rivet engine

# MQTT data flow
mosquitto_sub -h localhost -t '4817/#' -v -C 5       # see 5 messages

# Open live monitor
open tools/live-monitor.html                          # web-based dashboard

Documentation

All project documentation is in .settings/:

#	File	Purpose
0	0.DIAGRAM.md	System diagrams (Mermaid)
0	0.NAMING.md	Project naming & identity
0	0.STRAT.md	BLAST-OPS strategy
1	1.PROMPT.md	System prompt & data model reference
2	2.PRD.md	Product requirements
3	3.ARCHITECTURE.md	System architecture
4	4.CONTRACTS.md	MQTT contracts & payload schemas
5	5.SCAFFOLDING.md	Project structure
6	6.PIPELINE.md	Data pipeline
7	7.TASKS.md	Task backlog
8	8.TESTING.md	Testing strategy
9	9.GOVERNANCE.md	Data governance
10	10.CONOPS.md	Concept of operations
11	11.EXPERIMENTS.md	Experiment protocol
12	12.DEFINITIONS.md	Definitions & glossary
13	13.ALFUS.md	NIST ALFUS autonomy framework
15	15.DEVSETUP.md	Development environment setup
16	16.MISSION_ENGINE.md	Mission engine — waypoint missions, state machine, search patterns
17	17.COMMAND_CONTROL.md	Command & Control — operator commands, authority model
18	18.FAULT_INJECTION.md	Fault injection — GPS denial, comms loss, battery, CI scenarios
19	19.COORDINATION.md	Inter-platform coordination — fleet, detection relay, handoffs
20	20.ENVIRONMENT_SIM.md	Environment simulation — wind, sea state, currents, day/night
21	21.MCAP_SESSIONS.md	MCAP session capture — recording, replay, CI validation
22	22.COMMANDS.md	CLI command reference (all developer-facing commands)
23	23.REGULATORY_COMPLIANCE.md	Regulatory compliance — KROG, DIGDIR, EU AI Act, NATO RAI, NIS2
24	24.RIVET.md	Rivet actors — stateful runtime, 11 actor types, milestones
25	25.DEPLOYMENT.md	Deployment guide — local, dev lab, production architectures
26	26.GAP-TASKS.md	Gap analysis — operational readiness tasks
27	27.ReductStore-ROS2.md	ReductStore ROS2 extension — MCAP persistence pipeline
28	28.Convex.md	Convex reactive backend — schema, functions, integration guide

Technology Stack

Component	Choice
Language	Python 3.10+ (bridge), TypeScript (actors, monitor), Rust (Rivet engine)
ROS2	rclpy (Humble/Jazzy)
Flight controller	PX4 + uXRCE-DDS
MQTT	paho-mqtt / aiomqtt (MQTT 5.0)
JSON serialization	orjson
MCAP storage	ReductStore (time-series, FIFO quotas)
Reactive database	Convex (self-hosted, 12 tables, real-time subscriptions)
Actor runtime	Rivet (rivetkit TypeScript + Rust engine, PostgreSQL state)
State management	Zustand (client-side reactive stores)
Monitoring	Prometheus + Grafana
Visualization	Foxglove Studio, J.O.S.H.U.A. Monitor (Vite + Leaflet)
ML inference	ONNX Runtime (edge)
Container base	ros:jazzy-ros-base-noble / ros:humble
Orchestration	Docker Compose (local/dev) / Helm + RKE2 (production)

STANAG 4817 Version

Pinned to v0.3.0-rc2 (schemas in docs/4817-IDL/).

Repository

https://git.office.ilab.zone/RAID/R2D2-LOCUST.git

License

NATO / Coalition use. See project governance for classification and access policies.