From d74f2bd6523e75ea8c77a9404d2f84efdd651202 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 09:45:53 -0600 Subject: [PATCH 1/2] Capabilities from the features table for firmware after 3.10.10 The SDK ships benchpod-firmware's features/features.json (feature_map.json, scripts/sync-feature-map.sh) and reads the pod's status with "caps":false. Firmware that answers with features_rev gets its features from the table (Capabilities.features, has(), fpga_image); older firmware ignores the argument and sends its caps list, read as before. supports() also takes table names without a flag (la_dir, i2c_master, diag, ...). A pod with a newer table than the SDK logs one warning to update the SDK. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/README.md | 13 +- .../src/embeddedci/benchpod/capabilities.py | 53 +- .../src/embeddedci/benchpod/client.py | 24 +- .../src/embeddedci/benchpod/feature_map.json | 627 ++++++++++++++++++ .../src/embeddedci/benchpod/feature_map.py | 112 ++++ .../src/embeddedci/benchpod/transport/base.py | 7 + .../embeddedci/benchpod/transport/serial.py | 3 + .../src/embeddedci/benchpod/transport/tcp.py | 3 + packages/embeddedci/tests/api_surface.json | 4 + packages/embeddedci/tests/test_feature_map.py | 141 ++++ scripts/sync-feature-map.sh | 14 + 11 files changed, 994 insertions(+), 7 deletions(-) create mode 100644 packages/embeddedci/src/embeddedci/benchpod/feature_map.json create mode 100644 packages/embeddedci/src/embeddedci/benchpod/feature_map.py create mode 100644 packages/embeddedci/tests/test_feature_map.py create mode 100755 scripts/sync-feature-map.sh diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index a198c8d..1b77e1f 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -374,7 +374,18 @@ properties `can_gpio`, `can_trigger`, `can_spi`, `can_profile_power`, `can_calib `can_current_out`, `can_reset_target` and `can_analog` name the common ones (`can_config` … `can_disable` stay the CAN bus commands). A call the pod cannot serve raises `UnsupportedFeatureError` (see [Errors](#errors)), before anything is sent when the capabilities -already say so: +already say so. + +Where those come from: firmware after 3.10.10 no longer lists its features. The SDK asks for its +`status` without the list (`"caps":false`) and gets `capabilities.features_rev`, the revision of +the features table the firmware is built from, plus the running image (`capabilities.fpga_image`) +and a few hardware facts. The SDK ships that table (`embeddedci.benchpod.feature_map`, a copy of +benchpod-firmware's `features/features.json`), so this needs no network: `capabilities.features` +is every feature the table gives the pod, and `bp.supports()` also takes table names without a +flag of their own (`"la_dir"`, `"i2c_master"`, `"diag"`, `"wiring_store"`, ...). Older firmware +sends its list as before and gets the same answers. A pod with a higher `features_rev` than the +SDK knows logs a warning once: update the SDK (`pip install -U embeddedci`) to use those features. + ```python import pytest diff --git a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py index 8548c12..7c17958 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py +++ b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py @@ -23,7 +23,9 @@ import re from dataclasses import dataclass, field -from typing import Any, Dict, Mapping, Optional, Tuple +from typing import Any, Dict, FrozenSet, Mapping, Optional, Tuple + +from . import feature_map as _feature_map # Built-in nominal front-end calibration per board — the affine fit ``volts = a + b*count`` # for boards whose analog front-end is inverting (so the naive count/full-scale model would @@ -205,6 +207,17 @@ class Capabilities: uart_hd: bool = False #: The running gateware version (``status`` ``gateware``); 0 when not reported. gateware: int = 0 + #: The features-table revision the pod's firmware is built from (``status`` with + #: ``"caps":false``, firmware after 3.10.10); 0 for older firmware, which sends a ``caps`` + #: list instead. + features_rev: int = 0 + #: With :attr:`features_rev`: every feature the table gives this pod + #: (:mod:`~embeddedci.benchpod.feature_map`), including ones with no flag here (``la_dir``, + #: ``i2c_master``, ``diag``, ...). Empty for older firmware. + features: FrozenSet[str] = frozenset() + #: The running gateware image: ``"loop"``, ``"deep"``, ``"emu"``, ``"unknown"``; ``""`` when the + #: firmware does not say. + fpga_image: str = "" #: The pod can calibrate its own ADC and keeps the result: :meth:`BenchPod.calibrate`. calibrate: bool = False #: ``calibrate`` also takes the DMM-guided forms (firmware 3.9.4+): this pod's own DAC line @@ -384,6 +397,13 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities": setattr(c, attr, True) if "analog" in names: c.analog = True + # Firmware after 3.10.10, asked with "caps":false: no list, the features table instead. + if (rev := _as_int(status, "features_rev")) is not None and rev > 0: + c.features_rev = rev + c.fpga_image = str(status.get("fpga_image", "") or "") + facts = _feature_map.facts_from_status(status) + c.features = _feature_map.resolve(rev, c.gateware, facts) + c._apply_features(facts) 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"))) @@ -392,6 +412,28 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities": c._apply_range(status) return c + def _apply_features(self, facts: Mapping[str, Any]) -> None: + """Set the flags of :attr:`features` (a table name is the flag's name, except the two + below) and the hardware facts.""" + for name in self.features: + attr = _TABLE_ALIASES.get(name, name) + if attr in _BOOL_FIELDS: + setattr(self, attr, True) + for fact in ("usb_cc", "pod_current", "nrst_pin"): + if facts.get(fact) is True: + setattr(self, fact, True) + + def has(self, feature: str) -> bool: + """Whether the pod has ``feature``: a table name (``"la_dir"``, ``"i2c_master"``, ...) + when the pod announced :attr:`features_rev`, else the flag of that name (older firmware).""" + if self.features_rev and feature in _feature_map.feature_map().get("features", {}): + return feature in self.features + if feature == "la_dir": + return self.la_dir + if feature in ("i2c_master", "spi_modes_1_2"): + return self.bus_master + return bool(getattr(self, _TABLE_ALIASES.get(feature, feature), False)) + def _apply_range(self, src: Mapping[str, Any], prefix: str = "") -> None: """The ADC input range the fit is for (firmware 3.9.5+).""" rng = src.get(prefix + "adc_range") @@ -525,12 +567,16 @@ def boot_warning(self) -> Optional[str]: def la_dir(self) -> bool: """The pod takes pin directions (``la_dir``, firmware 3.10.4+). False when the firmware version is unknown.""" + if self.features_rev: + return "la_dir" in self.features v = _version_tuple(self.firmware_version) return v is not None and v >= LA_DIR_FIRMWARE @property def bus_master(self) -> bool: """The I2C master, SPI modes 1 and 2 and send-and-capture (gateware v55+).""" + if self.features_rev: + return "i2c_master" in self.features return self.gateware >= BUS_MASTER_GATEWARE @property @@ -572,3 +618,8 @@ def merge(self, other: "Capabilities") -> "Capabilities": _FIELD_NAMES = tuple(f for f in Capabilities().__dict__.keys()) +_BOOL_FIELDS = frozenset(f for f, v in Capabilities().__dict__.items() if isinstance(v, bool)) + +#: Table names whose flag here has another name: the table's ``uart`` and ``la`` are the old +#: ``serial`` and ``analyzer`` flags. +_TABLE_ALIASES = {"uart": "serial", "la": "analyzer"} diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 913f5d5..11ca356 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -44,6 +44,7 @@ from . import dsp as _dsp from . import esp as _esp from . import expansion as _expansion +from . import feature_map as _feature_map from . import flash as _flash from . import i2c as _i2c from . import i2c_master as _i2c_master @@ -465,6 +466,12 @@ def status(self) -> Dict[str, Any]: """The pod's status report: firmware version, board, network and advertised features.""" return _dict(self._transport.status()) + def _caps_status(self) -> Dict[str, Any]: + """``status`` for the capabilities: without the ``caps`` list where the firmware has the + features table (:mod:`~embeddedci.benchpod.feature_map`).""" + read = getattr(self._transport, "status_without_caps", None) + return _dict(read() if callable(read) else 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, @@ -526,7 +533,7 @@ def capabilities(self) -> Capabilities: if self._caps is None: status_ok = True try: - status = self.status() + status = self._caps_status() except FirmwareError as exc: # Firmware 3.10.4's status can be too large for the cloud channel. Reading it again # will not help: use the server's capabilities alone, and keep them. @@ -538,6 +545,11 @@ def capabilities(self) -> Capabilities: if status_ok and status.get("short_form") and self._direct_network(): status = self._full_status(status) caps = Capabilities.from_status(status) + if caps.features_rev > _feature_map.revision(): + _log.warning( + "this pod's firmware has features this SDK does not know (features table " + "revision %d, the SDK has %d): update the SDK (pip install -U embeddedci) to use them", + caps.features_rev, _feature_map.revision()) api = self._try_server_api() if api is not None and self._device_name: try: @@ -563,7 +575,7 @@ def _full_status(self, status: Dict[str, Any]) -> Dict[str, Any]: 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() + again = self._caps_status() except BenchPodError: again = status if not again.get("short_form"): @@ -582,9 +594,11 @@ def refresh_capabilities(self) -> Capabilities: def supports(self, feature: str) -> bool: """Whether this pod has ``feature``, a :class:`Capabilities` flag (``"spi_master"``, - ``"capture_trigger"``, ``"can"``, ...). Reads the capabilities once; ``False`` for a - flag this SDK does not know. The ``can_*`` properties name the common ones.""" - return bool(getattr(self.capabilities, feature, False)) + ``"capture_trigger"``, ``"can"``, ...) or a name in the features table + (:mod:`~embeddedci.benchpod.feature_map`: ``"la_dir"``, ``"i2c_master"``, ``"diag"``, ...). + Reads the capabilities once; ``False`` for a name this SDK does not know. The ``can_*`` + properties name the common ones.""" + return self.capabilities.has(feature) @property def can_gpio(self) -> bool: diff --git a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json new file mode 100644 index 0000000..79163d6 --- /dev/null +++ b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json @@ -0,0 +1,627 @@ +{ + "_generated": "GENERATED by tools/gen_features.py from features/features.toml. DO NOT EDIT: edit the table.", + "schema": 1, + "revision": 1, + "table_sha256": "f614d1f34dbd3f7697945cf7a31c7fd1eefb820b7e7b7d695b6ba3045882d5f5", + "floor": "3.9.2", + "docs_base": "https://github.com/embeddedci-com/benchpod-firmware/blob/main/docs/", + "facts": { + "analog": { + "status": "analog", + "frame": "analog", + "legacy_caps": "analog" + }, + "nrst_pin": { + "status": "nrst_pin", + "frame": "nrst_pin", + "legacy_caps": "nrst_pin" + }, + "emu_image": { + "status": "sensors_digital", + "frame": "sensors_digital" + }, + "fpga_image": { + "status": "fpga_image", + "frame": "fpga_image" + }, + "wifi": { + "hw": "wifi", + "frame": "wifi_scan", + "legacy_caps": "wifi_scan" + }, + "usb_cc": { + "hw": "usb_cc", + "legacy_caps": "usb_cc" + }, + "pod_current": { + "hw": "pod_current", + "frame": "pod_current", + "legacy_caps": "pod_current" + }, + "adc_low_range": { + "hw": "adc_low_range", + "frame": "adc_low_range", + "legacy_caps": "adc_low_range" + } + }, + "releases": [ + { + "firmware": "3.9.2", + "gateware": 48, + "date": "2026-10-15" + }, + { + "firmware": "3.9.3", + "gateware": 48, + "date": "2026-10-19" + }, + { + "firmware": "3.9.4", + "gateware": 48, + "date": "2026-10-20" + }, + { + "firmware": "3.9.5", + "gateware": 49, + "date": "2026-10-31" + }, + { + "firmware": "3.9.6", + "gateware": 51, + "date": "2026-11-04" + }, + { + "firmware": "3.10.0", + "gateware": 53, + "date": "2026-11-08" + }, + { + "firmware": "3.10.1", + "gateware": 53, + "date": "2026-11-09" + }, + { + "firmware": "3.10.3", + "gateware": 54, + "date": "2026-11-13" + }, + { + "firmware": "3.10.4", + "gateware": 55, + "date": "2026-11-13" + }, + { + "firmware": "3.10.5", + "gateware": 55, + "date": "2026-11-14" + }, + { + "firmware": "3.10.6", + "gateware": 55, + "date": "2026-11-14" + }, + { + "firmware": "3.10.7", + "gateware": 55, + "date": "2026-11-16" + }, + { + "firmware": "3.10.8", + "gateware": 56, + "date": "2026-11-17" + }, + { + "firmware": "3.10.10", + "gateware": 56, + "date": "2026-11-17" + } + ], + "features": { + "gpio": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "gpio", + "docs": "API.md#gpio" + }, + "power": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "power", + "docs": "API.md#power" + }, + "swd": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "swd", + "docs": "API.md#swd" + }, + "uart": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "uart", + "docs": "API.md#uart_proxy_start" + }, + "la": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "la", + "docs": "API.md#la_capture" + }, + "analyzer": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "analyzer", + "legacy_frame": "analyzer" + }, + "command": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "command", + "legacy_frame": "command" + }, + "tunnel": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "tunnel", + "legacy_frame": "tunnel" + }, + "ota": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "ota", + "legacy_frame": "ota", + "docs": "API.md#ota_begin" + }, + "la_pins": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "la_pins", + "legacy_frame": "la_pins", + "docs": "API.md#la_pins" + }, + "power_profile": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "power_profile", + "legacy_frame": "power_profile", + "docs": "API.md#power_profile" + }, + "capture_b64": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "capture_b64", + "legacy_frame": "capture_b64", + "docs": "API.md#capture" + }, + "blob_slots": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "blob_slots" + }, + "can": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "can", + "legacy_frame": "can", + "docs": "API.md#can_config" + }, + "ota_sig": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "ota_sig" + }, + "sig_policy_cmd": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "sig_policy_cmd" + }, + "ws_auth_v2": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "ws_auth_v2" + }, + "lease_state": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "lease_state" + }, + "cloud_ca": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "cloud_ca" + }, + "cloud_proxy": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "cloud_proxy" + }, + "lan_policy_cmd": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "lan_policy_cmd" + }, + "tunnel_max_tier": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "tunnel_max_tier" + }, + "usb_net": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "usb_net", + "docs": "API.md#usb_network" + }, + "usb_net_setting": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "usb_net_setting", + "docs": "API.md#usb_network" + }, + "lan_tls": { + "rev": 1, + "firmware": "3.9.3", + "board": "any", + "legacy_caps": "lan_tls", + "legacy_frame": "lan_tls", + "docs": "API.md#lan_tls--the-lan-api-over-tls" + }, + "wifi_scan": { + "rev": 1, + "firmware": "3.9.4", + "board": "any", + "requires": [ + "wifi" + ], + "legacy_caps": "wifi_scan", + "legacy_frame": "wifi_scan", + "docs": "API.md#wifi_scan--the-networks-the-pods-wi-fi-sees" + }, + "sensors": { + "rev": 1, + "firmware": "3.10.3", + "board": "any", + "legacy_caps": "sensors", + "legacy_frame": "sensors", + "docs": "API.md#sensor_define" + }, + "sensors_format_1": { + "rev": 1, + "firmware": "3.10.3", + "board": "any", + "legacy_frame": "sensors_format" + }, + "sensor_la_trigger": { + "rev": 1, + "firmware": "3.10.4", + "board": "any", + "legacy_caps": "sensor_la_trigger", + "docs": "API.md#sensor_la" + }, + "can_fd": { + "rev": 1, + "firmware": "3.10.3", + "board": "any", + "legacy_caps": "can_fd", + "legacy_frame": "can_fd", + "docs": "API.md#can_config" + }, + "la_dir": { + "rev": 1, + "firmware": "3.10.4", + "board": "any", + "docs": "API.md#la_dir" + }, + "wiring_store": { + "rev": 1, + "firmware": "3.10.8", + "board": "any", + "legacy_frame": "wiring_store", + "docs": "API.md#wiring_list" + }, + "error_codes": { + "rev": 1, + "firmware": "3.10.8", + "board": "any", + "legacy_frame": "error_codes", + "docs": "https://embeddedci.com/docs/errors" + }, + "mac_fields": { + "rev": 1, + "firmware": "3.10.8", + "board": "any" + }, + "diag": { + "rev": 1, + "firmware": "3.10.10", + "board": "any", + "docs": "API.md#diag--heap-stack-and-network-diagnostics" + }, + "wiring_la_mv": { + "rev": 1, + "firmware": "3.10.10", + "board": "any" + }, + "gpio_read": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 35, + "board": "any", + "legacy_caps": "gpio_read", + "legacy_frame": "gpio_read", + "docs": "API.md#gpio_get" + }, + "capture_trigger": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 35, + "board": "any", + "legacy_caps": "capture_trigger", + "legacy_frame": "capture_trigger", + "docs": "API.md#capture" + }, + "spi_master": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 45, + "board": "any", + "legacy_caps": "spi_master", + "legacy_frame": "spi_master", + "docs": "API.md#spi_xfer" + }, + "spi_stream": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 45, + "board": "any", + "legacy_caps": "spi_stream", + "legacy_frame": "spi_stream", + "docs": "API.md#spi_stream" + }, + "la_rate_48mhz": { + "rev": 1, + "firmware": "3.9.6", + "gateware": 50, + "board": "any", + "legacy_frame": "la_max_rate_hz", + "docs": "API.md#la_capture--deep-raw-logic-analyzer-capture" + }, + "la_pretrigger": { + "rev": 1, + "firmware": "3.9.6", + "gateware": 50, + "board": "any", + "docs": "API.md#la_capture--deep-raw-logic-analyzer-capture" + }, + "i2c_master": { + "rev": 1, + "firmware": "3.10.4", + "gateware": 55, + "board": "any", + "docs": "API.md#i2c_start" + }, + "spi_modes_1_2": { + "rev": 1, + "firmware": "3.10.4", + "gateware": 55, + "board": "any", + "docs": "API.md#spi_xfer" + }, + "uart_frame": { + "rev": 1, + "firmware": "3.10.8", + "gateware": 56, + "board": "any", + "legacy_caps": "uart_frame", + "legacy_frame": "uart_frame", + "docs": "API.md#uart_proxy_start" + }, + "sensors_digital": { + "rev": 1, + "firmware": "3.10.3", + "gateware": 54, + "board": "any", + "requires": [ + "emu_image" + ], + "legacy_frame": "sensors_digital", + "docs": "API.md#sensor_start" + }, + "scope": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "scope", + "legacy_frame": "scope", + "docs": "API.md#capture" + }, + "dac": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "dac", + "legacy_frame": "dac", + "docs": "API.md#generate" + }, + "dac_dc": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "dac_dc", + "legacy_frame": "dac_dc", + "docs": "API.md#dac_out" + }, + "dac_replay": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "dac_replay", + "legacy_frame": "dac_replay", + "docs": "API.md#replay" + }, + "signal_alias": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "signal" + }, + "adc_cal_unwrap": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_frame": "adc_cal_unwrap" + }, + "dac_deep_replay": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 17, + "board": "analog", + "requires": [ + "fpga_image:deep" + ], + "legacy_caps": "dac_deep_replay", + "legacy_frame": "dac_deep_replay", + "docs": "API.md#replay" + }, + "dac_control_loop": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 23, + "board": "analog", + "requires": [ + "fpga_image:loop" + ], + "legacy_caps": "dac_control_loop", + "legacy_frame": "dac_control_loop", + "docs": "API.md#dac_loop" + }, + "dac_cotrig": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 27, + "board": "analog", + "legacy_caps": "dac_cotrig", + "legacy_frame": "dac_cotrig" + }, + "dac_loop_sources": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 29, + "board": "analog", + "legacy_caps": "dac_loop_sources", + "legacy_frame": "dac_loop_sources" + }, + "dac_loop_input_map": { + "rev": 1, + "firmware": "3.9.2", + "gateware": 30, + "board": "analog", + "legacy_caps": "dac_loop_input_map", + "legacy_frame": "dac_loop_input_map" + }, + "dac_limits": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "dac_limits", + "legacy_frame": "dac_limits", + "docs": "API.md#dac_limits" + }, + "calibrate": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "calibrate", + "legacy_frame": "calibrate", + "docs": "API.md#calibrate" + }, + "current_out": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "current_out", + "legacy_frame": "current_out", + "docs": "API.md#current_out--hold-a-current-on-the-4-20-ma-output-j9" + }, + "generate16": { + "rev": 1, + "firmware": "3.9.2", + "board": "analog", + "legacy_caps": "generate16", + "legacy_frame": "generate_bits", + "docs": "API.md#generate--dac-waveform-output" + }, + "cal_dmm": { + "rev": 1, + "firmware": "3.9.4", + "board": "analog", + "legacy_caps": "cal_dmm", + "legacy_frame": "cal_dmm", + "docs": "API.md#dmm-guided-calibration-firmware-394" + }, + "adc_low_range": { + "rev": 1, + "firmware": "3.9.5", + "board": "analog", + "requires": [ + "adc_low_range" + ], + "legacy_caps": "adc_low_range", + "legacy_frame": "adc_low_range", + "docs": "API.md#adc_range--the-adc-input-range-analog-module-v3r4" + }, + "gps": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "gps", + "legacy_frame": "gps", + "status": "retired" + }, + "sensor_types": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "sensor_types", + "legacy_frame": "sensor_types", + "status": "retired" + }, + "i2c_sensor": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_caps": "i2c_sensor", + "status": "retired" + }, + "serial": { + "rev": 1, + "firmware": "3.9.2", + "board": "any", + "legacy_frame": "serial", + "status": "retired" + } + } +} diff --git a/packages/embeddedci/src/embeddedci/benchpod/feature_map.py b/packages/embeddedci/src/embeddedci/benchpod/feature_map.py new file mode 100644 index 0000000..ed974fd --- /dev/null +++ b/packages/embeddedci/src/embeddedci/benchpod/feature_map.py @@ -0,0 +1,112 @@ +"""Which firmware and gateware have which BenchPod feature: the SDK's copy of the features table. + +``feature_map.json`` is benchpod-firmware's ``features/features.json`` (generated there from +``features/features.toml``; ``scripts/sync-feature-map.sh`` copies it here). It ships with the +SDK, so deciding what a pod can do needs no network connection. + +A pod with firmware after 3.10.10 answers ``{"cmd":"status","caps":false}`` with +``features_rev`` (the table revision it is built from), ``fpga_image`` and the ``hw`` facts +instead of the ``caps`` list. :func:`resolve` turns those into the set of features the pod has: +every entry with ``rev <= features_rev`` whose gateware, board and ``requires`` facts match. +Older firmware sends the ``caps`` list as before (:meth:`Capabilities.from_status` reads it). +""" + +from __future__ import annotations + +import json +import re +from functools import lru_cache +from importlib import resources +from typing import Any, Dict, FrozenSet, Mapping, Optional, Tuple + + +@lru_cache(maxsize=1) +def feature_map() -> Dict[str, Any]: + """The bundled table (``schema``, ``revision``, ``facts``, ``releases``, ``features``).""" + try: + text = resources.files(__package__).joinpath("feature_map.json").read_text("utf-8") + data = json.loads(text) + except (OSError, ValueError): + data = {} + if not isinstance(data, dict) or data.get("schema") != 1: + return {"schema": 1, "revision": 0, "facts": {}, "releases": [], "features": {}} + return data + + +def revision() -> int: + """The highest revision this SDK's table knows.""" + return int(feature_map().get("revision", 0) or 0) + + +def _version(v: Any) -> Optional[Tuple[int, int, int]]: + m = re.match(r"^v?(\d+)\.(\d+)\.(\d+)", str(v or "").strip()) + return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else None + + +def facts_from_status(status: Mapping[str, Any]) -> Dict[str, Any]: + """The table's facts from a ``status`` reply: the top-level fields each fact names + (``status``), and the ``hw`` list (``hw``). ``fpga_image`` is a string, the rest booleans.""" + hw = status.get("hw") + hw_names = {str(x).lower() for x in hw} if isinstance(hw, (list, tuple)) else set() + out: Dict[str, Any] = {} + for name, f in feature_map().get("facts", {}).items(): + if "status" in f and f["status"] in status: + v = status[f["status"]] + out[name] = v if name == "fpga_image" else v is True + elif "hw" in f: + out[name] = f["hw"] in hw_names + if "analog" not in out: + out["analog"] = True # firmware before the analog flag: every pod was an analog board + return out + + +def facts_from_frame(params: Mapping[str, Any], prefix: str = "") -> Dict[str, Any]: + """The facts from the cloud capabilities frame (or the server's ``cap.*`` map with + ``prefix="cap."``), where they are the fields each fact names as ``frame``.""" + out: Dict[str, Any] = {} + for name, f in feature_map().get("facts", {}).items(): + key = prefix + f["frame"] if "frame" in f else None + if key is None or key not in params: + continue + v = params[key] + out[name] = str(v) if name == "fpga_image" else str(v).strip().lower() in ("true", "1") + out.setdefault("analog", True) + return out + + +def _requires_ok(req: str, facts: Mapping[str, Any]) -> bool: + name, _, value = req.partition(":") + if value: + return str(facts.get(name, "")) == value + return facts.get(name) is True + + +def _board_ok(board: str, facts: Mapping[str, Any]) -> bool: + analog = facts.get("analog", True) is not False + return board == "any" or (board == "analog" and analog) or (board == "digital" and not analog) + + +def resolve(features_rev: int, gateware: int, facts: Mapping[str, Any]) -> FrozenSet[str]: + """The features of a pod that announced ``features_rev``, runs ``gateware`` (0 when not + known: gateware-gated features are left out) and has ``facts``.""" + out = set() + for name, e in feature_map().get("features", {}).items(): + if e.get("status") == "retired": + continue + if int(e.get("rev", 0)) > features_rev: + continue + if "gateware" in e and gateware < int(e["gateware"]): + continue + if not _board_ok(e.get("board", "any"), facts): + continue + if not all(_requires_ok(r, facts) for r in e.get("requires", [])): + continue + out.add(name) + return frozenset(out) + + +def first_firmware(feature: str) -> str: + """The first firmware release with ``feature`` (``"next"`` when not released yet, ``""`` for a + name the table does not have): for messages like "needs firmware 3.10.8".""" + e = feature_map().get("features", {}).get(feature) + return str(e.get("firmware", "")) if e else "" diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/base.py b/packages/embeddedci/src/embeddedci/benchpod/transport/base.py index 6bee6f1..b209dd3 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/base.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/base.py @@ -61,6 +61,13 @@ class Transport(ABC): def status(self) -> Any: """Return the pod's status report (a dict).""" + def status_without_caps(self) -> Any: + """The status report a client with the features table asks for: ``"caps":false``, so + firmware after 3.10.10 sends ``features_rev`` instead of the ``caps`` list (older firmware + ignores the argument and sends the list). A transport that cannot send it returns + :meth:`status`.""" + return self.status() + @abstractmethod def target_power(self, efuse: int, on: bool, delay_ms: int = 0) -> None: """Enable (``on=True``) or disable a target-power eFuse (1 or 2). diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py index ff9a5c4..000ee72 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py @@ -487,6 +487,9 @@ def _clean(raw: str, cmd: str) -> str: def status(self) -> Any: return self.command({"cmd": "status"}) + def status_without_caps(self) -> Any: + return self.command({"cmd": "status", "caps": False}) + def ping(self) -> Any: return self.command({"cmd": "ping"}) diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py index f4f8c9e..f3bbf44 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py @@ -403,6 +403,9 @@ def stage_psram(self, data: bytes) -> int: def status(self) -> Any: return self.command({"cmd": "status"}) + def status_without_caps(self) -> Any: + return self.command({"cmd": "status", "caps": False}) + def ping(self) -> Any: return self.command({"cmd": "ping"}) diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 93ce032..4eefcbc 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -318,6 +318,9 @@ "uart_frame", "uart_hd", "gateware", + "features_rev", + "features", + "fpga_image", "calibrate", "cal_dmm", "current_out", @@ -356,6 +359,7 @@ "counts_to_volts": "(self, count: 'float') -> 'float'", "from_parameters": "(cls, params: 'Mapping[str, Any]') -> \"'Capabilities'\"", "from_status": "(cls, status: 'Mapping[str, Any]') -> \"'Capabilities'\"", + "has": "(self, feature: 'str') -> 'bool'", "la_dir": "property", "merge": "(self, other: \"'Capabilities'\") -> \"'Capabilities'\"" }, diff --git a/packages/embeddedci/tests/test_feature_map.py b/packages/embeddedci/tests/test_feature_map.py new file mode 100644 index 0000000..3db0166 --- /dev/null +++ b/packages/embeddedci/tests/test_feature_map.py @@ -0,0 +1,141 @@ +"""The features table (feature_map.json, benchpod-firmware's features/features.json): what a pod +that sends features_rev can do, and that it matches what the caps list said before.""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +from typing import Any, Dict, List + +import pytest + +from embeddedci.benchpod import feature_map +from embeddedci.benchpod.capabilities import Capabilities +from embeddedci.benchpod.client import BenchPod + +# A 3.10.10 analog pod on the loop image and gateware 56, as its plain status lists it +# (cloud_caps_emit_list). +LEGACY_LIST = [ + "signal", "gpio", "power", "swd", "uart", "la", "analyzer", "command", "tunnel", "ota", + "la_pins", "power_profile", "capture_b64", "can", "can_fd", "sensors", "sensor_la_trigger", + "usb_net", "usb_net_setting", "lan_tls", "wifi_scan", "pod_current", "adc_low_range", "analog", + "scope", "dac_limits", "calibrate", "cal_dmm", "current_out", "dac", "dac_dc", "dac_replay", + "dac_control_loop", "dac_cotrig", "generate16", "dac_loop_sources", "dac_loop_input_map", + "gpio_read", "capture_trigger", "spi_master", "spi_stream", "uart_frame", "nrst_pin", "usb_cc", +] +TOP = {"version": "3.10.10", "board": "stm32h563", "analog": True, "nrst_pin": True, + "gateware": 56, "sensors_digital": True, "ota_sig": True, "sig_policy_cmd": True, + "lan_policy_cmd": True, "tunnel_max_tier": True, "lease_state": True, "cloud_ca": True, + "cloud_proxy": True} +NEW_FACTS = {"features_rev": 1, "fpga_image": "loop", + "hw": ["wifi", "usb_cc", "pod_current", "adc_low_range"]} + +# Flags the old list never carried (frame only, or not at all) that the table now gives. +TABLE_ONLY = {"blob_slots", "ws_auth_v2"} + + +def _flags(c: Capabilities) -> Dict[str, bool]: + return {k: v for k, v in vars(c).items() if isinstance(v, bool)} + + +def test_table_matches_the_old_list(): + old = Capabilities.from_status({**TOP, "caps": LEGACY_LIST}) + new = Capabilities.from_status({**TOP, **NEW_FACTS}) + assert old.features_rev == 0 and new.features_rev == 1 + lost = sorted(k for k, v in _flags(old).items() if v and not getattr(new, k)) + gained = sorted(k for k, v in _flags(new).items() if v and not getattr(old, k)) + assert lost == [], f"the table lost {lost}" + assert set(gained) <= TABLE_ONLY, f"the table gave more than expected: {gained}" + assert new.fpga_image == "loop" + assert {"la_dir", "i2c_master", "diag", "wiring_store", "error_codes"} <= new.features + + +def test_image_and_gateware_decide(): + deep = Capabilities.from_status({**TOP, **NEW_FACTS, "fpga_image": "deep"}) + assert deep.dac_deep_replay and not deep.dac_control_loop + old_gw = Capabilities.from_status({**TOP, **NEW_FACTS, "gateware": 55}) + assert not old_gw.uart_frame and old_gw.spi_master and old_gw.bus_master + unknown = Capabilities.from_status({**TOP, **NEW_FACTS, "gateware": 0}) + assert not unknown.gpio_read and not unknown.spi_master and unknown.can_fd + + +def test_digital_board(): + c = Capabilities.from_status({**TOP, **NEW_FACTS, "analog": False, "nrst_pin": False, + "hw": [], "sensors_digital": False}) + assert c.analog is False + assert not (c.dac or c.scope or c.calibrate or c.current_out) + assert not c.usb_cc and not c.pod_current and not c.adc_low_range and not c.sensors_digital + assert "wifi_scan" not in c.features and "gpio_read" in c.features + + +def test_rev_above_the_pod(monkeypatch): + table = json.loads(json.dumps(feature_map.feature_map())) + table["features"]["future_thing"] = {"rev": 2, "firmware": "next", "board": "any"} + table["revision"] = 2 + monkeypatch.setattr(feature_map, "feature_map", lambda: table) + assert "future_thing" not in feature_map.resolve(1, 56, {"analog": True}) + assert "future_thing" in feature_map.resolve(2, 56, {"analog": True}) + + +def test_has_names_without_a_flag(): + new = Capabilities.from_status({**TOP, **NEW_FACTS, "version": "3.10.10"}) + assert new.has("la_dir") and new.has("diag") and new.has("can_fd") and not new.has("nope") + old = Capabilities.from_status({**TOP, "version": "3.10.3", "gateware": 54, "caps": ["la"]}) + assert not old.has("la_dir") and not old.has("i2c_master") + assert Capabilities.from_status({**TOP, "version": "3.10.4", "caps": []}).has("la_dir") + + +def test_first_firmware(): + assert feature_map.first_firmware("uart_frame") == "3.10.8" + assert feature_map.first_firmware("no_such_feature") == "" + + +class _Pod: + """A LAN pod: answers status with or without the caps list.""" + + def __init__(self, new_firmware: bool) -> None: + self.new = new_firmware + self.requests: List[dict] = [] + self.timeout = 30.0 + + def status(self) -> Dict[str, Any]: + return self.command({"cmd": "status"}) + + def status_without_caps(self) -> Dict[str, Any]: + return self.command({"cmd": "status", "caps": False}) + + def command(self, req: dict) -> Any: + self.requests.append(req) + if req["cmd"] != "status": + return {} + if self.new and req.get("caps") is False: + return {**TOP, **NEW_FACTS} + return {**TOP, "caps": LEGACY_LIST} # old firmware ignores "caps" + + def ping(self) -> Any: + return "pong" + + def close(self) -> None: + pass + + +@pytest.mark.parametrize("new_firmware", [True, False]) +def test_client_asks_without_the_list(new_firmware): + pod = _Pod(new_firmware) + bp = BenchPod(transport=pod, lease=False, api_key="", api_base="") + assert bp.supports("uart_frame") and bp.supports("spi_master") + assert {"cmd": "status", "caps": False} in pod.requests + assert bp.capabilities.features_rev == (1 if new_firmware else 0) + assert bp.supports("la_dir") + + +def test_bundled_copy_matches_the_firmware(): + """The bundled feature_map.json is benchpod-firmware's features/features.json, byte for byte + (scripts/sync-feature-map.sh), when that checkout is next to this repository.""" + fw = os.environ.get("BENCHPOD_FIRMWARE_DIR") or str(Path(__file__).resolve().parents[3] / ".." / "benchpod-firmware") + src = Path(fw) / "features" / "features.json" + if not src.exists(): + pytest.skip(f"no {src}") + bundled = Path(feature_map.__file__).with_name("feature_map.json") + assert bundled.read_bytes() == src.read_bytes(), "run scripts/sync-feature-map.sh" diff --git a/scripts/sync-feature-map.sh b/scripts/sync-feature-map.sh new file mode 100755 index 0000000..605e97e --- /dev/null +++ b/scripts/sync-feature-map.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# Copy the BenchPod features table (features/features.json, generated in benchpod-firmware from +# features/features.toml) into the SDK, which decides from it what a pod with features_rev can do. +# +# scripts/sync-feature-map.sh [path/to/benchpod-firmware] # default: ../benchpod-firmware +set -euo pipefail +here="$(cd "$(dirname "$0")/.." && pwd)" +fw="${1:-$here/../benchpod-firmware}" +src="$fw/features/features.json" +dst="$here/packages/embeddedci/src/embeddedci/benchpod/feature_map.json" +[ -f "$src" ] || { echo "sync-feature-map: no $src (pass the benchpod-firmware checkout)" >&2; exit 1; } +python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); assert d["schema"]==1 and d["features"]' "$src" +cp "$src" "$dst" +python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); print("sync-feature-map:", len(d["features"]), "features, revision", d["revision"], "table", d["table_sha256"][:12])' "$dst" From 0171afa5b9913877127c0c21b7a90c4f2e5a7492 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 10:03:00 -0600 Subject: [PATCH 2/2] feature_map.json: uart_hd from the table (benchpod-firmware#162) Co-Authored-By: Claude Opus 5.5 --- .../embeddedci/src/embeddedci/benchpod/feature_map.json | 9 ++++++++- packages/embeddedci/tests/test_feature_map.py | 2 ++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json index 79163d6..7872b35 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json +++ b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json @@ -2,7 +2,7 @@ "_generated": "GENERATED by tools/gen_features.py from features/features.toml. DO NOT EDIT: edit the table.", "schema": 1, "revision": 1, - "table_sha256": "f614d1f34dbd3f7697945cf7a31c7fd1eefb820b7e7b7d695b6ba3045882d5f5", + "table_sha256": "5b64c07e36263d775a2f06d20833db87023055edced5958ee4bc5d17aa29855f", "floor": "3.9.2", "docs_base": "https://github.com/embeddedci-com/benchpod-firmware/blob/main/docs/", "facts": { @@ -439,6 +439,13 @@ "legacy_frame": "uart_frame", "docs": "API.md#uart_proxy_start" }, + "uart_hd": { + "rev": 1, + "firmware": "next", + "gateware": 57, + "board": "any", + "docs": "API.md#uart_proxy_start--transparent-uart-bridge" + }, "sensors_digital": { "rev": 1, "firmware": "3.10.3", diff --git a/packages/embeddedci/tests/test_feature_map.py b/packages/embeddedci/tests/test_feature_map.py index 3db0166..ea4dbfa 100644 --- a/packages/embeddedci/tests/test_feature_map.py +++ b/packages/embeddedci/tests/test_feature_map.py @@ -56,6 +56,8 @@ def test_image_and_gateware_decide(): assert deep.dac_deep_replay and not deep.dac_control_loop old_gw = Capabilities.from_status({**TOP, **NEW_FACTS, "gateware": 55}) assert not old_gw.uart_frame and old_gw.spi_master and old_gw.bus_master + hd = Capabilities.from_status({**TOP, **NEW_FACTS, "gateware": 57}) + assert hd.uart_hd and not Capabilities.from_status({**TOP, **NEW_FACTS}).uart_hd unknown = Capabilities.from_status({**TOP, **NEW_FACTS, "gateware": 0}) assert not unknown.gpio_read and not unknown.spi_master and unknown.can_fd