embeddedci 2.5.0__tar.gz → 2.7.0__tar.gz

{embeddedci-2.5.0 → embeddedci-2.7.0}/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog — `embeddedci`
 
+## 2.7.0
+
+- `UartSession.write` on a link that is gone (a reset connection, an unplugged pod, a closed
+  cloud tunnel) raises `UartLinkError` instead of the raw `BrokenPipeError`/`OSError`.
+- Typed refusals. `PodLockedError`: the pod's LAN policy keeps this command for the cloud or the
+  USB console (`locked: …`, and a policy change sent over the LAN). `PodLeasedError` (with
+  `holder`, `left_s` and, from the server, `expires_at`): a cloud job holds the pod (`busy: a
+  cloud job holds this pod (…)` on the LAN, HTTP 409 from the server). `PodBusyError`: any other
+  `busy: …`. `PermissionDeniedError` (with `status`): the pod's `forbidden: …` on a cloud tunnel
+  and a server HTTP 403 (`ServerPermissionDeniedError` from `ServerApi`). An HTML 403 from the
+  Cloudflare edge stays a `TransportError`. Every new class also subclasses what the refusal used
+  to raise (`FirmwareError`, `TransportError`, `DeviceBusyError`, `ServerApiError`), so existing
+  handlers still catch them. Refusals are classified wherever they arrive, not only in
+  `BenchPod.command`.
+- `Capabilities` parses every flag firmware 3.6 and the server announce: `analog` (`None` when not
+  announced), `dac_limits`, `flash_kb`, `blob_slots`, `ota_sig`, `sig_policy`, `sig_keys`,
+  `sig_policy_cmd`, `lan_policy`, `lan_policy_cmd`, `tunnel_max_tier`, `lease_state`, `cloud_ca`,
+  `cloud_proxy` and (server only) `ws_auth_v2`.
+- Errors: a socket or serial failure no longer escapes as a raw `OSError`. A pod that does not
+  answer in time raises `TransportTimeout` (a `TransportError`, and still a `TimeoutError`); a
+  connection that ends or resets before the reply raises `ConnectionClosedError` (a
+  `TransportError`). Over the cloud a slow pod used to look like a closed connection; it is now
+  a timeout too, and a lost connection to the server during a command is a
+  `ConnectionClosedError` instead of a raw exception.
+- Timeouts follow the request: a blocking `measure_power(duration)` waits for its duration on top
+  of the connection timeout (it used to fail after the fixed 30 s), and so do a triggered
+  capture's `trigger_timeout` and a `dap_start` wait. The cloud command channel asks the server
+  to wait that long too (the server caps it at 120 s).
+- The handshake that switches a connection to raw mode (`dap_start`, `uart_proxy_start`) is
+  bounded by the timeout. A pod that never acknowledged it used to hang the caller.
+- `BenchPod.capabilities` is not cached when the status read fails, so a passing glitch no longer
+  leaves the whole session without capabilities. The failure is logged.
+- `UartSession`: when the link dies with an error (the connection drops, the pod is unplugged),
+  `expect()` and `read_until()` raise `UartLinkError` at once (a `UartTimeout` with the text so
+  far and the `cause`), `read()` raises it once nothing is unread, and `UartSession.error` says
+  why. They used to wait out the full timeout as if the DUT were quiet. A link closed with
+  `close()` is not an error.
+- Serial: stale bytes (a reply to a request that timed out) are dropped before each JSON request,
+  so they can no longer be taken as the next command's reply.
+- Cloud: after a Cloudflare edge error (502/503/504/52x) the command channel repeats only commands
+  that read (`status`, `ping`, `target_status`, `power_status`, the read form of `la_voltage`,
+  `dac_limits`, `calibrate`, ...). It used to repeat everything except a few target actions, so
+  an `spi_xfer`, a `generate` or a delayed `target_power` could run twice. A command the server
+  refused before forwarding ("retry shortly") is still repeated, whatever it is.
+- `la_step`: the docs said `delay` is the time between pulses; it is half of it (each pulse is
+  high for `delay`, then low for `delay`). `steps` above 65535 and a `delay` outside 4 µs..65.535 ms
+  now raise `ValueError` before anything is sent: the pod's counters are 16-bit and it refused
+  them with a bare "invalid args". `GpioPin.pulse` documents the same bounds.
+
+## 2.6.0
+
+- Cloud: the tunnel WebSocket sends the session token as an `Authorization: Bearer` header (and
+  the lease as `X-Benchpod-Lease`) instead of `?token=` in the URL, so the token stays out of
+  access logs. A tunnel error message never shows the token.
+- Cloud: a client-side upload over `embeddedci:<device>` (`replay()` of a waveform, SPI PSRAM
+  staging) goes out in frames of at most 1 KiB, paced to 128 KiB/s. It used to be one WebSocket
+  frame, which the pod drops without an error above about 1.5 KB. The upload also skips the
+  `{"ack":N}` progress lines the pod sends on a cloud tunnel instead of taking the first one as
+  the completion.
+- `PowerStatus.pod`: the pod's own 5 V draw, on boards that measure it (INA226 at 0x41, the
+  v3r1 analog and v3r2 digital boards). `PowerStatus.total_current` adds the DUT's internal rail
+  to it, which is what the USB input delivers. Both are `None` on other boards and on firmware
+  up to 3.5.1.
+- `Capabilities.pod_current`: the board has that monitor. Parsed from the pod's `status` and the
+  server's `cap.pod_current`.
+
 ## 2.5.0
 
 - `Capabilities.can`: the pod has classic CAN on CAN+/CAN- (`open_can`). Parsed from the pod's

