diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index 284174e..cab3ce0 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog — `embeddedci-mcp` +## Unreleased + +- The wiring reference (the `wiring` resource and the end of the `wiring` tool's text) tells the + agent to load the board's own profile by name and shows one consistent example, the + process-node bench's `process-node-stm32` profile (UART RX on LA3, I2C SCL on LA1 and SDA on LA2, + the alarm on LA5). It used to mix that bench's I2C pins with the default pins' UART RX (LA5). + ## 3.0.2 - Needs embeddedci 3.0.2. diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py index 3ee5816..29a80f1 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py @@ -46,17 +46,21 @@ BenchPod wiring reference The pod has no fixed pin roles: 14 generic logic-analyzer channels (LA1-LA14) on the DUT -header, and any DUT signal can be on any of them. Always confirm the real wiring with the -user. The example bench (the BMP280 HIL demo) is wired like this: +header, and any DUT signal can be on any of them. Load your board's profile: the pod stores +named profiles (load_wiring(name), or connect(wiring_profile=name)); `wiring` shows the one in +use. The pod's default pins (UART RX LA5, I2C SDA LA1 / SCL LA2) are not any particular bench. +Always confirm the real wiring with the user. One example, the process-node bench (a +NUCLEO-F446RE; profile 'process-node-stm32' from the examples repository), is wired like this: DUT signal Pod connection Tool arguments -------------------------- --------------------------- --------------------------------- SWCLK LA11 flash swclk=11 SWDIO LA12 flash swdio=12 NRST pod reset pin (J1 pin 22) flash nreset=true, reset_target - UART: DUT TX -> pod LA5 rx=5 + UART: DUT TX -> pod LA3 rx=3 UART: DUT RX <- pod LA4 tx=4 - I2C SDA / SCL LA2 / LA1 sda=2, scl=1 (engage their pull-ups) + I2C SCL / SDA LA1 / LA2 scl=1, sda=2 (engage their pull-ups) + ALARM (DUT output) LA5 signal "ALARM" Target power internal 5 V (efuse 1) efuse=1 (external: efuse=2) Bias resistors (3V3-referenced, so unavailable while the LA bank is at 1.8 V): diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index f3d9238..054eb6b 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog — `embeddedci` +## Unreleased + +- The preset of the default pins is now `Wiring.preset("embeddedci-default")` (also the default of + `Wiring.preset()`), and `wiring.DEFAULT_PINS` is its values: they are the pins the pod used to + assume, not the wiring of a particular bench. The old names `"embeddedci-reference"` and + `REFERENCE_BENCH` still work. The values are unchanged, so version 1 profiles mean what they did. + ## 3.0.2 - **The profile on the pod's header:** `BenchPod.board_header()` says which I/O header the pod has diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 8f6030f..bb3e123 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -579,10 +579,14 @@ print(wiring.describe()) # a pin table: bias resistor and **Nothing is wired unless the profile says so** (schema version 2, SDK 3.0). A pin the profile does not set is never driven, and a call that needs it says which one to pass: `bp.flash()` without `swclk`/`swdio` in the profile raises `ValueError: swd_swclk was not given and the wiring profile has -no swd_swclk`. The EmbeddedCI reference bench (a NUCLEO-F446RE: UART on LA5/LA4, I2C on LA1/LA2, SWD -on LA11/LA12, 3.3 V, internal 5 V), what profiles used to default to, is a preset: -`Wiring.preset("embeddedci-reference")`. A version 1 file or dict (or one without a `version` key) -still means what it did: what it leaves out takes the reference bench's values, and the profile you +no swd_swclk`. The default pins, what profiles used to default to (UART RX on LA5 and TX on LA4, I2C +SDA on LA1 and SCL on LA2, SWD on LA11/LA12, 3.3 V, internal 5 V), are a preset: +`Wiring.preset("embeddedci-default")` (the old name `"embeddedci-reference"` still works). They are +not the wiring of any particular bench: load your board's own profile by name +(`BenchPod(conn, wiring_profile="process-node-stm32")`, `bp.load_wiring("process-node-stm32")`), as +the [process-node example](https://github.com/embeddedci-com/examples/tree/main/process-node-stm32) +does with its `wiring/process-node-stm32.json`. A version 1 file or dict (or one without a `version` +key) still means what it did: what it leaves out takes the default pins' values, and the profile you get back is version 2 with them written out. Re-save such a file as version 2 with `benchpod wiring upgrade wiring.json`. diff --git a/packages/embeddedci/src/embeddedci/benchpod/wiring.py b/packages/embeddedci/src/embeddedci/benchpod/wiring.py index 98d2071..7657bad 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/wiring.py +++ b/packages/embeddedci/src/embeddedci/benchpod/wiring.py @@ -12,7 +12,7 @@ Profiles live on the pod (firmware with the wiring commands): up to 16 named profiles, one of them the default, the same over LAN, USB and the cloud. Schema version 2: what a profile does not set is undefined (that pin is not wired, no I/O voltage, no power rail). A version 1 object (or one without -a version) still means what it did: what it leaves out takes the reference bench's values +a version) still means what it did: what it leaves out takes the default pins' values (:meth:`Wiring.preset`). See :class:`Wiring`. """ @@ -29,15 +29,20 @@ PULL_CHANNELS = PULLUP_CHANNELS + PULLDOWN_CHANNELS WIRING_VERSION = 2 -#: The schema versions :meth:`Wiring.from_dict` reads: 1 (missing keys = the reference bench) and 2. +#: The schema versions :meth:`Wiring.from_dict` reads: 1 (missing keys = the default pins) and 2. WIRING_VERSIONS = (1, 2) -#: The reference bench (the EmbeddedCI NUCLEO-F446RE wiring), and what a version 1 profile fills in. -REFERENCE_BENCH: Mapping[str, Any] = { +#: The default pins: what the pod assumed before profiles left nothing undefined, and what a +#: version 1 profile fills in. Not the wiring of any particular bench. +DEFAULT_PINS: Mapping[str, Any] = { "la_mv": 3300, "efuse": 1, "uart_rx": 5, "uart_tx": 4, "i2c_sda": 1, "i2c_scl": 2, "i2c_addr": "0x76", "swd_swclk": 11, "swd_swdio": 12, } +#: The old name of :data:`DEFAULT_PINS`, kept for older code. +REFERENCE_BENCH = DEFAULT_PINS #: Presets: complete profiles to start a new one from (:meth:`Wiring.preset`). Copied, never linked. -PRESETS: Mapping[str, Mapping[str, Any]] = {"embeddedci-reference": REFERENCE_BENCH} +PRESETS: Mapping[str, Mapping[str, Any]] = {"embeddedci-default": DEFAULT_PINS} +#: Old preset names that still work: name -> the preset it is now. +PRESET_ALIASES: Mapping[str, str] = {"embeddedci-reference": "embeddedci-default"} #: Profile keys that name the LA channel of a DUT signal role. ROLE_KEYS: Tuple[str, ...] = ("uart_rx", "uart_tx", "i2c_sda", "i2c_scl", "swd_swclk", "swd_swdio", @@ -105,7 +110,7 @@ class Wiring: What is not set is undefined: ``Wiring()`` wires nothing, has no I/O voltage (``la_mv`` None) and no power rail (``efuse`` None); a call that needs one of them says so. Only plain call settings keep a value (``uart_baud`` 115200, ``swd_nreset`` False, ``swd_target`` auto-detect). Start from - the reference bench with ``Wiring.preset("embeddedci-reference")``. Construction validates the whole profile and + the default pins with ``Wiring.preset("embeddedci-default")``. Construction validates the whole profile and raises :class:`ValueError` listing every problem — including two roles or signals on one LA channel. :meth:`warnings` lists wiring that works but is risky (an I2C bus without a pod pull-up). """ @@ -170,27 +175,30 @@ def undefined(cls) -> "Wiring": return cls(source="undefined") @classmethod - def preset(cls, name: str = "embeddedci-reference") -> "Wiring": - """A complete profile to start from: ``"embeddedci-reference"`` is the EmbeddedCI reference - bench (a NUCLEO-F446RE: UART on LA5/LA4, I2C on LA1/LA2, SWD on LA11/LA12, 3.3 V, internal - 5 V). Save a copy under your own name: ``bp.save_wiring(Wiring.preset(), name="nucleo")``.""" + def preset(cls, name: str = "embeddedci-default") -> "Wiring": + """A complete profile to start from: ``"embeddedci-default"`` is the default pins, what the + pod assumed before version 2 (UART RX on LA5 and TX on LA4, I2C SDA on LA1 and SCL on LA2, + SWD on LA11/LA12, 3.3 V, internal 5 V). It is not the wiring of any particular bench: check + it against yours, then save a copy under your board's name: + ``bp.save_wiring(Wiring.preset().with_changes(uart_rx=3), name="nucleo")``. The old name + ``"embeddedci-reference"`` still works.""" try: - values = PRESETS[name] + values = PRESETS[PRESET_ALIASES.get(name, name)] except KeyError: raise ValueError(f"no wiring preset {name!r} (presets: {', '.join(sorted(PRESETS))})") from None return cls(**values, source="preset") @classmethod def defaults(cls) -> "Wiring": - """The reference bench, what a profile was before version 2 left nothing undefined. Kept for + """The default pins, what a profile was before version 2 left nothing undefined. Kept for older code: use :meth:`preset` (or :meth:`undefined`).""" - return cls.preset("embeddedci-reference") + return cls.preset("embeddedci-default") @classmethod def from_dict(cls, data: Mapping[str, Any], *, source: str = "dict", strict: bool = True) -> "Wiring": """Build a profile from its JSON object. Version 2: absent keys are undefined. Version 1, or no - ``version`` key: absent keys take the reference bench's values (:data:`REFERENCE_BENCH`), as + ``version`` key: absent keys take the default pins' values (:data:`DEFAULT_PINS`), as before version 2; the result is a version 2 profile with them written out. ``null`` pins are not wired. ``strict=False`` keeps unknown keys in :attr:`extra` instead of rejecting them (for a profile written by a newer server).""" diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 6ab48a5..531ca6f 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -1288,7 +1288,7 @@ "load": "(cls, path: 'Union[str, Path]') -> \"'Wiring'\"", "pin_dut_dirs": "(self) -> 'Dict[int, str]'", "pins": "(self) -> 'Dict[int, str]'", - "preset": "(cls, name: 'str' = 'embeddedci-reference') -> \"'Wiring'\"", + "preset": "(cls, name: 'str' = 'embeddedci-default') -> \"'Wiring'\"", "signal": "(self, name: 'str') -> 'Signal'", "to_dict": "(self) -> 'Dict[str, Any]'", "undefined": "(cls) -> \"'Wiring'\"", diff --git a/packages/embeddedci/tests/test_wiring.py b/packages/embeddedci/tests/test_wiring.py index 5d28631..d5ce1e2 100644 --- a/packages/embeddedci/tests/test_wiring.py +++ b/packages/embeddedci/tests/test_wiring.py @@ -10,7 +10,7 @@ import pytest from embeddedci.benchpod import BenchPod, Signal, Wiring -from embeddedci.benchpod.wiring import ROLE_KEYS +from embeddedci.benchpod.wiring import DEFAULT_PINS, REFERENCE_BENCH, ROLE_KEYS def test_nothing_is_wired_by_default(): @@ -21,16 +21,18 @@ def test_nothing_is_wired_by_default(): assert Wiring.undefined() == w -def test_the_reference_preset_is_the_old_default_bench(): - w = Wiring.preset("embeddedci-reference") +def test_the_default_preset_is_the_old_default_pins(): + w = Wiring.preset("embeddedci-default") assert (w.uart_rx, w.uart_tx, w.uart_baud, w.i2c_sda, w.i2c_scl) == (5, 4, 115200, 1, 2) assert (w.swd_swclk, w.swd_swdio, w.efuse, w.la_voltage, w.i2c_address) == (11, 12, 1, 3.3, 0x76) assert w.source == "preset" and w.warnings() == [] and Wiring.defaults() == w + assert Wiring.preset() == w and Wiring.preset("embeddedci-reference") == w # the old name + assert DEFAULT_PINS is REFERENCE_BENCH with pytest.raises(ValueError, match="no wiring preset"): Wiring.preset("nope") -def test_version_1_fills_the_reference_bench_and_version_2_does_not(): +def test_version_1_fills_the_default_pins_and_version_2_does_not(): assert Wiring.from_dict({"uart_rx": 7}).swd_swclk == 11 # no version: version 1 assert Wiring.from_dict({"version": 1, "uart_rx": 7}).la_mv == 3300 v2 = Wiring.from_dict({"version": 2, "uart_rx": 7})