embeddedci 0.2.0__tar.gz → 0.2.2__tar.gz

{embeddedci-0.2.0 → embeddedci-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embeddedci
-Version: 0.2.0
+Version: 0.2.2
 Summary: BenchPod pytest client for EmbeddedCI hardware-in-the-loop testing
 Project-URL: Homepage, https://embeddedci.com
 Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -68,10 +68,36 @@ pip install embeddedci
 pip install "embeddedci[cloud]"
 ```
 
-Flashing shells out to **OpenOCD**, which must be on your `PATH`
-(`brew install open-ocd` / `apt install openocd`). The `[cloud]` extra pulls in a
-WebSocket client used only by the `embeddedci:` destination; local wifi/serial use
-needs nothing extra.
+The `[cloud]` extra pulls in a WebSocket client used only by the `embeddedci:` destination;
+local wifi/serial use needs nothing extra.
+
+### OpenOCD (required for flashing)
+
+Flashing shells out to **OpenOCD**, which must be on your `PATH`. It drives the pod's SWD probe
+through OpenOCD's `remote_bitbang` adapter in **SWD** mode — and **SWD support for `remote_bitbang`
+only exists in OpenOCD *master* (post‑0.12.0)**. The stock packages (`apt install openocd`,
+`brew install open-ocd`) are **0.12.0**, whose `remote_bitbang` is `jtag_only`; flashing with them
+fails immediately:
+
+```
+Info : only one transport option; autoselect 'jtag'
+Error: Can't change session's transport after the initial selection was made
+```
+
+Install a master snapshot instead — the easiest is **xPack OpenOCD**:
+
+```bash
+# macOS / Linux via npm (xpm), or grab a release tarball directly:
+npm install -g @xpack-dev-tools/openocd
+# or: https://github.com/xpack-dev-tools/openocd-xpack/releases  (extract, add bin/ to PATH)
+```
+
+Verify your OpenOCD can do SWD over `remote_bitbang`:
+
+```bash
+openocd -c "adapter driver remote_bitbang" -c "transport list" -c "exit"
+# must list:  jtag  swd     (if only 'jtag', it's too old)
+```
 
 ## Named constants (no magic numbers)
 
@@ -191,10 +217,10 @@ from embeddedci import benchpod
 
 with benchpod.BenchPod("192.168.1.213") as bp:
     bp.flash(file="app.elf", target="target/stm32f4x.cfg",
-             swclk=benchpod.PIN13, swdio=benchpod.PIN14, target_power=benchpod.INTERNAL)
+             swclk=benchpod.PIN11, swdio=benchpod.PIN12, target_power=benchpod.INTERNAL)
 
-    # I2C is open-drain — enable the pod's pull-ups on SDA/SCL (LA1-8 only),
-    # then have the pod become a BMP280 on those lines.
+    # I2C is open-drain — enable the pod's pull-ups on SDA/SCL. Pull-ups exist
+    # only on LA1-8 (LA1/2=4.7k, LA3/4=2.2k, LA5-8=10k), so put SDA/SCL on LA1/2.
     bp.enable_pullup(benchpod.PIN1, benchpod.PIN2)
     bp.enable_i2c_sensor(benchpod.Sensor.BMP280, sda=benchpod.PIN1, scl=benchpod.PIN2,
                          temperature_c=22.5, pressure_pa=101000)
@@ -263,8 +289,10 @@ pytest examples/test_bmp280.py \
 
 It uses the plugin's `benchpod`, `pins` and `firmware` fixtures and the
 `@pytest.mark.hardware` marker, and **skips automatically** without a connection.
-The pin map comes from `--benchpod-swclk/-swdio/-nreset/-uart-rx/-uart-tx/-i2c-sda/-i2c-scl/-efuse`
-options (sensible defaults) so tests aren't hardcoded to your wiring. See
+The `pins` fixture exposes the pod's 12 generic LA channels (`pins.pin_1` …
+`pins.pin_12`) plus `pins.efuse` — there are no role-named pins, since any DUT
+signal can be on any channel. The example maps its own wiring (which signal is on
+which channel) in a small `wiring` fixture at the top. See
 [`examples/README.md`](examples/README.md) for the full wiring table.
 
 A more thorough multi-case version (present/absent + I2C-bus decode) lives in

{embeddedci-0.2.0 → embeddedci-0.2.2}/README.md

@@ -38,10 +38,36 @@ pip install embeddedci
 pip install "embeddedci[cloud]"
 ```
 
-Flashing shells out to **OpenOCD**, which must be on your `PATH`
-(`brew install open-ocd` / `apt install openocd`). The `[cloud]` extra pulls in a
-WebSocket client used only by the `embeddedci:` destination; local wifi/serial use
-needs nothing extra.
+The `[cloud]` extra pulls in a WebSocket client used only by the `embeddedci:` destination;
+local wifi/serial use needs nothing extra.
+
+### OpenOCD (required for flashing)
+
+Flashing shells out to **OpenOCD**, which must be on your `PATH`. It drives the pod's SWD probe
+through OpenOCD's `remote_bitbang` adapter in **SWD** mode — and **SWD support for `remote_bitbang`
+only exists in OpenOCD *master* (post‑0.12.0)**. The stock packages (`apt install openocd`,
+`brew install open-ocd`) are **0.12.0**, whose `remote_bitbang` is `jtag_only`; flashing with them
+fails immediately:
+
+```
+Info : only one transport option; autoselect 'jtag'
+Error: Can't change session's transport after the initial selection was made
+```
+
+Install a master snapshot instead — the easiest is **xPack OpenOCD**:
+
+```bash
+# macOS / Linux via npm (xpm), or grab a release tarball directly:
+npm install -g @xpack-dev-tools/openocd
+# or: https://github.com/xpack-dev-tools/openocd-xpack/releases  (extract, add bin/ to PATH)
+```
+
+Verify your OpenOCD can do SWD over `remote_bitbang`:
+
+```bash
+openocd -c "adapter driver remote_bitbang" -c "transport list" -c "exit"
+# must list:  jtag  swd     (if only 'jtag', it's too old)
+```
 
 ## Named constants (no magic numbers)
 
@@ -161,10 +187,10 @@ from embeddedci import benchpod
 
 with benchpod.BenchPod("192.168.1.213") as bp:
     bp.flash(file="app.elf", target="target/stm32f4x.cfg",
-             swclk=benchpod.PIN13, swdio=benchpod.PIN14, target_power=benchpod.INTERNAL)
+             swclk=benchpod.PIN11, swdio=benchpod.PIN12, target_power=benchpod.INTERNAL)
 
