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
9 changes: 7 additions & 2 deletions packages/embeddedci-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,13 @@
agent to load the board's own profile by name and shows one consistent example, the
process-node bench's `process-node-stm32` profile (UART RX on LA3, I2C SCL on LA1 and SDA on LA2,
the alarm on LA5). It used to mix that bench's I2C pins with the default pins' UART RX (LA5).
- `set_wiring`'s `profile` description lists the `pulls` key (the LA channels whose pull
resistor `power_on` switches on).
- `set_wiring`'s `profile` description lists the `pulls` key: a map of LA channel to `up` /
`down`, or a list of channels that pull their own direction.
- `set_pull(las, pull="up" | "down" | "off")`: pull by direction; the pod picks the resistor.
`enabled` still works (true = each channel's own direction). Channels 1-14; a direction a
channel can't pull is refused (BP0024, BP0023 without a resistor).
- `pull_status` lists all 14 channels with `state` (up, down, off) and `supported` directions;
`la_pins` (and the gpio tools' pins) add `pull_dirs`.

## 3.0.2

Expand Down
8 changes: 4 additions & 4 deletions packages/embeddedci-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ description, ranges and enums, so an agent sees more than this table.
### I2C master

The pod as an I2C master on two LA pins (gateware v55+), to read and write registers of a chip on
the DUT's board. The bus needs pull-ups: the pod's on LA1-LA6 (`set_pull` first, LA voltage 3.3), or
the DUT's board. The bus needs pull-ups: the pod's on LA1-LA6 (`set_pull(pull="up")` first, LA voltage 3.3), or
the board's with `pullups="external"`.

| Tool | Purpose | Parameters |
Expand Down Expand Up @@ -293,8 +293,8 @@ version the SDK pins (0.1.0, bundled) unless `BENCHPOD_SENSOR_LIBRARY`, the CLI'

| Tool | Purpose | Parameters |
| --- | --- | --- |
| `set_pull` | Engage or release the bias resistors: LA1-LA6 pull up, LA7/LA8 pull down. | **`las`**, **`enabled`** |
| `pull_status` | State, direction and value of the bias resistor on LA1-LA8. | none |
| `set_pull` | Pull LA channels `up` or `down`, or switch their resistor `off`; the pod picks the value. Today LA1-LA6 pull up, LA7/LA8 down, LA9-LA14 have none; another direction is refused (BP0024, BP0023). `enabled` is the older on/off form. | **`las`**, `pull`, `enabled` |
| `pull_status` | Every LA channel's pull resistor: state (`up`, `down` or `off`), the directions it supports and its value. | none |
| `lan_tls` | The pod's LAN API over TLS (firmware 3.9.3+): port 8443, the HTTPS-only setting and the certificate's sha256 (what clients pin). Turning HTTPS-only off and regenerating need a TLS, USB or cloud connection. | `https_only`, `regenerate` |
| `usb_network` | Read the pod's USB network setting (firmware 3.9.0+), or turn the adapter off over the USB link. Only the device changes it; turning it back on is `benchpod usb-network on` on the USB console. | `set=off` |

Expand Down Expand Up @@ -445,7 +445,7 @@ capture tools' summaries, `la_timing` and `decode_la` instead.
the user for the board's (1.8 or 3.3), 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], enabled=false)`.
`sensor_stop`; a pull conflict to `set_pull(las=[7], pull="off")`.
- **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
11 changes: 6 additions & 5 deletions packages/embeddedci-mcp/src/embeddedci_mcp/guide.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@
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], true), 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([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.
- 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], true) on LA1-LA6 (LA7/LA8 pull DOWN) 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([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 249 ohm sense resistor. 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.
Expand Down Expand Up @@ -63,9 +63,10 @@
ALARM (DUT output) LA5 signal "ALARM"
Target power internal 5 V (efuse 1) efuse=1 (external: efuse=2)

Bias resistors (3V3-referenced, so unavailable while the LA bank is at 1.8 V):
LA1, LA2 4.7k pull-up LA3, LA4 2.2k pull-up LA5, LA6 10k pull-up
LA7, LA8 10k pull-DOWN LA9-LA14 none
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; 3V3-referenced, so off at a 1.8 V LA bank):
LA1, LA2 4.7k up LA3, LA4 2.2k up LA5, LA6 10k up
LA7, LA8 10k down only LA9-LA14 none

LA I/O bank: 1.8 V or 3.3 V, matching the DUT's I/O voltage: the wiring profile's la_mv (set_la_voltage overrides it for a session).

Expand Down
12 changes: 10 additions & 2 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,10 @@ class LaPinResult(BaseModel):
"swd_dio, i2c_sda, i2c_scl, step, step_dir, spi_*, sensor_*, or i2cm_sda/i2cm_scl (i2c_open)."))
gpio: Optional[str] = Field(None, description="GPIO mode when function is gpio: input, output or open_drain.")
level: Optional[int] = Field(None, description="Commanded level of a GPIO output / open-drain channel.")
pull: Optional[str] = Field(None, description="Bias direction: up, down, or null on LA9-LA14.")
pull: Optional[str] = Field(None, description=(
"The way its pull resistor pulls when on: up or down; null without one (LA9-LA14 today)."))
pull_dirs: Optional[List[str]] = Field(None, description=(
"Every direction set_pull can pull it: [up], [down], [up, down] or []."))
pull_ohms: Optional[str] = None
pull_on: bool = False
in_use: bool = Field(description="A function other than none owns the channel.")
Expand Down Expand Up @@ -532,8 +535,13 @@ class I2cRegsResult(BaseModel):

