pico-uart 0.0.0.dev39596311668__py3-none-any.whl

pico_uart/__init__.py

@@ -0,0 +1,115 @@
+"""Python client tools for PicoUart hardware."""
+
+from .client import (
+    PicoUartHid,
+    read_board_status,
+    read_board_temperature,
+    read_feature,
+    read_firmware_version,
+    read_configuration,
+    read_hardware_info,
+    read_overflow_counts,
+    reset_board,
+    send_command,
+)
+from .protocol import (
+    BOARD_STATUS_FLAG_HID_RESET,
+    BOARD_STATUS_LAYOUT_VERSION,
+    BOARD_STATUS_RESERVED0_KNOWN_FLAGS,
+    BOARD_STATUS_SIZE,
+    CONFIGURATION_SIZE,
+    COMMAND_ARM_RESET,
+    COMMAND_RESET_BOARD,
+    COMMAND_TOGGLE_LED,
+    HARDWARE_INFO_LAYOUT_VERSION,
+    HARDWARE_INFO_SIZE,
+    MCU_RP2040,
+    MCU_RP2350,
+    OVERFLOW_COUNTS_SIZE,
+    REPORT_ID_BOARD_STATUS,
+    REPORT_ID_COMMAND,
+    REPORT_ID_CONFIGURATION,
+    REPORT_ID_HARDWARE_INFO,
+    REPORT_ID_OVERFLOW_COUNTS,
+    REPORT_ID_STATUS,
+    RESET_ARM_WINDOW_S,
+    STATUS_CHANNEL_SIZE,
+    STATUS_HEADER_SIZE,
+    STATUS_LAYOUT_VERSION,
+    STATUS_SIGNATURE,
+    STATUS_SIZE,
+    UART_CHANNEL_COUNT,
+    decode_health,
+    parse_board_status,
+    parse_configuration,
+    parse_hardware_info,
+    parse_overflow_counts,
+    parse_status,
+    require_payload,
+)
+from .transport import (
+    HID_INTERFACE_NUMBER,
+    PRODUCT_ID,
+    PRODUCT_STRING,
+    USAGE,
+    USAGE_PAGE,
+    VENDOR_ID,
+    hid,
+    open_device,
+    open_enumerated_device,
+)
+
+__all__ = [
+    "PicoUartHid",
+    "read_board_status",
+    "read_board_temperature",
+    "read_feature",
+    "read_firmware_version",
+    "read_configuration",
+    "read_hardware_info",
+    "read_overflow_counts",
+    "reset_board",
+    "send_command",
+    "BOARD_STATUS_FLAG_HID_RESET",
+    "BOARD_STATUS_LAYOUT_VERSION",
+    "BOARD_STATUS_RESERVED0_KNOWN_FLAGS",
+    "BOARD_STATUS_SIZE",
+    "CONFIGURATION_SIZE",
+    "COMMAND_ARM_RESET",
+    "COMMAND_RESET_BOARD",
+    "COMMAND_TOGGLE_LED",
+    "HID_INTERFACE_NUMBER",
+    "HARDWARE_INFO_LAYOUT_VERSION",
+    "HARDWARE_INFO_SIZE",
+    "MCU_RP2040",
+    "MCU_RP2350",
+    "OVERFLOW_COUNTS_SIZE",
+    "PRODUCT_ID",
+    "PRODUCT_STRING",
+    "REPORT_ID_BOARD_STATUS",
+    "REPORT_ID_COMMAND",
+    "REPORT_ID_CONFIGURATION",
+    "REPORT_ID_HARDWARE_INFO",
+    "REPORT_ID_OVERFLOW_COUNTS",
+    "REPORT_ID_STATUS",
+    "RESET_ARM_WINDOW_S",
+    "STATUS_CHANNEL_SIZE",
+    "STATUS_HEADER_SIZE",
+    "STATUS_LAYOUT_VERSION",
+    "STATUS_SIGNATURE",
+    "STATUS_SIZE",
+    "UART_CHANNEL_COUNT",
+    "USAGE",
+    "USAGE_PAGE",
+    "VENDOR_ID",
+    "decode_health",
+    "hid",
+    "open_device",
+    "open_enumerated_device",
+    "parse_board_status",
+    "parse_configuration",
+    "parse_hardware_info",
+    "parse_overflow_counts",
+    "parse_status",
+    "require_payload",
+]

