Where do you want to start?

New here? DotBots are small wheeled robots you drive from your browser or your own code - one bot, or a swarm of hundreds. Pick a starting point:

  • Try it with no hardware - the simulator runs the full web UI with no bot or gateway needed: dotbot run simulator -w. See the simulator guide.

  • Get one bot moving - build and cable-flash a single DotBot and gateway, then drive it from the browser. See the one-bot guide.

  • Run a swarm experiment - provision and command many bots over the air. The swarm quickstart below is the main path; then see swarm and LH2 localization.

  • Script it / collect data - drive the swarm from your own code today over REST / WebSocket or MQTT, and log runs with dotbot run controller --csv-data-output. (A higher-level Python SDK is planned.)

  • Extend the platform - every command and flag is in the CLI reference; the firmware flows live under fw and device.

  • Before flashing hardware - the simulator and driving an existing swarm need only Python; building and cable-flashing firmware also need SES and the nRF Command Line Tools (nrfjprog). See Prerequisites below before you start.

CI PyPI version Documentation Coverage License

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.

On this page
Show Source