`dotbot swarm` - operate the fleet over the air#

Run experiments across many DotBots at once. dotbot swarm drives the SwarmIT orchestration backend: it OTA-flashes a sandbox app to every DotBot, starts/stops it, and watches status - all wirelessly through a gateway.

For one cabled board, use device. To build the apps you flash, see fw. The host bridge and dashboard come from run.

The flow#

provision (once)   device flash-mari-gateway + device flash-swarmit-sandbox
host bridge        run gateway          (UART <-> MQTT)
build the payload  fw artifacts --sandbox  (or fw fetch)
operate            swarm               flash | start | stop | status | monitor

1. Provision once#

Each DotBot needs the SwarmIT sandbox-host firmware; the gateway is an nRF5340-DK running the Mari gateway firmware. Both are cabled flashes over USB-C (the DotBot v3 has an on-board programmer - no separate J-Link needed). Details and chip caveats live in device.

dotbot device flash-mari-gateway      --swarm-id 1234 --probe 10 -f 0.8.0rc1   # a DK -> gateway, net id 0x1234
dotbot device flash-swarmit-sandbox --swarm-id 1234 --probe 77 -f 0.8.0rc1   # each DotBot -> sandbox host

2. Start the host bridge#

The gateway board needs a host process bridging its UART to MQTT:

dotbot run gateway -m mqtts://argus.paris.inria.fr:8883 -p /dev/cu.usbmodem...

run gateway is the host process; device flash-mari-gateway flashed the firmware - same word, different objects.

3. Build the OTA payload#

The OTA payload is a sandbox app - a TrustZone non-secure .bin. Build it, or fetch a pre-compiled release:

dotbot fw artifacts --sandbox          # builds -> ~/.dotbot/artifacts/dotbot-firmware-local/<app>-sandbox-<board>.bin
dotbot fw fetch                        # or pull the pinned releases into ~/.dotbot/artifacts/<source>-<version>/

Sandbox apps include dotbot, move, rgbled, spin, timer. Artifact names look like spin-sandbox-dotbot-v3.bin. (Bare .hex apps are not OTA payloads - those are cabled via device flash.)

The common demos have short names, so you rarely type a path - see Flash by name below.

4. Connect#

The connection is given as global options before the subcommand, or in a .toml via -c:

Option	Meaning
`-n`, `--conn`, `--connection`	one string: `mqtts://host:port` (broker) or `/dev/ttyACM0` (serial gateway)
`-s`, `--swarm-id`	hex swarm id - required for MQTT, ignored for serial
`-c`, `--config-path`	a `.toml` carrying the same fields
`-b`, `--baudrate`	serial baudrate (default `1000000`)
`-d`, `--devices`	restrict to a comma-separated subset of addresses

See dotbot swarm --help for the full list.

dotbot config init --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234

This writes ./dotbot.toml; dotbot swarm discovers it from the current directory like the other dotbot commands (pass --conn / --swarm-id / -c to override). If the broker needs auth, set DOTBOT_MQTT_USER / DOTBOT_MQTT_PASS.

5. Operate the fleet#

dotbot swarm status                                # who's out there + their state
dotbot swarm status -w                             # keep watching
dotbot swarm flash spin -ys                        # flash a bundled demo by name
dotbot swarm stop                                  # back to bootloader (before re-flashing)
dotbot swarm start                                 # (re)start the loaded app
dotbot swarm monitor                               # tail SWARMIT_EVENT_LOG from bots
dotbot swarm message "hello"                       # custom text to the bots

To replace a running experiment: stop, then flash ... -ys.

Flash by name#

swarm flash takes either a bundled app name or an explicit .hex/.bin path. A name resolves to the matching <app>-sandbox-dotbot-v3.bin in your artifacts cache (run dotbot fw fetch first); a path is flashed as-is. List the names with dotbot swarm flash --list (they’re also summarized at the foot of dotbot swarm flash --help):

Name	Firmware	What it does
`rc-car`	`dotbot-sandbox-dotbot-v3.bin`	drive the DotBot from the UI / keyboard / joystick
`spin`	`spin-sandbox-dotbot-v3.bin`	the DotBots spin in place
`lights`	`rgbled-sandbox-dotbot-v3.bin`	the on-board RGB LED

For another board or an app outside this list, pass the full .bin path.

`swarm flash` flags#

Flag	Meaning
`--list`	print the bundled-app names and exit
`-y`, `--yes`	flash without the confirmation prompt
`-s`, `--start`	start the app once flashed
`-t`, `--ota-timeout`	seconds per OTA ACK (default `0.7`)
`-r`, `--ota-max-retries`	retries per OTA message (default `10`)

6. LH2 calibration over the air#

Capture and push a Lighthouse-2 calibration for one DotBot without a cable, driving it over the swarm. The arena geometry and -d sizing live in the LH2 calibration guide.

dotbot swarm stop                                              # capture only runs in READY
dotbot swarm lh2-calibration collect --device BC3D... -d 500   # capture from one DotBot -> solve -> save
dotbot swarm lh2-calibration push ~/.dotbot/calibrations/calibration-<UTC>.toml   # apply to every ready DotBot

collect walks one DotBot through the four arena corners over the air, solves the homography, and saves it under ~/.dotbot/calibrations/. push (no --device) then sends that calibration to every ready DotBot - the arena shares one transform. (collect --push is a single-DotBot shortcut: it sends only to the captured DotBot.) push takes a calibration-*.toml or the legacy raw payload - the format is picked by file extension. Get the --device address from dotbot swarm status.

Two web servers - don’t mix them up#

Command	What it serves	Default port
`dotbot run controller`	drive/visualize Web UI + REST/WS	`8000`
`dotbot swarm serve`	SwarmIT FastAPI orchestration backend	`8001`

dotbot swarm auto-discovers a running serve daemon; pass --no-server to skip the probe and run an in-process controller for that one invocation. Use serve --local for a zero-config local backend.

See dotbot swarm <command> --help for every flag.

dotbot swarm - operate the fleet over the air#