lr-shuttle 0.1.0__tar.gz → 0.2.0__tar.gz

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.1.0
+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,10 +79,16 @@ 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
 
-Every device message carries a monotonically increasing `seq` counter. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
+Every device message carries a monotonically increasing `seq` counter emitted by the firmware transport itself. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
 
 - During a command, any gap in response/event sequence numbers raises a `ShuttleSerialError`, helping you catch dropped frames immediately.
 - Pass `--seq-meta /path/to/seq.meta` to persist the last observed sequence number. Subsequent Shuttle runs expect the very next `seq` value; if a gap is detected (for example because the device dropped messages while Shuttle was offline), the CLI exits with an error detailing the missing value.

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # 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
@@ -30,6 +30,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
@@ -52,10 +53,16 @@ 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
 
-Every device message carries a monotonically increasing `seq` counter. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
+Every device message carries a monotonically increasing `seq` counter emitted by the firmware transport itself. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
 
 - During a command, any gap in response/event sequence numbers raises a `ShuttleSerialError`, helping you catch dropped frames immediately.
 - Pass `--seq-meta /path/to/seq.meta` to persist the last observed sequence number. Subsequent Shuttle runs expect the very next `seq` value; if a gap is detected (for example because the device dropped messages while Shuttle was offline), the CLI exits with an error detailing the missing value.

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lr-shuttle"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI and Python client for host-side of json based serial communication with embedded device bridge."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -15,6 +15,7 @@ dependencies = [
   "pydantic>=2.8",
   "typer>=0.12",
   "pyserial>=3.5",
+  "esptool>=4.7",
 ]
 keywords = ["CLI"]
 classifiers = [
@@ -34,4 +35,10 @@ package-dir = {"" = "src"}
 where = ["src"]
 
 [project.optional-dependencies]
-dev = ["build>=1.2.1", "twine>=5.1.1", "wheel", "pytest>=8.4.2", "black>=25.9.0", "pytest-html", "pytest-cov"]
+dev = ["build>=1.2.1", "twine>=5.1.1", "wheel", "pytest>=8.4.2", "black>=25.9.0", "pytest-html", "pytest-cov"]
+
+[tool.setuptools.package-data]
+"shuttle" = [
+  "firmware/esp32c5/*.bin",
+  "firmware/esp32c5/manifest.json",
+]

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/src/lr_shuttle.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.1.0
+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,10 +79,16 @@ 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
 
-Every device message carries a monotonically increasing `seq` counter. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
+Every device message carries a monotonically increasing `seq` counter emitted by the firmware transport itself. Shuttle enforces sequential integrity both within multi-transfer operations and across invocations when requested:
 
 - During a command, any gap in response/event sequence numbers raises a `ShuttleSerialError`, helping you catch dropped frames immediately.
 - Pass `--seq-meta /path/to/seq.meta` to persist the last observed sequence number. Subsequent Shuttle runs expect the very next `seq` value; if a gap is detected (for example because the device dropped messages while Shuttle was offline), the CLI exits with an error detailing the missing value.

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/src/lr_shuttle.egg-info/SOURCES.txt

@@ -8,14 +8,23 @@ src/lr_shuttle.egg-info/requires.txt
 src/lr_shuttle.egg-info/top_level.txt
 src/shuttle/cli.py
 src/shuttle/constants.py
+src/shuttle/flash.py
 src/shuttle/prodtest.py
 src/shuttle/serial_client.py
 src/shuttle/timo.py
+src/shuttle/firmware/__init__.py
+src/shuttle/firmware/esp32c5/__init__.py
+src/shuttle/firmware/esp32c5/boot_app0.bin
+src/shuttle/firmware/esp32c5/devboard.ino.bin
+src/shuttle/firmware/esp32c5/devboard.ino.bootloader.bin
+src/shuttle/firmware/esp32c5/devboard.ino.partitions.bin
+src/shuttle/firmware/esp32c5/manifest.json
 tests/test_cli.py
 tests/test_cli_client.py
 tests/test_cli_edge.py
 tests/test_cli_seq.py
 tests/test_cli_utils.py
+tests/test_flash.py
 tests/test_prodtest_edge.py
 tests/test_prodtest_helpers.py
 tests/test_serial_client.py

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/src/lr_shuttle.egg-info/requires.txt

@@ -2,6 +2,7 @@ rich>=13.7
 pydantic>=2.8
 typer>=0.12
 pyserial>=3.5
+esptool>=4.7
 
 [dev]
 build>=1.2.1

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/src/shuttle/cli.py

@@ -4,17 +4,20 @@ from __future__ import annotations
 
 import string
 import sys
+import time
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Set, Tuple
 
 import atexit
+from concurrent.futures import TimeoutError as FutureTimeout
 import typer
 from rich.console import Console
 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,
@@ -22,6 +25,7 @@ from .constants import (
     SPI_CHOICE_FIELDS,
     UART_PARITY_ALIASES,
 )
+from .firmware import DEFAULT_BOARD
 from .serial_client import (
     NDJSONSerialClient,
     SerialLogger,
@@ -40,6 +44,7 @@ app.add_typer(
 )
 
 console = Console()
+UART_RX_POLL_INTERVAL = 0.25
 
 # Backwards-compatible aliases for tests and external callers
 _SerialLogger = SerialLogger
@@ -369,6 +374,74 @@ def _render_ping_response(response: Dict[str, Any]) -> None:
     _render_payload_response("ping", response)
 
 
+def _render_uart_event(event: Dict[str, Any]) -> None:
+    data_hex = event.get("data")
+    if not isinstance(data_hex, str):
+        console.print("[yellow]uart.rx event missing data payload[/]")
+        return
+    try:
+        payload = bytes.fromhex(data_hex)
+    except ValueError:
+        console.print("[red]uart.rx event payload is not valid hex[/]")
+        return
+
+    seq = event.get("seq", "?")
+    port = event.get("port", 0)
+    n_field = event.get("n")
+    byte_count = n_field if isinstance(n_field, int) else len(payload)
+    preview_limit = 64
+    ascii_preview = "".join(
+        chr(b) if 32 <= b < 127 else "." for b in payload[:preview_limit]
+    )
+    if len(payload) > preview_limit:
+        ascii_preview += " ..."
+
+    console.print(f"[green]uart.rx[/] seq={seq} port={port} bytes={byte_count}")
+    console.print(f"  hex  : {_format_hex(data_hex)}")
+    if payload:
+        console.print(
+            f"  ascii: {ascii_preview if ascii_preview else '(non-printable)'}"
+        )
+
+
+def _consume_uart_events(
+    listener,
+    *,
+    duration: Optional[float],
+    forever: bool,
+) -> int:
+    events_seen = 0
+    start = time.monotonic()
+    deadline = start + duration if duration is not None else None
+
+    while True:
+        if deadline is not None:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            timeout_value = (
+                remaining
+                if remaining < UART_RX_POLL_INTERVAL
+                else UART_RX_POLL_INTERVAL
+            )
+        elif forever:
+            timeout_value = UART_RX_POLL_INTERVAL
+        else:
+            timeout_value = None
+
+        try:
+            event = listener.next(timeout=timeout_value)
+        except FutureTimeout:
+            continue
+
+        _render_uart_event(event)
+        events_seen += 1
+        if duration is None and not forever:
+            break
+
+    return events_seen
+
+
 @app.callback()
 def main(
     ctx: typer.Context,
@@ -1671,6 +1744,69 @@ def uart_cfg_command(
     _render_payload_response("uart.cfg", response)
 
 
+@app.command("uart-sub")
+def uart_sub_command(
+    ctx: typer.Context,
+    port: Optional[str] = typer.Option(
+        None,
+        "--port",
+        envvar="SHUTTLE_PORT",
+        help="Serial port (e.g., /dev/ttyUSB0)",
+    ),
+    baudrate: int = typer.Option(DEFAULT_BAUD, "--baud", help="Serial baud rate"),
+    timeout: float = typer.Option(
+        DEFAULT_TIMEOUT, "--timeout", help="Read timeout in seconds"
+    ),
+    enable: Optional[bool] = typer.Option(
+        None,
+        "--enable/--disable",
+        help="Enable or disable uart.rx event emission",
+    ),
+    gap_ms: Optional[int] = typer.Option(
+        None,
+        "--gap-ms",
+        min=0,
+        max=1000,
+        help="Milliseconds of idle before emitting buffered bytes",
+    ),
+    buf: Optional[int] = typer.Option(
+        None,
+        "--buf",
+        min=1,
+        max=1024,
+        help="Emit an event once this many bytes are buffered",
+    ),
+):
+    """Query or update uart.rx subscription settings."""
+
+    resources = _ctx_resources(ctx)
+    sub_payload: Dict[str, Any] = {}
+    if enable is not None:
+        sub_payload["enable"] = enable
+    if gap_ms is not None:
+        sub_payload["gap_ms"] = gap_ms
+    if buf is not None:
+        sub_payload["buf"] = buf
+
+    resolved_port = _require_port(port)
+    action = "Updating" if sub_payload else "Querying"
+    with spinner(f"{action} uart.sub over {resolved_port}"):
+        try:
+            with NDJSONSerialClient(
+                resolved_port,
+                baudrate=baudrate,
+                timeout=timeout,
+                logger=resources.get("logger"),
+                seq_tracker=resources.get("seq_tracker"),
+            ) as client:
+                response = client.uart_sub(sub_payload if sub_payload else None)
+        except ShuttleSerialError as exc:
+            console.print(f"[red]{exc}[/]")
+            raise typer.Exit(1) from exc
+
+    _render_payload_response("uart.sub", response)
+
+
 @app.command("uart-tx")
 def uart_tx_command(
     ctx: typer.Context,
@@ -1754,6 +1890,146 @@ def uart_tx_command(
     _render_payload_response("uart.tx", response)
 
 
+@app.command("uart-rx")
+def uart_rx_command(
+    ctx: typer.Context,
+    port: Optional[str] = typer.Option(
+        None,
+        "--port",
+        envvar="SHUTTLE_PORT",
+        help="Serial port (e.g., /dev/ttyUSB0)",
+    ),
+    baudrate: int = typer.Option(DEFAULT_BAUD, "--baud", help="Serial baud rate"),
+    timeout: float = typer.Option(
+        DEFAULT_TIMEOUT, "--timeout", help="Read timeout in seconds"
+    ),
+    duration: Optional[float] = typer.Option(
+        None,
+        "--duration",
+        min=0.0,
+        help="Listen for uart.rx events for N seconds before exiting",
+    ),
+    forever: bool = typer.Option(
+        False,
+        "--forever",
+        help="Stream uart.rx events until interrupted",
+    ),
+    ensure_subscription: bool = typer.Option(
+        True,
+        "--ensure-subscription/--no-ensure-subscription",
+        help="Call uart.sub --enable before listening",
+    ),
+    gap_ms: Optional[int] = typer.Option(
+        None,
+        "--gap-ms",
+        min=0,
+        max=1000,
+        help="Override gap_ms while ensuring the subscription",
+    ),
+    buf: Optional[int] = typer.Option(
+        None,
+        "--buf",
+        min=1,
+        max=1024,
+        help="Override buf while ensuring the subscription",
+    ),
+):
+    """Stream uart.rx events emitted by the firmware."""
+
+    if forever and duration is not None:
+        raise typer.BadParameter("--duration cannot be combined with --forever")
+
+    if (gap_ms is not None or buf is not None) and not ensure_subscription:
+        raise typer.BadParameter("--gap-ms/--buf require --ensure-subscription")
+
+    resources = _ctx_resources(ctx)
+    resolved_port = _require_port(port)
+    console.print(f"Listening for uart.rx events on {resolved_port}...")
+
+    events_seen = 0
+    try:
+        with NDJSONSerialClient(
+            resolved_port,
+            baudrate=baudrate,
+            timeout=timeout,
+            logger=resources.get("logger"),
+            seq_tracker=resources.get("seq_tracker"),
+        ) as client:
+            if ensure_subscription:
+                sub_payload: Dict[str, Any] = {"enable": True}
+                if gap_ms is not None:
+                    sub_payload["gap_ms"] = gap_ms
+                if buf is not None:
+                    sub_payload["buf"] = buf
+                client.uart_sub(sub_payload)
+            listener = client.register_event_listener("uart.rx")
+            events_seen = _consume_uart_events(
+                listener, duration=duration, forever=forever
+            )
+    except ShuttleSerialError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/]")
+        raise typer.Exit(1)
+
+    if not events_seen:
+        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,

lr_shuttle-0.2.0/src/shuttle/firmware/__init__.py

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

lr_shuttle-0.2.0/src/shuttle/firmware/esp32c5/__init__.py

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

lr_shuttle-0.2.0/src/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"}
+  ]
+}

lr_shuttle-0.2.0/src/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.0 → lr_shuttle-0.2.0}/src/shuttle/serial_client.py

@@ -342,6 +342,12 @@ class NDJSONSerialClient:
             payload["port"] = port
         return self._command("uart.tx", payload)
 
+    def uart_sub(self, sub: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if sub:
+            payload["uart"] = {"sub": sub}
+        return self._command("uart.sub", payload)
+
     def _command(self, op: str, params: Dict[str, Any]) -> Dict[str, Any]:
         future = self.send_command(op, params)
         return future.result()

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/tests/test_cli.py

@@ -240,6 +240,7 @@ def test_timo_write_reg_reports_parse_error(monkeypatch):
 # -*- coding: utf-8 -*-
 
 import io
+from concurrent.futures import TimeoutError as FutureTimeout
 from contextlib import contextmanager
 from types import SimpleNamespace
 
@@ -1640,6 +1641,396 @@ def test_uart_tx_stdin(monkeypatch):
     assert record.data == "4f4b0a"
 
 
+def test_flash_command_invokes_helper(monkeypatch, recorded_console):
+    monkeypatch.setattr(cli_module, "spinner", _noop_spinner)
+    record = SimpleNamespace(args=None)
+
+    monkeypatch.setattr(
+        cli_module.flash_module,
+        "list_available_boards",
+        lambda: ["esp32c5"],
+    )
+
+    def fake_flash(**kwargs):
+        record.args = kwargs
+        return {"label": "ESP32-C5"}
+
+    monkeypatch.setattr(cli_module.flash_module, "flash_firmware", fake_flash)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "flash",
+            "--port",
+            "/dev/ttyUSB0",
+            "--board",
+            "esp32c5",
+            "--erase-first",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert record.args == {
+        "port": "/dev/ttyUSB0",
+        "baudrate": cli_module.DEFAULT_BAUD,
+        "board": "esp32c5",
+        "erase_first": True,
+    }
+    assert "flashed" in recorded_console.getvalue().lower()
+
+
+def test_flash_command_handles_failure(monkeypatch):
+    monkeypatch.setattr(cli_module, "spinner", _noop_spinner)
+    monkeypatch.setattr(
+        cli_module.flash_module,
+        "list_available_boards",
+        lambda: ["esp32c5"],
+    )
+
+    def boom(**_kwargs):
+        raise cli_module.flash_module.FirmwareFlashError("boom")
+
+    monkeypatch.setattr(cli_module.flash_module, "flash_firmware", boom)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["flash", "--port", "/dev/ttyUSB0"])
+
+    assert result.exit_code == 1
+    assert "boom" in result.stdout.lower()
+
+
+def test_uart_sub_queries_device(monkeypatch, recorded_console):
+    monkeypatch.setattr(cli_module, "spinner", _noop_spinner)
+    record = SimpleNamespace(payloads=[])
+
+    class UartClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def uart_sub(self, sub=None):
+            record.payloads.append(sub)
+            return {
+                "type": "resp",
+                "id": 1,
+                "ok": True,
+                "uart": {"subscription": {"enabled": False}},
+            }
+
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", UartClient)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["uart-sub", "--port", "/dev/ttyUSB0"])
+
+    assert result.exit_code == 0
+    assert record.payloads == [None]
+    assert "uart.sub payload" in recorded_console.getvalue()
+
+
+def test_uart_sub_updates_fields(monkeypatch):
+    monkeypatch.setattr(cli_module, "spinner", _noop_spinner)
+    record = SimpleNamespace(payload=None)
+
+    class UartClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def uart_sub(self, sub=None):
+            record.payload = sub
+            return {"type": "resp", "id": 1, "ok": True}
+
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", UartClient)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-sub",
+            "--port",
+            "/dev/ttyUSB0",
+            "--enable",
+            "--gap-ms",
+            "10",
+            "--buf",
+            "32",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert record.payload == {"enable": True, "gap_ms": 10, "buf": 32}
+
+
+def test_uart_rx_waits_for_single_event(monkeypatch, recorded_console):
+    record = SimpleNamespace(uart_sub_calls=[])
+
+    class Listener:
+        def __init__(self):
+            self.returned = False
+
+        def next(self, timeout=None):
+            assert timeout is None
+            if self.returned:
+                raise AssertionError("listener queried more than once")
+            self.returned = True
+            return {"data": "4142", "seq": 1, "n": 2, "port": 0}
+
+    class RxClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def register_event_listener(self, name):
+            assert name == "uart.rx"
+            return Listener()
+
+        def uart_sub(self, payload=None):
+            record.uart_sub_calls.append(payload)
+            return {"type": "resp", "id": 2, "ok": True}
+
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", RxClient)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["uart-rx", "--port", "/dev/ttyUSB0"])
+
+    assert result.exit_code == 0
+    assert record.uart_sub_calls == [{"enable": True}]
+    output = recorded_console.getvalue()
+    assert "uart.rx" in output
+    assert "41 42" in output
+
+
+def test_uart_rx_duration_mode(monkeypatch, recorded_console):
+    class DurationListener:
+        def __init__(self):
+            self.calls = 0
+
+        def next(self, timeout=None):
+            if self.calls < 2:
+                self.calls += 1
+                return {
+                    "data": f"0{self.calls}",
+                    "seq": self.calls,
+                    "n": 1,
+                    "port": 0,
+                }
+            raise FutureTimeout()
+
+    listener = DurationListener()
+
+    class RxClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def register_event_listener(self, name):
+            assert name == "uart.rx"
+            return listener
+
+        def uart_sub(self, payload=None):  # pragma: no cover - disabled via CLI flag
+            return {"type": "resp", "id": 3, "ok": True}
+
+    fake_time = SimpleNamespace(current=0.0)
+
+    def fake_monotonic():
+        value = fake_time.current
+        fake_time.current += 0.3
+        return value
+
+    monkeypatch.setattr(cli_module, "time", SimpleNamespace(monotonic=fake_monotonic))
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", RxClient)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-rx",
+            "--port",
+            "/dev/ttyUSB0",
+            "--duration",
+            "0.6",
+            "--no-ensure-subscription",
+        ],
+    )
+
+    assert result.exit_code == 0
+    output = recorded_console.getvalue()
+    assert output.count("uart.rx") == 2
+
+
+def test_uart_rx_duration_conflict():
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-rx",
+            "--port",
+            "/dev/ttyUSB0",
+            "--duration",
+            "1",
+            "--forever",
+        ],
+    )
+
+    assert result.exit_code != 0
+    combined = (result.stdout + result.stderr).lower()
+    assert "cannot" in combined
+
+
+def test_uart_rx_gap_requires_ensure():
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-rx",
+            "--port",
+            "/dev/ttyUSB0",
+            "--gap-ms",
+            "5",
+            "--no-ensure-subscription",
+        ],
+    )
+
+    assert result.exit_code != 0
+    combined = (result.stdout + result.stderr).lower()
+    assert "require" in combined
+
+
+def test_uart_rx_applies_gap_and_buf(monkeypatch, recorded_console):
+    record = SimpleNamespace(uart_sub_calls=[])
+
+    class Listener:
+        def __init__(self):
+            self.called = False
+
+        def next(self, timeout=None):
+            if self.called:
+                raise AssertionError("listener should only be polled once")
+            self.called = True
+            return {"data": "aa", "seq": 1, "n": 1, "port": 0}
+
+    class RxClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def register_event_listener(self, name):
+            assert name == "uart.rx"
+            return Listener()
+
+        def uart_sub(self, payload=None):
+            record.uart_sub_calls.append(payload)
+            return {"type": "resp", "id": 9, "ok": True}
+
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", RxClient)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-rx",
+            "--port",
+            "/dev/ttyUSB0",
+            "--gap-ms",
+            "15",
+            "--buf",
+            "8",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert record.uart_sub_calls == [{"enable": True, "gap_ms": 15, "buf": 8}]
+    assert "aa" in recorded_console.getvalue().lower()
+
+
+def test_uart_rx_no_events_message(monkeypatch, recorded_console):
+    class SilentListener:
+        def next(self, timeout=None):
+            raise FutureTimeout()
+
+    class RxClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, exc_tb):
+            return False
+
+        def register_event_listener(self, name):
+            assert name == "uart.rx"
+            return SilentListener()
+
+        def uart_sub(self, payload=None):  # pragma: no cover - disabled via CLI flag
+            return {"type": "resp", "id": 10, "ok": True}
+
+    fake_time = SimpleNamespace(current=0.0)
+
+    def fake_monotonic():
+        value = fake_time.current
+        fake_time.current += 0.2
+        return value
+
+    monkeypatch.setattr(cli_module, "time", SimpleNamespace(monotonic=fake_monotonic))
+    monkeypatch.setattr(cli_module, "NDJSONSerialClient", RxClient)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "uart-rx",
+            "--port",
+            "/dev/ttyUSB0",
+            "--duration",
+            "0.4",
+            "--no-ensure-subscription",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert "No uart.rx events observed" in recorded_console.getvalue()
+
+
+def test_render_uart_event_handles_invalid_payload(monkeypatch):
+    buffer = io.StringIO()
+    console = Console(file=buffer, force_terminal=False, width=80)
+    monkeypatch.setattr(cli_module, "console", console)
+
+    cli_module._render_uart_event({"seq": 1})
+    cli_module._render_uart_event({"data": "zz"})
+
+    output = buffer.getvalue()
+    assert "missing data" in output.lower()
+    assert "not valid hex" in output.lower()
+
+
 def test_ndjson_serial_client_handles_event_and_response(monkeypatch, recorded_console):
     monkeypatch.setattr(serial_client_module.secrets, "randbits", lambda bits: 1)
     stub = _install_serial_stub(

lr_shuttle-0.2.0/tests/test_flash.py

@@ -0,0 +1,92 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from shuttle import flash
+from shuttle.firmware import DEFAULT_BOARD
+
+
+def test_list_available_boards_includes_default():
+    assert DEFAULT_BOARD in flash.list_available_boards()
+
+
+def test_load_firmware_manifest_returns_segments():
+    manifest, package = flash.load_firmware_manifest("esp32c5")
+    assert manifest["segments"]
+    assert package.endswith("esp32c5")
+
+
+def test_flash_firmware_invokes_esptool(monkeypatch):
+    calls = []
+
+    def fake_run(args):
+        calls.append(args)
+
+    monkeypatch.setattr(flash, "_run_esptool", fake_run)
+
+    manifest = flash.flash_firmware(
+        port="/dev/ttyUSB0",
+        baudrate=921600,
+        board="esp32c5",
+        erase_first=True,
+    )
+
+    assert manifest["label"]
+    assert len(calls) == 2  # erase + write
+    erase_args, write_args = calls
+    assert erase_args[:4] == ["--chip", manifest["chip"], "--port", "/dev/ttyUSB0"]
+    assert "write-flash" in write_args
+    assert any("devboard.ino.bin" in arg for arg in write_args)
+
+
+def test_flash_firmware_unknown_board():
+    with pytest.raises(flash.FirmwareFlashError):
+        flash.flash_firmware(port="/dev/null", baudrate=115200, board="does-not-exist")
+
+
+def test_flash_firmware_handles_no_compress(monkeypatch):
+    calls = []
+
+    def fake_run(args):
+        calls.append(args)
+
+    manifest, package = flash.load_firmware_manifest("esp32c5")
+    custom_manifest = dict(manifest)
+    custom_manifest["compress"] = False
+
+    monkeypatch.setattr(flash, "_run_esptool", fake_run)
+    monkeypatch.setattr(
+        flash,
+        "load_firmware_manifest",
+        lambda _board: (custom_manifest, package),
+    )
+
+    flash.flash_firmware(port="/dev/ttyUSB0", baudrate=921600)
+
+    assert len(calls) == 1
+    assert "--no-compress" in calls[0]
+
+
+def test_run_esptool_success_with_exit_zero(monkeypatch):
+    recorded = []
+
+    def fake_main(args):
+        recorded.append(list(args))
+        raise SystemExit(0)
+
+    monkeypatch.setattr(flash.esptool, "main", fake_main)
+
+    flash._run_esptool(["ping"])
+
+    assert recorded[0] == ["ping"]
+
+
+def test_run_esptool_failure(monkeypatch):
+    def fake_main(_args):
+        raise SystemExit(2)
+
+    monkeypatch.setattr(flash.esptool, "main", fake_main)
+
+    with pytest.raises(flash.FirmwareFlashError):
+        flash._run_esptool(["bad"])

{lr_shuttle-0.1.0 → lr_shuttle-0.2.0}/tests/test_serial_client.py

@@ -71,6 +71,8 @@ def test_ndjson_serial_client_payload_builders():
     client.uart_cfg({"baudrate": 9600})
     client.spi_enable()
     client.spi_disable()
+    client.uart_sub({"enable": True, "gap_ms": 5})
+    client.uart_sub()
 
     assert calls[0][0] == "spi.cfg"
     assert calls[0][1]["spi"]["hz"] == 123
@@ -78,6 +80,10 @@ def test_ndjson_serial_client_payload_builders():
     assert calls[1][1]["uart"]["baudrate"] == 9600
     assert calls[2][0] == "spi.enable"
     assert calls[3][0] == "spi.disable"
+    assert calls[4][0] == "uart.sub"
+    assert calls[4][1]["uart"]["sub"] == {"enable": True, "gap_ms": 5}
+    assert calls[5][0] == "uart.sub"
+    assert calls[5][1] == {}
 
 
 def test_record_sequence_no_tracker(monkeypatch):