embeddedci 0.1.0__py3-none-any.whl

embeddedci/__init__.py

@@ -0,0 +1,20 @@
+"""embeddedci — Python tooling for EmbeddedCI hardware.
+
+The :mod:`embeddedci.benchpod` subpackage is a pytest-friendly client for a
+BenchPod device. Import it as::
+
+    from embeddedci import benchpod
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import benchpod
+
+try:
+    __version__ = version("embeddedci")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["benchpod", "__version__"]

embeddedci/benchpod/__init__.py

@@ -0,0 +1,95 @@
+"""BenchPod — a pytest-friendly client for an EmbeddedCI BenchPod device.
+
+Connect over wifi/network or serial, power the target, flash firmware and assert
+the result, all from a test::
+
+    from embeddedci import benchpod
+
+    def test_boots(benchpod_device):  # the `benchpod` fixture is also available
+        benchpod_device.power_on(benchpod.INTERNAL)
+        result = benchpod_device.flash(
+            file="firmware.elf", target="target/stm32f1x.cfg",
+            swclk=benchpod.PIN1, swdio=benchpod.PIN2, nreset=benchpod.PIN3,
+            target_power=benchpod.INTERNAL,
+        )
+        assert result.ok
+"""
+
+from __future__ import annotations
+
+from . import i2c
+from .client import BenchPod
+from .connection import ConnSpec, parse_connection, resolve_connection
+from .i2c import I2CByte, I2CMessage, I2CTransaction
+from .constants import (
+    BMP280_ADDR_PRIMARY,
+    BMP280_ADDR_SECONDARY,
+    EXTERNAL,
+    INTERNAL,
+    PIN1,
+    PIN2,
+    PIN3,
+    PIN4,
+    PIN5,
+    PIN6,
+    PIN7,
+    PIN8,
+    PIN9,
+    PIN10,
+    PIN11,
+    PIN12,
+    Efuse,
+    Pin,
+    Sensor,
+)
+from .errors import (
+    BenchPodError,
+    ConnectionConfigError,
+    FirmwareError,
+    FlashError,
+    TargetUnreachableError,
+    TransportError,
+)
+from .flash import FlashResult
+from .uart import UartCapture
+
+__all__ = [
+    "BenchPod",
+    "FlashResult",
+    "UartCapture",
+    "i2c",
+    "I2CByte",
+    "I2CMessage",
+    "I2CTransaction",
+    # connection
+    "ConnSpec",
+    "resolve_connection",
+    "parse_connection",
+    # constants
+    "Efuse",
+    "Pin",
+    "Sensor",
+    "INTERNAL",
+    "EXTERNAL",
+    "BMP280_ADDR_PRIMARY",
+    "BMP280_ADDR_SECONDARY",
+    "PIN1",
+    "PIN2",
+    "PIN3",
+    "PIN4",
+    "PIN5",
+    "PIN6",
+    "PIN7",
+    "PIN8",
+    "PIN9",
+    "PIN10",
+    "PIN11",
+    "PIN12",
+    # errors
+    "BenchPodError",
+    "ConnectionConfigError",
+    "TransportError",
+    "FirmwareError",
+    "FlashError",
+    "TargetUnreachableError",
+]

embeddedci/benchpod/client.py

@@ -0,0 +1,314 @@
+"""The :class:`BenchPod` facade — the user-facing API.
+
+Wraps a :class:`~embeddedci.benchpod.transport.base.Transport` with intuitive,
+named operations: connect, power on/off, flash (and assert ok/not ok), plus a
+stubbed I2C sensor hook. Designed to drop straight into pytest::
+
+    from embeddedci import benchpod
+
+    with benchpod.BenchPod("192.168.1.213") as bp:
+        bp.power_on(benchpod.INTERNAL)
+        assert bp.flash(file="fw.elf", target="target/stm32f1x.cfg",
+                        swclk=benchpod.PIN1, swdio=benchpod.PIN2).ok
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, List, Optional, Sequence, Union
+
+from . import flash as _flash
+from . import i2c as _i2c
+from . import sensor as _sensor
+from . import uart as _uart
+from .constants import Efuse, Pin, Sensor, coerce_efuse, coerce_pin
+from .connection import resolve_connection
+from .errors import BenchPodError
+from .flash import FlashResult
+from .transport import Transport, open_transport
+
+
+class BenchPod:
+    """A connected BenchPod device."""
+
+    def __init__(
+        self,
+        connection: Optional[str] = None,
+        *,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        """Open a BenchPod.
+
+        ``connection`` is a host[:port], a serial device path, or ``"serial"``;
+        when omitted the ``BENCHPOD_CONNECTION`` environment variable is used.
+        Pass ``transport`` directly to inject a custom/standalone backend.
+        """
+        self.timeout = timeout
+        if transport is not None:
+            self._transport: Transport = transport
+        else:
+            spec = resolve_connection(connection)
+            self._transport = open_transport(spec, timeout=timeout)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "BenchPod":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- basic status -------------------------------------------------------
+
+    def ping(self) -> Any:
+        """Confirm the pod is reachable."""
+        return self._transport.ping()
+
+    def status(self) -> Any:
+        """Return firmware/connection status."""
+        return self._transport.status()
+
+    # -- power --------------------------------------------------------------
+
+    def target_power(self, efuse: Union[Efuse, int] = Efuse.INTERNAL, *,
+                     on: bool, delay: Optional[float] = None) -> None:
+        """Enable or disable a target-power eFuse.
+
+        ``delay`` (seconds) schedules the change pod-side and returns
+        immediately — handy to power-on *during* a UART capture.
+        """
+        delay_ms = int(round(delay * 1000)) if delay else 0
+        self._transport.target_power(coerce_efuse(efuse), on, delay_ms)
+
+    def power_on(self, efuse: Union[Efuse, int] = Efuse.INTERNAL,
+                 *, delay: Optional[float] = None) -> None:
+        """Power the target on via the given eFuse (default INTERNAL 5V)."""
+        self.target_power(efuse, on=True, delay=delay)
+
+    def power_off(self, efuse: Union[Efuse, int] = Efuse.INTERNAL,
+                  *, delay: Optional[float] = None) -> None:
+        """Power the target off."""
+        self.target_power(efuse, on=False, delay=delay)
+
+    # -- flash --------------------------------------------------------------
+
+    def flash(
+        self,
+        *,
+        swclk: Union[Pin, int],
+        swdio: Union[Pin, int],
+        nreset: Optional[Union[Pin, int]] = None,
+        target: str = "",
+        file: str = "",
+        load_address: str = "",
+        target_power: Optional[Union[Efuse, int]] = None,
+        verify: bool = True,
+        reset: bool = True,
+        connect_under_reset: Optional[bool] = None,
+        clear_reset_events: bool = True,
+        openocd_bin: Optional[str] = None,
+        extra_configs: Sequence[str] = (),
+        extra_args: Sequence[str] = (),
+        timeout: float = 300.0,
+        connect_attempts: int = 5,
+        check: bool = True,
+    ) -> FlashResult:
+        """Flash an SWD target and report the result.
+
+        ``swclk``/``swdio``/``nreset`` are LA pins (``benchpod.PIN1``..``PIN12``
+        or 1-12). ``target_power`` of ``benchpod.INTERNAL``/``EXTERNAL`` powers
+        the target first. By default (``check=True``) a failed flash raises
+        :class:`FlashError`/:class:`TargetUnreachableError`; pass ``check=False``
+        to get the :class:`FlashResult` and ``assert result.ok`` yourself.
+        """
+        swclk_i = coerce_pin(swclk, "swclk")
+        swdio_i = coerce_pin(swdio, "swdio")
+        if swclk_i == swdio_i:
+            raise BenchPodError("swclk and swdio must be different LA pins")
+        nreset_i = coerce_pin(nreset, "nreset") if nreset is not None else None
+        power = coerce_efuse(target_power) if target_power is not None else None
+
+        result = _flash.flash(
+            self._transport,
+            swclk=swclk_i, swdio=swdio_i, nreset=nreset_i,
+            target=target, file=file, load_address=load_address,
+            target_power=power, verify=verify, reset=reset,
+            connect_under_reset=connect_under_reset,
+            clear_reset_events=clear_reset_events,
+            openocd_bin=openocd_bin,
+            extra_configs=extra_configs, extra_args=extra_args,
+            timeout=timeout, connect_attempts=connect_attempts,
+        )
+        if check:
+            _flash.raise_for_result(result)
+        return result
+
+    # -- LA pin pull-ups (LA1-8) --------------------------------------------
+
+    def pullup(self, la: Union[Pin, int], on: Optional[bool] = None) -> dict:
+        """Switch (or query) an LA pin's pull-up resistor. LA1-8 only.
+
+        The pod has fixed pull-ups (LA1/2 = 4.7k, LA3/4 = 2.2k, LA5-8 = 10k) —
+        enable them on the I2C SDA/SCL lines so an open-drain bus idles high.
+        ``on=None`` queries without changing. Returns e.g.
+        ``{"la":1,"pullup":1,"ohms":"4.7k"}``.
+        """
+        la_i = coerce_pin(la, "la")
+        if not 1 <= la_i <= 8:
+            raise BenchPodError("pull-ups are only on LA1-8")
+        req: dict = {"cmd": "pullup", "la": la_i}
+        if on is not None:
+            req["state"] = "on" if on else "off"
+        return self.command(req)
+
+    def enable_pullup(self, *las: Union[Pin, int]) -> None:
+        """Enable the pull-up on one or more LA pins (LA1-8)."""
+        for la in las:
+            self.pullup(la, on=True)
+
+    def disable_pullup(self, *las: Union[Pin, int]) -> None:
+        """Disable the pull-up on one or more LA pins (LA1-8)."""
+        for la in las:
+            self.pullup(la, on=False)
+
+    def pullup_status(self) -> dict:
+        """Return ``{"la_pullup_mask": <bitmask>}`` (bit la-1 set = pull-up on)."""
+        return self.command({"cmd": "pullup_status"})
+
+    # -- emulated I2C sensor (TCP transport only) ---------------------------
+
+    def enable_i2c_sensor(
+        self,
+        sensor: Union[Sensor, str] = Sensor.BMP280,
+        *,
+        sda: Union[Pin, int],
+        scl: Union[Pin, int],
+        address: int = 0x76,
+        temperature_c: Optional[float] = None,
+        pressure_pa: Optional[float] = None,
+    ) -> dict:
+        """Make the pod emulate an I2C sensor (e.g. BMP280) on ``sda``/``scl``.
+
+        The pod becomes an I2C slave the DUT's master can read. Optionally seed
+        initial ``temperature_c``/``pressure_pa``. Returns the start response.
+        """
+        result = _sensor.sensor_start(
+            self._transport, sensor, sda=sda, scl=scl, address=address
+        )
+        if temperature_c is not None or pressure_pa is not None:
+            _sensor.sensor_set(self._transport, temperature_c=temperature_c,
+                               pressure_pa=pressure_pa)
+        return result
+
+    def set_i2c_sensor(self, *, temperature_c: Optional[float] = None,
+                       pressure_pa: Optional[float] = None) -> dict:
+        """Update the emulated sensor's reported values."""
+        return _sensor.sensor_set(self._transport, temperature_c=temperature_c,
+                                  pressure_pa=pressure_pa)
+
+    def disable_i2c_sensor(self) -> None:
+        """Disarm the emulated sensor (safe if none is active)."""
+        _sensor.sensor_stop(self._transport)
+
+    def i2c_sensor_status(self) -> dict:
+        """Return sensor + I2C-bus activity counters."""
+        return _sensor.sensor_status(self._transport)
+
+    def i2c_sensor_regs(self, start: int = 0, length: int = 256) -> List[int]:
+        """Read the emulated register image."""
+        return _sensor.sensor_regs(self._transport, start, length)
+
+    def i2c_sensor_la(self, samples: int = 256,
+                      sample_rate_mhz: Optional[float] = None) -> List[int]:
+        """Raw I2C-bus logic capture (packed bytes)."""
+        return _sensor.sensor_la(self._transport, samples, sample_rate_mhz)
+
+    def i2c_sensor_la_decoded(self, samples: int = 1024,
+                              sample_rate_mhz: Optional[float] = None
+                              ) -> "List[_i2c.I2CTransaction]":
+        """Capture the I2C bus and decode it into transactions.
+
+        Convenience over :meth:`i2c_sensor_la` + :func:`benchpod.i2c.decode`.
+        Sample fast enough to resolve the bus: ~1 MS/s (the default) gives ~10
+        samples per bit at 100 kHz I2C over a ~4 ms window per 1024 bytes.
+        """
+        raw = self.i2c_sensor_la(samples, sample_rate_mhz)
+        return _i2c.decode(raw)
+
+    # -- UART capture -------------------------------------------------------
+
+    def capture_uart(
+        self,
+        *,
+        rx: Union[Pin, int],
+        tx: Union[Pin, int],
+        baud: int = 115200,
+        duration: float,
+        until: Optional[_uart.Until] = None,
+    ) -> "_uart.UartCapture":
+        """Capture the DUT's UART output for ``duration`` seconds.
+
+        ``rx`` is the LA channel the pod samples (wire the DUT's TX here); ``tx``
+        is driven (DUT's RX). ``until`` (substring/regex/predicate) stops early.
+        """
+        link = self._transport.uart_proxy_start(
+            coerce_pin(rx, "rx"), coerce_pin(tx, "tx"), int(baud)
+        )
+        return _uart.capture(link, duration=duration, until=until)
+
+    def power_cycle_and_capture(
+        self,
+        *,
+        rx: Union[Pin, int],
+        tx: Union[Pin, int],
+        efuse: Union[Efuse, int] = Efuse.INTERNAL,
+        delay: float = 1.0,
+        duration: float = 4.0,
+        baud: int = 115200,
+        until: Optional[_uart.Until] = None,
+        off_settle: float = 0.3,
+    ) -> "_uart.UartCapture":
+        """Power-cycle the target while capturing its boot output.
+
+        Powers the eFuse off, schedules a power-on ``delay`` seconds out (pod-
+        side timer), then enters UART capture so the scheduled power-on — and the
+        DUT's boot banner — land *inside* the capture window. ``duration`` should
+        comfortably exceed ``delay``.
+        """
+        self.power_off(efuse)
+        if off_settle:
+            time.sleep(off_settle)
+        self.power_on(efuse, delay=delay)
+        return self.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration,
+                                 until=until)
+
+    # -- low-level pass-throughs (TCP transport only) -----------------------
+
+    def command(self, req: dict) -> Any:
+        """Send a raw JSON command (TCP transport only)."""
+        cmd = getattr(self._transport, "command", None)
+        if cmd is None:
+            raise BenchPodError("raw JSON commands are only available on the TCP transport")
+        return cmd(req)
+
+    def capture(self, samples: int = 256, *, sample_rate_mhz: Optional[float] = None) -> List[int]:
+        """Capture ADC samples (TCP transport only)."""
+        fn = getattr(self._transport, "samples", None)
+        if fn is None:
+            raise BenchPodError("capture is only available on the TCP transport")
+        req: dict = {"cmd": "capture", "samples": samples}
+        if sample_rate_mhz is not None:
+            req["sample_rate_mhz"] = sample_rate_mhz
+        return fn(req)
+
+    def gpio_set(self, la: Union[Pin, int], state: Union[int, str]) -> Any:
+        """Drive an LA channel high/low/high-Z (TCP transport only)."""
+        return self.command({"cmd": "gpio_set", "la": coerce_pin(la, "la"), "state": state})

