PyDotBot

The control plane for the DotBot - 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.

▶️ Click to see a DotBot swarm in action

┌───────────┐           ┌────────────┐               ┌─────────┐
│  web UI / │           │            │               │         │
│   CLI /   │──REST/WS─▶│ controller │──serial/MQTT─▶│ gateway │──radio─▶ 🤖🤖🤖 DotBot swarm
│ your code │           │            │               │         │
└───────────┘           └────────────┘               └─────────┘
  ╰─────────── PyDotBot ───────────╯

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
• 🛰️ 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

Install

PyDotBot is available on PyPi, install it with:

pip install --pre pydotbot

Then, check your installation with dotbot --version and learn what's possible with dotbot --help.

Every command and flag is documented in the CLI reference.

Try the simulator

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/ :

dotbot run simulator -w

Drive the simulated bots from the UI, or run a bundled demo in a second terminal:

dotbot run demo circle   # drive one bot in a circle (the simplest demo)

Learn how to script the swarm from your own code, run the richer examples, and more - all with no hardware - in the simulator guide.

Deploy a real swarm

The DotBot is made to operate as a swarm, here is how you can deploy it on real robots.

Prerequisites

Minimal hardware setup:

• DotBot v3, as well as a USB-C cable and a barrel-jack charger (2.5 mm, 6–18 V, 5/10 A)
• nRF5340-DK to use as gateway, as well as a micro-USB cable

Software to install (as needed):

• Python ≥ 3.11 - ensure you also have pip available in your PATH
• nRF Command Line Tools (nrfjprog), for commands such as dotbot device flash

Setup

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.

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:

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

(device flash-mari-gateway / flash-swarmit-sandbox auto-fetch the firmware into ~/.dotbot/artifacts/ if it isn't already there.)

Now, run the gateway (the broker comes from your config):

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 🔄 🔄

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

(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.)

Then, flash another experiment:

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

Observe and control your swarm from a web interface:

dotbot run controller -w  # will open a webpage at http://localhost:8000/PyDotBot/

Full walkthrough of fleet operations - status, OTA flash, start/stop, monitor - is in the swarm reference.

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):

dotbot swarm stop                                              # bots 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.

Going further

• Drive a single bot end to end - build, flash, and control one DotBot: the one-bot guide.
• Position tracking with Lighthouse 2 - give the fleet real-world (x, y), calibrated over the air: the LH2 calibration guide (a cabled alternative is covered there too).
• The controller + web UI - drive and visualize a swarm from the browser: the controller guide.
• Build firmware from source instead of dotbot fw fetch - needs SEGGER Embedded Studio and a DotBot-firmware checkout:

  git clone --recurse-submodules --branch develop https://github.com/DotBots/DotBot-firmware.git
  export DOTBOT_FIRMWARE_REPO=$(pwd)/DotBot-firmware
  

  then dotbot fw build / dotbot fw artifacts (see fw).
• Everything else - the full dotbot CLI (fw / device / swarm / run
  • config), the REST/WS and MQTT surfaces, and hardware notes: the documentation.

Most of dotbot is in the base install; only LH2 calibration needs an extra:

pip install --pre 'pydotbot[calibrate]'   # opencv (the LH2 homography solve)

Hitting a snag (e.g. the web UI not loading in Firefox)? See Troubleshooting.

Tests

To run the tests, run tox:

tox

License

See LICENSE in each component repository.