Merge pull request #266 from geonnave/config-cli-wiring

config: unify the dotbot CLI config into one file (dotbot -c config.toml)

Author: geonnave

AGENTS.md

@@ -27,7 +27,7 @@ pip install pydotbot                         # or `pip install -e .`
 dotbot --help                    # unified dispatcher: fw / device / swarm / run
 dotbot fw --help                 # firmware artifacts: build / fetch / list / make
 dotbot device --help             # one cabled device: flash an app/role, read info
-dotbot swarm --help              # the fleet over the air (optional: pip install pydotbot[swarm])
+dotbot swarm --help              # the fleet over the air (swarmit; in the base install)
 dotbot run --help                # host-side processes (controller, gateway, simulator, ...)
 dotbot run controller --help     # start the controller
 dotbot run lh2-calibration --help  # LH2 calibration (optional: pip install pydotbot[calibrate])
@@ -52,8 +52,9 @@ CI: `.github/workflows/continuous-integration.yml` — `tox` on Linux/macOS/Wind
 - **`PyDotBot-utils`** — `pyproject.toml:49`; used by `utils/hooks/sdist.py:build_frontend`
 - **`DotBot-libs`** — checked out in CI to build `utils/control_loop` C library
 - **`DotBot-firmware`** — referenced only in README (flashing instructions); no code dep
-- **`swarmit`** — optional sibling package (`pyproject.toml`'s
-  `[testbed]` extra); imported lazily inside `dotbot/cli/testbed.py`.
+- **`swarmit`** — sibling package, a core dependency (`pyproject.toml`);
+  imported lazily inside `dotbot/cli/swarm.py`, which bridges the unified
+  config's `conn`/`swarm_id` into swarmit's flags at the mount boundary.
 - **`dotbot-provision`** — vendored into `dotbot/provision/` (Phase 2,
   2026-05). Standalone PyPI package scheduled for deprecation.
 - **`dotbot-lh2-calibration` (Python)** — vendored into

README.md

@@ -42,7 +42,7 @@ talk to it, and it drives the swarm through a gateway.
 See the whole thing run with nothing but Python:
 
 ```bash
-pip install --pre pydotbot
+pip install --pre pydotbot  # using 'pre' while we are at release candidate
 dotbot run simulator -w   # opens the web UI at http://localhost:8000/PyDotBot/, driving a simulated swarm
 ```
 
@@ -61,11 +61,13 @@ import requests, time
 BASE = "http://localhost:8000"
 bot = requests.get(f"{BASE}/controller/dotbots").json()[0]["address"]
 
-# roll forward for ~1 s - the motors stop after 200 ms, so keep sending
-for _ in range(10):
+# roll in a circle for ~5 s - left_y and right_y are the two wheel speeds
+for _ in range(50):
     requests.put(f"{BASE}/controller/dotbots/{bot}/0/move_raw",
-                 json={"left_x": 0, "left_y": 60, "right_x": 0, "right_y": 60})
+                 json={"left_x": 0, "left_y": 60, "right_x": 0, "right_y": 30})
     time.sleep(0.1)
+requests.put(f"{BASE}/controller/dotbots/{bot}/0/move_raw",
+             json={"left_x": 0, "left_y": 0, "right_x": 0, "right_y": 0})
 ```
 
 The full surface - every endpoint, the live WebSocket stream, and CSV data
@@ -92,7 +94,7 @@ Minimal hardware setup:
 ## Install
 
 ```bash
-pip install --pre 'pydotbot[swarm]'   # --pre while 0.29 is in pre-release
+pip install --pre pydotbot   # --pre while 0.29 is in pre-release
 git clone --recurse-submodules --branch develop https://github.com/DotBots/DotBot-firmware.git
 ```
 
@@ -120,10 +122,13 @@ Every command and flag is documented in the [CLI reference][cli-doc].
 Build and flash firmware for a single dotbot:
 
 ```bash
-# build the bare dotbot app into ./artifacts/ (needs SEGGER Embedded Studio)
+# build the bare dotbot apps into ./artifacts/ (needs SEGGER Embedded Studio)
+# two steps because the DotBot has two cores
 dotbot fw artifacts --app dotbot
+dotbot fw artifacts --app nrf5340_net --target nrf5340dk-net
 # cable-flash it to the bot whose J-Link serial starts with 77
