Multi-UAV ROS 2 Stack (Sim + MAVSDK-ready)

This folder (uav_github/) is a clean GitHub-exportable snapshot of the workspace. It contains the ROS 2 packages (src/), launch entrypoints, scripts, and example data.

What this repo demonstrates

An end-to-end multi-UAV pipeline:

• Perception publishes detections with explicit time + frame.
• Projection turns pixel detections into a metric, frame-consistent target.
• Orchestrator tracks/filters detections and produces goals.
• Agents execute goals (simulated or MAVSDK-backed) and publish a minimal TF tree.

The goal is not “perfect perception.” The goal is production-shaped contracts and runtime discipline.

Project maturity (read this first)

This repository is in the introduction / MVP phase: it is an engineering platform and demo stack, not firefighter-ready operational software.

Short, honest answer: when can it become top-tier?

• Not in months. Expect roughly 2–3 years with focused engineering, field testing, and safety validation to reach a “top-tier” level appropriate for public-safety operations.
• Today, this stack is roughly TRL 3–4 (architecture in place, lab/sim validated). Firefighter deployment typically demands TRL 7–8 (field-validated reliability + safety case).

If you see anything claiming “production wildfire UAV software” in 6–12 months, it’s usually either a demo, a one-off prototype, or dangerously under-validated.

Key contracts (production-shaped)

Message contracts are intentionally explicit:

• multi_uav_msgs/msg/DetectionPixel
  • published on /detections_pixel
  • contains (u, v) pixel coordinates, image size, confidence, covariance, and header.frame_id = camera frame
• multi_uav_msgs/msg/Detection
  • published on /detections
  • metric position in a declared frame_id (currently map), plus covariance + source

UavStatus and UavGoal also carry std_msgs/Header + frame_id so frames/time are always declared.

Minimal TF tree

Each UAV publishes a minimal transform chain:

• map -> <uav>/odom (static, identity)
• <uav>/odom -> <uav>/base_link (dynamic, UAV pose)
• <uav>/base_link -> <uav>/camera_link (static)

Pixel detections are published in <uav>/camera_link and projected into map.

How the “true distance” works (Option A)

Detectors do not invent metric world coordinates.

1. A detector produces a pixel centroid in camera frame (DetectionPixel on /detections_pixel).
2. The projection node (detector/pixel_projection_node) does a ray–ground-plane intersection using TF, and republishes a metric Detection on /detections.

Assumptions in the current minimal implementation:

• A ground plane at z = ground_z (default 0.0).
• Camera model uses a simple FOV-based pinhole approximation (fov_x_deg, fov_y_deg).

This is a deliberate “production step”: time+frame are explicit, and projection is centralized.

What’s included

• Packages under uav_github/src/:
  • uav_agent: simulated agent + MAVSDK agent
  • orchestrator: fleet orchestration + detection confirmation logic
  • detector: pixel detectors + projection node
  • map_merge: basic occupancy grid merge
  • multi_uav_msgs: message definitions
• Launch entrypoint (canonical): orchestrator/sim_multi_uav.launch.py
• Scripts: uav_github/scripts/ (tests + helpers)
• Example data: uav_github/data/images/

Requirements

• Ubuntu + ROS 2 Jazzy
• colcon
• (Optional, MAVSDK mode) Python deps: pip install -r uav_github/requirements.txt

Operational assumptions (important)

• Time base: The stack assumes all nodes share a consistent ROS clock. In simulation, set /use_sim_time consistently across nodes. Mixed wall-time vs sim-time will cause staleness filters and TF lookups to drop messages.
• Frame authority: The metric detection contract (multi_uav_msgs/msg/Detection) is expected to be in frame_id=map by default. Pixel detections must set header.frame_id to the camera frame (<uav>/camera_link).
• Failure semantics:
  • If projection cannot resolve TF (map <- camera_frame), or the ray does not intersect the ground plane, the detection is dropped (no metric output is published).
  • If detections are stale beyond configured thresholds, they are dropped.
  • These drops are reported via structured logs (event=... reason=...).
• Safety disclaimer: This repo is a research/demo stack and is not flight-safety certified. Do not use it to control real vehicles without a full safety case, geofencing, failsafes, and independent verification.

Roadmap to firefighter-grade (no fluff)

Top-tier public-safety deployment is not a feature sprint. It is discipline, traceability, and boring reliability.

Phase 1 — Architectural hardening (0–6 months)

Goal: make the stack difficult to misuse accidentally; ensure behavior is repeatable and auditable.

• Freeze and enforce contracts (headers, frames, covariance semantics) with tests that fail loudly.
• Deterministic orchestration (explicit state machine, timeout-driven transitions, no implicit behavior).
• Camera model realism: replace FOV approximation with real intrinsics/extrinsics (still monocular + ground plane).
• Offline replay discipline: every mission records a rosbag; CI can replay bags and validate outputs.

Target outcome: TRL 4 → TRL 5 (credible engineering platform).

Phase 2 — Autonomy reliability (6–18 months)

Goal: survive reality (smoke, comms drops, GPS degradation, wind, sensor faults).

• Multi-frame tracking and multi-UAV fusion (single-frame triggers are not acceptable).
• Navigation stack integration (avoidance, wind/terrain considerations) and robust mission execution.
• Comprehensive failsafes with defined states + actions (loss of comms/GPS/EKF degradation/battery anomalies).
• Human-in-the-loop UI: mission modes, live detections with uncertainty, operator override always available.

Target outcome: TRL 6–7 (field-testable with supervision).

Phase 3 — Certification & trust (18–36 months)

Goal: be allowed to operate.

• Safety case + hazard analysis (FMEA), operational envelope, explicit non-goals.
• Redundancy and conservative behavior under uncertainty.
• Regulatory alignment (airspace/BVLOS readiness, emergency services protocols).

Target outcome: TRL 8 (where real firefighter deployments begin).

Build

From inside uav_github/:

source /opt/ros/jazzy/setup.bash
rosdep update
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

Run (simulation)

Launch the full stack (recommended):

source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 launch orchestrator sim_multi_uav.launch.py

Deterministic demo (image -> pixel detection -> projection -> threat goal), with exploration disabled:

source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 launch orchestrator sim_multi_uav.launch.py \
  enable_explore:=false \
  image_path:=data/images/firephoto.jpeg

Tests

cd uav_github
bash scripts/run_tests.sh

Debug capture (rosbag)

To record a reproducible bag containing the perception/projection/orchestration topics:

cd uav_github
source /opt/ros/jazzy/setup.bash
source install/setup.bash
bash scripts/record_debug_bag.sh --duration 30

Notes

• colcon test may report “NO TESTS RAN” for some Python packages; the intended unit tests are executed by scripts/run_tests.sh.
• If you see “clock skew detected” during build, your system clock is out of sync; the build still completes but you should fix NTP for reliable CI.