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
3 changes: 3 additions & 0 deletions packages/embeddedci-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
- Needs embeddedci 3.0.2. `uart_open`, `capture_uart` and `power_cycle_and_capture` take the
frame from the wiring profile (`uart_parity`, `uart_stop_bits`) when `parity` / `stop_bits` are
omitted; `uart_open` reports the frame it used.
- `uart_open` and `capture_uart` take `half_duplex` (a one-wire UART on `rx`) and `entry`
(`reset_ms`, `tx_low`, `hold_ms`, `idle_ms`, `data_hex`: a boot-mode entry the pod times before
the session). Needs gateware v57.

## 3.0.1

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 @@ -253,9 +253,9 @@ the board's with `pullups="external"`.

| Tool | Purpose | Parameters |
| --- | --- | --- |
| `capture_uart` | Record the DUT's UART for a window, or until a regex matches. | **`duration`**, `rx`, `tx`, `baud`, `until_regex`, `parity`, `stop_bits` |
| `capture_uart` | Record the DUT's UART for a window, or until a regex matches. | **`duration`**, `rx`, `tx`, `baud`, `until_regex`, `parity`, `stop_bits`, `half_duplex`, `entry` |
| `power_cycle_and_capture` | Power-cycle the target and capture UART across the boot. | `rx`, `tx`, `efuse`, `delay=1`, `duration=4`, `baud`, `until_regex`, `off_settle=0.3`, `parity`, `stop_bits` |
| `uart_open` | Start buffering the DUT's UART in the background. The frame is the profile's (`uart_parity`, `uart_stop_bits`; 8N1 unless set) unless `parity` (`none`/`even`/`odd`) or `stop_bits` (1/2) say otherwise; anything but 8N1 needs firmware 3.10.8+. | `rx`, `tx`, `baud`, `parity`, `stop_bits` |
| `uart_open` | Start buffering the DUT's UART in the background. The frame is the profile's (`uart_parity`, `uart_stop_bits`; 8N1 unless set) unless `parity` (`none`/`even`/`odd`) or `stop_bits` (1/2) say otherwise; anything but 8N1 needs firmware 3.10.8+. `half_duplex` runs it on one wire (`rx`; `tx` defaults to it) and `entry` (`reset_ms`, `tx_low`, `hold_ms`, `idle_ms`, `data_hex`) runs a pod-timed boot-mode entry first: reset with TX held low, release, the first bytes (gateware v57, for boot-ROM pins such as RL78 TOOL0). | `rx`, `tx`, `baud`, `parity`, `stop_bits`, `half_duplex`, `entry` |
| `uart_write` | Send text to the DUT through the open UART session. | **`text`**, `line_ending=lf` |
| `uart_read` | Return output received since the last read, optionally waiting for a match. | `until_regex`, `timeout=2` |
| `uart_close` | Stop the background UART session. | none |
Expand Down
1 change: 1 addition & 0 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,7 @@ class UartSessionResult(BaseModel):
baud: Optional[int] = None
parity: Optional[str] = None # "none" / "even" / "odd" (open sessions)
stop_bits: Optional[int] = None
half_duplex: bool = False # one wire (rx == tx)


class UartWriteResult(BaseModel):
Expand Down
59 changes: 53 additions & 6 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
from mcp.server.fastmcp import Context, FastMCP
from mcp.server.fastmcp.exceptions import ToolError
from mcp.types import ToolAnnotations
from pydantic import Field
from pydantic import BaseModel, Field

from embeddedci.benchpod import (
EXPANSION_CHIPS,
Expand Down Expand Up @@ -1130,6 +1130,26 @@ def _uart_result(cap: Any) -> m.UartCaptureResult:
"Anything but 8N1 needs firmware 3.10.8+ (gateware v56)."))]
UartStopBits = Annotated[Optional[Literal[1, 2]], Field(description=(
"Stop bits after the data (and parity) bits; omit for the profile's uart_stop_bits (1 unless set)."))]
UartHalfDuplex = Annotated[bool, Field(description=(
"One-wire UART: rx alone carries both directions (tx defaults to rx). The pod only pulls the "
"line low and its pull-up (LA1-LA6) or the board's holds it high; the pod does not read back "
"its own bytes. For boot-ROM programming pins such as RL78 TOOL0. Needs gateware v57."))]


