swarmit 0.2.0__tar.gz → 0.3.0__tar.gz

{swarmit-0.2.0 → swarmit-0.3.0}/PKG-INFO

@@ -1,10 +1,11 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: swarmit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Run Your Own Robot Swarm Testbed.
 Project-URL: Homepage, https://github.com/DotBots/swarmit
 Project-URL: Bug Tracker, https://github.com/DotBots/swarmit/issues
 Author-email: Alexandre Abadie <alexandre.abadie@inria.fr>
+License: BSD
 License-File: AUTHORS
 License-File: LICENSE
 Classifier: License :: OSI Approved :: BSD License
@@ -15,6 +16,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.7
 Requires-Dist: click==8.1.7
 Requires-Dist: cryptography==43.0.1
+Requires-Dist: paho-mqtt>=2.1.0
 Requires-Dist: pydotbot==0.22.0
 Requires-Dist: pyserial==3.5
 Requires-Dist: rich==13.8.1

swarmit-0.3.0/dotbot-firmware/doc/sphinx/conf.py

@@ -0,0 +1,191 @@
+# Configuration file for the Sphinx documentation builder.
+
+import glob
+import os
+import shutil
+import subprocess
+import sys
+
+
+project = 'DotBot-firmware'
+copyright = '2023, Inria'
+author = 'Alexandre Abadie'
+
+# -- General configuration ----------------------------------------------------
+extensions = [
+    'breathe',
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+]
+
+language = "en"
+tls_verify = False
+templates_path = ['_templates']
+exclude_patterns = ["_build"]
+nitpick_ignore_regex = [
+    (r'c:.*', r'[u]*int\d{1,2}_t'),     # ignore int8_t, uint8_t, ...
+    (r'c:.*', r'NRF_.*'),               # ignore NRF_ macros
+    (r'c:.*', r'[s]*size_t'),           # ignore size_t and ssize_t 
+    (r'c:.*', r'[U]*INT\d{1,2}_MAX'),   # ignore INT8_MAX, UINT8_MAX, ...
+]
+
+# -- Options for breathe ------------------------------------------------------
+breathe_projects = {"DotBot-firmware": "../doxygen/xml/"}
+breathe_default_project = "DotBot-firmware"
+breathe_show_include = False
+breathe_domain_by_extension = {
+    "h" : "c",
+}
+
+myst_enable_extensions = ["html_image"]
+
+# -- Options for HTML output --------------------------------------------------
+html_theme = "pydata_sphinx_theme"
+html_sourcelink_suffix = ""
+html_static_path = ["_static"]
+
+# Define the json_url for our version switcher.
+json_url = "https://dotbot-firmware.readthedocs.io/en/latest/_static/switcher.json"
+rtd_version = os.environ.get("READTHEDOCS_VERSION")
+rtd_version_type = os.environ.get("READTHEDOCS_VERSION_TYPE")
+rtd_git_identifier = os.environ.get("READTHEDOCS_GIT_IDENTIFIER")
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not rtd_version or rtd_version.isdigit() or rtd_version == "latest":
+    rtd_version = "dev"
+    json_url = "_static/switcher.json"
+elif rtd_version == "stable":
+    rtd_version = f"{rtd_git_identifier}"
+elif rtd_version_type == "tag":
+    rtd_version = f"{rtd_git_identifier}"
+
+html_theme_options = {
+    "external_links": [
+        {
+            "url": "https://github.com/DotBots/PyDotBot",
+            "name": "PyDotBot",
+            "attributes": {
+               "target" : "_blank",
+               "rel" : "noopener me",
+            },
+        },
+        {
+            "url": "https://github.com/DotBots/DotBot-hardware",
+            "name": "DotBot hardware",
+            "attributes": {
+               "target" : "_blank",
+               "rel" : "noopener me",
+            },
+        },
+    ],
+    "icon_links": [
+         {
+            "name": "GitHub",
+            "url": "https://github.com/DotBots/DotBot-firmware",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+    "header_links_before_dropdown": 4,
+    "logo": {
+        "text": "DotBot firmware",
+    },
+    "navbar_align": "left",
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    "switcher": {
+        "json_url": json_url,
+        "version_match": rtd_version,
+    },
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+}
+
+# -- Options for autosummary/autodoc output -----------------------------------
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_member_order = "groupwise"
+
+# Hook for building doxygen documentation -------------------------------------
+
+def run_doxygen(app):
+    """Run the doxygen make command."""
+    doxygen_path = "../doxygen"
+    try:
+        retcode = subprocess.call(f"make -C {doxygen_path}", shell=True)
+        if retcode < 0:
+            sys.stderr.write(f"doxygen terminated by signal {-retcode}")
+    except OSError as e:
+        sys.stderr.write(f"doxygen execution failed: {e}")
+
+# Hook for generating linked README.md files --------------------------------------------
+
+README_INCLUDE_TEMPLATE = """```{{include}} {path_to_readme}
+:relative-images:
+:relative-docs: ../../
+```
+"""
+
+def generate_readme(app, prefix, dest):
+    projects_dir = os.path.join(app.srcdir, "../../projects/")
+    projects = [os.path.basename(project) for project in glob.glob(f"{projects_dir}/{prefix}*")]
+    output_dir = os.path.join(app.srcdir, dest)
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+    for project in projects:
+        with open(os.path.join(output_dir, f"{project}.md"), "w") as f:
+            f.write(README_INCLUDE_TEMPLATE.format(path_to_readme=f"../../../projects/{project}/README.md"))
+
+
+def generate_projects_readme(app):
+    for prefix, dest in [("01", "_examples"), ("03app", "_projects")]:
+        generate_readme(app, prefix, dest)
+
+
+API_INCLUDE_TEMPLATE = """{title}
+=================================
+
+.. doxygengroup:: {module}
+.. doxygenfile:: {header}
+
+"""
+EXCLUDE_MODULES = [
+    "board_config",
+    "soft_ed25519",
+    "soft_edsign",
+    "soft_f25519",
+    "soft_fprime",
+    "soft_sha256",
+    "soft_sha512",
+]
+
+
+def generate_api_files(app):
+    output_dir = os.path.join(app.srcdir, "_api")
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+    for module in ["bsp", "crypto", "drv"]:
+        module_dir = os.path.join(app.srcdir, f"../../{module}/")
+        submodules = [os.path.basename(project).split(".")[0] for project in glob.glob(f"{module_dir}/*.h")]
+        submodules = [module for module in submodules if module not in EXCLUDE_MODULES]
+        for submodule in submodules:
+            with open(os.path.join(output_dir, f"{module}_{submodule}.rst"), "w") as f:
+                f.write(
+                    API_INCLUDE_TEMPLATE.format(
+                        title=f"{submodule.capitalize()}",
+                        module=f"{module}_{submodule}",
+                        header=f"{module}/{submodule}.h"
+                    )
+                )
+
+
+def setup(app):
+    """Add hook for building doxygen documentation."""
+    app.connect("builder-inited", run_doxygen)
+    app.connect("builder-inited", generate_api_files)
+    app.connect("builder-inited", generate_projects_readme)

{swarmit-0.2.0 → swarmit-0.3.0}/pyproject.toml

@@ -1,5 +1,7 @@
 [build-system]
-requires = ["hatchling"]
+requires = [
+    "hatchling>=1.4.1",
+]
 build-backend = "hatchling.build"
 
 [tool.hatch.build]
@@ -11,9 +13,12 @@ exclude = [
     "sample/",
 ]
 
+[tool.hatch.version]
+path = "testbed/swarmit/__init__.py"
+
 [project]
 name = "swarmit"
-version = "0.2.0"
+dynamic = ["version"]
 authors = [
     { name="Alexandre Abadie", email="alexandre.abadie@inria.fr" },
 ]
@@ -25,10 +30,11 @@ dependencies = [
     "rich           == 13.8.1",
     "structlog      == 24.4.0",
     "tqdm           == 4.66.5",
+    "paho-mqtt      >= 2.1.0",
 ]
 description = "Run Your Own Robot Swarm Testbed."
 readme = "README.md"
-license-file = ["LICENSE"]
+license = { text="BSD" }
 requires-python = ">=3.7"
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -46,10 +52,14 @@ classifiers = [
 swarmit = "testbed.cli.main:main"
 
 [tool.ruff]
-select = ["E", "F"]
+lint.select = ["E", "F"]
 line-length = 88
-ignore = ["E501"]
+lint.ignore = ["E501"]
 
 [tool.isort]
 multi_line_output = 3  # Use Vertical Hanging Indent
 profile = "black"
+
+[tool.black]
+line-length = 79
+skip-string-normalization = true

swarmit-0.3.0/testbed/cli/main.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python
+
+import logging
+import time
+
+import click
+import serial
+import structlog
+from dotbot.serial_interface import SerialInterfaceException, get_default_port
+from rich import print
+from rich.console import Console
+from rich.pretty import pprint
+
+from testbed.swarmit import __version__
+from testbed.swarmit.controller import (
+    CHUNK_SIZE,
+    Controller,
+    ControllerSettings,
+    ResetLocation,
+    print_start_status,
+    print_status,
+    print_stop_status,
+    print_transfer_status,
+)
+
+SERIAL_PORT_DEFAULT = get_default_port()
+BAUDRATE_DEFAULT = 1000000
+
+
+@click.group(context_settings=dict(help_option_names=["-h", "--help"]))
+@click.version_option(version=__version__)
+@click.option(
+    "-p",
+    "--port",
+    default=SERIAL_PORT_DEFAULT,
+    help=f"Serial port to use to send the bitstream to the gateway. Default: {SERIAL_PORT_DEFAULT}.",
+)
+@click.option(
+    "-b",
+    "--baudrate",
+    default=BAUDRATE_DEFAULT,
+    help=f"Serial port baudrate. Default: {BAUDRATE_DEFAULT}.",
+)
+@click.option(
+    "-e",
+    "--edge",
+    is_flag=True,
+    default=False,
+    help="Use MQTT adapter to communicate with an edge gateway.",
+)
+@click.option(
+    "-d",
+    "--devices",
+    type=str,
+    default="",
+    help="Subset list of devices to interact with, separated with ,",
+)
+@click.pass_context
+def main(ctx, port, baudrate, edge, devices):
+    if ctx.invoked_subcommand != "monitor":
+        # Disable logging if not monitoring
+        structlog.configure(
+            wrapper_class=structlog.make_filtering_bound_logger(
+                logging.CRITICAL
+            ),
+        )
+    ctx.ensure_object(dict)
+    ctx.obj["port"] = port
+    ctx.obj["baudrate"] = baudrate
+    ctx.obj["edge"] = edge
+    ctx.obj["devices"] = [e for e in devices.split(",") if e]
+
+
+@main.command()
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Print start result.",
+)
+@click.pass_context
+def start(ctx, verbose):
+    """Start the user application."""
+    try:
+        settings = ControllerSettings(
+            serial_port=ctx.obj["port"],
+            serial_baudrate=ctx.obj["baudrate"],
+            mqtt_host="argus.paris.inria.fr",
+            mqtt_port=8883,
+            edge=ctx.obj["edge"],
+            devices=list(ctx.obj["devices"]),
+        )
+        controller = Controller(settings)
+    except (
+        SerialInterfaceException,
+        serial.serialutil.SerialException,
+    ) as exc:
+        console = Console()
+        console.print(f"[bold red]Error:[/] {exc}")
+        return
+    if controller.ready_devices:
+        started = controller.start()
+        print_start_status(
+            sorted(started),
+            sorted(set(controller.ready_devices).difference(set(started))),
+        )
+        if verbose:
+            print("Started devices:")
+            pprint(started)
+            print("Not started devices:")
+            pprint(
+                sorted(set(controller.ready_devices).difference(set(started)))
+            )
+    else:
+        print("No device to start")
+    controller.terminate()
+
+
+@main.command()
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Print start result.",
+)
+@click.pass_context
+def stop(ctx, verbose):
+    """Stop the user application."""
+    try:
+        settings = ControllerSettings(
+            serial_port=ctx.obj["port"],
+            serial_baudrate=ctx.obj["baudrate"],
+            mqtt_host="argus.paris.inria.fr",
+            mqtt_port=8883,
+            edge=ctx.obj["edge"],
+            devices=list(ctx.obj["devices"]),
+        )
+        controller = Controller(settings)
+    except (
+        SerialInterfaceException,
+        serial.serialutil.SerialException,
+    ) as exc:
+        console = Console()
+        console.print(f"[bold red]Error:[/] {exc}")
+        return
+    if controller.running_devices or controller.resetting_devices:
+        stopped = controller.stop()
+        print_stop_status(
+            sorted(stopped),
+            sorted(
+                set(
+                    controller.running_devices + controller.resetting_devices
+                ).difference(set(stopped))
+            ),
+        )
+        if verbose:
+            print("Started devices:")
+            pprint(stopped)
+            print("Not started devices:")
+            pprint(
+                sorted(
+                    set(
+                        controller.running_devices
+                        + controller.resetting_devices
+                    ).difference(set(stopped))
+                )
+            )
+    else:
+        print("No device to stop")
+    controller.terminate()
+
+
+@main.command()
+@click.argument(
+    "locations",
+    type=str,
+)
+@click.pass_context
+def reset(ctx, locations):
+    """Reset robots locations.
+
+    Locations are provided as '<device_id>:<x>,<y>-<device_id>:<x>,<y>|...'
+    """
+    devices = ctx.obj["devices"]
+    if not devices:
+        print("No devices selected.")
+        return
+    locations = {
+        location.split(':')[0]: ResetLocation(
+            pos_x=int(float(location.split(':')[1].split(',')[0]) * 1e6),
+            pos_y=int(float(location.split(':')[1].split(',')[1]) * 1e6),
+        )
+        for location in locations.split("-")
+    }
+    if sorted(devices) and sorted(locations.keys()) != sorted(devices):
+        print("Selected devices and reset locations do not match.")
+        return
+    try:
+        settings = ControllerSettings(
+            serial_port=ctx.obj["port"],
+            serial_baudrate=ctx.obj["baudrate"],
+            mqtt_host="argus.paris.inria.fr",
+            mqtt_port=8883,
+            edge=ctx.obj["edge"],
+            devices=list(ctx.obj["devices"]),
+        )
+        controller = Controller(settings)
+    except (
+        SerialInterfaceException,
+        serial.serialutil.SerialException,
+    ) as exc:
+        console = Console()
+        console.print(f"[bold red]Error:[/] {exc}")
+        return
+    if not controller.ready_devices:
+        print("No device to reset.")
+        return
+    controller.reset(locations)
+    controller.terminate()
+
+
+@main.command()
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Flash the firmware without prompt.",
+)
+@click.option(
+    "-s",
+    "--start",
+    is_flag=True,
+    help="Start the firmware once flashed.",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Print transfer data.",
+)
+@click.argument("firmware", type=click.File(mode="rb"), required=False)
+@click.pass_context
+def flash(ctx, yes, start, verbose, firmware):
+    """Flash a firmware to the robots."""
+    console = Console()
+    if firmware is None:
+        console.print("[bold red]Error:[/] Missing firmware file. Exiting.")
+        ctx.exit()
+
+    fw = bytearray(firmware.read())
+    settings = ControllerSettings(
+        serial_port=ctx.obj["port"],
+        serial_baudrate=ctx.obj["baudrate"],
+        mqtt_host="argus.paris.inria.fr",
+        mqtt_port=8883,
+        edge=ctx.obj["edge"],
+        devices=ctx.obj["devices"],
+    )
+    controller = Controller(settings)
+    if not controller.ready_devices:
+        console.print("[bold red]Error:[/] No ready devices found. Exiting.")
+        controller.terminate()
+        return
+    print(
+        f"Devices to flash ([bold white]{len(controller.ready_devices)}):[/]"
+    )
+    pprint(controller.ready_devices, expand_all=True)
+    if yes is False:
+        click.confirm("Do you want to continue?", default=True, abort=True)
+
+    devices = controller.settings.devices
+    start_data = controller.start_ota(fw)
+    if (devices and sorted(start_data.ids) != sorted(devices)) or (
+        not devices
+        and sorted(start_data.ids) != sorted(controller.ready_devices)
+    ):
+        console = Console()
+        console.print(
+            "[bold red]Error:[/] some acknowledgments are missing "
+            f'({", ".join(sorted(set(controller.ready_devices).difference(set(start_data.ids))))}). '
+            "Aborting."
+        )
+        raise click.Abort()
+    print()
+    print(f"Image size: [bold cyan]{len(fw)}B[/]")
+    print(f"Image hash: [bold cyan]{start_data.fw_hash.hex().upper()}[/]")
+    print(f"Radio chunks ([bold]{CHUNK_SIZE}B[/bold]): {start_data.chunks}")
+    start_time = time.time()
+    data = controller.transfer(fw)
+    print(f"Elapsed: [bold cyan]{time.time() - start_time:.3f}s[/bold cyan]")
+    print_transfer_status(data, start_data)
+    if verbose:
+        pprint(data)
+    if not all([value.hashes_match for value in data.values()]):
+        controller.terminate()
+        console = Console()
+        console.print("[bold red]Error:[/] Hashes do not match.")
+        raise click.Abort()
+
+    if start is True:
+        started = controller.start()
+        print_start_status(
+            sorted(started),
+            sorted(set(start_data.ids).difference(set(started))),
+        )
+    controller.terminate()
+
+
+@main.command()
+@click.pass_context
+def monitor(ctx):
+    """Monitor running applications."""
+    try:
+        settings = ControllerSettings(
+            serial_port=ctx.obj["port"],
+            serial_baudrate=ctx.obj["baudrate"],
+            mqtt_host="argus.paris.inria.fr",
+            mqtt_port=8883,
+            edge=ctx.obj["edge"],
+            devices=ctx.obj["devices"],
+        )
+        controller = Controller(settings)
+    except (
+        SerialInterfaceException,
+        serial.serialutil.SerialException,
+    ) as exc:
+        console = Console()
+        console.print(f"[bold red]Error:[/] {exc}")
+        return {}
+    try:
+        controller.monitor()
+    except KeyboardInterrupt:
+        print("Stopping monitor.")
+    finally:
+        controller.terminate()
+
+
+@main.command()
+@click.pass_context
+def status(ctx):
+    """Print current status of the robots."""
+    settings = ControllerSettings(
+        serial_port=ctx.obj["port"],
+        serial_baudrate=ctx.obj["baudrate"],
+        mqtt_host="argus.paris.inria.fr",
+        mqtt_port=8883,
+        edge=ctx.obj["edge"],
+        devices=ctx.obj["devices"],
+    )
+    controller = Controller(settings)
+    data = controller.status()
+    if not data:
+        click.echo("No devices found.")
+    else:
+        print_status(data)
+    controller.terminate()
+
+
+@main.command()
+@click.argument("message", type=str, required=True)
+@click.pass_context
+def message(ctx, message):
+    """Send a custom text message to the robots."""
+    settings = ControllerSettings(
+        serial_port=ctx.obj["port"],
+        serial_baudrate=ctx.obj["baudrate"],
+        mqtt_host="argus.paris.inria.fr",
+        mqtt_port=8883,
+        edge=ctx.obj["edge"],
+        devices=ctx.obj["devices"],
+    )
+    controller = Controller(settings)
+    controller.send_message(message)
+    controller.terminate()
+
+
+if __name__ == "__main__":
+    main(obj={})

swarmit-0.3.0/testbed/swarmit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"