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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions packages/embeddedci-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

## 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
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.
Expand Down
4 changes: 2 additions & 2 deletions packages/embeddedci-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<name>`, `discover`, `saved`, or `embeddedci:<device>`; 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 |
Expand Down Expand Up @@ -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")`.
Expand Down
2 changes: 1 addition & 1 deletion packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:<name>', or 'embeddedci:<device>'. 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"),
Expand Down
2 changes: 1 addition & 1 deletion packages/embeddedci-mcp/src/embeddedci_mcp/guide.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

Start every session with:
1. connect — a host[:port] or 'embeddedci:<device>'. 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:<name>' (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:<name>'). 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:<name>') authenticates with BENCHPOD_API_KEY, else the user's `benchpod login` session; if neither exists, ask the user to run `benchpod login`.
Expand Down
24 changes: 23 additions & 1 deletion packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)."))
Expand Down Expand Up @@ -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 ----------------------------------------------------------------
Expand Down Expand Up @@ -549,6 +566,11 @@ 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
#: 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):
Expand Down
47 changes: 35 additions & 12 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -478,8 +478,9 @@ async def connect(
"'discover' (mDNS) or 'embeddedci:<device-name>' (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,
Expand Down Expand Up @@ -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 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).
"""
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 -------------------------------------------------------------------
Expand Down Expand Up @@ -1644,7 +1664,9 @@ 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),
held=getattr(state, "held", None))


def _sdk_pulls_by_direction(pod: Any) -> bool:
Expand Down Expand Up @@ -1672,9 +1694,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:
Expand Down
7 changes: 5 additions & 2 deletions packages/embeddedci-mcp/tests/test_e2e_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion packages/embeddedci-mcp/tests/test_refusals.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down
6 changes: 4 additions & 2 deletions packages/embeddedci-mcp/tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------------------------------
Expand Down Expand Up @@ -598,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}
"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"):
Expand Down
Loading