embeddedci/benchpod/connection.py

@@ -0,0 +1,84 @@
+"""Resolve a connection string into a concrete transport spec.
+
+Mirrors the Go CLI's ``connection.go``:
+
+* ``host`` or ``host:port``        -> TCP/wifi (default port 8080)
+* ``/dev/tty*`` / ``COM3`` / ``\\\\.\\COM3`` -> serial device path
+* ``serial`` / ``usb``             -> serial, auto-detect by USB VID 0x2E8A
+
+Precedence is handled by the caller: an explicit argument wins over the
+``BENCHPOD_CONNECTION`` environment variable.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+
+from .errors import ConnectionConfigError
+
+DEFAULT_PORT = 8080
+ENV_VAR = "BENCHPOD_CONNECTION"
+
+_COM_RE = re.compile(r"^COM[0-9]+$", re.IGNORECASE)
+
+
+@dataclass
+class ConnSpec:
+    """A resolved connection target."""
+
+    kind: str  # "tcp" or "serial"
+    addr: str = ""  # "host:port" when kind == "tcp"
+    device: str = ""  # device path when kind == "serial"; "" means auto-detect
+
+    def is_wifi(self) -> bool:
+        return self.kind == "tcp"
+
+    def is_serial(self) -> bool:
+        return self.kind == "serial"
+
+
+def _is_device_path(s: str) -> bool:
+    if s.startswith("/dev/"):
+        return True
+    if s.startswith("\\\\.\\"):  # Windows \\.\COM10 form
+        return True
+    if _COM_RE.match(s):
+        return True
+    return False
+
+
+def _normalize_addr(s: str) -> str:
+    # Bracketed IPv6 literal, optionally with a port.
+    if s.startswith("["):
+        return s if "]:" in s else f"{s}:{DEFAULT_PORT}"
+    # A single colon means host:port; more than one and no brackets means a bare
+    # IPv6 address, which needs the default port appended as-is.
+    if s.count(":") == 1:
+        return s
+    return f"{s}:{DEFAULT_PORT}"
+
+
+def parse_connection(raw: str) -> ConnSpec:
+    """Parse a connection string into a :class:`ConnSpec`."""
+    s = raw.strip()
+    if not s:
+        raise ConnectionConfigError("connection string is empty")
+    if s.lower() in ("serial", "usb"):
+        return ConnSpec(kind="serial", device="")
+    if _is_device_path(s):
+        return ConnSpec(kind="serial", device=s)
+    return ConnSpec(kind="tcp", addr=_normalize_addr(s))
+
+
+def resolve_connection(connection: "str | None" = None) -> ConnSpec:
+    """Resolve a connection from an explicit value or the environment."""
+    raw = connection if connection is not None else os.environ.get(ENV_VAR)
+    if not raw or not str(raw).strip():
+        raise ConnectionConfigError(
+            "no BenchPod connection configured; pass connection=... or set "
+            f"the {ENV_VAR} environment variable "
+            "(e.g. '192.168.1.213', '/dev/ttyACM0', or 'serial')"
+        )
+    return parse_connection(str(raw))

embeddedci/benchpod/constants.py

@@ -0,0 +1,95 @@
+"""Static, named constants for the BenchPod API.
+
+The firmware speaks raw integers — eFuse ``1``/``2`` and LA channels ``1``-``12``.
+These :class:`~enum.IntEnum` types give those wire values intuitive names so test
+code reads ``benchpod.INTERNAL`` / ``benchpod.PIN1`` instead of bare numbers.
+Because they are ``IntEnum``s they serialize as their integer on the wire, and
+the coercion helpers below accept either an enum member or a plain int.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, IntEnum
+from typing import Union
+
+from .errors import BenchPodError
+
+
+class Efuse(IntEnum):
+    """Target-power eFuse rail."""
+
+    INTERNAL = 1  # internal 5V supply
+    EXTERNAL = 2  # external supply
+
+
+class Sensor(str, Enum):
+    """Emulated I2C sensor model (firmware ships BMP280 today)."""
+
+    BMP280 = "bmp280"
+
+
+# Common BMP280 7-bit I2C addresses (datasheet: SDO low / high).
+BMP280_ADDR_PRIMARY = 0x76
+BMP280_ADDR_SECONDARY = 0x77
+
+
+class Pin(IntEnum):
+    """Logic-analyzer channel (LA1..LA12) on the iCE40 FPGA bank."""
+
+    PIN1 = 1
+    PIN2 = 2
+    PIN3 = 3
+    PIN4 = 4
+    PIN5 = 5
+    PIN6 = 6
+    PIN7 = 7
+    PIN8 = 8
+    PIN9 = 9
+    PIN10 = 10
+    PIN11 = 11
+    PIN12 = 12
+
+
+# Module-level aliases, re-exported from ``benchpod`` so callers can write
+# ``benchpod.INTERNAL`` and ``benchpod.PIN1``.
+INTERNAL = Efuse.INTERNAL
+EXTERNAL = Efuse.EXTERNAL
+
+PIN1 = Pin.PIN1
+PIN2 = Pin.PIN2
+PIN3 = Pin.PIN3
+PIN4 = Pin.PIN4
+PIN5 = Pin.PIN5
+PIN6 = Pin.PIN6
+PIN7 = Pin.PIN7
+PIN8 = Pin.PIN8
+PIN9 = Pin.PIN9
+PIN10 = Pin.PIN10
+PIN11 = Pin.PIN11
+PIN12 = Pin.PIN12
+
+
+def coerce_efuse(value: Union[Efuse, int]) -> int:
+    """Validate and normalize an eFuse selector to ``1`` or ``2``."""
+    try:
+        ivalue = int(value)
+    except (TypeError, ValueError):
+        raise BenchPodError(f"efuse must be 1 (INTERNAL) or 2 (EXTERNAL), got {value!r}") from None
+    if ivalue not in (Efuse.INTERNAL, Efuse.EXTERNAL):
+        raise BenchPodError(
+            f"efuse must be 1 (INTERNAL) or 2 (EXTERNAL), got {value!r}"
+        )
+    return ivalue
+
+
+def coerce_pin(value: Union[Pin, int], name: str = "pin") -> int:
+    """Validate and normalize an LA pin selector to an int in ``1``..``12``."""
+    try:
+        ivalue = int(value)
+    except (TypeError, ValueError):
+        raise BenchPodError(f"{name} must be an LA pin 1-12 (e.g. benchpod.PIN1), got {value!r}") from None
+    if not 1 <= ivalue <= 12:
+        raise BenchPodError(
+            f"{name} must be an LA pin 1-12 (e.g. benchpod.PIN1), got {value!r}"
+        )
+    return ivalue

embeddedci/benchpod/errors.py

@@ -0,0 +1,40 @@
+"""Exception hierarchy for the BenchPod client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class BenchPodError(Exception):
+    """Base class for every error this package raises."""
+
+
+class ConnectionConfigError(BenchPodError):
+    """No usable connection was configured, or the spec could not be parsed."""
+
+
+class TransportError(BenchPodError):
+    """A transport-level failure: could not reach or talk to the pod."""
+
+
+class FirmwareError(BenchPodError):
+    """The pod accepted the request but replied ``{"status":"error"}``."""
+
+    def __init__(self, message: str, *, cmd: Optional[str] = None) -> None:
+        self.firmware_message = message
+        self.cmd = cmd
+        if cmd:
+            super().__init__(f"{cmd}: {message}")
+        else:
+            super().__init__(message)
+
+
+class FlashError(BenchPodError):
+    """Flashing failed — OpenOCD exited non-zero (see ``stderr``)."""
+
+
+class TargetUnreachableError(FlashError):
+    """OpenOCD's probe worked but the target never answered on SWD.
+
+    Almost always means the target is unpowered, mis-wired, or held in reset.
+    """