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
13 changes: 13 additions & 0 deletions packages/embeddedci-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Changelog — `embeddedci-mcp`

## 3.0.6

- Every command carries `"client": "mcp <version>"` and the client API level (with embeddedci
after 3.0.5).
- **Client too old:** a pod whose firmware is newer than this server handles (it announces a
higher client API level, or refuses with `BP0030`) fails `connect` and every tool with
`ClientTooOldError`, saying to update the server (`uvx embeddedci-mcp@latest`,
`pip install -U embeddedci-mcp`, or the benchpod plugin) and reconnect. Needs embeddedci after
3.0.5; with 3.0.5 nothing changes.
- Refusals take their kind from the error code (embeddedci after 3.0.5): `PodBusyError` for an
open I2C or SPI session, `WiringError` for the wiring profiles, and so on. `BP0001` (I/O voltage
not set) keeps this server's text, which names `set_wiring` and `set_la_voltage`.

## 3.0.5

- Needs embeddedci 3.0.5.
Expand Down
11 changes: 11 additions & 0 deletions packages/embeddedci-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -456,6 +456,17 @@ capture tools' summaries, `la_timing` and `decode_la` instead.
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")`.
- **Error codes.** Firmware 3.10.8 and later sends a stable code with a refusal (`BP0009` ...): the
error then reads `<Kind>: <cmd>: BP0009: <what went wrong>; <the fix, as tool calls> (docs:
https://embeddedci.com/docs/errors#BP0009)`. The code is the stable part to act on, and it also
picks the kind (`PodBusyError` for an open I2C or SPI session, `WiringError` for the wiring
profiles, ...); the text may change between releases.
- **Client too old.** Every command carries the server's client API level (`client_api`) and
`"client": "mcp <version>"`. When the pod's firmware is newer than this server can talk to (it
announces a higher client API level on `connect`, or refuses a command with `BP0030`), the tool
fails with `ClientTooOldError` and says to update the server: `uvx embeddedci-mcp@latest`, or
`pip install -U embeddedci-mcp`, or update the benchpod plugin, then reconnect. Retrying does
not help. Firmware 3.10.13 and older does not announce a level and works as before.
- **Capabilities.** `connect` and `status` report what the pod can do as flags, so an agent can
check before it calls a tool: for example `la_pins`, `capture_trigger`, `power_profile`,
`nrst_pin`, `can`, `calibrate`, `cal_dmm`, `current_out`, `pod_current`, `sensors` and `analog` (false on the
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 @@ -14,7 +14,7 @@

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`.

Wiring: the pod has 14 generic LA channels (LA1-LA14) and nothing is fixed. Call `wiring` first: it is the bench's profile, normally one of the named profiles stored on the pod itself (the same ones the web app shows; `profile_name`, the pod's default unless connect(wiring_profile=...) named another): which DUT signal is on which channel, the I/O voltage, the target-power rail, the UART baud, the SWD target. Every channel, baud, rail or SWD argument you omit comes from it, and channel arguments also accept its names ("READY", "uart_rx"). What the profile does not set is undefined: when a tool says a pin is missing, ask the user which LA channel it is on, never guess. Confirm the wiring with the user if it looks wrong. `set_wiring` changes it for this connection only: nothing is stored until save_wiring (or the server's --wiring-autosave). Once the wiring works on the board, ask the user whether to save it, and under which name when it is a different board (save_wiring(name='nrf52840')). `unsaved_changes` in the result lists what is not stored; it is lost on disconnect. load_wiring switches to another stored profile, set_default_wiring changes the pod's default (ask first). power_on applies the profile first (its I/O voltage, then the rail) and records it on the pod. Refusals carry a stable code (BP0009 ...) with the fix; follow it. Target power is internal 5 V (efuse 1) or external (efuse 2). The DUT's reset line goes to the pod's own reset pin: flash(nreset=true), reset_target.
Wiring: the pod has 14 generic LA channels (LA1-LA14) and nothing is fixed. Call `wiring` first: it is the bench's profile, normally one of the named profiles stored on the pod itself (the same ones the web app shows; `profile_name`, the pod's default unless connect(wiring_profile=...) named another): which DUT signal is on which channel, the I/O voltage, the target-power rail, the UART baud, the SWD target. Every channel, baud, rail or SWD argument you omit comes from it, and channel arguments also accept its names ("READY", "uart_rx"). What the profile does not set is undefined: when a tool says a pin is missing, ask the user which LA channel it is on, never guess. Confirm the wiring with the user if it looks wrong. `set_wiring` changes it for this connection only: nothing is stored until save_wiring (or the server's --wiring-autosave). Once the wiring works on the board, ask the user whether to save it, and under which name when it is a different board (save_wiring(name='nrf52840')). `unsaved_changes` in the result lists what is not stored; it is lost on disconnect. load_wiring switches to another stored profile, set_default_wiring changes the pod's default (ask first). power_on applies the profile first (its I/O voltage, then the rail) and records it on the pod. Refusals carry a stable code (BP0009 ...) with the fix; follow it. ClientTooOldError means this MCP server is older than the pod's firmware: tell the user to update embeddedci-mcp (uvx embeddedci-mcp@latest, pip install -U embeddedci-mcp, or the benchpod plugin), then reconnect; retrying will not help. Target power is internal 5 V (efuse 1) or external (efuse 2). The DUT's reset line goes to the pod's own reset pin: flash(nreset=true), reset_target.

GPIO: each LA channel has one owner at a time. gpio_mode claims channels (input/output/open_drain), gpio_write drives them, gpio_read reads any channel's live level, gpio_wait polls for one, gpio_pulse emits FPGA-timed pulses, gpio_release frees them. Release a GPIO channel before uart_open, flash or sensor_start uses it, otherwise the pod refuses with "pin conflict: LA4 is in use by gpio; release it with gpio_release(la=[4])": the error names the tool that frees the channel (gpio_release, uart_close, sensor_stop); la_pins shows every channel's owner. Captures observe all 14 channels whatever owns them.

Expand Down
50 changes: 50 additions & 0 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@
from embeddedci.benchpod.cloud_auth import DEFAULT_API_BASE
from embeddedci.benchpod.connection import CLOUD_PREFIX
from embeddedci.benchpod import errors as _errors
from embeddedci.benchpod import protocol as _protocol
from embeddedci.benchpod.errors import STATUS_FITS_FIRMWARE, FirmwareError, status_too_large
from embeddedci.benchpod.errors import BenchPodError
from embeddedci.benchpod.server_api import ServerApi
Expand Down Expand Up @@ -224,6 +225,49 @@ def _error_text(exc: BenchPodError) -> str:
return f"{cmd}: {text}" if cmd else text


#: How to update this server, for a pod whose firmware is newer than it handles.
_MCP_UPDATE = ("update embeddedci-mcp: uvx embeddedci-mcp@latest or pip install -U embeddedci-mcp, "
"or update the benchpod plugin; then reconnect")


def _mcp_version() -> str:
try:
from importlib.metadata import version
return version("embeddedci-mcp")
except Exception: # a source tree without install
return "unknown"


def _name_this_client() -> None:
"""Requests from this server carry ``"client": "mcp <version>"`` (embeddedci after 3.0.5)."""
set_name = getattr(_protocol, "set_client_name", None)
if callable(set_name):
set_name(f"mcp {_mcp_version()}")


_name_this_client()


def _client_too_old_text(exc: BenchPodError) -> Optional[str]:
"""The ClientTooOldError of embeddedci after 3.0.5 (a pod above this server's client API
level on connect, or the pod's BP0030), told as what to update: this server, not the SDK."""
cls = getattr(_errors, "ClientTooOldError", None)
if cls is None or not isinstance(exc, cls):
return None
fw = getattr(exc, "firmware_version", "") or ""
pod = f"the pod's firmware {fw}" if fw else "the pod's firmware"
have, api, need = (getattr(exc, "client_api", 0), getattr(exc, "api", 0),
getattr(exc, "min_client_api", 0))
if getattr(exc, "code", "") == "BP0030":
why = f"{pod} needs client API {need or '?'} or newer, this server sent {have}"
else:
why = f"{pod} speaks client API {api or '?'}, this server handles {have}"
cmd = getattr(exc, "cmd", None)
text = (f"this BenchPod MCP server (embeddedci-mcp {_mcp_version()}) is too old for this pod: "
f"{why}. Tell the user to {_MCP_UPDATE}")
return f"{cmd}: {text}" if cmd else text


def _coded_text(exc: BenchPodError) -> Optional[str]:
"""A refusal with a stable error code, rendered with the catalog's fix for an agent."""
from embeddedci.benchpod.errors import error_catalog
Expand All @@ -234,11 +278,17 @@ def _coded_text(exc: BenchPodError) -> Optional[str]:
values = getattr(exc, "values", {}) or {}
fill = lambda t: re.sub(r"\{([a-z0-9_]+)\}", lambda m: str(values.get(m.group(1), "?")), t) # noqa: E731
cmd = getattr(exc, "cmd", None)
if code == "BP0001": # this server's own text, as for firmware without codes
text = f"{code}: {_LA_VOLTAGE_MCP} (docs: {exc.docs_url})"
return f"{cmd}: {text}" if cmd else text
text = f"{code}: {fill(entry['message'])}; {fill(entry['fix']['mcp'])} (docs: {exc.docs_url})"
return f"{cmd}: {text}" if cmd else text


def _tool_error(exc: BenchPodError) -> ToolError:
too_old = _client_too_old_text(exc)
if too_old:
return ToolError(f"{type(exc).__name__}: {too_old}")
coded = _coded_text(exc)
if coded:
return ToolError(f"{type(exc).__name__}: {coded}")
Expand Down
53 changes: 53 additions & 0 deletions packages/embeddedci-mcp/tests/test_refusals.py
Original file line number Diff line number Diff line change
Expand Up @@ -172,3 +172,56 @@ def test_status_reports_the_macs(connected):
connected.status = lambda: dict(real(), eth_mac="02:35:c7:76:b7:9b", wifi_mac="7c:e8:b1:c5:ca:6c")
result = call("status")
assert result["eth_mac"] == "02:35:c7:76:b7:9b" and result["wifi_mac"] == "7c:e8:b1:c5:ca:6c"


# -- the client API level (embeddedci after 3.0.5) ---------------------------------------------

needs_client_api = pytest.mark.skipif(not hasattr(errors, "ClientTooOldError"),
reason="needs ClientTooOldError (embeddedci after 3.0.5)")


@needs_client_api
def test_requests_name_this_server():
from embeddedci.benchpod import protocol

assert protocol.client_name().startswith("mcp ")


@needs_client_api
def test_a_pod_above_this_servers_level_fails_the_connect(fake_open, fake_transport):
real = fake_transport.status
fake_transport.status = lambda: {**real(), "version": "3.11.0", "api": 2, "min_client_api": 1}
with pytest.raises(ToolError) as info:
call("connect", connection="192.168.1.50", la_voltage=3.3)
msg = str(info.value)
assert "ClientTooOldError: this BenchPod MCP server (embeddedci-mcp " in msg
assert "the pod's firmware 3.11.0 speaks client API 2, this server handles 1" in msg
assert "uvx embeddedci-mcp@latest" in msg and "pip install -U embeddedci-mcp" in msg
assert "benchpod plugin" in msg and "pip install -U embeddedci " not in msg


@needs_client_api
def test_bp0030_on_a_tool_says_to_update_this_server(connected):
def command(req):
raise firmware_error("update the BenchPod SDK, MCP or CLI", cmd=req["cmd"], code="BP0030",
values={"client_api": 1, "min_client_api": 2, "api": 2})

connected.command = command
with pytest.raises(ToolError) as info:
call("gpio_pulse", la=3, width=0.001, count=5)
msg = str(info.value)
assert "ClientTooOldError: la: this BenchPod MCP server" in msg
assert "needs client API 2 or newer, this server sent 1" in msg
assert "uvx embeddedci-mcp@latest" in msg


def test_coded_la_voltage_keeps_this_servers_text(connected):
def command(req):
raise firmware_error("la voltage not set; set la_mv ...", cmd=req["cmd"], code="BP0001")

connected.command = command
with pytest.raises(ToolError) as info:
call("gpio_pulse", la=3, width=0.001, count=5)
msg = str(info.value)
assert "la: BP0001: la voltage not set; the wiring profile sets no I/O voltage" in msg
assert "call set_la_voltage" in msg
18 changes: 18 additions & 0 deletions packages/embeddedci/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
# Changelog — `embeddedci`

## 3.0.6

- **Error codes decide the exception class.** Every code in the error catalog (`BP0001` to
`BP0030`) maps to one class, and the code's values fill its fields; the text decides only for a
refusal without a code (older firmware) or with a code newer than this SDK. New `WiringError`
(`BP0007` to `BP0015`, with `name`). `BP0003` and `BP0004` (an I2C or SPI session is open),
`BP0005` (the SWD/SPI/I2C engine is busy) and `BP0016` (storage busy) raise `PodBusyError`;
`BP0017` (gateware too old) raises `UnsupportedFeatureError` with the feature from the code.
Match on `exc.code` or the class, not the text. README: [Error codes](README.md#error-codes).
- **Client API level.** Every JSON command carries `"client_api": 1` and `"client": "sdk
<version>"` (firmware 3.10.13 and older ignores them). `feature_map.CLIENT_API` is the level this
SDK handles; `Capabilities.api`, `min_client_api` and `client_api_level` are the pod's (firmware
after 3.10.13; a pod that does not say counts as 1). Connecting to a pod above the SDK's level,
or the pod's refusal `BP0030`, raises the new `ClientTooOldError`: update the SDK with
`pip install -U embeddedci`.
- Error catalog: `BP0030` (client too old). Features table revision 8, with `api` and
`min_client_api`.

## 3.0.5

- `la_pins(la=...)` lists only those channels (firmware after 3.10.12 sends only them; older
Expand Down
Loading