-    # I2C is open-drain — enable the pod's pull-ups on SDA/SCL (LA1-8 only),
-    # then have the pod become a BMP280 on those lines.
+    # I2C is open-drain — enable the pod's pull-ups on SDA/SCL. Pull-ups exist
+    # only on LA1-8 (LA1/2=4.7k, LA3/4=2.2k, LA5-8=10k), so put SDA/SCL on LA1/2.
     bp.enable_pullup(benchpod.PIN1, benchpod.PIN2)
     bp.enable_i2c_sensor(benchpod.Sensor.BMP280, sda=benchpod.PIN1, scl=benchpod.PIN2,
                          temperature_c=22.5, pressure_pa=101000)
@@ -233,8 +259,10 @@ pytest examples/test_bmp280.py \
 
 It uses the plugin's `benchpod`, `pins` and `firmware` fixtures and the
 `@pytest.mark.hardware` marker, and **skips automatically** without a connection.
-The pin map comes from `--benchpod-swclk/-swdio/-nreset/-uart-rx/-uart-tx/-i2c-sda/-i2c-scl/-efuse`
-options (sensible defaults) so tests aren't hardcoded to your wiring. See
+The `pins` fixture exposes the pod's 12 generic LA channels (`pins.pin_1` …
+`pins.pin_12`) plus `pins.efuse` — there are no role-named pins, since any DUT
+signal can be on any channel. The example maps its own wiring (which signal is on
+which channel) in a small `wiring` fixture at the top. See
 [`examples/README.md`](examples/README.md) for the full wiring table.
 
 A more thorough multi-case version (present/absent + I2C-bus decode) lives in

embeddedci-0.2.2/docs/event-uart-design.md