class UartEntryArg(BaseModel):
"""A boot-mode entry the pod times itself before the session starts."""

reset_ms: int = Field(10, ge=0, le=1000, description="Target held in reset (the pod's reset pin), ms.")
tx_low: bool = Field(True, description="Hold TX low across the reset release (a boot strap on the UART pin).")
hold_ms: int = Field(10, ge=0, le=1000, description="After the reset release, TX stays low this long, ms.")
idle_ms: int = Field(10, ge=0, le=1000, description="From TX release (line idles high) to the first byte, ms.")
data_hex: str = Field("", pattern=r"^([0-9a-fA-F]{2}){0,32}$",
description="Bytes sent right after idle_ms, as hex (at most 32 bytes).")


UartEntryOpt = Annotated[Optional[UartEntryArg], Field(description=(
"Run a boot-mode entry on the pod first: TX low, reset, release, then the first bytes, all "
"timed on the pod. Needs gateware v57 and the pod's reset pin. Omit for a plain session."))]


def _uart_frame(pod: Any, method: str, parity: Optional[str], stop_bits: Optional[int]) -> Dict[str, Any]:
Expand All @@ -1145,6 +1165,21 @@ def _uart_frame(pod: Any, method: str, parity: Optional[str], stop_bits: Optiona
return {k: v for k, v in (("parity", parity), ("stop_bits", stop_bits)) if v is not None}


def _uart_line(pod: Any, method: str, half_duplex: bool, entry: Optional[UartEntryArg]) -> Dict[str, Any]:
"""The one-wire and boot-mode entry keyword arguments for an SDK UART call: none when unused,
so an older SDK still works; refused when the SDK predates them."""
kw: Dict[str, Any] = {}
if half_duplex:
kw["half_duplex"] = True
if entry is not None:
from embeddedci.benchpod import UartEntry
kw["entry"] = UartEntry(reset_ms=entry.reset_ms, tx_low=entry.tx_low, hold_ms=entry.hold_ms,
idle_ms=entry.idle_ms, data=bytes.fromhex(entry.data_hex))
if kw and "half_duplex" not in inspect.signature(getattr(type(pod), method)).parameters:
raise ValueError("UART half_duplex and entry need a newer embeddedci SDK; upgrade embeddedci")
return kw


@mcp.tool(annotations=_ann("Capture UART output"))
async def capture_uart(
duration: Annotated[float, Field(gt=0, le=600, description="Capture window in seconds.")],
Expand All @@ -1154,19 +1189,24 @@ async def capture_uart(
until_regex: Regex = None,
parity: UartParity = None,
stop_bits: UartStopBits = None,
half_duplex: UartHalfDuplex = False,
entry: UartEntryOpt = None,
ctx: Context = None, # type: ignore[assignment]
) -> m.UartCaptureResult:
"""Record the DUT's UART output for a fixed window (or until until_regex matches).

The channels, baud, parity and stop bits come from the wiring profile when omitted (8N1 unless
the profile says otherwise).
half_duplex runs it on one wire, and entry runs a pod-timed boot-mode entry first (reset
with TX low, release, first bytes).
"""
pattern = _compile(until_regex)

def op() -> m.UartCaptureResult:
pod = SESSION.require()
return _uart_result(pod.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration, until=pattern,
**_uart_frame(pod, "capture_uart", parity, stop_bits)))
**_uart_frame(pod, "capture_uart", parity, stop_bits),
**_uart_line(pod, "capture_uart", half_duplex, entry)))

return await _call_reporting(ctx, "capturing UART", op)

