From 9e95c037990fcb55397c891b5e1ad957bc6059e3 Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Mon, 16 Nov 2026 16:06:26 -0600 Subject: [PATCH 1/4] UART parity and stop bits in the SDK and MCP open_uart, capture_uart and power_cycle_and_capture take parity (none/even/odd) and stop_bits (1/2); the MCP's uart_open, capture_uart and power_cycle_and_capture too. Anything but 8N1 needs the pod's uart_frame capability (firmware 3.10.8+, gateware v56) and is refused before anything is sent on older firmware. The TCP transport sends the fields only for a non-8N1 frame; the USB console stays 8N1. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/CHANGELOG.md | 5 + packages/embeddedci-mcp/README.md | 6 +- .../src/embeddedci_mcp/models.py | 2 + .../src/embeddedci_mcp/server.py | 58 ++++++-- packages/embeddedci-mcp/tests/conftest.py | 6 +- packages/embeddedci-mcp/tests/test_tools.py | 16 +++ .../embeddedci-mcp/tests/test_wiring_tools.py | 2 +- .../embeddedci-mcp/tests/tools_surface.json | 63 ++++++++ packages/embeddedci/CHANGELOG.md | 8 ++ packages/embeddedci/README.md | 18 ++- .../src/embeddedci/benchpod/capabilities.py | 8 ++ .../src/embeddedci/benchpod/client.py | 53 +++++-- .../src/embeddedci/benchpod/transport/base.py | 9 +- .../embeddedci/benchpod/transport/serial.py | 8 +- .../src/embeddedci/benchpod/transport/tcp.py | 14 +- packages/embeddedci/tests/api_surface.json | 7 +- packages/embeddedci/tests/test_uart_frame.py | 136 ++++++++++++++++++ 17 files changed, 380 insertions(+), 39 deletions(-) create mode 100644 packages/embeddedci/tests/test_uart_frame.py diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index beb57d0..42a57bb 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -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 diff --git a/packages/embeddedci-mcp/README.md b/packages/embeddedci-mcp/README.md index ae709b7..bb1d31b 100644 --- a/packages/embeddedci-mcp/README.md +++ b/packages/embeddedci-mcp/README.md @@ -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 | diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index 75236fc..65aaf15 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -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): diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index c395815..dceedf8 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -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; Modbus RTU uses even. Anything but 8N1 needs firmware " + "3.10.8+ (gateware v56)."))] +UartStopBits = Annotated[Literal[1, 2], Field(description="Stop bits (2 for Modbus RTU without parity).")] + + +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")) @@ -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)) @@ -1149,17 +1171,24 @@ 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")) @@ -1167,22 +1196,27 @@ 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 (Modbus RTU: parity "even", or stop_bits 2). 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) diff --git a/packages/embeddedci-mcp/tests/conftest.py b/packages/embeddedci-mcp/tests/conftest.py index 85bbc06..f40f6ca 100644 --- a/packages/embeddedci-mcp/tests/conftest.py +++ b/packages/embeddedci-mcp/tests/conftest.py @@ -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 @@ -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], @@ -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" diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index 4ac6edc..adbdc2d 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -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(): diff --git a/packages/embeddedci-mcp/tests/test_wiring_tools.py b/packages/embeddedci-mcp/tests/test_wiring_tools.py index c76d395..32ceab6 100644 --- a/packages/embeddedci-mcp/tests/test_wiring_tools.py +++ b/packages/embeddedci-mcp/tests/test_wiring_tools.py @@ -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 diff --git a/packages/embeddedci-mcp/tests/tools_surface.json b/packages/embeddedci-mcp/tests/tools_surface.json index cc06164..559a56b 100644 --- a/packages/embeddedci-mcp/tests/tools_surface.json +++ b/packages/embeddedci-mcp/tests/tools_surface.json @@ -1086,6 +1086,17 @@ "title": "Duration", "type": "number" }, + "parity": { + "default": "none", + "description": "Parity bit after the 8 data bits; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "enum": [ + "none", + "even", + "odd" + ], + "title": "Parity", + "type": "string" + }, "rx": { "anyOf": [ { @@ -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 (2 for Modbus RTU without parity).", + "enum": [ + 1, + 2 + ], + "title": "Stop Bits", + "type": "integer" + }, "tx": { "anyOf": [ { @@ -3346,6 +3367,17 @@ "title": "Off Settle", "type": "number" }, + "parity": { + "default": "none", + "description": "Parity bit after the 8 data bits; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "enum": [ + "none", + "even", + "odd" + ], + "title": "Parity", + "type": "string" + }, "rx": { "anyOf": [ { @@ -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 (2 for Modbus RTU without parity).", + "enum": [ + 1, + 2 + ], + "title": "Stop Bits", + "type": "integer" + }, "tx": { "anyOf": [ { @@ -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; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "enum": [ + "none", + "even", + "odd" + ], + "title": "Parity", + "type": "string" + }, "rx": { "anyOf": [ { @@ -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 (2 for Modbus RTU without parity).", + "enum": [ + 1, + 2 + ], + "title": "Stop Bits", + "type": "integer" + }, "tx": { "anyOf": [ { diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index 1206269..b628ec3 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -1,5 +1,13 @@ # 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 Modbus RTU (8E1, 8N2) and + other non-8N1 devices. 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. + ## 3.0.0 A major release: wiring profiles live on the pod, nothing is wired by default, and refusals carry diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index f23cb6c..516d449 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -937,6 +937,22 @@ 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`. Modbus RTU, for +example, is 8E1 (or 8N2 without parity): + +```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. For 5 V serial and RS-485 wiring +see the [5 V logic and RS-485](https://embeddedci.com/docs/benchpod/5v-logic-rs485) page. + ## LA bias resistors Eight LA channels carry a fixed, switchable bias resistor. They are referenced to 3V3, so the pod @@ -2282,7 +2298,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) | diff --git a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py index 0ddff47..17e4e91 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/capabilities.py +++ b/packages/embeddedci/src/embeddedci/benchpod/capabilities.py @@ -86,6 +86,8 @@ def _as_bool(m: Mapping[str, Any], *keys: str) -> Optional[bool]: #: server as ``cap.``), command_handler.c handle_status / cloud_client.c. #: The first gateware with the I2C master, SPI modes 1 and 2 and send-and-capture. BUS_MASTER_GATEWARE = 55 +#: The first firmware with UART parity and stop bits (gateware v56, capability ``uart_frame``). +UART_FRAME_FIRMWARE = "3.10.8" #: The first firmware with ``la_dir`` (pin directions). LA_DIR_FIRMWARE = (3, 10, 4) @@ -193,6 +195,10 @@ class Capabilities: #: ``spi_stream``: send an upload staged in PSRAM through the SPI master in one CS frame #: (an FPGA bitstream): :meth:`SpiSession.stream `. spi_stream: bool = False + #: ``uart_frame``: the UART proxy takes a parity bit and two stop bits (gateware v56+, + #: firmware 3.10.8+): :meth:`BenchPod.open_uart` / :meth:`BenchPod.capture_uart` ``parity``, + #: ``stop_bits``. + uart_frame: 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`. @@ -357,6 +363,7 @@ def from_status(cls, status: Mapping[str, Any]) -> "Capabilities": ("usb_cc", "usb_cc"), ("spi_master", "spi_master"), ("spi_stream", "spi_stream"), + ("uart_frame", "uart_frame"), ("calibrate", "calibrate"), ("cal_dmm", "cal_dmm"), ("current_out", "current_out"), @@ -431,6 +438,7 @@ def from_parameters(cls, params: Mapping[str, Any]) -> "Capabilities": ("capture_b64", "cap.capture_b64"), ("nrst_pin", "cap.nrst_pin"), ("usb_cc", "cap.usb_cc"), ("spi_master", "cap.spi_master"), ("spi_stream", "cap.spi_stream"), + ("uart_frame", "cap.uart_frame"), ("calibrate", "cap.calibrate"), ("cal_dmm", "cap.cal_dmm"), ("current_out", "cap.current_out"), ("can", "cap.can"), ("pod_current", "cap.pod_current"), ("adc_low_range", "cap.adc_low_range"), diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 69169c4..7d73742 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -49,7 +49,8 @@ from . import motor_emulator as _motor_emulator from . import spi as _spi from . import uart as _uart -from .capabilities import ADC_WRAP_SPAN, ADC_WRAP_THRESHOLD, BUS_MASTER_GATEWARE, AffineCal, Capabilities +from .capabilities import (ADC_WRAP_SPAN, ADC_WRAP_THRESHOLD, BUS_MASTER_GATEWARE, UART_FRAME_FIRMWARE, + AffineCal, Capabilities) from .constants import ( ADC_SOURCE_PATHS, ADC_GAIN_SOURCES, @@ -1860,24 +1861,43 @@ def capture_uart( baud: Optional[int] = None, duration: float, until: Optional[_uart.Until] = None, + parity: str = "none", + stop_bits: int = 1, ) -> _uart.UartCapture: """Capture the DUT's UART output for ``duration`` seconds. ``rx`` is the LA channel the pod samples (wire the DUT's TX here); ``tx`` is driven (the DUT's RX). ``until`` (substring / compiled regex / predicate) stops early on a match. - Omitted ``rx``, ``tx`` and ``baud`` come from the wiring profile. + Omitted ``rx``, ``tx`` and ``baud`` come from the wiring profile. ``parity`` + (``"none"``, ``"even"``, ``"odd"``) and ``stop_bits`` (1 or 2) set the frame format, as in + :meth:`open_uart`. """ if duration <= 0: raise ValueError(f"duration must be > 0 seconds, got {duration!r}") - link = self._uart_link(rx, tx, baud) + link = self._uart_link(rx, tx, baud, parity, stop_bits) return _uart.capture(link, duration=duration, until=until) - def _uart_link(self, rx: Any, tx: Any, baud: Optional[int]) -> Any: + def _uart_link(self, rx: Any, tx: Any, baud: Optional[int], parity: str = "none", + stop_bits: int = 1) -> Any: + if parity not in ("none", "even", "odd"): + raise ValueError(f"parity must be 'none', 'even' or 'odd', got {parity!r}") + if isinstance(stop_bits, bool) or stop_bits not in (1, 2): + raise ValueError(f"stop_bits must be 1 or 2, got {stop_bits!r}") + if parity != "none" or stop_bits != 1: + if not self.supports("uart_frame"): + fw = self.capabilities.firmware_version or "unknown" + raise UnsupportedFeatureError( + 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) rx_i = self._wired(rx, "uart_rx") tx_i = self._wired(tx, "uart_tx") + b = int(self.wiring.uart_baud if baud is None else baud) with _classified_errors(): - return self._transport.uart_proxy_start( - rx_i, tx_i, int(self.wiring.uart_baud if baud is None else baud)) + 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) def power_cycle_and_capture( self, @@ -1890,6 +1910,8 @@ def power_cycle_and_capture( baud: Optional[int] = None, until: Optional[_uart.Until] = None, off_settle: float = 0.3, + parity: str = "none", + stop_bits: int = 1, ) -> _uart.UartCapture: """Power-cycle the target while capturing its boot output. @@ -1904,7 +1926,8 @@ def power_cycle_and_capture( if off_settle: time.sleep(off_settle) self.power_on(efuse, delay=delay) - return self.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration, until=until) + return self.capture_uart(rx=rx, tx=tx, baud=baud, duration=duration, until=until, + parity=parity, stop_bits=stop_bits) def open_uart( self, @@ -1913,6 +1936,8 @@ def open_uart( tx: Union[Pin, int, str, None] = None, baud: Optional[int] = None, max_buffer: int = 1 << 20, + parity: str = "none", + stop_bits: int = 1, ) -> _uart.UartSession: """Open an event-based UART session (a background reader buffers the DUT's output). @@ -1928,8 +1953,20 @@ def open_uart( Over the cloud, other commands run on the cloud command channel while a session is open. Omitted ``rx``, ``tx`` and ``baud`` come from the wiring profile. A channel in GPIO mode (or used by anything else) is refused with :class:`~embeddedci.benchpod.errors.PinConflictError`. + + The frame is 8N1 unless ``parity`` (``"none"``, ``"even"``, ``"odd"``) or ``stop_bits`` + (1 or 2) say otherwise; Modbus RTU, for example, is 8E1 (or 8N2):: + + with bp.open_uart(rx=5, tx=4, baud=19200, parity="even") as uart: + uart.write(request) + + Anything but 8N1 needs firmware 3.10.8+ (gateware v56, capability ``uart_frame``); older + firmware is refused with :class:`~embeddedci.benchpod.errors.UnsupportedFeatureError` + before anything is sent. The receiver checks the parity bit and the first stop bit; a + byte with a wrong parity bit is still delivered, and ``status()["uart_rx_parity_error"]`` + turns true for the session. """ - link = self._uart_link(rx, tx, baud) + link = self._uart_link(rx, tx, baud, parity, stop_bits) return _uart.UartSession(link, max_buffer=max_buffer) # -- 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 ce0dd84..05ed5cf 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/base.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/base.py @@ -90,12 +90,15 @@ 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) -> RawLink: + def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", + stop_bits: int = 1) -> 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). The returned link - carries raw 8N1 bytes; ``close()`` leaves the proxy. + 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 + link carries raw bytes; ``close()`` leaves the proxy. """ @abstractmethod diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py index dcadf86..c5ac9b6 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/serial.py @@ -22,6 +22,7 @@ ConnectionClosedError, ConnectionConfigError, FirmwareError, + UnsupportedFeatureError, TransportError, TransportTimeout, ) @@ -610,7 +611,12 @@ def dap_start(self, swclk: int, swdio: int, packet_size: Optional[int] = None, cmd = f"dap-start {swclk} {swdio}" return self._console_raw_handshake(cmd, DAP_READY, quit_byte=DAP_LEAVE) - def uart_proxy_start(self, rx: int, tx: int, baud: int) -> RawLink: + def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", + stop_bits: int = 1) -> RawLink: + if parity != "none" or stop_bits != 1: + raise UnsupportedFeatureError( + "UART parity and stop bits need the network, the USB network or the cloud: the " + "USB console's uart-proxy is 8N1 only", feature="uart_frame") return self._console_raw_handshake( f"uart-proxy {rx} {tx} {baud}", UART_READY, quit_byte=CTRL_RBRACKET ) diff --git a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py index f8603d4..674c8bc 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py +++ b/packages/embeddedci/src/embeddedci/benchpod/transport/tcp.py @@ -452,11 +452,15 @@ def dap_start(self, swclk: int, swdio: int, packet_size: Optional[int] = None, req["wait_ms"] = wait_ms return self._raw_handshake(req, "dap_start", "flash") - def uart_proxy_start(self, rx: int, tx: int, baud: int) -> RawLink: - return self._raw_handshake( - {"cmd": "uart_proxy_start", "rx": rx, "tx": tx, "baud": baud}, - "uart_proxy_start", "uart", - ) + def uart_proxy_start(self, rx: int, tx: int, baud: int, parity: str = "none", + stop_bits: int = 1) -> 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 + return self._raw_handshake(req, "uart_proxy_start", "uart") def close(self) -> None: # Nothing persistent is held; connections are per-command. diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 56f3cca..4e32664 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) -> '_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: 'str' = 'none', stop_bits: 'int' = 1) -> '_uart.UartCapture'", "clear_calibration": "(self, part: 'Optional[CalibrationPart]' = None) -> 'Calibration'", "close": "(self) -> 'None'", "command": "(self, req: 'Dict[str, Any]') -> 'Any'", @@ -149,11 +149,11 @@ "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) -> '_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: 'str' = 'none', stop_bits: 'int' = 1) -> '_uart.UartSession'", "pin_directions": "(self, wiring: 'Optional[Wiring]' = None) -> 'Dict[int, str]'", "pin_levels": "(self) -> 'Dict[int, int]'", "ping": "(self) -> 'Any'", - "power_cycle_and_capture": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, efuse: 'Optional[Union[Efuse, int]]' = None, delay: 'float' = 1.0, duration: 'float' = 4.0, baud: 'Optional[int]' = None, until: 'Optional[_uart.Until]' = None, off_settle: 'float' = 0.3) -> '_uart.UartCapture'", + "power_cycle_and_capture": "(self, *, rx: 'Union[Pin, int, str, None]' = None, tx: 'Union[Pin, int, str, None]' = None, efuse: 'Optional[Union[Efuse, int]]' = None, delay: 'float' = 1.0, duration: 'float' = 4.0, baud: 'Optional[int]' = None, until: 'Optional[_uart.Until]' = None, off_settle: 'float' = 0.3, parity: 'str' = 'none', stop_bits: 'int' = 1) -> '_uart.UartCapture'", "power_off": "(self, efuse: 'Optional[Union[Efuse, int]]' = None, *, delay: 'Optional[float]' = None) -> 'None'", "power_on": "(self, efuse: 'Optional[Union[Efuse, int]]' = None, *, delay: 'Optional[float]' = None, wiring_profile: 'Optional[str]' = None) -> 'None'", "power_profile": "(self, *, efuse: 'Optional[Union[Efuse, int]]' = None, rate_hz: 'float' = 500.0, keep_samples: 'int' = 4096, max_duration: 'float' = 60.0) -> 'PowerProfileSession'", @@ -314,6 +314,7 @@ "usb_cc", "spi_master", "spi_stream", + "uart_frame", "gateware", "calibrate", "cal_dmm", diff --git a/packages/embeddedci/tests/test_uart_frame.py b/packages/embeddedci/tests/test_uart_frame.py new file mode 100644 index 0000000..24ceaa4 --- /dev/null +++ b/packages/embeddedci/tests/test_uart_frame.py @@ -0,0 +1,136 @@ +"""UART parity and stop bits: open_uart / capture_uart refuse old firmware before sending, check +their arguments, and pass the frame format to the transport; the TCP transport sends the fields +only for a non-8N1 frame (firmware command_handler_uart.c uart_proxy_start).""" + +from __future__ import annotations + +import json +import threading +from typing import Any, Dict, List + +import pytest + +from embeddedci.benchpod import BenchPod, UnsupportedFeatureError +from embeddedci.benchpod.transport.tcp import TcpTransport + + +class UartPod: + """Answers status with the given caps and records uart_proxy_start calls.""" + + def __init__(self, caps: List[str], version: str = "3.10.8") -> None: + self.caps = caps + self.version = version + self.starts: List[Dict[str, Any]] = [] + + def status(self) -> Dict[str, Any]: + return {"board": "stm32h563", "adc_bits": 16, "version": self.version, "caps": self.caps, + "la_voltage": 3.3, "gateware": 56 if "uart_frame" in self.caps else 55} + + def ping(self) -> Any: + return "pong" + + def close(self) -> None: + pass + + def command(self, req: dict) -> Any: + raise AssertionError(f"unexpected command {req}") + + def uart_proxy_start(self, rx: int, tx: int, baud: int, **frame: Any) -> Any: + self.starts.append({"rx": rx, "tx": tx, "baud": baud, **frame}) + return object() + + +def _bp(caps: List[str], version: str = "3.10.8") -> "tuple[BenchPod, UartPod]": + pod = UartPod(caps, version) + return BenchPod(transport=pod, lease=False), pod + + +def test_8n1_needs_no_capability_and_sends_no_frame_fields(): + bp, pod = _bp(["la_pins"], "3.10.7") + bp._uart_link(5, 4, 9600) + bp._uart_link(5, 4, 9600, "none", 1) + assert pod.starts == [{"rx": 5, "tx": 4, "baud": 9600}] * 2 + + +def test_parity_and_stop_bits_reach_the_transport(): + bp, pod = _bp(["la_pins", "uart_frame"]) + bp._uart_link(5, 4, 19200, "even", 1) + bp._uart_link(5, 4, 19200, "none", 2) + bp._uart_link(5, 4, 19200, "odd", 2) + assert pod.starts == [ + {"rx": 5, "tx": 4, "baud": 19200, "parity": "even", "stop_bits": 1}, + {"rx": 5, "tx": 4, "baud": 19200, "parity": "none", "stop_bits": 2}, + {"rx": 5, "tx": 4, "baud": 19200, "parity": "odd", "stop_bits": 2}, + ] + + +def test_old_firmware_is_refused_before_anything_is_sent(): + bp, pod = _bp(["la_pins"], "3.10.7") + with pytest.raises(UnsupportedFeatureError) as info: + bp.open_uart(rx=5, tx=4, baud=19200, parity="even") + msg = str(info.value) + assert "UART parity and stop bits need firmware 3.10.8+" in msg and "3.10.7" in msg + assert info.value.feature == "uart_frame" + with pytest.raises(UnsupportedFeatureError): + bp.capture_uart(rx=5, tx=4, baud=19200, duration=0.1, stop_bits=2) + assert pod.starts == [] + + +@pytest.mark.parametrize("kw", [{"parity": "mark"}, {"parity": "E"}, {"stop_bits": 3}, + {"stop_bits": 1.5}, {"stop_bits": True}]) +def test_bad_frame_arguments(kw): + bp, pod = _bp(["la_pins", "uart_frame"]) + with pytest.raises(ValueError): + bp.open_uart(rx=5, tx=4, **kw) + assert pod.starts == [] + + +def test_capabilities_read_uart_frame(): + bp, _ = _bp(["la_pins", "uart_frame"]) + assert bp.supports("uart_frame") + bp, _ = _bp(["la_pins"]) + assert not bp.supports("uart_frame") + + +def _serve_once(seen: List[dict]): + import socket + + srv = socket.socket() + srv.bind(("127.0.0.1", 0)) + srv.listen(4) + + def run(): + while True: + try: + conn, _ = srv.accept() + except OSError: + return + with conn: + buf = b"" + while b"\n" not in buf: + chunk = conn.recv(4096) + if not chunk: + break + buf += chunk + seen.append(json.loads(buf.partition(b"\n")[0])) + conn.sendall(b'{"status":"ok","data":"uart ready"}\n') + + threading.Thread(target=run, daemon=True).start() + return srv, "127.0.0.1:%d" % srv.getsockname()[1] + + +def test_tcp_sends_the_frame_fields_only_when_not_8n1(): + seen: List[dict] = [] + srv, addr = _serve_once(seen) + try: + t = TcpTransport(addr, timeout=2) + t.uart_proxy_start(5, 4, 115200).close() + t.uart_proxy_start(5, 4, 9600, parity="even").close() + t.uart_proxy_start(5, 4, 9600, parity="none", stop_bits=2).close() + finally: + srv.close() + assert seen == [ + {"cmd": "uart_proxy_start", "rx": 5, "tx": 4, "baud": 115200}, + {"cmd": "uart_proxy_start", "rx": 5, "tx": 4, "baud": 9600, "parity": "even"}, + {"cmd": "uart_proxy_start", "rx": 5, "tx": 4, "baud": 9600, "stop_bits": 2}, + ] From b8150b35c870ec3fdb88f70e9e7c1fcd64b5a13c Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Mon, 16 Nov 2026 16:14:54 -0600 Subject: [PATCH 2/4] open_uart(encoding=...): latin-1 for binary protocols A UART session decoded everything as UTF-8 with replacement, so a Modbus RTU frame with bytes above 0x7F came back mangled. encoding latin-1 maps each byte to one character and back. Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/CHANGELOG.md | 3 ++ packages/embeddedci/README.md | 9 +++- .../src/embeddedci/benchpod/client.py | 9 +++- .../src/embeddedci/benchpod/uart.py | 9 ++-- packages/embeddedci/tests/api_surface.json | 4 +- packages/embeddedci/tests/test_uart_frame.py | 44 +++++++++++++++++++ 6 files changed, 70 insertions(+), 8 deletions(-) diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index b628ec3..bc4d89c 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -7,6 +7,9 @@ other non-8N1 devices. 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 such as Modbus RTU: `uart.read().encode("latin-1")` gives the + received bytes back unchanged. ## 3.0.0 diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 516d449..66d4504 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -950,8 +950,13 @@ Anything but 8N1 needs firmware 3.10.8+ (gateware v56, `bp.supports("uart_frame" 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. For 5 V serial and RS-485 wiring -see the [5 V logic and RS-485](https://embeddedci.com/docs/benchpod/5v-logic-rs485) page. +`bp.status()["uart_rx_parity_error"]` turns true for the session. + +**Binary protocols.** A session decodes what it receives as UTF-8, which suits a console. For bytes +that are not text (Modbus RTU 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 5 V serial, RS-485 wiring and a Modbus RTU test, see +[5 V logic and RS-485](https://www.embeddedci.com/docs/benchpod-5v-rs485). ## LA bias resistors diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 7d73742..6082675 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -26,6 +26,7 @@ from __future__ import annotations import base64 +import codecs import json import logging import math @@ -1938,6 +1939,7 @@ def open_uart( max_buffer: int = 1 << 20, parity: str = "none", stop_bits: int = 1, + encoding: str = "utf-8", ) -> _uart.UartSession: """Open an event-based UART session (a background reader buffers the DUT's output). @@ -1965,9 +1967,14 @@ def open_uart( before anything is sent. The receiver checks the parity bit and the first stop bit; a byte with a wrong parity bit is still delivered, and ``status()["uart_rx_parity_error"]`` turns true for the session. + + ``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. """ + codecs.lookup(encoding) # an unknown encoding fails here, before the proxy starts link = self._uart_link(rx, tx, baud, parity, stop_bits) - return _uart.UartSession(link, max_buffer=max_buffer) + return _uart.UartSession(link, max_buffer=max_buffer, encoding=encoding) # -- SPI master / SPI flash ------------------------------------------------ diff --git a/packages/embeddedci/src/embeddedci/benchpod/uart.py b/packages/embeddedci/src/embeddedci/benchpod/uart.py index 81438e5..c19a68b 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/uart.py +++ b/packages/embeddedci/src/embeddedci/benchpod/uart.py @@ -80,13 +80,16 @@ class UartSession: """ def __init__(self, link: RawLink, *, max_buffer: int = 1 << 20, - chunk: int = 256) -> None: + chunk: int = 256, encoding: str = "utf-8") -> None: self._link = link self._max_buffer = max_buffer self._chunk = chunk + #: How received bytes become text, and text written becomes bytes. "latin-1" maps every + #: byte to one character and back, for binary protocols (Modbus RTU): ``read().encode("latin-1")``. + self.encoding = encoding # Decoded incrementally, so a multi-byte character split across reads survives and the # read cursor is a character offset (invalid bytes become U+FFFD). - self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace") + self._decoder = codecs.getincrementaldecoder(encoding)(errors="replace") self._parts: List[str] = [] # received text, joined lazily self._size = 0 self._consumed = 0 # read cursor: text before it has been returned @@ -245,7 +248,7 @@ def write(self, data: Union[bytes, str]) -> None: Raises :class:`~embeddedci.benchpod.errors.UartLinkError` when the link is gone (a reset connection, an unplugged pod) instead of the raw socket or serial error.""" if isinstance(data, str): - data = data.encode("utf-8") + data = data.encode(self.encoding) try: self._link.write(data) except (OSError, BenchPodError) as exc: diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 4e32664..957920f 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -149,7 +149,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: 'str' = 'none', stop_bits: 'int' = 1) -> '_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: 'str' = 'none', stop_bits: 'int' = 1, encoding: 'str' = 'utf-8') -> '_uart.UartSession'", "pin_directions": "(self, wiring: 'Optional[Wiring]' = None) -> 'Dict[int, str]'", "pin_levels": "(self) -> 'Dict[int, int]'", "ping": "(self) -> 'Any'", @@ -1167,7 +1167,7 @@ "__init__": "(self, message: 'str', *, text: 'str' = '', cause: 'Optional[BaseException]' = None) -> 'None'" }, "UartSession": { - "__init__": "(self, link: 'RawLink', *, max_buffer: 'int' = 1048576, chunk: 'int' = 256) -> 'None'", + "__init__": "(self, link: 'RawLink', *, max_buffer: 'int' = 1048576, chunk: 'int' = 256, encoding: 'str' = 'utf-8') -> 'None'", "close": "(self) -> 'None'", "closed": "property", "error": "property", diff --git a/packages/embeddedci/tests/test_uart_frame.py b/packages/embeddedci/tests/test_uart_frame.py index 24ceaa4..a29a199 100644 --- a/packages/embeddedci/tests/test_uart_frame.py +++ b/packages/embeddedci/tests/test_uart_frame.py @@ -6,6 +6,7 @@ import json import threading +import time from typing import Any, Dict, List import pytest @@ -134,3 +135,46 @@ def test_tcp_sends_the_frame_fields_only_when_not_8n1(): {"cmd": "uart_proxy_start", "rx": 5, "tx": 4, "baud": 9600, "parity": "even"}, {"cmd": "uart_proxy_start", "rx": 5, "tx": 4, "baud": 9600, "stop_bits": 2}, ] + + +class _Link: + """A raw link that delivers the given chunks, then EOF.""" + + def __init__(self, chunks: List[bytes]) -> None: + self.chunks = list(chunks) + self.written = bytearray() + self.closed = threading.Event() + + def read(self, n: int) -> bytes: + if self.chunks: + return self.chunks.pop(0) + self.closed.wait(2) + return b"" + + def write(self, data: bytes) -> None: + self.written += data + + def close(self) -> None: + self.closed.set() + + +def test_latin1_session_keeps_binary_bytes(): + from embeddedci.benchpod.uart import UartSession + + frame = bytes([0x01, 0x03, 0x02, 0x00, 0xFA, 0x38, 0x07]) # a Modbus reply with 0xFA, invalid UTF-8 + link = _Link([frame[:3], frame[3:]]) + with UartSession(link, encoding="latin-1") as uart: + deadline = time.monotonic() + 2 + data = b"" + while len(data) < len(frame) and time.monotonic() < deadline: + data += uart.read(timeout=0.2).encode("latin-1") + assert data == frame + uart.write(bytes([0x01, 0x03]).decode("latin-1")) + assert bytes(link.written) == b"\x01\x03" + + +def test_open_uart_refuses_an_unknown_encoding(): + bp, pod = _bp(["la_pins"]) + with pytest.raises(LookupError): + bp.open_uart(rx=5, tx=4, encoding="no-such-codec") + assert pod.starts == [] From 6fb4cddca5da19148af633379693482a9996635b Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Mon, 16 Nov 2026 16:24:21 -0600 Subject: [PATCH 3/4] UART frame docs: the pod has no 5 V or RS-485 I/O Parity and stop bits are described as frame settings, not Modbus support; where Modbus RTU comes up, the docs say it needs an external RS-485 transceiver (and 5 V serial a level shifter). Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci-mcp/src/embeddedci_mcp/server.py | 7 ++++--- packages/embeddedci-mcp/tests/tools_surface.json | 12 ++++++------ packages/embeddedci/CHANGELOG.md | 7 ++++--- packages/embeddedci/README.md | 11 +++++++---- .../embeddedci/src/embeddedci/benchpod/client.py | 3 ++- packages/embeddedci/src/embeddedci/benchpod/uart.py | 2 +- 6 files changed, 24 insertions(+), 18 deletions(-) diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index dceedf8..ec4f9d1 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -1120,9 +1120,9 @@ def _uart_result(cap: Any) -> m.UartCaptureResult: 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; Modbus RTU uses even. Anything but 8N1 needs firmware " + "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 (2 for Modbus RTU without parity).")] +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]: @@ -1204,7 +1204,8 @@ async def uart_open( 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. The frame is 8N1 unless parity or stop_bits say - otherwise (Modbus RTU: parity "even", or stop_bits 2). A channel used as GPIO must be released + 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: diff --git a/packages/embeddedci-mcp/tests/tools_surface.json b/packages/embeddedci-mcp/tests/tools_surface.json index 559a56b..600d1de 100644 --- a/packages/embeddedci-mcp/tests/tools_surface.json +++ b/packages/embeddedci-mcp/tests/tools_surface.json @@ -1088,7 +1088,7 @@ }, "parity": { "default": "none", - "description": "Parity bit after the 8 data bits; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", "enum": [ "none", "even", @@ -1122,7 +1122,7 @@ }, "stop_bits": { "default": 1, - "description": "Stop bits (2 for Modbus RTU without parity).", + "description": "Stop bits after the data (and parity) bits.", "enum": [ 1, 2 @@ -3369,7 +3369,7 @@ }, "parity": { "default": "none", - "description": "Parity bit after the 8 data bits; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", "enum": [ "none", "even", @@ -3403,7 +3403,7 @@ }, "stop_bits": { "default": 1, - "description": "Stop bits (2 for Modbus RTU without parity).", + "description": "Stop bits after the data (and parity) bits.", "enum": [ 1, 2 @@ -5452,7 +5452,7 @@ }, "parity": { "default": "none", - "description": "Parity bit after the 8 data bits; Modbus RTU uses even. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", + "description": "Parity bit after the 8 data bits. Anything but 8N1 needs firmware 3.10.8+ (gateware v56).", "enum": [ "none", "even", @@ -5486,7 +5486,7 @@ }, "stop_bits": { "default": 1, - "description": "Stop bits (2 for Modbus RTU without parity).", + "description": "Stop bits after the data (and parity) bits.", "enum": [ 1, 2 diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index bc4d89c..c04ac2c 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -3,12 +3,13 @@ ## 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 Modbus RTU (8E1, 8N2) and - other non-8N1 devices. Anything but 8N1 needs firmware 3.10.8+ (gateware v56, new capability + `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 such as Modbus RTU: `uart.read().encode("latin-1")` gives the + `"latin-1"` for binary protocols: `uart.read().encode("latin-1")` gives the received bytes back unchanged. ## 3.0.0 diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 66d4504..a965d7a 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -938,8 +938,7 @@ arrived and the oldest were dropped. Running commands such as `power_on` while a 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`. Modbus RTU, for -example, is 8E1 (or 8N2 without parity): +`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 @@ -952,10 +951,14 @@ firmware the call raises `UnsupportedFeatureError` before anything is sent. The 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 (Modbus RTU frames), open it with `encoding="latin-1"`: every byte is one +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 5 V serial, RS-485 wiring and a Modbus RTU test, see +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-5v-rs485). ## LA bias resistors diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index 6082675..6508f74 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -1957,7 +1957,8 @@ def open_uart( used by anything else) is refused with :class:`~embeddedci.benchpod.errors.PinConflictError`. The frame is 8N1 unless ``parity`` (``"none"``, ``"even"``, ``"odd"``) or ``stop_bits`` - (1 or 2) say otherwise; Modbus RTU, for example, is 8E1 (or 8N2):: + (1 or 2) 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, between the pod and the device:: with bp.open_uart(rx=5, tx=4, baud=19200, parity="even") as uart: uart.write(request) diff --git a/packages/embeddedci/src/embeddedci/benchpod/uart.py b/packages/embeddedci/src/embeddedci/benchpod/uart.py index c19a68b..a9d7434 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/uart.py +++ b/packages/embeddedci/src/embeddedci/benchpod/uart.py @@ -85,7 +85,7 @@ def __init__(self, link: RawLink, *, max_buffer: int = 1 << 20, self._max_buffer = max_buffer self._chunk = chunk #: How received bytes become text, and text written becomes bytes. "latin-1" maps every - #: byte to one character and back, for binary protocols (Modbus RTU): ``read().encode("latin-1")``. + #: byte to one character and back, for binary protocols: ``read().encode("latin-1")``. self.encoding = encoding # Decoded incrementally, so a multi-byte character split across reads survives and the # read cursor is a character offset (invalid bytes become U+FFFD). From f85179e871fa7a89b5e292f88bf8f2ce9ba45a9c Mon Sep 17 00:00:00 2001 From: Edward Viaene Date: Mon, 16 Nov 2026 17:33:36 -0600 Subject: [PATCH 4/4] README: the 5 V / RS-485 page moved under Supported hardware Co-Authored-By: Claude Opus 5.5 --- packages/embeddedci/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index a965d7a..a9c15c8 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -959,7 +959,7 @@ transceiver behind a level shifter), between the pod and the device. 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-5v-rs485). +[5 V logic and RS-485](https://www.embeddedci.com/docs/benchpod-targets/5v-rs485). ## LA bias resistors