From 24e9034d4b157b61603f06987b6351c247f773bf Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Mon, 16 Nov 2026 23:15:56 -0600 Subject: [PATCH] embeddedci 3.0.1: bp.diag(); warn when a LAN status is the short form Firmware 3.10.9 moves the diagnostics from status to the diag command. diag() reads it, else the full status on older firmware. A short status over a direct connection is read once more; still short, the SDK warns that the ADC calibration and feature flags come from embeddedci.com or the board defaults. README: diag() and the pod-stored save_wiring. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/CHANGELOG.md | 10 ++ packages/embeddedci/README.md | 2 +- packages/embeddedci/pyproject.toml | 2 +- .../src/embeddedci/benchpod/client.py | 44 +++++++ packages/embeddedci/tests/api_surface.json | 1 + packages/embeddedci/tests/test_status_diag.py | 124 ++++++++++++++++++ 6 files changed, 181 insertions(+), 2 deletions(-) create mode 100644 packages/embeddedci/tests/test_status_diag.py diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index 702ac57..2b7bb7a 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog — `embeddedci` +## 3.0.1 + +- `bp.diag()`: the pod's heap, per-task stacks, network-stack and console counters. Firmware 3.10.9 + moved them from `status` to the new `diag` command, so the full status keeps room under the + 2047 bytes a LAN connection takes in one reply; with older firmware `diag()` reads them from + `status`. +- When a LAN or USB-network status comes back as the short form (the full one did not fit the + connection), the SDK reads it once more and, when it is still short, logs a warning: the ADC + calibration and feature flags then come from embeddedci.com, else the board's defaults. + ## 3.0.0 A major release: wiring profiles live on the pod, nothing is wired by default, and refusals carry diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index a9c15c8..c054bdf 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -2194,7 +2194,7 @@ lease_wait=600.0, lease_ttl=120, wiring=None)`. A context manager; `close()` is | Area | Methods and properties | |---|---| -| Connection and device | `ping()`, `status()`, `mac_addresses(status=None)` (the Ethernet and Wi-Fi MACs, see [MAC addresses](#mac-addresses-managed-networks)), `capabilities`, `refresh_capabilities()` (drop the cached capabilities and read them again), `close()`, `leased` (true while this client holds the cloud lease), `wiring`, `save_wiring(wiring=None)` (store a cloud device's profile on embeddedci.com), `signal(name)`, `fpga_image(image)`, `usb_cc()`, `usb_network(on=None)` (the USB network setting; `False` turns the adapter off over the USB link), `lan_tls()`, `set_lan_tls_https_only(on)`, `regenerate_lan_tls()`, `set_lan_tls_cert(cert_pem, key_pem)` (the LAN API over TLS, see [TLS on the LAN](#tls-on-the-lan)) | +| Connection and device | `ping()`, `status()`, `diag()` (heap, per-task stacks, network-stack and console counters: the `diag` command on firmware 3.10.9+, else the full `status`), `mac_addresses(status=None)` (the Ethernet and Wi-Fi MACs, see [MAC addresses](#mac-addresses-managed-networks)), `capabilities`, `refresh_capabilities()` (drop the cached capabilities and read them again), `close()`, `leased` (true while this client holds the cloud lease), `wiring`, `save_wiring(wiring=None, name=None)` (store a wiring profile on the pod; firmware before 3.10.8: on embeddedci.com), `signal(name)`, `fpga_image(image)`, `usb_cc()`, `usb_network(on=None)` (the USB network setting; `False` turns the adapter off over the USB link), `lan_tls()`, `set_lan_tls_https_only(on)`, `regenerate_lan_tls()`, `set_lan_tls_cert(cert_pem, key_pem)` (the LAN API over TLS, see [TLS on the LAN](#tls-on-the-lan)) | | LA voltage | `set_la_voltage(volts)`, `get_la_voltage()` | | Power and reset | `power_on(efuse=None, *, delay=None)`, `power_off(efuse=None, *, delay=None)`, `target_power(efuse=None, *, on, delay=None)`, `target_status()`, `power_status()`, `measure_power(duration, *, efuse=None, rate_hz=500.0, keep_samples=0)`, `power_profile(*, efuse=None, rate_hz=500.0, keep_samples=4096, max_duration=60.0)`, `reset_target(*, pulse=0.1)`, `set_reset(asserted)`, `reset_state()` | | Flashing | `flash(...)`, `spi_flash(image, addr=0, *, erase=True, verify=True, hold_reset=False, sck=, mosi=, miso=, cs=)`, `open_spi(...)`, `open_motor_emulator(...)` | diff --git a/packages/embeddedci/pyproject.toml b/packages/embeddedci/pyproject.toml index 8f4c145..44704dd 100644 --- a/packages/embeddedci/pyproject.toml +++ b/packages/embeddedci/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "embeddedci" -version = "3.0.0" +version = "3.0.1" description = "BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing" readme = "README.md" requires-python = ">=3.10" diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 6508f74..259c5b1 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -439,6 +439,24 @@ def status(self) -> Dict[str, Any]: """The pod's status report: firmware version, board, network and advertised features.""" return _dict(self._transport.status()) + def diag(self) -> Dict[str, Any]: + """The pod's health counters: ``heap_free``, ``heap_min``, ``stack_min``, per-task + ``stacks``, the network stack's ``lwip_mem_*`` and ``pbuf_pool_*`` high-water marks, + ``malloc_failures``, the console's ``rx_dropped``/``tx_dropped`` and ``board_rev_mv``. + + Firmware 3.10.9+ answers the ``diag`` command; older firmware has them in its full + :meth:`status`, which this reads instead (over the cloud that status is the short form, + so only the heap and ``stack_min`` are there). + """ + try: + return _dict(self.command({"cmd": "diag"})) + except UnsupportedFeatureError: + st = self.status() + keys = ("heap_free", "heap_min", "stack_min", "stacks", "lwip_mem_max", "lwip_mem_size", + "pbuf_pool_max", "pbuf_pool_size", "malloc_failures", "rx_dropped", "tx_dropped", + "board_rev_mv") + return {k: st[k] for k in keys if k in st} + def mac_addresses(self, status: Optional[Mapping[str, Any]] = None) -> "MacAddresses": """The pod's Ethernet and Wi-Fi MACs, for a network that hands out addresses only to registered devices. @@ -491,6 +509,8 @@ def capabilities(self) -> Capabilities: except BenchPodError as exc: _log.warning("could not read the pod's status for its capabilities: %s", exc) status, status_ok = {}, False + if status_ok and status.get("short_form") and self._direct_network(): + status = self._full_status(status) caps = Capabilities.from_status(status) api = self._try_server_api() if api is not None and self._device_name: @@ -505,6 +525,30 @@ def capabilities(self) -> Capabilities: self._caps = caps return self._caps + def _direct_network(self) -> bool: + """A LAN or USB network connection: one that should get the pod's full status.""" + from .transport.tcp import TcpTransport + return isinstance(self._transport, TcpTransport) + + def _full_status(self, status: Dict[str, Any]) -> Dict[str, Any]: + """``status`` was the short form over a direct connection: the full form did not fit the + connection whole (more than 2047 bytes, or the connection's send buffer was busy). Ask + once more, and warn when it is still short: the ADC calibration and feature flags the + short form leaves out then come from embeddedci.com when this computer is signed in, + else from the board's defaults.""" + try: + again = self.status() + except BenchPodError: + again = status + if not again.get("short_form"): + return again + _log.warning( + "the pod sent its short status over the network: its full status did not fit the connection. " + "The ADC calibration and the feature flags it leaves out come from embeddedci.com when " + "this computer is signed in, else from the board's defaults, so ADC readings can be " + "off. Firmware 3.10.9 keeps the full status small: update the pod (benchpod flash-self).") + return again + def refresh_capabilities(self) -> Capabilities: """Drop the cached capabilities and re-read them.""" self._caps = None diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 957920f..451877b 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -122,6 +122,7 @@ "dac_stop": "(self) -> 'None'", "decode": "(self, source: 'Union[LaCapture, Sequence[int]]', protocol: 'DecodeProtocol' = 'i2c', *, sample_rate_hz: 'Optional[float]' = None, **channels: 'Any') -> 'list'", "delete_wiring": "(self, name: 'str') -> 'None'", + "diag": "(self) -> 'Dict[str, Any]'", "disable_pulldown": "(self, *las: 'Union[Pin, int]') -> 'None'", "disable_pullup": "(self, *las: 'Union[Pin, int]') -> 'None'", "enable_pulldown": "(self, *las: 'Union[Pin, int]') -> 'None'", diff --git a/packages/embeddedci/tests/test_status_diag.py b/packages/embeddedci/tests/test_status_diag.py new file mode 100644 index 0000000..891c6e9 --- /dev/null +++ b/packages/embeddedci/tests/test_status_diag.py @@ -0,0 +1,124 @@ +"""bp.diag() and the short status over a direct connection (firmware 3.10.9 moved the diagnostics +out of status so its full form fits a connection's 2047-byte send buffer).""" +import json +import logging +import socket +import threading + +import pytest + +from embeddedci.benchpod.client import BenchPod +from embeddedci.benchpod.transport.tcp import TcpTransport + +FULL = {"device": "benchpod", "version": "3.10.9", "board": "stm32h563", "analog": True, + "board_rev": "v3r2", "adc_bits": 16, "adc_fullscale_mv": 4096, + "adc_cal_a_uv": 65678177, "adc_cal_b_nv": -1002109, "adc_cal_unwrap": True, + "ota_sig": True, "heap_free": 128000, "heap_min": 126000, "stack_min": 400, + "caps": ["gpio", "uart", "la"]} +SHORT = {k: v for k, v in FULL.items() if not k.startswith("adc_cal") and k != "ota_sig"} +SHORT["short_form"] = True +DIAG = {"heap_free": 128000, "heap_min": 126000, "stack_min": 400, "stacks": {"hw": 6992, "IDLE": 400}, + "lwip_mem_max": 12288, "lwip_mem_size": 65536, "pbuf_pool_max": 1, "pbuf_pool_size": 16, + "malloc_failures": 0, "rx_dropped": 0, "tx_dropped": 0, "board_rev_mv": 2728} + + +class FakePod: + """Answers status with the next entry of `statuses` (the last one repeats) and diag with DIAG, + or "unknown cmd" when has_diag is False.""" + + def __init__(self, statuses, has_diag=True): + self.statuses = list(statuses) + self.has_diag = has_diag + self.requests = [] + self._sock = socket.socket() + self._sock.bind(("127.0.0.1", 0)) + self._sock.listen(4) + self.addr = "127.0.0.1:%d" % self._sock.getsockname()[1] + self._stop = False + threading.Thread(target=self._serve, daemon=True).start() + + def _reply(self, req): + cmd = req.get("cmd") + if cmd == "status": + st = self.statuses.pop(0) if len(self.statuses) > 1 else self.statuses[0] + return {"status": "ok", "data": st} + if cmd == "diag" and self.has_diag: + return {"status": "ok", "data": DIAG} + if cmd == "ping": + return {"status": "ok", "data": {}} + return {"status": "error", "code": "BP0002", "args": {"cmd": cmd}, "message": "unknown cmd"} + + def _serve(self): + while not self._stop: + try: + conn, _ = self._sock.accept() + except OSError: + return + with conn: + buf = b"" + while True: + while b"\n" not in buf: + c = conn.recv(4096) + if not c: + break + buf += c + if b"\n" not in buf: + break + line, buf = buf.split(b"\n", 1) + req = json.loads(line) + self.requests.append(req) + conn.sendall(json.dumps(self._reply(req)).encode() + b"\n") + + def close(self): + self._stop = True + try: + self._sock.close() + except OSError: + pass + + +def _bp(pod): + return BenchPod(transport=TcpTransport(pod.addr, timeout=2), lease=False) + + +def test_diag_reads_the_diag_command(): + pod = FakePod([FULL]) + try: + d = _bp(pod).diag() + assert d["stacks"] == {"hw": 6992, "IDLE": 400} and d["lwip_mem_max"] == 12288 + assert pod.requests[-1]["cmd"] == "diag" + finally: + pod.close() + + +def test_diag_on_older_firmware_reads_status(): + old = dict(FULL, version="3.10.8", stacks={"hw": 7000}, lwip_mem_max=100) + pod = FakePod([old], has_diag=False) + try: + d = _bp(pod).diag() + assert d["stacks"] == {"hw": 7000} and d["lwip_mem_max"] == 100 and "version" not in d + finally: + pod.close() + + +def test_short_status_once_is_read_again(caplog): + """A busy send buffer can make one status the short form: the second read is whole, so the + calibration is the pod's and nothing is logged.""" + pod = FakePod([SHORT, FULL]) + try: + with caplog.at_level(logging.WARNING): + caps = _bp(pod).capabilities + assert caps.adc_affine is not None and abs(caps.adc_affine.b + 1.002109e-3) < 1e-9 + assert "short status" not in caplog.text + finally: + pod.close() + + +def test_short_status_over_lan_warns(caplog): + pod = FakePod([SHORT]) + try: + with caplog.at_level(logging.WARNING): + _bp(pod).capabilities + assert "short status over the network" in caplog.text and "3.10.9" in caplog.text + finally: + pod.close()