-dotbot device flash dotbot -s 77
+dotbot device flash dotbot -s 77  # app core
+dotbot device flash nrf5340_net -b nrf5340dk-net -s 77  # network core
 ```
 
 Now, build and flash the gateway to connect to a robot.
@@ -132,7 +137,7 @@ computer; it bridges the robot's radio to USB serial.
 
 ```bash
 # build the gateway firmware for your DK board into ./artifacts/ (needs SEGGER Embedded Studio)
-dotbot fw artifacts --app dotbot_gateway -t nrf52840dk
+dotbot fw artifacts --app dotbot_gateway --target nrf52840dk
 # cable-flash it to the DK whose J-Link serial starts with 10
 dotbot device flash dotbot_gateway -b nrf52840dk -s 10
 ```
@@ -151,60 +156,58 @@ and driving it from the web UI ([controller guide][controller-doc]).
 
 ### setup the swarm
 
-To operate as a swarm, we need to fetch some firmware, and setup a configuration file:
+To operate as a swarm, set your swarm connection config:
 
 ```bash
-# pull the pre-compiled firmwares from a release
-dotbot fw fetch -f 0.8.0rc1  # or build yourself with: dotbot fw artifacts --sandbox
-# configure where to connect and which swarm
-cat > swarm-config.toml <<'EOF'
-conn = "mqtts://argus.paris.inria.fr:8883"
-swarm_id = "1234"
-EOF
+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 - replace
-> `conn` and `swarm_id` with your own broker and swarm id (your testbed admin
-> provides these).
+> `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].
 
 The swarm mode also requires a special "sandbox" firmware in each dotbot.
-We also need a more powerful gateway firmware.
-Let's flash both:
+We also need a more powerful gateway firmware. Let's flash both - the network
+id comes from your config:
 
 ```bash
-dotbot device flash-mari-gateway -n 1234 -s 10 -f 0.8.0rc1  # flash the gateway, setting its swarm id to 0x1234
-dotbot device flash-swarmit-sandbox -n 1234 -s 77 -f 0.8.0rc1  # flash the sandbox firmware - do this on each dotbot
+dotbot fw fetch -f 0.8.0rc1  # pull the pre-compiled firmwares from a release
+dotbot device flash-mari-gateway -s 10 -f 0.8.0rc1  # flash the gateway
+dotbot device flash-swarmit-sandbox -s 77 -f 0.8.0rc1  # the sandbox firmware - do this on each dotbot
 ```
 
 (`device flash-mari-gateway` / `flash-swarmit-sandbox` auto-fetch
 the release into `./artifacts/` if it isn't already there.)
 
-Now, run the gateway:
+Now, run the gateway (the broker comes from your config):
 
 ```bash
-dotbot run gateway -m mqtts://argus.paris.inria.fr:8883 -p /dev/cu.usbmodem0010500324491
+dotbot run gateway -p /dev/cu.usbmodem0010500324491
 ```
 
 ### use the swarm
 
-
 You can flash as many dotbots as you want, all at once! First, how about making them spinnnn 🔄 🔄
 
 ```bash
-dotbot swarm -c swarm-config.toml flash ./artifacts/spin-sandbox-dotbot-v3.bin -ys  # flash the whole fleet with a simple spinning app
+dotbot swarm flash ./artifacts/spin-sandbox-dotbot-v3.bin -ys  # flash the whole fleet with a simple spinning app
 ```
 
+(`dotbot swarm` reads the same `dotbot.toml` as the rest - pass `--conn` /
+`--swarm-id` to override it for one run.)
+
 Then, flash another experiment:
 
 ```bash
-dotbot swarm -c swarm-config.toml stop  # ensure all robots are in bootloader
-dotbot swarm -c swarm-config.toml flash ./artifacts/dotbot-sandbox-dotbot-v3.bin -ys  # this firmware allows bots to be remote-controlled
+dotbot swarm stop  # ensure all robots are in bootloader
+dotbot swarm flash ./artifacts/dotbot-sandbox-dotbot-v3.bin -ys  # this firmware allows bots to be remote-controlled
 ```
 
 Observe and control your swarm from a web interface:
 
 ```bash
