dotbot-provision 0.1.0__tar.gz

dotbot_provision-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Segger Studio specific files
+
+*.emSession
+*.jlink
+
+# Python compiled files
+*.pyc
+
+# Git conflict files
+*.orig
+
+# Visual Studio specific files
+.vscode/
+
+# Segger Studio output directory
+Output/
+
+# Python package dist
+dist/
+
+# Virtual env folder
+.venv/
+
+# Tox
+.tox/
+
+# Mac OS files
+.DS_Store
+
+# folder with binaries
+bin

dotbot_provision-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: dotbot-provision
+Version: 0.1.0
+Summary: A command-line tool for provisioning DotBot devices and gateways.
+Author-email: Geovane Fedrecheski <geovane.fedrecheski@inria.fr>
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: click>=8.1.7
+Requires-Dist: intelhex>=2.3.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# `dotbot-provision`
+
+A command-line tool for provisioning DotBot devices and gateways.
+
+## Installation
+
+```bash
+pip install dotbot-provision
+```
+
+```
+Usage: dotbot-provision [OPTIONS] COMMAND [ARGS]...
+
+  A tool for provisioning DotBot devices and gateways.
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  fetch          Fetch firmware assets into bin/<fw-version>/.
+  flash          Flash firmware + config using versioned bin layout.
+  flash-bringup  Flash J-Link OB or DAPLink programmer firmware.
+  flash-hex      Flash explicit app/net hex files.
+  read-config    Read config from the device.
+```
+
+## Deploying a testbed
+
+First, download firmware assets:
+
+```bash
+dotbot-provision fetch --fw-version v0.7.0
+```
+
+Then, to flash a DotBot-v3 while specifying a certain Network ID:
+
+```bash
+dotbot-provision flash --device dotbot-v3 --fw-version v0.7.0 --network-id 0100
+```
+
+And to flash a Mari Gateway:
+
+```bash
+dotbot-provision flash --device gateway --fw-version v0.7.0 --network-id 0100
+```
+
+... and it's done!
+
+## Deploying a testbed on fresh robots
+
+If your robot just arrived from factory, first you have to run the `flash-bringup` command.
+You can concatenate it with a regular `flash` command so that all happens in sequence with minimal manual work.
+Like this:
+
+```bash
+dotbot-provision flash-bringup --programmer-firmware jlink -d ../../../programer-files-dotbot && \
+  dotbot-provision flash -d dotbot-v3 -f local -n 0100 -s 77
+```
+... where the `-s` flag stands for `--sn-starting-digits` and serves as a pattern to identify the connected programming probe. In this case it solves a problem where the flash command incorrectly selects the external J-Link probe instead of the dotbot's (most DotBots come from factory with a serial number starting by 77).

dotbot_provision-0.1.0/README.md

@@ -0,0 +1,59 @@
+# `dotbot-provision`
+
+A command-line tool for provisioning DotBot devices and gateways.
+
+## Installation
+
+```bash
+pip install dotbot-provision
+```
+
+```
+Usage: dotbot-provision [OPTIONS] COMMAND [ARGS]...
+
+  A tool for provisioning DotBot devices and gateways.
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  fetch          Fetch firmware assets into bin/<fw-version>/.
+  flash          Flash firmware + config using versioned bin layout.
+  flash-bringup  Flash J-Link OB or DAPLink programmer firmware.
+  flash-hex      Flash explicit app/net hex files.
+  read-config    Read config from the device.
+```
+
+## Deploying a testbed
+
+First, download firmware assets:
+
+```bash
+dotbot-provision fetch --fw-version v0.7.0
+```
+
+Then, to flash a DotBot-v3 while specifying a certain Network ID:
+
+```bash
+dotbot-provision flash --device dotbot-v3 --fw-version v0.7.0 --network-id 0100
+```
+
+And to flash a Mari Gateway:
+
+```bash
+dotbot-provision flash --device gateway --fw-version v0.7.0 --network-id 0100
+```
+
+... and it's done!
+
+## Deploying a testbed on fresh robots
+
+If your robot just arrived from factory, first you have to run the `flash-bringup` command.
+You can concatenate it with a regular `flash` command so that all happens in sequence with minimal manual work.
+Like this:
+
+```bash
+dotbot-provision flash-bringup --programmer-firmware jlink -d ../../../programer-files-dotbot && \
+  dotbot-provision flash -d dotbot-v3 -f local -n 0100 -s 77
+```
+... where the `-s` flag stands for `--sn-starting-digits` and serves as a pattern to identify the connected programming probe. In this case it solves a problem where the flash command incorrectly selects the external J-Link probe instead of the dotbot's (most DotBots come from factory with a serial number starting by 77).

dotbot_provision-0.1.0/dotbot_provision/__init__.py

@@ -0,0 +1,3 @@
+"""DotBot provisioning CLI package."""
+
+__version__ = "0.1.0"

dotbot_provision-0.1.0/dotbot_provision/cli.py

