Metadata-Version: 2.4
Name: dotbot-sdk
Version: 0.1.0
Summary: Package to easily control your DotBots and SailBots.
Project-URL: Homepage, https://github.com/DotBots/PyDotBot
Project-URL: Bug Tracker, https://github.com/DotBots/PyDotBot/issues
Author-email: Alexandre Abadie <alexandre.abadie@inria.fr>, Theo Akbas <theo.akbas@inria.fr>, Filip Maksimovic <filip.maksimovic@inria.fr>, Said Alvarado-Marin <said-alexander.alvarado-marin@inria.fr>, Mališa Vučinić <malisa.vucinic@inria.fr>, Diego Badillo <diego.badillo@sansano.usm.cl>, Geovane Fedrecheski <geovane.fedrecheski@inria.fr>
License: BSD
License-File: AUTHORS
License-File: LICENSE.txt
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: click>=8.1.7
Requires-Dist: fastapi>=0.115.0
Requires-Dist: gmqtt>=0.7.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: intelhex>=2.3.0
Requires-Dist: marilib-pkg>=0.9.0rc3
Requires-Dist: numpy>=2.1.1
Requires-Dist: pydotbot-utils>=0.3.0
Requires-Dist: pygame>=2.6.1
Requires-Dist: pynput>=1.8.1
Requires-Dist: pyserial>=3.5
Requires-Dist: qrkey>=0.12.2
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=14.0.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: swarmit>=0.8.0rc3
Requires-Dist: toml>=0.10.2
Requires-Dist: tomlkit>=0.13.0
Requires-Dist: uvicorn>=0.32.0
Requires-Dist: websockets>=13.1.0
Provides-Extra: all
Requires-Dist: opencv-python>=4.12.0.88; extra == 'all'
Requires-Dist: textual>=6.4.0; extra == 'all'
Provides-Extra: calibrate
Requires-Dist: opencv-python>=4.12.0.88; extra == 'calibrate'
Requires-Dist: textual>=6.4.0; extra == 'calibrate'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

[![CI][ci-badge]][ci-link]
[![PyPI version][pypi-badge]][pypi-link]
[![Documentation][doc-badge]][doc-link]
[![Coverage][codecov-badge]][codecov-link]
[![License][license-badge]][license-link]

# PyDotBot

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.

[▶️ Click to see a DotBot swarm in action](https://www.youtube.com/watch?v=pXGTLqafReU)

```text
┌───────────┐           ┌────────────┐               ┌─────────┐
│  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](https://pypi.org/project/pydotbot/), install it with:

```bash
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][cli-doc].

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

```bash
dotbot run simulator -w
```

Drive the simulated bots 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)
```

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

## 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](https://pip.pypa.io/en/stable/) available in your PATH
- [nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools) (`nrfjprog`), for commands such as `dotbot device flash`

### Setup

To operate as a swarm, set your swarm connection config:

```bash
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].

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

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

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

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

(`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:

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

Observe and control your swarm from a web interface:

```bash
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][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):

```bash
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][lh2-doc].

## Going further

- **Drive a single bot** 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
  alternative is covered there too).
- **The controller + web UI** - drive and visualize a swarm from the browser:
  the [controller guide][controller-doc].
- **Build firmware from source** instead of `dotbot fw fetch` - needs
  [SEGGER Embedded Studio](https://www.segger.com/products/development-tools/embedded-studio/)
  and a DotBot-firmware checkout:
  ```bash
  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`][fw-doc]).
- **Everything else** - the full `dotbot` CLI (`fw` / `device` / `swarm` / `run`
  + `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].

## Tests

To run the tests, run [tox](https://pypi.org/project/tox/):

```
tox
```

## License

See `LICENSE` in each component repository.

[ci-badge]: https://github.com/DotBots/PyDotBot/workflows/CI/badge.svg
[ci-link]: https://github.com/DotBots/PyDotBot/actions?query=workflow%3ACI+branch%3Amain
[pypi-badge]: https://badge.fury.io/py/pydotbot.svg
[pypi-link]: https://badge.fury.io/py/pydotbot
[doc-badge]: https://readthedocs.org/projects/pydotbot/badge/?version=latest
[doc-link]: https://pydotbot.readthedocs.io/en/latest
[license-badge]: https://img.shields.io/pypi/l/pydotbot
[license-link]: https://github.com/DotBots/pydotbot/blob/main/LICENSE.txt
[codecov-badge]: https://codecov.io/gh/DotBots/PyDotBot/branch/main/graph/badge.svg
[codecov-link]: https://codecov.io/gh/DotBots/PyDotBot
[cli-doc]: https://pydotbot.readthedocs.io/en/latest/cli/index.html
[fw-doc]: https://pydotbot.readthedocs.io/en/latest/cli/fw.html
[swarm-doc]: https://pydotbot.readthedocs.io/en/latest/cli/swarm.html
[config-doc]: https://pydotbot.readthedocs.io/en/latest/reference/configuration.html
[simulator-doc]: https://pydotbot.readthedocs.io/en/latest/guides/simulator.html
[controller-doc]: https://pydotbot.readthedocs.io/en/latest/guides/controller.html
[one-bot-doc]: https://pydotbot.readthedocs.io/en/latest/guides/one-bot.html
[lh2-doc]: https://pydotbot.readthedocs.io/en/latest/guides/lh2-calibration.html
[troubleshooting-doc]: https://pydotbot.readthedocs.io/en/latest/reference/troubleshooting.html