Expand Down Expand Up @@ -1208,6 +1248,8 @@ async def uart_open(
baud: WiredBaud = None,
parity: UartParity = None,
stop_bits: UartStopBits = None,
half_duplex: UartHalfDuplex = False,
entry: UartEntryOpt = None,
) -> m.UartSessionResult:
"""Start buffering the DUT's UART in the background (replacing any open session).

Expand All @@ -1216,20 +1258,25 @@ async def uart_open(
when omitted; the result says which were used. So do parity and stop_bits (8N1 unless the profile
says otherwise). The LA pins are 1.8/3.3 V only: a 5 V UART needs a level shifter and an RS-485 bus
(Modbus RTU) an external RS-485 transceiver in between. A channel used as GPIO must be released
first (gpio_release).
first (gpio_release). half_duplex runs the session on one wire (rx; tx defaults to it), and
entry runs a pod-timed boot-mode entry before it starts (reset with TX held low, release, the
first bytes), for boot-ROM programming such as RL78 TOOL0.
"""
def op() -> m.UartSessionResult:
pod = SESSION.require()
rx_i, tx_i = _channel(pod, rx, "uart_rx"), _channel(pod, tx, "uart_tx")
rx_i = _channel(pod, rx, "uart_rx")
tx_i = rx_i if half_duplex and tx is None else _channel(pod, tx, "uart_tx")
rate = int(pod.wiring.uart_baud if baud is None else baud)
frame = _uart_frame(pod, "open_uart", parity, stop_bits)
line = _uart_line(pod, "open_uart", half_duplex, entry)
SESSION.close_uart()
SESSION.uart = pod.open_uart(rx=rx_i, tx=tx_i, baud=rate, **frame)
SESSION.uart = pod.open_uart(rx=rx_i, tx=tx_i, baud=rate, **frame, **line)
SESSION.uart_port = (rx_i, tx_i, rate)
used_parity = parity if parity is not None else getattr(pod.wiring, "uart_parity", None) or "none"
used_stop = stop_bits if stop_bits is not None else getattr(pod.wiring, "uart_stop_bits", None) or 1
return m.UartSessionResult(open=True, rx=rx_i, tx=tx_i, baud=rate,
parity=used_parity, stop_bits=used_stop)
parity=used_parity, stop_bits=used_stop,
half_duplex=half_duplex)

return await _call(op)

Expand Down
12 changes: 9 additions & 3 deletions packages/embeddedci-mcp/tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ def __init__(self) -> None:
self.dirs: Dict[int, str] = {}
self.power_efuse = 1
self.uart_frames: List[Tuple[str, int]] = [] # (parity, stop_bits) per uart_proxy_start
self.uart_lines: List[Tuple[int, int, bool, Any]] = [] # (rx, tx, half_duplex, entry)
#: The bin-averaged trace a power_profile reply carries (µA / mV, µs since the start).
self.power_samples: Dict[str, Any] = {
"t_us": [0, 250_000, 500_000, 750_000],
Expand Down Expand Up @@ -131,15 +132,20 @@ def target_power(self, efuse: int, on: bool, delay_ms: int = 0) -> None:
def dap_start(self, swclk: int, swdio: int):
return FakeRawLink()

def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", stop_bits: int = 1):
def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", stop_bits: int = 1,
half_duplex: bool = False, entry: Any = None):
self.uart_frames.append((parity, stop_bits))
self.uart_lines.append((rx, tx, half_duplex, entry))
for la, fn in list(self.function.items()): # a new proxy replaces the previous one
if fn in ("uart_rx", "uart_tx"):
if fn in ("uart_rx", "uart_tx", "uart_hd"):
self.function[la] = "none"
for la in (rx, tx):
if self.function[la] != "none":
raise FirmwareError(self._conflict(la), cmd="uart_proxy_start")
self.function[rx], self.function[tx] = "uart_rx", "uart_tx"
if half_duplex:
self.function[rx] = "uart_hd"
else:
self.function[rx], self.function[tx] = "uart_rx", "uart_tx"
link = FakeRawLink(self.uart_data)
self.uart_links.append(link)
return link
Expand Down
27 changes: 27 additions & 0 deletions packages/embeddedci-mcp/tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,33 @@ def test_uart_frame_format(connected):
call("uart_close")