@@ -0,0 +1,572 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import click
+
+from .nrf_flash import (
+    do_daplink,
+    do_daplink_if,
+    do_jlink,
+    flash_nrf_both_cores,
+    flash_nrf_one_core,
+    pick_last_jlink_snr,
+    pick_matching_jlink_snr,
+    read_device_id,
+    read_net_id,
+)
+
+try:
+    from intelhex import IntelHex
+except ModuleNotFoundError:  # pragma: no cover - optional dependency
+    IntelHex = None
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # pragma: no cover - fallback for older Pythons
+    tomllib = None
+
+
+DEFAULT_BIN_DIR = Path("bin")
+VALID_DEVICES = ("dotbot-v3", "gateway")
+VALID_PROGRAMMERS = ("jlink", "daplink")
+CONFIG_ADDR = 0x0103F800
+CONFIG_MAGIC = 0x5753524D
+CONFIG_MANIFEST_NAME = "config-manifest.json"
+RELEASE_BASE_URL = "https://github.com/DotBots/swarmit/releases/download"
+# Programmer bring-up files
+GEEHY_PACK_NAME = "Geehy.APM32F1xx_DFP.1.1.0.pack"
+JLINK_REQUIRED_FILES = ("JLink-ob.bin", "stm32f103xb_bl.hex", GEEHY_PACK_NAME)
+DAPLINK_REQUIRED_FILES = (
+    "stm32f103xb_bl.hex",
+    "stm32f103xb_if.hex",
+    GEEHY_PACK_NAME,
+)
+APM_DEVICE = "APM32F103CB"
+# it seems to always start with 77
+DOTBOT_V3_SERIAL_PATTERN = r"77[0-9A-F]{7}"
+
+DEVICE_ASSETS: dict[str, dict[str, str]] = {
+    "dotbot-v3": {
+        "app": "bootloader-dotbot-v3.hex",
+        "net": "netcore-nrf5340-net.hex",
+        "examples": ["rgbled-dotbot-v3.bin", "dotbot-dotbot-v3.bin"],
+    },
+    "gateway": {
+        "app": "03app_gateway_app-nrf5340-app.hex",
+        "net": "03app_gateway_net-nrf5340-net.hex",
+        "examples": [],
+    },
+}
+
+
+def load_config(path: Path) -> dict:
+    if tomllib is None:
+        raise click.ClickException(
+            "tomllib not available; install Python 3.11+ or add tomli."
+        )
+    try:
+        return tomllib.loads(path.read_text())
+    except FileNotFoundError as exc:
+        raise click.ClickException(f"Config file not found: {path}") from exc
+    except Exception as exc:  # noqa: BLE001 - surface parse errors
+        raise click.ClickException(
+            f"Failed to parse config file {path}: {exc}"
+        ) from exc
+
+
+def normalize_network_id(raw: str | None) -> tuple[int, str] | None:
+    if raw is None:
+        return None
+    s = raw.strip().lower()
+    if s.startswith("0x"):
+        s = s[2:]
+    try:
+        value = int(s, 16)
+    except ValueError as exc:
+        raise click.ClickException(
+            f"Invalid network_id '{raw}' (expected hex)."
+        ) from exc
+    if not (0x0000 <= value <= 0xFFFF):
+        raise click.ClickException(
+            "network_id must be 16-bit (0x0000..0xFFFF)."
+        )
+    return value, f"{value:04X}"
+
+
+def resolve_fw_root(bin_dir: Path, fw_version: str) -> Path:
+    return bin_dir / fw_version
+
+
+def download_file(url: str, dest: Path) -> None:
+    click.echo(f"[GET ] {url}")
+    try:
+        with urllib.request.urlopen(url) as resp:
+            status = getattr(resp, "status", 200)
+            if status != 200:
+                raise click.ClickException(
+                    f"HTTP {status} while downloading {url}"
+                )
+            data = resp.read()
+    except urllib.error.HTTPError as exc:
+        raise click.ClickException(
+            f"HTTP error while downloading {url}: {exc}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise click.ClickException(
+            f"Network error while downloading {url}: {exc}"
+        ) from exc
+
+    dest.write_bytes(data)
+    click.echo(f"[OK  ] wrote {dest} ({len(data)} bytes)")
+
+
+def find_existing_config_hex(fw_root: Path) -> Path | None:
+    candidates = sorted(
+        fw_root.glob("config-*.hex"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    return candidates[0] if candidates else None
+
+
+def make_config_hex_path(
+    fw_root: Path, device: str, fw_version: str, net_id_hex: str
+) -> Path:
+    ts = time.strftime("%Y%b%d-%H%M%S")
+    return fw_root / f"config-{device}-{fw_version}-{net_id_hex}-{ts}.hex"
+
+
+def create_config_hex(dest: Path, net_id_value: int) -> None:
+    if IntelHex is None:
+        raise click.ClickException(
+            "intelhex not available; install it to build config hex."
+        )
+    ih = IntelHex()
+    for offset, word in enumerate((CONFIG_MAGIC, net_id_value)):
+        addr = CONFIG_ADDR + offset * 4
+        ih[addr + 0] = (word >> 0) & 0xFF
+        ih[addr + 1] = (word >> 8) & 0xFF
+        ih[addr + 2] = (word >> 16) & 0xFF
+        ih[addr + 3] = (word >> 24) & 0xFF
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    ih.tofile(str(dest), "hex")
+
+
+def load_config_manifest(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text())
+    except Exception as exc:  # noqa: BLE001 - surface parse errors
+        raise click.ClickException(
+            f"Failed to parse config manifest {path}: {exc}"
+        ) from exc
+
+
+def write_config_manifest(path: Path, payload: dict) -> None:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def build_manifest_payload(
+    config_hex: Path,
+    device: str,
+    fw_version: str,
+    net_id_hex: str,
+) -> dict:
+    created_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    return {
+        "config_hex": config_hex.name,
+        "device": device,
+        "fw_version": fw_version,
+        "network_id": net_id_hex,
+        "config_addr": f"0x{CONFIG_ADDR:08X}",
+        "magic": f"0x{CONFIG_MAGIC:08X}",
+        "created_at": created_at,
+    }
+
+
+def manifest_matches(
+    payload: dict, device: str, fw_version: str, net_id_hex: str
+) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    return (
+        payload.get("device") == device
+        and payload.get("fw_version") == fw_version
+        and payload.get("network_id") == net_id_hex
+        and payload.get("config_addr") == f"0x{CONFIG_ADDR:08X}"
+        and payload.get("magic") == f"0x{CONFIG_MAGIC:08X}"
+        and isinstance(payload.get("config_hex"), str)
+    )
+
+
+@click.group(
+    help="A tool for provisioning DotBot devices and gateways in the context of a SwarmIT-enabled testbed."
+)
+def cli() -> None:
+    pass
+
+
+@cli.command("fetch", help="Fetch firmware assets into bin/<fw-version>/.")
+@click.option(
+    "--fw-version",
+    "-f",
+    required=True,
+    help="Firmware version tag or 'local'.",
+)
+@click.option(
+    "--local-root",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    help="Root directory for local builds (used with --fw-version local).",
+)
+@click.option(
+    "--bin-dir",
+    default=DEFAULT_BIN_DIR,
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    show_default=True,
+    help="Destination bin directory.",
+)
+def cmd_fetch(fw_version: str, local_root: Path | None, bin_dir: Path) -> None:
+    if fw_version == "local" and not local_root:
+        raise click.ClickException(
+            "--local-root is required when --fw-version=local."
+        )
+    if fw_version != "local" and local_root:
+        click.echo(
+            "[WARN] --local-root ignored when --fw-version is not 'local'.",
+            err=True,
+        )
+
+    out_dir = resolve_fw_root(bin_dir, fw_version)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    click.echo(f"[INFO] target dir: {out_dir}")
+
+    if fw_version == "local":
+        local_root = local_root.expanduser().resolve()
+        mapping = {
+            "bootloader-dotbot-v3.hex": local_root
+            / "device/bootloader/Output/dotbot-v3/Debug/Exe/bootloader-dotbot-v3.hex",
+            "netcore-nrf5340-net.hex": local_root
+            / "device/network_core/Output/nrf5340-net/Debug/Exe/netcore-nrf5340-net.hex",
+            "03app_gateway_app-nrf5340-app.hex": local_root
+            / "mari/app/03app_gateway_app/Output/nrf5340-app/Debug/Exe/03app_gateway_app-nrf5340-app.hex",
+            "03app_gateway_net-nrf5340-net.hex": local_root
+            / "mari/app/03app_gateway_net/Output/nrf5340-net/Debug/Exe/03app_gateway_net-nrf5340-net.hex",
+        }
+
+        missing = [name for name, src in mapping.items() if not src.exists()]
+        if missing:
+            missing_list = ", ".join(missing)
+            raise click.ClickException(
+                f"Missing local build artifacts: {missing_list}"
+            )
+
+        for name, src in mapping.items():
+            dest = out_dir / name
+            if dest.exists() or dest.is_symlink():
+                dest.unlink()
+            try:
+                os.symlink(src, dest)
+                click.echo(f"[LINK] {dest} -> {src}")
+            except OSError:
+                shutil.copy2(src, dest)
+                click.echo(f"[COPY] {dest} <- {src}")
+        return
+
+    assets = [
+        "bootloader-dotbot-v3.hex",
+        "netcore-nrf5340-net.hex",
+        "03app_gateway_app-nrf5340-app.hex",
+        "03app_gateway_net-nrf5340-net.hex",
+    ]
+    for name in assets:
+        url = f"{RELEASE_BASE_URL}/{fw_version}/{name}"
+        dest = out_dir / name
+        download_file(url, dest)
+
+
+@cli.command(
+    "flash",
+    help="Flash firmware + config using versioned bin layout.",
+)
+@click.option(
+    "--device", "-d", type=click.Choice(VALID_DEVICES), required=True
+)
+@click.option("--fw-version", "-f", help="Firmware version tag or 'local'.")
+@click.option(
+    "--config",
+    "-c",
+    "config_path",
+    type=click.Path(path_type=Path, dir_okay=False),
+)
+@click.option("--network-id", "-n", help="16-bit hex network ID, e.g. 0100.")
+@click.option(
+    "--sn-starting-digits",
+    "-s",
+    help="Serial number pattern to use for auto-selection, e.g. 77.",
+)
+@click.option(
+    "--bin-dir",
+    default=DEFAULT_BIN_DIR,
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    show_default=True,
+    help="Bin directory containing firmware files.",
+)
+def cmd_flash(
+    device: str,
+    fw_version: str | None,
+    config_path: Path | None,
+    network_id: str | None,
+    sn_starting_digits: str | None,
+    bin_dir: Path,
+) -> None:
+    assets = DEVICE_ASSETS[device]
+
+    if sn_starting_digits:
+        snr = pick_matching_jlink_snr(sn_starting_digits)
+    else:
+        snr = pick_last_jlink_snr()
+    if snr is None:
+        raise click.ClickException(
+            "Unable to auto-select J-Link; provide --snr explicitly."
+        )
+    click.echo(f"[INFO] using J-Link with serial number: {snr}")
+
+    if device == "dotbot-v3" and not snr.startswith("77"):
+        click.secho(
+            f"[WARN] Serial number {snr} seems to not be a DotBot, but you are trying to flash a {device} firmware to it.",
+            fg="yellow",
+        )
+        if not click.confirm(
+            "Do you want to continue? (you can check or plug the right board)",
+            default=True,
+        ):
+            raise click.ClickException("Aborting.")
+    elif device == "gateway" and snr.startswith("77"):
+        click.secho(
+            f"[WARN] Serial number {snr} seems to be a DotBot, but you are trying to flash a {device} firmware to it.",
+            fg="yellow",
+        )
+        if not click.confirm(
+            "Do you want to continue? (you can check or plug the right board)",
+            default=True,
+        ):
+            raise click.ClickException("Aborting.")
+
+    config = {}
+    if config_path:
+        config = load_config(config_path)
+
+    provisioning = (
+        config.get("provisioning", {}) if isinstance(config, dict) else {}
+    )
+    fw_version = fw_version or provisioning.get("firmware_version")
+    net_raw = network_id or provisioning.get("network_id")
+
+    if not fw_version:
+        raise click.ClickException(
+            "Missing --fw-version (or provisioning.firmware_version in config)."
+        )
+    net_id = normalize_network_id(net_raw)
+    if net_id is None:
+        raise click.ClickException(
+            "Missing --network-id (or provisioning.network_id in config)."
+        )
+
+    net_id_val, net_id_hex = net_id
+    fw_root = resolve_fw_root(bin_dir, fw_version)
+    if not fw_root.exists():
+        raise click.ClickException(f"Firmware root not found: {fw_root}")
+
+    app_hex = fw_root / assets["app"]
+    net_hex = fw_root / assets["net"]
+    manifest_path = fw_root / CONFIG_MANIFEST_NAME
+    manifest = load_config_manifest(manifest_path)
+    config_hex = None
+    if manifest:
+        click.echo(
+            f"[INFO] loaded manifest {manifest_path}: {json.dumps(manifest, indent=2)}"
+        )
+        if manifest_matches(manifest, device, fw_version, net_id_hex):
+            candidate = fw_root / manifest["config_hex"]
+            if candidate.exists():
+                config_hex = candidate
+                click.secho(
+                    f"[NOTE] using config hex from manifest: {config_hex}",
+                    fg="yellow",
+                )
+        else:
+            click.secho(
+                "[INFO] manifest does not match, will create new config hex",
+                fg="yellow",
+            )
+
+    if config_hex is None:
+        config_hex = make_config_hex_path(
+            fw_root, device, fw_version, net_id_hex
+        )
+        click.secho(f"[INFO] created new config hex: {config_hex}", fg="green")
+
+    missing = [str(p) for p in (app_hex, net_hex) if not p.exists()]
+    if missing:
+        missing_list = ", ".join(missing)
+        raise click.ClickException(f"Missing firmware files: {missing_list}")
+
+    click.echo(f"[INFO] device: {device}")
+    click.echo(f"[INFO] fw_version: {fw_version}")
+    click.echo(f"[INFO] network_id: 0x{net_id_hex}")
+    click.echo(f"[INFO] app hex: {app_hex}")
+    click.echo(f"[INFO] net hex: {net_hex}")
+    click.echo(f"[INFO] config hex: {config_hex}")
+
+    if not config_hex.exists():
+        create_config_hex(config_hex, net_id_val)
+        click.echo(f"[OK  ] wrote config hex: {config_hex}")
+        manifest_payload = build_manifest_payload(
+            config_hex, device, fw_version, net_id_hex
+        )
+        write_config_manifest(manifest_path, manifest_payload)
+        click.echo(f"[OK  ] wrote config manifest: {manifest_path}")
+        click.echo(
+            f"[INFO] manifest: {json.dumps(manifest_payload, indent=2)}"
+        )
+    else:
+        click.echo(f"[INFO] using existing config hex: {config_hex}")
+    flash_nrf_both_cores(app_hex, net_hex, nrfjprog_opt=None, snr_opt=snr)
+    flash_nrf_one_core(net_hex=config_hex, nrfjprog_opt=None, snr_opt=snr)
+    click.echo("\n[INFO] ==== Flash Complete ====\n")
+    try:
+        readback_net_id = read_net_id(snr=snr)
+        readback_device_id = read_device_id(snr=snr)
+    except RuntimeError as exc:
+        click.echo(f"[WARN] readback failed: {exc}", err=True)
+        return
+    click.echo(f"[INFO] readback net_id: {readback_net_id}")
+    click.echo(f"[INFO] readback device_id: {readback_device_id}")
+
+
+@cli.command("flash-hex", help="Flash explicit app/net hex files.")
+@click.option(
+    "--app", "app_hex", type=click.Path(path_type=Path, dir_okay=False)
+)
+@click.option(
+    "--net", "net_hex", type=click.Path(path_type=Path, dir_okay=False)
+)
+def cmd_flash_hex(app_hex: Path | None, net_hex: Path | None) -> None:
+    if not app_hex and not net_hex:
+        raise click.ClickException("Provide at least one of --app or --net.")
+    if app_hex:
+        click.echo(f"[TODO] flash app core: {app_hex}")
+    if net_hex:
+        click.echo(f"[TODO] flash net core: {net_hex}")
+
+
+@cli.command("read-config", help="Read config from the device.")
+@click.option(
+    "--sn-starting-digits",
+    "-s",
+    help="Serial number pattern to use for auto-selection, e.g. 77.",
+)
+def cmd_read_config(sn_starting_digits: str | None) -> None:
+    if sn_starting_digits:
+        snr = pick_matching_jlink_snr(sn_starting_digits)
+    else:
+        snr = pick_last_jlink_snr()
+    if snr is None:
+        raise click.ClickException(
+            "Unable to auto-select J-Link; provide --snr explicitly."
+        )
+    click.echo(f"[INFO] using J-Link with serial number: {snr}")
+    try:
+        readback_net_id = read_net_id(snr=snr)
+        readback_device_id = read_device_id(snr=snr)
+    except RuntimeError as exc:
+        click.echo(f"[WARN] readback failed: {exc}", err=True)
+        return
+    click.echo(f"[INFO] readback net_id: {readback_net_id}")
+    click.echo(f"[INFO] readback device_id: {readback_device_id}")
+
+
+@cli.command(
+    "flash-bringup",
+    help="Flash J-Link OB or DAPLink programmer firmware.",
+)
+@click.option(
+    "--programmer-firmware",
+    "-p",
+    type=click.Choice(VALID_PROGRAMMERS),
+    required=True,
+)
+@click.option(
+    "--files-dir",
+    "-d",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    required=True,
+)
+def cmd_flash_bringup(programmer_firmware: str, files_dir: Path) -> None:
+    files_dir = files_dir.expanduser().resolve()
+    if not files_dir.exists():
+        raise click.ClickException(f"files-dir does not exist: {files_dir}")
+
+    required = {
+        "jlink": JLINK_REQUIRED_FILES,
+        "daplink": DAPLINK_REQUIRED_FILES,
+    }[programmer_firmware]
+
+    missing = [name for name in required if not (files_dir / name).exists()]
+    if missing:
+        missing_list = ", ".join(missing)
+        raise click.ClickException(
+            f"Missing required files in {files_dir}: {missing_list}"
+        )
+
+    click.echo(f"[INFO] programmer: {programmer_firmware}")
+    click.echo(f"[INFO] files-dir: {files_dir}")
+    if programmer_firmware == "jlink":
+        jlink_bin = (files_dir / "JLink-ob.bin").resolve()
+        bl_hex = (files_dir / "stm32f103xb_bl.hex").resolve()
+        pack_path = str((files_dir / GEEHY_PACK_NAME).resolve())
+        do_jlink(
+            jlink_bin,
+            bl_hex,
+            apm_device=APM_DEVICE,
+            jlinktool=None,
+            pack_path=pack_path,
+        )
+    elif programmer_firmware == "daplink":
+        bl_hex = (files_dir / "stm32f103xb_bl.hex").resolve()
+        if_hex = (files_dir / "stm32f103xb_if.hex").resolve()
+        pack_path = str((files_dir / GEEHY_PACK_NAME).resolve())
+        do_daplink(
+            bl_hex, apm_device=APM_DEVICE, jlinktool=None, pack_path=pack_path
+        )
+        time.sleep(1.0)
+        do_daplink_if(if_hex, apm_device=APM_DEVICE, pack_path=pack_path)
+    else:
+        raise click.ClickException(
+            f"Invalid programmer firmware: {programmer_firmware}"
+        )
+
+    # small delay to let the target settle if needed
+    time.sleep(1.0)
+    click.secho(
+        f"[OK  ] ==== {programmer_firmware} programmer firmware flashed ====",
+        fg="green",
+    )
+
+
+def main() -> int:
+    cli(standalone_mode=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dotbot_provision-0.1.0/dotbot_provision/nrf_flash.py

@@ -0,0 +1,428 @@
+#!/usr/bin/env python3
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+# Timings
+POLL_INTERVAL = 1.0
+TIMEOUT_JLINK_SEC = 120
+TIMEOUT_BUILD_SEC = 900
+TIMEOUT_MAINTENANCE_SEC = 300
+
+DEFAULT_SWD_SPEED_KHZ = 4000
+
+
+def run(cmd, timeout=None, cwd=None):
+    print(f"[CMD] {' '.join(cmd)}")
+    proc = subprocess.run(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        timeout=timeout,
+        cwd=cwd,
+    )
+    print(proc.stdout)
+    return proc.returncode, proc.stdout
+
+
+def run_capture(cmd):
+    proc = subprocess.run(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            proc.stdout.strip() or f"Command failed: {' '.join(cmd)}"
+        )
+    return proc.stdout
+
+
+def which_tool(exe_name, user_supplied=None, candidates=None):
+    if user_supplied:
+        return user_supplied
+    p = shutil.which(exe_name)
+    if p:
+        return p
+    for c in candidates or []:
+        if Path(c).exists():
+            return c
+    return exe_name
+
+
+# ---------- JLink / DAPLink (APM32F103) ----------
+def make_jlink_script(device, speed_khz, hex_path):
+    lines = []
+    lines.append(f"device {device}")
+    lines.append("si SWD")
+    if speed_khz:
+        lines.append(f"speed {speed_khz}")
+    lines.append("connect")
+    lines.append("h")
+    lines.append("r")
+    lines.append("erase")
+    lines.append(f"loadfile {hex_path}")
+    lines.append("verify")
+    lines.append("r")
+    lines.append("g")
+    lines.append("exit")
+    return "\n".join(lines)
+
+
+def jlink_flash_hex(jlink_exe, device, image_hex, timeout=TIMEOUT_JLINK_SEC):
+    speed_khz = DEFAULT_SWD_SPEED_KHZ
+    with tempfile.NamedTemporaryFile("w", delete=False, suffix=".jlink") as tf:
+        tf.write(make_jlink_script(device, speed_khz, str(image_hex)))
+        script_path = tf.name
+    try:
+        rc, out = run(
+            [jlink_exe, "-CommanderScript", script_path], timeout=timeout
+        )
+    finally:
+        try:
+            os.unlink(script_path)
+        except OSError:
+            pass
+    if rc != 0 or "ERROR" in out.upper() or "FAILED" in out.upper():
+        raise RuntimeError("J-Link flash failed; see log above.")
+
+
+def pyocd_flash_hex(jlink_bin, device, pack_path: str):
+    erase_args = [
+        "pyocd",
+        "erase",
+        "--chip",
+        "--pack",
+        pack_path,
+        "-t",
+        str(device),
+        "--uid",
+        "261006773",
+    ]
+    rc, out = run(erase_args, timeout=60)
+    args = ["pyocd", "flash", str(jlink_bin)]
+    args += ["--pack", pack_path]
+    args += ["-t", str(device)]
+    rc, out = run(args, timeout=120)
+
+
+def do_daplink(
+    bl_hex: Path, apm_device: str, jlinktool: str | None, pack_path: str
+):
+    """Flash STM32 bootloader (DAPLink) using external J-Link."""
+    jlink_tool = which_tool(
+        "JLink.exe",
+        jlinktool,
+        candidates=[
+            # r"C:\Program Files\SEGGER\JLink_V818\JLink.exe",
+            "/usr/local/bin/JLinkExe",
+        ],
+    )
+    if not bl_hex.exists():
+        raise FileNotFoundError(f"Bootloader image not found: {bl_hex}")
+
+    print("== Flashing STM32 bootloader (DAPLink) to APM32F103CB ==")
+    jlink_flash_hex(jlink_tool, apm_device, bl_hex)
+    print("[OK] DAPLink bootloader programmed.")
+
+
+def do_daplink_if(if_hex: Path, apm_device: str, pack_path: str):
+    """Flash DAPLink interface firmware over SWD using pyOCD."""
+    if not if_hex.exists():
+        raise FileNotFoundError(f"DAPLink interface image not found: {if_hex}")
+
+    print("== Flashing DAPLink interface image via pyOCD ==")
+    pyocd_flash_hex(if_hex, apm_device, pack_path)
+    print("[OK] DAPLink interface programmed.")
+
+
+def do_jlink(
+    jlink_bin: Path,
+    bl_hex: Path,
+    apm_device: str,
+    jlinktool: str | None,
+    pack_path: str,
+):
+    """Flash STM32 bootloader, then J-Link OB image (overwrites BL)."""
+    if not jlink_bin.exists():
+        raise FileNotFoundError(f"J-Link OB image not found: {jlink_bin}")
+
+    do_daplink(
+        bl_hex=bl_hex,
+        apm_device=apm_device,
+        jlinktool=jlinktool,
+        pack_path=pack_path,
+    )
+
+    print("[INFO] Waiting 5 seconds for STM32 bootloader to enumerate...")
+    time.sleep(5)
+
+    print("== Flashing J-Link OB image via pyOCD ==")
+    pyocd_flash_hex(jlink_bin, apm_device, pack_path)
+    print("[OK] J-Link OB programmed.")
+
+
+# ---------- Flash nRF5340 with nrfjprog ----------
+def pick_last_jlink_snr(nrfjprog_opt=None):
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        nrfjprog_opt,
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+
+    rc2, out2 = run([nrfjprog, "--ids"], timeout=10)
+    ids = (
+        [line.strip() for line in out2.splitlines() if line.strip().isdigit()]
+        if rc2 == 0
+        else []
+    )
+    print(f"[DEBUG] Found J-Link IDs: {ids}")
+    if ids:
+        return ids[-1]
+    raise RuntimeError(
+        "Unable to auto-select J-Link; provide --snr explicitly."
+    )
+
+
+def pick_matching_jlink_snr(
+    sn_starting_digits: str, nrfjprog_opt: str | None = None
+):
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        nrfjprog_opt,
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+    rc2, out2 = run([nrfjprog, "--ids"], timeout=10)
+    ids = (
+        [
+            line.strip()
+            for line in out2.splitlines()
+            if line.strip().isdigit()
+            and line.strip().startswith(sn_starting_digits)
+        ]
+        if rc2 == 0
+        else []
+    )
+    print(f"[DEBUG] Found J-Link IDs: {ids}")
+    if not ids:
+        raise RuntimeError(
+            f"No J-Link found with serial number starting with {sn_starting_digits}"
+        )
+    return ids[0]
+
+
+def nrfjprog_recover(nrfjprog, snr=None):
+    args = [nrfjprog, "-f", "NRF53"]
+    if snr:
+        args += ["-s", str(snr)]
+    print(f"[INFO] Recovering both cores of nRF5340 (SNR={snr})...")
+    rc, out = run(
+        args + ["--recover", "--coprocessor", "CP_APPLICATION"], timeout=120
+    )
+    rc, out = run(
+        args + ["--recover", "--coprocessor", "CP_NETWORK"], timeout=120
+    )
+    print(f"[INFO] Erasing both cores of nRF5340 (SNR={snr})...")
+    rc, out = run(args + ["-e"], timeout=120)
+
+
+def nrfjprog_program(
+    nrfjprog,
+    hex_path,
+    network=False,
+    verify=True,
+    reset=True,
+    chiperase=True,
+    snr=None,
+):
+    args = [nrfjprog, "-f", "NRF53"]
+    if snr:
+        args += ["-s", str(snr)]
+    if network:
+        args += ["--coprocessor", "CP_NETWORK"]
+    else:
+        args += ["--coprocessor", "CP_APPLICATION"]
+    args += ["--program", str(hex_path)]
+    if verify:
+        args += ["--verify"]
+    if chiperase:
+        args += ["--chiperase"]
+    if reset:
+        args += ["--reset"]
+    rc, out = run(args, timeout=120)
+    if rc != 0 or "ERROR" in out.upper() or "failed" in out.lower():
+        raise RuntimeError("nrfjprog programming failed; see log above.")
+
+
+def _parse_memrd_words(output: str) -> list[str]:
+    line = output.strip().splitlines()[0] if output.strip() else ""
+    if ":" not in line:
+        raise RuntimeError(f"Unexpected memrd output: {output.strip()}")
+    _, rest = line.split(":", 1)
+    words = [w for w in rest.strip().split() if not w.startswith(("0x", "0X"))]
+    return words
+
+
+def read_device_id(snr: str | None = None) -> str:
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+    args = [nrfjprog, "-f", "NRF53"]
+    args += ["--coprocessor", "CP_NETWORK"]
+    args += ["--memrd", "0x01FF0204"]
+    args += ["--n", "8"]
+    if snr:
+        args += ["-s", str(snr)]
+    out = run_capture(args)
+    words = _parse_memrd_words(out)
+    if len(words) < 2:
+        raise RuntimeError(f"Unexpected device ID output: {out.strip()}")
+    return f"{words[1]}{words[0]}"
+
+
+def read_net_id(snr: str | None = None) -> str:
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+    args = [nrfjprog, "-f", "NRF53"]
+    args += ["--coprocessor", "CP_NETWORK"]
+    args += ["--memrd", "0x0103F804"]
+    args += ["--n", "4"]
+    if snr:
+        args += ["-s", str(snr)]
+    out = run_capture(args)
+    words = _parse_memrd_words(out)
+    if len(words) < 1:
+        raise RuntimeError(f"Unexpected net ID output: {out.strip()}")
+    return f"{words[0][-4:]}"
+
+
+def flash_nrf_both_cores(
+    app_hex: Path, net_hex: Path, nrfjprog_opt: str | None, snr_opt: str | None
+):
+    """Flash nRF5340 application and network cores with full recover + chiperase."""
+    if not app_hex.exists():
+        raise FileNotFoundError(f"App hex not found: {app_hex}")
+    if not net_hex.exists():
+        raise FileNotFoundError(f"Net hex not found: {net_hex}")
+
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        nrfjprog_opt,
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+
+    snr = snr_opt or pick_last_jlink_snr(nrfjprog)
+    print(f"[INFO] Using J-Link with serial number: {snr}")
+
+    nrfjprog_recover(nrfjprog, snr=snr)
+
+    print("== Flashing nRF5340 application core with nrfjprog ==")
+    nrfjprog_program(
+        nrfjprog,
+        app_hex,
+        network=False,
+        verify=True,
+        reset=True,
+        chiperase=True,
+        snr=snr,
+    )
+    print("[OK] Application core programmed.")
+
+    print("== Flashing nRF5340 network core with nrfjprog ==")
+    nrfjprog_program(
+        nrfjprog,
+        net_hex,
+        network=True,
+        verify=True,
+        reset=True,
+        chiperase=True,
+        snr=snr,
+    )
+    print("[OK] Network core programmed.")
+
+
+def flash_nrf_one_core(
+    app_hex: Path | None = None,
+    net_hex: Path | None = None,
+    nrfjprog_opt: str | None = None,
+    snr_opt: str | None = None,
+):
+    """Flash only one core; no recover and no chiperase."""
+    if app_hex is None and net_hex is None:
+        raise FileNotFoundError("Provide app_hex or net_hex.")
+    if app_hex is not None and net_hex is not None:
+        raise FileNotFoundError("Provide only one of app_hex or net_hex.")
+    if app_hex is not None and not app_hex.exists():
+        raise FileNotFoundError(f"App hex not found: {app_hex}")
+    if net_hex is not None and not net_hex.exists():
+        raise FileNotFoundError(f"Net hex not found: {net_hex}")
+
+    nrfjprog = which_tool(
+        "nrfjprog.exe",
+        nrfjprog_opt,
+        candidates=[
+            # r"C:\Program Files\Nordic Semiconductor\nrf-command-line-tools\bin\nrfjprog.exe"
+            "/usr/local/bin/nrfjprog",
+        ],
+    )
+
+    snr = snr_opt or pick_last_jlink_snr(nrfjprog)
+    print(f"[INFO] Using J-Link with serial number: {snr}")
+
+    if app_hex is not None:
+        print("== Flashing nRF5340 application core with nrfjprog ==")
+        nrfjprog_program(
+            nrfjprog,
+            app_hex,
+            network=False,
+            verify=True,
+            reset=True,
+            chiperase=False,
+            snr=snr,
+        )
+        print("[OK] Application core programmed.")
+    else:
+        print("== Flashing nRF5340 network core with nrfjprog ==")
+        nrfjprog_program(
+            nrfjprog,
+            net_hex,
+            network=True,
+            verify=True,
+            reset=True,
+            chiperase=False,
+            snr=snr,
+        )
+        print("[OK] Network core programmed.")
+        # also need to reset the application core (without programming, just reset)
+        nrfjprog_reset_core(nrfjprog, snr=snr, core="CP_APPLICATION")
+        print("[OK] Application core reset.")
+
+
+def nrfjprog_reset_core(nrfjprog, snr=None, core="CP_APPLICATION"):
+    args = [nrfjprog, "-f", "NRF53"]
+    if snr:
+        args += ["-s", str(snr)]
+    args += ["--reset", "--coprocessor", core]
+    rc, out = run(args, timeout=120)
+    if rc != 0 or "ERROR" in out.upper() or "failed" in out.lower():
+        raise RuntimeError("nrfjprog reset failed; see log above.")

dotbot_provision-0.1.0/provision-config-sample.toml

@@ -0,0 +1,3 @@
+[provisioning]
+network_id = "0100"
+# firmware_version = "v0.6.0"

dotbot_provision-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = [
+    "hatchling>=1.4.1",
+]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = [
+    "dotbot_provision/**",
+    "README.md",
+    "provision-config-sample.toml",
+]
+exclude = [
+]
+
+[tool.hatch.version]
+path = "dotbot_provision/__init__.py"
+
+[project]
+name = "dotbot-provision"
+dynamic = ["version"]
+authors = [
+    { name="Geovane Fedrecheski", email="geovane.fedrecheski@inria.fr" },
+]
+dependencies = [
+    "click >= 8.1.7",
+    "intelhex >= 2.3.0",
+    "tomli >= 2.0.1; python_version < '3.11'",
+]
+description = "A command-line tool for provisioning DotBot devices and gateways."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+]
+
+[project.scripts]
+dotbot-provision = "dotbot_provision.cli:main"