From b2c25a3325dd9a794adb01334cdc42a0631b49df Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 22:40:16 -0600 Subject: [PATCH 1/4] Digital board v3r4: 5 V I/O, pin 21, pull strength (SDK + MCP) SDK: set_la_voltage(5.0) on a pod with the la_5v feature (the bank stays at 3.3 V, J1 pin 21 goes to 5 V); other pods get ValueError before anything is sent. Wiring la_mv takes 5000. LaVoltage.pin21 (new Pin21) reports pin 21's source, setting, measured voltage and state on v3r4. Capabilities.vref_out is the hardware fact. PullState.strength reports what the pod picked; la_pins() takes the reply's pull_dirs. No new parameters: the pod picks the strength. MCP: set_la_voltage takes 5.0 and an omitted voltage (read only) and returns pin21; connect and --la-voltage take 5.0; capabilities has vref_out; pull channels have strength. Feature map (revision 7) and error catalog (BP0028, BP0029) synced from benchpod-firmware#178. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/CHANGELOG.md | 5 + .../src/embeddedci_mcp/__main__.py | 2 +- .../src/embeddedci_mcp/models.py | 21 ++- .../src/embeddedci_mcp/server.py | 42 +++-- packages/embeddedci-mcp/tests/test_e2e_mcp.py | 7 +- packages/embeddedci-mcp/tests/test_tools.py | 5 +- .../embeddedci-mcp/tests/tools_surface.json | 30 ++-- packages/embeddedci/CHANGELOG.md | 9 ++ packages/embeddedci/README.md | 35 ++++- .../src/embeddedci/benchpod/capabilities.py | 5 +- .../src/embeddedci/benchpod/client.py | 31 +++- .../src/embeddedci/benchpod/constants.py | 3 + .../src/embeddedci/benchpod/gpio.py | 8 +- .../src/embeddedci/benchpod/state.py | 47 +++++- .../src/embeddedci/benchpod/wiring.py | 5 +- packages/embeddedci/tests/api_surface.json | 5 +- .../embeddedci/tests/test_digital_v3r4.py | 147 ++++++++++++++++++ packages/embeddedci/tests/test_wiring.py | 2 +- 18 files changed, 365 insertions(+), 44 deletions(-) create mode 100644 packages/embeddedci/tests/test_digital_v3r4.py diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index 1177cc6..1b6ca6a 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -2,6 +2,11 @@ ## 3.0.5 +- **Digital board v3r4:** `set_la_voltage` takes `5.0` (and `connect` `la_voltage=5.0`, the + `--la-voltage` flag too) on a pod with 5 V I/O, and `voltage` may be omitted to read the voltage + without changing it. The result has `pin21` (source, setting, measured, state, up) there; the + tool tells the agent what `high` means. `capabilities` has `vref_out`; `pull_status` and + `set_pull` channels have `strength`. - `adc_read` on `current_in` returns `sense_ohms`, the resistance the loop current was computed with: 249 ohm up to analog module v3r4, about 100 ohm from v3r5 (firmware 3.10.13+), which also reads `current_in` in the low range by default. The guide explains the 30 mA limiter. diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py b/packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py index 8f12a06..0aeae14 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py @@ -39,7 +39,7 @@ def build_parser() -> argparse.ArgumentParser: parser.add_argument("--connection", default=None, help="Default connection for the connect tool: host[:port], a serial device, " "'usb', 'usb:', or 'embeddedci:'. Falls back to BENCHPOD_CONNECTION.") - parser.add_argument("--la-voltage", type=float, choices=[1.8, 3.3], default=None, + parser.add_argument("--la-voltage", type=float, choices=[1.8, 3.3, 5.0], default=None, help="LA I/O voltage applied on connect. Falls back to BENCHPOD_LA_VOLTAGE.") parser.add_argument("--wiring-autosave", action="store_true", default=os.environ.get("BENCHPOD_WIRING_AUTOSAVE", "").strip().lower() in ("1", "true", "yes", "on"), diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index 5e9c29d..5b7dd7b 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -49,7 +49,7 @@ class InputMapSpec(BaseModel): class CapabilitiesInfo(BaseModel): board: str = "" - board_rev: str = Field("", description="PCB revision: v2, v3 or unknown.") + board_rev: str = Field("", description="PCB revision: v2, v3, v3r2, v3r4 (digital board v3r4) or unknown.") firmware_version: str = "" adc_bits: int = 0 scope: bool = False @@ -67,6 +67,9 @@ class CapabilitiesInfo(BaseModel): power_profile: bool = Field(False, description="Power profiles (measure_power, power_profile_start).") nrst_pin: bool = Field(False, description="Dedicated target-reset pin (reset_target, flash nreset).") usb_cc: bool = Field(False, description='USB-C CC monitoring (command {"cmd": "usb_cc"}).') + vref_out: bool = Field(False, description=( + "Digital board v3r4: J1 pin 21 is switched and measured, 5 V I/O (set_la_voltage 5.0), and every " + "channel's pull goes up or down with a strength the pod picks.")) calibrate: bool = Field(False, description="The pod calibrates its own ADC offset on the 4-20 mA input (calibrate, calibration).") current_out: bool = Field(False, description=( "4-20 mA output on terminal J9 (current_out, and dac_path current_out on generate and replay).")) @@ -139,9 +142,23 @@ class StatusResult(BaseModel): "web UI's Wiring tab shows it), file (BENCHPOD_WIRING), dict (set_wiring) or defaults.")) +class Pin21Result(BaseModel): + """J1 pin 21 on digital v3r4: the rail the pull-ups pull to.""" + + source: str = Field(description="bank (follows the I/O bank, 1.8 or 3.3 V) or 5v.") + setting: float = Field(description="What pin 21 should be, volts.") + measured: Optional[float] = Field(None, description="What the pod measures, volts.") + state: str = Field(description=( + "ok; high: more than 0.2 V above its setting, a DUT signal above the I/O voltage lifts it " + "through the pulls (tell the user to select 5 V or remove the signal); low: overloaded, or 5 V " + "did not come up; short: shorted or held down, the pulls are off; unknown: no reading yet.")) + up: bool = Field(description="High enough for the pull resistors to work.") + + class LaVoltageResult(BaseModel): voltage: Optional[float] readback: Optional[float] = None + pin21: Optional[Pin21Result] = Field(None, description="Digital v3r4 only: J1 pin 21.") # -- wiring profile ---------------------------------------------------------------- @@ -549,6 +566,8 @@ class PullChannel(BaseModel): direction: Optional[str] ohms: str available: bool + #: Digital v3r4: 10k, 2.2k or both (about 1.8k), none when off; picked from the pin's function. + strength: Optional[str] = None class PullStatusResult(BaseModel): diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index 3dba1b9..be4a15e 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -478,8 +478,9 @@ async def connect( "'discover' (mDNS) or 'embeddedci:' (cloud). Omit to use the server default " "(--connection, else BENCHPOD_CONNECTION, else the connection saved with `benchpod " "set-connection`), else to find the one pod on the LAN over mDNS."))] = None, - la_voltage: Annotated[Optional[Literal[1.8, 3.3]], Field(description=( - "Select the LA I/O-bank voltage right after connecting (the DUT's I/O voltage)."))] = None, + la_voltage: Annotated[Optional[Literal[1.8, 3.3, 5.0]], Field(description=( + "Select the LA I/O-bank voltage right after connecting (the DUT's I/O voltage; 5.0 needs the " + "digital board v3r4)."))] = None, lease_wait: Annotated[float, Field(ge=0, le=3600, description=( "Seconds to wait when someone else holds the pod's lease (the cloud device's, or the " "pod's own on the LAN and USB network)."))] = 30.0, @@ -519,16 +520,35 @@ async def status() -> m.StatusResult: return await _call(_status) +def _pin21(state: Any) -> Optional[m.Pin21Result]: + p = getattr(state, "pin21", None) # embeddedci before digital v3r4 support has none + if p is None: + return None + return m.Pin21Result(source=p.source, setting=p.setting, measured=p.measured, state=p.state, up=p.up) + + @mcp.tool(annotations=_ann("Set LA I/O voltage", idempotent=True)) -async def set_la_voltage(voltage: Literal[1.8, 3.3]) -> m.LaVoltageResult: - """Select the LA I/O-bank voltage to match the DUT's I/O (1.8 V needs a rev3 pod). +async def set_la_voltage(voltage: Annotated[Optional[Literal[1.8, 3.3, 5.0]], Field(description=( + "The DUT's I/O voltage. 5.0 needs a pod with the digital board v3r4 (status capabilities " + "vref_out). Omit it to read the current voltage and pin 21 without changing anything."))] = None, +) -> m.LaVoltageResult: + """Select the LA I/O-bank voltage to match the DUT's I/O (1.8 V needs a rev3 pod, 5.0 a digital + v3r4 board). Usually not needed: connect sets it from the wiring profile's la_mv, and firmware 3.10.10+ takes it from the profile on the first LA operation. Call it when the profile sets none (ask the user), or to override the profile for this session. + + At 5.0 the pod reads 5 V signals at full speed, and its outputs reach 5 V only through their + pull-ups: switch on the pull-up (set_pull up) on outputs into 5 V CMOS-level inputs. On digital + v3r4 the result has pin21; when its state is high, tell the user a DUT signal is above the I/O + voltage (select 5.0 or remove the signal). """ - state = await _call(lambda: SESSION.require().set_la_voltage(voltage)) - return m.LaVoltageResult(voltage=state.voltage, readback=state.readback) + if voltage is None: + state = await _call(lambda: SESSION.require().get_la_voltage()) + else: + state = await _call(lambda: SESSION.require().set_la_voltage(voltage)) + return m.LaVoltageResult(voltage=state.voltage, readback=state.readback, pin21=_pin21(state)) # -- wiring profile ------------------------------------------------------------------- @@ -1644,7 +1664,8 @@ def _pull(state: Any) -> m.PullChannel: supported = (direction,) if direction in ("up", "down") else () return m.PullChannel(la=state.la, state=getattr(state, "state", direction if state.enabled else "off"), supported=list(supported), enabled=state.enabled, direction=direction, - ohms=state.ohms, available=state.available) + ohms=state.ohms, available=state.available, + strength=getattr(state, "strength", None)) def _sdk_pulls_by_direction(pod: Any) -> bool: @@ -1672,9 +1693,10 @@ def _set_pull_old_sdk(pod: Any, la: int, want: Any) -> Any: async def set_pull( las: Annotated[List[PullPin], Field(min_length=1, max_length=14, description="LA channels (1-14).")], pull: Annotated[Optional[Literal["up", "down", "off"]], Field(description=( - "The direction: up, down or off. The pod picks the resistor (ohms in the result). A channel " - "pulls only the ways its resistor allows (pull_status: supported); today LA1-LA6 pull up, " - "LA7/LA8 down, LA9-LA14 have none, and the pod refuses the rest (BP0024, BP0023)."))] = None, + "The direction: up, down or off. The pod picks the resistor from the pin's function (ohms and " + "strength in the result). A channel pulls only the ways its resistor allows (pull_status: " + "supported): on the digital board v3r4 every channel pulls up or down; on older boards LA1-LA6 " + "pull up, LA7/LA8 down, LA9-LA14 have none, and the pod refuses the rest (BP0024, BP0023)."))] = None, enabled: Annotated[Optional[bool], Field(description=( "Older form, use pull: true engages each channel's own direction, false is off."))] = None, ) -> m.PullStatusResult: diff --git a/packages/embeddedci-mcp/tests/test_e2e_mcp.py b/packages/embeddedci-mcp/tests/test_e2e_mcp.py index cce45ff..4e01cb8 100644 --- a/packages/embeddedci-mcp/tests/test_e2e_mcp.py +++ b/packages/embeddedci-mcp/tests/test_e2e_mcp.py @@ -267,9 +267,12 @@ def test_rev3_tools(connected): if not connected["firmware"].get("nrst_pin"): pytest.skip("not a rev3 pod") caps = connected["capabilities"] - assert caps["board_rev"] in ("v3", "v3r2") and caps["nrst_pin"] and caps["usb_cc"], caps + assert caps["board_rev"] in ("v3", "v3r2", "v3r4") and caps["nrst_pin"] and caps["usb_cc"], caps try: - assert call("set_la_voltage", voltage=1.8) == {"voltage": 1.8, "readback": 1.8} + r = call("set_la_voltage", voltage=1.8) + assert (r["voltage"], r["readback"]) == (1.8, 1.8), r + # pin 21 only on digital v3r4, where it follows the bank to 1.8 V + assert (r.get("pin21") is None) == (not caps.get("vref_out")), r finally: assert call("set_la_voltage", voltage=3.3)["readback"] == 3.3 try: diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index 182f94c..332c2c8 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -86,7 +86,8 @@ def test_enums_reach_the_schema(): tools = {t.name: t for t in anyio.run(mcp.list_tools)} assert tools["analog_path"].inputSchema["properties"]["path"]["enum"][0] == "off" - assert tools["set_la_voltage"].inputSchema["properties"]["voltage"]["enum"] == [1.8, 3.3] + # optional since digital v3r4 (omitted = read); 5.0 is the v3r4 5 V mode + assert tools["set_la_voltage"].inputSchema["properties"]["voltage"]["anyOf"][0]["enum"] == [1.8, 3.3, 5.0] # -- errors + connection --------------------------------------------------------------- @@ -598,7 +599,7 @@ def test_pulls(connected): return assert [c["la"] for c in status["channels"]] == list(range(1, 15)) assert status["channels"][8] == {"la": 9, "state": "off", "supported": [], "enabled": False, - "direction": None, "ohms": "", "available": True} + "direction": None, "ohms": "", "available": True, "strength": None} with pytest.raises(ToolError, match="BP0023"): call("set_pull", las=[9], pull="up") with pytest.raises(ToolError, match="LA7 supports pull-down only on this board"): diff --git a/packages/embeddedci-mcp/tests/tools_surface.json b/packages/embeddedci-mcp/tests/tools_surface.json index fb3dbda..bd70962 100644 --- a/packages/embeddedci-mcp/tests/tools_surface.json +++ b/packages/embeddedci-mcp/tests/tools_surface.json @@ -1541,7 +1541,8 @@ { "enum": [ 1.8, - 3.3 + 3.3, + 5.0 ], "type": "number" }, @@ -1550,7 +1551,7 @@ } ], "default": null, - "description": "Select the LA I/O-bank voltage right after connecting (the DUT's I/O voltage).", + "description": "Select the LA I/O-bank voltage right after connecting (the DUT's I/O voltage; 5.0 needs the digital board v3r4).", "title": "La Voltage" }, "lease_wait": { @@ -5101,17 +5102,24 @@ "input": { "properties": { "voltage": { - "enum": [ - 1.8, - 3.3 + "anyOf": [ + { + "enum": [ + 1.8, + 3.3, + 5.0 + ], + "type": "number" + }, + { + "type": "null" + } ], - "title": "Voltage", - "type": "number" + "default": null, + "description": "The DUT's I/O voltage. 5.0 needs a pod with the digital board v3r4 (status capabilities vref_out). Omit it to read the current voltage and pin 21 without changing anything.", + "title": "Voltage" } }, - "required": [ - "voltage" - ], "title": "set_la_voltageArguments", "type": "object" } @@ -5166,7 +5174,7 @@ } ], "default": null, - "description": "The direction: up, down or off. The pod picks the resistor (ohms in the result). A channel pulls only the ways its resistor allows (pull_status: supported); today LA1-LA6 pull up, LA7/LA8 down, LA9-LA14 have none, and the pod refuses the rest (BP0024, BP0023).", + "description": "The direction: up, down or off. The pod picks the resistor from the pin's function (ohms and strength in the result). A channel pulls only the ways its resistor allows (pull_status: supported): on the digital board v3r4 every channel pulls up or down; on older boards LA1-LA6 pull up, LA7/LA8 down, LA9-LA14 have none, and the pod refuses the rest (BP0024, BP0023).", "title": "Pull" } }, diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index c1cc17b..e892196 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -2,6 +2,15 @@ ## 3.0.5 +- **Digital board v3r4:** `set_la_voltage(5.0)` (and `la_mv: 5000` in a wiring profile) on a pod + with the `la_5v` feature: the bank stays at 3.3 V, J1 pin 21 (the pull-up rail) goes to 5 V; other + pods raise `ValueError` before anything is sent. `LaVoltage.pin21` (new `Pin21`: `source`, + `setting`, `measured`, `state`, `up`, `ok`) reports pin 21 there, `None` elsewhere. + `Capabilities.vref_out` is the hardware fact. `PullState.strength` reports the resistors the pod + picked (`10k`, `2.2k`, `both`, `none`); every channel pulls up or down there, and `la_pins()` takes + the reply's `pull_dirs`. No new parameters: the pod picks the strength from the pin's function. + Error catalog `BP0028` (5 V did not come up) and `BP0029` (pin 21 is down); features table + revision 7 (`la_5v`, `la_pull_strength`). - **4-20 mA input on analog module v3r5** (firmware 3.10.13+): the sense resistor is 100 Ω (249 Ω up to v3r4). `AdcReading.sense_ohms` and `Calibration.sense_ohms` give the resistance the pod converts with, and `capture_adc(source="current_in")` uses it for `currents` (249 Ω when the diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 8a3e519..570304f 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -170,6 +170,24 @@ the wiring profile sets no I/O voltage: set la_mv in it (bp.save_wiring(bp.wirin 1800 for a 1.8 V board), or pass BenchPod(conn, la_voltage=3.3), or call bp.set_la_voltage(3.3)` (prefixed with the command, as every `FirmwareError` is). +**5 V I/O (digital board v3r4).** On a pod with the digital board v3r4 (`bp.supports("la_5v")`, +`bp.capabilities.vref_out`), `bp.set_la_voltage(5.0)` (or `la_mv: 5000` in the profile) keeps the +bank at 3.3 V and switches J1 pin 21, the rail every pull-up pulls to, to 5 V. The pod reads 5 V +signals at full speed; its outputs reach 5 V only through their pull-ups, so switch the pull-up on +for outputs into 5 V CMOS-level inputs (`bp.set_pull(la, "up")`). The pod checks pin 21 and raises +`FirmwareError` `BP0028` when 5 V did not come up (a weak USB supply). Other pods raise +`ValueError` before anything is sent. On v3r4, `LaVoltage.pin21` reports pin 21 (`None` elsewhere): + +```python +st = bp.get_la_voltage() +if st.pin21 and st.pin21.state == "high": + # a DUT signal above the I/O voltage lifts pin 21 through the pulls: select 5 V or remove it + print(f"pin 21 at {st.pin21.measured} V, set to {st.pin21.setting} V") +``` + +`Pin21` has `source` (`"bank"` or `"5v"`), `setting` and `measured` (volts), `state` (`"ok"`, +`"high"`, `"low"`, `"short"` or `"unknown"`), `up` (high enough for the pulls) and `ok`. + Other constructor arguments: `timeout` (seconds, default 30), `api_key`, `api_base`, `cloud_token`, `cloud_audience`, `cloud_user_token`, `lease`, `lease_wait`, `lease_ttl` (see [Cloud](#cloud-embeddedcidevice-name)), `wiring` and `wiring_source` (see [Wiring profile](#wiring-profile)) and `transport` (inject a @@ -1194,6 +1212,14 @@ value. Which channels have one and which way each can pull depends on the board, The resistors are referenced to 3V3, so the pod won't engage one while the LA bank is at 1.8 V (`PullState.available` is false). +**Digital board v3r4** (`bp.supports("la_pull_strength")`): every channel, LA1–LA14, pulls up or +down with a 10k, a 2.2k or both (about 1.8k). You still name only the direction: the pod picks the +strength from the pin's function (2.2k for I2C, one-wire UART, open drain, and pod outputs in 5 V +mode; 10k otherwise), and `PullState.strength` says which (`"10k"`, `"2.2k"`, `"both"`, `"none"` +when off). The pull-ups go to J1 pin 21, so they work at 1.8, 3.3 and 5 V. While pin 21 is down +(shorted or held down) the pod turns every pull off and refuses new ones with `BP0029`; when the +pod switches the DUT's power off, the pull-ups stay off until a rail is on again or you set a pull. + ```python from embeddedci.benchpod import PIN1, PIN2, PIN7 @@ -2514,7 +2540,8 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen | Type | Returned by / used for | Fields and members | |---|---|---| -| `LaVoltage` | `get_la_voltage`, `set_la_voltage` | `voltage`, `readback`, `is_set` | +| `LaVoltage` | `get_la_voltage`, `set_la_voltage` | `voltage`, `readback`, `is_set`, `pin21` (a `Pin21`, digital v3r4 only) | +| `Pin21` | `LaVoltage.pin21` | `source`, `setting`, `measured` (V), `state`, `up`, `ok` | | `TargetStatus` | `target_status` | `internal`, `external` (each an `EfuseState`), `supported`, `efuse(n)` | | `EfuseState` | `TargetStatus.efuse` | `enabled`, `fault`, `valid` | | `PowerStatus` | `power_status` | `internal`, `external` (each a `RailPower`), `pod`, `total_current`, `rail(n)` | @@ -2525,7 +2552,7 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen | `MacAddresses` | `mac_addresses` | `eth_mac`, `wifi_mac` (None while not known), `has_wifi`, `source` (`pod`, `server` or empty) | | `LanTls` | `lan_tls`, `set_lan_tls_https_only`, `regenerate_lan_tls`, `set_lan_tls_cert` | `port`, `https_only`, `sessions`, `origin` (`generated`/`user`), `key`, `subject`, `san`, `not_after`, `sha256` (what clients pin), `error` (no certificate) | | `UsbCcStatus` | `usb_cc` | `orientation`, `advertised`, `advertised_current` (A), `cc1_voltage`, `cc2_voltage` (V) | -| `PullState` | `pull_state`, `set_pull` | `la`, `enabled`, `direction`, `ohms`, `available` | +| `PullState` | `pull_state`, `set_pull` | `la`, `enabled`, `direction`, `ohms`, `available`, `supported`, `strength` (digital v3r4) | | `LaPinState` | `la_pins`, `configure_gpio`, `la_dir` | `la`, `function`, `gpio`, `level`, `pull`, `pull_ohms`, `pull_on`, `pull_dirs`, `dir`, `warn`, `warnings`, `in_use` | | `GpioPin` (class) | `gpio`, `gpio_pins`, `signal` | `name`, `configure()`, `set(level)`, `high()`, `low()`, `activate()`, `deactivate()`, `is_active()`, `read()`, `wait_for(level, *, timeout)`, `pulse(width, *, count=1)`, `state()`, `release()` | | `ExtPin` (class) | `gpio`, `gpio_pins`, `signal` on an EXT pin | a `GpioPin` with `ext`, `pin`; `la` is `None`; `pulse()` raises `ExpansionError` | @@ -2599,10 +2626,10 @@ reported keeps its default (`False`, `0` or `""`), so a feature check is just | Group | Fields | |---|---| -| Identity | `board`, `firmware_version`, `board_rev` (`"v2"`, `"v3"`, `"unknown"`, or `""`), `la_vccio_mv` (the LA bank voltage the pod reports) | +| Identity | `board`, `firmware_version`, `board_rev` (`"v2"`, `"v3"`, `"v3r2"`, `"v3r4"` (digital v3r4), `"unknown"`, or `""`), `la_vccio_mv` (the LA I/O voltage the pod reports, 5000 in 5 V mode) | | ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit, of the range in use), `adc_low_range` (analog module v3r4+: the low range), `adc_range` (`"normal"`, `"low"`, or `""` before firmware 3.9.5), `adc_range_fullscale` (volts, ±), `adc_max_count`, `counts_to_volts(count)` | | DAC and replay | `dac`, `dac_dc`, `dac_replay`, `dac_deep_replay`, `dac_control_loop`, `dac_loop_sources` (gateware v29+), `dac_loop_input_map` (v30+), `dac_cotrig` (v27+), `generate16` (firmware 3.9.1+: `generate` in calibrated 16-bit volts), `dac_bits`, `dac_replay_bits`, `dac_replay_max_samples`, `dac_fullscale_mv`, `dac_channels`, `dac_limits` (output limits on the DAC paths) | -| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `uart_frame` (UART parity and stop bits, gateware v56+), `uart_hd` (one-wire UART and boot-mode entry, gateware v57+), `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensors` (sensor emulation from definitions, with `sensors_format` the format the pod reads), `analog` (`False` on the digital-only board, `None` when not announced) | +| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `vref_out` (digital v3r4: pin 21 switched and measured, 5 V I/O, pulls with a strength on every channel), `spi_master` (v45+), `spi_stream`, `uart_frame` (UART parity and stop bits, gateware v56+), `uart_hd` (one-wire UART and boot-mode entry, gateware v57+), `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensors` (sensor emulation from definitions, with `sensors_format` the format the pod reads), `analog` (`False` on the digital-only board, `None` when not announced) | | Firmware updates and policies | `flash_kb` (MCU flash in KiB, 0 when not reported), `blob_slots`, `ota_sig`, `sig_policy` (`"audit"`, `"required"`, ...), `sig_keys`, `sig_policy_cmd`, `lan_policy` (`"open"`, `"locked"`, `"off"`), `lan_policy_cmd`, `tunnel_max_tier`, `lease_state` (the pod refuses LAN writes while a cloud job holds it), `cloud_ca`, `cloud_proxy`, `ws_auth_v2` (server only) | | Boot health | `safe_mode`, `safe_reason`, `last_crash`, `reset_cause`, `boot_warning()` (a one-line warning after safe mode or a crash, else `None`) | | Source | `raw` (the map it was parsed from) | diff --git a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py index b544d4f..014c7f2 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py +++ b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py @@ -191,6 +191,9 @@ class Capabilities: nrst_pin: bool = False #: USB-C CC-line monitoring (rev3 pods): :meth:`BenchPod.usb_cc`. usb_cc: bool = False + #: J1 pin 21 is switched and measured, and the pod has 5 V I/O (digital board v3r4+): the + #: hardware fact ``vref_out``. :attr:`LaVoltage.pin21` reports pin 21. + vref_out: bool = False #: SPI master on four LA pins and SPI NOR flash programming (gateware >= v45): #: :meth:`BenchPod.open_spi`, :meth:`BenchPod.spi_flash`. spi_master: bool = False @@ -423,7 +426,7 @@ def _apply_features(self, facts: Mapping[str, Any]) -> None: attr = _TABLE_ALIASES.get(name, name) if attr in _BOOL_FIELDS: setattr(self, attr, True) - for fact in ("usb_cc", "pod_current", "nrst_pin"): + for fact in ("usb_cc", "pod_current", "nrst_pin", "vref_out"): if facts.get(fact) is True: setattr(self, fact, True) diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 4a51601..5008866 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -72,6 +72,7 @@ LA_STEP_MAX_STEPS, LA_STEP_MIN_DELAY_US, LA_VOLTAGES, + LA_VOLTAGE_5V, PULL_DIRECTIONS, PULL_TABLE, REPLAY_MAPPINGS, @@ -1102,7 +1103,14 @@ def _efuse(self, efuse: Optional[Union[Efuse, int]]) -> int: # -- LA I/O-bank voltage ------------------------------------------------ def set_la_voltage(self, voltage: float) -> LaVoltage: - """Select the LA I/O-bank voltage: ``1.8`` or ``3.3`` volts (1.8 V needs a rev3 pod). + """Select the LA I/O-bank voltage: ``1.8`` or ``3.3`` volts (1.8 V needs a rev3 pod), or + ``5.0`` on a pod with the digital board v3r4 (feature ``la_5v``). + + At 5.0 the pod keeps the bank at 3.3 V and switches J1 pin 21, the rail the pull-ups pull + to, to 5 V: it reads 5 V signals at full speed, and its outputs reach 5 V through their + pull-ups (switch them on for outputs into 5 V CMOS-level inputs). It checks pin 21 and + raises :class:`~embeddedci.benchpod.errors.FirmwareError` ``BP0025`` when 5 V did not + come up. :attr:`LaVoltage.pin21` reports pin 21. Match it to the DUT's I/O voltage. It must be set before any LA-bank operation (flashing, the UART proxy, LA capture, pull resistors, sensor emulation), or the pod refuses them with @@ -1111,11 +1119,25 @@ def set_la_voltage(self, voltage: float) -> LaVoltage: profile, and firmware 3.10.10+ takes it from the profile on the first LA operation. """ v = float(voltage) + if abs(v - LA_VOLTAGE_5V) < 0.05: + # 5 V I/O (digital v3r4): the pod keeps the bank at 3.3 V and moves pin 21 to 5 V. + if not self.supports("la_5v"): + raise ValueError("5 V I/O needs a BenchPod with the digital board v3r4 or later and " + "firmware that has it (feature la_5v): use 1.8 or 3.3") + with _classified_errors(): + return LaVoltage.from_reply(self.command({"cmd": "la_voltage", "mv": 5000})) match = next((ok for ok in LA_VOLTAGES if abs(v - ok) < 0.05), None) if match is None: - raise ValueError(f"la voltage must be 1.8 or 3.3 (volts), got {voltage!r}") + five = " or 5.0 (this pod has 5 V I/O)" if self._has_5v() else "" + raise ValueError(f"la voltage must be 1.8 or 3.3{five} (volts), got {voltage!r}") return LaVoltage.from_reply(self.command({"cmd": "la_voltage", "mv": int(round(match * 1000))})) + def _has_5v(self) -> bool: + try: + return self.supports("la_5v") + except BenchPodError: + return False + def get_la_voltage(self) -> LaVoltage: """The current LA I/O-bank voltage (``voltage`` is ``None`` until one is selected).""" return LaVoltage.from_reply(self.command({"cmd": "la_voltage"})) @@ -3488,7 +3510,10 @@ def la_pins(self) -> List[LaPinState]: self._require_capability("la_pins", "LA pin modes and GPIO") with _classified_errors(): data = _dict(self.command({"cmd": "la_pins"})) - return [LaPinState.from_reply(e) for e in data.get("pins") or []] + # Digital v3r4 says the directions once for every channel ("pull_dirs"). + dirs = data.get("pull_dirs") + return [LaPinState.from_reply(e, pull_dirs=dirs if isinstance(dirs, list) else None) + for e in data.get("pins") or []] def la_dir(self, la: Union[Pin, int, str, Sequence[Union[Pin, int, str]], None] = None, dir: Optional[str] = None) -> List[LaPinState]: diff --git a/packages/embeddedci/src/embeddedci/benchpod/constants.py b/packages/embeddedci/src/embeddedci/benchpod/constants.py index d0476cf..02ccfe5 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/constants.py +++ b/packages/embeddedci/src/embeddedci/benchpod/constants.py @@ -157,6 +157,9 @@ class Pin(IntEnum): #: LA I/O-bank voltages the pod supports (volts). 1.8 V needs a rev3 pod. LA_VOLTAGES: Tuple[float, ...] = (1.8, 3.3) +#: 5 V I/O: digital board v3r4 and later (feature ``la_5v``). The bank stays at 3.3 V and pin 21, +#: the rail the pull-ups pull to, goes to 5 V. +LA_VOLTAGE_5V: float = 5.0 #: Pull directions a host asks for (``BenchPod.set_pull``). The pod picks the resistor value. PullDirection = Literal["up", "down", "off"] diff --git a/packages/embeddedci/src/embeddedci/benchpod/gpio.py b/packages/embeddedci/src/embeddedci/benchpod/gpio.py index 137b9e0..27fa016 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/gpio.py +++ b/packages/embeddedci/src/embeddedci/benchpod/gpio.py @@ -18,7 +18,7 @@ from __future__ import annotations from dataclasses import dataclass, field -from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple +from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Tuple if TYPE_CHECKING: # pragma: no cover from .client import BenchPod @@ -83,9 +83,13 @@ def in_use(self) -> bool: return self.function != "none" @classmethod - def from_reply(cls, entry: Any) -> "LaPinState": + def from_reply(cls, entry: Any, pull_dirs: Optional[Sequence[Any]] = None) -> "LaPinState": + """``pull_dirs``: the la_pins reply's directions for every channel (digital v3r4, whose + entries leave ``dirs`` out).""" e = entry if isinstance(entry, dict) else {} pull = e.get("pull") if isinstance(e.get("pull"), dict) else {} + if pull and "dirs" not in pull and pull_dirs is not None: + pull = dict(pull, dirs=list(pull_dirs)) level = e.get("level") return cls(la=int(e.get("la", 0) or 0), function=str(e.get("function") or "none"), gpio=e.get("gpio") or None, level=None if level is None else int(level), diff --git a/packages/embeddedci/src/embeddedci/benchpod/state.py b/packages/embeddedci/src/embeddedci/benchpod/state.py index db54853..9e0d5d2 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/state.py +++ b/packages/embeddedci/src/embeddedci/benchpod/state.py @@ -36,6 +36,39 @@ def _raw() -> Any: return field(default_factory=dict, repr=False, compare=False) +@dataclass(frozen=True) +class Pin21: + """J1 pin 21 on digital v3r4 (:attr:`LaVoltage.pin21`): the rail every pull-up pulls to, and a + reference the DUT can use. It follows the I/O voltage, or is 5 V in 5 V mode.""" + + #: ``"bank"`` (follows the I/O bank, 1.8 or 3.3 V) or ``"5v"``. + source: str + #: What pin 21 should be, in volts. + setting: float + #: What the pod measures, in volts (``None`` without a reading). + measured: Optional[float] + #: ``"ok"``; ``"high"``: more than 0.2 V above its setting, a DUT signal above the I/O voltage + #: lifts it through the pulls (select 5 V or remove the signal); ``"low"``: overloaded, or + #: 5 V that did not come up; ``"short"``: shorted or held down (the pulls are off); + #: ``"unknown"``: no reading yet. + state: str + #: Pin 21 is high enough for the pull resistors to work. + up: bool + + @property + def ok(self) -> bool: + return self.state == "ok" + + @classmethod + def from_reply(cls, d: Any) -> Optional["Pin21"]: + if not isinstance(d, dict): + return None + mv = _opt_int(d, "mv") + return cls(source=str(d.get("source") or "bank"), setting=(_opt_int(d, "set_mv") or 0) / 1000.0, + measured=mv / 1000.0 if mv is not None and mv >= 0 else None, + state=str(d.get("state") or "unknown"), up=d.get("up") is True) + + @dataclass(frozen=True) class LaVoltage: """The LA I/O-bank voltage (``BenchPod.set_la_voltage`` / ``get_la_voltage``).""" @@ -43,8 +76,11 @@ class LaVoltage: #: Selected bank voltage in volts (1.8 or 3.3), or ``None`` when none has been chosen yet — #: the pod refuses every LA-bank operation until one is. voltage: Optional[float] - #: The measured bank voltage in volts, or ``None`` when the board cannot measure it. + #: The measured bank voltage in volts, or ``None`` when the board cannot measure it. In 5 V + #: mode the bank is at 3.3 V while :attr:`voltage` is 5.0. readback: Optional[float] = None + #: J1 pin 21 on digital v3r4 (``None`` on other boards). + pin21: Optional["Pin21"] = None raw: Dict[str, Any] = _raw() @property @@ -59,7 +95,8 @@ def from_reply(cls, reply: Any) -> "LaVoltage": # Boards without a readback divider report 0 (or a negative sentinel): that is "unknown", # not a bank sitting at 0 V. return cls(voltage=mv / 1000.0 if mv else None, - readback=rb / 1000.0 if rb is not None and rb > 0 else None, raw=d) + readback=rb / 1000.0 if rb is not None and rb > 0 else None, + pin21=Pin21.from_reply(d.get("vref_out")), raw=d) @dataclass(frozen=True) @@ -203,6 +240,9 @@ class PullState: available: bool = True #: Every direction the channel can pull: ``("up",)``, ``("down",)``, ``("up", "down")`` or ``()``. supported: Tuple[str, ...] = () + #: Digital v3r4: the resistors engaged, ``"10k"``, ``"2.2k"`` or ``"both"`` (about 1.8k; + #: ``"none"`` when off). The pod picks them from the pin's function. ``None`` on other boards. + strength: Optional[str] = None raw: Dict[str, Any] = _raw() @property @@ -236,7 +276,8 @@ def from_reply(cls, reply: Any, la: int) -> "PullState": direction = state return cls(la=la, enabled=enabled, direction=direction, ohms=str(d.get("ohms", hw.ohms if hw else "") or ""), - available=bool(d.get("pullups_available", 1)), supported=supported, raw=d) + available=bool(d.get("pullups_available", 1)), supported=supported, + strength=str(d["strength"]) if isinstance(d.get("strength"), str) else None, raw=d) @dataclass(frozen=True) diff --git a/packages/embeddedci/src/embeddedci/benchpod/wiring.py b/packages/embeddedci/src/embeddedci/benchpod/wiring.py index d8b1d7a..57eaff0 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/wiring.py +++ b/packages/embeddedci/src/embeddedci/benchpod/wiring.py @@ -425,8 +425,9 @@ def _errors(self) -> List[str]: errs: List[str] = [] if self.version != WIRING_VERSION: errs.append(f"version must be {WIRING_VERSION}, got {self.version!r}") - if self.la_mv is not None and (not _is_int(self.la_mv) or self.la_mv not in (1800, 3300)): - errs.append(f"la_mv must be 1800 or 3300 (or None: not set), got {self.la_mv!r}") + if self.la_mv is not None and (not _is_int(self.la_mv) or self.la_mv not in (1800, 3300, 5000)): + errs.append(f"la_mv must be 1800, 3300 or 5000 (5 V: digital board v3r4; or None: not set), " + f"got {self.la_mv!r}") if self.efuse is not None and (not _is_int(self.efuse) or self.efuse not in (1, 2)): errs.append(f"efuse must be 1 (internal) or 2 (external) (or None: not set), got {self.efuse!r}") if not _is_int(self.uart_baud) or not 300 <= self.uart_baud <= 4_000_000: diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index a75463a..5f59323 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -321,6 +321,7 @@ "capture_b64", "nrst_pin", "usb_cc", + "vref_out", "spi_master", "spi_stream", "uart_frame", @@ -735,7 +736,7 @@ "pull_dirs", "raw" ], - "from_reply": "(cls, entry: 'Any') -> \"'LaPinState'\"", + "from_reply": "(cls, entry: 'Any', pull_dirs: 'Optional[Sequence[Any]]' = None) -> \"'LaPinState'\"", "in_use": "property", "warnings": "property" }, @@ -743,6 +744,7 @@ "__fields__": [ "voltage", "readback", + "pin21", "raw" ], "from_reply": "(cls, reply: 'Any') -> \"'LaVoltage'\"", @@ -974,6 +976,7 @@ "ohms", "available", "supported", + "strength", "raw" ], "from_reply": "(cls, reply: 'Any', la: 'int') -> \"'PullState'\"", diff --git a/packages/embeddedci/tests/test_digital_v3r4.py b/packages/embeddedci/tests/test_digital_v3r4.py new file mode 100644 index 0000000..0b08d57 --- /dev/null +++ b/packages/embeddedci/tests/test_digital_v3r4.py @@ -0,0 +1,147 @@ +"""Digital board v3r4 (firmware board_caps.h): 5 V I/O and pin 21 (``set_la_voltage(5.0)``, +:attr:`LaVoltage.pin21`), and pulls with a direction and a strength on every channel. A pod +without the ``vref_out`` fact behaves as before: 5.0 is refused before anything is sent.""" + +from __future__ import annotations + +from typing import Any, Dict, List + +import pytest + +from embeddedci.benchpod import BenchPod, FirmwareError, Wiring +from embeddedci.benchpod.errors import firmware_error + + +class Pod: + def __init__(self, v3r4: bool, features_rev: int = 7) -> None: + self.v3r4 = v3r4 + self.features_rev = features_rev + self.sent: List[Dict[str, Any]] = [] + self.mv = 0 + self.pin21_mv = 3300 + self.five_v_ok = True + self.pulls: Dict[int, tuple] = {} + + def status(self) -> Dict[str, Any]: + hw = ["nrst_pin"] + (["vref_out"] if self.v3r4 else []) + return {"board": "stm32h563", "adc_bits": 16, "version": "3.10.13", "features_rev": self.features_rev, + "gateware": 58, "fpga_image": "deep", "hw": hw, "board_rev": "v3r4" if self.v3r4 else "v3"} + + def ping(self) -> Any: + return "pong" + + def close(self) -> None: + pass + + def _vref(self) -> Dict[str, Any]: + src = "5v" if self.mv == 5000 else "bank" + return {"source": src, "set_mv": 5000 if src == "5v" else (self.mv or 3300), "mv": self.pin21_mv, + "state": "ok", "up": True} + + def command(self, req: dict) -> Any: + if req.get("cmd") == "status": + return self.status() + self.sent.append(req) + if req["cmd"] == "la_voltage": + if "mv" in req: + if req["mv"] == 5000 and not self.v3r4: + raise firmware_error("la voltage must be 1800 or 3300 (mv)", cmd="la_voltage") + if req["mv"] == 5000 and not self.five_v_ok: + raise firmware_error("5 V did not come up on pin 21 (4120 mV); check the USB supply", + cmd="la_voltage", code="BP0025", values={"mv": 4120}) + self.mv = req["mv"] + self.pin21_mv = 4920 if self.mv == 5000 else self.mv + out: Dict[str, Any] = {"mv": self.mv, "st": 1, "readback_mv": 3300 if self.mv == 5000 else self.mv} + if self.v3r4: + out["vref_out"] = self._vref() + return out + if req["cmd"] == "la": + la = req["la"] + want = req.get("pull", "off") + if want != "off": + self.pulls[la] = (want, "2.2k" if la in (1, 2) else "10k") + else: + self.pulls.pop(la, None) + d, s = self.pulls.get(la, ("off", "none")) + ohms = {"2.2k": "2.2k", "10k": "10k", "none": "10k"}[s] + return {"la": la, "pullup": int(d != "off"), "ohms": ohms, "pull": d if d != "off" else "up", + "state": d, "dirs": ["up", "down"], "strength": s, + "strengths": ["10k", "2.2k", "both"], "pullups_available": 1} + if req["cmd"] == "la_pins": + pins = [{"la": n, "function": "none", "gpio": None, "level": None, + "pull": {"dir": "up", "ohms": "10k", "on": False}} for n in range(1, 15)] + return {"pins": pins, "pull_dirs": ["up", "down"], "levels": None} + raise AssertionError(req) + + +def _bp(v3r4: bool, features_rev: int = 7) -> "tuple[BenchPod, Pod]": + pod = Pod(v3r4, features_rev) + return BenchPod(transport=pod, lease=False, wiring={"version": 2}), pod + + +def test_capabilities_say_v3r4(): + bp, _ = _bp(True) + assert bp.capabilities.vref_out + assert bp.supports("la_5v") and bp.supports("la_pull_strength") + old, _ = _bp(False) + assert not old.capabilities.vref_out + assert not old.supports("la_5v") and not old.supports("la_pull_strength") + + +def test_5v_on_v3r4(): + bp, pod = _bp(True) + st = bp.set_la_voltage(5.0) + assert pod.sent[-1] == {"cmd": "la_voltage", "mv": 5000} + assert st.voltage == 5.0 and st.readback == 3.3 + assert st.pin21 is not None and st.pin21.source == "5v" and st.pin21.ok + assert st.pin21.measured == pytest.approx(4.92) and st.pin21.setting == 5.0 + + +def test_5v_refused_before_sending_on_older_boards(): + bp, pod = _bp(False) + with pytest.raises(ValueError, match="digital board v3r4"): + bp.set_la_voltage(5.0) + assert not [r for r in pod.sent if r["cmd"] == "la_voltage"] + # 3.3 V is as before, and there is no pin 21 in the reply + st = bp.set_la_voltage(3.3) + assert st.voltage == 3.3 and st.pin21 is None + + +def test_5v_that_did_not_come_up(): + bp, pod = _bp(True) + pod.five_v_ok = False + with pytest.raises(FirmwareError) as e: + bp.set_la_voltage(5.0) + assert e.value.code == "BP0025" + + +def test_other_voltages_name_5v_only_where_it_exists(): + bp, _ = _bp(True) + with pytest.raises(ValueError, match="or 5.0"): + bp.set_la_voltage(2.5) + old, _ = _bp(False) + with pytest.raises(ValueError) as e: + old.set_la_voltage(2.5) + assert "5.0" not in str(e.value) + + +def test_pull_strength_reported(): + bp, _ = _bp(True) + st = bp.set_pull(1, "up") + assert st.state == "up" and st.strength == "2.2k" and st.ohms == "2.2k" + st = bp.set_pull(9, "down") # every channel on v3r4, both ways + assert st.state == "down" and st.supported == ("up", "down") and st.strength == "10k" + st = bp.set_pull(9, "off") + assert st.state == "off" and st.strength == "none" + + +def test_la_pins_takes_the_directions_said_once(): + bp, _ = _bp(True) + pins = bp.la_pins() + assert len(pins) == 14 and all(p.pull_dirs == ("up", "down") for p in pins) + + +def test_profile_takes_5v(): + assert Wiring(la_mv=5000).la_voltage == 5.0 + with pytest.raises(ValueError, match="1800, 3300 or 5000"): + Wiring(la_mv=2500) diff --git a/packages/embeddedci/tests/test_wiring.py b/packages/embeddedci/tests/test_wiring.py index d5ce1e2..2cdbfad 100644 --- a/packages/embeddedci/tests/test_wiring.py +++ b/packages/embeddedci/tests/test_wiring.py @@ -56,7 +56,7 @@ def test_lookups_by_role_and_signal(): def test_every_problem_is_reported_at_once(): with pytest.raises(ValueError) as ei: - Wiring(la_mv=5000, efuse=3, uart_baud=10, uart_rx=15, i2c_addr="0x80", + Wiring(la_mv=2500, efuse=3, uart_baud=10, uart_rx=15, i2c_addr="0x80", signals=[Signal("1bad", 20), Signal("uart_tx", 6, "sideways")]) msg = str(ei.value) for part in ("la_mv", "efuse", "uart_baud", "uart_rx", "i2c_addr", "signals[0].name", From 84ec4b85084b53114b7fb8b555772936444bd26c Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 09:13:50 -0600 Subject: [PATCH 2/4] la_pins(la=...), PullState.held, both pull directions in la_dir/gpio entries on v3r4 - la_pins(la=...) lists only those channels. Firmware after 3.10.12 sends only them, older firmware sends all 14 and the SDK filters. A full listing answered with "reply too large" is read in two parts (LA1-7, LA8-14). - PullState.held (and MCP pull_status/set_pull "held"): why a pull that was set is off now on digital v3r4 (pin21_down, dut_off, fault). enabled/state are the live state (firmware #181). - la_dir() and gpio entries on v3r4 had pull_dirs ("up",) only: their replies leave dirs out and have no pull_dirs. They now get ("up","down") when the pod has la_pull_strength. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/CHANGELOG.md | 3 + .../src/embeddedci_mcp/models.py | 3 + .../src/embeddedci_mcp/server.py | 3 +- packages/embeddedci-mcp/tests/test_tools.py | 3 +- packages/embeddedci/CHANGELOG.md | 6 ++ packages/embeddedci/README.md | 9 ++- .../src/embeddedci/benchpod/client.py | 48 ++++++++++-- .../src/embeddedci/benchpod/state.py | 8 +- packages/embeddedci/tests/api_surface.json | 3 +- .../embeddedci/tests/test_digital_v3r4.py | 78 +++++++++++++++++-- 10 files changed, 146 insertions(+), 18 deletions(-) diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index 1b6ca6a..36031a7 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -2,6 +2,9 @@ ## 3.0.5 +- `pull_status` and `set_pull` channels have `held` on digital v3r4: why a pull that was set is off + right now (`pin21_down`, `dut_off`, `fault`). `la_pins` reads a listing too large for one cloud + reply in two parts (through the SDK). - **Digital board v3r4:** `set_la_voltage` takes `5.0` (and `connect` `la_voltage=5.0`, the `--la-voltage` flag too) on a pod with 5 V I/O, and `voltage` may be omitted to read the voltage without changing it. The result has `pin21` (source, setting, measured, state, up) there; the diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index 5b7dd7b..cd991a3 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -568,6 +568,9 @@ class PullChannel(BaseModel): available: bool #: Digital v3r4: 10k, 2.2k or both (about 1.8k), none when off; picked from the pin's function. strength: Optional[str] = None + #: Digital v3r4: why a pull that was set is off right now (pin21_down, dut_off, fault); the pod + #: puts it back by itself. None when everything set is on. + held: Optional[str] = None class PullStatusResult(BaseModel): diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index be4a15e..51145e4 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -1665,7 +1665,8 @@ def _pull(state: Any) -> m.PullChannel: return m.PullChannel(la=state.la, state=getattr(state, "state", direction if state.enabled else "off"), supported=list(supported), enabled=state.enabled, direction=direction, ohms=state.ohms, available=state.available, - strength=getattr(state, "strength", None)) + strength=getattr(state, "strength", None), + held=getattr(state, "held", None)) def _sdk_pulls_by_direction(pod: Any) -> bool: diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index 332c2c8..6dffebd 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -599,7 +599,8 @@ def test_pulls(connected): return assert [c["la"] for c in status["channels"]] == list(range(1, 15)) assert status["channels"][8] == {"la": 9, "state": "off", "supported": [], "enabled": False, - "direction": None, "ohms": "", "available": True, "strength": None} + "direction": None, "ohms": "", "available": True, "strength": None, + "held": None} with pytest.raises(ToolError, match="BP0023"): call("set_pull", las=[9], pull="up") with pytest.raises(ToolError, match="LA7 supports pull-down only on this board"): diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index e892196..d0b0425 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -2,6 +2,12 @@ ## 3.0.5 +- `la_pins(la=...)` lists only those channels (firmware after 3.10.12 sends only them; older + firmware sends all 14 and the SDK keeps the ones asked for). A full listing the pod answers with + "reply too large" is read in two parts by itself. +- **Digital board v3r4:** `PullState.held` says why a pull that was set is off right now + (`pin21_down`, `dut_off`, `fault`), and `enabled`/`state` are what is on the wire. `la_dir()` and + `gpio` entries now report both pull directions there, like `la_pins()`. - **Digital board v3r4:** `set_la_voltage(5.0)` (and `la_mv: 5000` in a wiring profile) on a pod with the `la_5v` feature: the bank stays at 3.3 V, J1 pin 21 (the pull-up rail) goes to 5 V; other pods raise `ValueError` before anything is sent. `LaVoltage.pin21` (new `Pin21`: `source`, diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 570304f..13e9505 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -1219,6 +1219,9 @@ mode; 10k otherwise), and `PullState.strength` says which (`"10k"`, `"2.2k"`, `" when off). The pull-ups go to J1 pin 21, so they work at 1.8, 3.3 and 5 V. While pin 21 is down (shorted or held down) the pod turns every pull off and refuses new ones with `BP0029`; when the pod switches the DUT's power off, the pull-ups stay off until a rail is on again or you set a pull. +While the pod holds a pull off like this, `PullState.enabled` and `state` say what is on the wire +and `PullState.held` says why (`"pin21_down"`, `"dut_off"` or `"fault"`; `None` otherwise). The pod +puts the pull back by itself (firmware after 3.10.12). ```python from embeddedci.benchpod import PIN1, PIN2, PIN7 @@ -1288,7 +1291,9 @@ The other owners point to `bp.sensors.stop("")`, closing the session f `bp.open_uart()` or `bp.open_spi()`, or waiting for a flash or step train to finish. The pod's own text, with its raw protocol command, stays in `exc.firmware_message`. -`bp.la_pins()` lists every channel's `LaPinState` (`function`, `gpio` mode, `level`, `pull`, `pull_on`, `pull_dirs`), +`bp.la_pins()` lists every channel's `LaPinState` (`function`, `gpio` mode, `level`, `pull`, `pull_on`, `pull_dirs`); +`bp.la_pins(la=[3, 4])` only those channels. A listing too large for one cloud reply (a long +sensor instance name on every channel) is read in two parts by itself (firmware after 3.10.12), and `bp.configure_gpio(channels, mode)` is the same group claim as `gpio_pins()` returning those states. Captures observe every channel whatever its function. GPIO channels stay GPIO — also across disconnects — until released (the pytest `benchpod` fixture releases them at session start and end), @@ -2523,7 +2528,7 @@ lease_wait=600.0, lease_ttl=120, wiring=None, lease_purpose=None)`. A context ma | GPIO expanders | `expansion(chip="", *, addr=None, sda=None, scl=None, spi=None, load=None, count=None, hz=None, pullups=None, names=None)` (see [GPIO expanders](#gpio-expanders)) | | UART | `capture_uart(...)`, `power_cycle_and_capture(...)`, `open_uart(...)` | | Bias resistors | `enable_pullup(*las)`, `disable_pullup(*las)`, `enable_pulldown(*las)`, `disable_pulldown(*las)` (LA7/LA8), `set_pull(la, enabled)`, `pull_state(la)`, `enabled_pulls()` | -| GPIO and pins | `gpio(la, mode="output", *, level=None)`, `gpio_pins(las, mode="output", *, level=None)`, `configure_gpio(las, mode="output", *, level=None)`, `set_gpio(la, level)` (`level` may be a list, one per channel), `read_gpio(la)`, `wait_for_level(la, level, *, timeout, poll=0.005)` (`False` when `timeout` passes first), `pin_levels()`, `la_pins()`, `la_dir(la=None, dir=None)`, `pin_directions(wiring=None)`, `apply_pin_directions(wiring=None)`, `pin_directions_status`, `release_gpio(*las)`, `la_step(la, *, steps, delay, dir_la=None, direction=0)` | +| GPIO and pins | `gpio(la, mode="output", *, level=None)`, `gpio_pins(las, mode="output", *, level=None)`, `configure_gpio(las, mode="output", *, level=None)`, `set_gpio(la, level)` (`level` may be a list, one per channel), `read_gpio(la)`, `wait_for_level(la, level, *, timeout, poll=0.005)` (`False` when `timeout` passes first), `pin_levels()`, `la_pins(la=None)`, `la_dir(la=None, dir=None)`, `pin_directions(wiring=None)`, `apply_pin_directions(wiring=None)`, `pin_directions_status`, `release_gpio(*las)`, `la_step(la, *, steps, delay, dir_la=None, direction=0)` | | Emulated sensors | `sensors` (a `SensorEmulation`: `start(definition, *, instance=None, pins=None, address=None, baud=None, values=None)`, `define()`, `validate()`, `set()`, `fault()`, `clear_fault()`, `load_stimulus()`, `start_stimulus()`, `stop_stimulus()`, `stop()`, `status()`, `regs()`, `capture()`, `i2c_transactions()`, `library()`); see [Emulated sensors](#emulated-sensors) | | Analog | `analog_path(path, *, range=None)`, `adc_read(source="ext", *, range=None)`, `adc_range(range=None)`, `adc_range_test()`, `dac_output(path, *, volts=None)`, `current_out(current)`, `current_out_range()`, `calibrate(source="current_in")`, `calibration()`, `clear_calibration(part=None)`, `calibrate_dac(path, points)`, `calibrate_adc_gain(source, *, range="normal")`, `DMM_SET_POINTS` | | Captures | `capture_adc(...)`, `capture_la(..., send=None)`, `capture_correlated(...)`, `decode(source, protocol="i2c", ...)` | diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 5008866..8e0fb8e 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -3504,17 +3504,51 @@ def waveforms(self) -> "WaveformLibrary": # -- LA pin modes + GPIO -------------------------------------------------- # The LA pins on the iCE40 (not STM32 GPIOs). Each has one function at a time; see gpio.py. - def la_pins(self) -> List[LaPinState]: + def la_pins(self, la: Union[Pin, int, str, Sequence[Union[Pin, int, str]], None] = None + ) -> List[LaPinState]: """Every LA channel's function (``none``, ``gpio``, ``uart_rx``, …), GPIO mode and level, and - bias resistor. A channel that is in use refuses other functions.""" + bias resistor. A channel that is in use refuses other functions. + + ``la``: only these channels (a channel, a wiring name, or a list), in pin order. Firmware + after 3.10.12 sends only those; older firmware sends all 14 and the SDK keeps the ones asked + for. A full listing too large for one cloud reply (a long sensor instance name on every + pin) is read in two parts by itself.""" self._require_capability("la_pins", "LA pin modes and GPIO") + if la == "all": + la = None + if la is not None: + want = sorted(set(self._resolve_las(la, why="la_pins lists LA channels"))) + return [p for p in self._la_pins_query(want) if p.la in want] + try: + return self._la_pins_query(None) + except FirmwareError as e: + if "reply too large" not in str(getattr(e, "firmware_message", "") or e): + raise + first = self._la_pins_query(list(range(1, 8))) + if len(first) > 7: # firmware without the subset: it listed everything again + raise + return first + [p for p in self._la_pins_query(list(range(8, 15))) if p.la >= 8] + + def _la_pins_query(self, las: Optional[List[int]]) -> List[LaPinState]: + req: Dict[str, Any] = {"cmd": "la_pins"} + if las is not None: + req["la"] = las with _classified_errors(): - data = _dict(self.command({"cmd": "la_pins"})) + data = _dict(self.command(req)) # Digital v3r4 says the directions once for every channel ("pull_dirs"). dirs = data.get("pull_dirs") return [LaPinState.from_reply(e, pull_dirs=dirs if isinstance(dirs, list) else None) for e in data.get("pins") or []] + def _entry_pull_dirs(self, entries: Any) -> Optional[Tuple[str, ...]]: + """The pull directions for listing replies that do not say them (la_dir, gpio): on digital + v3r4 every channel pulls both ways, said only once in the la_pins reply.""" + if not isinstance(entries, list): + return None + bare = any(isinstance(e, dict) and isinstance(e.get("pull"), dict) and "dirs" not in e["pull"] + for e in entries) + return ("up", "down") if bare and self.supports("la_pull_strength") else None + def la_dir(self, la: Union[Pin, int, str, Sequence[Union[Pin, int, str]], None] = None, dir: Optional[str] = None) -> List[LaPinState]: """Tell the pod which way each pin's DUT signal goes, and return the changed pins' state. @@ -3538,7 +3572,9 @@ def la_dir(self, la: Union[Pin, int, str, Sequence[Union[Pin, int, str]], None] with _classified_errors(): data = self.command(req) entries = data.get("pins") if isinstance(data, dict) else data - return [LaPinState.from_reply(e) for e in entries or []] if isinstance(entries, list) else [] + dirs = self._entry_pull_dirs(entries) + return ([LaPinState.from_reply(e, pull_dirs=dirs) for e in entries or []] + if isinstance(entries, list) else []) def pin_directions(self, wiring: Optional[Wiring] = None) -> Dict[int, str]: """The DUT direction of every pin the wiring profile names, as :meth:`la_dir` takes it: @@ -3775,7 +3811,9 @@ def _gpio_configure(self, las: List[int], mode: str, level: Optional[int]) -> Li self._require_capability("la_pins", "GPIO") with _classified_errors(): data = _dict(self.command(req)) - pins = [LaPinState.from_reply(e) for e in data.get("pins") or []] + entries = data.get("pins") or [] + dirs = self._entry_pull_dirs(entries) + pins = [LaPinState.from_reply(e, pull_dirs=dirs) for e in entries] return pins or [LaPinState(la=la, function="gpio", gpio=mode, level=level) for la in las] def _resolve_las(self, la: Any, why: str = "") -> List[int]: diff --git a/packages/embeddedci/src/embeddedci/benchpod/state.py b/packages/embeddedci/src/embeddedci/benchpod/state.py index 9e0d5d2..01a461f 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/state.py +++ b/packages/embeddedci/src/embeddedci/benchpod/state.py @@ -243,6 +243,11 @@ class PullState: #: Digital v3r4: the resistors engaged, ``"10k"``, ``"2.2k"`` or ``"both"`` (about 1.8k; #: ``"none"`` when off). The pod picks them from the pin's function. ``None`` on other boards. strength: Optional[str] = None + #: Digital v3r4: why a pull the host set is off right now, else ``None``. ``"pin21_down"`` + #: (pin 21 is down: every pull off), ``"dut_off"`` (pull-ups suspended after the pod switched the + #: DUT off), ``"fault"`` (an expander write failed). ``enabled`` is what is on the wire; the pod + #: puts the pull back by itself. + held: Optional[str] = None raw: Dict[str, Any] = _raw() @property @@ -277,7 +282,8 @@ def from_reply(cls, reply: Any, la: int) -> "PullState": return cls(la=la, enabled=enabled, direction=direction, ohms=str(d.get("ohms", hw.ohms if hw else "") or ""), available=bool(d.get("pullups_available", 1)), supported=supported, - strength=str(d["strength"]) if isinstance(d.get("strength"), str) else None, raw=d) + strength=str(d["strength"]) if isinstance(d.get("strength"), str) else None, + held=str(d["held"]) if isinstance(d.get("held"), str) else None, raw=d) @dataclass(frozen=True) diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 5f59323..de22ca2 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -138,7 +138,7 @@ "gpio": "(self, la: 'Union[Pin, int, str]', mode: 'GpioMode' = 'output', *, level: 'Optional[int]' = None) -> 'GpioPin'", "gpio_pins": "(self, las: 'Sequence[Union[Pin, int, str]]', mode: 'GpioMode' = 'output', *, level: 'Optional[int]' = None) -> 'List[GpioPin]'", "la_dir": "(self, la: 'Union[Pin, int, str, Sequence[Union[Pin, int, str]], None]' = None, dir: 'Optional[str]' = None) -> 'List[LaPinState]'", - "la_pins": "(self) -> 'List[LaPinState]'", + "la_pins": "(self, la: 'Union[Pin, int, str, Sequence[Union[Pin, int, str]], None]' = None) -> 'List[LaPinState]'", "la_step": "(self, la: 'Union[Pin, int]', *, steps: 'int', delay: 'float', dir_la: 'Optional[Union[Pin, int]]' = None, direction: 'int' = 0) -> 'Dict[str, Any]'", "lan_tls": "(self) -> \"'LanTls'\"", "leased": "property", @@ -977,6 +977,7 @@ "available", "supported", "strength", + "held", "raw" ], "from_reply": "(cls, reply: 'Any', la: 'int') -> \"'PullState'\"", diff --git a/packages/embeddedci/tests/test_digital_v3r4.py b/packages/embeddedci/tests/test_digital_v3r4.py index 0b08d57..c8792e4 100644 --- a/packages/embeddedci/tests/test_digital_v3r4.py +++ b/packages/embeddedci/tests/test_digital_v3r4.py @@ -21,6 +21,9 @@ def __init__(self, v3r4: bool, features_rev: int = 7) -> None: self.pin21_mv = 3300 self.five_v_ok = True self.pulls: Dict[int, tuple] = {} + self.held = "" # la query: a pull held off ("pin21_down", ...) + self.subset = True # firmware with la_pins "la" + self.too_large = False # the full la_pins listing does not fit one reply def status(self) -> Dict[str, Any]: hw = ["nrst_pin"] + (["vref_out"] if self.v3r4 else []) @@ -57,22 +60,37 @@ def command(self, req: dict) -> Any: return out if req["cmd"] == "la": la = req["la"] - want = req.get("pull", "off") - if want != "off": + want = req.get("pull") # None: a query + if want is None: + pass + elif want != "off": self.pulls[la] = (want, "2.2k" if la in (1, 2) else "10k") else: self.pulls.pop(la, None) d, s = self.pulls.get(la, ("off", "none")) ohms = {"2.2k": "2.2k", "10k": "10k", "none": "10k"}[s] - return {"la": la, "pullup": int(d != "off"), "ohms": ohms, "pull": d if d != "off" else "up", - "state": d, "dirs": ["up", "down"], "strength": s, - "strengths": ["10k", "2.2k", "both"], "pullups_available": 1} + out = {"la": la, "pullup": int(d != "off"), "ohms": ohms, "pull": d if d != "off" else "up", + "state": d, "dirs": ["up", "down"], "strength": s, + "strengths": ["10k", "2.2k", "both"], "pullups_available": 1} + if self.held and d != "off": + out.update(pullup=0, state="off", held=self.held) + return out if req["cmd"] == "la_pins": - pins = [{"la": n, "function": "none", "gpio": None, "level": None, - "pull": {"dir": "up", "ohms": "10k", "on": False}} for n in range(1, 15)] + want = req.get("la") if self.subset else None + if want is None and self.too_large: + raise firmware_error("reply too large", cmd="la_pins") + pins = [self._entry(n) for n in range(1, 15) if want is None or n in want] return {"pins": pins, "pull_dirs": ["up", "down"], "levels": None} + if req["cmd"] in ("la_dir", "gpio"): # the same entries, without pull_dirs + las = req["la"] if isinstance(req["la"], list) else [req["la"]] + return {"pins": [self._entry(n) for n in las]} raise AssertionError(req) + @staticmethod + def _entry(n: int) -> Dict[str, Any]: + return {"la": n, "function": "none", "gpio": None, "level": None, + "pull": {"dir": "up", "ohms": "10k", "on": False}} + def _bp(v3r4: bool, features_rev: int = 7) -> "tuple[BenchPod, Pod]": pod = Pod(v3r4, features_rev) @@ -141,6 +159,52 @@ def test_la_pins_takes_the_directions_said_once(): assert len(pins) == 14 and all(p.pull_dirs == ("up", "down") for p in pins) +def test_la_pins_subset(): + bp, pod = _bp(True) + pins = bp.la_pins(la=[9, 3]) + assert pod.sent[-1] == {"cmd": "la_pins", "la": [3, 9]} + assert [p.la for p in pins] == [3, 9] and pins[0].pull_dirs == ("up", "down") + # Older firmware ignores "la" and lists all 14: the SDK keeps the ones asked for. + pod.subset = False + assert [p.la for p in bp.la_pins(la=5)] == [5] + # Without la the request is as before. + bp.la_pins() + assert pod.sent[-1] == {"cmd": "la_pins"} + + +def test_la_pins_too_large_reads_in_two_parts(): + bp, pod = _bp(True) + pod.too_large = True + pins = bp.la_pins() + assert [p.la for p in pins] == list(range(1, 15)) + assert pod.sent[-2:] == [{"cmd": "la_pins", "la": [1, 2, 3, 4, 5, 6, 7]}, + {"cmd": "la_pins", "la": [8, 9, 10, 11, 12, 13, 14]}] + # Firmware without the subset cannot help: the error stands. + pod.subset = False + with pytest.raises(FirmwareError, match="reply too large"): + bp.la_pins() + + +def test_la_dir_and_gpio_entries_pull_both_ways_on_v3r4(): + bp, _ = _bp(True) + assert bp.la_dir(9, "dut_input")[0].pull_dirs == ("up", "down") + assert all(p.pull_dirs == ("up", "down") for p in bp._gpio_configure([4], "input", None)) + # Older boards say dirs per entry; without them an entry keeps its one direction. + old, _ = _bp(False) + assert old.la_dir(9, "dut_input")[0].pull_dirs == ("up",) + + +def test_pull_held_off(): + bp, pod = _bp(True) + bp.set_pull(2, "up") + pod.held = "dut_off" + st = bp.pull_state(2) + assert st.held == "dut_off" and not st.enabled and st.state == "off" and st.strength == "2.2k" + pod.held = "" + st = bp.pull_state(2) + assert st.held is None and st.enabled + + def test_profile_takes_5v(): assert Wiring(la_mv=5000).la_voltage == 5.0 with pytest.raises(ValueError, match="1800, 3300 or 5000"): From f3677156d9833a2fdfe44cf135ed2027f9fb256f Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 09:27:59 -0600 Subject: [PATCH 3/4] la_pins too large on older firmware: say to update the pod A full la_pins listing that older firmware answers with "reply too large" (it has no la subset, so the SDK cannot read it in parts) now says that firmware after 3.10.12 reads it in parts, how to update, and that bp.la_pins(la=[...]) asks for fewer channels. Like the status hint. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/CHANGELOG.md | 3 ++- packages/embeddedci/src/embeddedci/benchpod/errors.py | 11 +++++++++++ packages/embeddedci/tests/test_digital_v3r4.py | 3 ++- packages/embeddedci/tests/test_refusal_errors.py | 9 +++++++++ 4 files changed, 24 insertions(+), 2 deletions(-) diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index d0b0425..a06e90b 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -4,7 +4,8 @@ - `la_pins(la=...)` lists only those channels (firmware after 3.10.12 sends only them; older firmware sends all 14 and the SDK keeps the ones asked for). A full listing the pod answers with - "reply too large" is read in two parts by itself. + "reply too large" is read in two parts by itself; on older firmware, which cannot, the error + says to update the pod or ask for fewer channels. - **Digital board v3r4:** `PullState.held` says why a pull that was set is off right now (`pin21_down`, `dut_off`, `fault`), and `enabled`/`state` are what is on the wire. `la_dir()` and `gpio` entries now report both pull directions there, like `la_pins()`. diff --git a/packages/embeddedci/src/embeddedci/benchpod/errors.py b/packages/embeddedci/src/embeddedci/benchpod/errors.py index 8fab4e7..8ceff63 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/errors.py +++ b/packages/embeddedci/src/embeddedci/benchpod/errors.py @@ -89,6 +89,10 @@ def __init__(self, message: str, *, cmd: Optional[str] = None) -> None: if status_too_large(message, cmd): text += (f"; firmware {STATUS_FITS_FIRMWARE} and later send a status that fits: update " "the pod (`benchpod flash-self`, or the firmware update in the web app)") + elif la_pins_too_large(message, cmd): + text += ("; firmware after 3.10.12 reads this list in parts (la_pins with la): update " + "the pod (`benchpod flash-self`, or the firmware update in the web app), or ask " + "for fewer channels with bp.la_pins(la=[...])") if cmd: super().__init__(f"{cmd}: {text}") else: @@ -320,6 +324,13 @@ def __init__(self, message: str, *, cmd: Optional[str] = None, def status_too_large(message: str, cmd: Optional[str] = "status") -> bool: """Whether a pod refusal is a ``status`` reply that did not fit the cloud channel.""" return cmd == "status" and _STATUS_TOO_LARGE in message + + +def la_pins_too_large(message: str, cmd: Optional[str] = "la_pins") -> bool: + """Whether a pod refusal is a full ``la_pins`` listing too large for one reply (LAN + ``reply too large``, cloud ``... for the cloud channel``). Only older firmware leaves it there: + newer firmware takes ``la`` and the SDK reads the list in parts.""" + return cmd == "la_pins" and "reply too large" in message _LA_VOLTAGE_SDK = ("la voltage not set; the wiring profile sets no I/O voltage: set la_mv in it " "(bp.save_wiring(bp.wiring.with_changes(la_mv=3300)), 1800 for a 1.8 V board), " "or pass BenchPod(conn, la_voltage=3.3), or call bp.set_la_voltage(3.3)") diff --git a/packages/embeddedci/tests/test_digital_v3r4.py b/packages/embeddedci/tests/test_digital_v3r4.py index c8792e4..ac38188 100644 --- a/packages/embeddedci/tests/test_digital_v3r4.py +++ b/packages/embeddedci/tests/test_digital_v3r4.py @@ -181,8 +181,9 @@ def test_la_pins_too_large_reads_in_two_parts(): {"cmd": "la_pins", "la": [8, 9, 10, 11, 12, 13, 14]}] # Firmware without the subset cannot help: the error stands. pod.subset = False - with pytest.raises(FirmwareError, match="reply too large"): + with pytest.raises(FirmwareError, match="reply too large") as e: bp.la_pins() + assert "firmware after 3.10.12 reads this list in parts" in str(e.value) def test_la_dir_and_gpio_entries_pull_both_ways_on_v3r4(): diff --git a/packages/embeddedci/tests/test_refusal_errors.py b/packages/embeddedci/tests/test_refusal_errors.py index 532d5a9..6280885 100644 --- a/packages/embeddedci/tests/test_refusal_errors.py +++ b/packages/embeddedci/tests/test_refusal_errors.py @@ -61,6 +61,15 @@ def test_status_too_large_for_the_cloud_names_the_fix(): assert "3.10.5" not in str(other) +def test_la_pins_too_large_names_the_update(): + for msg in ("reply too large", "reply too large for the cloud channel (2288 bytes, limit 1791)"): + err = firmware_error(msg, cmd="la_pins") + assert err.firmware_message == msg + assert "firmware after 3.10.12 reads this list in parts" in str(err) + assert "benchpod flash-self" in str(err) and "la_pins(la=" in str(err) + assert "3.10.12" not in str(firmware_error("reply too large", cmd="gpio")) + + def test_busy_without_a_lease(): err = firmware_error("busy: a capture or upload is running") assert type(err) is PodBusyError From 8a46d798e40739244235ef4a3cbee6a2a2069897 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Thu, 19 Nov 2026 09:36:26 -0600 Subject: [PATCH 4/4] 5 V I/O: one page, linked; set_la_voltage raises BP0028 (not BP0025) The SDK README, the set_la_voltage docstring and the MCP tool point to embeddedci.com/docs/benchpod-targets/5v-rs485#5v-io instead of explaining 5 V I/O again. The README no longer says the pod has no 5 V I/O (only boards before v3r4). The MCP instructions and la-voltage-not-set hints name 5.0 on a digital v3r4 pod. The docstring named the lease code BP0025 for a 5 V that did not come up; it is BP0028 (the test fake had it too). Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/README.md | 4 ++-- packages/embeddedci-mcp/src/embeddedci_mcp/guide.py | 2 +- .../embeddedci-mcp/src/embeddedci_mcp/server.py | 8 ++++---- packages/embeddedci-mcp/tests/test_refusals.py | 2 +- packages/embeddedci/README.md | 13 ++++++------- .../embeddedci/src/embeddedci/benchpod/client.py | 9 ++++----- .../embeddedci/src/embeddedci/benchpod/state.py | 3 ++- packages/embeddedci/tests/test_digital_v3r4.py | 4 ++-- 8 files changed, 22 insertions(+), 23 deletions(-) diff --git a/packages/embeddedci-mcp/README.md b/packages/embeddedci-mcp/README.md index 09ef321..dea44bf 100644 --- a/packages/embeddedci-mcp/README.md +++ b/packages/embeddedci-mcp/README.md @@ -140,7 +140,7 @@ transparently, so an idle chat never blocks CI on that pod. `status` shows the p | Flag | Environment | Default | | | --- | --- | --- | --- | | `--connection` | `BENCHPOD_CONNECTION` | the CLI's saved connection, else mDNS | host[:port], serial device, `usb`, `usb:`, `discover`, `saved`, or `embeddedci:`; unset = `benchpod set-connection`'s saved one, else find the one pod on the LAN | -| `--la-voltage` | `BENCHPOD_LA_VOLTAGE` | — | LA I/O voltage (1.8 or 3.3) applied on connect | +| `--la-voltage` | `BENCHPOD_LA_VOLTAGE` | — | LA I/O voltage (1.8 or 3.3; 5.0 on a digital v3r4 pod) applied on connect | | `--wiring-autosave` | `BENCHPOD_WIRING_AUTOSAVE` | off | `set_wiring` also stores the profile on the pod (not a change of the I/O voltage, power rail or SWD target: those need `save_wiring`) | | — | `BENCHPOD_API_KEY` | — | cloud pods and the waveform library (without it, cloud tools use the `benchpod login` session) | | — | `BENCHPOD_API_BASE` | `https://www.embeddedci.com` | another embeddedci server | @@ -452,7 +452,7 @@ capture tools' summaries, `la_timing` and `decode_la` instead. `status` also warns when a cloud job holds the pod or the LAN policy is locked. Refusals whose fix the firmware spells as a raw protocol command name the tool instead: `FirmwareError: uart_proxy_start: la voltage not set; the wiring profile sets no I/O voltage: ask - the user for the board's (1.8 or 3.3), set it in the profile (set_wiring with la_mv 1800 or 3300, + the user for the board's (1.8 or 3.3, 5.0 on a digital v3r4 pod), set it in the profile (set_wiring with la_mv 1800 or 3300, then save_wiring) or call set_la_voltage` and `PinConflictError: uart_proxy_start: pin conflict: LA4 is in use by gpio; release it with gpio_release(la=[4])`. The other pin owners point to `uart_close` and `sensor_stop`; a pull conflict to `set_pull(las=[7], pull="off")`. diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py index de5aa64..35217d1 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py @@ -9,7 +9,7 @@ Start every session with: 1. connect — a host[:port] or 'embeddedci:'. Omit it to use the server default (--connection, else BENCHPOD_CONNECTION, else the connection saved with `benchpod set-connection`); with none configured, connect finds the one pod on the LAN over mDNS, and if it finds none or several its error lists them and what to pass instead (a host, 'usb', or a cloud pod from cloud_list_devices). With firmware 3.9.0 and later, 'usb' reaches the full API over the pod's USB network adapter (unless Wi-Fi is configured on the pod, which turns USB networking off; status then reports kind 'usb_net' when it worked). With several pods plugged into one computer, 'usb' errors and lists them by name; pick one with 'usb:' (for example 'usb:benchpod-baea06'). A serial device path, or 'usb' that fell back to the console (kind 'serial'), only supports status, LA voltage and power on an STM32 pod; everything else needs the network, the USB network or cloud. -2. The I/O voltage (1.8 or 3.3, the DUT's) comes from the wiring profile's la_mv: connect sets it, so status normally reports one. When status warns that none is selected, the profile sets none: ask the user for the board's I/O voltage and set it in the profile (set_wiring with la_mv, then save_wiring), or call set_la_voltage for this session. The pod refuses flash, UART, LA capture, pull resistors and sensor emulation until it is set. +2. The I/O voltage (1.8 or 3.3, the DUT's; 5.0 on a digital v3r4 pod, see set_la_voltage) comes from the wiring profile's la_mv: connect sets it, so status normally reports one. When status warns that none is selected, the profile sets none: ask the user for the board's I/O voltage and set it in the profile (set_wiring with la_mv, then save_wiring), or call set_la_voltage for this session. The pod refuses flash, UART, LA capture, pull resistors and sensor emulation until it is set. 3. status shows firmware, capabilities, the LA voltage and open sessions. Cloud pods: cloud_list_devices lists the pods registered on embeddedci.com (name, online) without connecting to any; connect to one with its `connection` ('embeddedci:'). Tools named cloud_* talk to embeddedci.com, not to a pod. Test runs (benchpod ci, pytest --embeddedci-upload, build_report): cloud_runs_list finds them, cloud_run_get shows the failed cases and measurements outside their limits, cloud_run_trace the pod calls of a failed case, cloud_run_compare what changed since an earlier run. Cloud access (cloud_* and connect to 'embeddedci:') authenticates with BENCHPOD_API_KEY, else the user's `benchpod login` session; if neither exists, ask the user to run `benchpod login`. diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index 51145e4..8f1b264 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -161,7 +161,7 @@ def isa(name: str) -> bool: #: The firmware's "la voltage not set; ..." (any firmware version). _LA_VOLTAGE_UNSET = "la voltage not set" _LA_VOLTAGE_MCP = ("la voltage not set; the wiring profile sets no I/O voltage: ask the user " - "for the board's (1.8 or 3.3), set it in the profile (set_wiring with la_mv " + "for the board's (1.8 or 3.3, 5.0 on a digital v3r4 pod), set it in the profile (set_wiring with la_mv " "1800 or 3300, then save_wiring) or call set_la_voltage") #: Fixes the firmware spells as raw protocol commands (la_pins.c release_hint, the pull and @@ -435,7 +435,7 @@ def _status() -> m.StatusResult: "once that pin is released)") if la is None: warnings.append("LA I/O voltage not selected, and the wiring profile sets none: ask the user for " - "the board's I/O voltage (1.8 or 3.3) and set la_mv in the profile (set_wiring, " + "the board's I/O voltage (1.8 or 3.3, 5.0 on a digital v3r4 pod) and set la_mv in the profile (set_wiring, " "then save_wiring), or call set_la_voltage, before flash, UART, LA capture, " "pulls or sensor emulation") try: @@ -539,8 +539,8 @@ async def set_la_voltage(voltage: Annotated[Optional[Literal[1.8, 3.3, 5.0]], Fi takes it from the profile on the first LA operation. Call it when the profile sets none (ask the user), or to override the profile for this session. - At 5.0 the pod reads 5 V signals at full speed, and its outputs reach 5 V only through their - pull-ups: switch on the pull-up (set_pull up) on outputs into 5 V CMOS-level inputs. On digital + At 5.0 outputs reach 5 V only through their pull-ups: switch on the pull-up (set_pull up) on + outputs into 5 V CMOS-level inputs. Point the user to https://embeddedci.com/docs/benchpod-targets/5v-rs485#5v-io for the details. On digital v3r4 the result has pin21; when its state is high, tell the user a DUT signal is above the I/O voltage (select 5.0 or remove the signal). """ diff --git a/packages/embeddedci-mcp/tests/test_refusals.py b/packages/embeddedci-mcp/tests/test_refusals.py index f338f4d..8e5c8e2 100644 --- a/packages/embeddedci-mcp/tests/test_refusals.py +++ b/packages/embeddedci-mcp/tests/test_refusals.py @@ -89,7 +89,7 @@ def test_la_voltage_not_set_names_set_la_voltage(connected): with pytest.raises(ToolError) as info: call("gpio_pulse", la=3, width=0.001, count=5) assert str(info.value).endswith("FirmwareError: la: la voltage not set; the wiring profile sets no " - "I/O voltage: ask the user for the board's (1.8 or 3.3), set it in " + "I/O voltage: ask the user for the board's (1.8 or 3.3, 5.0 on a digital v3r4 pod), set it in " "the profile (set_wiring with la_mv 1800 or 3300, then save_wiring) " "or call set_la_voltage") diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 13e9505..4d95137 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -172,10 +172,9 @@ the wiring profile sets no I/O voltage: set la_mv in it (bp.save_wiring(bp.wirin **5 V I/O (digital board v3r4).** On a pod with the digital board v3r4 (`bp.supports("la_5v")`, `bp.capabilities.vref_out`), `bp.set_la_voltage(5.0)` (or `la_mv: 5000` in the profile) keeps the -bank at 3.3 V and switches J1 pin 21, the rail every pull-up pulls to, to 5 V. The pod reads 5 V -signals at full speed; its outputs reach 5 V only through their pull-ups, so switch the pull-up on -for outputs into 5 V CMOS-level inputs (`bp.set_pull(la, "up")`). The pod checks pin 21 and raises -`FirmwareError` `BP0028` when 5 V did not come up (a weak USB supply). Other pods raise +bank at 3.3 V and switches J1 pin 21, the pull-up rail, to 5 V; outputs reach 5 V through their +pull-up (`bp.set_pull(la, "up")`). What that means for the wiring is on the +[5 V page](https://embeddedci.com/docs/benchpod-targets/5v-rs485#5v-io). `FirmwareError` `BP0028`: 5 V did not come up. Other pods raise `ValueError` before anything is sent. On v3r4, `LaVoltage.pin21` reports pin 21 (`None` elsewhere): ```python @@ -1144,9 +1143,9 @@ firmware the call raises `UnsupportedFeatureError` before anything is sent. The stop bit of what it receives; a byte with a wrong parity bit is still delivered, and `bp.status()["uart_rx_parity_error"]` turns true for the session. -The LA pins are 1.8 V or 3.3 V only: the pod has no 5 V I/O and no RS-485 port. A 5 V UART needs a -level shifter, and Modbus RTU on RS-485 an external RS-485 transceiver powered at 3.3 V (or a 5 V -transceiver behind a level shifter), between the pod and the device. +No pod has an RS-485 port, and boards before the digital v3r4 have no 5 V I/O: a 5 V UART needs a +level shifter there, and Modbus RTU on RS-485 an external RS-485 transceiver powered at 3.3 V (or a +5 V transceiver behind a level shifter). The digital v3r4 has [5 V I/O](https://embeddedci.com/docs/benchpod-targets/5v-rs485#5v-io). **One wire (half duplex).** Some parts talk UART on a single pin, for example a boot ROM's programming pin. `half_duplex=True` runs the session on `rx` alone (`tx` defaults to the same diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 8e0fb8e..bf84b9a 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -1106,11 +1106,10 @@ def set_la_voltage(self, voltage: float) -> LaVoltage: """Select the LA I/O-bank voltage: ``1.8`` or ``3.3`` volts (1.8 V needs a rev3 pod), or ``5.0`` on a pod with the digital board v3r4 (feature ``la_5v``). - At 5.0 the pod keeps the bank at 3.3 V and switches J1 pin 21, the rail the pull-ups pull - to, to 5 V: it reads 5 V signals at full speed, and its outputs reach 5 V through their - pull-ups (switch them on for outputs into 5 V CMOS-level inputs). It checks pin 21 and - raises :class:`~embeddedci.benchpod.errors.FirmwareError` ``BP0025`` when 5 V did not - come up. :attr:`LaVoltage.pin21` reports pin 21. + At 5.0 the bank stays at 3.3 V, J1 pin 21 (the pull-up rail) goes to 5 V, and outputs + reach 5 V through their pull-ups: https://embeddedci.com/docs/benchpod-targets/5v-rs485#5v-io + Raises :class:`~embeddedci.benchpod.errors.FirmwareError` ``BP0028`` when 5 V did not come + up. :attr:`LaVoltage.pin21` reports pin 21. Match it to the DUT's I/O voltage. It must be set before any LA-bank operation (flashing, the UART proxy, LA capture, pull resistors, sensor emulation), or the pod refuses them with diff --git a/packages/embeddedci/src/embeddedci/benchpod/state.py b/packages/embeddedci/src/embeddedci/benchpod/state.py index 01a461f..92d9f15 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/state.py +++ b/packages/embeddedci/src/embeddedci/benchpod/state.py @@ -73,7 +73,8 @@ def from_reply(cls, d: Any) -> Optional["Pin21"]: class LaVoltage: """The LA I/O-bank voltage (``BenchPod.set_la_voltage`` / ``get_la_voltage``).""" - #: Selected bank voltage in volts (1.8 or 3.3), or ``None`` when none has been chosen yet — + #: Selected I/O voltage in volts (1.8 or 3.3; 5.0 in 5 V I/O on digital v3r4, where the bank + #: stays at 3.3 V), or ``None`` when none has been chosen yet — #: the pod refuses every LA-bank operation until one is. voltage: Optional[float] #: The measured bank voltage in volts, or ``None`` when the board cannot measure it. In 5 V diff --git a/packages/embeddedci/tests/test_digital_v3r4.py b/packages/embeddedci/tests/test_digital_v3r4.py index ac38188..0afa3e4 100644 --- a/packages/embeddedci/tests/test_digital_v3r4.py +++ b/packages/embeddedci/tests/test_digital_v3r4.py @@ -51,7 +51,7 @@ def command(self, req: dict) -> Any: raise firmware_error("la voltage must be 1800 or 3300 (mv)", cmd="la_voltage") if req["mv"] == 5000 and not self.five_v_ok: raise firmware_error("5 V did not come up on pin 21 (4120 mV); check the USB supply", - cmd="la_voltage", code="BP0025", values={"mv": 4120}) + cmd="la_voltage", code="BP0028", values={"mv": 4120}) self.mv = req["mv"] self.pin21_mv = 4920 if self.mv == 5000 else self.mv out: Dict[str, Any] = {"mv": self.mv, "st": 1, "readback_mv": 3300 if self.mv == 5000 else self.mv} @@ -130,7 +130,7 @@ def test_5v_that_did_not_come_up(): pod.five_v_ok = False with pytest.raises(FirmwareError) as e: bp.set_la_voltage(5.0) - assert e.value.code == "BP0025" + assert e.value.code == "BP0028" def test_other_voltages_name_5v_only_where_it_exists():