RootWeaver.jl

Distributed robots that discover one another, grow an exit-rooted tree, and spread out where they are useful.

Julia 1.10+ · continuous unicycle motion · lossy indoor radio · no team-size oracle

RootWeaver solves a deployment problem for robots that begin scattered inside a known building. A robot initially knows only itself. It moves toward the exit, learns teammates only through successfully decoded packets, attaches to a locally believed rooted branch, and then expands the formation to improve visibility across free space. No controller waits for global connectivity or receives the complete team roster.

See it run

Synthetic office	Nav2 Depot	Radish Intel Lab
90.1 s · 25.1% discovery	99.0 s · 28.2% discovery	101.6 s · 12.3% discovery

The three demos use eight robots, the same seed, and the same realistic-radio controller. All terminate locally and globally rooted with zero wall or robot penetrations. Discovery ratios are environment-dependent and are not intended as a cross-map score.

The algorithm

Each robot runs the same asynchronous state machine:

1. Seek — head toward a deterministic exit staging point while knowing no teammates.
2. Attach — when decoded gossip reveals a rooted peer, select a reachable local target whose Gaussian visibility contour connects the robot to the exit-rooted component.
3. Expand — bid on nearby targets by local discovery gain, travel cost, and information age. Expiring leases settle competing target claims.
4. Repair — release stale parent links and reconnect to a fresh rooted peer or the exit.

An inflated-grid A* path supplies global guidance. An acceleration-limited DWA controller follows that path with continuous unicycle motion while treating root-link margin as a soft cost. Identity, poses, parent links, targets, and claims enter a controller only through successful one-hop packets and later gossip.

Read the environment and model details →

Quick start

git clone <your-rootweaver-url>
cd RootWeaver.jl
julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. --threads=auto bin/rootweaver.jl run configs/synthetic.toml

The run writes summary.json, a complete run.jld2, robot/network/auction CSV traces, actual.mp4, and belief_r0.mp4 under output/demo/.

Run the included environments:

julia --project=. --threads=auto bin/rootweaver.jl run configs/depot.toml --output output/depot
julia --project=. --threads=auto bin/rootweaver.jl run configs/intel-lab.toml --output output/intel-lab

Re-render a saved local-belief view:

julia --project=. bin/rootweaver.jl animate output/depot/run.jld2 \
  --view belief --robot r0 --output output/depot/belief-r0.mp4

Package API

using RootWeaver

config = load_config("configs/depot.toml")
result = simulate(config)
write_results(result, "output/depot")
render_mp4(result, "output/depot/actual.mp4")

Test

julia --project=. -e 'using Pkg; Pkg.test()'

Repository layout

src/       continuous motion, radio, belief, auction, simulation, rendering
bin/       run and animate CLI
configs/   ready-to-run synthetic, Depot, and Intel Lab environments
maps/      versioned public map fixtures and attribution
assets/    README artwork and compact demo animations
test/      geometry, radio, algorithm, determinism, safety, and output tests

RootWeaver.jl is available under the MIT License. Public map assets retain their respective licenses; see THIRD_PARTY.md.