@@ -0,0 +1,182 @@
+# Design: event-based UART for pytest (`open_uart`)
+
+**Status: design only — not implemented.**
+
+## Problem
+
+Today UART is *capture-window* based:
+
+```python
+cap = bp.capture_uart(rx=5, tx=4, baud=115200, duration=6, until="APP_OK")
+```
+
+`capture()` ([uart.py](../src/embeddedci/benchpod/uart.py)) opens the proxy, then
+**blocks** reading for `duration` (or until a match) and closes. Because the read
+loop owns the calling thread, you cannot do anything else — including powering
+the target — while it runs. To catch a boot banner you must therefore use
+`power_cycle_and_capture`, which schedules a **delayed, pod-side** eFuse power-on
+so it fires *inside* the capture window:
+
+```python
+# the power-on is delayed so the banner lands in the window
+cap = bp.power_cycle_and_capture(rx=5, tx=4, efuse=1, delay=1.0, duration=6.0, until="APP_OK")
+```
+
+That delay is a workaround. We want to **start the eFuse immediately** (no
+pod-side timer) and still see the boot message. The only way is to begin
+*listening before* powering the target, then read at a later point.
+
+## Goal
+
+An event-based session: open the UART (start buffering in the background),
+power the target with a plain non-delayed `power_on`, then read.
+
+```python
+with bp.open_uart(rx=5, tx=4, baud=115200) as uart:
+    bp.power_on(bp.INTERNAL)                 # immediate — no pod-side delay
+    assert uart.read_until("APP_OK", timeout=6)
+    # ... later, a second read from the same stream:
+    uart.write(b"status\r\n")
+    print(uart.read_until("rx_byte_count", timeout=2))
+```
+
+Because the background reader is already draining the proxy when `power_on`
+fires, the banner emitted microseconds after power-up is buffered and the first
+`read_until` finds it.
+
+## Proposed API
+
+A new `UartSession` returned by `BenchPod.open_uart(...)`:
+
+```python
+class UartSession:
+    # --- reading ---
+    def read_until(self, pattern: Until, *, timeout: float) -> Optional[re.Match | str]:
+        """Block until `pattern` (substring/regex/predicate) appears in the
+        accumulated text or `timeout` elapses. Returns the match (truthy) or
+        None on timeout. Does NOT consume — `text` keeps growing."""
+
+    def read(self, *, timeout: float = 0.0) -> str:
+        """Return all text received so far. timeout>0 waits up to that long for
+        at least one new byte; timeout=0 is non-blocking."""
+
+    def expect(self, pattern: Until, *, timeout: float) -> re.Match | str:
+        """Like read_until but raises UartTimeout instead of returning None."""
+
+    @property
+    def text(self) -> str: ...          # everything decoded so far
+    @property
+    def lines(self) -> list[str]: ...   # convenience split
+
+    def drain(self) -> str:
+        """Return + clear the buffer (so the next read_until only sees new data)."""
+
+    # --- writing (proxy is bidirectional) ---
+    def write(self, data: bytes | str) -> None: ...
+
+    # --- lifecycle ---
+    def close(self) -> None: ...        # stop reader, leave the proxy
+    def __enter__(self) -> "UartSession": ...
+    def __exit__(self, *exc) -> None: ...   # calls close()
+```
+
+`BenchPod`:
+
+```python
+def open_uart(self, *, rx, tx, baud=115200, max_buffer=1<<20) -> UartSession: ...
+```
+
+`UartTimeout(BenchPodError)` is raised by `expect`.
+
+## Internals
+
+```
+open_uart()
+  link = transport.uart_proxy_start(rx, tx, baud)   # existing RawLink, raw 8N1
+  start a daemon thread: loop link.read(chunk) -> append under lock -> notify
+  return UartSession(link, thread, buffer, condition)
+```
+
+- **Buffer**: a `bytearray` guarded by a `threading.Lock`; a `threading.Condition`
+  signals readers when new bytes arrive or the link closes.
+- **Reader thread**: `while not stopped: data = link.read(chunk); if not data: mark
+  closed + notify; break; with lock: buffer += data; notify_all()`.
+  `link.read` already blocks until data/EOF, so the thread parks when the DUT is
+  quiet — no busy-poll.
+- **`read_until`**: under the condition, re-evaluate the predicate against
+  `buffer.decode("utf-8", errors="replace")` (decode the whole buffer each time, as
+  `capture()` does, so multi-byte chars split across chunks resolve); `wait(timeout)`
+  until it matches, the deadline passes, or the link closes.
+- **`close()`**: set `stopped`, `link.close()` (which unblocks the reader's
+  in-flight `read` and tells the firmware to leave PROTO_UART), `thread.join()`.
+- **Bounded buffer**: cap at `max_buffer`; on overflow drop oldest and set an
+  `overflowed` flag (surfaced on read) so a chatty DUT can't OOM a long session.
+- **Decode position**: keep raw bytes; decode lazily in `text`/`read_until`. Track a
+  `consumed` offset for `drain()`.
+
+`capture_uart` can be re-expressed on top of this (open → `read_until` or sleep
+`duration` → snapshot `text`/`lines` → close), keeping the existing one-shot API
+backward-compatible.
+
+## The key concurrency question: powering while listening
+
+`open_uart` holds the proxy connection for the whole session. `power_on` must run
+**concurrently** on a *different* path. This differs by transport:
+
+- **TCP (`TcpTransport`)** — every command dials a *fresh* socket
+  ([tcp.py](../src/embeddedci/benchpod/transport/tcp.py) `_dial`). The proxy holds
+  socket A; `power_on` opens socket B. The firmware services multiple AT
+  connections, and the soft-UART (FPGA) and the eFuse (target-power GPIO) are
+  independent subsystems — so they run concurrently. **Works as-is.**
+
+- **Cloud (`CloudTransport`)** — **implemented.** `CloudTransport.command()` now
+  routes non-streaming commands over the cloud **command channel**
+  (`POST /api/cloud/devices/command`, which the server turns into a
+  `command.request`/`command.response`) instead of dialing a second byte tunnel.
+  The firmware services the command channel (`CH_CLOUD_CONN`) and the byte tunnel
+  (`CH_CLOUD_TUNNEL_CONN`) as independent connections and announces
+  `"command":true` in its capabilities, so `power_on`/`power_off`/`gpio_set`/etc.
+  run *while* `uart_proxy_start` holds the tunnel. Streaming modes
+  (`dap_start`/`uart_proxy_start`) still use the tunnel via `_dial`. This both
+  removes the two-concurrent-tunnels requirement and makes every command faster
+  (one HTTP round-trip vs a fresh WebSocket dial).
+
+- **Thread-safety of the link** — the reader thread calls `link.read` while the
+  main thread may call `link.write`/`close`. Sockets allow concurrent
+  read/write in opposite directions; the cloud WS socket is created with
+  `enable_multithread=True` already, so this holds. `close()` from the main thread
+  unblocking a `read()` in the reader thread is the same pattern `capture()`'s
+  timer already relies on.
+
+## Edge cases to cover in implementation
+
+- **close() races**: idempotent close; reader thread exits on EOF or `stopped`.
+- **timeout returns vs raises**: `read_until` returns `None`; `expect` raises
+  `UartTimeout` carrying the buffered text (mirrors how `flash` surfaces context).
+- **partial UTF-8 / binary**: decode the whole buffer with `errors="replace"`;
+  never split a decode across a chunk boundary.
+- **predicate cost**: re-decoding the whole buffer per notify is O(n) per wakeup;
+  for very large/long sessions, decode incrementally or cap the scan window.
+- **proxy escape**: `close()` relies on `RawLink.close()` to leave the proxy
+  (TCP: socket close; serial: the proxy escape). No in-band sentinel needed.
+- **teardown ordering**: `__exit__` closes the UART session; target power is the
+  caller's responsibility (or a `power_off` in a fixture finalizer), unchanged.
+
+## Worked example (the motivating case)
+
+```python
+def test_boot_banner(benchpod):
+    bp = benchpod
+    with bp.open_uart(rx=5, tx=4, baud=115200) as uart:   # listening starts now
+        bp.power_on(bp.INTERNAL)                           # immediate eFuse start
+        m = uart.read_until(r"APP_OK", timeout=6)
+        assert m, f"no boot banner; got:\n{uart.text}"
+
+        # a second, independent read on the same live stream
+        uart.write(b"ping\r\n")
+        assert uart.expect("pong", timeout=2)
+    bp.power_off(bp.INTERNAL)
+```
+
+No `delay=`, no `power_cycle_and_capture` — the banner is caught because listening
+began before power-up.

