lr-shuttle 0.2.3__py3-none-any.whl → 0.2.8__py3-none-any.whl

{lr_shuttle-0.2.3.dist-info → lr_shuttle-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lr-shuttle
-Version: 0.2.3
+Version: 0.2.8
 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
@@ -119,6 +119,7 @@ Commands implementing the SPI protocol as described at [docs.lumenradio.io/timot
 | `shuttle timo read-reg --addr 0x05 --length 2` | Performs the two-phase TiMo register read sequence and decodes the resulting payload/IRQ flags. |
 | `shuttle timo write-reg --addr 0x05 --data cafebabe` | Performs the two-phase TiMo register write sequence to write bytes to a register. |
 | `shuttle timo read-dmx --length 12` | Reads the latest received DMX values from the TiMo device using a two-phase SPI sequence. |
+| `shuttle timo update-fw TIMO.cci --port /dev/ttyUSB0` | Streams a TiMo `.cci` firmware image via FW_BLOCK commands (requires SPI ≤ 2 MHz and ≥ 255-byte transfers). |
 
 All commands respect the global options declared on the root CLI (`--log`, `--seq-meta`, `--port`, etc.). Rich tables are used to render human-friendly summaries of responses and decoded payloads.
 
@@ -174,6 +175,23 @@ This will print a summary table with the length, data bytes (hex), and IRQ flags
 - `--port` is your serial device
 
 
+### TiMo Firmware Update
+
+Use `shuttle timo update-fw` to push official `.cci` images (for example `timotwo-fx-b50f26ad.cci`; the companion `.hex` is provided for reference only) through the Shuttle bridge without touching an external programmer:
+
+```bash
+shuttle timo update-fw timotwo-fx-b50f26ad.cci --port /dev/ttyUSB0
+```
+
+- The command first checks `spi_caps.max_transfer_bytes` and the current SPI clock. Firmware updates require at least 255 bytes per `spi.xfer` call and a clock ≤ 2 MHz. Run `shuttle spi-cfg --hz 2000000` (or lower) if the persisted setting is faster.
+- Shuttle enables SPI, sets TiMo into UPDATE_MODE by writing `0x40` to CONFIG, waits for the IRQ reboot window (0.6 s), and verifies bit 7 of STATUS before streaming data.
+- `.cci` files contain a 4-byte header followed by 272-byte chunks. Because the TiMo FW loader accepts at most 255 contiguous bytes, each chunk is split into one `FW_BLOCK_CMD_1` transfer (0x8E + 254 bytes) and one `FW_BLOCK_CMD_2` transfer (0x8F + 18 bytes).
+- The first chunk after the header carries metadata. After every 16 data chunks the device writes flash internally, so the CLI pauses for `--flush-wait-ms` (defaults to 500 ms) before continuing. When the whole image has been sent it waits `--final-wait-ms` (defaults to 1000 ms) to let TiMo finalize the update.
+- Once STATUS clears UPDATE_MODE the command reads the VERSION register, prints FW/HW revisions, and confirms completion. If any step fails (IRQ bit 7, transport error, malformed `.cci`) the CLI aborts with a helpful message.
+
+Tip: combine `--flush-wait-ms 0` and `--final-wait-ms 0` with a lab DUT when replaying the same firmware repeatedly, but keep the defaults when programming production hardware to honour the vendor timing guidelines.
+
+
 ### Using the Library from Python
 
 Use the transport helpers for HIL tests with explicit request→response pairing:

{lr_shuttle-0.2.3.dist-info → lr_shuttle-0.2.8.dist-info}/RECORD

@@ -1,18 +1,18 @@
-shuttle/cli.py,sha256=i75UW_r_v2AbVTMA1X4u_LnVf3fQz5Xc00IjbxNZwN8,93515
+shuttle/cli.py,sha256=fv5HfJxfg8hnyO4CCA2vwG-OfTDSygnV6MrsZwv1yD8,108548
 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=WjGanUAL16qw2RZcCjHjYMKHsk-B6zY3cMeS0gPtPHE,17650
-shuttle/timo.py,sha256=1K18y0QtDF2lw2Abeok9PgrpPUiCEbQdGQXOQik75Hw,16481
+shuttle/prodtest.py,sha256=nI8k2OndhqsOv8BMtXwfcpGEdmHU7ywbIgMuW49EULU,8006
+shuttle/serial_client.py,sha256=0srdCjKHW35LQFmZM_q-A9QEtSNadJp3WpqzIAHI1zo,19743
+shuttle/timo.py,sha256=SfWgiYUtPjSsUln5hgDLiYMYOt8zg1DLL5t07sgu2wY,18336
 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=eCkSHtcBBbLRvHQmkvXR1jRoMMqMTMEXaXMv8GMIsD8,1098256
+shuttle/firmware/esp32c5/devboard.ino.bin,sha256=idrwg2JFHYjLK2KQVj4d_v31GHkqO8gEgr2TWkPHbbY,1101248
 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.3.dist-info/METADATA,sha256=_hp5-NmIdtKB2wZIQww4oPpXCe3mDHqevScN3G9uj4Y,13611
-lr_shuttle-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lr_shuttle-0.2.3.dist-info/entry_points.txt,sha256=obqdFPgvQLB1_EWcnD9ch8HjQRlNVT_pdB_EidDRDco,44
-lr_shuttle-0.2.3.dist-info/top_level.txt,sha256=PtNxNQQdya-Xs8DYublNTBTa8c1TrtfEpQ0lUd_OeZY,8
-lr_shuttle-0.2.3.dist-info/RECORD,,
+lr_shuttle-0.2.8.dist-info/METADATA,sha256=6yYpMjMjWpAOEMIJntX3XDiX1MveRgqJ3TnjheFZ_Ks,15574
+lr_shuttle-0.2.8.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+lr_shuttle-0.2.8.dist-info/entry_points.txt,sha256=obqdFPgvQLB1_EWcnD9ch8HjQRlNVT_pdB_EidDRDco,44
+lr_shuttle-0.2.8.dist-info/top_level.txt,sha256=PtNxNQQdya-Xs8DYublNTBTa8c1TrtfEpQ0lUd_OeZY,8
+lr_shuttle-0.2.8.dist-info/RECORD,,

{lr_shuttle-0.2.3.dist-info → lr_shuttle-0.2.8.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

shuttle/cli.py

@@ -2,12 +2,13 @@
 # -*- coding: utf-8 -*-
 from __future__ import annotations
 
+import io
 import ipaddress
 import re
 import string
 import sys
 import time
-from contextlib import contextmanager
+from contextlib import contextmanager, nullcontext
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Set, Tuple
 
@@ -107,7 +108,9 @@ for entry in PRODTEST_TX_POWER_LEVELS:
     for alias in entry["aliases"]:
         PRODTEST_TX_POWER_ALIASES[alias.lower()] = entry["value"]
     PRODTEST_TX_POWER_ALIASES[str(entry["value"])] = entry["value"]
-PRODTEST_TX_POWER_CANONICAL = [entry["aliases"][0] for entry in PRODTEST_TX_POWER_LEVELS]
+PRODTEST_TX_POWER_CANONICAL = [
+    entry["aliases"][0] for entry in PRODTEST_TX_POWER_LEVELS
+]
 
 _HOST_PORT_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+:\d+$")
 _IPV6_HOST_PORT_PATTERN = re.compile(r"^\[[0-9A-Fa-f:]+\]:\d+$")
@@ -121,6 +124,53 @@ def _ctx_resources(ctx: typer.Context) -> Dict[str, Optional[object]]:
     return ctx.obj or {}
 
 
+@contextmanager
+def _sys_error_reporter(client) -> None:
+    setter = getattr(client, "set_event_callback", None)
+    if setter is None:
+        yield
+        return
+    setter(_handle_sys_error_event)
+    try:
+        yield
+    finally:
+        setter(None)
+
+
+def _handle_sys_error_event(event: Dict[str, Any]) -> None:
+    if event.get("ev") != "sys.error":
+        return
+    code = event.get("code", "?")
+    msg = event.get("msg", "")
+    seq = event.get("seq")
+    parts = [f"Device sys.error ({code})"]
+    if seq is not None:
+        parts.append(f"seq={seq}")
+    if msg:
+        parts.append(f"- {msg}")
+    console.print(f"[red]{' '.join(parts)}[/]")
+
+
+@contextmanager
+def _open_serial_client(
+    resolved_port: str,
+    *,
+    baudrate: int,
+    timeout: float,
+    logger: Optional[SerialLogger],
+    seq_tracker: Optional[SequenceTracker],
+):
+    with NDJSONSerialClient(
+        resolved_port,
+        baudrate=baudrate,
+        timeout=timeout,
+        logger=logger,
+        seq_tracker=seq_tracker,
+    ) as client:
+        with _sys_error_reporter(client):
+            yield client
+
+
 @contextmanager
 def spinner(message: str, enabled: bool = True):
     """Show a Rich spinner while the body executes."""
@@ -159,9 +209,7 @@ def _resolve_prodtest_power_choice(value: str) -> Tuple[int, Dict[str, str]]:
             resolved = parsed
     if resolved is None:
         allowed = ", ".join(PRODTEST_TX_POWER_CANONICAL)
-        raise typer.BadParameter(
-            f"Power must be one of: {allowed} or an index 0-7"
-        )
+        raise typer.BadParameter(f"Power must be one of: {allowed} or an index 0-7")
     return resolved, PRODTEST_TX_POWER_META[resolved]
 
 
@@ -259,9 +307,7 @@ def _resolve_uart_payload(
 def _normalize_port(port: str) -> str:
     trimmed = port.strip()
     if not trimmed:
-        raise typer.BadParameter(
-            "Serial port is required (use --port or SHUTTLE_PORT)"
-        )
+        raise typer.BadParameter("Serial port is required (use --port or SHUTTLE_PORT)")
     if "://" in trimmed:
         return trimmed
     if trimmed.startswith("/") or trimmed.startswith("\\"):
@@ -439,6 +485,267 @@ def _render_read_dmx_result(result, rx_frames):
             )
 
 
+class FirmwareUpdateError(RuntimeError):
+    """Raised when TiMo firmware update prerequisites or transfers fail."""
+
+
+FW_UPDATE_SPI_LIMIT_HZ = 2_000_000
+FW_UPDATE_BOOT_DELAY_S = 1.75
+FW_UPDATE_IRQ_RETRIES = 5
+FW_UPDATE_IRQ_RETRY_DELAY_S = 0.25
+
+
+def _run_timo_sequence_with_client(
+    client,
+    sequence: Sequence[Dict[str, Any]],
+    *,
+    label: str,
+) -> List[Dict[str, Any]]:
+    responses: List[Dict[str, Any]] = []
+    for idx, transfer in enumerate(sequence):
+        response = client.spi_xfer(**transfer)
+        responses.append(response)
+        if not response.get("ok"):
+            phase = "command" if idx == 0 else "payload"
+            err = response.get("err", {})
+            details = f"code={err.get('code')} msg={err.get('msg')}" if err else ""
+            raise FirmwareUpdateError(
+                f"{label} failed during {phase} phase {details}".strip()
+            )
+    return responses
+
+
+def _write_reg_checked(client, address: int, data: bytes) -> timo.WriteRegisterResult:
+    label = f"write-reg 0x{address:02X}"
+    for attempt in range(1, FW_UPDATE_IRQ_RETRIES + 1):
+        responses = _run_timo_sequence_with_client(
+            client,
+            timo.write_reg_sequence(address, data),
+            label=label,
+        )
+        rx_frames = [resp.get("rx", "") for resp in responses]
+        try:
+            parsed = timo.parse_write_reg_response(address, data, rx_frames)
+        except ValueError as exc:  # pragma: no cover - defensive
+            raise FirmwareUpdateError(
+                f"Unable to parse {label} response: {exc}"
+            ) from exc
+        needs_retry = timo.requires_restart(
+            parsed.irq_flags_command
+        ) or timo.requires_restart(parsed.irq_flags_payload)
+        if not needs_retry:
+            return parsed
+        if attempt < FW_UPDATE_IRQ_RETRIES:
+            console.print(
+                f"[yellow]{label} attempt {attempt}/{FW_UPDATE_IRQ_RETRIES} reported IRQ bit7; retrying after {FW_UPDATE_IRQ_RETRY_DELAY_S:.3f}s...[/]"
+            )
+            time.sleep(FW_UPDATE_IRQ_RETRY_DELAY_S)
+    raise FirmwareUpdateError(
+        f"{label} kept reporting IRQ bit7 after {FW_UPDATE_IRQ_RETRIES} attempts"
+    )
+
+
+def _read_reg_checked(
+    client,
+    address: int,
+    length: int,
+    *,
+    label: str,
+    wait_irq: timo.WaitIrqOption = None,
+    retries: int = FW_UPDATE_IRQ_RETRIES,
+) -> timo.ReadRegisterResult:
+    max_attempts = max(1, retries)
+    for attempt in range(1, max_attempts + 1):
+        responses = _run_timo_sequence_with_client(
+            client,
+            timo.read_reg_sequence(address, length, wait_irq=wait_irq),
+            label=label,
+        )
+        rx_frames = [resp.get("rx", "") for resp in responses]
+        try:
+            parsed = timo.parse_read_reg_response(address, length, rx_frames)
+        except ValueError as exc:
+            raise FirmwareUpdateError(
+                f"Unable to parse {label} response: {exc}"
+            ) from exc
+        needs_retry = timo.requires_restart(
+            parsed.irq_flags_command
+        ) or timo.requires_restart(parsed.irq_flags_payload)
+        if not needs_retry:
+            return parsed
+        if attempt < max_attempts and max_attempts > 1:
+            console.print(
+                f"[yellow]{label} attempt {attempt}/{max_attempts} reported IRQ bit7; retrying after {FW_UPDATE_IRQ_RETRY_DELAY_S:.3f}s...[/]"
+            )
+            time.sleep(FW_UPDATE_IRQ_RETRY_DELAY_S)
+    raise FirmwareUpdateError(
+        f"{label} kept reporting IRQ bit7 after {max_attempts} attempts"
+    )
+
+
+def _ensure_spi_ready_for_update(client, *, max_frame_bytes: int) -> Dict[str, Any]:
+    info = client.get_info()
+    spi_caps = info.get("spi_caps") or {}
+    max_transfer = spi_caps.get("max_transfer_bytes")
+    if not isinstance(max_transfer, int) or max_transfer < max_frame_bytes:
+        raise FirmwareUpdateError(
+            "Device SPI transport cannot send the required firmware block size "
+            f"(needs {max_frame_bytes} bytes, reports {max_transfer}). Update the devboard firmware."
+        )
+    cfg_resp = client.spi_cfg()
+    spi_cfg = cfg_resp.get("spi") or {}
+    hz = spi_cfg.get("hz") or spi_caps.get("default_hz")
+    if isinstance(hz, str):
+        try:
+            hz = int(hz, 0)
+        except ValueError:
+            hz = None
+    if isinstance(hz, int) and hz > FW_UPDATE_SPI_LIMIT_HZ:
+        raise FirmwareUpdateError(
+            f"Configured SPI clock {hz} Hz exceeds update limit {FW_UPDATE_SPI_LIMIT_HZ} Hz. "
+            "Run 'shuttle spi-cfg --hz 2000000' before retrying."
+        )
+    enable_resp = client.spi_enable()
+    if not enable_resp.get("ok"):
+        err = enable_resp.get("err", {})
+        msg = err.get("msg") if isinstance(err, dict) else "unable to enable SPI"
+        raise FirmwareUpdateError(f"spi.enable failed: {msg}")
+    return spi_caps
+
+
+def _send_fw_block(
+    client,
+    opcode: int,
+    payload: bytes,
+    *,
+    max_transfer_bytes: int,
+):
+    frame = bytes([opcode]) + payload
+    if len(frame) > max_transfer_bytes:
+        raise FirmwareUpdateError(
+            f"FW block (opcode 0x{opcode:02X}) exceeds spi_caps.max_transfer_bytes"
+        )
+    response = client.spi_xfer(tx=frame.hex(), n=len(frame))
+    if not response.get("ok"):
+        err = response.get("err", {})
+        msg = err.get("msg") if isinstance(err, dict) else "unknown"
+        raise FirmwareUpdateError(f"FW block opcode 0x{opcode:02X} failed: {msg}")
+
+
+def _read_status_byte(
+    client,
+    *,
+    wait_irq: timo.WaitIrqOption = None,
+    retries: int = FW_UPDATE_IRQ_RETRIES,
+) -> int:
+    reg_meta = timo.REGISTER_MAP["STATUS"]
+    result = _read_reg_checked(
+        client,
+        reg_meta["address"],
+        reg_meta.get("length", 1),
+        label="STATUS register",
+        wait_irq=wait_irq,
+        retries=retries,
+    )
+    return result.data[0] if result.data else 0
+
+
+def _read_version_bytes(client) -> bytes:
+    reg_meta = timo.REGISTER_MAP["VERSION"]
+    result = _read_reg_checked(
+        client,
+        reg_meta["address"],
+        reg_meta.get("length", 8),
+        label="VERSION register",
+    )
+    return result.data
+
+
+def _enter_update_mode(client) -> None:
+    config_addr = timo.REGISTER_MAP["CONFIG"]["address"]
+    console.print("[cyan]Requesting TiMo UPDATE_MODE[/]")
+    _write_reg_checked(client, config_addr, bytes([0x40]))
+    console.print(
+        f"Waiting {FW_UPDATE_BOOT_DELAY_S:.3f}s before reading STATUS for UPDATE_MODE"
+    )
+    time.sleep(FW_UPDATE_BOOT_DELAY_S)
+    status_byte = _read_status_byte(client, wait_irq=False, retries=3)
+    if status_byte & 0x80:
+        console.print("[green]TiMo entered UPDATE_MODE[/]")
+        return
+    raise FirmwareUpdateError("TiMo did not enter update mode (STATUS bit7 missing)")
+
+
+def _format_fw_progress(block_index: int, total_blocks: int, total_bytes: int) -> str:
+    return f"Transferred {block_index}/{total_blocks} blocks ({total_bytes} bytes)"
+
+
+def _stream_fw_image(
+    client,
+    *,
+    firmware_path: Path,
+    max_transfer_bytes: int,
+    flush_wait_s: float,
+) -> Tuple[int, int, bytes]:
+    bytes_per_block = timo.FW_BLOCK_CMD_1_SIZE + timo.FW_BLOCK_CMD_2_SIZE
+    try:
+        total_size = firmware_path.stat().st_size
+        payload_bytes_on_disk = total_size - timo.CCI_HEADER_SIZE
+        if payload_bytes_on_disk <= 0:
+            raise FirmwareUpdateError("CCI firmware contains no payload blocks")
+        if payload_bytes_on_disk % bytes_per_block != 0:
+            raise FirmwareUpdateError(
+                "CCI firmware size is not aligned to FW block payloads"
+            )
+        expected_blocks = payload_bytes_on_disk // bytes_per_block
+        with firmware_path.open("rb") as raw_file:
+            reader = io.BufferedReader(raw_file)
+            header = timo.read_cci_header(reader)
+            console.print(f"CCI header ({timo.CCI_HEADER_SIZE} bytes): {header.hex()}")
+            status_ctx = (
+                console.status(
+                    _format_fw_progress(0, expected_blocks, 0), spinner="dots"
+                )
+                if sys.stdout.isatty()
+                else nullcontext(None)
+            )
+            with status_ctx as transfer_status:
+                total_blocks = 0
+                total_bytes = 0
+                for block_index, chunk_1, chunk_2 in timo.iter_cci_chunks(reader):
+                    total_blocks += 1
+                    _send_fw_block(
+                        client,
+                        timo.FW_BLOCK_CMD_1,
+                        chunk_1,
+                        max_transfer_bytes=max_transfer_bytes,
+                    )
+                    _send_fw_block(
+                        client,
+                        timo.FW_BLOCK_CMD_2,
+                        chunk_2,
+                        max_transfer_bytes=max_transfer_bytes,
+                    )
+                    total_bytes += len(chunk_1) + len(chunk_2)
+                    message = _format_fw_progress(
+                        block_index, expected_blocks, total_bytes
+                    )
+                    if transfer_status is not None:
+                        transfer_status.update(message)
+                    elif block_index == 1 or block_index % 16 == 0:
+                        console.print(message)
+                    data_blocks_sent = block_index - 1
+                    if data_blocks_sent > 0 and data_blocks_sent % 16 == 0:
+                        time.sleep(flush_wait_s)
+            if total_blocks == 0:
+                raise FirmwareUpdateError("CCI firmware contains no payload blocks")
+            return total_blocks, total_bytes, header
+    except OSError as exc:
+        raise FirmwareUpdateError(f"Unable to read firmware: {exc}") from exc
+    except ValueError as exc:
+        raise FirmwareUpdateError(str(exc)) from exc
+
+
 def _execute_timo_sequence(
     *,
     port: Optional[str],
@@ -453,7 +760,7 @@ def _execute_timo_sequence(
     responses: List[Dict[str, Any]] = []
     with spinner(f"{spinner_label} over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -1050,7 +1357,7 @@ def timo_dmx(
         mask = ((1 << width) - 1) << (total_bits - hi - 1)
         return (base & ~mask) | ((value & ((1 << width) - 1)) << (total_bits - hi - 1))
 
-    with NDJSONSerialClient(
+    with _open_serial_client(
         resolved_port,
         baudrate=baudrate,
         timeout=timeout,
@@ -1308,7 +1615,7 @@ def timo_device_name(
         data = payload[1:] if payload else b""
         return data.split(b"\x00", 1)[0].decode("ascii", errors="replace")
 
-    with NDJSONSerialClient(
+    with _open_serial_client(
         resolved_port,
         baudrate=baudrate,
         timeout=timeout,
@@ -1490,6 +1797,113 @@ def timo_read_dmx(
     _render_read_dmx_result(parsed, rx_frames)
 
 
+@timo_app.command("update-fw")
+def timo_update_fw(
+    ctx: typer.Context,
+    firmware: Path = typer.Argument(
+        ...,
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        resolve_path=True,
+        help="Path to TiMo .cci firmware image",
+    ),
+    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"
+    ),
+    flush_wait_ms: float = typer.Option(
+        100.0,
+        "--flush-wait-ms",
+        min=0.0,
+        help="Delay (ms) after each 16 data blocks (post-header)",
+    ),
+    final_wait_ms: float = typer.Option(
+        1000.0,
+        "--final-wait-ms",
+        min=0.0,
+        help="Delay (ms) after streaming all blocks to let TiMo finalize",
+    ),
+):
+    """Flash TiMo firmware by streaming a .cci file over FW_BLOCK commands."""
+
+    resources = _ctx_resources(ctx)
+    resolved_port = _require_port(port)
+    flush_wait_s = flush_wait_ms / 1000.0
+    final_wait_s = final_wait_ms / 1000.0
+    console.print(f"[cyan]Starting TiMo update via {firmware}[/]")
+
+    try:
+        with _open_serial_client(
+            resolved_port,
+            baudrate=baudrate,
+            timeout=timeout,
+            logger=resources.get("logger"),
+            seq_tracker=resources.get("seq_tracker"),
+        ) as client:
+            spi_caps = _ensure_spi_ready_for_update(
+                client, max_frame_bytes=1 + timo.FW_BLOCK_CMD_1_SIZE
+            )
+            _enter_update_mode(client)
+            max_transfer_bytes = int(spi_caps["max_transfer_bytes"])
+            blocks_sent, payload_bytes, header = _stream_fw_image(
+                client,
+                firmware_path=firmware,
+                max_transfer_bytes=max_transfer_bytes,
+                flush_wait_s=flush_wait_s,
+            )
+            console.print(
+                f"Waiting {final_wait_s:.3f}s for TiMo to finalize the update"
+            )
+            time.sleep(final_wait_s)
+            status_after = _read_status_byte(client)
+            if status_after & 0x80:
+                raise FirmwareUpdateError(
+                    "TiMo still reports UPDATE_MODE after sending all blocks"
+                )
+            version_bytes = _read_version_bytes(client)
+    except FirmwareUpdateError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+    except ShuttleSerialError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+
+    summary = Table(title="TiMo firmware update", show_header=False, box=None)
+    summary.add_column("Field", style="cyan", no_wrap=True)
+    summary.add_column("Value", style="white")
+    summary.add_row("Blocks transferred", str(blocks_sent))
+    summary.add_row("Data blocks", str(blocks_sent - 1))
+    summary.add_row("Bytes transferred", str(payload_bytes))
+    summary.add_row("CCI header", header.hex())
+    console.print(summary)
+
+    if len(version_bytes) < 8:
+        console.print(
+            "[yellow]VERSION register shorter than expected; unable to decode versions[/]"
+        )
+    else:
+        version_fields = timo.REGISTER_MAP["VERSION"]["fields"]
+        fw_field = version_fields["FW_VERSION"]["bits"]
+        hw_field = version_fields["HW_VERSION"]["bits"]
+        fw_version = timo.slice_bits(version_bytes, *fw_field)
+        hw_version = timo.slice_bits(version_bytes, *hw_field)
+        version_table = Table(title="TiMo VERSION", show_header=False, box=None)
+        version_table.add_column("Field", style="cyan", no_wrap=True)
+        version_table.add_column("Value", style="white")
+        version_table.add_row("FW_VERSION", f"0x{fw_version:08X}")
+        version_table.add_row("HW_VERSION", f"0x{hw_version:08X}")
+        console.print(version_table)
+
+    console.print("[green]TiMo firmware update complete[/]")
+
+
 @prodtest_app.command("reset")
 def prodtest_reset(
     ctx: typer.Context,
@@ -1568,7 +1982,9 @@ def prodtest_ping(
         raise typer.Exit(1)
 
     if len(responses) != len(sequence):
-        console.print("[red]Prodtest command halted before completing all SPI phases[/]")
+        console.print(
+            "[red]Prodtest command halted before completing all SPI phases[/]"
+        )
         raise typer.Exit(1)
 
     command_response, payload_response = responses
@@ -1583,9 +1999,7 @@ def prodtest_ping(
         command_label="spi.xfer (prodtest payload)",
     )
 
-    rx_bytes = _decode_hex_response(
-        payload_response, label="prodtest ping (payload)"
-    )
+    rx_bytes = _decode_hex_response(payload_response, label="prodtest ping (payload)")
     if not rx_bytes or rx_bytes[0] != 0x2D:  # ord('-')
         console.print(
             "[red]Ping failed: expected '-' (0x2D), got: "
@@ -1623,9 +2037,7 @@ def prodtest_antenna(
         antenna_value = PRODTEST_ANTENNA_CHOICES[normalized]
     except KeyError as exc:
         allowed = ", ".join(sorted(PRODTEST_ANTENNA_CHOICES))
-        raise typer.BadParameter(
-            f"Antenna must be one of: {allowed}"
-        ) from exc
+        raise typer.BadParameter(f"Antenna must be one of: {allowed}") from exc
 
     sequence = [prodtest.select_antenna(antenna_value)]
     responses = _execute_timo_sequence(
@@ -1767,7 +2179,9 @@ def prodtest_hw_device_id(
         raise typer.Exit(1)
 
     if len(responses) != len(sequence):
-        console.print("[red]Prodtest command halted before completing all SPI phases[/]")
+        console.print(
+            "[red]Prodtest command halted before completing all SPI phases[/]"
+        )
         raise typer.Exit(1)
 
     result_response = responses[-1]
@@ -1858,11 +2272,11 @@ def prodtest_serial_number(
             result_response,
             command_label="spi.xfer (prodtest payload)",
         )
-        rx_bytes = _decode_hex_response(
-            result_response, label="prodtest serial-number"
-        )
+        rx_bytes = _decode_hex_response(result_response, label="prodtest serial-number")
         if len(rx_bytes) < prodtest.SERIAL_NUMBER_LEN:
-            console.print("[red]Prodtest serial-number response shorter than expected[/]")
+            console.print(
+                "[red]Prodtest serial-number response shorter than expected[/]"
+            )
             raise typer.Exit(1)
         serial_bytes = rx_bytes[-prodtest.SERIAL_NUMBER_LEN :]
         console.print(f"Serial number: {_format_hex(serial_bytes.hex())}")
@@ -2178,7 +2592,7 @@ def spi_cfg_command(
     action = "Updating" if spi_payload else "Querying"
     with spinner(f"{action} spi.cfg over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2213,8 +2627,8 @@ def spi_enable_command(
     resolved_port = _require_port(port)
     with spinner(f"Enabling SPI over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
-                port=resolved_port,
+            with _open_serial_client(
+                resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
                 logger=resources.get("logger"),
@@ -2247,8 +2661,8 @@ def spi_disable_command(
     resolved_port = _require_port(port)
     with spinner(f"Disabling SPI over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
-                port=resolved_port,
+            with _open_serial_client(
+                resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
                 logger=resources.get("logger"),
@@ -2312,7 +2726,7 @@ def uart_cfg_command(
     action = "Updating" if uart_payload else "Querying"
     with spinner(f"{action} uart.cfg over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2375,7 +2789,7 @@ def uart_sub_command(
     action = "Updating" if sub_payload else "Querying"
     with spinner(f"{action} uart.sub over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2476,7 +2890,9 @@ def wifi_cfg_command(
     if parsed_gateway is not None:
         network_payload["gateway"] = parsed_gateway
 
-    dns_entries = [entry for entry in (parsed_dns_primary, parsed_dns_secondary) if entry]
+    dns_entries = [
+        entry for entry in (parsed_dns_primary, parsed_dns_secondary) if entry
+    ]
     if dns_entries:
         network_payload["dns"] = dns_entries
 
@@ -2492,7 +2908,7 @@ def wifi_cfg_command(
     action = "Updating" if wifi_payload else "Querying"
     with spinner(f"{action} wifi.cfg over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2575,7 +2991,7 @@ def uart_tx_command(
     byte_label = "byte" if payload_len == 1 else "bytes"
     with spinner(f"Sending {payload_len} UART {byte_label} over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2648,7 +3064,7 @@ def uart_rx_command(
 
     events_seen = 0
     try:
-        with NDJSONSerialClient(
+        with _open_serial_client(
             resolved_port,
             baudrate=baudrate,
             timeout=timeout,
@@ -2715,7 +3131,7 @@ def power_command(
 
     with spinner(f"{action} power over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2801,7 +3217,7 @@ def get_info(
     resolved_port = _require_port(port)
     with spinner(f"Querying get.info over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
@@ -2832,7 +3248,7 @@ def ping(
     resolved_port = _require_port(port)
     with spinner(f"Pinging device over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,

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
@@ -18,6 +19,12 @@ 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."""
 
@@ -229,10 +236,23 @@ class NDJSONSerialClient:
     ):
         try:
             self._serial = serial.serial_for_url(
-                url=port, baudrate=baudrate, timeout=timeout
+                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
+        except AttributeError:
+            # Test stubs without an open() method are already "connected"
+            pass
         self._serial.reset_input_buffer()
         self._lock = threading.Lock()
         self._pending: Dict[int, CommandFuture] = {}
@@ -243,6 +263,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
@@ -306,6 +327,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]:
@@ -413,8 +441,19 @@ 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]]:
@@ -458,6 +497,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:
@@ -499,3 +539,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

@@ -2,7 +2,7 @@
 # -*- 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 +18,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 +52,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",
@@ -420,7 +439,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 +453,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 +530,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