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

## 3.0.0

- Needs embeddedci 3.0. Wiring profiles live on the pod: `wiring` lists them and reports
`unsaved_changes` with a hint; new tools `save_wiring`, `load_wiring`, `set_default_wiring`,
`delete_wiring`; `connect(wiring_profile=)` and `power_on(wiring_profile=)`. `set_wiring` changes
this connection only (version 2: what it leaves out is undefined); `--wiring-autosave`
(`BENCHPOD_WIRING_AUTOSAVE`) also stores it, never a change of the I/O voltage, rail or SWD target.
- `power_on` applies the profile first (I/O voltage, then the rail) and names the profile in its
result.
- Refusals with a stable error code show the code, the fix for an agent and the docs link.


## 2.13.21

- Needs embeddedci 2.13.21. New `expansion` tool: attach an I2C/SPI GPIO expander board
Expand Down
13 changes: 9 additions & 4 deletions packages/embeddedci-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ chat never blocks CI on that pod.
| --- | --- | --- | --- |
| `--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 |
| `--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 |
| — | `BENCHPOD_WIRING` | — | wiring profile file (`.json`/`.toml`) that wins over the stored profile |
Expand Down Expand Up @@ -177,7 +178,7 @@ description, ranges and enums, so an agent sees more than this table.

| Tool | Purpose | Parameters |
| --- | --- | --- |
| `connect` | Open a connection (closing any previous one) and report status, capabilities and where the wiring profile came from. Without a `connection` or a configured default (`--connection`, `BENCHPOD_CONNECTION`, the CLI's saved connection), finds the one pod on the LAN over mDNS. | `connection`, `la_voltage`, `lease_wait=30` |
| `connect` | Open a connection (closing any previous one) and report status, capabilities and where the wiring profile came from. Without a `connection` or a configured default (`--connection`, `BENCHPOD_CONNECTION`, the CLI's saved connection), finds the one pod on the LAN over mDNS. `wiring_profile` names a profile stored on the pod (default: the pod's default profile). | `connection`, `la_voltage`, `lease_wait=30`, `wiring_profile` |
| `disconnect` | Close UART/CAN sessions and the connection, releasing a cloud lease. | none |
| `status` | Firmware, capabilities, LA voltage, open sessions and warnings (works when not connected); `eth_mac` and `wifi_mac`, the MACs a network admin registers before the pod gets an address (from the pod with firmware after 3.10.7, else from embeddedci.com's record; `wifi_mac` null until the pod scanned for Wi-Fi or joined). | none |
| `set_la_voltage` | Select the LA I/O voltage to match the DUT (1.8 V needs a rev3 pod). | **`voltage`** |
Expand All @@ -192,14 +193,18 @@ description, ranges and enums, so an agent sees more than this table.

| Tool | Purpose | Parameters |
| --- | --- | --- |
| `wiring` | Which DUT signal is on which LA channel, plus the power rail, UART baud and SWD target. | none |
| `set_wiring` | Replace the wiring profile for this connection, or store it on embeddedci.com. Also sends the profile's pin directions to the pod (`la_dir`, firmware 3.10.4+; `directions` in the result says whether it worked). | **`profile`**, `save=false` |
| `wiring` | Which DUT signal is on which LA channel, plus the I/O voltage, power rail, UART baud and SWD target; the profiles stored on the pod and `unsaved_changes` (what this connection changed that is not stored). What a profile does not set is undefined. | none |
| `set_wiring` | Replace the wiring profile for this connection only (version 2: what it leaves out is undefined); `save=true`, or the server's `--wiring-autosave`, also stores it on the pod. Autosave never stores a change of the I/O voltage, rail or SWD target. Also sends the profile's pin directions to the pod (`la_dir`, firmware 3.10.4+). | **`profile`**, `save=false` |
| `save_wiring` | Store this connection's profile (or `profile`) on the pod, under `name` or the profile it was loaded from. Saving the loaded profile refuses with `BP0009` when someone else saved it meanwhile. Never changes the pod's default. | `name`, `profile` |
| `load_wiring` | Switch this connection to a profile stored on the pod (omit `name`: the pod's default). Nothing on the pod changes. | `name` |
| `set_default_wiring` | Make a stored profile the pod's default: what every connection uses when it names none. | **`name`** |
| `delete_wiring` | Delete a stored profile (not the default: `BP0013`). | **`name`** |

### Power

| Tool | Purpose | Parameters |
| --- | --- | --- |
| `power_on` | Switch the target's power rail on (optionally scheduled pod-side). | `efuse`, `delay` |
| `power_on` | Power the board on with its wiring profile applied first: the profile's I/O voltage (when the pod has none or another one), then the rail; the pod records the profile. Never changes the I/O voltage under a powered board. `wiring_profile` powers on with a stored profile. | `efuse`, `delay`, `wiring_profile` |
| `power_off` | Switch the target's power rail off. | `efuse`, `delay` |
| `power_status` | Both target-power rails, internal 5 V (efuse 1) and external (efuse 2): on/off, tripped, bus voltage and current, and the pod's own draw. | none |
| `reset_target` | Drive the DUT's reset line from the pod's reset pin. | `action=pulse`, `pulse=0.1` |
Expand Down
4 changes: 2 additions & 2 deletions packages/embeddedci-mcp/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "embeddedci-mcp"
version = "2.13.21"
version = "3.0.0"
description = "MCP server that lets AI agents drive an EmbeddedCI BenchPod hardware-in-the-loop bench"
readme = "README.md"
requires-python = ">=3.10"
Expand All @@ -26,7 +26,7 @@ classifiers = [
dependencies = [
# cloud: the embeddedci:<device> destination; discovery: connect("discover") over mDNS;
# analysis: dominant frequency in capture summaries; yaml: sensor definitions an agent writes.
"embeddedci[cloud,discovery,analysis,yaml]>=2.13.21,<3",
"embeddedci[cloud,discovery,analysis,yaml]>=3.0.0,<4",
"mcp>=1.12,<2",
"anyio>=4",
"pydantic>=2.7",
Expand Down
4 changes: 2 additions & 2 deletions packages/embeddedci-mcp/server.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"name": "io.github.embeddedci-com/embeddedci-mcp",
"title": "EmbeddedCI BenchPod",
"description": "Drive a BenchPod hardware-in-the-loop bench: power, flash, UART, I2C, CAN, analog and logic.",
"version": "2.13.21",
"version": "3.0.0",
"websiteUrl": "https://www.embeddedci.com/docs/benchpod-mcp",
"repository": {
"url": "https://github.com/embeddedci-com/embeddedci-python",
Expand All @@ -15,7 +15,7 @@
"registryType": "pypi",
"registryBaseUrl": "https://pypi.org",
"identifier": "embeddedci-mcp",
"version": "2.13.21",
"version": "3.0.0",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
Expand Down
6 changes: 6 additions & 0 deletions packages/embeddedci-mcp/src/embeddedci_mcp/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@ def build_parser() -> argparse.ArgumentParser:
"'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,
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"),
help="set_wiring also stores the profile on the pod, except a change of the I/O voltage, "
"the power rail or the SWD target. Falls back to BENCHPOD_WIRING_AUTOSAVE. Default: off "
"(the agent calls save_wiring).")
parser.add_argument("--lease-wait", type=float, default=30.0,
help="Cloud: seconds connect waits for a busy shared device (default 30).")
parser.add_argument("--idle-timeout", type=float, default=600.0,
Expand Down Expand Up @@ -71,6 +76,7 @@ def main(argv: Optional[Sequence[str]] = None) -> None:

SESSION.default_connection = args.connection
SESSION.default_la_voltage = args.la_voltage
SESSION.wiring_autosave = bool(args.wiring_autosave)
SESSION.lease_wait = args.lease_wait
SESSION.idle_timeout = max(0.0, args.idle_timeout)
SESSION.timeout = args.timeout
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. 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 (the one stored on embeddedci.com and shown in the web UI's Wiring tab when the pod is registered and the user is signed in; `source` says where it came from): which DUT signal is on which channel, 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"). Confirm it with the user if it looks wrong; `set_wiring` replaces it (save=true stores it on embeddedci.com). 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. 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
32 changes: 24 additions & 8 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -166,22 +166,36 @@ class WiringResult(BaseModel):
"""The bench's effective wiring profile: which DUT signal is on which LA channel."""

source: str = Field(description=(
"Where the profile came from: server (stored on embeddedci.com for this pod, over the cloud "
"or, signed in, over the LAN/USB), file (BENCHPOD_WIRING), dict (set_wiring) or defaults."))
version: int = 1
la_voltage: float = Field(description="LA I/O-bank voltage the profile asks for, in volts.")
efuse: int = Field(description=(
"Target-power rail the tools default to: internal 5 V (efuse 1) or external (efuse 2)."))
"Where the profile came from: pod (a profile stored on the pod), file (BENCHPOD_WIRING), dict "
"(set_wiring, not saved), server (older firmware: the profile on embeddedci.com) or undefined "
"(nothing is wired)."))
version: int = 2
profile_name: str = Field("", description=(
"The pod profile this connection uses ('' when it came from elsewhere)."))
profile_rev: int = Field(0, description="That profile's revision on the pod when it was loaded.")
default_profile: Optional[str] = Field(None, description="The pod's default profile.")
profiles: List[Dict[str, Any]] = Field(default_factory=list, description=(
"The profiles stored on the pod: [{name, rev, bytes}]. Empty on firmware that stores none."))
unsaved_changes: List[str] = Field(default_factory=list, description=(
"Keys of this connection's profile that differ from the copy stored on the pod: lost on "
"disconnect unless saved (save_wiring)."))
hint: Optional[str] = Field(None, description="What to do next about saving, when anything.")
autosave: bool = Field(False, description="The server saves set_wiring's profile on the pod (--wiring-autosave).")
la_voltage: Optional[float] = Field(description=(
"LA I/O-bank voltage the profile asks for, in volts; null when it sets none."))
efuse: Optional[int] = Field(description=(
"Target-power rail the tools default to: internal 5 V (efuse 1) or external (efuse 2); null "
"when the profile sets none (pass efuse)."))
uart_baud: int
i2c_address: int = Field(description="The profile's I2C address (i2c_addr) as a 7-bit integer.")
i2c_address: Optional[int] = Field(description="The profile's I2C address (i2c_addr) as a 7-bit integer; null when unset.")
swd_nreset: bool
swd_target: str
pins: List[WiringPin] = Field(description="LA1-LA14 with what is wired to each and its bias resistor.")
signals: List[WiringSignal] = Field(default_factory=list)
warnings: List[str] = Field(default_factory=list,
description="Wiring that works but is risky (e.g. an I2C bus with no pull-up).")
profile: Dict[str, Any] = Field(default_factory=dict, description="The profile as its JSON object.")
saved: bool = Field(False, description="set_wiring stored this profile on embeddedci.com.")
saved: bool = Field(False, description="This call stored the profile (on the pod, or on embeddedci.com for older firmware).")
directions: Optional[str] = Field(None, description=(
"'sent' when the pod has the profile's pin directions (la_dir: sent on connect and by "
"set_wiring), else 'not sent: <why>' (older firmware, or a DUT output pin driven right now)."))
Expand Down Expand Up @@ -276,6 +290,8 @@ class GpioReleaseResult(BaseModel):
# -- power -----------------------------------------------------------------------

class PowerResult(BaseModel):
profile: Optional[str] = Field(None, description="The wiring profile the board was powered on with.")
la_voltage: Optional[float] = Field(None, description="The I/O voltage the profile set before power-on.")
efuse: int = Field(description="The rail used: internal 5 V (efuse 1) or external (efuse 2).")
on: bool
delay: Optional[float] = None
Expand Down
Loading