{embeddedci-0.2.0 → embeddedci-0.2.2}/examples/README.md

@@ -27,19 +27,25 @@ Without `--benchpod-connection` the test **skips** (so it's safe in CI). The
 
 ### Wiring
 
-The defaults match a typical bench; override any pin with `--benchpod-<name>`:
+The pod has **no dedicated SWD/UART/I2C pins** — it exposes 12 generic LA channels
+(`pins.pin_1` … `pins.pin_12`) and any DUT signal can be on any of them. The example
+maps its own wiring in a `wiring` fixture at the top of `test_bmp280.py`; the table
+below is what that fixture uses — edit it to match your board.
 
-| DUT pin | Pod LA channel | Flag |
+| DUT pin | Pod LA channel | `wiring` field |
 |---|---|---|
-| SWCLK | LA11 | `--benchpod-swclk` |
-| SWDIO | LA12 | `--benchpod-swdio` |
-| NRST | LA3 | `--benchpod-nreset` |
-| UART TX (DUT→pod samples) | LA5 | `--benchpod-uart-rx` |
-| UART RX (pod→DUT drives) | LA4 | `--benchpod-uart-tx` |
-| I2C SDA (LA1–8 have pull-ups) | LA2 | `--benchpod-i2c-sda` |
-| I2C SCL (LA1–8 have pull-ups) | LA1 | `--benchpod-i2c-scl` |
+| SWCLK | LA11 | `wiring.swclk` |
+| SWDIO | LA12 | `wiring.swdio` |
+| NRST | LA3 | `wiring.nreset` |
+| UART TX (DUT→pod samples) | LA5 | `wiring.uart_rx` |
+| UART RX (pod→DUT drives) | LA4 | `wiring.uart_tx` |
+| I2C SDA (needs a pull-up) | LA2 | `wiring.i2c_sda` |
+| I2C SCL (needs a pull-up) | LA1 | `wiring.i2c_scl` |
 | Target 5V eFuse (1=int, 2=ext) | — | `--benchpod-efuse` |
 
+Pull-ups exist only on **LA1–8** (LA1/2 = 4.7k, LA3/4 = 2.2k, LA5–8 = 10k); LA9–12
+have none, so the open-drain I2C lines must sit on a pull-up-capable channel.
+
 ### Notes
 
 - **Serial vs wifi.** Over a serial console, SWD flashing is bit-banged and

{embeddedci-0.2.0 → embeddedci-0.2.2}/examples/test_bmp280.py

@@ -12,23 +12,27 @@
 #       --benchpod-connection=/dev/tty.usbserial-0001 \    # or 192.168.1.50 for wifi
 #       --benchpod-firmware=path/to/your_app.elf
 #
-# Wiring (override any with --benchpod-<name>=<LA-channel>):
+# Wiring — the pod has no dedicated SWD/UART/I2C pins. It exposes 12 generic LA
+# channels (pins.pin_1 .. pins.pin_12) and any DUT signal can be on any of them.
+# The `wiring` fixture below is THIS bench's map; edit it to match your board:
 #
-#   DUT pin                         Pod LA channel   flag
-#   ------------------------------  --------------   --------------------
-#   SWCLK                           LA11             --benchpod-swclk
-#   SWDIO                           LA12             --benchpod-swdio
-#   NRST                            LA3              --benchpod-nreset
-#   UART TX  (DUT -> pod samples)   LA5              --benchpod-uart-rx
-#   UART RX  (pod -> DUT drives)    LA4              --benchpod-uart-tx
-#   I2C SDA  (has a pull-up)        LA2              --benchpod-i2c-sda
-#   I2C SCL  (has a pull-up)        LA1              --benchpod-i2c-scl
+#   DUT pin                         Pod LA channel   wiring fixture
+#   ------------------------------  --------------   --------------
+#   SWCLK                           LA11             wiring.swclk
+#   SWDIO                           LA12             wiring.swdio
+#   NRST                            LA3              wiring.nreset
+#   UART TX  (DUT -> pod samples)   LA5              wiring.uart_rx
+#   UART RX  (pod -> DUT drives)    LA4              wiring.uart_tx
+#   I2C SDA  (needs a pull-up)      LA2 (4.7k)       wiring.i2c_sda
+#   I2C SCL  (needs a pull-up)      LA1 (4.7k)       wiring.i2c_scl
 #   5V power eFuse (1=int, 2=ext)   --benchpod-efuse
 #
-# The `benchpod`, `pins` and `firmware` fixtures come from the installed plugin;
-# the whole test skips automatically if no --benchpod-connection is given.
+# Pull-ups exist only on LA1-8 (LA1/2=4.7k, LA3/4=2.2k, LA5-8=10k), so the I2C
+# lines must sit on one of those. The `benchpod`, `pins` and `firmware` fixtures
+# come from the installed plugin; the test skips if no --benchpod-connection is set.
 
 import re
+from types import SimpleNamespace
 
 import pytest
 from embeddedci import benchpod as bp
@@ -37,8 +41,20 @@ APP_OK = re.compile(r"APP_OK")
 PRESENT = re.compile(r"chip id match=0x58|bmp280_detected=yes")
 
 
+@pytest.fixture
+def wiring(pins):
+    """This bench's wiring: DUT signal → BenchPod LA channel. Bench-specific —
+    any signal can be on any LA channel, except I2C SDA/SCL need a pull-up (LA1-8)."""
+    return SimpleNamespace(
+        swclk=pins.pin_11, swdio=pins.pin_12, nreset=pins.pin_3,
+        uart_rx=pins.pin_5, uart_tx=pins.pin_4,
+        i2c_sda=pins.pin_2, i2c_scl=pins.pin_1,  # LA1/2 — 4.7k pull-ups
+        efuse=pins.efuse,
+    )
+
+
 @pytest.mark.hardware
-def test_bmp280_sensor_present(benchpod, pins, firmware):
+def test_bmp280_sensor_present(benchpod, wiring, firmware):
     """Flash the DUT, emulate a BMP280 on I2C, power-cycle, assert on UART."""
 
     try:
@@ -46,18 +62,18 @@ def test_bmp280_sensor_present(benchpod, pins, firmware):
         result = benchpod.flash(
             file=firmware,
             target="target/stm32f4x.cfg",
-            swclk=pins.swclk, swdio=pins.swdio,
-            nreset=pins.nreset, target_power=pins.efuse,
+            swclk=wiring.swclk, swdio=wiring.swdio,
+            nreset=wiring.nreset, target_power=wiring.efuse,
             verify=False,  # bit-bang-over-serial: program reliably, skip the slow verify
         )
         assert result.ok
 
         # 2. Have the pod emulate a BMP280 on the DUT's I2C bus.
         #    I2C is open-drain, so enable the pod's pull-ups to idle the bus high.
-        benchpod.enable_pullup(pins.i2c_sda, pins.i2c_scl)
+        benchpod.enable_pullup(wiring.i2c_sda, wiring.i2c_scl)
         benchpod.enable_i2c_sensor(
             bp.Sensor.BMP280,
-            sda=pins.i2c_sda, scl=pins.i2c_scl,
+            sda=wiring.i2c_sda, scl=wiring.i2c_scl,
             address=bp.BMP280_ADDR_PRIMARY,
             temperature_c=22.5, pressure_pa=101000,
         )
@@ -67,7 +83,7 @@ def test_bmp280_sensor_present(benchpod, pins, firmware):
         #    we don't miss the boot banner. Stop at APP_OK, which the app prints last
         #    (after the BMP280 probe), so the capture contains both markers.
         cap = benchpod.power_cycle_and_capture(
-            rx=pins.uart_rx, tx=pins.uart_tx, efuse=pins.efuse,
+            rx=wiring.uart_rx, tx=wiring.uart_tx, efuse=wiring.efuse,
             delay=1.5, duration=8.0, until=APP_OK,
         )
 
@@ -78,4 +94,4 @@ def test_bmp280_sensor_present(benchpod, pins, firmware):
     finally:
         # Always leave the DUT powered down — cut the eFuse whether the test
         # passed or failed so the bench is left in a safe, known state.
-        benchpod.power_off(pins.efuse)
+        benchpod.power_off(wiring.efuse)

{embeddedci-0.2.0 → embeddedci-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "embeddedci"
-version = "0.2.0"
+version = "0.2.2"
 description = "BenchPod pytest client for EmbeddedCI hardware-in-the-loop testing"
 readme = "README.md"
 requires-python = ">=3.9"

{embeddedci-0.2.0 → embeddedci-0.2.2}/src/embeddedci/benchpod/__init__.py

@@ -49,14 +49,17 @@ from .errors import (
     FlashError,
     TargetUnreachableError,
     TransportError,
+    UartTimeout,
 )
 from .flash import FlashResult
-from .uart import UartCapture
+from .uart import UartCapture, UartSession
 
 __all__ = [
     "BenchPod",
     "FlashResult",
     "UartCapture",
+    "UartSession",
+    "UartTimeout",
     "i2c",
     "I2CByte",
     "I2CMessage",

{embeddedci-0.2.0 → embeddedci-0.2.2}/src/embeddedci/benchpod/client.py

@@ -301,6 +301,36 @@ class BenchPod:
         return self.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration,
                                  until=until)
 
+    def open_uart(
+        self,
+        *,
+        rx: Union[Pin, int],
+        tx: Union[Pin, int],
+        baud: int = 115200,
+        max_buffer: int = 1 << 20,
+    ) -> "_uart.UartSession":
+        """Open an event-based UART session (background reader) on the DUT.
+
+        Unlike :meth:`capture_uart` (a fixed window) this starts buffering
+        immediately and lets you read at a later point, so you can begin
+        listening *before* an action and still catch its output — e.g. a
+        **non-delayed** eFuse power-on whose boot banner you still want to see::
+
+            with bp.open_uart(rx=5, tx=4, baud=115200) as uart:
+                bp.power_on(bp.INTERNAL)            # immediate, no pod-side delay
+                uart.expect("APP_OK", timeout=6)    # banner buffered since power-up
+
+        ``rx`` is the LA channel the pod samples (wire the DUT's TX here); ``tx``
+        is driven (DUT's RX). Use as a context manager (or call ``.close()``).
+        Over the cloud transport, running other commands (``power_on``, ...) while
+        a session is open needs them to use the cloud command channel rather than
+        a second tunnel — see ``docs/event-uart-design.md``.
+        """
+        link = self._transport.uart_proxy_start(
+            coerce_pin(rx, "rx"), coerce_pin(tx, "tx"), int(baud)
+        )
+        return _uart.UartSession(link, max_buffer=max_buffer)
+
     # -- low-level pass-throughs (TCP transport only) -----------------------
 
     def command(self, req: dict) -> Any:

{embeddedci-0.2.0 → embeddedci-0.2.2}/src/embeddedci/benchpod/cloud_auth.py

@@ -19,8 +19,20 @@ import urllib.request
 
 from .errors import CloudAuthError
 
+# The OIDC audience is a logical identifier the server matches against the token's `aud` claim; it
+# does not have to be a reachable URL. The API base is the actual canonical host (note: the apex
+# embeddedci.com 301-redirects to www, which urllib would mishandle on a POST).
 DEFAULT_AUDIENCE = "https://embeddedci.com"
-DEFAULT_API_BASE = "https://embeddedci.com"
+DEFAULT_API_BASE = "https://www.embeddedci.com"
+
+# A real User-Agent is required: the apex/edge (Cloudflare) bans the default "Python-urllib/x.y"
+# signature (HTTP 403, error 1010). Identify the SDK explicitly instead.
+try:  # pragma: no cover - trivial
+    from importlib.metadata import version as _pkg_version
+
+    USER_AGENT = f"embeddedci-python/{_pkg_version('embeddedci')}"
+except Exception:  # pragma: no cover
+    USER_AGENT = "embeddedci-python"
 
 _HTTP_TIMEOUT = 15.0
 
@@ -52,7 +64,12 @@ def mint_oidc_token(audience: str = DEFAULT_AUDIENCE) -> str:
     sep = "&" if "?" in req_url else "?"
     url = f"{req_url}{sep}audience={urllib.parse.quote(audience, safe='')}"
     request = urllib.request.Request(
-        url, headers={"Authorization": f"Bearer {req_token}", "Accept": "application/json"}
+        url,
+        headers={
+            "Authorization": f"Bearer {req_token}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        },
     )
     try:
         with urllib.request.urlopen(request, timeout=_HTTP_TIMEOUT) as resp:
@@ -75,7 +92,11 @@ def exchange_token(api_base: str, oidc_token: str) -> dict:
     data = json.dumps({"token": oidc_token}).encode("utf-8")
     request = urllib.request.Request(
         url, data=data, method="POST",
-        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        },
     )
     try:
         with urllib.request.urlopen(request, timeout=_HTTP_TIMEOUT) as resp:

{embeddedci-0.2.0 → embeddedci-0.2.2}/src/embeddedci/benchpod/errors.py

@@ -47,3 +47,15 @@ class TargetUnreachableError(FlashError):
 
     Almost always means the target is unpowered, mis-wired, or held in reset.
     """
+
+
+class UartTimeout(BenchPodError):
+    """An event-based UART read (``UartSession.expect``) timed out.
+
+    Carries the text accumulated so far in :attr:`text` so the caller can see
+    what the DUT actually sent.
+    """
+
+    def __init__(self, message: str, *, text: str = "") -> None:
+        self.text = text
+        super().__init__(message)