-dotbot run controller --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234 -w  # will open a webpage at http://localhost:8000/PyDotBot/
+dotbot run controller -w  # will open a webpage at http://localhost:8000/PyDotBot/
 ```
 
 Full walkthrough of fleet operations - status, OTA flash, start/stop, monitor -
@@ -222,8 +225,8 @@ dotbot device flash lh2_calibration -s 77
 dotbot run lh2-calibration collect -p /dev/tty.usbmodem0007745943981 -d 200  # square of side 20 cm
 
 # 2. push the resulting calibration to the fleet over the air
-dotbot swarm -c swarm-config.toml stop  # ensure all robots are in bootloader
-dotbot swarm -c swarm-config.toml calibrate-lh2 ~/.dotbot/calibration-2026-05-26T14-00-36Z.toml
+dotbot swarm stop  # ensure all robots are in bootloader
+dotbot swarm calibrate-lh2 ~/.dotbot/calibration-2026-05-26T14-00-36Z.toml
 ```
 
 Your bots now report their `(x, y)` location. The full setup - arena sizing,
@@ -236,12 +239,10 @@ Full command reference and guides - running the controller + web UI, the four
 CLI namespaces (`fw` / `device` / `swarm` / `run`), hardware, and LH2
 calibration - are in the [documentation][doc-link].
 
-Some commands need optional runtime deps:
+Swarm orchestration is in the base install. Only LH2 calibration needs an extra:
 
 ```bash
-pip install --pre 'pydotbot[swarm]'      # swarmit (fleet orchestration)
 pip install --pre 'pydotbot[calibrate]'  # opencv-python + textual (LH2 calibration)
-pip install --pre 'pydotbot[all]'        # everything
 ```
 
 Hitting a snag (e.g. the web UI not loading in Firefox)? See
@@ -274,6 +275,7 @@ See `LICENSE` in each component repository.
 [fw-doc]: https://pydotbot.readthedocs.io/en/latest/cli/fw.html
 [device-doc]: https://pydotbot.readthedocs.io/en/latest/cli/device.html
 [swarm-doc]: https://pydotbot.readthedocs.io/en/latest/cli/swarm.html
+[config-doc]: https://pydotbot.readthedocs.io/en/latest/reference/configuration.html
 [controller-doc]: https://pydotbot.readthedocs.io/en/latest/guides/controller.html
 [lh2-doc]: https://pydotbot.readthedocs.io/en/latest/guides/lh2-calibration.html
 [troubleshooting-doc]: https://pydotbot.readthedocs.io/en/latest/reference/troubleshooting.html

doc/cli/device.md

@@ -71,7 +71,7 @@ dotbot device flash nrf5340_net -b nrf5340dk-net -s 10
 | `-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) |
 | `--sandbox` | Resolve the sandbox-app flavor (`.bin`) |
-| `-c, --config` | `Debug` \| `Release` (default `Release`) |
+| `--build-config` | `Debug` \| `Release` (default `Release`) |
 
 ## Flash a role
 

doc/cli/fw.md

@@ -15,6 +15,9 @@ Studio (SES). Point the CLI at the checkout (otherwise it looks for
 
 ```bash
 export DOTBOT_FIRMWARE_REPO=/path/to/DotBot-firmware
+# or persist it once in ~/.dotbot/config.toml:
+#   [fw]
+#   firmware_repo = "/path/to/DotBot-firmware"
 ```
 
 ## Which command do I want?
@@ -43,7 +46,7 @@ Both share the same build options:
 |---|---|
 | `-a, --app <app>` | Build one app (default: every app for the target) |
 | `-t, --target <target>` | Board/target (default: `dotbot-v3`) |
-| `-c, --config Debug\|Release` | Build config (default: `Release`) |
+| `--build-config Debug\|Release` | Build configuration (default: `Release`) |
 | `--sandbox` | TrustZone NS flavor → `sandbox-<board>`, emits `.bin` |
 | `--rebuild` | Force a full rebuild (default: incremental) |
 | `-v, --verbose` | Full SES output |

doc/cli/swarm.md

@@ -14,7 +14,7 @@ see [`fw`](fw.md). The host bridge and dashboard come from [`run`](run.md).
 1. provision (once)   device flash-mari-gateway + device flash-swarmit-sandbox
 2. host bridge        run gateway          (UART <-> MQTT)
 3. build the payload  fw artifacts --sandbox  (or fw fetch)
-4. operate            swarm -c config  flash | start | stop | status | monitor
+4. operate            swarm               flash | start | stop | status | monitor
 ```
 
 ## 1. Provision once