def test_uart_half_duplex_and_entry(connected):
if "half_duplex" not in inspect.signature(BenchPod.open_uart).parameters:
# The minimum SDK (mcp-min-sdk) predates the arguments: the tool says to upgrade it.
with pytest.raises(ToolError, match="newer embeddedci SDK"):
call("uart_open", rx=3, half_duplex=True)
return
# one wire and the boot-mode entry need the pod's uart_hd capability (gateware v57)
with pytest.raises(ToolError, match="gateware v57"):
call("uart_open", rx=3, half_duplex=True)
connected.caps.extend(["uart_hd", "nrst_pin"])
SESSION.require().refresh_capabilities()
r = call("uart_open", rx=3, half_duplex=True)
assert (r["rx"], r["tx"], r["half_duplex"]) == (3, 3, True)
assert connected.uart_lines[-1][:3] == (3, 3, True)
call("uart_open", rx=3, half_duplex=True,
entry={"reset_ms": 5, "hold_ms": 3, "idle_ms": 2, "data_hex": "00"})
e = connected.uart_lines[-1][3]
assert e.to_request() == {"reset_ms": 5, "tx_low": True, "hold_ms": 3, "idle_ms": 2, "hex": "00"}
call("capture_uart", rx=1, tx=2, duration=0.2, entry={})
assert connected.uart_lines[-1][2] is False and connected.uart_lines[-1][3] is not None
with pytest.raises(ToolError):
call("uart_open", rx=3, half_duplex=True, entry={"data_hex": "0"})
with pytest.raises(ToolError):
call("uart_open", rx=3, half_duplex=True, entry={"reset_ms": 5000})
call("uart_close")


# -- I2C sensor + pulls ----------------------------------------------------------------

