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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -80,7 +80,7 @@ make -C host dev
 
 ### 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.1.1}/README.md

@@ -55,7 +55,7 @@ make -C host dev
 
 ### 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.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lr-shuttle"
-version = "0.1.0"
+version = "0.1.1"
 description = "CLI and Python client for host-side of json based serial communication with embedded device bridge."
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -80,7 +80,7 @@ make -C host dev
 
 ### 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.1.1}/src/shuttle/cli.py

@@ -4,11 +4,13 @@ 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
@@ -40,6 +42,7 @@ app.add_typer(
 )
 
 console = Console()
+UART_RX_POLL_INTERVAL = 0.25
 
 # Backwards-compatible aliases for tests and external callers
 _SerialLogger = SerialLogger
@@ -369,6 +372,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 +1742,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 +1888,93 @@ 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("get-info")
 def get_info(
     ctx: typer.Context,

{lr_shuttle-0.1.0 → lr_shuttle-0.1.1}/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.1.1}/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,337 @@ def test_uart_tx_stdin(monkeypatch):
     assert record.data == "4f4b0a"
 
 
+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.1.0 → lr_shuttle-0.1.1}/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):