lr-shuttle 0.2.2__py3-none-any.whl → 0.2.12__py3-none-any.whl

shuttle/constants.py

@@ -6,7 +6,6 @@ from __future__ import annotations
 
 from typing import Dict, Set
 
-
 SPI_ALLOWED_FIELDS: Set[str] = {
     "cs_active",
     "setup_us",

shuttle/prodtest.py

@@ -62,9 +62,7 @@ def command(
 ) -> dict:
     """Build an NDJSON-ready spi.xfer payload for a prodtest command."""
 
-    return timo.command_payload(
-        _build_command_bytes(opcode, arguments), params=params
-    )
+    return timo.command_payload(_build_command_bytes(opcode, arguments), params=params)
 
 
 def reset() -> dict:

shuttle/serial_client.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import json
 import secrets
 import threading
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
@@ -17,6 +18,11 @@ import serial
 from serial import SerialException
 from .constants import DEFAULT_BAUD, DEFAULT_TIMEOUT
 
+USB_CDC_PACKET_SIZE = 64
+# Delay between USB CDC write chunks to avoid overwhelming the host USB stack with back-to-back packets.
+# Tune for typical desktop OS USB stacks & current use cases; may need adjustment for other hosts.
+USB_CDC_WRITE_DELAY_S = 0.000
+
 
 class ShuttleSerialError(Exception):
     """Raised when serial transport encounters an unrecoverable error."""
@@ -228,10 +234,25 @@ class NDJSONSerialClient:
         seq_tracker: Optional[SequenceTracker] = None,
     ):
         try:
-            self._serial = serial.Serial(port=port, baudrate=baudrate, timeout=timeout)
+            self._serial = serial.serial_for_url(
+                url=port,
+                baudrate=baudrate,
+                timeout=timeout,
+                do_not_open=True,
+            )
+        except SerialException as exc:  # pragma: no cover - hardware specific
+            raise ShuttleSerialError(f"Unable to initialize {port}: {exc}") from exc
+
+        try:
+            if getattr(self._serial, "open", None) is not None:
+                if not getattr(self._serial, "is_open", False):
+                    self._serial.open()
         except SerialException as exc:  # pragma: no cover - hardware specific
             raise ShuttleSerialError(f"Unable to open {port}: {exc}") from exc
-        self._serial.reset_input_buffer()
+        except AttributeError:
+            # Test stubs without an open() method are already "connected"
+            pass
+        self._reset_input_buffer()
         self._lock = threading.Lock()
         self._pending: Dict[int, CommandFuture] = {}
         self._response_backlog: Dict[int, Dict[str, Any]] = {}
@@ -241,6 +262,7 @@ class NDJSONSerialClient:
         self._logger = logger
         self._seq_tracker = seq_tracker
         self._reader: Optional[threading.Thread] = None
+        self._event_callback: Optional[Callable[[Dict[str, Any]], None]] = None
 
     def __enter__(self) -> "NDJSONSerialClient":
         return self
@@ -258,9 +280,41 @@ class NDJSONSerialClient:
         if getattr(self, "_serial", None) and self._serial.is_open:
             self._serial.close()
 
+    def _reset_input_buffer(self) -> None:
+        serial_obj = getattr(self, "_serial", None)
+        if serial_obj is None:
+            return
+        reset = getattr(serial_obj, "reset_input_buffer", None)
+        if reset is None:
+            return
+        try:
+            reset()
+        except SerialException:
+            pass
+
+    def flush_input_and_log(self):
+        """Read and log all available data from the serial buffer before sending a command."""
+        if not hasattr(self, "_serial"):
+            return
+        try:
+            while True:
+                waiting = getattr(self._serial, "in_waiting", 0)
+                if not waiting:
+                    break
+                data = self._serial.read(waiting)
+                if data:
+                    self._log_serial("RX", data)
+        except Exception:
+            pass
+        finally:
+            self._reset_input_buffer()
+
     def send_command(self, op: str, params: Dict[str, Any]) -> CommandFuture:
         """Send a command without blocking, returning a future for the response."""
 