def test_sensor_library_tools_need_no_pod():
Expand Down
3 changes: 2 additions & 1 deletion packages/embeddedci-mcp/tests/test_wiring_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,8 @@ def test_wiring_resource_is_registered():
def test_uart_tools_take_channels_and_baud_from_the_profile(connected):
_set()
result = call("uart_open")
assert result == {"open": True, "rx": 7, "tx": 8, "baud": 9600, "parity": "none", "stop_bits": 1}
assert result == {"open": True, "rx": 7, "tx": 8, "baud": 9600, "parity": "none", "stop_bits": 1,
"half_duplex": False}
call("uart_close")
call("capture_uart", duration=0.2)
assert connected.uart_links[-1] is not None
Expand Down
128 changes: 128 additions & 0 deletions packages/embeddedci-mcp/tests/tools_surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -1063,6 +1063,52 @@
"title": "Capture UART output"
},
"input": {
"$defs": {
"UartEntryArg": {
"description": "A boot-mode entry the pod times itself before the session starts.",
"properties": {
"data_hex": {
"default": "",
"description": "Bytes sent right after idle_ms, as hex (at most 32 bytes).",
"pattern": "^([0-9a-fA-F]{2}){0,32}$",
"title": "Data Hex",
"type": "string"
},
"hold_ms": {
"default": 10,
"description": "After the reset release, TX stays low this long, ms.",
"maximum": 1000,
"minimum": 0,
"title": "Hold Ms",
"type": "integer"
},
"idle_ms": {
"default": 10,
"description": "From TX release (line idles high) to the first byte, ms.",
"maximum": 1000,
"minimum": 0,
"title": "Idle Ms",
"type": "integer"
},
"reset_ms": {
"default": 10,
"description": "Target held in reset (the pod's reset pin), ms.",
"maximum": 1000,
"minimum": 0,
"title": "Reset Ms",
"type": "integer"
},
"tx_low": {
"default": true,
"description": "Hold TX low across the reset release (a boot strap on the UART pin).",
"title": "Tx Low",
"type": "boolean"
}
},
"title": "UartEntryArg",
"type": "object"
}
},
"properties": {
"baud": {
"anyOf": [
Expand All @@ -1086,6 +1132,24 @@
"title": "Duration",
"type": "number"
},
"entry": {
"anyOf": [
{
"$ref": "#/$defs/UartEntryArg"
},
{
"type": "null"
}
],
"default": null,
"description": "Run a boot-mode entry on the pod first: TX low, reset, release, then the first bytes, all timed on the pod. Needs gateware v57 and the pod's reset pin. Omit for a plain session."
},
"half_duplex": {
"default": false,
"description": "One-wire UART: rx alone carries both directions (tx defaults to rx). The pod only pulls the line low and its pull-up (LA1-LA6) or the board's holds it high; the pod does not read back its own bytes. For boot-ROM programming pins such as RL78 TOOL0. Needs gateware v57.",
"title": "Half Duplex",
"type": "boolean"
},
"parity": {
"anyOf": [
{
Expand Down Expand Up @@ -5462,6 +5526,52 @@
"title": "Open a UART session"
},
"input": {
"$defs": {
"UartEntryArg": {
"description": "A boot-mode entry the pod times itself before the session starts.",
"properties": {
"data_hex": {
"default": "",
"description": "Bytes sent right after idle_ms, as hex (at most 32 bytes).",
"pattern": "^([0-9a-fA-F]{2}){0,32}$",
"title": "Data Hex",
"type": "string"
},
"hold_ms": {
"default": 10,
"description": "After the reset release, TX stays low this long, ms.",
"maximum": 1000,
"minimum": 0,
"title": "Hold Ms",
"type": "integer"
},
"idle_ms": {
"default": 10,
"description": "From TX release (line idles high) to the first byte, ms.",
"maximum": 1000,
"minimum": 0,
"title": "Idle Ms",
"type": "integer"
},
"reset_ms": {
"default": 10,
"description": "Target held in reset (the pod's reset pin), ms.",
"maximum": 1000,
"minimum": 0,
"title": "Reset Ms",
"type": "integer"
},
"tx_low": {
"default": true,
"description": "Hold TX low across the reset release (a boot strap on the UART pin).",
"title": "Tx Low",
"type": "boolean"
}
},
"title": "UartEntryArg",
"type": "object"
}
},
"properties": {
"baud": {
"anyOf": [
Expand All @@ -5478,6 +5588,24 @@
"description": "UART baud rate; omit for the wiring profile's uart_baud.",
"title": "Baud"
},
"entry": {
"anyOf": [
{
"$ref": "#/$defs/UartEntryArg"
},
{
"type": "null"
}
],
"default": null,
"description": "Run a boot-mode entry on the pod first: TX low, reset, release, then the first bytes, all timed on the pod. Needs gateware v57 and the pod's reset pin. Omit for a plain session."
},
"half_duplex": {
"default": false,
"description": "One-wire UART: rx alone carries both directions (tx defaults to rx). The pod only pulls the line low and its pull-up (LA1-LA6) or the board's holds it high; the pod does not read back its own bytes. For boot-ROM programming pins such as RL78 TOOL0. Needs gateware v57.",
"title": "Half Duplex",
"type": "boolean"
},
"parity": {
"anyOf": [
{
Expand Down
4 changes: 4 additions & 0 deletions packages/embeddedci/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
- `flash(target="esp32...")` switches the FPGA to the deep-replay image before staging the image,
so a pod left on the emulation or loop image no longer refuses with `load_bin: deep replay is
not in the emulation image`.
- **One-wire UART and boot-mode entry:** `open_uart` and `capture_uart` take `half_duplex=True`
(rx and tx on one LA pin; the pod only pulls the line low and does not read back its own bytes)
and `entry=UartEntry(...)`, a reset with TX held low, its release and the first bytes, all timed
on the pod. Needs gateware v57 (capability `uart_hd`); the entry also needs the reset pin.

## 3.0.1

Expand Down
Loading