Metadata-Version: 2.4
Name: pydotbot
Version: 0.29.0rc1
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: marilib-pkg>=0.9.0rc2
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: rich>=14.0.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: toml>=0.10.2
Requires-Dist: uvicorn>=0.32.0
Requires-Dist: websockets>=13.1.0
Provides-Extra: all
Requires-Dist: intelhex>=2.3.0; extra == 'all'
Requires-Dist: opencv-python>=4.12.0.88; extra == 'all'
Requires-Dist: swarmit>=0.6.0; 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'
Provides-Extra: provision
Requires-Dist: intelhex>=2.3.0; extra == 'provision'
Provides-Extra: swarm
Requires-Dist: swarmit>=0.6.0; extra == 'swarm'
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

This package contains a complete environment for controlling and visualizing
[DotBots](http://www.dotbots.org).

The DotBots hardware design can be found [here (PCB)][dotbot-pcb-repo].
The firmware running on the DotBots can be found [here][dotbot-firmware-repo].

This package can also be used to control devices running the SailBot firmware
application.

![DotBots controller overview][pydotbot-overview]

## Installation

Run `pip install pydotbot`

## Setup

Flash the required firmwares on the DotBots and gateway board (use an
nRF52833DK/nRF52840DK/nrf5340DK board as gateway), as explained in
[the DotBots firmware repository][dotbot-firmware-repo].

## Usage

A single `dotbot` CLI dispatches to every workflow — controller,
testbed ops, calibration, demos:

```
dotbot --help
Usage: dotbot [OPTIONS] COMMAND [ARGS]...

  Control DotBots: drive robots, run testbed experiments, calibrate, demos.

Commands:
  controller  Start the controller (adapter + REST/WS + dashboard).
  sim         Standalone simulator (equivalent to controller --adapter dotbot-simulator).
  testbed     Testbed-side ops: provision, status, start/stop, OTA flash, monitor.
  calibrate-lh2 LH2 calibration: capture, apply, export (serial-side / single device).
  demo        Built-in research demos (qrkey phone bridge, ...).
  fw          Firmware-developer workflow (scaffold/build/flash). Not yet implemented.
  keyboard    Drive a DotBot from the keyboard (live).
  joystick    Drive a DotBot from a joystick (live).
```

Some subcommands need optional runtime deps:

```
pip install pydotbot[testbed]    # adds swarmit (testbed orchestration)
pip install pydotbot[provision]  # adds intelhex (used by `dotbot testbed provision`)
pip install pydotbot[calibrate]  # adds opencv-python + textual (LH2 calibration TUI + exporter)
pip install pydotbot[all]        # all of the above
```

Calibration (`dotbot calibrate-lh2`) and provisioning (`dotbot testbed
provision`) are vendored in-tree, but their heavyweight runtime deps
(textual / opencv-python / intelhex) are gated behind extras so the
core install stays lean.

### Starting the controller

Run `dotbot controller --help` for the full flag list (adapter, MQTT,
HTTP port, map size, etc.). By default the controller expects the serial
port to be `/dev/ttyACM0` on Linux — use `--port` to override (e.g.
`--port COM3` on Windows).

With `--webbrowser`, a tab opens at
[http://localhost:8000/PyDotBot](http://localhost:8000/PyDotBot). The
page lists available DotBots, lets you select and control one, and
exposes a virtual joystick and RGB LED control.

Use `--config-path` for a TOML config file:

```bash
# Use settings from the config file
dotbot controller --config-path config_sample.toml
# Use config file but override port and adapter (simulator example)
dotbot controller --config-path config_sample.toml -a dotbot-simulator
```

CLI flags override config-file values when both are provided.

The legacy `dotbot-controller`, `dotbot-keyboard`, and `dotbot-joystick`
console scripts remain as backwards-compatible aliases for one
deprecation cycle. Prefer `dotbot <subcommand>` for new code.

**Firefox users:**
If the webapp is not working, press `Ctrl + L`, type `about:config`,
and set `network.http.http2.websockets` to `false`.

## Tests

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

```
tox
```

[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
[pydotbot-overview]: https://github.com/DotBots/PyDotBot/blob/main/dotbots.png?raw=True
[dotbot-firmware-repo]: https://github.com/DotBots/DotBot-firmware
[dotbot-pcb-repo]: https://github.com/DotBots/DotBot-hardware
