embeddedci-openhtf 0.1.0__py3-none-any.whl

embeddedci_openhtf/__init__.py

@@ -0,0 +1,70 @@
+"""embeddedci-openhtf — drive an EmbeddedCI BenchPod from OpenHTF.
+
+An `OpenHTF <https://www.openhtf.com/>`_ plug (and a few phase helpers) that wrap
+the :mod:`embeddedci` BenchPod SDK, for teams that want OpenHTF's test-sequencing
+and record/GUI stack while connecting **directly** to a pod over TCP or serial —
+no EmbeddedCI cloud account or web UI required.
+
+    import openhtf as htf
+    from embeddedci_openhtf import benchpod_plug, flash_phase, boot_banner_phase
+
+    bench = benchpod_plug("192.168.1.50:8080")   # or "/dev/ttyACM0"
+
+    test = htf.Test(
+        flash_phase(bench, file="fw.elf", target="target/stm32f4x.cfg",
+                    swclk=11, swdio=12, nreset=3),
+        boot_banner_phase(bench, rx=1, tx=2, expect="APP_OK"),
+    )
+    test.execute(test_start=lambda: "SN-0001")
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .analog import (
+    adc_capture_phase,
+    loopback_measure_phase,
+    measure,
+    signal_generate,
+    signal_generate_phase,
+    signal_stop,
+)
+from .measurements import (
+    flash_ok_measurement,
+    record_flash,
+    record_samples,
+    record_uart,
+    uart_matched_measurement,
+)
+from .phases import boot_banner_phase, flash_phase, power_phase
+from .plug import BenchPodPlug, benchpod_plug, close_persistent_benchpods
+
+try:
+    __version__ = version("embeddedci-openhtf")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "BenchPodPlug",
+    "benchpod_plug",
+    "close_persistent_benchpods",
+    # phase factories
+    "power_phase",
+    "flash_phase",
+    "boot_banner_phase",
+    "signal_generate_phase",
+    "adc_capture_phase",
+    "loopback_measure_phase",
+    # analog low-level helpers
+    "signal_generate",
+    "signal_stop",
+    "measure",
+    # measurement helpers
+    "flash_ok_measurement",
+    "uart_matched_measurement",
+    "record_flash",
+    "record_uart",
+    "record_samples",
+    "__version__",
+]

embeddedci_openhtf/analog.py

@@ -0,0 +1,184 @@
+"""Analog stimulus/acquisition helpers for OpenHTF phases.
+
+The BenchPod's analog path is a DAC output and an ADC input on the iCE40 FPGA.
+The SDK exposes the acquisition side as ``BenchPod.capture(...)`` and everything
+else through raw JSON commands; these helpers wrap the firmware's ``generate``
+(DAC waveform), ``measure`` (synchronized DAC+ADC loopback), and ``capture``
+(ADC snapshot) commands, and the phase factories turn the captured samples into
+OpenHTF measurements via :func:`embeddedci_openhtf.record_samples`.
+
+**TCP only.** These commands need the JSON/sample channel, which the serial
+console does not provide — they raise ``BenchPodError`` on a serial connection.
+
+The ``bench`` argument to every helper is a connected :class:`BenchPod` *or* a
+:class:`~embeddedci_openhtf.BenchPodPlug` (the plug proxies the SDK methods), so
+inside a phase you can pass the injected ``bench`` straight through::
+
+    @htf.plug(bench=benchpod_plug("192.168.1.50:8080"))
+    def stim(test, bench):
+        signal_generate(bench, waveform="sine", freq=1000, amplitude=100, offset=128)
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Union
+
+import openhtf as htf
+
+from embeddedci.benchpod.errors import BenchPodError
+
+from .measurements import record_samples
+
+__all__ = [
+    "signal_generate",
+    "signal_stop",
+    "measure",
+    "signal_generate_phase",
+    "adc_capture_phase",
+    "loopback_measure_phase",
+]
+
+_Range = Optional[tuple]  # (min, max) inclusive, or None for no limit
+
+
+# -- low-level helpers (operate on a BenchPod or BenchPodPlug) ---------------
+
+def signal_generate(bench: Any, *, waveform: str, freq: float, amplitude: float,
+                    offset: float = 128.0, duration_ms: Optional[int] = None,
+                    sample_rate_mhz: Optional[float] = None) -> Any:
+    """Start a DAC waveform (``sine``/``square``/``sawtooth``/...).
+
+    ``amplitude`` is 0-127 and ``offset`` 0-255 (firmware DAC units). With
+    ``duration_ms`` unset/0 the waveform runs until the next command (e.g.
+    :func:`signal_stop` or a ``capture``).
+    """
+    req: dict = {"cmd": "generate", "waveform": waveform, "freq": freq,
+                 "amplitude": amplitude, "offset": offset}
+    if duration_ms is not None:
+        req["duration_ms"] = duration_ms
+    if sample_rate_mhz is not None:
+        req["sample_rate_mhz"] = sample_rate_mhz
+    return bench.command(req)
+
+
+def signal_stop(bench: Any) -> Any:
+    """Stop a free-running DAC waveform."""
+    return bench.command({"cmd": "dac_stop"})
+
+
+def measure(bench: Any, *, waveform: str, freq: float, amplitude: float,
+            offset: float = 128.0, samples: int = 256,
+            sample_rate_mhz: Optional[float] = None) -> List[int]:
+    """Drive the DAC and capture the ADC in one synchronized command (loopback).
+
+    Returns the reassembled ADC sample array. Use for round-trip checks where the
+    DAC output is wired (directly or through a DUT) back to the ADC input.
+    """
+    # measure returns a (possibly chunked) sample array, so it needs the
+    # transport's chunk-reassembling `samples` path, not plain `command`.
+    transport = getattr(bench, "transport", None)
+    fn = getattr(transport, "samples", None)
+    if fn is None:
+        raise BenchPodError("measure is only available on the TCP transport")
+    req: dict = {"cmd": "measure", "waveform": waveform, "freq": freq,
+                 "amplitude": amplitude, "offset": offset, "samples": samples}
+    if sample_rate_mhz is not None:
+        req["sample_rate_mhz"] = sample_rate_mhz
+    return fn(req)
+
+
+# -- phase factories ---------------------------------------------------------
+
+def _stat_measures(prefix: str, *, mean_range: _Range, pp_range: _Range,
+                   min_range: _Range, max_range: _Range) -> list:
+    """Declare min/max/mean/pp measurements, applying any ranges as limits."""
+    spec = {"min": min_range, "max": max_range, "mean": mean_range, "pp": pp_range}
+    out = []
+    for suffix, rng in spec.items():
+        meas = htf.Measurement(f"{prefix}_{suffix}")
+        if rng is not None:
+            meas = meas.in_range(rng[0], rng[1])
+        out.append(meas)
+    return out
+
+
+def signal_generate_phase(plug: type, *, waveform: str, freq: float,
+                          amplitude: float, offset: float = 128.0,
+                          duration_ms: Optional[int] = None,
+                          sample_rate_mhz: Optional[float] = None,
+                          name: str = "signal_generate") -> object:
+    """A setup phase that starts a DAC waveform and continues.
+
+    With ``duration_ms`` unset the waveform free-runs; pair it with a later
+    :func:`adc_capture_phase` (sampling a different channel) and stop it with
+    ``signal_stop`` in a teardown phase if needed.
+    """
+
+    @htf.PhaseOptions(name=name)
+    @htf.plug(bench=plug)
+    def _gen(test, bench):
+        signal_generate(bench, waveform=waveform, freq=freq, amplitude=amplitude,
+                        offset=offset, duration_ms=duration_ms,
+                        sample_rate_mhz=sample_rate_mhz)
+        test.logger.info("DAC %s @ %g Hz, amp %g, offset %g", waveform, freq,
+                         amplitude, offset)
+
+    return _gen
+
+
+def adc_capture_phase(plug: type, *, samples: int = 4096,
+                      sample_rate_mhz: Optional[float] = None,
+                      prefix: str = "adc", mean_range: _Range = None,
+                      pp_range: _Range = None, min_range: _Range = None,
+                      max_range: _Range = None, name: str = "adc_capture") -> object:
+    """A phase that snapshots the ADC and records min/max/mean/pp.
+
+    Pass any of ``mean_range`` / ``pp_range`` / ``min_range`` / ``max_range`` as
+    ``(low, high)`` to turn that stat into a pass/fail limit; the raw samples are
+    always attached as ``adc.json``.
+    """
+
+    @htf.PhaseOptions(name=name)
+    @htf.measures(*_stat_measures(prefix, mean_range=mean_range, pp_range=pp_range,
+                                  min_range=min_range, max_range=max_range))
+    @htf.plug(bench=plug)
+    def _cap(test, bench):
+        data = bench.capture(samples, sample_rate_mhz=sample_rate_mhz)
+        stats = record_samples(test, data, prefix=prefix)
+        test.logger.info("ADC %d samples: min=%s max=%s mean=%.1f pp=%s",
+                         len(data), stats[f"{prefix}_min"], stats[f"{prefix}_max"],
+                         stats[f"{prefix}_mean"], stats[f"{prefix}_pp"])
+
+    return _cap
+
+
+def loopback_measure_phase(plug: type, *, waveform: str, freq: float,
+                           amplitude: float, offset: float = 128.0,
+                           samples: int = 4096,
+                           sample_rate_mhz: Optional[float] = None,
+                           prefix: str = "adc", mean_range: _Range = None,
+                           pp_range: _Range = None, min_range: _Range = None,
+                           max_range: _Range = None,
+                           name: str = "loopback_measure") -> object:
+    """A phase that drives the DAC and captures the ADC together (loopback), then
+    records min/max/mean/pp.
+
+    The canonical analog self-test: stimulate with a known waveform and assert
+    the round-trip amplitude/offset, e.g. ``pp_range=(180, 255)`` for a healthy
+    signal path. Raw samples are attached as ``adc.json``.
+    """
+
+    @htf.PhaseOptions(name=name)
+    @htf.measures(*_stat_measures(prefix, mean_range=mean_range, pp_range=pp_range,
+                                  min_range=min_range, max_range=max_range))
+    @htf.plug(bench=plug)
+    def _meas(test, bench):
+        data = measure(bench, waveform=waveform, freq=freq, amplitude=amplitude,
+                       offset=offset, samples=samples,
+                       sample_rate_mhz=sample_rate_mhz)
+        stats = record_samples(test, data, prefix=prefix)
+        test.logger.info("loopback %s @ %g Hz -> %d samples: mean=%.1f pp=%s",
+                         waveform, freq, len(data), stats[f"{prefix}_mean"],
+                         stats[f"{prefix}_pp"])
+
+    return _meas

