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

## 4.0.0

Pairs with BenchPod firmware 4.0.0 and embeddedci 4.0. Breaking changes:

- **Firmware 4.0 or later only.** `connect` to a pod with firmware 3.x fails with
`FirmwareTooOldError`, which tells the agent to have the user update the pod's firmware
(`benchpod flash-self` or the web app). The instructions say so too.
- `generate` returns no `bits` (the pod always plays 16 bits).
- A serial device path (the USB console) supports `status` only.
- **Refusals by code only.** Every coded refusal is rendered from the catalog with its MCP fix
(`fix.mcp`, naming this server's tools); the text rewrites of raw protocol commands are gone. A
refusal without a code keeps the pod's text.
- `connect` to a LAN address uses TLS on 8443 by default; mDNS discovery connects to the pod's
TLS port and refuses a pod with firmware 3.x.
- **Tool parameters in units.** Seconds end in `_s`: `connect` `lease_wait_s`, `power_on`/
`power_off` `delay_s`, `measure_power` `duration_s`, `power_profile_start` `max_duration_s`,
`reset_target` `pulse_s`, `flash` `timeout_s`, `capture_uart` `duration_s`,
`power_cycle_and_capture` `delay_s`/`duration_s`/`off_settle_s`, `uart_read` `timeout_s`,
`gpio_wait` `timeout_s`, `gpio_pulse` `width_s`, `capture_adc`/`capture_la`/
`capture_correlated` `trigger_timeout_s` and `stop_dac_after_s`, `generate` `duration_s`,
`can_read` `timeout_s`, `la_step` `delay_s` (as `sensor_fault` `duration_s` and the vision
tools already were). The I/O voltage is `la_voltage` everywhere (`set_la_voltage` took
`voltage`).
- `set_pull` takes `la` (a list of channels) and a required `pull`; `las` and `enabled` are gone.
- `replay` takes `waveform_id` (with `window_start`, `window_len`, `target_samples`) for a
cloud-library waveform; the `replay_waveform` tool is gone.
- `usb_network` takes `enabled=false` (was `set="off"`) and returns `enabled` (was `setting`).
- `status` warns when `module.dac_pinout_ok` is false: the DAC is off because the digital board
and the analog module do not belong together (`BP0080`).

## 3.0.6

Never released: its changes ship in 4.0.0.

- 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
Expand Down
60 changes: 30 additions & 30 deletions packages/embeddedci-mcp/README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion packages/embeddedci-mcp/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]>=3.0.5,<4",
"embeddedci[cloud,discovery,analysis,yaml]>=4.0.0.dev0,<5",
"mcp>=1.12,<2",
"anyio>=4",
"pydantic>=2.7",
Expand Down
19 changes: 9 additions & 10 deletions packages/embeddedci-mcp/src/embeddedci_mcp/guide.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,28 +8,28 @@
Drive an EmbeddedCI BenchPod: a hardware-in-the-loop tester wired to a real target board (the DUT).

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.
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). '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; everything else needs the network, the USB network or cloud. This server needs pod firmware 4.0.0 or later: FirmwareTooOldError on connect means the pod runs firmware 3.x; tell the user to update it (benchpod flash-self, or the firmware update in the web app).
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`.

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.
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 PinConflictError BP0031 ("LA4 is in use by gpio; free LA4 first: gpio_release(la=[4]) ..."): the error names the tools that free the channel (gpio_release, uart_close, sensor_stop); la_pins shows every channel's owner. Captures observe all 14 channels whatever owns them.

More GPIOs: expansion(chip, addr, sda, scl) attaches an I2C/SPI expander breakout (tca9555, mcp23017, pcf8574, 74hc595, ...; expansion() lists them) on 2-5 LA channels and names its pins EXT1..EXTn. gpio_mode, gpio_write, gpio_read, gpio_wait and gpio_release then take 'EXTn' (or names given with names=) next to LA channels; each call is a bus transaction (milliseconds), so gpio_pulse, triggers and la_dir refuse EXT pins. expansion(detach=true) puts every EXT pin back to input.

Typical flows:
- Flash and boot: flash(file) then power_cycle_and_capture(until_regex) — with a wiring profile that is all; otherwise pass swclk, swdio, target, nreset and rx, tx.
- SPI flash (a 25-series chip on four LA pins, wiring spi_sclk/spi_mosi/spi_miso/spi_cs): spi_flash_info to see it answers, then spi_flash_program(file, addr); hold_reset=true keeps the DUT off the bus. spi_transfer talks to any other SPI device.
- I2C master (gateware v55+): set_pull([sda, scl], pull="up"), i2c_open, then i2c_transfer(addr, write_hex, read) or i2c_scan; i2c_close. capture_la(send={...}) runs one I2C, SPI or gpio transaction right after the capture arms and triggers on it. la_dir marks DUT outputs so the pod never drives against them; connect and set_wiring send the wiring profile's directions (firmware 3.10.4+), so this is on by default.
- I2C master (gateware v55+): set_pull(la=[sda, scl], pull="up"), i2c_open, then i2c_transfer(addr, write_hex, read) or i2c_scan; i2c_close. capture_la(send={...}) runs one I2C, SPI or gpio transaction right after the capture arms and triggers on it. la_dir marks DUT outputs so the pod never drives against them; connect and set_wiring send the wiring profile's directions, so this is on by default.
- Interactive console: uart_open, power_on, uart_read(until_regex), uart_write, uart_close.
- Emulate sensors (I2C, SPI, UART, analog; firmware with the 'sensors' capability): the pod plays a sensor from a definition. sensor_library lists ready ones (bme280, bmp280, sht4x, mpu6050, gps_nmea, ...) and sensor_show gives one's YAML and params. For I2C, set_pull([sda, scl], pull="up") on LA1-LA6 (LA7/LA8 pull down only) first. sensor_start(definition=<name or YAML>, pins={sda, scl} | {tx} | ...), then sensor_set(instance, values) changes readings, sensor_stimulus_load + sensor_stimulus_start play values over time, sensor_fault injects a fault, sensor_status shows bus activity, sensor_capture waits for the DUT's next transaction on an I2C sensor's bus and decodes it, sensor_stop ends it. A part the library lacks: read sensor_format, write a definition from the datasheet, check it with sensor_validate, then sensor_start it. A GPS module is gps_nmea on pins={tx: <LA wired to the DUT RX>}.
- Emulate sensors (I2C, SPI, UART, analog; firmware with the 'sensors' capability): the pod plays a sensor from a definition. sensor_library lists ready ones (bme280, bmp280, sht4x, mpu6050, gps_nmea, ...) and sensor_show gives one's YAML and params. For I2C, set_pull(la=[sda, scl], pull="up") on LA1-LA6 (LA7/LA8 pull down only) first. sensor_start(definition=<name or YAML>, pins={sda, scl} | {tx} | ...), then sensor_set(instance, values) changes readings, sensor_stimulus_load + sensor_stimulus_start play values over time, sensor_fault injects a fault, sensor_status shows bus activity, sensor_capture waits for the DUT's next transaction on an I2C sensor's bus and decodes it, sensor_stop ends it. A part the library lacks: read sensor_format, write a definition from the datasheet, check it with sensor_validate, then sensor_start it. A GPS module is gps_nmea on pins={tx: <LA wired to the DUT RX>}.
- Analog: dac_output (DC), generate (sine/square/sawtooth) and replay drive the DAC and route its path; adc_read gives one calibrated value, capture_adc a waveform summary; dac_stop ends any DAC output.
- 4-20 mA input: adc_read(source='current_in') reads terminal J8 and returns current in amps (0.004 to 0.020 for a live loop) next to the voltage across the sense resistor (249 ohm; from analog module v3r5 100 ohm behind a 30 mA limiter, read in the low range by default, so a reading stuck near 28.5 to 31.5 mA is the limiter). calibration shows whether the pod has calibrated its ADC offset there. If not, analog readings can be off by up to about 50 mV: ask the user to disconnect J8, then calibrate (once per pod, stored on the pod; on firmware 3.9.3+ it corrects every ADC source).
- 4-20 mA output: current_out(current) holds a loop current on terminal J9, in amps (0.012 is 12 mA), and returns the current actually held and the range. It needs an external floating loop supply on J9 and cannot go below about 4 mA or above about 20 mA. It shares the DAC with the voltage outputs and switches them off; dac_stop does not return the loop to 4 mA, current_out(0.004) does. The loop must float: nothing in it may touch pod ground, also not through a target that shares a ground with the pod (SWD, UART). Ask the user how J9 is wired first, and never suggest wiring J9 straight into J8. generate, replay and replay_waveform take dac_path='current_out' to play a waveform as a current (levels in amps); capture_adc(source='current_in') summarises the loop current in amps.
- Gateware images: the FPGA runs either the 'loop' image (control_loop) or the 'deep_replay' image (replays longer than 2048 samples). control_loop, replay and replay_waveform switch automatically (~3 s; switched_image in the result says so). A switch resets the FPGA and stops any DAC output, UART session or sensor emulation, so start those after it. fpga_image switches explicitly. I2C/SPI/UART sensors run on a third, emulation image that sensor_start loads by itself (control_loop and deep replays are unavailable while it runs).
- 4-20 mA input: adc_read(source='current_in') reads terminal J8 and returns current in amps (0.004 to 0.020 for a live loop) next to the voltage across the sense resistor (249 ohm; from analog module v3r5 100 ohm behind a 30 mA limiter, read in the low range by default, so a reading stuck near 28.5 to 31.5 mA is the limiter). calibration shows whether the pod has calibrated its ADC offset there. If not, analog readings can be off by up to about 50 mV: ask the user to disconnect J8, then calibrate (once per pod, stored on the pod; it corrects every ADC source).
- 4-20 mA output: current_out(current) holds a loop current on terminal J9, in amps (0.012 is 12 mA), and returns the current actually held and the range. It needs an external floating loop supply on J9 and cannot go below about 4 mA or above about 20 mA. It shares the DAC with the voltage outputs and switches them off; dac_stop does not return the loop to 4 mA, current_out(0.004) does. The loop must float: nothing in it may touch pod ground, also not through a target that shares a ground with the pod (SWD, UART). Ask the user how J9 is wired first, and never suggest wiring J9 straight into J8. generate and replay take dac_path='current_out' to play a waveform as a current (levels in amps); capture_adc(source='current_in') summarises the loop current in amps.
- Gateware images: the FPGA runs either the 'loop' image (control_loop) or the 'deep_replay' image (replays longer than 2048 samples). control_loop and replay switch automatically (~3 s; switched_image in the result says so). A switch resets the FPGA and stops any DAC output, UART session or sensor emulation, so start those after it. fpga_image switches explicitly. I2C/SPI/UART sensors run on a third, emulation image that sensor_start loads by itself (control_loop and deep replays are unavailable while it runs).
- Logic: capture_la, then decode_la (i2c/uart/spi) re-decodes that capture without re-capturing, and la_timing measures edge times, pulse widths, frequency and the delay between two channels (e.g. trigger pin to result pin).
- Triggers: capture_adc, capture_la and capture_correlated take trigger_la (+ trigger_edge rising/falling/high/low, trigger_timeout seconds) to start on an event rather than immediately, so t = 0 is that edge. Without the trigger firing the tool fails with "TriggerTimeout: ...".
- Power profiles: measure_power(duration) reports the DUT's average/minimum/peak current, voltage, energy and charge over a window, with an optional trace (points). To profile across other tool calls, bracket them with power_profile_start and power_profile_stop.
Expand Down Expand Up @@ -63,9 +63,8 @@
ALARM (DUT output) LA5 signal "ALARM"
Target power internal 5 V (efuse 1) efuse=1 (external: efuse=2)

Pull resistors: set_pull(las, pull="up"|"down"|"off"); the pod picks the value. Today's boards
(pull_status shows each channel's supported directions; they pull to the LA voltage, 1.8 V or 3.3 V;
firmware 3.10.12 and older refuses them at 1.8 V):
Pull resistors: set_pull(la=[...], pull="up"|"down"|"off"); the pod picks the value. Today's boards
(pull_status shows each channel's supported directions; they pull to the LA voltage, 1.8 V or 3.3 V):
LA1, LA2 4.7k up LA3, LA4 2.2k up LA5, LA6 10k up
LA7, LA8 10k down only LA9-LA14 none

Expand Down
7 changes: 2 additions & 5 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,6 @@ class CapabilitiesInfo(BaseModel):
sensors: bool = Field(False, description=(
"Sensor emulation from definitions (sensor_start and the other sensor_* tools). Without it "
"the firmware is too old for sensor emulation."))
sensors_format: int = Field(0, description="The sensor definition format the pod reads (0 = not reported).")
flash_kb: int = Field(0, description="Internal flash of the pod's MCU in KiB (0 = not reported).")
ota_sig: bool = Field(False, description="Firmware updates are signed and the pod checks them.")
sig_policy: str = Field("", description="Signature policy: audit (report only) or required.")
Expand Down Expand Up @@ -773,8 +772,6 @@ class GenerateResult(BaseModel):
freq_hz: float
dac_path: str
cotrig: bool
bits: int = Field(default=8, description=(
"16 when the pod played the calibrated 16-bit waveform (firmware 3.9.1+), 8 for 8-bit levels."))


class StopResult(BaseModel):
Expand Down Expand Up @@ -992,6 +989,6 @@ class LogLevelResult(BaseModel):


class UsbNetworkResult(BaseModel):
"""The pod's USB network setting (firmware 3.9.0+)."""
setting: str = Field(description='"on" or "off": whether the pod\'s USB port is also a network adapter.')
"""The pod's USB network setting."""
enabled: bool = Field(description="Whether the pod's USB port is also a network adapter.")
note: str = Field("", description="What happens next, after a change.")
Loading
Loading