Where do you want to start?

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

  • Try it with no hardware - the simulator runs the full web UI with no DotBot or gateway needed: dotbot run simulator. See the simulator guide, or run dotbot guide for a one-page start that also suits AI coding agents.

  • Get one DotBot 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 DotBots 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 SEGGER Embedded Studio and the nRF Command Line Tools (nrfjprog). See Prerequisites below before you start.

Sites and areas

Positions are millimetres in a site: the floor you work on, with its zero at a physical mark you write down and named rectangles called areas. An area can have a role. The field is where experiments happen and what a calibration covers, and a site has at most one. Staging is where robots park and charge. A corner is a small patch, such as a bench, that may overlap other areas and stays hidden in the console until you turn it on. dotbot config init writes a site with a field and a staging strip, and commands that need a place default to the field. See sites in the configuration reference.

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 DotBot and control a whole fleet over the air, from one DotBot 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 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

Install#

PyDotBot is available on PyPi, install it with:

pip install pydotbot

Then, check your installation with dotbot --version and learn what’s possible with dotbot --help. dotbot guide prints a getting-started page, written for people and AI coding agents alike.

Every command and flag is documented in the CLI reference.

Try the simulator#

See the whole thing run with nothing but Python!

First, give yourself a place to work in:

dotbot config init

This writes a site named default to ~/.dotbot/sites/ and selects it: a 2 x 2 m field, where experiments happen, and a staging strip below it, where robots park. --field 1.5m or --field 2x3m sizes the field, and the rest follows from it. Every folder sees it, and its site.toml is yours to edit once you measure a real room.

Then run a simulated swarm, which you can observe in the web console at http://localhost:8000/console/ :

dotbot run simulator --robots 20

The console opens automatically; pass --headless to suppress it (it’s still served). It is one map-first UI for both driving the fleet and orchestrating the testbed - firmware flashing, start/stop and live events - when a swarmit server is reachable.

Drive the simulated DotBots from the console, or run a bundled demo in a second terminal:

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

--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, or a site pack that carries the broker: dotbot site add <pack> --use.) This writes a site whose connection is the broker, and your swarm id, under ~/.dotbot/; every command picks them up, so you don’t repeat the flags. If the broker needs a login, save it once with dotbot config login argus.paris.inria.fr. dotbot config show says where each setting came from, and the configuration reference has the rest.

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 --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 fetch the pinned 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 🔄 🔄

# 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 config as the rest - pass --conn / --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:

dotbot swarm stop  # ensure all DotBots are in bootloader
dotbot swarm flash remote-control -ys  # this firmware lets DotBots be remote-controlled

Observe and control your swarm from a web interface:

dotbot run controller  # opens the console at http://localhost:8000/console/

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

Calibrate positions (optional)#

Give the DotBots real-world (x, y) with Lighthouse 2. It’s a two-step flow: collect a calibration by placing one DotBot on the four corners of your site’s field, then push it to the whole fleet - one capture calibrates the whole site. This needs the [calibrate] extra (opencv, for the homography solve):

pip install 'pydotbot[calibrate]'

First, flash the calibrate app and collect. Each corner is captured when you press the DotBot’s button:

dotbot swarm flash calibrate -ys          # the app that captures on a button press
dotbot swarm calibrate-lh2 collect        # the field's four corners -> solve -> save

This saves the calibration under ~/.dotbot/calibrations/<site>/ and prints its id. Then push it to the whole fleet:

dotbot swarm calibrate-lh2 push <id>

Choosing the points, checking the result on the map, and upgrading older calibration files are in the LH2 calibration guide.

Going further#

  • Drive a single DotBot 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, which also points at an experimental calibration from robots spinning in place.

  • 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 clone of the source:

    git clone --recurse-submodules https://github.com/DotBots/DotBot-firmware.git
export DOTBOT_FW_SOURCES_DOTBOT_FIRMWARE=$(pwd)/DotBot-firmware
dotbot fw build spin                     # -> ~/.dotbot/artifacts/dotbot-firmware-local/
dotbot swarm flash spin -f local -ys     # flash your build instead of the release

    swarmit-sandbox and mari-gateway build the same way (see fw).

  • Everything else - the full dotbot CLI (fw / device / swarm / run

    • config), the REST/WS and MQTT surfaces, and hardware notes: the documentation.

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