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

shuttle/cli.py

@@ -2,10 +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
 
@@ -105,7 +108,12 @@ 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+$")
 
 # Backwards-compatible aliases for tests and external callers
 _SerialLogger = SerialLogger
@@ -116,6 +124,66 @@ 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)}[/]")
+
+
+def _flush_client_input(client) -> None:
+    """Best-effort drain any unread serial noise before issuing commands."""
+
+    flush = getattr(client, "flush_input_and_log", None)
+    if flush is None:
+        return
+    try:
+        flush()
+    except Exception:
+        # Flushing is opportunistic; failures should not leak into CLI flows.
+        pass
+
+
+@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."""
@@ -154,9 +222,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]
 
 
@@ -251,9 +317,22 @@ def _resolve_uart_payload(
     return payload_bytes.hex(), len(payload_bytes)
 
 
+def _normalize_port(port: str) -> str:
+    trimmed = port.strip()
+    if not trimmed:
+        raise typer.BadParameter("Serial port is required (use --port or SHUTTLE_PORT)")
+    if "://" in trimmed:
+        return trimmed
+    if trimmed.startswith("/") or trimmed.startswith("\\"):
+        return trimmed
+    if _HOST_PORT_PATTERN.match(trimmed) or _IPV6_HOST_PORT_PATTERN.match(trimmed):
+        return f"socket://{trimmed}"
+    return trimmed
+
+
 def _require_port(port: Optional[str]) -> str:
     if port:
-        return port
+        return _normalize_port(port)
     raise typer.BadParameter("Serial port is required (use --port or SHUTTLE_PORT)")
 
 
@@ -269,6 +348,16 @@ def _parse_int_option(value: str, *, name: str) -> int:
     return parsed
 
 
+def _parse_ipv4(value: Optional[str], *, name: str) -> Optional[str]:
+    if value is None:
+        return None
+    try:
+        ipaddress.IPv4Address(value)
+    except ipaddress.AddressValueError as exc:
+        raise typer.BadParameter(f"{name} must be a valid IPv4 address") from exc
+    return value
+
+
 def _parse_prodtest_mask(value: str) -> bytes:
     try:
         return prodtest.mask_from_hex(value)
@@ -409,6 +498,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],
@@ -423,13 +773,16 @@ 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,
                 logger=logger,
                 seq_tracker=seq_tracker,
             ) as client:
+                # Drain any pending serial noise before issuing commands, to avoid
+                # mixing stale data into NDJSON responses.
+                _flush_client_input(client)
                 for transfer in sequence:
                     response = client.spi_xfer(**transfer)
                     responses.append(response)
@@ -1020,7 +1373,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,
@@ -1271,14 +1624,14 @@ def timo_device_name(
     resolved_port = _require_port(port)
 
     def _read_name(client) -> str:
-        seq = timo.read_reg_sequence(reg_meta["address"], reg_meta.get("length", 16))
+        seq = timo.read_reg_sequence(reg_meta["address"], reg_meta.get("length", 32))
         responses = [client.spi_xfer(**cmd) for cmd in seq]
         rx = responses[-1].get("rx", "")
         payload = bytes.fromhex(rx) if isinstance(rx, str) else b""
         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,
@@ -1460,6 +1813,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,
@@ -1521,17 +1981,49 @@ def prodtest_ping(
         logger=resources.get("logger"),
         seq_tracker=resources.get("seq_tracker"),
     )
-    if not responses or len(responses) < 2:
+    if not responses:
         console.print("[red]Device returned no response[/]")
         raise typer.Exit(1)
-    rx2 = responses[1].get("rx", "")
-    if rx2 and isinstance(rx2, str):
-        rx_bytes = bytes.fromhex(rx2)
-        if rx_bytes and rx_bytes[0] == 0x2D:  # ord('-')
-            console.print("[green]Ping successful: got '-' response[/]")
-            return
-    console.print(f"[red]Ping failed: expected '-' (0x2D), got: {rx2}[/]")
-    raise typer.Exit(1)
+
+    failed_idx = next(
+        (idx for idx, resp in enumerate(responses) if not resp.get("ok")), None
+    )
+    if failed_idx is not None:
+        phase = "command" if failed_idx == 0 else "payload"
+        _render_spi_response(
+            f"prodtest ping ({phase})",
+            responses[failed_idx],
+            command_label=f"spi.xfer (prodtest {phase})",
+        )
+        raise typer.Exit(1)
+
+    if len(responses) != len(sequence):
+        console.print(
+            "[red]Prodtest command halted before completing all SPI phases[/]"
+        )
+        raise typer.Exit(1)
+
+    command_response, payload_response = responses
+    _render_spi_response(
+        "prodtest ping (command)",
+        command_response,
+        command_label="spi.xfer (prodtest command)",
+    )
+    _render_spi_response(
+        "prodtest ping (payload)",
+        payload_response,
+        command_label="spi.xfer (prodtest 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: "
+            f"{_format_hex(payload_response.get('rx', ''))}[/]"
+        )
+        raise typer.Exit(1)
+
+    console.print("[green]Ping successful: got '-' response[/]")
 
 
 @prodtest_app.command("antenna")
@@ -1561,9 +2053,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(
@@ -1705,7 +2195,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]
@@ -1796,11 +2288,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())}")
@@ -2116,7 +2608,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,
@@ -2151,13 +2643,14 @@ 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"),
                 seq_tracker=resources.get("seq_tracker"),
             ) as client:
+                _flush_client_input(client)
                 response = client.spi_enable()
         except ShuttleSerialError as exc:
             console.print(f"[red]{exc}[/]")
@@ -2185,13 +2678,14 @@ 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"),
                 seq_tracker=resources.get("seq_tracker"),
             ) as client:
+                _flush_client_input(client)
                 response = client.spi_disable()
         except ShuttleSerialError as exc:
             console.print(f"[red]{exc}[/]")
@@ -2250,7 +2744,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,
@@ -2313,7 +2807,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,
@@ -2328,6 +2822,125 @@ def uart_sub_command(
     _render_payload_response("uart.sub", response)
 
 
+@app.command("wifi-cfg")
+def wifi_cfg_command(
+    ctx: typer.Context,
+    port: Optional[str] = typer.Option(
+        None,
+        "--port",
+        envvar="SHUTTLE_PORT",
+        help="Serial port or host:port (e.g., /dev/ttyUSB0 or 192.168.1.10:5000)",
+    ),
+    baudrate: int = typer.Option(DEFAULT_BAUD, "--baud", help="Serial baud rate"),
+    timeout: float = typer.Option(
+        DEFAULT_TIMEOUT, "--timeout", help="Read timeout in seconds"
+    ),
+    ssid: Optional[str] = typer.Option(
+        None,
+        "--ssid",
+        help="Set the station SSID",
+        show_default=False,
+    ),
+    psk: Optional[str] = typer.Option(
+        None,
+        "--psk",
+        help="Set the WPA/WPA2/WPA3 passphrase",
+        show_default=False,
+    ),
+    dhcp: Optional[bool] = typer.Option(
+        None,
+        "--dhcp/--static",
+        help="Enable DHCP or force static IPv4 addressing",
+    ),
+    ip_addr: Optional[str] = typer.Option(
+        None,
+        "--ip",
+        help="Static IPv4 address (requires --static or other static fields)",
+        show_default=False,
+    ),
+    netmask: Optional[str] = typer.Option(
+        None,
+        "--netmask",
+        help="Static subnet mask (e.g., 255.255.255.0)",
+        show_default=False,
+    ),
+    gateway: Optional[str] = typer.Option(
+        None,
+        "--gateway",
+        help="Static default gateway IPv4 address",
+        show_default=False,
+    ),
+    dns: Optional[str] = typer.Option(
+        None,
+        "--dns",
+        help="Primary DNS server IPv4 address",
+        show_default=False,
+    ),
+    dns_alt: Optional[str] = typer.Option(
+        None,
+        "--dns-alt",
+        help="Secondary DNS server IPv4 address",
+        show_default=False,
+    ),
+):
+    """Query or update Wi-Fi credentials and network settings."""
+
+    resources = _ctx_resources(ctx)
+    wifi_payload: Dict[str, Any] = {}
+    if ssid is not None:
+        wifi_payload["ssid"] = ssid
+    if psk is not None:
+        wifi_payload["psk"] = psk
+    if dhcp is not None:
+        wifi_payload["dhcp"] = dhcp
+
+    network_payload: Dict[str, Any] = {}
+    parsed_ip = _parse_ipv4(ip_addr, name="--ip")
+    parsed_mask = _parse_ipv4(netmask, name="--netmask")
+    parsed_gateway = _parse_ipv4(gateway, name="--gateway")
+    parsed_dns_primary = _parse_ipv4(dns, name="--dns")
+    parsed_dns_secondary = _parse_ipv4(dns_alt, name="--dns-alt")
+
+    if parsed_ip is not None:
+        network_payload["ip"] = parsed_ip
+    if parsed_mask is not None:
+        network_payload["netmask"] = parsed_mask
+    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
+    ]
+    if dns_entries:
+        network_payload["dns"] = dns_entries
+
+    if network_payload:
+        if wifi_payload.get("dhcp") is True:
+            raise typer.BadParameter(
+                "Static network options cannot be combined with --dhcp"
+            )
+        wifi_payload.setdefault("dhcp", False)
+        wifi_payload["network"] = network_payload
+
+    resolved_port = _require_port(port)
+    action = "Updating" if wifi_payload else "Querying"
+    with spinner(f"{action} wifi.cfg over {resolved_port}"):
+        try:
+            with _open_serial_client(
+                resolved_port,
+                baudrate=baudrate,
+                timeout=timeout,
+                logger=resources.get("logger"),
+                seq_tracker=resources.get("seq_tracker"),
+            ) as client:
+                response = client.wifi_cfg(wifi_payload if wifi_payload else None)
+        except ShuttleSerialError as exc:
+            console.print(f"[red]{exc}[/]")
+            raise typer.Exit(1) from exc
+
+    _render_payload_response("wifi.cfg", response)
+
+
 @app.command("uart-tx")
 def uart_tx_command(
     ctx: typer.Context,
@@ -2396,7 +3009,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,
@@ -2469,7 +3082,7 @@ def uart_rx_command(
 
     events_seen = 0
     try:
-        with NDJSONSerialClient(
+        with _open_serial_client(
             resolved_port,
             baudrate=baudrate,
             timeout=timeout,
@@ -2536,13 +3149,14 @@ def power_command(
 
     with spinner(f"{action} power over {resolved_port}"):
         try:
-            with NDJSONSerialClient(
+            with _open_serial_client(
                 resolved_port,
                 baudrate=baudrate,
                 timeout=timeout,
                 logger=resources.get("logger"),
                 seq_tracker=resources.get("seq_tracker"),
             ) as client:
+                _flush_client_input(client)
                 method = getattr(client, method_name)
                 response = method()
         except ShuttleSerialError as exc:
@@ -2576,6 +3190,11 @@ def flash_command(
         "--erase-first/--no-erase-first",
         help="Erase the entire flash before writing",
     ),
+    sleep_after_flash: float = typer.Option(
+        1.25,
+        "--sleep-after-flash",
+        help="Seconds to wait after flashing to allow device reboot",
+    ),
 ):
     """Flash the bundled firmware image to the devboard."""
 
@@ -2599,6 +3218,24 @@ def flash_command(
             console.print(f"[red]{exc}[/]")
             raise typer.Exit(1) from exc
 
+    if sleep_after_flash:
+        time.sleep(
+            sleep_after_flash
+        )  # Give the device a moment to reboot. 0.75s is sometimes too short.
+
+    # After flashing, drain/log any startup output from the device before further commands
+    logger = ctx.obj["logger"] if ctx.obj and "logger" in ctx.obj else None
+    try:
+        from .serial_client import NDJSONSerialClient
+
+        # Use a short timeout just for draining
+        with NDJSONSerialClient(
+            resolved_port, baudrate=baudrate, timeout=0.5, logger=logger
+        ) as client:
+            _flush_client_input(client)
+    except Exception:
+        pass
+
     label = str(manifest.get("label", board))
     console.print(
         f"[green]Successfully flashed {label} ({board}) over {resolved_port}[/]"
@@ -2622,7 +3259,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,
@@ -2653,7 +3290,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,