swarmit 0.2.0__tar.gz → 0.4.4__tar.gz

{swarmit-0.2.0 → swarmit-0.4.4}/.gitignore

@@ -20,3 +20,6 @@ dist/
 
 # Virtual env folder
 .venv/
+
+# Tox
+.tox/

swarmit-0.4.4/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: swarmit
+Version: 0.4.4
+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
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Requires-Dist: click==8.1.7
+Requires-Dist: cryptography==43.0.1
+Requires-Dist: marilib-pkg>=0.6.0
+Requires-Dist: pydotbot>=0.24.1
+Requires-Dist: rich==14.0.0
+Requires-Dist: structlog==24.4.0
+Requires-Dist: tqdm==4.66.5
+Description-Content-Type: text/markdown
+
+ # SwarmIT
+
+SwarmIT provides a embedded C port for nRF53 as well as Python based services to
+easily build and deploy a robotic swarm infrastructure testbed.
+ARM TrustZone is used to create a sandboxed user environment on each device
+under test, without requiring a control co-processor attached to it.
+
+https://github.com/user-attachments/assets/eff63b07-216a-41fb-9062-2e0e56f03c20
+
+## Features
+
+- Experiment management: start, stop, monitor and status check
+- Deploy a custom firmware on all or on a subset of robots of a swarm testbed
+- Resilient robot state: even when crashed by buggy user code, the robot can be reprogrammed remotely and wirelessly
+
+## Usage
+
+### Get the code
+
+Swarmit depends on the [DotBot-firmware](https://github.com/DotBots/DotBot-firmware)
+and [Mari](https://github.com/DotBots/mari) repositories. They are included
+in the codebase as [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+Use the following command to clone the Swarmit codebase locally:
+
+```
+git clone --recurse-submodules https://github.com/DotBots/swarmit.git
+```
+
+### Embedded C code
+
+SwarmIT embedded C code can be built using
+[Segger Embedded Studio (SES)](https://www.segger.com/products/development-tools/embedded-studio/).
+Use Tools > Package manager to install the CMSIS 5 CMSIS-CORE, CMSIS-DSP and nRF packages.
+
+To provision a device, follow the following steps:
+1. open [netcore.emProject](swarmit-netcore.emProject)
+   and [bootloader.emProject](swarmit-bootloader-dotbot-v3.emProject)
+   (or [bootloader.emProject](swarmit-bootloader-dotbot-v2.emProject) depending on
+   your robot version) in SES
+2. build and load the netcore application on the nRF53 network core,
+3. build and load the bootloader application on the nRF53 application core.
+
+The device is now ready.
+
+### Gateway
+
+The communication between the computer and the swarm devices is performed via a
+gateway board connected via USB to the computer.
+
+This gateway uses the [mari](https://github.com/dotbots/mari) network stack and
+the it must run the Mari gateway firmware, either Edge or Cloud version.
+
+The documentation to setup a Mari gateway is located
+[here](https://github.com/DotBots/mari/wiki/Getting-started#running-mari-network-on-your-computer).
+
+### Python CLI script
+
+The Python CLI script provides commands for flashing, starting and stopping user
+code on the device, as well as monitoring and checking the status of devices
+in the swarm.
+
+The Python CLI script connects via a virtual COM port to the gateway connected to
+the computer.
+
+The Python CLI script is available on PyPI. Install it using:
+
+```
+pip install swarmit
+```
+
+Print usage using `swarmit --help`:
+
+```
+Usage: swarmit [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  -p, --port TEXT                 Serial port to use to send the bitstream to
+                                  the gateway. Default: /dev/ttyACM0.
+  -b, --baudrate INTEGER          Serial port baudrate. Default: 1000000.
+  -H, --mqtt-host TEXT            MQTT host. Default: localhost.
+  -P, --mqtt-port INTEGER         MQTT port. Default: 1883.
+  -T, --mqtt-use_tls              Use TLS with MQTT.
+  -n, --network-id INTEGER        Marilib network ID to use. Default: 1
+  -a, --adapter [edge|cloud]
+                                  Choose the adapter to communicate with the
+                                  gateway.  [default: edge]
+  -d, --devices TEXT              Subset list of devices to interact with,
+                                  separated with ,
+  -v, --verbose                   Enable verbose mode.
+  -V, --version                   Show the version and exit.
+  -h, --help                      Show this message and exit.
+
+Commands:
+  flash    Flash a firmware to the robots.
+  message  Send a custom text message to the robots.
+  monitor  Monitor running applications.
+  reset    Reset robots locations.
+  start    Start the user application.
+  status   Print current status of the robots.
+  stop     Stop the user application.
+```

swarmit-0.4.4/README.md

@@ -0,0 +1,102 @@
+ # SwarmIT
+
+SwarmIT provides a embedded C port for nRF53 as well as Python based services to
+easily build and deploy a robotic swarm infrastructure testbed.
+ARM TrustZone is used to create a sandboxed user environment on each device
+under test, without requiring a control co-processor attached to it.
+
+https://github.com/user-attachments/assets/eff63b07-216a-41fb-9062-2e0e56f03c20
+
+## Features
+
+- Experiment management: start, stop, monitor and status check
+- Deploy a custom firmware on all or on a subset of robots of a swarm testbed
+- Resilient robot state: even when crashed by buggy user code, the robot can be reprogrammed remotely and wirelessly
+
+## Usage
+
+### Get the code
+
+Swarmit depends on the [DotBot-firmware](https://github.com/DotBots/DotBot-firmware)
+and [Mari](https://github.com/DotBots/mari) repositories. They are included
+in the codebase as [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+Use the following command to clone the Swarmit codebase locally:
+
+```
+git clone --recurse-submodules https://github.com/DotBots/swarmit.git
+```
+
+### Embedded C code
+
+SwarmIT embedded C code can be built using
+[Segger Embedded Studio (SES)](https://www.segger.com/products/development-tools/embedded-studio/).
+Use Tools > Package manager to install the CMSIS 5 CMSIS-CORE, CMSIS-DSP and nRF packages.
+
+To provision a device, follow the following steps:
+1. open [netcore.emProject](swarmit-netcore.emProject)
+   and [bootloader.emProject](swarmit-bootloader-dotbot-v3.emProject)
+   (or [bootloader.emProject](swarmit-bootloader-dotbot-v2.emProject) depending on
+   your robot version) in SES
+2. build and load the netcore application on the nRF53 network core,
+3. build and load the bootloader application on the nRF53 application core.
+
+The device is now ready.
+
+### Gateway
+
+The communication between the computer and the swarm devices is performed via a
+gateway board connected via USB to the computer.
+
+This gateway uses the [mari](https://github.com/dotbots/mari) network stack and
+the it must run the Mari gateway firmware, either Edge or Cloud version.
+
+The documentation to setup a Mari gateway is located
+[here](https://github.com/DotBots/mari/wiki/Getting-started#running-mari-network-on-your-computer).
+
+### Python CLI script
+
+The Python CLI script provides commands for flashing, starting and stopping user
+code on the device, as well as monitoring and checking the status of devices
+in the swarm.
+
+The Python CLI script connects via a virtual COM port to the gateway connected to
+the computer.
+
+The Python CLI script is available on PyPI. Install it using:
+
+```
+pip install swarmit
+```
+
+Print usage using `swarmit --help`:
+
+```
+Usage: swarmit [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  -p, --port TEXT                 Serial port to use to send the bitstream to
+                                  the gateway. Default: /dev/ttyACM0.
+  -b, --baudrate INTEGER          Serial port baudrate. Default: 1000000.
+  -H, --mqtt-host TEXT            MQTT host. Default: localhost.
+  -P, --mqtt-port INTEGER         MQTT port. Default: 1883.
+  -T, --mqtt-use_tls              Use TLS with MQTT.
+  -n, --network-id INTEGER        Marilib network ID to use. Default: 1
+  -a, --adapter [edge|cloud]
+                                  Choose the adapter to communicate with the
+                                  gateway.  [default: edge]
+  -d, --devices TEXT              Subset list of devices to interact with,
+                                  separated with ,
+  -v, --verbose                   Enable verbose mode.
+  -V, --version                   Show the version and exit.
+  -h, --help                      Show this message and exit.
+
+Commands:
+  flash    Flash a firmware to the robots.
+  message  Send a custom text message to the robots.
+  monitor  Monitor running applications.
+  reset    Reset robots locations.
+  start    Start the user application.
+  status   Print current status of the robots.
+  stop     Stop the user application.
+```

swarmit-0.4.4/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.4.4}/pyproject.toml

@@ -1,5 +1,7 @@
 [build-system]
-requires = ["hatchling"]
+requires = [
+    "hatchling>=1.4.1",
+]
 build-backend = "hatchling.build"
 
 [tool.hatch.build]
@@ -11,24 +13,30 @@ exclude = [
     "sample/",
 ]
 
+[tool.hatch.version]
+path = "testbed/swarmit/__init__.py"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
 [project]
 name = "swarmit"
-version = "0.2.0"
+dynamic = ["version"]
 authors = [
     { name="Alexandre Abadie", email="alexandre.abadie@inria.fr" },
 ]
 dependencies = [
     "click          == 8.1.7",
     "cryptography   == 43.0.1",
-    "pydotbot       == 0.22.0",
-    "pyserial       == 3.5",
-    "rich           == 13.8.1",
+    "pydotbot       >= 0.24.1",
+    "rich           == 14.0.0",
     "structlog      == 24.4.0",
     "tqdm           == 4.66.5",
+    "marilib-pkg    >= 0.6.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 +54,15 @@ classifiers = [
 swarmit = "testbed.cli.main:main"
 
 [tool.ruff]
-select = ["E", "F"]
+lint.select = ["E", "F"]
 line-length = 88
-ignore = ["E501"]
+lint.ignore = ["E501", "E722"]
+exclude = ["dotbot-firmware"]
 
 [tool.isort]
 multi_line_output = 3  # Use Vertical Hanging Indent
 profile = "black"
+
+[tool.black]
+line-length = 79
+skip-string-normalization = true