From ce612ceb81610cf40805ae4622637f086d190ff8 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 08:16:59 -0600 Subject: [PATCH 1/4] embeddedci: one-wire UART (half_duplex) and a pod-timed boot-mode entry (UartEntry) open_uart / capture_uart take half_duplex (rx alone, tx defaults to it) and entry=UartEntry(reset_ms, tx_low, hold_ms, idle_ms, data): the pod holds TX low across a reset, releases it and sends the first bytes, timed on the pod. Capability uart_hd (gateware v57); entry also needs nrst_pin. Refused before anything is sent on older pods and on the USB console. Refs embeddedci-com/benchpod-firmware#135 Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/README.md | 27 +++++- .../src/embeddedci/benchpod/__init__.py | 3 +- .../src/embeddedci/benchpod/capabilities.py | 5 ++ .../src/embeddedci/benchpod/client.py | 64 +++++++++++-- .../src/embeddedci/benchpod/transport/base.py | 7 +- .../embeddedci/benchpod/transport/serial.py | 7 +- .../src/embeddedci/benchpod/transport/tcp.py | 8 +- .../src/embeddedci/benchpod/uart.py | 48 ++++++++++ packages/embeddedci/tests/api_surface.json | 16 +++- .../embeddedci/tests/test_uart_half_duplex.py | 90 +++++++++++++++++++ 10 files changed, 258 insertions(+), 17 deletions(-) create mode 100644 packages/embeddedci/tests/test_uart_half_duplex.py diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index bc6b479..a198c8d 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -965,6 +965,30 @@ 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. 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. +**One wire (half duplex).** Some parts talk UART on a single pin, for example a boot ROM's +programming pin. `half_duplex=True` runs the session on `rx` alone (`tx` defaults to the same +channel): the pod only pulls the line low and lets the pull-up hold it high, so the device answers +on the same wire, and the pod does not read back its own bytes. Use LA1 to LA6, whose pull-up the +pod turns on for the session, or a pull-up on the board. + +**Boot-mode entry.** A boot ROM that picks its mode from the UART pin at reset needs the pin held +low while the chip leaves reset, then a byte soon after. `entry=UartEntry(...)` has the pod run that +sequence before the session starts, timed on the pod so no network delay sits in between: TX +low (`tx_low`), reset for `reset_ms`, release, wait `hold_ms`, release TX, wait `idle_ms`, then send +`data` (at most 32 bytes). Times are whole milliseconds, 0 to 1000: + +```python +from embeddedci.benchpod import UartEntry + +entry = UartEntry(reset_ms=5, hold_ms=3, idle_ms=2, data=b"\x00") +with bp.open_uart(rx=PIN3, half_duplex=True, entry=entry, encoding="latin-1") as uart: + reply = uart.read(timeout=0.5) +``` + +Both need gateware v57 (`bp.supports("uart_hd")`), and `entry` also the pod's reset pin +(`bp.supports("nrst_pin")`); older pods raise `UnsupportedFeatureError` before anything is sent. +The USB console has neither. + **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 @@ -2257,6 +2281,7 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen | `SpiFlashResult` | `spi_flash`, `SpiSession.flash_program` | `jedec_id`, `addr`, `length`, `erased`, `verified`, `seconds` | | `SpiStreamResult` | `SpiSession.stream` | `sent`, `seconds` | | `UartCapture` | `capture_uart`, `power_cycle_and_capture` | `text`, `lines`, `matched`, `match(pattern)`, `contains(needle)` (also `needle in capture`) | +| `UartEntry` (frozen dataclass) | passed to `open_uart` / `capture_uart` as `entry` | `reset_ms`, `tx_low`, `hold_ms`, `idle_ms`, `data`, `to_request()` | | `UartSession` (class) | `open_uart` (a context manager) | `write(data)`, `read(*, timeout=0.0)`, `read_until(pattern, *, timeout)`, `expect(pattern, *, timeout)`, `text`, `lines`, `closed`, `error`, `close()` | | `Sensor` (class) | `sensors.start`, `sensors.sensor` | `instance`, `kind`, `name`, `params`, `info`, `started`, `set(**values)`, `fault(type, *, duration_s=None, **fields)`, `clear_fault()`, `status()`, `regs(start=0, length=None)`, `capture(samples, sample_rate_hz, *, timeout_s, wait_for_traffic)`, `i2c_transactions(...)`, `stop()` | | `SensorEmulation` (class) | `BenchPod.sensors` | see [Emulated sensors](#emulated-sensors) | @@ -2319,7 +2344,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`, `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) | +| 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+), `uart_hd` (one-wire UART and boot-mode entry, gateware v57+), `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) | diff --git a/packages/embeddedci/src/embeddedci/benchpod/__init__.py b/packages/embeddedci/src/embeddedci/benchpod/__init__.py index 1c4c15b..aa5b259 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/__init__.py +++ b/packages/embeddedci/src/embeddedci/benchpod/__init__.py @@ -161,7 +161,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin TargetStatus, UsbCcStatus, ) -from .uart import UartCapture, UartSession +from .uart import UartCapture, UartEntry, UartSession from .spi import SpiFlashInfo, SpiFlashResult, SpiSession, SpiStreamResult from . import motor_emulator from .motor_emulator import BatteryModel, EmulatorCalibration, MotorEmulator @@ -212,6 +212,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin # flash + UART "FlashResult", "UartCapture", + "UartEntry", "UartSession", "SpiSession", "SpiFlashInfo", diff --git a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py index 17e4e91..8548c12 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py +++ b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py @@ -199,6 +199,10 @@ class Capabilities: #: firmware 3.10.8+): :meth:`BenchPod.open_uart` / :meth:`BenchPod.capture_uart` ``parity``, #: ``stop_bits``. uart_frame: bool = False + #: ``uart_hd``: the UART proxy runs on one wire (``half_duplex``) and takes a pod-timed + #: boot-mode entry (``entry``, with ``nrst_pin``) (gateware v57+): :meth:`BenchPod.open_uart` + #: / :meth:`BenchPod.capture_uart` ``half_duplex``, ``entry``. + uart_hd: bool = False #: The running gateware version (``status`` ``gateware``); 0 when not reported. gateware: int = 0 #: The pod can calibrate its own ADC and keeps the result: :meth:`BenchPod.calibrate`. @@ -364,6 +368,7 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities": ("spi_master", "spi_master"), ("spi_stream", "spi_stream"), ("uart_frame", "uart_frame"), + ("uart_hd", "uart_hd"), ("calibrate", "calibrate"), ("cal_dmm", "cal_dmm"), ("current_out", "current_out"), diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 5b3228f..913f5d5 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -1953,6 +1953,8 @@ def capture_uart( until: Optional[_uart.Until] = None, parity: Optional[str] = None, stop_bits: Optional[int] = None, + half_duplex: bool = False, + entry: Optional[_uart.UartEntry] = None, ) -> _uart.UartCapture: """Capture the DUT's UART output for ``duration`` seconds. @@ -1960,15 +1962,16 @@ def capture_uart( DUT's RX). ``until`` (substring / compiled regex / predicate) stops early on a match. Omitted ``rx``, ``tx``, ``baud``, ``parity`` and ``stop_bits`` come from the wiring profile. ``parity`` (``"none"``, ``"even"``, ``"odd"``) and ``stop_bits`` (1 or 2) set the frame - format, as in :meth:`open_uart`. + format, as in :meth:`open_uart`, and so do ``half_duplex`` and ``entry``. """ if duration <= 0: raise ValueError(f"duration must be > 0 seconds, got {duration!r}") - link = self._uart_link(rx, tx, baud, parity, stop_bits) + link = self._uart_link(rx, tx, baud, parity, stop_bits, half_duplex, entry) return _uart.capture(link, duration=duration, until=until) def _uart_link(self, rx: Any, tx: Any, baud: Optional[int], parity: Optional[str] = None, - stop_bits: Optional[int] = None) -> Any: + stop_bits: Optional[int] = None, half_duplex: bool = False, + entry: Optional[_uart.UartEntry] = None) -> Any: if parity is not None and parity not in ("none", "even", "odd"): raise ValueError(f"parity must be 'none', 'even' or 'odd', got {parity!r}") if stop_bits is not None and (isinstance(stop_bits, bool) or stop_bits not in (1, 2)): @@ -1985,14 +1988,39 @@ def _uart_link(self, rx: Any, tx: Any, baud: Optional[int], parity: Optional[str f"UART parity and stop bits need firmware {UART_FRAME_FIRMWARE}+ (gateware v56; " f"this pod runs firmware {fw}): update the pod's firmware", feature="uart_frame", firmware_version=self.capabilities.firmware_version) + if entry is not None and not isinstance(entry, _uart.UartEntry): + raise ValueError(f"entry must be a UartEntry, got {type(entry).__name__}") + if half_duplex or entry is not None: + if not self.supports("uart_hd"): + fw = self.capabilities.firmware_version or "unknown" + raise UnsupportedFeatureError( + f"UART half_duplex and entry need gateware v57 (capability uart_hd; this pod " + f"runs firmware {fw}): update the pod's firmware", + feature="uart_hd", firmware_version=self.capabilities.firmware_version) + if entry is not None and not self.supports("nrst_pin"): + raise UnsupportedFeatureError( + "UART entry needs the pod's reset pin, which this board does not have (v3 boards " + "have it): open the UART without entry and reset the target yourself", + feature="nrst_pin", firmware_version=self.capabilities.firmware_version) rx_i = self._wired(rx, "uart_rx") - tx_i = self._wired(tx, "uart_tx") + if half_duplex: + # One wire: tx defaults to rx, not to the profile's uart_tx. + tx_i = rx_i if tx is None else self._wired(tx, "uart_tx") + if tx_i != rx_i: + raise ValueError(f"half_duplex runs on one pin: rx is LA{rx_i} and tx is LA{tx_i}; " + "omit tx or give the same channel") + else: + tx_i = self._wired(tx, "uart_tx") b = int(self.wiring.uart_baud if baud is None else baud) + kw: Dict[str, Any] = {} + if parity != "none" or stop_bits != 1: + kw.update(parity=parity, stop_bits=stop_bits) + if half_duplex: + kw["half_duplex"] = True + if entry is not None: + kw["entry"] = entry with _classified_errors(): - if parity == "none" and stop_bits == 1: - return self._transport.uart_proxy_start(rx_i, tx_i, b) - return self._transport.uart_proxy_start(rx_i, tx_i, b, parity=parity, - stop_bits=stop_bits) + return self._transport.uart_proxy_start(rx_i, tx_i, b, **kw) def power_cycle_and_capture( self, @@ -2034,6 +2062,8 @@ def open_uart( parity: Optional[str] = None, stop_bits: Optional[int] = None, encoding: str = "utf-8", + half_duplex: bool = False, + entry: Optional[_uart.UartEntry] = None, ) -> _uart.UartSession: """Open an event-based UART session (a background reader buffers the DUT's output). @@ -2067,9 +2097,25 @@ def open_uart( ``encoding`` turns the received bytes into text (and text you write into bytes). For a binary protocol pass ``"latin-1"``: every byte is one character, so ``uart.read().encode("latin-1")`` gives the bytes back unchanged. + + ``half_duplex=True`` runs a one-wire UART on ``rx`` alone (``tx`` defaults to it): the pod + only pulls the line low and lets the pull-up hold it high, so the device answers on the + same wire, and the pod does not read back its own bytes. Use LA1 to LA6 (the pod turns + their pull-up on for the session) or a pull-up on the board. + + ``entry`` runs a boot-mode entry on the pod before the session starts: reset with TX held + low, release, then the first bytes, timed on the pod (see :class:`UartEntry`):: + + entry = benchpod.UartEntry(reset_ms=5, hold_ms=3, idle_ms=2, data=b"\\x00") + with bp.open_uart(rx=3, half_duplex=True, entry=entry, encoding="latin-1") as uart: + uart.write(...) + + Both need gateware v57 (capability ``uart_hd``); ``entry`` also needs the pod's reset pin + (capability ``nrst_pin``). Older pods are refused with + :class:`~embeddedci.benchpod.errors.UnsupportedFeatureError` before anything is sent. """ codecs.lookup(encoding) # an unknown encoding fails here, before the proxy starts - link = self._uart_link(rx, tx, baud, parity, stop_bits) + link = self._uart_link(rx, tx, baud, parity, stop_bits, half_duplex, entry) return _uart.UartSession(link, max_buffer=max_buffer, encoding=encoding) # -- SPI master / SPI flash ------------------------------------------------ diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/base.py b/packages/embeddedci/src/embeddedci/benchpod/transport/base.py index 05ed5cf..6bee6f1 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/base.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/base.py @@ -91,13 +91,16 @@ def dap_start(self, swclk: int, swdio: int, packet_size: Optional[int] = None, @abstractmethod def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", - stop_bits: int = 1) -> RawLink: + stop_bits: int = 1, half_duplex: bool = False, + entry: Any = None) -> RawLink: """Enter transparent UART-proxy mode and return the raw byte link. ``rx``/``tx`` are LA channels: ``rx`` is sampled (wire the DUT's TX here), ``tx`` is driven (wire the DUT's RX here). ``parity`` (``"none"``, ``"even"``, ``"odd"``) and ``stop_bits`` (1, 2) set the frame format; only - 8N1 is sent as before (older firmware knows nothing else). The returned + 8N1 is sent as before (older firmware knows nothing else). ``half_duplex`` (one + wire, ``rx == tx``) and ``entry`` (a :class:`~embeddedci.benchpod.uart.UartEntry`) are + sent only when set (gateware v57). The returned link carries raw bytes; ``close()`` leaves the proxy. """ diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py index c5ac9b6..ff9a5c4 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py @@ -612,7 +612,12 @@ def dap_start(self, swclk: int, swdio: int, packet_size: Optional[int] = None, return self._console_raw_handshake(cmd, DAP_READY, quit_byte=DAP_LEAVE) def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", - stop_bits: int = 1) -> RawLink: + stop_bits: int = 1, half_duplex: bool = False, + entry: Any = None) -> RawLink: + if half_duplex or entry is not None: + raise UnsupportedFeatureError( + "UART half_duplex and entry need the network, the USB network or the cloud: the " + "USB console's uart-proxy has neither", feature="uart_hd") if parity != "none" or stop_bits != 1: raise UnsupportedFeatureError( "UART parity and stop bits need the network, the USB network or the cloud: the " diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py index 674c8bc..f4f8c9e 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py @@ -453,13 +453,19 @@ def dap_start(self, swclk: int, swdio: int, packet_size: Optional[int] = None, return self._raw_handshake(req, "dap_start", "flash") def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", - stop_bits: int = 1) -> RawLink: + stop_bits: int = 1, half_duplex: bool = False, + entry: Any = None) -> RawLink: req: dict = {"cmd": "uart_proxy_start", "rx": rx, "tx": tx, "baud": baud} # Only a non-8N1 frame adds the fields (firmware 3.10.8+ / gateware v56 take them). if parity != "none": req["parity"] = parity if stop_bits != 1: req["stop_bits"] = stop_bits + # One wire and the boot-mode entry (gateware v57), likewise only when asked for. + if half_duplex: + req["half_duplex"] = True + if entry is not None: + req["entry"] = entry.to_request() return self._raw_handshake(req, "uart_proxy_start", "uart") def close(self) -> None: diff --git a/packages/embeddedci/src/embeddedci/benchpod/uart.py b/packages/embeddedci/src/embeddedci/benchpod/uart.py index a9d7434..f6dd490 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/uart.py +++ b/packages/embeddedci/src/embeddedci/benchpod/uart.py @@ -23,6 +23,54 @@ Until = Union[str, "Pattern[str]", Callable[[str], bool]] +UART_ENTRY_MS_MAX = 1000 +UART_ENTRY_DATA_MAX = 32 + + +@dataclass(frozen=True) +class UartEntry: + """A boot-mode entry the pod runs before a UART session starts (``open_uart(entry=...)``). + + Some boot ROMs pick their mode from the level of the UART pin when the chip leaves reset, and + expect a byte soon after (Renesas RL78 on TOOL0, for one). The pod times the whole sequence + itself, so the network never sits between the reset and the first byte: + + 1. with ``tx_low``, drive TX low; + 2. hold the target in reset (the pod's reset pin) for ``reset_ms``, release it; + 3. wait ``hold_ms`` (TX still low with ``tx_low``); + 4. release TX (the UART starts, the line idles high), wait ``idle_ms``; + 5. send ``data``. + + Times are whole milliseconds, 0 to 1000; ``data`` is at most 32 bytes. The target's own + timing requirements come from its datasheet. + """ + + reset_ms: int = 10 + tx_low: bool = True + hold_ms: int = 10 + idle_ms: int = 10 + data: bytes = b"" + + def __post_init__(self) -> None: + for name in ("reset_ms", "hold_ms", "idle_ms"): + v = getattr(self, name) + if isinstance(v, bool) or not isinstance(v, int) or not 0 <= v <= UART_ENTRY_MS_MAX: + raise ValueError(f"{name} must be a whole number of milliseconds, 0 to " + f"{UART_ENTRY_MS_MAX}, got {v!r}") + if not isinstance(self.data, (bytes, bytearray)): + raise ValueError(f"data must be bytes, got {type(self.data).__name__}") + if len(self.data) > UART_ENTRY_DATA_MAX: + raise ValueError(f"data is at most {UART_ENTRY_DATA_MAX} bytes, got {len(self.data)}") + + def to_request(self) -> dict: + """The ``entry`` object of the pod's ``uart_proxy_start``.""" + req: dict = {"reset_ms": self.reset_ms, "tx_low": self.tx_low, "hold_ms": self.hold_ms, + "idle_ms": self.idle_ms} + if self.data: + req["hex"] = bytes(self.data).hex() + return req + + @dataclass class UartCapture: """Decoded UART output collected during a capture window.""" diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 869b296..93ce032 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -110,7 +110,7 @@ "capture_adc": "(self, samples: 'int' = 4096, *, sample_rate_hz: 'Optional[float]' = None, source: 'Optional[AdcSource]' = None, trigger: 'Optional[Trigger]' = None, trigger_timeout: 'float' = 10.0, range: 'Optional[AdcRange]' = None, oversample: 'bool' = False) -> 'Capture'", "capture_correlated": "(self, *, adc_samples: 'int' = 4096, adc_sample_rate_hz: 'Optional[float]' = None, la_samples: 'int' = 4096, la_sample_rate_hz: 'Optional[float]' = None, stop_dac_after: 'Optional[float]' = None, trigger: 'Optional[Trigger]' = None, trigger_timeout: 'float' = 10.0, source: 'Optional[AdcSource]' = None) -> 'CorrelatedCapture'", "capture_la": "(self, samples: 'int' = 4096, *, sample_rate_hz: 'Optional[float]' = None, stop_dac_after: 'Optional[float]' = None, trigger: 'Optional[Trigger]' = None, trigger_timeout: 'float' = 10.0, send: 'Optional[_i2c_master.Send]' = None) -> 'LaCapture'", - "capture_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, duration: 'float', until: 'Optional[_uart.Until]' = None, parity: 'Optional[str]' = None, stop_bits: 'Optional[int]' = None) -> '_uart.UartCapture'", + "capture_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, duration: 'float', until: 'Optional[_uart.Until]' = None, parity: 'Optional[str]' = None, stop_bits: 'Optional[int]' = None, half_duplex: 'bool' = False, entry: 'Optional[_uart.UartEntry]' = None) -> '_uart.UartCapture'", "clear_calibration": "(self, part: 'Optional[CalibrationPart]' = None) -> 'Calibration'", "close": "(self) -> 'None'", "command": "(self, req: 'Dict[str, Any]') -> 'Any'", @@ -150,7 +150,7 @@ "open_i2c": "(self, sda: 'Union[Pin, int, str, None]' = None, scl: 'Union[Pin, int, str, None]' = None, *, hz: 'int' = 100000, pullups: 'str' = 'pod') -> '_i2c_master.I2CMaster'", "open_motor_emulator": "(self, *, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, programn: 'Union[Pin, int, str, None]' = None, done: 'Union[Pin, int, str, None]' = None, hz: 'int' = 6000000, calibration: 'Optional[_motor_emulator.EmulatorCalibration]' = None) -> '_motor_emulator.MotorEmulator'", "open_spi": "(self, *, sck: 'Union[Pin, int, str, None]' = None, mosi: 'Union[Pin, int, str, None]' = None, miso: 'Union[Pin, int, str, None]' = None, cs: 'Union[Pin, int, str, None]' = None, hz: 'int' = 1000000, mode: 'int' = 0) -> '_spi.SpiSession'", - "open_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, max_buffer: 'int' = 1048576, parity: 'Optional[str]' = None, stop_bits: 'Optional[int]' = None, encoding: 'str' = 'utf-8') -> '_uart.UartSession'", + "open_uart": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, baud: 'Optional[int]' = None, max_buffer: 'int' = 1048576, parity: 'Optional[str]' = None, stop_bits: 'Optional[int]' = None, encoding: 'str' = 'utf-8', half_duplex: 'bool' = False, entry: 'Optional[_uart.UartEntry]' = None) -> '_uart.UartSession'", "pin_directions": "(self, wiring: 'Optional[Wiring]' = None) -> 'Dict[int, str]'", "pin_levels": "(self) -> 'Dict[int, int]'", "ping": "(self) -> 'Any'", @@ -316,6 +316,7 @@ "spi_master", "spi_stream", "uart_frame", + "uart_hd", "gateware", "calibrate", "cal_dmm", @@ -1152,6 +1153,16 @@ "contains": "(self, needle: 'str') -> 'bool'", "match": "(self, pattern: \"Union[str, 'Pattern[str]']\") -> 'bool'" }, + "UartEntry": { + "__fields__": [ + "reset_ms", + "tx_low", + "hold_ms", + "idle_ms", + "data" + ], + "to_request": "(self) -> 'dict'" + }, "UartFrame": { "__fields__": [ "index", @@ -1420,6 +1431,7 @@ "TriggerEdge", "TriggerTimeout", "UartCapture", + "UartEntry", "UartFrame", "UartLinkError", "UartSession", diff --git a/packages/embeddedci/tests/test_uart_half_duplex.py b/packages/embeddedci/tests/test_uart_half_duplex.py new file mode 100644 index 0000000..351acf4 --- /dev/null +++ b/packages/embeddedci/tests/test_uart_half_duplex.py @@ -0,0 +1,90 @@ +"""One-wire UART (half_duplex) and the pod-timed boot-mode entry (UartEntry): refused before +anything is sent on pods without them, checked, and sent by the TCP transport only when asked +for (firmware command_handler_uart.c uart_proxy_start, gateware v57).""" + +from __future__ import annotations + +from typing import List + +import pytest + +from embeddedci.benchpod import UartEntry, UnsupportedFeatureError +from embeddedci.benchpod.transport.tcp import TcpTransport + +from test_uart_frame import _bp, _serve_once + +HD = ["la_pins", "uart_frame", "uart_hd", "nrst_pin"] + + +def test_half_duplex_uses_one_pin_and_tx_defaults_to_rx(): + bp, pod = _bp(HD) + bp._uart_link(3, None, 115200, half_duplex=True) + bp._uart_link(3, 3, 115200, "odd", 1, half_duplex=True) + assert pod.starts == [ + {"rx": 3, "tx": 3, "baud": 115200, "half_duplex": True}, + {"rx": 3, "tx": 3, "baud": 115200, "parity": "odd", "stop_bits": 1, "half_duplex": True}, + ] + + +def test_half_duplex_refuses_two_pins(): + bp, pod = _bp(HD) + with pytest.raises(ValueError, match="one pin"): + bp.open_uart(rx=3, tx=4, half_duplex=True) + assert pod.starts == [] + + +def test_entry_reaches_the_transport(): + bp, pod = _bp(HD) + e = UartEntry(reset_ms=5, hold_ms=3, idle_ms=2, data=b"\x00") + bp._uart_link(3, None, 115200, half_duplex=True, entry=e) + assert pod.starts == [{"rx": 3, "tx": 3, "baud": 115200, "half_duplex": True, "entry": e}] + assert e.to_request() == {"reset_ms": 5, "tx_low": True, "hold_ms": 3, "idle_ms": 2, "hex": "00"} + assert UartEntry().to_request() == {"reset_ms": 10, "tx_low": True, "hold_ms": 10, "idle_ms": 10} + + +def test_old_pods_are_refused_before_anything_is_sent(): + bp, pod = _bp(["la_pins", "uart_frame", "nrst_pin"]) + with pytest.raises(UnsupportedFeatureError) as info: + bp.open_uart(rx=3, half_duplex=True) + assert info.value.feature == "uart_hd" and "gateware v57" in str(info.value) + with pytest.raises(UnsupportedFeatureError): + bp.capture_uart(rx=1, tx=2, duration=0.1, entry=UartEntry()) + bp, pod2 = _bp(["la_pins", "uart_frame", "uart_hd"]) # no reset pin + with pytest.raises(UnsupportedFeatureError) as info: + bp.open_uart(rx=1, tx=2, entry=UartEntry()) + assert info.value.feature == "nrst_pin" + bp._uart_link(3, None, 115200, half_duplex=True) # half duplex alone is fine + assert pod.starts == [] and len(pod2.starts) == 1 + + +@pytest.mark.parametrize("kw", [{"reset_ms": 1001}, {"hold_ms": -1}, {"idle_ms": 1.5}, + {"reset_ms": True}, {"data": bytes(33)}, {"data": "00"}]) +def test_bad_entry_values(kw): + with pytest.raises(ValueError): + UartEntry(**kw) + + +def test_entry_must_be_a_uart_entry(): + bp, pod = _bp(HD) + with pytest.raises(ValueError, match="UartEntry"): + bp.open_uart(rx=1, tx=2, entry={"reset_ms": 5}) # type: ignore[arg-type] + assert pod.starts == [] + + +def test_tcp_sends_half_duplex_and_entry_only_when_set(): + seen: List[dict] = [] + srv, addr = _serve_once(seen) + try: + t = TcpTransport(addr, timeout=2) + t.uart_proxy_start(3, 4, 115200).close() + t.uart_proxy_start(3, 3, 115200, half_duplex=True).close() + t.uart_proxy_start(3, 3, 115200, half_duplex=True, + entry=UartEntry(tx_low=False, data=b"\x3a\xff")).close() + finally: + srv.close() + assert seen == [ + {"cmd": "uart_proxy_start", "rx": 3, "tx": 4, "baud": 115200}, + {"cmd": "uart_proxy_start", "rx": 3, "tx": 3, "baud": 115200, "half_duplex": True}, + {"cmd": "uart_proxy_start", "rx": 3, "tx": 3, "baud": 115200, "half_duplex": True, + "entry": {"reset_ms": 10, "tx_low": False, "hold_ms": 10, "idle_ms": 10, "hex": "3aff"}}, + ] From 6b640ee28701e0c6e403de382cc99bf981d70673 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 08:16:59 -0600 Subject: [PATCH 2/4] embeddedci-mcp: uart_open / capture_uart half_duplex and entry Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/README.md | 4 +- .../src/embeddedci_mcp/models.py | 1 + .../src/embeddedci_mcp/server.py | 59 +++++++- packages/embeddedci-mcp/tests/conftest.py | 12 +- packages/embeddedci-mcp/tests/test_tools.py | 22 +++ .../embeddedci-mcp/tests/test_wiring_tools.py | 3 +- .../embeddedci-mcp/tests/tools_surface.json | 128 ++++++++++++++++++ 7 files changed, 217 insertions(+), 12 deletions(-) diff --git a/packages/embeddedci-mcp/README.md b/packages/embeddedci-mcp/README.md index ac9c2ca..8dd8178 100644 --- a/packages/embeddedci-mcp/README.md +++ b/packages/embeddedci-mcp/README.md @@ -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 | diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index 65aaf15..132cff2 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -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): diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index f461a65..f58400c 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -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, @@ -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]: @@ -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.")], @@ -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) @@ -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). @@ -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) diff --git a/packages/embeddedci-mcp/tests/conftest.py b/packages/embeddedci-mcp/tests/conftest.py index f40f6ca..69fef63 100644 --- a/packages/embeddedci-mcp/tests/conftest.py +++ b/packages/embeddedci-mcp/tests/conftest.py @@ -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], @@ -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 diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index adbdc2d..7b1df4f 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -442,6 +442,28 @@ def test_uart_frame_format(connected): call("uart_close") +def test_uart_half_duplex_and_entry(connected): + # 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(): diff --git a/packages/embeddedci-mcp/tests/test_wiring_tools.py b/packages/embeddedci-mcp/tests/test_wiring_tools.py index 32ceab6..9192383 100644 --- a/packages/embeddedci-mcp/tests/test_wiring_tools.py +++ b/packages/embeddedci-mcp/tests/test_wiring_tools.py @@ -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 diff --git a/packages/embeddedci-mcp/tests/tools_surface.json b/packages/embeddedci-mcp/tests/tools_surface.json index b7bf260..4d3d4f8 100644 --- a/packages/embeddedci-mcp/tests/tools_surface.json +++ b/packages/embeddedci-mcp/tests/tools_surface.json @@ -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": [ @@ -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": [ { @@ -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": [ @@ -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": [ { From 64b08e4b47c9783f620b0aab8e40b1d53307c1c7 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 09:21:02 -0600 Subject: [PATCH 3/4] CHANGELOG 3.0.2: one-wire UART and boot-mode entry Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/CHANGELOG.md | 3 +++ packages/embeddedci/CHANGELOG.md | 4 ++++ 2 files changed, 7 insertions(+) diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index b4d5371..7448fa9 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -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 diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index a3fe172..85d187e 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -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 From edac21b858e99b835d915e262e87e851dfa2ac8f Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Wed, 18 Nov 2026 09:22:20 -0600 Subject: [PATCH 4/4] MCP test: an SDK without half_duplex is refused with the upgrade hint (mcp-min-sdk) Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/tests/test_tools.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index 7b1df4f..f54d60b 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -443,6 +443,11 @@ def test_uart_frame_format(connected): 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)