pico_uart/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pico_uart/cli.py

@@ -0,0 +1,121 @@
+"""Command-line interface for PicoUart HID diagnostics and board controls."""
+
+import argparse
+import json
+import math
+import sys
+import time
+
+from .client import PicoUartHid
+from .protocol import decode_health
+
+
+def print_status(status: dict[str, object]) -> None:
+    """Print one concise status report for monitor and status commands."""
+    channels = " ".join(
+        f"cdc{channel['id']} health=0x{channel['health']:02x}"
+        f"[{','.join(decode_health(channel['health'])) or '-'}] "
+        f"uart_tx/rx={channel['controller_tx_bytes']}/{channel['controller_rx_bytes']} "
+        f"cdc_tx/rx={channel['cdc_tx_bytes']}/{channel['cdc_rx_bytes']} "
+        f"ring_peak={channel['ring_high_watermark']}"
+        for channel in status["channels"]
+    )
+    print(f"seq={status['sequence']} {channels}")
+
+
+def monitor(client: PicoUartHid, duration: float) -> None:
+    """Print valid status reports until the requested duration expires."""
+    deadline = time.monotonic() + duration
+    valid_reports = 0
+    while time.monotonic() < deadline:
+        status = client.read_status(timeout_ms=250)
+        if status is None:
+            continue
+        print_status(status)
+        valid_reports += 1
+    if valid_reports == 0:
+        raise RuntimeError("monitor timed out without receiving a valid status report")
+
+
+def parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse the HID command-line interface."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    selection = parser.add_mutually_exclusive_group()
+    selection.add_argument("--serial", help="select a PicoUart HID interface by USB serial number")
+    selection.add_argument("--device-path", help="select a PicoUart HID interface by hidapi path")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    monitor_parser = commands.add_parser("monitor", help="print periodic status reports")
+    monitor_parser.add_argument("--duration", type=float, default=5.0, help="monitor duration in seconds")
+    status_parser = commands.add_parser("status", help="read one channel status report")
+    status_parser.add_argument("--timeout", type=float, default=2.0, help="status read timeout in seconds")
+    status_parser.add_argument("--json", action="store_true", help="print status as JSON")
+    commands.add_parser("temperature", help="read the internal board temperature")
+    commands.add_parser("version", help="read the firmware semantic version (MAJOR.MINOR.PATCH)")
+    commands.add_parser("overruns", help="read cumulative UART RX dropped-byte counts")
+    commands.add_parser("hardware", help="read MCU identity and current system clock as JSON")
+    commands.add_parser("config", help="read persistent configuration diagnostics as JSON")
+    commands.add_parser("toggle-led", help="toggle the board's default LED")
+    commands.add_parser(
+        "reset",
+        help="arm then reset the board (requires firmware HID reset support)",
+    )
+    web_parser = commands.add_parser("web", help="start the local Flask diagnostics dashboard")
+    web_parser.add_argument("--port", type=int, default=5000, help="local web server port")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the selected PicoUart HID command."""
+    arguments = parse_arguments(argv)
+    if arguments.command == "monitor" and (not math.isfinite(arguments.duration) or arguments.duration <= 0):
+        raise SystemExit("--duration must be a finite value greater than zero")
+    if arguments.command == "status" and (not math.isfinite(arguments.timeout) or arguments.timeout <= 0):
+        raise SystemExit("--timeout must be a finite value greater than zero")
+    if arguments.command == "web":
+        if not 1 <= arguments.port <= 65535:
+            raise SystemExit("--port must be between 1 and 65535")
+        try:
+            from .web.app import run_server
+
+            run_server(arguments.port, arguments.serial, arguments.device_path)
+        except (OSError, RuntimeError) as error:
+            print(f"error: {error}", file=sys.stderr)
+            return 1
+        return 0
+
+    try:
+        with PicoUartHid(arguments.serial, arguments.device_path) as client:
+            if arguments.command == "monitor":
+                monitor(client, arguments.duration)
+            elif arguments.command == "status":
+                deadline = time.monotonic() + arguments.timeout
+                status = None
+                while status is None and time.monotonic() < deadline:
+                    remaining_ms = max(1, min(250, int((deadline - time.monotonic()) * 1000)))
+                    status = client.read_status(remaining_ms)
+                if status is None:
+                    raise RuntimeError("timed out without receiving a valid status report")
+                if arguments.json:
+                    print(json.dumps(status, sort_keys=True))
+                else:
+                    print_status(status)
+            elif arguments.command == "temperature":
+                print(f"temperature={client.read_board_temperature():.2f} C")
+            elif arguments.command == "version":
+                print(client.read_firmware_version())
+            elif arguments.command == "overruns":
+                print(" ".join(f"cdc{index}={count}" for index, count in enumerate(client.read_overflow_counts())))
+            elif arguments.command == "hardware":
+                print(json.dumps(client.read_hardware_info(), sort_keys=True))
+            elif arguments.command == "config":
+                print(json.dumps(client.read_configuration(), sort_keys=True))
+            elif arguments.command == "toggle-led":
+                client.toggle_led()
+            elif arguments.command == "reset":
+                client.reset_board()
+    except (OSError, RuntimeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+
+    return 0

pico_uart/client.py

@@ -0,0 +1,245 @@
+"""Resource-owning Python API for PicoUart's HID status and board controls."""
+
+import threading
+import time
+import struct
+from typing import Any
+
+from .protocol import (
+    BOARD_STATUS_FLAG_HID_RESET,
+    BOARD_STATUS_SIZE,
+    COMMAND_ARM_RESET,
+    COMMAND_RESET_BOARD,
+    COMMAND_TOGGLE_LED,
+    HARDWARE_INFO_SIZE,
+    IDENTITY_SIZE,
+    RUNTIME_SIZE,
+    LED_SIZE,
+    REPORT_ID_LED,
+    parse_led,
+    OVERFLOW_COUNTS_SIZE,
+    REPORT_ID_BOARD_STATUS,
+    REPORT_ID_COMMAND,
+    REPORT_ID_OVERFLOW_COUNTS,
+    REPORT_ID_HARDWARE_INFO,
+    REPORT_ID_IDENTITY,
+    REPORT_ID_RUNTIME,
+    REPORT_ID_STATUS,
+    RESET_ARM_WINDOW_S,
+    STATUS_SIZE,
+    parse_board_status,
+    parse_hardware_info,
+    parse_identity,
+    parse_runtime,
+    parse_overflow_counts,
+    parse_status,
+    require_payload,
+    REPORT_ID_CHANNEL_BASE,
+    CHANNEL_DIAGNOSTICS_SIZE,
+    parse_channel_diagnostics,
+    REPORT_ID_CONFIGURATION,
+    CONFIGURATION_SIZE,
+    parse_configuration,
+    REPORT_ID_CONFIGURATION_SAVE,
+    CONFIGURATION_SAVE_SIZE,
+    parse_configuration_save,
+)
+from .transport import open_device
+
+
+def read_feature(device: Any, report_id: int, payload_size: int) -> bytes:
+    """Read a fixed-size feature report, excluding its HID report ID."""
+    return require_payload(
+        device.get_feature_report(report_id, payload_size + 1),
+        report_id,
+        payload_size,
+    )
+
+
+def read_board_status(device: Any) -> dict[str, object]:
+    """Read temperature, firmware version, and board capabilities."""
+    payload = read_feature(device, REPORT_ID_BOARD_STATUS, BOARD_STATUS_SIZE)
+    return parse_board_status(payload)
+
+
+def read_board_temperature(device: Any) -> float:
+    """Read the internal RP2 temperature estimate in degrees Celsius."""
+    return float(read_board_status(device)["temperature_celsius"])
+
+
+def read_firmware_version(device: Any) -> str:
+    """Read the firmware semantic version (MAJOR.MINOR.PATCH) from HID."""
+    return str(read_board_status(device)["firmware_version"])
+
+
+def read_overflow_counts(device: Any) -> list[int]:
+    """Read cumulative UART-to-USB dropped-byte counts for every channel."""
+    payload = read_feature(device, REPORT_ID_OVERFLOW_COUNTS, OVERFLOW_COUNTS_SIZE)
+    return parse_overflow_counts(payload)
+
+
+def read_hardware_info(device: Any) -> dict[str, object]:
+    """Read the MCU model and current system clock from hardware-info report 6."""
+    return parse_hardware_info(read_feature(device, REPORT_ID_HARDWARE_INFO, HARDWARE_INFO_SIZE))
+
+
+def read_configuration(device: Any) -> dict[str, object]:
+    """Read persistent configuration diagnostics without exposing stored data."""
+    return parse_configuration(read_feature(device, REPORT_ID_CONFIGURATION, CONFIGURATION_SIZE))
+
+
+def send_command(device: Any, command: int) -> None:
+    """Send a one-byte board command through the HID feature-report path."""
+    bytes_written = device.send_feature_report([REPORT_ID_COMMAND, command])
+    if bytes_written != 2:
+        raise RuntimeError(f"HID command write was incomplete: wrote {bytes_written} bytes")
+
+
+def reset_board(device: Any) -> None:
+    """Arm then reset the board only when firmware enables remote reset."""
+    if not read_board_status(device)["hid_reset_enabled"]:
+        raise RuntimeError("firmware HID reset is disabled; rebuild with -DPICO_UART_ALLOW_HID_RESET=1")
+    send_command(device, COMMAND_ARM_RESET)
+    time.sleep(min(0.05, RESET_ARM_WINDOW_S / 10.0))
+    send_command(device, COMMAND_RESET_BOARD)
+
+
+class PicoUartHid:
+    """Own a PicoUart HID connection and expose decoded status and controls."""
+
+    def __init__(
+        self,
+        serial_number: str | None = None,
+        device_path: str | None = None,
+        device: Any | None = None,
+    ) -> None:
+        if device is not None and (serial_number is not None or device_path is not None):
+            raise ValueError("an injected device cannot be combined with a device selector")
+        self._device = device if device is not None else open_device(serial_number, device_path)
+        self._lock = threading.RLock()
+        self._closed = False
+
+    def _require_open(self) -> Any:
+        if self._closed:
+            raise RuntimeError("PicoUart HID connection is closed")
+        return self._device
+
+    def read_status(self, timeout_ms: int = 250) -> dict[str, object] | None:
+        """Read one periodic channel report, returning None if none is ready."""
+        if timeout_ms < 0:
+            raise ValueError("timeout_ms must not be negative")
+        with self._lock:
+            report = self._require_open().read(STATUS_SIZE + 1, timeout_ms)
+        if not report:
+            return None
+        if report[0] != REPORT_ID_STATUS:
+            raise RuntimeError(f"unexpected HID report ID {report[0]}")
+        return parse_status(bytes(report[1:]))
+
+    def read_board_status(self) -> dict[str, object]:
+        with self._lock:
+            return read_board_status(self._require_open())
+
+    def read_board_temperature(self) -> float:
+        return float(self.read_board_status()["temperature_celsius"])
+
+    def read_firmware_version(self) -> str:
+        return str(self.read_board_status()["firmware_version"])
+
+    def read_overflow_counts(self) -> list[int]:
+        with self._lock:
+            return read_overflow_counts(self._require_open())
+
+    def read_hardware_info(self) -> dict[str, object]:
+        with self._lock:
+            return read_hardware_info(self._require_open())
+
+    def read_configuration(self) -> dict[str, object]:
+        with self._lock:
+            return read_configuration(self._require_open())
+
+    def read_configuration_save(self) -> dict[str, object]:
+        """Read the most recent persistent profile save result."""
+        with self._lock:
+            return parse_configuration_save(read_feature(
+                self._require_open(), REPORT_ID_CONFIGURATION_SAVE, CONFIGURATION_SAVE_SIZE))
+
+    def save_configuration(self, profile: int, unsafe_overclock: bool = False) -> dict[str, object]:
+        """Persist a supported clock profile; firmware reboots after confirming the save."""
+        if type(profile) is not int or profile not in (0, 1, 2) or type(unsafe_overclock) is not bool:
+            raise ValueError("invalid clock profile or overclock acknowledgement")
+        if profile != 0 and not unsafe_overclock:
+            raise ValueError("non-default clocks require explicit unsafe overclock acknowledgement")
+        with self._lock:
+            device = self._require_open()
+            hardware = self.read_hardware_info()
+            supported = {1: (0, 1), 2: (0, 2)}.get(hardware["mcu_id"], ())
+            if profile not in supported:
+                raise ValueError("clock profile is not supported on this MCU")
+            if self.read_configuration_save()["status"] == 1:
+                raise RuntimeError("a configuration save is already pending")
+            payload = bytes([REPORT_ID_CONFIGURATION_SAVE]) + struct.pack(
+                "<BBHI", 1, int(unsafe_overclock), 0, profile)
+            written = device.send_feature_report(list(payload))
+            if written != len(payload):
+                raise RuntimeError(f"HID configuration write was incomplete: wrote {written} bytes")
+            deadline = time.monotonic() + 3.0
+            errors = {
+                3: "firmware rejected the configuration request",
+                4: "close all CDC ports and stop UART traffic before saving configuration",
+                5: "configuration flash write or verification failed",
+            }
+            while time.monotonic() < deadline:
+                result = self.read_configuration_save()
+                status = result["status"]
+                if status in errors:
+                    raise RuntimeError(errors[status])
+                if result["profile"] != profile:
+                    raise RuntimeError("configuration save result does not match the requested profile")
+                if status == 2:
+                    return result
+                time.sleep(0.05)
+            raise RuntimeError("configuration save timed out; read back the configuration before retrying")
+
+    def read_identity(self) -> dict[str, object]:
+        """Read the product and USB serial / board UID."""
+        with self._lock:
+            return parse_identity(read_feature(self._require_open(), REPORT_ID_IDENTITY, IDENTITY_SIZE))
+
+    def read_runtime(self) -> dict[str, object]:
+        """Read the device's runtime counters, not host session estimates."""
+        with self._lock:
+            return parse_runtime(read_feature(self._require_open(), REPORT_ID_RUNTIME, RUNTIME_SIZE))
+
+    def read_channel_diagnostics(self) -> list[dict[str, object]]:
+        """Read six independently addressed channel diagnostic feature reports."""
+        with self._lock:
+            return [parse_channel_diagnostics(read_feature(
+                self._require_open(), REPORT_ID_CHANNEL_BASE + index, CHANNEL_DIAGNOSTICS_SIZE))
+                for index in range(6)]
+
+    def toggle_led(self) -> None:
+        with self._lock:
+            send_command(self._require_open(), COMMAND_TOGGLE_LED)
+
+    def read_led(self) -> dict[str, bool | None]:
+        """Read the manual override and physical LED output."""
+        with self._lock:
+            return parse_led(read_feature(self._require_open(), REPORT_ID_LED, LED_SIZE))
+
+    def reset_board(self) -> None:
+        with self._lock:
+            reset_board(self._require_open())
+
+    def close(self) -> None:
+        with self._lock:
+            if not self._closed:
+                self._device.close()
+                self._closed = True
+
+    def __enter__(self) -> "PicoUartHid":
+        self._require_open()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()