ROS 2 counter-UAS research stack from Fratres X AI
Physics-first sensing, fusion, and autonomy scaffolding — reviewable, gated, and honest about maturity

Quick start · Architecture · Maturity · Docs · fratres-x.com

---

ClearSky OS is the open ROS 2 workspace behind Fratres X AI’s counter-UAS research thread: multimodal sensing → fusion → safety gates → operator-facing decision support, with an immutable audit spine.

Built the Fratres X way — physics first, conservative claims, systems built for scrutiny. No AI magic. No inflated readiness.

Safety: No autonomous weapon release. Kinetic / last-resort simulation paths stay policy-off by default. Human-on-the-loop is required for mitigation recommendations.

Why this repo

Focus	What you get
Integration skeleton	Docker-first ROS 2 Kilted workspace with CI on every push
Reviewable control path	Detect → track → fuse → gate → plan, with inspectable topics
Safety-encoded posture	Confidence gates, human veto, IFF lockout, kinetic defaults off
Audit spine	Hash-chained event trail for after-action replay
Honest boundaries	Stub vs production adapters called out in docs — replace, don’t pretend

Quick start

Supported method: Docker only.

CLEARSKY_LAUNCH_FILE=clearsky_os_basic_demo.launch.py \
  docker compose -f docker/docker-compose.yml up --build

Inside the container:

cd /opt/clearsky_os_ws
source /opt/ros/kilted/setup.bash
./clean-build.sh
ros2 launch clearsky_os_bringup clearsky_os_basic_demo.launch.py

Smoke-check:

ros2 topic list | grep -E '^/fused_tracks|^/audit/events|^/safety_gate_status|^/effector/'

See docs/TESTING.md.

Architecture

flowchart LR
  payloadSelector[payload_selector.yaml] --> bringup[clearsky_os_bringup]
  bringup --> sensors[sensors]
  bringup --> fusion[fusion]
  bringup --> safetyGate[safety_gate]
  bringup --> cognitive[cognitive]
  sensors --> fusion
  fusion --> fusedTracks[/fused_tracks/]
  fusedTracks --> cognitive
  safetyGate --> safetyStatus[/safety_gate_status/]
  safetyStatus --> cognitive
  cognitive --> audit[/audit/events/]
  cognitive --> xai[/xai_explanation/]

Loading

Default demo chain: sensors → fusion → audit → safety gate → scout / micro-payload sim → operator copilot → non-kinetic-first effector planning.

Maturity

ClearSky OS is an active research / prototype workspace, not a fielded product.

Layer today	Status
Topic contracts, bringup, Docker, CI	Stable scaffolding
Safety / effector policy gates	Real software logic
Visual perception	YOLO path when CLEARSKY_SIM_MODE=false + weights; labeled synthetic tracks in sim mode
Fusion	Constant-velocity EKF with Mahalanobis association (cv_ekf)
Digital twin	Analytic now-cast + Gazebo-compatible rollout backend → /digital_twin/veto
Sim / Gazebo	clearsky_os_sim truth bridge + worlds/clearsky_cuas.sdf (CI uses kinematics)
Acoustic / RF	Band-energy / spectral heuristics; optional ONNX when weights present
Thermal	Labeled synthetic stub
Fusion	CV-EKF authoritative + multimodal adapters; learned association on /fusion/learned_tracks (shadow)
Scout mothership	Enrichment of fused tracks (coverage/mesh) — does not invent PID tracks
Effector envelopes	Analytic Friis / success probability on /effector/status + plan XAI
Effector / swarm inventory pubs	Simulation status publishers — not hardware actuation

# Real vision (requires: pip install -r requirements-ml.txt && python scripts/download_visual_weights.py)
CLEARSKY_SIM_MODE=false CLEARSKY_VISUAL_SOURCE=/path/to/video.mp4 \
  docker compose -f docker/docker-compose.yml up --build

# Export YOLO → ONNX (Jetson: --format engine on the target)
python scripts/model_export.py --weights models/visual/yolo11n.pt

# Jetson profile (NVIDIA runtime + ML image)
docker compose -f docker/docker-compose.yml --profile jetson up --build

# Offline fusion / acoustic-RF / learned-shadow metrics
python scripts/eval_fusion_offline.py
python scripts/eval_acoustic_rf_offline.py
python scripts/eval_fusion_learned_offline.py

# Metric sim sensors (optional): override live sensor topics from truth bridge
# sim_override_sensors:=true  (or features.sim_override_sensors in payload_selector.yaml)

If you need production sensing, fusion, or autonomy work, talk to us at fratres-x.com.

Repository map

├── src/        # ROS 2 packages
├── docker/     # Supported runtime
├── config/     # Shared YAML
├── launch/     # Top-level launches
├── docs/       # Architecture + testing
├── k8s/        # Example edge manifests
├── scripts/    # Scenario / HIL helpers
└── assets/     # Branding

Documentation

Doc	Purpose
docs/ARCHITECTURE.md	Module topology & data flow
docs/COGNITIVE_ARCHITECTURE.md	Cognitive adjunct roadmap
docs/TESTING.md	Build, test, smoke validation
CONTRIBUTING.md	Dev setup & PR expectations
SECURITY.md	Vulnerability reporting

Contributing

PRs that harden physics adapters, fusion tests against production modules, and safety-gate regressions are especially welcome. See CONTRIBUTING.md.

License

Copyright © 2026 Fratres X AI.

Licensed under the Apache License, Version 2.0. See NOTICE.