Coordinated Swarm Exploration with ROS 2

ROS 2 workspace for multi-robot swarm exploration. Four TurtleBot3 Waffle robots autonomously explore a complex maze using decentralized frontier-based navigation. Gazebo sim runs headless and Foxglove provides the visualisation UI.

Written in Python with ROS 2 Jazzy, the codebase includes SLAM, Nav2, a custom frontier detector, and a per-robot FSM. Robots coordinate via geodesic Voronoi partitioning: a simultaneous multi-source BFS divides the merged map so each robot owns the region it can reach fastest, then selects the nearest frontier within its partition. This eliminates duplicate work without any central coordinator. See ARCHITECTURE.md for a full description.

The dev container forwards the host Docker socket, so docker compose commands work from inside it.

• Docker (Desktop or Engine)
• VS Code with the Dev Containers extension (ms-vscode-remote.remote-containers)

1. Clone this repo and open the folder in VS Code.
2. When prompted, click Reopen in Container (or F1 → Dev Containers: Reopen in Container).
3. VS Code builds the image from .devcontainer/Dockerfile.dev and mounts the workspace at /ws.
4. pre-commit install runs automatically on first open.

The dev container includes ROS 2 Jazzy, ruff, mypy, pre-commit, and recommended VS Code extensions (Ruff, Pylance, ROS, XML, TOML, Claude Code).

From the workspace root — either on the host or from a terminal inside the dev container:

make build    # Build the sim image (only needed after Dockerfile or dependency changes)
make up       # Start the full 4-robot stack
make down     # Stop and remove containers
make rebuild  # Build then start in one step
make logs     # Follow logs from all running services

This starts seven services:

Stop with Ctrl-C or make down.

Fast (headless) — validates launch file syntax and node imports in seconds, no display needed:

make test        # docker build --target test .

Live single-robot — starts Gazebo with one robot to verify the full exploration stack end-to-end:

make single      # docker compose --profile single up

Run headless at maximum simulation speed and record a bag (auto-stops when all robots reach DONE):

make record           # headless only
make record FOXGLOVE=1  # also start the Foxglove bridge
make record EXPLORE=60  # stop at 60% exploration
make record TIMEOUT=300  # stop after 300 seconds

Bags are written to ./bags/.

Open Foxglove (Desktop or web):

1. New connection → Foxglove WebSocket → ws://localhost:8765
2. Set fixed frame to world.

Useful topics:

A pre-built dashboard layout is in config/foxglove/swarm_ws.json — import it via File → Import layout.

Hooks run automatically before every commit. To run manually:

pre-commit run --all-files

Update hook versions:

pre-commit autoupdate

• Port 8765 in use: stop any process on that port and rerun docker compose up.
• No map updates: SLAM and the global map merge start with timed delays — wait ~25 s after the stack is up before expecting /merged_map or /frontiers.
• Robots not moving: the FSM enters EXPLORING only after frontiers appear on /frontiers; allow time for SLAM to build initial maps.
• Missing ROS packages in sim image: rebuild with docker compose build.
• DDS participant index errors: CycloneDDS is configured with MaxAutoParticipantIndex: 200 to handle 30+ nodes; if you see index collisions check the CYCLONEDDS_URI env var in compose.yaml.