@@ -70,24 +70,24 @@ The connection is given as global options *before* the subcommand, or in a
 See `dotbot swarm --help` for the full list.
 
 ```bash
-cat > tb-config.toml <<'EOF'
-conn = "mqtts://argus.paris.inria.fr:8883"
-swarm_id = "1234"
-EOF
+dotbot config init --conn mqtts://argus.paris.inria.fr:8883 --swarm-id 1234
 ```
 
-If the broker needs auth, set `DOTBOT_MQTT_USER` / `DOTBOT_MQTT_PASS`.
+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
 
 ```bash
-dotbot swarm -c tb-config.toml status                                # who's out there + their state
-dotbot swarm -c tb-config.toml status -w                             # keep watching
-dotbot swarm -c tb-config.toml flash ./artifacts/spin-sandbox-dotbot-v3.bin -ys
-dotbot swarm -c tb-config.toml stop                                  # back to bootloader (before re-flashing)
-dotbot swarm -c tb-config.toml start                                 # (re)start the loaded app
-dotbot swarm -c tb-config.toml monitor                               # tail SWARMIT_EVENT_LOG from bots
-dotbot swarm -c tb-config.toml message "hello"                       # custom text to the bots
+dotbot swarm status                                # who's out there + their state
+dotbot swarm status -w                             # keep watching
+dotbot swarm flash ./artifacts/spin-sandbox-dotbot-v3.bin -ys
+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`.
@@ -107,8 +107,8 @@ Send a calibration (captured from one cabled bot - see
 [LH2 calibration](../guides/lh2-calibration.md)) to the whole fleet:
 
 ```bash
-dotbot swarm -c tb-config.toml stop
-dotbot swarm -c tb-config.toml calibrate-lh2 ~/.dotbot/calibration-<UTC>.toml
+dotbot swarm stop
+dotbot swarm calibrate-lh2 ~/.dotbot/calibration-<UTC>.toml
 ```
 
 It accepts a `calibration-*.toml` or the legacy raw payload; the format is
@@ -118,7 +118,7 @@ picked by file extension.
 
 | Command | What it serves | Default port |
 |---|---|---|
-| `dotbot run controller --conn ... --swarm-id ... -w` | drive/visualize Web UI + REST/WS | `8000` |
+| `dotbot run controller -w` | 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

doc/conf.py

@@ -130,6 +130,10 @@
     # YouTube (demo video + its thumbnail) bot-blocks the linkcheck crawler.
     r"https://www\.youtube\.com/",
     r"https://img\.youtube\.com/",
+    # Badge services (shields.io, badge.fury.io) are decorative and
+    # intermittently time out or rate-limit the linkcheck bot.
+    r"https://img\.shields\.io/",
+    r"https://badge\.fury\.io/",
 ]
 
 # -- Options for autosummary/autodoc output -----------------------------------

doc/guides/controller.md

@@ -42,17 +42,22 @@ the UI with no robot or gateway.
 
 ## Use a config file
 
-Keep your connection settings in a TOML file instead of repeating flags:
+Save your connection once instead of repeating flags:
 
 ```bash
-# use settings from the config file
-dotbot run controller --config-path swarm-config.toml
+# save where to connect (writes ./dotbot.toml)
+dotbot config init --conn mqtts://broker:8883 --swarm-id 1234
 
-# use the config file but override the connection (run a simulator instead)
-dotbot run controller --config-path swarm-config.toml --conn simulator
+# the controller picks it up automatically when run from here
+dotbot run controller
+
+# override the saved connection for one run (a simulator instead)
+dotbot run controller --conn simulator
 ```
 
-CLI flags override config-file values when both are given.
+CLI flags override config-file values when both are given. See the
+[configuration reference](../reference/configuration.md) for how the file is
+discovered and the full schema.
 
 ## The web UI
 

doc/guides/lh2-calibration.md

@@ -88,8 +88,8 @@ Send the captured calibration over the air. Stop any running app first, then
 push the `.toml` (see [swarm](../cli/swarm.md) for the connection config):
 
 ```bash
-dotbot swarm -c tb-config.toml stop
-dotbot swarm -c tb-config.toml calibrate-lh2 ~/.dotbot/calibration-<UTC>.toml
+dotbot swarm stop
+dotbot swarm calibrate-lh2 ~/.dotbot/calibration-<UTC>.toml
 ```
 
 `calibrate-lh2` accepts either a `calibration-*.toml` or the legacy raw