embeddedci_openhtf/measurements.py

@@ -0,0 +1,109 @@
+"""Helpers that map BenchPod SDK result objects onto OpenHTF measurements and
+attachments.
+
+OpenHTF wants measurements *declared* on a phase (``@htf.measures(...)``) and
+*set* inside it (``test.measurements.x = ...``). These helpers give you the
+matching declaration/record pair for the common BenchPod results so you don't
+hand-roll the boilerplate:
+
+    @htf.measures(flash_ok_measurement())
+    @htf.plug(bench=benchpod_plug("192.168.1.50:8080"))
+    def flash(test, bench):
+        result = bench.flash(file="fw.elf", target="target/stm32f4x.cfg",
+                             swclk=11, swdio=12, nreset=3, check=False)
+        record_flash(test, result)            # sets flash_ok + attaches the log
+
+The recorders never raise on a bad result — they record the failing value so the
+measurement validator (not an exception) decides the phase outcome, and the
+OpenOCD / UART output is always attached for triage.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+import openhtf as htf
+
+from embeddedci.benchpod.flash import FlashResult
+from embeddedci.benchpod.uart import UartCapture
+
+__all__ = [
+    "flash_ok_measurement",
+    "uart_matched_measurement",
+    "record_flash",
+    "record_uart",
+    "record_samples",
+]
+
+
+# -- measurement declarations ------------------------------------------------
+
+def flash_ok_measurement(name: str = "flash_ok") -> htf.Measurement:
+    """A boolean measurement that passes only when the flash succeeded."""
+    return htf.Measurement(name).equals(True).doc(
+        "OpenOCD programmed and verified the target over the pod's SWD probe"
+    )
+
+
+def uart_matched_measurement(name: str = "boot_ok") -> htf.Measurement:
+    """A boolean measurement that passes when the UART ``until`` pattern hit."""
+    return htf.Measurement(name).equals(True).doc(
+        "Expected pattern was seen on the DUT's UART within the capture window"
+    )
+
+
+# -- recorders ---------------------------------------------------------------
+
+def record_flash(test: htf.TestApi, result: FlashResult, *,
+                 name: str = "flash_ok", attachment: str = "openocd.log") -> bool:
+    """Record a :class:`FlashResult`: set the ``name`` measurement to ``result.ok``
+    and attach the OpenOCD output. Returns ``result.ok``."""
+    log = (result.stdout or "")
+    if getattr(result, "stderr", ""):
+        log = f"{log}\n----- stderr -----\n{result.stderr}"
+    test.attach(attachment, log.encode("utf-8", "replace"), mimetype="text/plain")
+    test.measurements[name] = bool(result.ok)
+    return bool(result.ok)
+
+
+def record_uart(test: htf.TestApi, capture: UartCapture, *,
+                name: Optional[str] = "boot_ok",
+                attachment: str = "uart.txt") -> bool:
+    """Record a :class:`UartCapture`: attach the captured text and, when ``name``
+    is given, set that measurement to ``capture.matched``. Returns ``matched``."""
+    test.attach(attachment, capture.text.encode("utf-8", "replace"),
+                mimetype="text/plain")
+    if name is not None:
+        test.measurements[name] = bool(capture.matched)
+    return bool(capture.matched)
+
+
+def record_samples(test: htf.TestApi, samples: List[int], *,
+                   prefix: str = "adc", attachment: str = "adc.json") -> dict:
+    """Attach raw ADC/LA ``samples`` (from ``bench.capture(...)`` / ``measure``)
+    as JSON and set ``<prefix>_min`` / ``_max`` / ``_mean`` / ``_pp``
+    (peak-to-peak) measurements.
+
+    Declare the matching measurements on the phase (e.g.
+    ``htf.Measurement('adc_pp').in_range(...)``) to turn them into limits; only
+    declared ones are set. Returns the computed stats dict.
+    """
+    test.attach(attachment, json.dumps(samples).encode("utf-8"),
+                mimetype="application/json")
+    lo = min(samples) if samples else 0
+    hi = max(samples) if samples else 0
+    stats = {
+        f"{prefix}_min": lo,
+        f"{prefix}_max": hi,
+        f"{prefix}_mean": (sum(samples) / len(samples)) if samples else 0.0,
+        f"{prefix}_pp": hi - lo,
+    }
+    for key, value in stats.items():
+        # Only set measurements the phase actually declared; ignore the rest so
+        # callers can opt into just the stats they care about.
+        try:
+            test.measurements[key] = value
+        except Exception:
+            pass
+    return stats

embeddedci_openhtf/phases.py

@@ -0,0 +1,121 @@
+"""Ready-made OpenHTF phase factories for common BenchPod steps.
+
+Each factory returns a fully-decorated phase (plug + measurements wired up) so a
+test is just a list of them::
+
+    import openhtf as htf
+    from embeddedci_openhtf import benchpod_plug, flash_phase, boot_banner_phase
+
+    bench = benchpod_plug("192.168.1.50:8080")   # direct TCP, no cloud
+
+    test = htf.Test(
+        flash_phase(bench, file="fw.elf", target="target/stm32f4x.cfg",
+                    swclk=11, swdio=12, nreset=3),
+        boot_banner_phase(bench, rx=1, tx=2, expect="APP_OK"),
+    )
+    test.execute(test_start=lambda: "SN-0001")
+
+These are conveniences; for anything custom, write a normal phase with
+``@htf.plug(bench=benchpod_plug(...))`` and the recorders in
+:mod:`embeddedci_openhtf.measurements`.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import openhtf as htf
+
+from embeddedci.benchpod.constants import Efuse, Pin
+
+from .measurements import (
+    flash_ok_measurement,
+    record_flash,
+    record_uart,
+    uart_matched_measurement,
+)
+
+__all__ = ["power_phase", "flash_phase", "boot_banner_phase"]
+
+_PinT = Union[Pin, int]
+
+
+def power_phase(plug: type, *, efuse: Union[Efuse, int] = Efuse.INTERNAL,
+                on: bool = True, name: Optional[str] = None) -> object:
+    """A phase that powers the target eFuse on (or off)."""
+
+    @htf.PhaseOptions(name=name or ("power_on" if on else "power_off"))
+    @htf.plug(bench=plug)
+    def _power(test, bench):
+        (bench.power_on if on else bench.power_off)(efuse)
+        test.logger.info("target power %s (efuse %s)", "on" if on else "off",
+                         int(efuse))
+
+    return _power
+
+
+def flash_phase(plug: type, *, file: str, target: str,
+                swclk: _PinT, swdio: _PinT, nreset: Optional[_PinT] = None,
+                target_power: Optional[Union[Efuse, int]] = Efuse.INTERNAL,
+                name: str = "flash", stop_on_fail: bool = True,
+                **flash_kwargs) -> object:
+    """A phase that flashes the DUT over SWD and records the result.
+
+    ``swclk``/``swdio``/``nreset`` are LA channels (1-12). Records a ``flash_ok``
+    measurement and attaches the OpenOCD log. By default a failed flash stops the
+    test (``stop_on_fail``) so later phases don't run against an unprogrammed DUT.
+    Extra keyword args pass through to ``BenchPod.flash`` (``verify``,
+    ``connect_under_reset``, ``extra_configs``, ...).
+    """
+
+    @htf.PhaseOptions(name=name)
+    @htf.measures(flash_ok_measurement())
+    @htf.plug(bench=plug)
+    def _flash(test, bench):
+        result = bench.flash(
+            file=file, target=target, swclk=swclk, swdio=swdio, nreset=nreset,
+            target_power=target_power, check=False, **flash_kwargs,
+        )
+        ok = record_flash(test, result)
+        if not ok:
+            test.logger.error("flash failed (openocd rc=%s)", result.returncode)
+            if stop_on_fail:
+                return htf.PhaseResult.STOP
+        return htf.PhaseResult.CONTINUE
+
+    return _flash
+
+
+def boot_banner_phase(plug: type, *, rx: _PinT, tx: _PinT, expect,
+                      baud: int = 115200, duration: float = 5.0,
+                      power_cycle: bool = True,
+                      efuse: Union[Efuse, int] = Efuse.INTERNAL,
+                      delay: float = 1.0, name: str = "boot",
+                      measurement: str = "boot_ok") -> object:
+    """A phase that captures the DUT's UART and checks for ``expect``.
+
+    ``rx`` is the LA channel wired to the DUT's TX; ``tx`` drives the DUT's RX.
+    ``expect`` is a substring / compiled regex / ``text->bool`` predicate. When
+    ``power_cycle`` is true the target is power-cycled so the boot banner lands
+    inside the capture window; otherwise it captures the already-powered DUT.
+    Records ``measurement`` (True if ``expect`` was seen) and attaches the text.
+    """
+
+    @htf.PhaseOptions(name=name)
+    @htf.measures(uart_matched_measurement(measurement))
+    @htf.plug(bench=plug)
+    def _boot(test, bench):
+        if power_cycle:
+            cap = bench.power_cycle_and_capture(
+                rx=rx, tx=tx, efuse=efuse, delay=delay, duration=duration,
+                baud=baud, until=expect,
+            )
+        else:
+            cap = bench.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration,
+                                     until=expect)
+        matched = record_uart(test, cap, name=measurement)
+        if not matched:
+            test.logger.error("did not see %r on UART within %.1fs", expect, duration)
+        return htf.PhaseResult.CONTINUE
+
+    return _boot

