Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions packages/embeddedci/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/embeddedci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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(...)` |
Expand Down
2 changes: 1 addition & 1 deletion packages/embeddedci/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
44 changes: 44 additions & 0 deletions packages/embeddedci/src/embeddedci/benchpod/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions packages/embeddedci/tests/api_surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -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'",
Expand Down
124 changes: 124 additions & 0 deletions packages/embeddedci/tests/test_status_diag.py
Original file line number Diff line number Diff line change
@@ -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()