DotBots · geonnave · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@
 The control plane for the [DotBot](http://www.dotbots.org) - a small wireless
 wheeled robot built to operate in large swarms, for research and education.
 
-PyDotBot allows you to flash a robot and control a whole fleet over the air,
-from one bot to a thousand.
+PyDotBot allows you to flash a DotBot and control a whole fleet over the air,
+from one DotBot to a thousand.
 
 [▶️ Click to see a DotBot swarm in action](https://www.youtube.com/watch?v=pXGTLqafReU)
 
@@ -25,8 +25,8 @@ from one bot to a thousand.
 
 **What you can do**
 
-- 🕹️ Drive one bot or a whole fleet from a **web UI** (live map + joystick) or your own **Python** code
-- 📡 Flash the swarm **over the air** - one command, hundreds of bots at once
+- 🕹️ Drive one DotBot or a whole fleet from a **web UI** (live map + joystick) or your own **Python** code
+- 📡 Flash the swarm **over the air** - one command, hundreds of DotBots at once
 - 🛰️ Get real-world **(x, y) positions** with Lighthouse 2 localization
 - 🧪 Try it all with **zero hardware** using the built-in simulator
 - 🛠️ One `dotbot` CLI takes you from build → flash → run
@@ -36,7 +36,7 @@ from one bot to a thousand.
 PyDotBot is available on [PyPi](https://pypi.org/project/pydotbot/), install it with:
 
 ```bash
-pip install --pre pydotbot
+pip install pydotbot
 ```
 
 Then, check your installation with `dotbot --version` and learn what's possible with `dotbot --help`.
@@ -50,14 +50,15 @@ See the whole thing run with nothing but Python!
 The command below will run a simulated swarm, which you can observe in a web UI at http://localhost:8000/PyDotBot/ :
 
 ```bash
-dotbot run simulator -w
+dotbot run simulator
 ```
 
-Drive the simulated bots from the UI, or run a bundled demo in a
+The web UI opens automatically; pass `--headless` to suppress it (it's still
+served). Drive the simulated DotBots from the UI, or run a bundled demo in a
 second terminal:
 
 ```bash
-dotbot run demo circle   # drive one bot in a circle (the simplest demo)
+dotbot run demo circle   # drive one DotBot in a circle (the simplest demo)
 ```
 
 Learn how to script the swarm from your own code, run the richer examples, and more - all with
@@ -85,19 +86,22 @@ To operate as a swarm, set your swarm connection config:
 dotbot config init --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234
 ```
 
-> `argus.paris.inria.fr` is our Inria Paris broker and `1234` our swarm - pass
-> your own `--conn` and `--swarm-id` (your testbed admin provides these). This
-> writes `./dotbot.toml`; commands run from this directory pick it up, so you
-> don't repeat the flags. Full schema: the [configuration reference][config-doc].
+> `--conn` is your MQTT broker and `--swarm-id` a 16-bit hex id that identifies
+> your swarm. Running your own handful of DotBots? Pick any swarm
+> id - the example points `--conn` at our Inria Paris broker so it works out of
+> the box, but swap in your own broker once you have one. (On a shared testbed,
+> your admin gives you the broker and swarm id to use.) This writes
+> `./dotbot.toml`; commands run from this directory pick it up, so you don't
+> repeat the flags. Full schema: the [configuration reference][config-doc].
 
-The swarm mode also requires a special "sandbox" firmware in each dotbot.
+The swarm mode also requires a special "sandbox" firmware in each DotBot.
 We also need a more powerful gateway firmware. Let's flash both - the network
 id comes from your config:
 
 ```bash
 dotbot fw fetch  # pull the pinned pre-compiled firmwares (swarmit + dotbot-firmware)
-dotbot device flash-mari-gateway -s 10  # flash the gateway
-dotbot device flash-swarmit-sandbox -s 77  # the sandbox firmware - do this on each dotbot
+dotbot device flash-mari-gateway --probe 10  # flash the gateway
+dotbot device flash-swarmit-sandbox --probe 77  # the sandbox firmware - do this on each DotBot
 ```
 
 (`device flash-mari-gateway` / `flash-swarmit-sandbox` auto-fetch
@@ -111,52 +115,71 @@ dotbot run gateway -p /dev/cu.usbmodem0010500324491
 
 ### Deploy and control
 
-You can flash as many dotbots as you want, all at once! First, how about making them spinnnn 🔄 🔄
+You can flash as many DotBots as you want, all at once! First, how about making them spinnnn 🔄 🔄
 
 ```bash
-dotbot swarm flash ~/.dotbot/artifacts/dotbot-firmware-1.22.0rc1/spin-sandbox-dotbot-v3.bin -ys  # flash the whole fleet with a simple spinning app
+# flash the whole fleet with a simple spinning app
+# the -ys flags confirms (y) the flash,
+# and tell the app to start (s) right away after flashing is done
+dotbot swarm flash spin -ys
 ```
 
 (`dotbot swarm` reads the same `dotbot.toml` as the rest - pass `--conn` /
-`--swarm-id` to override it for one run. That path is the `dotbot-firmware`
-release `dotbot fw fetch` cached - run `dotbot fw list` to see the exact paths
-and versions on your machine.)
+`--swarm-id` to override it for one run. `spin` is a bundled app name -
+`dotbot swarm flash --list` shows them all, and an explicit `.bin` path still
+works. Names resolve to what `dotbot fw fetch` cached; `dotbot fw list` shows
+the exact paths and versions on your machine.)
 
 Then, flash another experiment:
 
 ```bash
-dotbot swarm stop  # ensure all robots are in bootloader
-dotbot swarm flash ~/.dotbot/artifacts/dotbot-firmware-1.22.0rc1/dotbot-sandbox-dotbot-v3.bin -ys  # this firmware allows bots to be remote-controlled
+dotbot swarm stop  # ensure all DotBots are in bootloader
+dotbot swarm flash rc-car -ys  # this firmware lets DotBots be remote-controlled
 ```
 
 Observe and control your swarm from a web interface:
 
 ```bash
-dotbot run controller -w  # will open a webpage at http://localhost:8000/PyDotBot/
+dotbot run controller  # opens a webpage at http://localhost:8000/PyDotBot/
 ```
 
 Full walkthrough of fleet operations - status, OTA flash, start/stop, monitor -
 is in the [`swarm` reference][swarm-doc].
 
 ### Calibrate positions (optional)
 
-Give the bots real-world `(x, y)` with Lighthouse 2 - capture once from any bot
-over the air, then push the result to the whole fleet (needs the `[calibrate]`
-extra, below):
+Give the DotBots real-world `(x, y)` with Lighthouse 2. It's a two-step flow:
+**collect** a calibration from one DotBot over the air, then **push** it to the
+whole fleet - a single DotBot's capture calibrates the shared arena. This needs
+the `[calibrate]` extra (opencv, for the homography solve):
 
 ```bash
-dotbot swarm stop                                              # bots must be idle to capture
+pip install 'pydotbot[calibrate]'
+```
+
+First, collect from one DotBot. Get its address from `dotbot swarm status` (the
+**Device Addr** column):
+
+```bash
+dotbot swarm status                                           # pick one Device Addr, e.g., BDF2B04BC00D2725
+dotbot swarm stop                                             # DotBots must be idle to capture
 dotbot swarm lh2-calibration collect --device <addr> -d 500   # capture + solve + save
-dotbot swarm lh2-calibration push ~/.dotbot/calibration-<UTC>.toml  # apply to every bot
 ```
 
-`-d` is your reference square's side, in mm (one bot's capture calibrates the
-whole arena). Full walkthrough - arena sizing and the cabled alternative - is in
-the [LH2 calibration guide][lh2-doc].
+`-d` is your reference square's side, in mm. This saves a
+`~/.dotbot/calibrations/calibration-<UTC>.toml`. Then push that file to the
+whole fleet:
+
+```bash
+dotbot swarm lh2-calibration push ~/.dotbot/calibrations/calibration-<UTC>.toml
+```
+
+Full walkthrough - arena sizing and the cabled alternative - is in the
+[LH2 calibration guide][lh2-doc].
 
 ## Going further
 
-- **Drive a single bot** end to end - build, flash, and control one DotBot:
+- **Drive a single DotBot** end to end - build, flash, and control one DotBot:
   the [one-bot guide][one-bot-doc].
 - **Position tracking with Lighthouse 2** - give the fleet real-world `(x, y)`,
   calibrated over the air: the [LH2 calibration guide][lh2-doc] (a cabled
@@ -175,12 +198,6 @@ the [LH2 calibration guide][lh2-doc].
   + `config`), the REST/WS and MQTT surfaces, and hardware notes: the
   [documentation][doc-link].
 
-Most of `dotbot` is in the base install; only LH2 calibration needs an extra:
-
-```bash
-pip install --pre 'pydotbot[calibrate]'   # opencv (the LH2 homography solve)
-```
-
 Hitting a snag (e.g. the web UI not loading in Firefox)? See
 [Troubleshooting][troubleshooting-doc].
 

diff --git a/doc/cli/device.md b/doc/cli/device.md
@@ -41,7 +41,7 @@ export DOTBOT_FIRMWARE_REPO=$(pwd)/repos/DotBot-firmware
 
 # Build, then flash the bare DotBot app onto a DotBot v3 (board defaults to dotbot-v3)
 dotbot fw artifacts --app dotbot
-dotbot device flash dotbot -s 77
+dotbot device flash dotbot --probe 77
 ```
 
 `-b/--board` selects the **chip family and core** to program. The nrfjprog family
@@ -55,7 +55,7 @@ e.g. don't flash an nRF53 image onto a connected nRF52 (or vice versa).
 ```bash
 # Gateway onto an nRF52840-DK (device flash picks -f NRF52 from the board)
 dotbot fw artifacts --app dotbot_gateway -t nrf52840dk
-dotbot device flash dotbot_gateway -b nrf52840dk -s 10
+dotbot device flash dotbot_gateway -b nrf52840dk --probe 10
 ```
 
 ### nRF5340 = two cores
@@ -67,19 +67,19 @@ net-core image. Build and flash each for its own target - the app image is
 ```bash
 # App core
 dotbot fw artifacts --app dotbot_gateway -t nrf5340dk-app
-dotbot device flash dotbot_gateway -b nrf5340dk-app -s 10
+dotbot device flash dotbot_gateway -b nrf5340dk-app --probe 10
 
 # Net core (-b *-net routes to CP_NETWORK)
 dotbot fw artifacts --app nrf5340_net -t nrf5340dk-net
-dotbot device flash nrf5340_net -b nrf5340dk-net -s 10
+dotbot device flash nrf5340_net -b nrf5340dk-net --probe 10
 ```
 
 **`flash` flags** (see `dotbot device flash --help` for the full list):
 
 | Flag | Meaning |
 |---|---|
 | `-b, --board` | Target board → chip family + core (default `dotbot-v3`) |
-| `-s, --sn-starting-digits` | J-Link serial **prefix**, e.g. `77` (v3) or `10` (DK) |
+| `--probe` | J-Link serial **prefix**, e.g. `77` (v3) or `10` (DK); omit it when only one probe is attached |
 | `--sandbox` | Resolve the sandbox-app flavor (`.bin`) |
 | `--build-config` | `Debug` \| `Release` (default `Release`) |
 
@@ -91,17 +91,17 @@ named release into `~/.dotbot/artifacts/` if it isn't cached.
 
 ```bash
 # nRF5340-DK → swarm gateway
-dotbot device flash-mari-gateway --swarm-id 0100 -f 0.8.0rc1 -s 10
+dotbot device flash-mari-gateway --swarm-id 0100 -f 0.8.0rc1 --probe 10
 
 # DotBot v3 → swarm sandbox host (the firmware that runs OTA apps)
-dotbot device flash-swarmit-sandbox --swarm-id 0100 -f 0.8.0rc1 -s 77
+dotbot device flash-swarmit-sandbox --swarm-id 0100 -f 0.8.0rc1 --probe 77
 ```
 
 | Flag | `flash-mari-gateway` | `flash-swarmit-sandbox` |
 |---|---|---|
 | `--swarm-id` | 16-bit hex swarm id (or from config) | 16-bit hex swarm id (or from config) |
 | `-f, --fw-version` | release to flash (default: the pinned swarmit version) | release to flash (default: the pinned swarmit version) |
-| `-s, --sn-starting-digits` | J-Link serial prefix | J-Link serial prefix |
+| `--probe` | J-Link serial prefix | J-Link serial prefix |
 | `-l, --calibration` | - | optional LH2 calibration file to bake in |
 
 A board flashed with `flash-swarmit-sandbox` is what [`swarm flash`](swarm.md)
@@ -110,7 +110,7 @@ targets to run sandboxed apps over the air.
 ## Inspect a board
 
 ```bash
-dotbot device info -s 77
+dotbot device info --probe 77
 ```
 
 Reports the chip id and network identity. It never fails on a blank board - it

diff --git a/doc/cli/index.md b/doc/cli/index.md
@@ -11,7 +11,7 @@ config
 
 One CLI for the whole DotBot workflow: build firmware, flash one board, control a
 whole swarm, and launch the host-side processes that tie it together -
-from one bot to a thousand.
+from one DotBot to a thousand.
 
 ```bash
 dotbot --help
@@ -25,7 +25,7 @@ dotbot --help
 |---|---|---|
 | [`fw`](fw.md) | Build, fetch, and list firmware files. No hardware needed. | You want a `.hex`/`.bin` to flash later, or to see what builds. |
 | [`device`](device.md) | Flash one cabled board and read its info. | A DotBot or DK is plugged into your USB port right now. |
-| [`swarm`](swarm.md) | Drive the whole fleet over the air - status, OTA flash, start/stop, monitor. | You're operating many provisioned bots through a gateway. |
+| [`swarm`](swarm.md) | Drive the whole fleet over the air - status, OTA flash, start/stop, monitor. | You're operating many provisioned DotBots through a gateway. |
 | [`run`](run.md) | Start host processes on your computer - controller, gateway bridge, simulator, demos, teleop. | You need the web UI, a gateway bridge, the simulator, or a demo. |
 
 Beyond the four namespaces, [`config`](config.md) scaffolds and inspects the

diff --git a/doc/cli/run.md b/doc/cli/run.md
@@ -14,7 +14,7 @@ dotbot run --help        # the full list
 | `controller` | Control plane: REST/WS API + web dashboard. The hub everything else talks to. |
 | `gateway` | Host bridge: gateway firmware UART ↔ MQTT broker. |
 | `simulator` | Standalone simulator (no hardware). |
-| `lh2-calibration` | LH2 calibration on one cabled board (capture / apply); deployed bots use `swarm lh2-calibration`. |
+| `lh2-calibration` | LH2 calibration on one cabled board (capture / apply); deployed DotBots use `swarm lh2-calibration`. |
 | `demo` | Built-in research demos (qrkey phone bridge, …). |
 | `keyboard` | Drive a DotBot from the keyboard. |
 | `joystick` | Drive a DotBot from a joystick. |
@@ -26,16 +26,16 @@ Connect to a swarm and serve the dashboard at `http://localhost:8000/PyDotBot/`.
 `simulator`.
 
 ```bash
-dotbot run controller --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234 -w
-dotbot run controller --conn /dev/ttyACM0 -w
+dotbot run controller --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234
+dotbot run controller --conn /dev/ttyACM0
 ```
 
 | Flag | Meaning |
 |---|---|
 | `-n/--conn` | `mqtts://host:port`, serial path, or `simulator` |
 | `-s/--swarm-id` | hex swarm id - **required for MQTT**, ignored for serial/simulator |
-| `-w/--webbrowser` | open the dashboard automatically |
-| `--csv-data-output` | record robot data to a CSV file |
+| `--headless` | don't open the dashboard in a browser (it's still served) |
+| `--csv-data-output` | record DotBot data to a CSV file |
 
 Full options and the dashboard tour live in
 [the controller guide](../guides/controller.md). See `dotbot run controller --help`.
@@ -60,15 +60,15 @@ No hardware, no gateway. Exactly equivalent to `run controller --conn simulator`
 so it shares the controller's flags and serves the same dashboard.
 
 ```bash
-dotbot run simulator -w
+dotbot run simulator
 ```
 
 ## `lh2-calibration` - capture & apply (cabled)
 
 Lighthouse v2 calibration against a single serial-attached board. `collect`
 opens a TUI to capture LH2 counts; `apply` writes the saved calibration out as
-a C header. This is the cabled, bench path - for deployed bots, capture over the
-air with [`swarm lh2-calibration`](swarm.md) instead.
+a C header. This is the cabled, bench path - for deployed DotBots, capture over
+the air with [`swarm lh2-calibration`](swarm.md) instead.
 
 ```bash
 dotbot run lh2-calibration collect
@@ -90,7 +90,7 @@ dotbot run demo qr          # qrkey phone bridge
 
 Drive a DotBot live through a running controller (start one with
 `run controller` first). Both default to `localhost:8000`; pass `-d` to target a
-specific robot by hex address.
+specific DotBot by hex address.
 
 ```bash
 dotbot run keyboard