embeddedci_openhtf/plug.py

@@ -0,0 +1,218 @@
+"""An OpenHTF plug that wraps the EmbeddedCI BenchPod SDK.
+
+This plug is built for driving a BenchPod **directly** — over a TCP socket
+(``host[:port]``) or a serial device path — with no EmbeddedCI cloud account or
+web UI involved. (A direct TCP/serial connection never takes a cloud lease, so
+nothing here talks to embeddedci.com.)
+
+Two ways to point it at a pod:
+
+* **Inline (most direct).** Bind the connection in the test file with
+  :func:`benchpod_plug`::
+
+      import openhtf as htf
+      from embeddedci_openhtf import benchpod_plug
+
+      @htf.plug(bench=benchpod_plug("192.168.1.50:8080"))
+      def power_up(test, bench):
+          bench.power_on()                  # methods proxy to the BenchPod SDK
+          bench.pod.flash(...)              # or reach the full client via .pod
+
+* **Via OpenHTF config.** Use :class:`BenchPodPlug` unbound and supply the
+  connection through OpenHTF's ``conf`` (a YAML file, ``--config-value``, or
+  :func:`openhtf.conf.load`), falling back to the ``BENCHPOD_CONNECTION`` env
+  var::
+
+      htf.conf.load(benchpod_connection="/dev/ttyACM0")
+
+      @htf.plug(bench=BenchPodPlug)
+      def power_up(test, bench):
+          bench.power_on()
+
+**Connection lifecycle.** By default a fresh connection is opened on each test
+execution and closed in :meth:`tearDown`, so OpenHTF owns the lifecycle. On a
+station that cycles many DUTs back-to-back, pass ``persistent=True`` to
+:func:`benchpod_plug` to keep one connection open across executions (re-checked
+with a ping each run and reconnected if it dropped); close it explicitly with
+:func:`close_persistent_benchpods` (also run automatically at process exit).
+
+Unknown attribute access proxies to the underlying
+:class:`~embeddedci.benchpod.BenchPod`, so ``bench.flash(...)`` /
+``bench.power_on()`` / ``bench.capture_uart(...)`` work directly; ``bench.pod``
+is the full client when you need it.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import threading
+from typing import Any, Dict, Optional
+
+import openhtf as htf
+from openhtf.plugs import BasePlug
+
+from embeddedci.benchpod import BenchPod
+from embeddedci.benchpod.connection import ENV_VAR
+from embeddedci.benchpod.errors import ConnectionConfigError
+
+# Mirror the SDK's connection sources as OpenHTF config keys, so a station can be
+# configured from a YAML file / --config-value instead of code.
+htf.conf.declare(
+    "benchpod_connection",
+    description=(
+        "BenchPod connection for direct (non-cloud) access: host[:port], a "
+        f"serial device path, or 'serial'. Falls back to the {ENV_VAR} env var."
+    ),
+    default_value=None,
+)
+htf.conf.declare(
+    "benchpod_timeout",
+    description="BenchPod transport timeout in seconds (default 30).",
+    default_value=30.0,
+)
+
+# Process-wide pool of persistent connections, keyed by the bound plug class (one
+# per benchpod_plug(persistent=True) call). Survives across test executions.
+_PERSISTENT_POOL: Dict[type, BenchPod] = {}
+_PERSISTENT_LOCK = threading.Lock()
+
+
+def close_persistent_benchpods() -> None:
+    """Close every persistent BenchPod connection and empty the pool.
+
+    Call at the end of a station run (or rely on the automatic ``atexit`` hook).
+    Idempotent — a plug with ``persistent=True`` reopens on its next execution.
+    """
+    with _PERSISTENT_LOCK:
+        pods = list(_PERSISTENT_POOL.values())
+        _PERSISTENT_POOL.clear()
+    for pod in pods:
+        try:
+            pod.close()
+        except Exception:
+            pass
+
+
+atexit.register(close_persistent_benchpods)
+
+
+def _acquire_persistent(cls: type, conn: Optional[str],
+                        pod_kwargs: Dict[str, Any], health_check: bool) -> BenchPod:
+    """Return the pooled connection for ``cls``, opening (or reopening, if a
+    health-check ping fails) it as needed."""
+    with _PERSISTENT_LOCK:
+        pod = _PERSISTENT_POOL.get(cls)
+        if pod is not None and health_check:
+            try:
+                pod.ping()  # cheap liveness check; reconnect if the link died
+            except Exception:
+                try:
+                    pod.close()
+                except Exception:
+                    pass
+                pod = None
+                _PERSISTENT_POOL.pop(cls, None)
+        if pod is None:
+            pod = BenchPod(conn, **pod_kwargs)
+            _PERSISTENT_POOL[cls] = pod
+        return pod
+
+
+class BenchPodPlug(BasePlug):
+    """OpenHTF plug wrapping a directly-connected :class:`BenchPod`.
+
+    Use unbound with OpenHTF config / ``BENCHPOD_CONNECTION``, or bind a
+    connection with :func:`benchpod_plug`. Subclasses may override the class
+    attributes below (that is what :func:`benchpod_plug` produces); leave
+    :data:`connection` / :data:`pod_kwargs` at their defaults to resolve from
+    config then env.
+    """
+
+    #: Connection override set by :func:`benchpod_plug`. ``None`` => use config/env.
+    connection: Optional[str] = None
+    #: Extra keyword args forwarded to ``BenchPod(...)`` (e.g. ``transport=`` for
+    #: tests). Set by :func:`benchpod_plug`.
+    pod_kwargs: Dict[str, Any] = {}
+    #: Keep one connection open across test executions (station mode).
+    persistent: bool = False
+    #: In persistent mode, ping a pooled connection before reuse and reconnect
+    #: if it has dropped.
+    health_check: bool = True
+
+    @htf.conf.inject_positional_args
+    def __init__(self, benchpod_connection: Optional[str] = None,
+                 benchpod_timeout: float = 30.0) -> None:
+        super().__init__()
+        cls = type(self)
+        pod_kwargs = dict(cls.pod_kwargs)
+        conn = self.connection or benchpod_connection or os.environ.get(ENV_VAR)
+        if not conn and "transport" not in pod_kwargs:
+            raise ConnectionConfigError(
+                "no BenchPod connection: bind one with benchpod_plug('host:port'), "
+                "set the OpenHTF 'benchpod_connection' config, or export "
+                f"{ENV_VAR}=<host:port|/dev/tty...>"
+            )
+        pod_kwargs.setdefault("timeout", benchpod_timeout)
+        if cls.persistent:
+            #: The connected SDK client (shared, kept open across executions).
+            self.pod: BenchPod = _acquire_persistent(
+                cls, conn, pod_kwargs, cls.health_check)
+        else:
+            # Direct TCP/serial connections never lease.
+            self.pod = BenchPod(conn, **pod_kwargs)
+        self.logger.info("BenchPod %s (%s)",
+                         "reusing connection" if cls.persistent else "connected",
+                         conn or "injected transport")
+
+    def tearDown(self) -> None:
+        """Close the connection — unless it is persistent, in which case it is
+        left open for the next test execution."""
+        if type(self).persistent:
+            return
+        try:
+            self.pod.close()
+        except Exception:  # teardown must not mask a phase failure
+            self.logger.exception("error closing BenchPod")
+
+    def __getattr__(self, name: str) -> Any:
+        # Proxy unknown attributes (flash/power_on/capture_uart/...) to the SDK
+        # client. Only consulted when normal lookup fails, so it never shadows
+        # plug internals (logger, tearDown, pod). Guarded so attribute probes
+        # before pod is set, and dunder lookups, don't recurse or leak.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        pod = self.__dict__.get("pod")
+        if pod is None:
+            raise AttributeError(name)
+        return getattr(pod, name)
+
+
+def benchpod_plug(connection: Optional[str] = None, *, persistent: bool = False,
+                  health_check: bool = True, **pod_kwargs: Any) -> type:
+    """Return a :class:`BenchPodPlug` subclass bound to a specific connection.
+
+    Ergonomic for direct bench use — put the pod's address right in the test::
+
+        @htf.plug(bench=benchpod_plug("192.168.1.50:8080"))
+        def phase(test, bench): ...
+
+        @htf.plug(bench=benchpod_plug("/dev/ttyACM0"))
+        def phase(test, bench): ...
+
+    Set ``persistent=True`` to keep one connection open across test executions
+    (reuse the *same* returned class for every ``Test.execute()`` so they share
+    it); see :func:`close_persistent_benchpods`. Extra keyword args are forwarded
+    to ``BenchPod(...)`` (``timeout=``, or ``transport=`` to inject a fake
+    backend in tests).
+    """
+    return type(
+        "BoundBenchPodPlug",
+        (BenchPodPlug,),
+        {
+            "connection": connection,
+            "pod_kwargs": pod_kwargs,
+            "persistent": persistent,
+            "health_check": health_check,
+        },
+    )

embeddedci_openhtf-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: embeddedci-openhtf
+Version: 0.1.0
+Summary: OpenHTF plug for driving an EmbeddedCI BenchPod directly over TCP or serial (no cloud)
+Project-URL: Homepage, https://embeddedci.com
+Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
+Project-URL: Issues, https://github.com/embeddedci-com/embeddedci-python/issues
+Author: EmbeddedCI
+License: Apache-2.0
+Keywords: benchpod,embedded,hardware-in-the-loop,manufacturing-test,openhtf,swd
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: embeddedci>=0.2
+Requires-Dist: openhtf>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# embeddedci-openhtf
+
+> ⚠️ **Experimental.** This package is new and its API may change between
+> releases. Pin a version and expect breaking changes before 1.0.
+
+Drive an **EmbeddedCI BenchPod** from [OpenHTF](https://www.openhtf.com/) —
+Google's open-source hardware test framework — connecting **directly** to the pod
+over a TCP socket or serial port. No EmbeddedCI cloud account, OIDC, or web UI is
+required: this package is for teams who want OpenHTF's test sequencing, limits,
+records, and station GUI while talking straight to a pod on their own bench.
+
+It's a thin wrapper over the [`embeddedci`](../embeddedci) BenchPod SDK: a single
+plug plus a few phase helpers. The dependency direction is strictly
+**`embeddedci-openhtf` → `embeddedci`**.
+
+```bash
+pip install embeddedci-openhtf      # pulls in embeddedci + openhtf
+```
+
+## The plug
+
+`BenchPodPlug` opens a `BenchPod` when a test starts and closes it at teardown.
+Bind the connection inline with `benchpod_plug(...)`, or leave it unbound and
+supply it through OpenHTF config / the `BENCHPOD_CONNECTION` env var.
+
+```python
+import openhtf as htf
+from embeddedci_openhtf import benchpod_plug
+
+bench = benchpod_plug("192.168.1.50:8080")   # TCP — or benchpod_plug("/dev/ttyACM0")
+
+@htf.plug(bench=bench)
+def power_up(test, bench):
+    bench.power_on()                 # methods proxy to the BenchPod SDK client
+    bench.pod.capture_uart(...)      # or reach the full client via .pod
+```
+
+Connection forms (all **direct**, never cloud):
+
+| Form | Example |
+| --- | --- |
+| TCP `host[:port]` | `benchpod_plug("192.168.1.50:8080")` |
+| Serial device path | `benchpod_plug("/dev/ttyACM0")` / `benchpod_plug("COM5")` |
+| `BENCHPOD_CONNECTION` env | `benchpod_plug()` (unbound) |
+| OpenHTF config | `htf.conf.load(benchpod_connection="...")` then `@htf.plug(bench=BenchPodPlug)` |
+
+## Phase helpers
+
+Ready-made, fully-decorated phases for the common steps:
+
+```python
+from embeddedci_openhtf import benchpod_plug, flash_phase, boot_banner_phase
+
+bench = benchpod_plug("192.168.1.50:8080")
+
+test = htf.Test(
+    flash_phase(bench, file="fw.elf", target="target/stm32f4x.cfg",
+                swclk=11, swdio=12, nreset=3),      # records flash_ok, attaches openocd.log
+    boot_banner_phase(bench, rx=1, tx=2, expect="APP_OK"),   # records boot_ok, attaches uart.txt
+)
+test.execute(test_start=lambda: "SN-0001")
+```
+
+LA channels are 1-12 (the pod has 12 generic logic-analyzer channels and no
+fixed-role pins — wire any DUT signal to any channel and name it here).
+
+For anything custom, write a normal phase and use the recorders in
+`embeddedci_openhtf.measurements` (`record_flash`, `record_uart`,
+`record_samples`) to map SDK results onto measurements and attachments.
+
+`flash_phase` needs `openocd` on PATH (the pod is the CMSIS-DAP probe; OpenOCD
+runs the flash algorithm from the `target=` config, so every OpenOCD-supported
+MCU works unchanged).
+
+### Analog steps
+
+The pod's DAC output and ADC input are exposed as analog phases (and low-level
+helpers). **These are TCP-only** — they need the JSON/sample channel that the
+serial console doesn't provide.
+
+```python
+from embeddedci_openhtf import (
+    benchpod_plug, signal_generate_phase, adc_capture_phase, loopback_measure_phase,
+)
+bench = benchpod_plug("192.168.1.50:8080")
+
+test = htf.Test(
+    # drive the DAC and capture the ADC together (loopback), assert the round trip
+    loopback_measure_phase(bench, waveform="sine", freq=10_000, amplitude=120,
+                           pp_range=(180, 255), mean_range=(110, 150)),
+    # or: free-run a waveform, then snapshot the ADC separately
+    signal_generate_phase(bench, waveform="square", freq=1_000, amplitude=100),
+    adc_capture_phase(bench, samples=4096, pp_range=(150, 255)),
+)
+```
+
+Each capture/measure phase records `<prefix>_min` / `_max` / `_mean` / `_pp`
+(peak-to-peak) measurements — pass any as `(low, high)` to make it a limit — and
+attaches the raw samples as `adc.json`. The low-level helpers `signal_generate`,
+`signal_stop`, and `measure` are available for custom phases.
+
+## Station mode (persistent connection)
+
+By default the plug opens a connection per `Test.execute()` and closes it at
+teardown. On a station cycling many DUTs back-to-back, pass `persistent=True` to
+keep **one** connection open across executions (re-checked with a ping each run,
+reconnected if it dropped). Reuse the *same* plug class for every execution, and
+close it once at the end:
+
+```python
+from embeddedci_openhtf import benchpod_plug, close_persistent_benchpods
+from openhtf.plugs import user_input
+
+bench = benchpod_plug("192.168.1.50:8080", persistent=True)
+test = htf.Test(power_phase(bench, on=True), boot_banner_phase(bench, rx=1, tx=2, expect="APP_OK"))
+try:
+    while test.execute(test_start=user_input.prompt_for_test_start()):
+        pass            # next DUT — same pod connection
+finally:
+    close_persistent_benchpods()   # also runs automatically at process exit
+```
+
+## Examples
+
+* [`examples/flash_and_boot.py`](examples/flash_and_boot.py) — flash over SWD then
+  assert the boot banner, over a direct TCP connection.
+* [`examples/serial_smoke.py`](examples/serial_smoke.py) — a no-flash power + UART
+  smoke test with a parsed measurement, over a direct serial connection.
+* [`examples/analog_loopback.py`](examples/analog_loopback.py) — DAC→ADC loopback
+  signal-path self-test, over a direct TCP connection.
+* [`examples/station.py`](examples/station.py) — a station loop testing many DUTs
+  over one **persistent** connection.
+
+## Development
+
+```bash
+# from the repo root
+pip install -e "packages/embeddedci[dev]"
+pip install -e "packages/embeddedci-openhtf[dev]"
+pytest packages/embeddedci-openhtf
+```
+
+The test suite runs the real OpenHTF executor against an in-memory fake transport
+(`tests/_fake.py`), so it needs no pod and no OpenOCD.

embeddedci_openhtf-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+embeddedci_openhtf/__init__.py,sha256=27fkOUJ1HlBbrGxyBux3hfL-WecGRLxzkMgm6Ptpx4E,2015
+embeddedci_openhtf/analog.py,sha256=UjEA5ygxQiT9Ci7QpNQChjONBY9z2Mj3yYi_JnnFDb0,8070
+embeddedci_openhtf/measurements.py,sha256=WPlYk7TJxXWMUXoW74sf-R0mtqnN2tF6lDEo4Xqe26c,4332
+embeddedci_openhtf/phases.py,sha256=sLe-f2p30Fx4SrbybWxALyp0xw6zaj6Djcf7WF-pIWo,4613
+embeddedci_openhtf/plug.py,sha256=RtiPFAKFgEl7qdRZUXJ5bLqgG4z_WjxND4lkjV2--Yk,8618
+embeddedci_openhtf-0.1.0.dist-info/METADATA,sha256=Sb8M8HFdfa5n73X0D9cQGxXbhobq11WKpIPX05KuXb4,6989
+embeddedci_openhtf-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+embeddedci_openhtf-0.1.0.dist-info/RECORD,,

embeddedci_openhtf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any