+        # Flush and log any unread data before sending a command
+        self.flush_input_and_log()
+
         cmd_id = self._next_cmd_id()
         message: Dict[str, Any] = {"type": "cmd", "id": cmd_id, "op": op}
         message.update(params)
@@ -304,6 +358,13 @@ class NDJSONSerialClient:
         self._ensure_reader_started()
         return listener
 
+    def set_event_callback(
+        self, callback: Optional[Callable[[Dict[str, Any]], None]]
+    ) -> None:
+        """Register a callback for every device event, regardless of listeners."""
+
+        self._event_callback = callback
+
     def spi_xfer(
         self, *, tx: str, n: Optional[int] = None, **overrides: Any
     ) -> Dict[str, Any]:
@@ -345,6 +406,12 @@ class NDJSONSerialClient:
             payload["uart"] = uart
         return self._command("uart.cfg", payload)
 
+    def wifi_cfg(self, wifi: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if wifi:
+            payload["wifi"] = wifi
+        return self._command("wifi.cfg", payload)
+
     def uart_tx(self, data: str, port: Optional[int] = None) -> Dict[str, Any]:
         payload: Dict[str, Any] = {"data": data}
         if port is not None:
@@ -405,33 +472,53 @@ class NDJSONSerialClient:
     def _write(self, message: Dict[str, Any]) -> None:
         serialized = json.dumps(message, separators=(",", ":"))
         payload = serialized.encode("utf-8") + b"\n"
+        total_written = 0
         with self._lock:
-            self._serial.write(payload)
+            while total_written < len(payload):
+                # Throttling writes to avoid overwhelming the USB stack
+                chunk = payload[total_written : total_written + USB_CDC_PACKET_SIZE]
+                written = self._serial.write(chunk)
+                if written != len(chunk):
+                    raise ShuttleSerialError(
+                        f"Short write to serial port: wrote {written} of {len(chunk)} bytes"
+                    )
+                total_written += written
+                if total_written < len(payload):
+                    time.sleep(USB_CDC_WRITE_DELAY_S)
         self._log_serial("TX", payload)
 
     def _read(self) -> Optional[Dict[str, Any]]:
-        try:
-            line = self._serial.readline()
-        except SerialException as exc:  # pragma: no cover - hardware specific
-            raise ShuttleSerialError(f"Serial read failed: {exc}") from exc
-        if not line:
-            return None
-        self._log_serial("RX", line)
-        stripped = line.strip()
-        if not stripped:
-            return None
-        try:
-            decoded = stripped.decode("utf-8")
-        except UnicodeDecodeError as exc:
-            raise ShuttleSerialError(f"Invalid UTF-8 from device: {exc}") from exc
-        try:
-            message = json.loads(decoded)
-        except json.JSONDecodeError as exc:
-            raise ShuttleSerialError(
-                f"Invalid JSON from device: {decoded} ({exc})"
-            ) from exc
-        self._record_sequence(message)
-        return message
+        while True:
+            try:
+                line = self._serial.readline()
+            except SerialException as exc:  # pragma: no cover - hardware specific
+                raise ShuttleSerialError(f"Serial read failed: {exc}") from exc
+            if not line:
+                return None
+            self._log_serial("RX", line)
+            stripped = line.strip()
+            if not stripped:
+                return None
+            try:
+                decoded = stripped.decode("utf-8")
+            except UnicodeDecodeError as exc:
+                self._reset_input_buffer()
+                raise ShuttleSerialError(f"Invalid UTF-8 from device: {exc}") from exc
+            trimmed = decoded.lstrip()
+            if not trimmed:
+                continue
+            if trimmed[0] not in ("{", "["):
+                self._reset_input_buffer()
+                continue
+            try:
+                message = json.loads(decoded)
+            except json.JSONDecodeError as exc:
+                self._reset_input_buffer()
+                raise ShuttleSerialError(
+                    f"Invalid JSON from device: {decoded} ({exc})"
+                ) from exc
+            self._record_sequence(message)
+            return message
 
     def _dispatch(self, message: Dict[str, Any]) -> None:
         mtype = message.get("type")
@@ -450,6 +537,7 @@ class NDJSONSerialClient:
             ev_name = message.get("ev")
             if not isinstance(ev_name, str):
                 raise ShuttleSerialError("Device event missing ev field")
+            self._emit_event_callback(message)
             with self._lock:
                 listeners = list(self._event_listeners.get(ev_name, []))
             for listener in listeners:
@@ -491,3 +579,13 @@ class NDJSONSerialClient:
             future.mark_exception(exc)
         for listener in listeners:
             listener.fail(exc)
+
+    def _emit_event_callback(self, message: Dict[str, Any]) -> None:
+        callback = getattr(self, "_event_callback", None)
+        if callback is None:
+            return
+        try:
+            callback(message)
+        except Exception:
+            # Callback failures should not kill the serial reader loop
+            pass

shuttle/timo.py

@@ -1,8 +1,9 @@
 #! /usr/bin/env python
 # -*- coding: utf-8 -*-
 """Helpers for TiMo SPI command sequences."""
+
 from __future__ import annotations
-from typing import Any, Dict, Sequence
+from typing import Any, BinaryIO, Dict, Iterator, Sequence, Tuple, Union
 
 NOP_OPCODE = 0xFF
 READ_REG_BASE = 0b00000000
@@ -18,8 +19,21 @@ READ_RDM_CMD = 0x83  # 1000 0011: Read received RDM request
 WRITE_DMX_CMD = 0x91  # 1001 0001: Write DMX generation buffer
 WRITE_RDM_CMD = 0x92  # 1001 0010: Write an RDM response
 
+FW_BLOCK_CMD_1 = 0x8E
+FW_BLOCK_CMD_2 = 0x8F
+FW_BLOCK_CMD_1_SIZE = 254
+FW_BLOCK_CMD_2_SIZE = 18
+CCI_CHUNK_SIZE = FW_BLOCK_CMD_1_SIZE + FW_BLOCK_CMD_2_SIZE
+CCI_HEADER_SIZE = 4
+
 IRQ_FLAG_RESTART = 0x80  # Bit 7 signals the slave could not process the transfer
-IRQ_WAIT_TIMEOUT_US = 1_000  # 1 millisecond
+IRQ_WAIT_TIMEOUT_US = 1_000_000  # Allow up to 1 second for IRQ trailing edge
+
+WaitIrqOption = Union[Dict[str, Any], bool, None]
+DEFAULT_WAIT_IRQ: Dict[str, Any] = {
+    "edge": "trailing",
+    "timeout_us": IRQ_WAIT_TIMEOUT_US,
+}
 
 # Selected register map and field descriptions from TiMo SPI interface docs
 REGISTER_MAP: Dict[str, Dict[str, Any]] = {
@@ -39,6 +53,12 @@ REGISTER_MAP: Dict[str, Dict[str, Any]] = {
                 "access": "R/W",
                 "desc": "0=UART RDM, 1=SPI RDM",
             },
+            "UPDATE_MODE": {
+                "bits": (5, 5),
+                "access": "W",
+                "reset": 0,
+                "desc": "1=driver update mode",
+            },
             "RADIO_ENABLE": {
                 "bits": (7, 7),
                 "access": "R/W",
@@ -229,9 +249,9 @@ REGISTER_MAP: Dict[str, Dict[str, Any]] = {
     },
     "DEVICE_NAME": {
         "address": 0x36,
-        "length": 16,
+        "length": 32,
         "fields": {
-            "DEVICE_NAME": {"bits": (0, 128), "access": "R/W"},
+            "DEVICE_NAME": {"bits": (0, 255), "access": "R/W"},
         },
     },
     "UNIVERSE_NAME": {
@@ -420,7 +440,12 @@ def nop_sequence() -> Sequence[Dict[str, Any]]:
     return [command_payload(nop_frame())]
 
 
-def read_reg_sequence(address: int, length: int) -> Sequence[Dict[str, Any]]:
+def read_reg_sequence(
+    address: int,
+    length: int,
+    *,
+    wait_irq: WaitIrqOption = None,
+) -> Sequence[Dict[str, Any]]:
     """Build the SPI transfer sequence to read a TiMo register."""
 
     if not 0 <= address <= READ_REG_ADDR_MASK:
@@ -429,10 +454,19 @@ def read_reg_sequence(address: int, length: int) -> Sequence[Dict[str, Any]]:
         raise ValueError(f"length must be 1..{READ_REG_MAX_LEN}")
 
     command_byte = READ_REG_BASE | (address & READ_REG_ADDR_MASK)
-    # Wait for IRQ trailing edge (high-to-low) after command phase
+    # Allow callers to override the default IRQ wait behavior for edge cases
+    if wait_irq is False:
+        resolved_wait = None
+    elif wait_irq is None or wait_irq is True:
+        resolved_wait = dict(DEFAULT_WAIT_IRQ)
+    else:
+        resolved_wait = wait_irq
+    command_params: Dict[str, Any] = {}
+    if resolved_wait is not None:
+        command_params["wait_irq"] = resolved_wait
     command_transfer = command_payload(
         bytes([command_byte]),
-        params={"wait_irq": {"edge": "trailing", "timeout_us": IRQ_WAIT_TIMEOUT_US}},
+        params=command_params or None,
     )
     payload_transfer = command_payload(bytes([READ_REG_DUMMY] + [0x00] * length))
     return [command_transfer, payload_transfer]
@@ -497,3 +531,29 @@ def requires_restart(irq_flags: int) -> bool:
     """Return True when bit 7 indicates the command must be retried."""
 
     return bool(irq_flags & IRQ_FLAG_RESTART)
+
+
+def read_cci_header(stream: BinaryIO) -> bytes:
+    """Read and return the 4-byte TiMo CCI header."""
+
+    header = stream.read(CCI_HEADER_SIZE)
+    if len(header) != CCI_HEADER_SIZE:
+        raise ValueError("CCI firmware header must contain 4 bytes")
+    return header
+
+
+def iter_cci_chunks(stream: BinaryIO) -> Iterator[Tuple[int, bytes, bytes]]:
+    """Yield successive FW block payloads (254+18 bytes) from a TiMo CCI image."""
+
+    block_index = 0
+    while True:
+        chunk_1 = stream.read(FW_BLOCK_CMD_1_SIZE)
+        if not chunk_1:
+            break
+        if len(chunk_1) != FW_BLOCK_CMD_1_SIZE:
+            raise ValueError("CCI firmware truncated in FW_BLOCK_CMD_1 payload")
+        chunk_2 = stream.read(FW_BLOCK_CMD_2_SIZE)
+        if len(chunk_2) != FW_BLOCK_CMD_2_SIZE:
+            raise ValueError("CCI firmware truncated in FW_BLOCK_CMD_2 payload")
+        block_index += 1
+        yield block_index, chunk_1, chunk_2

lr_shuttle-0.2.2.dist-info/RECORD

@@ -1,18 +0,0 @@
-shuttle/cli.py,sha256=eMJEEmHG6Ar3vQsrQmCbPLY0pHUJg6gUyUDCaW0KNGM,87851
-shuttle/constants.py,sha256=GUlAg3iEuPxLQ2mDCvlv5gVXHnlawl_YeLtaUSqsnPM,757
-shuttle/flash.py,sha256=9ph23MHL40SjKZoL38Sbd3JbykGb-ECxvzBzCIjAues,4492
-shuttle/prodtest.py,sha256=1q-1dZYtrWBpI_e0jPgROVGbb_42Y0q0DIxDoo4MWUk,8020
-shuttle/serial_client.py,sha256=CnqWpC4CyxNXzsQQgRQsGwkDf19OoIEYvipu4kt2IQo,17392
-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=vH-IBzbJCpSKgCLDl6snXqe2d5PFJJ3RDVQq41b3iKg,378880
-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.2.dist-info/METADATA,sha256=eS1NFB_YNkvsq7eT4akMzyUij0ormtqHHtagAMghonA,13611
-lr_shuttle-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lr_shuttle-0.2.2.dist-info/entry_points.txt,sha256=obqdFPgvQLB1_EWcnD9ch8HjQRlNVT_pdB_EidDRDco,44
-lr_shuttle-0.2.2.dist-info/top_level.txt,sha256=PtNxNQQdya-Xs8DYublNTBTa8c1TrtfEpQ0lUd_OeZY,8
-lr_shuttle-0.2.2.dist-info/RECORD,,