{embeddedci-2.5.0 → embeddedci-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: embeddedci
-Version: 2.5.0
+Version: 2.7.0
 Summary: BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing
 Project-URL: Homepage, https://embeddedci.com
 Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -1177,7 +1177,10 @@ with bp.open_can(bitrate=500_000, term=True) as can:        # on a real bus, 120
 ### Step/direction pulse trains
 
 `bp.la_step(PIN3, steps=200, delay=0.001, dir_la=PIN4, direction=1)` emits step pulses on an LA
-channel, `delay` seconds apart, generated by the FPGA; it returns immediately.
+channel, generated by the FPGA; it returns immediately. `delay` is half the step period: each pulse
+is high for `delay`, then low for `delay`, so the example steps every 2 ms (500 steps/s). `steps`
+is 1..65535 and `delay` 4 µs..65.535 ms (16-bit counters in the gateware); split a longer move into
+several trains.
 
 ## Cloud (`embeddedci:<device-name>`)
 
@@ -1317,13 +1320,20 @@ Invalid arguments raise `ValueError` before anything is sent. Everything else ra
 | `BenchPodError` | base class of all of the below | |
 | `ConnectionConfigError` | no connection configured, unparsable string, discovery found zero or several pods | |
 | `TransportError` | the pod or tunnel could not be reached / talked to | |
+| `TransportTimeout` (a `TransportError` and a `TimeoutError`) | the pod or tunnel did not answer in time | |
+| `ConnectionClosedError` (a `TransportError`) | the connection ended or reset before the reply | |
 | `FirmwareError` | the pod replied with an error (e.g. "la voltage not set") | `firmware_message`, `cmd` |
 | `FlashError` | OpenOCD failed, is missing, or lacks the TCP backend | |
 | `TargetUnreachableError` (a `FlashError`) | the probe worked but no target answered on SWD | |
 | `DeviceBusyError` | a cloud device lease was not granted within `lease_wait` | |
 | `CloudAuthError` | no session token: API key rejected, OIDC unavailable, exchange failed | |
 | `ServerApiError` | an embeddedci server API call failed | `status` (HTTP) |
+| `PodLockedError` (a `FirmwareError`) | the pod's LAN policy keeps the command for the cloud or the USB console | `firmware_message`, `cmd` |
+| `PodBusyError` (a `FirmwareError`) | the pod is busy (`busy: …`), e.g. a capture or upload is running | `firmware_message`, `cmd` |
+| `PodLeasedError` (a `PodBusyError`, `DeviceBusyError` and `TransportError`) | a cloud job holds the pod (its refusal on the LAN, or the server's HTTP 409) | `holder`, `left_s`, `expires_at`, `status` |
+| `PermissionDeniedError` (a `FirmwareError` and `TransportError`) | the pod's `forbidden: …` on a cloud tunnel, or a server HTTP 403 (`ServerPermissionDeniedError`, also a `ServerApiError`, from `ServerApi`) | `status` |
 | `UartTimeout` | `UartSession.expect` timed out | `text` |
+| `UartLinkError` (a `UartTimeout` and `ConnectionClosedError`) | the UART link died with an error while `UartSession` waited | `text`, `cause` |
 | `PinConflictError` | an LA channel is already used by another function (a `FirmwareError`) | `la`, `function` |
 | `PullConflictError` | an engaged bias resistor can't work with the channel's function (a `FirmwareError`) | `la` |
 | `TriggerTimeout` | a triggered capture's condition never happened (a `FirmwareError`) | `la`, `edge` |

{embeddedci-2.5.0 → embeddedci-2.7.0}/README.md

@@ -1139,7 +1139,10 @@ with bp.open_can(bitrate=500_000, term=True) as can:        # on a real bus, 120
 ### Step/direction pulse trains
 
 `bp.la_step(PIN3, steps=200, delay=0.001, dir_la=PIN4, direction=1)` emits step pulses on an LA
-channel, `delay` seconds apart, generated by the FPGA; it returns immediately.
+channel, generated by the FPGA; it returns immediately. `delay` is half the step period: each pulse
+is high for `delay`, then low for `delay`, so the example steps every 2 ms (500 steps/s). `steps`
+is 1..65535 and `delay` 4 µs..65.535 ms (16-bit counters in the gateware); split a longer move into
+several trains.
 
 ## Cloud (`embeddedci:<device-name>`)
 
@@ -1279,13 +1282,20 @@ Invalid arguments raise `ValueError` before anything is sent. Everything else ra
 | `BenchPodError` | base class of all of the below | |
 | `ConnectionConfigError` | no connection configured, unparsable string, discovery found zero or several pods | |
 | `TransportError` | the pod or tunnel could not be reached / talked to | |
+| `TransportTimeout` (a `TransportError` and a `TimeoutError`) | the pod or tunnel did not answer in time | |
+| `ConnectionClosedError` (a `TransportError`) | the connection ended or reset before the reply | |
 | `FirmwareError` | the pod replied with an error (e.g. "la voltage not set") | `firmware_message`, `cmd` |
 | `FlashError` | OpenOCD failed, is missing, or lacks the TCP backend | |
 | `TargetUnreachableError` (a `FlashError`) | the probe worked but no target answered on SWD | |
 | `DeviceBusyError` | a cloud device lease was not granted within `lease_wait` | |
 | `CloudAuthError` | no session token: API key rejected, OIDC unavailable, exchange failed | |
 | `ServerApiError` | an embeddedci server API call failed | `status` (HTTP) |
+| `PodLockedError` (a `FirmwareError`) | the pod's LAN policy keeps the command for the cloud or the USB console | `firmware_message`, `cmd` |
+| `PodBusyError` (a `FirmwareError`) | the pod is busy (`busy: …`), e.g. a capture or upload is running | `firmware_message`, `cmd` |
+| `PodLeasedError` (a `PodBusyError`, `DeviceBusyError` and `TransportError`) | a cloud job holds the pod (its refusal on the LAN, or the server's HTTP 409) | `holder`, `left_s`, `expires_at`, `status` |
+| `PermissionDeniedError` (a `FirmwareError` and `TransportError`) | the pod's `forbidden: …` on a cloud tunnel, or a server HTTP 403 (`ServerPermissionDeniedError`, also a `ServerApiError`, from `ServerApi`) | `status` |
 | `UartTimeout` | `UartSession.expect` timed out | `text` |
+| `UartLinkError` (a `UartTimeout` and `ConnectionClosedError`) | the UART link died with an error while `UartSession` waited | `text`, `cause` |
 | `PinConflictError` | an LA channel is already used by another function (a `FirmwareError`) | `la`, `function` |
 | `PullConflictError` | an engaged bias resistor can't work with the channel's function (a `FirmwareError`) | `la` |
 | `TriggerTimeout` | a triggered capture's condition never happened (a `FirmwareError`) | `la`, `edge` |

{embeddedci-2.5.0 → embeddedci-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "embeddedci"
-version = "2.5.0"
+version = "2.7.0"
 description = "BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing"
 readme = "README.md"
 requires-python = ">=3.10"

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/__init__.py

@@ -83,15 +83,22 @@ from .errors import (
     BenchPodError,
     CanTimeout,
     CloudAuthError,
+    ConnectionClosedError,
     ConnectionConfigError,
     DeviceBusyError,
     FirmwareError,
     FlashError,
+    PermissionDeniedError,
     PinConflictError,
+    PodBusyError,
+    PodLeasedError,
+    PodLockedError,
     PullConflictError,
     TargetUnreachableError,
     TransportError,
+    TransportTimeout,
     TriggerTimeout,
+    UartLinkError,
     UartTimeout,
 )
 from .flash import FlashResult
@@ -102,7 +109,7 @@ from .lowlevel import LowLevel
 from .power import PowerProfile, PowerProfileSession
 from .replay import DacHandle, Fault, ReplayHandle, Segment
 from .results import Capture, CorrelatedCapture, LaCapture, Trigger
-from .server_api import ServerApi, ServerApiError
+from .server_api import ServerApi, ServerApiError, ServerPermissionDeniedError
 from .state import (
     AdcReading,
     AnalogPathState,
@@ -253,13 +260,21 @@ __all__ = [
     "BenchPodError",
     "ConnectionConfigError",
     "TransportError",
+    "TransportTimeout",
+    "ConnectionClosedError",
     "FirmwareError",
     "FlashError",
     "TargetUnreachableError",
     "DeviceBusyError",
     "CloudAuthError",
     "ServerApiError",
+    "ServerPermissionDeniedError",
+    "PodLockedError",
+    "PodBusyError",
+    "PodLeasedError",
+    "PermissionDeniedError",
     "UartTimeout",
+    "UartLinkError",
     "CanTimeout",
     "PinConflictError",
     "PullConflictError",

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/capabilities.py

@@ -81,6 +81,12 @@ def _as_bool(m: Mapping[str, Any], *keys: str) -> Optional[bool]:
     return None
 
 
+#: Boolean capabilities the firmware's ``status`` reports as top-level ``true`` fields (and the
+#: server as ``cap.<name>``), command_handler.c handle_status / cloud_client.c.
+_STATUS_FLAGS = ("ota_sig", "sig_policy_cmd", "lan_policy_cmd", "tunnel_max_tier", "lease_state",
+                 "cloud_ca", "cloud_proxy", "blob_slots")
+
+
 def _crash_text(v: Any) -> str:
     """The firmware's crash summary, with its "none" (no crash) mapped to ``""``."""
     s = str(v or "").strip()
@@ -171,6 +177,44 @@ class Capabilities:
     #: Classic CAN on the pod's CAN+/CAN- terminals: :meth:`BenchPod.open_can`. Firmware older
     #: than the flag still has CAN on every v2/v3 pod; it just doesn't say so.
     can: bool = False
+    #: The board measures the pod's own 5 V current: :attr:`PowerStatus.pod`.
+    pod_current: bool = False
+    #: The board has the analog front end (ADC, DAC, 4-20 mA). ``False`` on the digital-only
+    #: board; ``None`` when the firmware does not say (older firmware, analog boards only).
+    analog: Optional[bool] = None
+    #: Output limits on the DAC paths (``{"cmd":"dac_limits"}``).
+    dac_limits: bool = False
+
+    # firmware updates and policies
+    #: Internal flash of the pod's MCU in KiB (2048 or 1024); 0 when not reported.
+    flash_kb: int = 0
+    #: Spare flash slots for the W25Q blobs (``flash-self`` installs them).
+    blob_slots: bool = False
+    #: Firmware updates carry a signature the pod checks.
+    ota_sig: bool = False
+    #: The signature policy: ``"audit"`` (report only), ``"required"``, ...; ``""`` when unknown.
+    sig_policy: str = ""
+    #: Number of signing keys the pod trusts; 0 when not reported.
+    sig_keys: int = 0
+    #: The pod takes the ``sig_policy`` command.
+    sig_policy_cmd: bool = False
+    #: The LAN policy: ``"open"``, ``"locked"`` (LAN keeps T0/T1, the rest needs the cloud or USB)
+    #: or ``"off"``; ``""`` when unknown.
+    lan_policy: str = ""
+    #: The pod takes the ``lan_policy`` command.
+    lan_policy_cmd: bool = False
+    #: The pod limits a cloud tunnel to the tier the server allows its user (a non-admin gets
+    #: :class:`~embeddedci.benchpod.errors.PermissionDeniedError` for config and firmware commands).
+    tunnel_max_tier: bool = False
+    #: The pod knows when a cloud job holds it and refuses LAN writes meanwhile
+    #: (:class:`~embeddedci.benchpod.errors.PodLeasedError`).
+    lease_state: bool = False
+    #: The pod accepts a company CA for its cloud connection (``cloud_ca``).
+    cloud_ca: bool = False
+    #: The pod reaches the cloud through an HTTP proxy (``cloud_proxy``).
+    cloud_proxy: bool = False
+    #: The pod signs its cloud login with the v2 scheme (server-side flag only).
+    ws_auth_v2: bool = False
 
     #: LA I/O-bank voltage the pod currently reports (mV), if known.
     la_vccio_mv: int = 0
@@ -217,6 +261,18 @@ class Capabilities:
             c.adc_channels = v
         if (v := _as_int(status, "la_vccio_mv")) is not None:
             c.la_vccio_mv = v
+        # Top-level fields of newer firmware (not in caps[]).
+        for attr in _STATUS_FLAGS:
+            if status.get(attr) is True:
+                setattr(c, attr, True)
+        if (v := _as_bool(status, "analog")) is not None:
+            c.analog = v
+        if (v := _as_int(status, "flash_kb")) is not None and v > 0:
+            c.flash_kb = v
+        if (v := _as_int(status, "sig_keys")) is not None and v > 0:
+            c.sig_keys = v
+        c.sig_policy = str(status.get("sig_policy", "") or "")
+        c.lan_policy = str(status.get("lan_policy", "") or "")
         caps = status.get("caps")
         if isinstance(caps, (list, tuple)):
             names = {str(x).lower() for x in caps}
@@ -251,9 +307,14 @@ class Capabilities:
                 ("calibrate", "calibrate"),
                 ("current_out", "current_out"),
                 ("can", "can"),
+                ("pod_current", "pod_current"),
+                ("dac_limits", "dac_limits"),
+                *((f, f) for f in _STATUS_FLAGS),
             ):
                 if name in names and hasattr(c, attr):
                     setattr(c, attr, True)
+            if "analog" in names:
+                c.analog = True
         c.safe_mode = _as_bool(status, "safe_mode") is True
         c.safe_reason = str(status.get("safe_reason", "") or "") if c.safe_mode else ""
         c.last_crash = _crash_text(status.get("last_crash", status.get("crash")))
@@ -302,11 +363,22 @@ class Capabilities:
             ("nrst_pin", "cap.nrst_pin"), ("usb_cc", "cap.usb_cc"),
             ("spi_master", "cap.spi_master"), ("spi_stream", "cap.spi_stream"),
             ("calibrate", "cap.calibrate"), ("current_out", "cap.current_out"),
-            ("can", "cap.can"),
+            ("can", "cap.can"), ("pod_current", "cap.pod_current"),
+            ("dac_limits", "cap.dac_limits"),
+            ("ws_auth_v2", "cap.ws_auth_v2"),
+            *((f, f"cap.{f}") for f in _STATUS_FLAGS),
         ):
             b = _as_bool(params, key)
             if b is not None:
                 setattr(c, attr, b)
+        # Tri-state: "" (not announced) stays None.
+        c.analog = _as_bool(params, "cap.analog")
+        if (v := _as_int(params, "cap.flash_kb")) is not None and v > 0:
+            c.flash_kb = v
+        if (v := _as_int(params, "cap.sig_keys")) is not None and v > 0:
+            c.sig_keys = v
+        c.sig_policy = str(params.get("cap.sig_policy", "") or "")
+        c.lan_policy = str(params.get("cap.lan_policy", "") or "")
         c.safe_mode = _as_bool(params, "cap.safe_mode") is True
         c.safe_reason = str(params.get("cap.safe_reason", "") or "") if c.safe_mode else ""
         c.last_crash = _crash_text(params.get("cap.last_crash"))

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/client.py

@@ -54,6 +54,9 @@ from .constants import (
     DAC_PATHS,
     DECODE_PROTOCOLS,
     GPIO_MODES,
+    LA_STEP_MAX_DELAY_US,
+    LA_STEP_MAX_STEPS,
+    LA_STEP_MIN_DELAY_US,
     LA_VOLTAGES,
     PULLDOWN_CHANNELS,
     PULLUP_CHANNELS,
@@ -322,13 +325,17 @@ class BenchPod:
 
         Parsed from :meth:`status` and — when the SDK has server access — enriched with the
         fuller ``cap.*`` set the server holds (explicit calibration + replay depth). Cached after
-        the first read; :meth:`refresh_capabilities` re-reads it.
+        the first successful read; :meth:`refresh_capabilities` re-reads it. When the status read
+        fails the result is not cached, so a passing glitch does not leave the session without
+        any capability for good.
         """
         if self._caps is None:
+            status_ok = True
             try:
                 status = self.status()
-            except BenchPodError:
-                status = {}
+            except BenchPodError as exc:
+                _log.warning("could not read the pod's status for its capabilities: %s", exc)
+                status, status_ok = {}, False
             caps = Capabilities.from_status(status)
             api = self._try_server_api()
             if api is not None and self._device_name:
@@ -338,6 +345,8 @@ class BenchPod:
                         caps = caps.merge(Capabilities.from_parameters(params))
                 except BenchPodError:
                     pass
+            if not status_ok:
+                return caps
             self._caps = caps
         return self._caps
 
@@ -1945,16 +1954,22 @@ class BenchPod:
 
     def la_step(self, la: Union[Pin, int], *, steps: int, delay: float,
                 dir_la: Optional[Union[Pin, int]] = None, direction: int = 0) -> Dict[str, Any]:
-        """Emit ``steps`` step pulses on an LA channel, ``delay`` seconds apart (step/dir drivers).
-
-        The FPGA runs the train autonomously and this returns immediately. With ``dir_la`` set,
-        that channel is driven to ``direction`` (0/1) first.
+        """Emit ``steps`` step pulses on an LA channel (step/dir drivers).
+
+        ``delay`` is HALF the step period: each pulse is high for ``delay`` seconds, then low for
+        ``delay``, so pulses are ``2 * delay`` apart (``1 / (2 * delay)`` steps per second).
+        ``steps`` is 1..65535 and ``delay`` 4 µs..65.535 ms (the gateware counters are 16-bit);
+        split a longer move into several trains. The FPGA runs the train autonomously and this
+        returns immediately. With ``dir_la`` set, that channel is driven to ``direction`` (0/1)
+        first.
         """
-        if steps <= 0:
-            raise ValueError(f"steps must be > 0, got {steps!r}")
+        if not 1 <= steps <= LA_STEP_MAX_STEPS:
+            raise ValueError(f"steps must be 1..{LA_STEP_MAX_STEPS} (the pod's step counter is "
+                             f"16-bit; split a longer move), got {steps!r}")
         delay_us = int(round(delay * 1e6))
-        if delay_us < 1:
-            raise ValueError(f"delay must be at least 1 µs, got {delay!r}")
+        if not LA_STEP_MIN_DELAY_US <= delay_us <= LA_STEP_MAX_DELAY_US:
+            raise ValueError(f"delay must be {LA_STEP_MIN_DELAY_US} µs..{LA_STEP_MAX_DELAY_US / 1e3:g} ms "
+                             f"(half the step period), got {delay!r}")
         if direction not in (0, 1):
             raise ValueError(f"direction must be 0 or 1, got {direction!r}")
         req: Dict[str, Any] = {"cmd": "la", "la": self._resolve_la(la)[0], "steps": int(steps),

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/constants.py

@@ -153,6 +153,12 @@ PULL_OHMS: Dict[int, str] = {
 PULLUP_CHANNELS: Tuple[int, ...] = (1, 2, 3, 4, 5, 6)
 PULLDOWN_CHANNELS: Tuple[int, ...] = (7, 8)
 
+# LA step trains (``la_step``, ``GpioPin.pulse``): the gateware counts steps and the half-period in
+# 16-bit counters, so the pod refuses more steps or a longer half-period.
+LA_STEP_MAX_STEPS = 65535
+LA_STEP_MIN_DELAY_US = 4
+LA_STEP_MAX_DELAY_US = 65535
+
 
 def check_choice(value: str, choices: Sequence[str], name: str) -> str:
     """Return ``value`` if it is one of ``choices``, else raise a :class:`ValueError` naming them."""

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/errors.py

@@ -18,6 +18,18 @@ class TransportError(BenchPodError):
     """A transport-level failure: could not reach or talk to the pod."""
 
 
+class TransportTimeout(TransportError, TimeoutError):
+    """The pod (or the cloud tunnel) did not answer within the timeout.
+
+    Distinct from :class:`ConnectionClosedError`: the link is still up, the reply just did not
+    come in time. Also a :class:`TimeoutError`, which the raw socket timeout used to be.
+    """
+
+
+class ConnectionClosedError(TransportError):
+    """The connection ended (EOF, reset or a closed tunnel) before the full reply arrived."""
+
+
 class DeviceBusyError(BenchPodError):
     """The shared cloud BenchPod is held by another consumer and did not free within the wait
     timeout. Raised when acquiring the device lease times out."""
@@ -67,6 +79,19 @@ class UartTimeout(BenchPodError):
         super().__init__(message)
 
 
+class UartLinkError(UartTimeout, ConnectionClosedError):
+    """The UART proxy link ended with an error (the connection dropped, the pod went away)
+    while :class:`~embeddedci.benchpod.uart.UartSession` was waiting for output.
+
+    A :class:`UartTimeout` too, so code written for the timeout still catches it; :attr:`text`
+    has everything received before the link died and :attr:`cause` the error that ended it.
+    """
+
+    def __init__(self, message: str, *, text: str = "", cause: Optional[BaseException] = None) -> None:
+        super().__init__(message, text=text)
+        self.cause = cause
+
+
 class CanTimeout(BenchPodError):
     """A :meth:`CanBus.expect` waited for a matching CAN frame but none arrived.
 
@@ -113,9 +138,62 @@ class TriggerTimeout(FirmwareError):
         self.edge = edge
 
 
+class PodLockedError(FirmwareError):
+    """The pod refused a command on its LAN connection: its LAN policy is ``locked`` (or the
+    command changes a policy), so the command needs the cloud (``embeddedci:<device>``) or the
+    USB console. Firmware text: ``locked: <cmd> needs the cloud or the USB console``."""
+
+
+class PodBusyError(FirmwareError):
+    """The pod refused because it is busy (``busy: …``): a capture or upload is running, or a
+    cloud job holds it (:class:`PodLeasedError`)."""
+
+
+class PodLeasedError(PodBusyError, DeviceBusyError, TransportError):
+    """A cloud job holds the pod, so this client may look but not touch.
+
+    Raised for the pod's own refusal on the LAN (``busy: a cloud job holds this pod (<holder>,
+    <n> s left)``) and for the server's HTTP 409 when another consumer holds the device lease.
+    :attr:`holder` names the job (``""`` when unknown), :attr:`left_s` the seconds its lease has
+    left (``None`` when unknown) and :attr:`expires_at` the server's expiry time, if it sent one.
+
+    Also a :class:`FirmwareError`, :class:`DeviceBusyError` and :class:`TransportError`, which
+    these refusals were before, so existing handlers keep working.
+    """
+
+    def __init__(self, message: str, *, cmd: Optional[str] = None, holder: str = "",
+                 left_s: Optional[int] = None, expires_at: str = "",
+                 status: Optional[int] = None) -> None:
+        super().__init__(message, cmd=cmd)
+        self.holder = holder
+        self.left_s = left_s
+        self.expires_at = expires_at
+        self.status = status
+
+
+class PermissionDeniedError(FirmwareError, TransportError):
+    """The caller is not allowed to do this: the pod's ``forbidden: <cmd> needs an organization
+    owner or admin`` on a cloud tunnel, or an HTTP 403 from the server (the API key lacks a
+    scope, the session token does not cover the device, the user is not an owner or admin).
+
+    :attr:`status` is the HTTP status (403) when the server refused, else ``None``. Also a
+    :class:`FirmwareError` and :class:`TransportError`, which these refusals were before.
+    """
+
+    def __init__(self, message: str, *, cmd: Optional[str] = None,
+                 status: Optional[int] = None) -> None:
+        super().__init__(message, cmd=cmd)
+        self.status = status
+
+
 _PIN_CONFLICT = re.compile(r"pin conflict: LA(\d+) is in use by (\w+)")
 _PULL_CONFLICT = re.compile(r"pull conflict: LA(\d+)")
 _TRIGGER_TIMEOUT = re.compile(r"trigger timeout: no (\w+) \w+ on LA(\d+)")
+#: "busy: a cloud job holds this pod (<holder>, <n> s left)" (command_handler.c dispatch_line).
+_LEASED = re.compile(r"busy: a cloud job holds this pod \((.*), (\d+) s left\)")
+#: Policy changes the LAN may not make (pod_policy.c).
+_POLICY_ELSEWHERE = ("change it from the cloud or the USB console",
+                     "only the USB console can loosen")
 
 
 def classify_firmware_error(exc: FirmwareError) -> FirmwareError:
@@ -132,4 +210,18 @@ def classify_firmware_error(exc: FirmwareError) -> FirmwareError:
     m = _TRIGGER_TIMEOUT.search(msg)
     if m:
         return TriggerTimeout(msg, cmd=exc.cmd, la=int(m.group(2)), edge=m.group(1))
+    if msg.startswith("locked:") or any(p in msg for p in _POLICY_ELSEWHERE):
+        return PodLockedError(msg, cmd=exc.cmd)
+    m = _LEASED.search(msg)
+    if m:
+        return PodLeasedError(msg, cmd=exc.cmd, holder=m.group(1), left_s=int(m.group(2)))
+    if msg.startswith("busy:"):
+        return PodBusyError(msg, cmd=exc.cmd)
+    if msg.startswith("forbidden:"):
+        return PermissionDeniedError(msg, cmd=exc.cmd)
     return exc
+
+
+def firmware_error(message: str, *, cmd: Optional[str] = None) -> FirmwareError:
+    """The :class:`FirmwareError` (its specific subclass when there is one) for a pod refusal."""
+    return classify_firmware_error(FirmwareError(message, cmd=cmd))

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/gpio.py

@@ -123,8 +123,8 @@ class GpioPin:
 
     def pulse(self, width: float, *, count: int = 1) -> None:
         """Emit ``count`` high pulses of ``width`` seconds (``width`` low between them), timed by the
-        FPGA; returns immediately. The pin must be a GPIO output at level 0 (it goes back to its GPIO
-        level afterwards) or unused."""
+        FPGA; returns immediately. ``count`` is 1..65535 and ``width`` 4 µs..65.535 ms. The pin must
+        be a GPIO output at level 0 (it goes back to its GPIO level afterwards) or unused."""
         self._pod.la_step(self.la, steps=count, delay=width)
 
     def release(self) -> None:

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/protocol.py

@@ -12,7 +12,7 @@ import json
 from dataclasses import dataclass
 from typing import Any, Optional
 
-from .errors import FirmwareError, TransportError
+from .errors import TransportError, firmware_error
 
 
 @dataclass
@@ -50,12 +50,13 @@ def parse_reply(line: bytes) -> Reply:
 
 
 def raise_for_status(reply: Reply, cmd: Optional[str] = None) -> Reply:
-    """Raise :class:`FirmwareError` if the reply is an error packet.
+    """Raise :class:`FirmwareError` (its specific subclass, see
+    :func:`~embeddedci.benchpod.errors.classify_firmware_error`) if the reply is an error packet.
 
     Returns the reply unchanged on success so callers can chain.
     """
     if reply.status == "error":
-        raise FirmwareError(reply.message or "unknown firmware error", cmd=cmd)
+        raise firmware_error(reply.message or "unknown firmware error", cmd=cmd)
     if reply.status not in ("ok", "chunk"):
         raise TransportError(f"unexpected reply status {reply.status!r}")
     return reply

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/server_api.py

@@ -22,7 +22,7 @@ import urllib.request
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from .cloud_auth import DEFAULT_API_BASE, USER_AGENT
-from .errors import BenchPodError, CloudAuthError, TransportError
+from .errors import BenchPodError, CloudAuthError, PermissionDeniedError, TransportError
 
 _HTTP_TIMEOUT = 60.0
 
@@ -35,6 +35,15 @@ class ServerApiError(BenchPodError):
         super().__init__(message)
 
 
+class ServerPermissionDeniedError(ServerApiError, PermissionDeniedError):
+    """The server answered HTTP 403: the credential is not allowed to do this. Both a
+    :class:`ServerApiError` (what it was before) and a
+    :class:`~embeddedci.benchpod.errors.PermissionDeniedError`."""
+
+    def __init__(self, message: str, *, status: Optional[int] = 403) -> None:
+        PermissionDeniedError.__init__(self, message, status=status)
+
+
 class ServerApi:
     """Thin client for the embeddedci server HTTP API (``{api_base}/api/...``)."""
 
@@ -120,7 +129,8 @@ class ServerApi:
                 hint = (" — this endpoint needs the 'benchpod:control' capability; a cloud "
                         "(OIDC/github_action) session token authorizes it for its allowed devices, "
                         "as does an API key or a real-user session")
-            raise ServerApiError(
+            cls = ServerPermissionDeniedError if exc.code == 403 else ServerApiError
+            raise cls(
                 f"{method} {path} failed (HTTP {exc.code}): {detail}{hint}", status=exc.code
             ) from exc
         except urllib.error.URLError as exc:

{embeddedci-2.5.0 → embeddedci-2.7.0}/src/embeddedci/benchpod/state.py

@@ -111,6 +111,12 @@ class PowerStatus:
 
     internal: RailPower
     external: RailPower
+    #: The pod's own 5 V draw, on boards that measure it (``Capabilities.pod_current``); ``None``
+    #: otherwise. The DUT's internal rail bypasses this monitor.
+    pod: Optional[RailPower] = None
+    #: Pod + DUT internal rail in amps: what the USB input delivers. ``None`` unless the pod
+    #: reported it (both monitors read).
+    total_current: Optional[float] = None
     raw: Dict[str, Any] = _raw()
 
     def rail(self, efuse: "Efuse | int") -> RailPower:
@@ -127,7 +133,10 @@ class PowerStatus:
                              bus_voltage=(_opt_int(r, "bus_mv") or 0) / 1000.0,
                              current=(_opt_int(r, "current_ua") or 0) / 1e6)
 
-        return cls(internal=one("internal"), external=one("external"), raw=d)
+        pod = one("pod") if isinstance(d.get("pod"), Mapping) else None
+        total_ua = _opt_int(_d(d.get("pod")), "total_ua")
+        return cls(internal=one("internal"), external=one("external"), pod=pod,
+                   total_current=None if total_ua is None else total_ua / 1e6, raw=d)
 
 
 @dataclass(frozen=True)