lr-shuttle 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

{lr_shuttle-0.1.1.dist-info → lr_shuttle-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.1.1
+Version: 0.2.0
 Summary: CLI and Python client for host-side of json based serial communication with embedded device bridge.
 Author-email: Jonas Estberger <jonas.estberger@lumenradio.com>
 License: MIT
@@ -14,6 +14,7 @@ Requires-Dist: rich>=13.7
 Requires-Dist: pydantic>=2.8
 Requires-Dist: typer>=0.12
 Requires-Dist: pyserial>=3.5
+Requires-Dist: esptool>=4.7
 Provides-Extra: dev
 Requires-Dist: build>=1.2.1; extra == "dev"
 Requires-Dist: twine>=5.1.1; extra == "dev"
@@ -25,7 +26,7 @@ Requires-Dist: pytest-cov; extra == "dev"
 
 # Shuttle
 
-`shuttle` is a Typer-based command-line interface & python library for interacting with the SPI-to-USB devboard over its NDJSON serial protocol. The tool is packaged as `lr-shuttle` for PyPI distribution and exposes high-level helpers for common workflows such as probing firmware info, querying protocol metadata, and issuing TiMo SPI sequences.
+`shuttle` is a Typer-based command-line interface & python library for interacting with the ESP32-C5 devboard over its NDJSON serial protocol. The tool is packaged as `lr-shuttle` for PyPI distribution and exposes high-level helpers for common workflows such as probing firmware info, querying protocol metadata, and issuing TiMo SPI sequences.
 
 
 ## Installation
@@ -55,6 +56,7 @@ make -C host dev
 | `shuttle spi-cfg [options]` | Queries or updates the devboard SPI defaults (wraps the `spi.cfg` protocol command). |
 | `shuttle uart-cfg [options]` | Queries or updates the devboard UART defaults (wraps the `uart.cfg` protocol command). |
 | `shuttle uart-tx [payload]` | Transmits bytes over the devboard UART (wraps the `uart.tx` protocol command). |
+| `shuttle flash --port /dev/ttyUSB0` | Programs the ESP32-C5 devboard using the bundled firmware artifacts. |
 
 
 ### SPI Configuration Workflow
@@ -77,6 +79,12 @@ make -C host dev
 - Use `--uart-port` if a future firmware exposes multiple UART instances; otherwise the option can be omitted and the default device UART is used.
 - Responses echo the number of bytes accepted by the firmware, matching the `n` field returned by `uart.tx`.
 
+### Flashing Bundled Firmware
+
+- `shuttle flash --port /dev/ttyUSB0` invokes `esptool.py` under the hood and writes the bundled ESP32-C5 firmware (bootloader, partitions, and application images) to the selected device. Pass `--erase-first` to issue a chip erase before programming.
+- Firmware bundles live under `shuttle/firmware/<board>` inside the Python package. Run `make -f Makefile.arduino arduino-python` from the repo root after compiling with Arduino CLI to refresh the packaged binaries and `manifest.json` for distribution builds. The helper also copies `boot_app0.bin` from the ESP-IDF core (needed for the USB CDC-on-boot option) so the CLI uses the same flashing layout as `arduino-cli upload`.
+- Use `--board <name>` if additional bundles are added; the command enumerates available bundles automatically and validates the provided identifier.
+
 
 ### Sequence Integrity Checks
 

lr_shuttle-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+shuttle/cli.py,sha256=SxTNlqIfGviNQDloIUIVE2IffggkvVKne-GoN9VJJfA,69716
+shuttle/constants.py,sha256=GUlAg3iEuPxLQ2mDCvlv5gVXHnlawl_YeLtaUSqsnPM,757
+shuttle/flash.py,sha256=a2KMECO4aVFuWtP0zrT7cELQgQuyDoSXNM1EBk1Wd-U,4416
+shuttle/prodtest.py,sha256=V0wkbicAb-kqMPKsvvi7lQgcPvto7M8RbACU9pf7y8I,3595
+shuttle/serial_client.py,sha256=B4ci-Ox-ig65H0xO32FgJHfTG0Ievg6VjGfQ_PSZjWE,17104
+shuttle/timo.py,sha256=1K18y0QtDF2lw2Abeok9PgrpPUiCEbQdGQXOQik75Hw,16481
+shuttle/firmware/__init__.py,sha256=KRXyz3xJ2GIB473tCHAky3DdPIQb78gX64Qn-uu55To,120
+shuttle/firmware/esp32c5/__init__.py,sha256=U2xXnb80Wv8EJaJ6Tv9iev1mVlpoaEeqsNmjmEtxdFQ,41
+shuttle/firmware/esp32c5/boot_app0.bin,sha256=-UxdeGp6j6sGrF0Q4zvzdxGmaXY23AN1WeoZzEEKF_A,8192
+shuttle/firmware/esp32c5/devboard.ino.bin,sha256=xrS7cn4mllTXPtpBqpgjuA9863shD1TISgFkHfxMIGk,377792
+shuttle/firmware/esp32c5/devboard.ino.bootloader.bin,sha256=LPU51SdUwebYemCZb5Pya-wGe7RC4UXrkRmBnsHePp0,20784
+shuttle/firmware/esp32c5/devboard.ino.partitions.bin,sha256=FIuVnL_xw4qo4dXAup1hLFSZe5ReVqY_QSI-72UGU6E,3072
+shuttle/firmware/esp32c5/manifest.json,sha256=CPOegfEK4PTtI6UPeohuUKkJNeg0t8aWntEczpoxYt4,480
+lr_shuttle-0.2.0.dist-info/METADATA,sha256=DeZ2s75NvqbuHDa-4077ItWJuvLWEbSEvk5byWEa_mw,13037
+lr_shuttle-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lr_shuttle-0.2.0.dist-info/entry_points.txt,sha256=obqdFPgvQLB1_EWcnD9ch8HjQRlNVT_pdB_EidDRDco,44
+lr_shuttle-0.2.0.dist-info/top_level.txt,sha256=PtNxNQQdya-Xs8DYublNTBTa8c1TrtfEpQ0lUd_OeZY,8
+lr_shuttle-0.2.0.dist-info/RECORD,,

shuttle/cli.py

@@ -17,6 +17,7 @@ from rich.panel import Panel
 from rich.pretty import Pretty
 from rich.table import Table
 
+from . import flash as flash_module
 from . import prodtest, timo
 from .constants import (
     DEFAULT_BAUD,
@@ -24,6 +25,7 @@ from .constants import (
     SPI_CHOICE_FIELDS,
     UART_PARITY_ALIASES,
 )
+from .firmware import DEFAULT_BOARD
 from .serial_client import (
     NDJSONSerialClient,
     SerialLogger,
@@ -1975,6 +1977,59 @@ def uart_rx_command(
         console.print("[yellow]No uart.rx events observed[/]")
 
 
+@app.command("flash")
+def flash_command(
+    ctx: typer.Context,
+    port: Optional[str] = typer.Option(
+        None,
+        "--port",
+        envvar="SHUTTLE_PORT",
+        help="Serial port connected to the ESP32-C5 devboard",
+    ),
+    baudrate: int = typer.Option(
+        DEFAULT_BAUD,
+        "--baud",
+        help="Serial baud used for the ROM bootloader",
+    ),
+    board: str = typer.Option(
+        DEFAULT_BOARD,
+        "--board",
+        help="Firmware bundle to flash",
+    ),
+    erase_first: bool = typer.Option(
+        False,
+        "--erase-first/--no-erase-first",
+        help="Erase the entire flash before writing",
+    ),
+):
+    """Flash the bundled firmware image to the devboard."""
+
+    resolved_port = _require_port(port)
+    available_boards = flash_module.list_available_boards()
+    available = ", ".join(available_boards)
+    if board not in available_boards:
+        raise typer.BadParameter(
+            f"Unknown firmware bundle '{board}'. Available: {available}"
+        )
+
+    with spinner(f"Flashing {board} firmware to {resolved_port}"):
+        try:
+            manifest = flash_module.flash_firmware(
+                port=resolved_port,
+                baudrate=baudrate,
+                board=board,
+                erase_first=erase_first,
+            )
+        except flash_module.FirmwareFlashError as exc:
+            console.print(f"[red]{exc}[/]")
+            raise typer.Exit(1) from exc
+
+    label = str(manifest.get("label", board))
+    console.print(
+        f"[green]Successfully flashed {label} ({board}) over {resolved_port}[/]"
+    )
+
+
 @app.command("get-info")
 def get_info(
     ctx: typer.Context,

shuttle/firmware/__init__.py

@@ -0,0 +1,5 @@
+"""Embedded firmware artifacts bundled with the Shuttle CLI."""
+
+DEFAULT_BOARD = "esp32c5"
+
+__all__ = ["DEFAULT_BOARD"]

shuttle/firmware/esp32c5/__init__.py

@@ -0,0 +1 @@
+"""ESP32-C5 devboard firmware bundle."""

shuttle/firmware/esp32c5/manifest.json

@@ -0,0 +1,17 @@
+{
+  "board": "esp32c5",
+  "label": "ESP32-C5 Devboard",
+  "chip": "esp32c5",
+  "flash-mode": "keep",
+  "flash-freq": "keep",
+  "flash-size": "keep",
+  "before": "default-reset",
+  "after": "hard-reset",
+  "compress": true,
+  "segments": [
+    {"offset": "0x2000", "file": "devboard.ino.bootloader.bin"},
+    {"offset": "0x8000", "file": "devboard.ino.partitions.bin"},
+    {"offset": "0xe000", "file": "boot_app0.bin"},
+    {"offset": "0x10000", "file": "devboard.ino.bin"}
+  ]
+}

shuttle/flash.py

@@ -0,0 +1,132 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Helpers for flashing embedded firmware bundles to the devboard."""
+
+from __future__ import annotations
+
+import json
+from contextlib import ExitStack
+from importlib import resources
+from pathlib import Path
+from typing import Dict, List, Sequence, Tuple
+
+import esptool
+
+from .firmware import DEFAULT_BOARD
+
+
+class FirmwareFlashError(RuntimeError):
+    """Raised when preparing or flashing bundled firmware fails."""
+
+
+def list_available_boards() -> List[str]:
+    """Return the set of firmware bundles shipped with the package."""
+
+    firmware_pkg = resources.files("shuttle.firmware")
+    return sorted(child.name for child in firmware_pkg.iterdir() if child.is_dir())
+
+
+def load_firmware_manifest(board: str) -> Tuple[Dict[str, object], str]:
+    """Load the manifest for the requested firmware bundle."""
+
+    package = f"shuttle.firmware.{board}"
+    try:
+        manifest_path = resources.files(package) / "manifest.json"
+    except ModuleNotFoundError as exc:
+        raise FirmwareFlashError(f"Unknown firmware target '{board}'") from exc
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise FirmwareFlashError(f"Firmware manifest missing for '{board}'") from exc
+    except json.JSONDecodeError as exc:
+        raise FirmwareFlashError(f"Invalid manifest for '{board}': {exc}") from exc
+
+    if not manifest.get("segments"):
+        raise FirmwareFlashError(f"Firmware manifest for '{board}' defines no segments")
+    manifest.setdefault("label", board)
+    manifest.setdefault("chip", board)
+    manifest.setdefault("compress", True)
+    return manifest, package
+
+
+def _run_esptool(args: Sequence[str]) -> None:
+    try:
+        esptool.main(list(args))
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        if code:
+            raise FirmwareFlashError(f"esptool exited with status {code}") from exc
+    except Exception as exc:  # pragma: no cover - esptool internal errors
+        raise FirmwareFlashError(str(exc)) from exc
+
+
+def flash_firmware(
+    *,
+    port: str,
+    baudrate: int,
+    board: str = DEFAULT_BOARD,
+    erase_first: bool = False,
+) -> Dict[str, object]:
+    """Flash the bundled firmware to the specified serial port."""
+
+    manifest, package = load_firmware_manifest(board)
+    base_args: List[str] = [
+        "--chip",
+        str(manifest.get("chip", board)),
+        "--port",
+        port,
+        "--baud",
+        str(baudrate),
+        "--before",
+        str(manifest.get("before", "default-reset")),
+        "--after",
+        str(manifest.get("after", "hard-reset")),
+    ]
+
+    with ExitStack() as stack:
+        resolved_segments: List[Tuple[str, Path]] = []
+        for segment in manifest["segments"]:
+            offset = segment.get("offset")
+            file_name = segment.get("file")
+            if not offset or not file_name:
+                raise FirmwareFlashError("Manifest segment entries require 'offset' and 'file'")
+            traversable = resources.files(package) / file_name
+            try:
+                file_path = stack.enter_context(resources.as_file(traversable))
+            except FileNotFoundError as exc:
+                raise FirmwareFlashError(f"Missing firmware artifact: {file_name}") from exc
+            resolved_segments.append((str(offset), Path(file_path)))
+
+        if erase_first:
+            _run_esptool(base_args + ["erase-flash"])
+
+        write_args: List[str] = base_args + ["write-flash"]
+        option_keys = [
+            ("flash-mode", manifest.get("flash-mode") or manifest.get("flash_mode")),
+            ("flash-freq", manifest.get("flash-freq") or manifest.get("flash_freq")),
+            ("flash-size", manifest.get("flash-size") or manifest.get("flash_size")),
+        ]
+        for option, value in option_keys:
+            if value:
+                write_args += [f"--{option}", str(value)]
+
+        if manifest.get("compress", True):
+            write_args.append("--compress")
+        else:
+            write_args.append("--no-compress")
+
+        for offset, artifact_path in resolved_segments:
+            write_args += [offset, str(artifact_path)]
+
+        _run_esptool(write_args)
+
+    return manifest
+
+
+__all__ = [
+    "FirmwareFlashError",
+    "flash_firmware",
+    "list_available_boards",
+    "load_firmware_manifest",
+]

lr_shuttle-0.1.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-shuttle/cli.py,sha256=UvaRuBKVdM0JsGC-Gqh8tYauMslouAlF6QuZTXGHjTM,68046
-shuttle/constants.py,sha256=GUlAg3iEuPxLQ2mDCvlv5gVXHnlawl_YeLtaUSqsnPM,757
-shuttle/prodtest.py,sha256=V0wkbicAb-kqMPKsvvi7lQgcPvto7M8RbACU9pf7y8I,3595
-shuttle/serial_client.py,sha256=B4ci-Ox-ig65H0xO32FgJHfTG0Ievg6VjGfQ_PSZjWE,17104
-shuttle/timo.py,sha256=1K18y0QtDF2lw2Abeok9PgrpPUiCEbQdGQXOQik75Hw,16481
-lr_shuttle-0.1.1.dist-info/METADATA,sha256=HYaly9JaR-hKo_S_SzPzJc0LgCoLkh4o-Mar-oRvxlE,12040
-lr_shuttle-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lr_shuttle-0.1.1.dist-info/entry_points.txt,sha256=obqdFPgvQLB1_EWcnD9ch8HjQRlNVT_pdB_EidDRDco,44
-lr_shuttle-0.1.1.dist-info/top_level.txt,sha256=PtNxNQQdya-Xs8DYublNTBTa8c1TrtfEpQ0lUd_OeZY,8
-lr_shuttle-0.1.1.dist-info/RECORD,,