class PullChannel(BaseModel):
la: int
#: What the channel does now: up, down or off.
state: str
#: The directions it can pull (empty: no pull resistor).
supported: List[str]
enabled: bool
direction: str
#: The way it pulls when on; None without a resistor.
direction: Optional[str]
ohms: str
available: bool

Expand Down
77 changes: 59 additions & 18 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@
"LA channel 1-14, or a name from the wiring profile — a signal ('READY') or a role "
"('uart_rx', 'i2c_sda', 'swd_swclk'). Call `wiring` to see the names. The gpio_* tools also "
"take expander pins ('EXT1') once one is attached (expansion)."))]
BiasPin = Annotated[int, Field(ge=1, le=8)]
PullPin = Annotated[int, Field(ge=1, le=14)]
EfuseRail = Annotated[Literal[1, 2], Field(description="Target-power rail: internal 5 V (efuse 1) or external (efuse 2).")]
WiredEfuse = Annotated[Optional[Literal[1, 2]], Field(description=(
"Target-power rail: internal 5 V (efuse 1) or external (efuse 2). Omit for the wiring profile's rail."))]
Expand Down Expand Up @@ -192,9 +192,10 @@ def isa(name: str) -> bool:
(re.compile(r"send i2c_stop first"), "call i2c_close first"),
(re.compile(r"send i2c_start first"), "call i2c_open first"),
(re.compile(r"i2c_start again"), "call i2c_open again"),
(re.compile(r'\{"cmd":"la","la":(\d+),"pullup":"on"\}'), r"set_pull(las=[\1], enabled=true)"),
(re.compile(r'\{"cmd":"la","la":(\d+),"(?:pullup":"on|pull":"up)"\}'), r'set_pull(las=[\1], pull="up")'),
(re.compile(r'\{"cmd":"la","la":(\d+),"pull":"down"\}'), r'set_pull(las=[\1], pull="down")'),
(re.compile(r'pass "pullups":"external"'), 'pass pullups="external"'),
(re.compile(r'\{"cmd":"la","la":(\d+),"pullup":"off"\}'), r"set_pull(las=[\1], enabled=false)"),
(re.compile(r'\{"cmd":"la","la":(\d+),"(?:pullup|pull)":"off"\}'), r'set_pull(las=[\1], pull="off")'),
(re.compile(r'\{"cmd":"gpio","la":(\d+),"mode":"output"\}'), r'gpio_mode(la=[\1], mode="output")'),
(re.compile(r'\{"cmd":"fpga_image","image":0\}'), 'fpga_image(image="loop")'),
(re.compile(r'\{"cmd":"dac_loop_input"\}'), "loop_input"),
Expand Down Expand Up @@ -573,8 +574,9 @@ async def set_wiring(
profile: Annotated[Dict[str, Any], Field(description=(
"The profile as a JSON object (schema version 2): la_mv, efuse, uart_rx/uart_tx/uart_baud, "
"i2c_sda/i2c_scl/i2c_addr, swd_swclk/swd_swdio/swd_nreset/swd_target, spi_*, and signals "
"[{name, la, direction, active_low, description}], pulls (the LA channels whose pull resistor "
"power_on switches on, e.g. [1, 2]; LA1-LA8 have one, the others it switches off; left out: "
"[{name, la, direction, active_low, description}], pulls (the pull resistors power_on switches "
"on, the others off: {\"1\": \"up\", \"2\": \"up\", \"8\": \"down\"}, or a list of channels "
"that pull their own way, e.g. [1, 2]; today LA1-LA6 pull up, LA7/LA8 down; left out: "
"power_on leaves the pulls as they are). What it leaves out is undefined (not "
"wired); a pin set to null is not wired. {\"version\": 1} objects fill in the old default pins."))],
save: Annotated[bool, Field(description=(
Expand Down Expand Up @@ -956,7 +958,7 @@ async def i2c_open(
scl: Annotated[Optional[LaRef], Field(description="SCL channel; omit for the profile's i2c_scl.")] = None,
hz: Annotated[int, Field(ge=10_000, le=1_000_000, description="SCL rate.")] = 100_000,
pullups: Annotated[Literal["pod", "external"], Field(description=(
"pod: LA1-LA6 with the pod's pull-ups on (set_pull first, LA voltage 3.3); "
"pod: channels with the pod's pull-up on (set_pull(pull=\"up\") first, LA1-LA6 today, LA voltage 3.3); "
"external: the board has its own."))] = "pod",
) -> m.I2cSessionResult:
"""Make the pod an I2C master on two LA pins (gateware v55+), replacing any open session.
Expand Down Expand Up @@ -1415,7 +1417,7 @@ async def sensor_library(version: LibraryVersion = None) -> m.SensorLibraryResul
"""The sensor library: ready definitions the pod can emulate (name, kind, label) and the version in use.

Sensor flow: sensor_library -> sensor_show(name) for its params -> set_la_voltage and, for I2C,
set_pull on SDA/SCL -> sensor_start(definition=name, pins) -> sensor_set / sensor_fault /
set_pull(pull="up") on SDA/SCL -> sensor_start(definition=name, pins) -> sensor_set / sensor_fault /
sensor_stimulus_load + sensor_stimulus_start -> sensor_status, sensor_regs -> sensor_stop.
No library entry for the part? Write a definition from its datasheet (sensor_format) and pass
the YAML to sensor_validate, then sensor_start. Needs no pod.
Expand Down Expand Up @@ -1490,7 +1492,7 @@ async def sensor_start(
) -> m.SensorStarted:
"""Make the pod play a sensor for the DUT: upload the definition (library name or your own YAML/JSON) and start it on pins.

Set the LA voltage first, and the pull-ups for I2C (set_pull on sda and scl, LA1-LA6).
Set the LA voltage first, and the pull-ups for I2C (set_pull([sda, scl], pull="up"), LA1-LA6).
Starting an instance name that runs replaces it. Up to 4 I2C sensors (several may share one
bus at different addresses), 1 SPI, 1 UART and 2 analog sensors (one per output) run at once.
I2C/SPI/UART sensors load the pod's emulation FPGA image if another runs (image_loaded in the
Expand Down Expand Up @@ -1607,25 +1609,62 @@ def op() -> m.I2cCaptureResult:
return await _call(op)


# -- bias resistors ---------------------------------------------------------------------
# -- pull resistors ---------------------------------------------------------------------

def _pull(state: Any) -> m.PullChannel:
return m.PullChannel(la=state.la, enabled=state.enabled, direction=state.direction,
# embeddedci before 3.0.3 has no state / supported on PullState
direction = state.direction
supported = getattr(state, "supported", None)
if supported is None:
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)


def _sdk_pulls_by_direction(pod: Any) -> bool:
"""The SDK takes set_pull(la, "up" | "down" | "off") (embeddedci 3.0.3+)."""
return "pull" in inspect.signature(type(pod).set_pull).parameters


def _set_pull_old_sdk(pod: Any, la: int, want: Any) -> Any:
"""set_pull on embeddedci before 3.0.3, which only knows on/off: a direction is checked here,
so "up" never engages LA7's pull-down."""
from embeddedci.benchpod.constants import PULLDOWN_CHANNELS, PULLUP_CHANNELS

if want in ("up", "down"):
ok = PULLUP_CHANNELS if want == "up" else PULLDOWN_CHANNELS
if la not in ok:
raise ValueError(f"LA{la} can't pull {want} on this board; upgrade embeddedci for the full "
"message (pull_status shows each channel's direction)")
want = True
elif want == "off":
want = False
return pod.set_pull(la, bool(want))


@mcp.tool(annotations=_ann("Set pull resistors", idempotent=True))
async def set_pull(
las: Annotated[List[BiasPin], Field(min_length=1, max_length=8, description="LA channels (1-8).")],
enabled: bool,
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,
enabled: Annotated[Optional[bool], Field(description=(
"Older form, use pull: true engages each channel's own direction, false is off."))] = None,
) -> m.PullStatusResult:
"""Engage or release the fixed bias resistors: LA1-LA6 pull UP (I2C lines), LA7/LA8 pull DOWN.
"""Pull LA channels up or down, or switch their pull resistor off. For an I2C bus pull SDA and
SCL up. The resistors are 3V3-referenced, so the pod refuses to engage them with the LA bank at
1.8 V."""
if pull is None and enabled is None:
raise ValueError('set_pull needs pull: "up", "down" or "off"')
want: Any = pull if pull is not None else bool(enabled)

The resistors are 3V3-referenced, so the pod refuses to engage them with the LA bank at 1.8 V.
"""
def op() -> m.PullStatusResult:
pod = SESSION.require()
return m.PullStatusResult(channels=[_pull(pod.set_pull(la, enabled)) for la in las])
if _sdk_pulls_by_direction(pod):
return m.PullStatusResult(channels=[_pull(pod.set_pull(la, want)) for la in las])
return m.PullStatusResult(channels=[_pull(_set_pull_old_sdk(pod, la, want)) for la in las])

return await _call(op)

Expand Down Expand Up @@ -1683,10 +1722,12 @@ def op() -> m.LanTlsResult:

@mcp.tool(annotations=_ann("Pull resistor status", read_only=True))
async def pull_status() -> m.PullStatusResult:
"""State, direction and value of the bias resistor on LA1-LA8."""
"""Every LA channel's pull resistor: state (up, down or off), the directions it supports
(empty without a resistor) and its value."""
def op() -> m.PullStatusResult:
pod = SESSION.require()
return m.PullStatusResult(channels=[_pull(pod.pull_state(la)) for la in range(1, 9)])
las = range(1, 15) if _sdk_pulls_by_direction(pod) else range(1, 9)
return m.PullStatusResult(channels=[_pull(pod.pull_state(la)) for la in las])

return await _call(op)

Expand Down
Loading