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

## Unreleased

- `uart_open`, `capture_uart` and `power_cycle_and_capture` take `parity` (`none`/`even`/`odd`)
and `stop_bits` (1/2); `uart_open` reports them. Needs firmware 3.10.8+ for anything but 8N1.

## 3.0.0

- Needs embeddedci 3.0. Wiring profiles live on the pod: `wiring` lists them and reports
Expand Down
6 changes: 3 additions & 3 deletions packages/embeddedci-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,9 +251,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` |
| `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` |
| `uart_open` | Start buffering the DUT's UART in the background. | `rx`, `tx`, `baud` |
| `capture_uart` | Record the DUT's UART for a window, or until a regex matches. | **`duration`**, `rx`, `tx`, `baud`, `until_regex`, `parity`, `stop_bits` |
| `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. 8N1 unless `parity` (`none`/`even`/`odd`) or `stop_bits` (1/2) say otherwise; anything else needs firmware 3.10.8+. | `rx`, `tx`, `baud`, `parity`, `stop_bits` |
| `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
2 changes: 2 additions & 0 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -450,6 +450,8 @@ class UartSessionResult(BaseModel):
rx: Optional[int] = None
tx: Optional[int] = None
baud: Optional[int] = None
parity: Optional[str] = None # "none" / "even" / "odd" (open sessions)
stop_bits: Optional[int] = None


class UartWriteResult(BaseModel):
Expand Down
59 changes: 47 additions & 12 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -1119,6 +1119,20 @@ def _uart_result(cap: Any) -> m.UartCaptureResult:
"LA channel (or wiring name) wired to the DUT's TX; omit for the profile's uart_rx."))]
UartTx = Annotated[Optional[LaRef], Field(description=(
"LA channel (or wiring name) wired to the DUT's RX; omit for the profile's uart_tx."))]
UartParity = Annotated[Literal["none", "even", "odd"], Field(description=(
"Parity bit after the 8 data bits. Anything but 8N1 needs firmware "
"3.10.8+ (gateware v56)."))]
UartStopBits = Annotated[Literal[1, 2], Field(description="Stop bits after the data (and parity) bits.")]


def _uart_frame(pod: Any, method: str, parity: str, stop_bits: int) -> Dict[str, Any]:
"""The frame-format keyword arguments for an SDK UART call: none for 8N1, so an older SDK
still works; refused when the SDK predates them."""
if parity == "none" and stop_bits == 1:
return {}
if "parity" not in inspect.signature(getattr(type(pod), method)).parameters:
raise ValueError("UART parity and stop bits need a newer embeddedci SDK; upgrade embeddedci")
return {"parity": parity, "stop_bits": stop_bits}


@mcp.tool(annotations=_ann("Capture UART output"))
Expand All @@ -1128,15 +1142,23 @@ async def capture_uart(
tx: UartTx = None,
baud: WiredBaud = None,
until_regex: Regex = None,
parity: UartParity = "none",
stop_bits: UartStopBits = 1,
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 and baud come from the wiring profile when omitted.
The channels and baud come from the wiring profile when omitted; the frame is 8N1 unless
parity or stop_bits say otherwise.
"""
pattern = _compile(until_regex)
return await _call_reporting(ctx, "capturing UART", lambda: _uart_result(
SESSION.require().capture_uart(rx=rx, tx=tx, baud=baud, duration=duration, until=pattern)))

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)))

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


@mcp.tool(annotations=_ann("Power-cycle and capture boot log", destructive=True))
Expand All @@ -1149,40 +1171,53 @@ async def power_cycle_and_capture(
baud: WiredBaud = None,
until_regex: Regex = None,
off_settle: Annotated[float, Field(ge=0, le=10)] = 0.3,
parity: UartParity = "none",
stop_bits: UartStopBits = 1,
ctx: Context = None, # type: ignore[assignment]
) -> m.UartCaptureResult:
"""Power the target off, then capture UART while it powers back on — the boot banner lands in the window.

The channels, baud and power rail come from the wiring profile when omitted.
The channels, baud and power rail come from the wiring profile when omitted; the frame is 8N1
unless parity or stop_bits say otherwise.
"""
pattern = _compile(until_regex)
return await _call_reporting(ctx, "power-cycling", lambda: _uart_result(
SESSION.require().power_cycle_and_capture(rx=rx, tx=tx, efuse=efuse, delay=delay,
duration=duration, baud=baud, until=pattern,
off_settle=off_settle)))

def op() -> m.UartCaptureResult:
pod = SESSION.require()
return _uart_result(pod.power_cycle_and_capture(
rx=rx, tx=tx, efuse=efuse, delay=delay, duration=duration, baud=baud, until=pattern,
off_settle=off_settle, **_uart_frame(pod, "power_cycle_and_capture", parity, stop_bits)))

return await _call_reporting(ctx, "power-cycling", op)


@mcp.tool(annotations=_ann("Open a UART session"))
async def uart_open(
rx: UartRx = None,
tx: UartTx = None,
baud: WiredBaud = None,
parity: UartParity = "none",
stop_bits: UartStopBits = 1,
) -> m.UartSessionResult:
"""Start buffering the DUT's UART in the background (replacing any open session).

Open it BEFORE an action whose output matters (power_on, reset_target), then uart_read; use
uart_write to type into the DUT's console. The channels and baud come from the wiring profile
when omitted; the result says which were used. A channel used as GPIO must be released first
(gpio_release).
when omitted; the result says which were used. The frame is 8N1 unless parity or stop_bits say
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).
"""
def op() -> m.UartSessionResult:
pod = SESSION.require()
rx_i, tx_i = _channel(pod, rx, "uart_rx"), _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)
SESSION.close_uart()
SESSION.uart = pod.open_uart(rx=rx_i, tx=tx_i, baud=rate)
SESSION.uart = pod.open_uart(rx=rx_i, tx=tx_i, baud=rate, **frame)
SESSION.uart_port = (rx_i, tx_i, rate)
return m.UartSessionResult(open=True, rx=rx_i, tx=tx_i, baud=rate)
return m.UartSessionResult(open=True, rx=rx_i, tx=tx_i, baud=rate,
parity=parity, stop_bits=stop_bits)

return await _call(op)

Expand Down
6 changes: 4 additions & 2 deletions packages/embeddedci-mcp/tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
import json
import math
import os
from typing import Any, Dict, Iterator, List, Optional
from typing import Any, Dict, Iterator, List, Optional, Tuple

import anyio
import pytest
Expand Down Expand Up @@ -101,6 +101,7 @@ def __init__(self) -> None:
self.spi: Optional[Dict[str, Any]] = None
self.dirs: Dict[int, str] = {}
self.power_efuse = 1
self.uart_frames: List[Tuple[str, int]] = [] # (parity, stop_bits) per uart_proxy_start
#: 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 @@ -130,7 +131,8 @@ 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):
def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", stop_bits: int = 1):
self.uart_frames.append((parity, stop_bits))
for la, fn in list(self.function.items()): # a new proxy replaces the previous one
if fn in ("uart_rx", "uart_tx"):
self.function[la] = "none"
Expand Down
16 changes: 16 additions & 0 deletions packages/embeddedci-mcp/tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -426,6 +426,22 @@ def test_uart_session_read_write(connected):
assert call("uart_close")["open"] is False


def test_uart_frame_format(connected):
# 8N1 by default; parity / stop bits need the pod's uart_frame capability
assert call("uart_open", rx=5, tx=4)["parity"] == "none"
with pytest.raises(ToolError, match="firmware 3.10.8"):
call("uart_open", rx=5, tx=4, parity="even")
connected.caps.append("uart_frame")
SESSION.require().refresh_capabilities()
r = call("uart_open", rx=5, tx=4, baud=19200, parity="even")
assert (r["parity"], r["stop_bits"], r["baud"]) == ("even", 1, 19200)
call("capture_uart", rx=5, tx=4, duration=0.2, stop_bits=2)
assert connected.uart_frames[-2:] == [("even", 1), ("none", 2)]
with pytest.raises(ToolError):
call("uart_open", rx=5, tx=4, parity="mark")
call("uart_close")


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

def test_sensor_library_tools_need_no_pod():
Expand Down
2 changes: 1 addition & 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,7 @@ 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}
assert result == {"open": True, "rx": 7, "tx": 8, "baud": 9600, "parity": "none", "stop_bits": 1}
call("uart_close")
call("capture_uart", duration=0.2)
assert connected.uart_links[-1] is not None
Expand Down
63 changes: 63 additions & 0 deletions packages/embeddedci-mcp/tests/tools_surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -1086,6 +1086,17 @@
"title": "Duration",
"type": "number"
},
"parity": {
"default": "none",
"description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).",
"enum": [
"none",
"even",
"odd"
],
"title": "Parity",
"type": "string"
},
"rx": {
"anyOf": [
{
Expand All @@ -1109,6 +1120,16 @@
"description": "LA channel (or wiring name) wired to the DUT's TX; omit for the profile's uart_rx.",
"title": "Rx"
},
"stop_bits": {
"default": 1,
"description": "Stop bits after the data (and parity) bits.",
"enum": [
1,
2
],
"title": "Stop Bits",
"type": "integer"
},
"tx": {
"anyOf": [
{
Expand Down Expand Up @@ -3346,6 +3367,17 @@
"title": "Off Settle",
"type": "number"
},
"parity": {
"default": "none",
"description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).",
"enum": [
"none",
"even",
"odd"
],
"title": "Parity",
"type": "string"
},
"rx": {
"anyOf": [
{
Expand All @@ -3369,6 +3401,16 @@
"description": "LA channel (or wiring name) wired to the DUT's TX; omit for the profile's uart_rx.",
"title": "Rx"
},
"stop_bits": {
"default": 1,
"description": "Stop bits after the data (and parity) bits.",
"enum": [
1,
2
],
"title": "Stop Bits",
"type": "integer"
},
"tx": {
"anyOf": [
{
Expand Down Expand Up @@ -5408,6 +5450,17 @@
"description": "UART baud rate; omit for the wiring profile's uart_baud.",
"title": "Baud"
},
"parity": {
"default": "none",
"description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).",
"enum": [
"none",
"even",
"odd"
],
"title": "Parity",
"type": "string"
},
"rx": {
"anyOf": [
{
Expand All @@ -5431,6 +5484,16 @@
"description": "LA channel (or wiring name) wired to the DUT's TX; omit for the profile's uart_rx.",
"title": "Rx"
},
"stop_bits": {
"default": 1,
"description": "Stop bits after the data (and parity) bits.",
"enum": [
1,
2
],
"title": "Stop Bits",
"type": "integer"
},
"tx": {
"anyOf": [
{
Expand Down
12 changes: 12 additions & 0 deletions packages/embeddedci/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog — `embeddedci`

## Unreleased

- UART parity and stop bits: `open_uart`, `capture_uart` and `power_cycle_and_capture` take
`parity` (`"none"`, `"even"`, `"odd"`) and `stop_bits` (1, 2), for devices that are not 8N1 (8E1,
8N2, ...). The pod's I/O is 1.8/3.3 V only: a 5 V UART needs a level shifter, and Modbus RTU on
RS-485 an external RS-485 transceiver, between the pod and the device. Anything but 8N1 needs firmware 3.10.8+ (gateware v56, new capability
`uart_frame`); older firmware is refused with `UnsupportedFeatureError` before anything is sent.
The USB console transport stays 8N1.
- `open_uart(encoding=...)`: how the session turns bytes into text (default `"utf-8"`). Use
`"latin-1"` for binary protocols: `uart.read().encode("latin-1")` gives the
received bytes back unchanged.

## 3.0.0

A major release: wiring profiles live on the pod, nothing is wired by default, and refusals carry
Expand Down
26 changes: 25 additions & 1 deletion packages/embeddedci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -937,6 +937,30 @@ their match, so the next call only sees newer output. `text` and `lines` keep ev
arrived and the oldest were dropped. Running commands such as `power_on` while a session is open needs a TCP or
cloud connection.

**Frame format.** The UART is 8N1 unless you pass `parity` (`"none"`, `"even"`, `"odd"`) or
`stop_bits` (`1`, `2`) to `open_uart`, `capture_uart` or `power_cycle_and_capture`:

```python
with bp.open_uart(rx=PIN5, tx=PIN4, baud=19200, parity="even") as uart: # 8E1
uart.write(request)
```

Anything but 8N1 needs firmware 3.10.8+ (gateware v56, `bp.supports("uart_frame")`); on older
firmware the call raises `UnsupportedFeatureError` before anything is sent. The USB console
(`usb` falling back to the serial console) is 8N1 only. The pod checks the parity bit and the first
stop bit of what it receives; a byte with a wrong parity bit is still delivered, and
`bp.status()["uart_rx_parity_error"]` turns true for the session.

The LA pins are 1.8 V or 3.3 V only: the pod has no 5 V I/O and no RS-485 port. A 5 V UART needs a
level shifter, and Modbus RTU on RS-485 an external RS-485 transceiver powered at 3.3 V (or a 5 V
transceiver behind a level shifter), between the pod and the device.

**Binary protocols.** A session decodes what it receives as UTF-8, which suits a console. For bytes
that are not text (a binary protocol's frames), open it with `encoding="latin-1"`: every byte is one
character, so `uart.read().encode("latin-1")` gives the bytes back unchanged, and a `bytes` write is
sent as is. For the adapter wiring and a Modbus RTU test through a transceiver, see
[5 V logic and RS-485](https://www.embeddedci.com/docs/benchpod-targets/5v-rs485).

## LA bias resistors

Eight LA channels carry a fixed, switchable bias resistor. They are referenced to 3V3, so the pod
Expand Down Expand Up @@ -2282,7 +2306,7 @@ reported keeps its default (`False`, `0` or `""`), so a feature check is just
| Identity | `board`, `firmware_version`, `board_rev` (`"v2"`, `"v3"`, `"unknown"`, or `""`), `la_vccio_mv` (the LA bank voltage the pod reports) |
| ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit, of the range in use), `adc_low_range` (analog module v3r4+: the low range), `adc_range` (`"normal"`, `"low"`, or `""` before firmware 3.9.5), `adc_range_fullscale` (volts, ±), `adc_max_count`, `counts_to_volts(count)` |
| DAC and replay | `dac`, `dac_dc`, `dac_replay`, `dac_deep_replay`, `dac_control_loop`, `dac_loop_sources` (gateware v29+), `dac_loop_input_map` (v30+), `dac_cotrig` (v27+), `generate16` (firmware 3.9.1+: `generate` in calibrated 16-bit volts), `dac_bits`, `dac_replay_bits`, `dac_replay_max_samples`, `dac_fullscale_mv`, `dac_channels`, `dac_limits` (output limits on the DAC paths) |
| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensors` (sensor emulation from definitions, with `sensors_format` the format the pod reads), `analog` (`False` on the digital-only board, `None` when not announced) |
| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `uart_frame` (UART parity and stop bits, gateware v56+), `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensors` (sensor emulation from definitions, with `sensors_format` the format the pod reads), `analog` (`False` on the digital-only board, `None` when not announced) |
| Firmware updates and policies | `flash_kb` (MCU flash in KiB, 0 when not reported), `blob_slots`, `ota_sig`, `sig_policy` (`"audit"`, `"required"`, ...), `sig_keys`, `sig_policy_cmd`, `lan_policy` (`"open"`, `"locked"`, `"off"`), `lan_policy_cmd`, `tunnel_max_tier`, `lease_state` (the pod refuses LAN writes while a cloud job holds it), `cloud_ca`, `cloud_proxy`, `ws_auth_v2` (server only) |
| Boot health | `safe_mode`, `safe_reason`, `last_crash`, `reset_cause`, `boot_warning()` (a one-line warning after safe mode or a crash, else `None`) |
| Source | `raw` (the map it was parsed from) |
Expand Down
Loading