diff --git a/packages/embeddedci-mcp/README.md b/packages/embeddedci-mcp/README.md index 413b732..fff8d85 100644 --- a/packages/embeddedci-mcp/README.md +++ b/packages/embeddedci-mcp/README.md @@ -179,7 +179,7 @@ description, ranges and enums, so an agent sees more than this table. | --- | --- | --- | | `connect` | Open a connection (closing any previous one) and report status, capabilities and where the wiring profile came from. Without a `connection` or a configured default (`--connection`, `BENCHPOD_CONNECTION`, the CLI's saved connection), finds the one pod on the LAN over mDNS. | `connection`, `la_voltage`, `lease_wait=30` | | `disconnect` | Close UART/CAN sessions and the connection, releasing a cloud lease. | none | -| `status` | Firmware, capabilities, LA voltage, open sessions and warnings (works when not connected). | none | +| `status` | Firmware, capabilities, LA voltage, open sessions and warnings (works when not connected); `eth_mac` and `wifi_mac`, the MACs a network admin registers before the pod gets an address (from the pod with firmware after 3.10.7, else from embeddedci.com's record; `wifi_mac` null until the pod scanned for Wi-Fi or joined). | none | | `set_la_voltage` | Select the LA I/O voltage to match the DUT (1.8 V needs a rev3 pod). | **`voltage`** | ### Cloud (embeddedci.com) diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index 94e3303..db003d7 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -123,6 +123,12 @@ class StatusResult(BaseModel): session: SessionInfo = Field(default_factory=SessionInfo) warnings: List[str] = Field(default_factory=list) firmware: Dict[str, Any] = Field(default_factory=dict, description="The pod's raw status report.") + eth_mac: Optional[str] = Field(None, description=( + "The pod's Ethernet MAC (aa:bb:cc:dd:ee:ff), for a network that hands out addresses only to " + "registered devices; null when not known (firmware 3.10.7 and older over the LAN).")) + wifi_mac: Optional[str] = Field(None, description=( + "The MAC the pod uses on Wi-Fi; null on a pod without Wi-Fi, or until the pod scanned for " + "Wi-Fi or joined a network. Over the cloud both come from embeddedci.com's record of the pod.")) wiring_source: Optional[str] = Field(None, description=( "Where this connection's wiring profile came from: server (stored on embeddedci.com, as the " "web UI's Wiring tab shows it), file (BENCHPOD_WIRING), dict (set_wiring) or defaults.")) diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index 822da6c..4dedd90 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -404,10 +404,16 @@ def _status() -> m.StatusResult: if la is None: warnings.append("LA I/O voltage not selected — call set_la_voltage (1.8 or 3.3, matching " "the DUT) before flash, UART, LA capture, pulls or sensor emulation") + try: + macs = pod.mac_addresses(firmware if isinstance(firmware, dict) else {}) + eth_mac, wifi_mac = macs.eth_mac, macs.wifi_mac + except (BenchPodError, AttributeError): + eth_mac = wifi_mac = None return m.StatusResult( connected=True, connection=SESSION.connection, kind=SESSION.kind, leased=pod.leased, la_voltage=la, capabilities=m.CapabilitiesInfo.from_caps(pod.capabilities), session=SESSION.info(), warnings=warnings, firmware=firmware, wiring_source=wiring_source, + eth_mac=eth_mac, wifi_mac=wifi_mac, ) diff --git a/packages/embeddedci-mcp/tests/test_refusals.py b/packages/embeddedci-mcp/tests/test_refusals.py index fd1156f..1897c5d 100644 --- a/packages/embeddedci-mcp/tests/test_refusals.py +++ b/packages/embeddedci-mcp/tests/test_refusals.py @@ -163,3 +163,10 @@ def test_capabilities_report_the_policy_flags(fake_open, fake_transport): caps = call("connect", connection="192.168.1.50", la_voltage=3.3)["capabilities"] assert caps["lan_policy"] == "open" and caps["ota_sig"] and caps["sig_policy"] == "audit" assert caps["tunnel_max_tier"] and caps["analog"] is True + + +def test_status_reports_the_macs(connected): + real = connected.status + connected.status = lambda: dict(real(), eth_mac="02:35:c7:76:b7:9b", wifi_mac="7c:e8:b1:c5:ca:6c") + result = call("status") + assert result["eth_mac"] == "02:35:c7:76:b7:9b" and result["wifi_mac"] == "7c:e8:b1:c5:ca:6c" diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 488a314..4c6cff9 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -287,6 +287,19 @@ cloud connection; over plaintext Ethernet or Wi-Fi the pod refuses (`PodLockedEr `set_lan_tls_cert` needs a network connection (it uploads the bundle); after it and after `regenerate_lan_tls()` the SDK pins the new certificate for the address it used. +### MAC addresses (managed networks) + +A lab network that hands out addresses only to registered devices needs the pod's MACs first. +`mac_addresses()` returns them as `MacAddresses`: `eth_mac`, `wifi_mac` (the MAC the pod uses on +Wi-Fi), `has_wifi` and `source`. With firmware after 3.10.7 they come from the pod's `status` +(`eth_mac`, `wifi_mac`; LAN and USB), else from embeddedci.com's record of the pod (`source` +`"server"`; recorded when the pod shipped, refreshed on every connect), which is how a cloud +connection gets them. `wifi_mac` is None until the pod scanned for Wi-Fi or joined a network. + +```python +macs = bp.mac_addresses() # MacAddresses(eth_mac='02:35:c7:76:b7:9b', wifi_mac=..., source='pod') +``` + ### Environment variables | Variable | Used when | Purpose | @@ -2096,7 +2109,7 @@ lease_wait=600.0, lease_ttl=120, wiring=None)`. A context manager; `close()` is | Area | Methods and properties | |---|---| -| Connection and device | `ping()`, `status()`, `capabilities`, `refresh_capabilities()` (drop the cached capabilities and read them again), `close()`, `leased` (true while this client holds the cloud lease), `wiring`, `save_wiring(wiring=None)` (store a cloud device's profile on embeddedci.com), `signal(name)`, `fpga_image(image)`, `usb_cc()`, `usb_network(on=None)` (the USB network setting; `False` turns the adapter off over the USB link), `lan_tls()`, `set_lan_tls_https_only(on)`, `regenerate_lan_tls()`, `set_lan_tls_cert(cert_pem, key_pem)` (the LAN API over TLS, see [TLS on the LAN](#tls-on-the-lan)) | +| Connection and device | `ping()`, `status()`, `mac_addresses(status=None)` (the Ethernet and Wi-Fi MACs, see [MAC addresses](#mac-addresses-managed-networks)), `capabilities`, `refresh_capabilities()` (drop the cached capabilities and read them again), `close()`, `leased` (true while this client holds the cloud lease), `wiring`, `save_wiring(wiring=None)` (store a cloud device's profile on embeddedci.com), `signal(name)`, `fpga_image(image)`, `usb_cc()`, `usb_network(on=None)` (the USB network setting; `False` turns the adapter off over the USB link), `lan_tls()`, `set_lan_tls_https_only(on)`, `regenerate_lan_tls()`, `set_lan_tls_cert(cert_pem, key_pem)` (the LAN API over TLS, see [TLS on the LAN](#tls-on-the-lan)) | | LA voltage | `set_la_voltage(volts)`, `get_la_voltage()` | | Power and reset | `power_on(efuse=None, *, delay=None)`, `power_off(efuse=None, *, delay=None)`, `target_power(efuse=None, *, on, delay=None)`, `target_status()`, `power_status()`, `measure_power(duration, *, efuse=None, rate_hz=500.0, keep_samples=0)`, `power_profile(*, efuse=None, rate_hz=500.0, keep_samples=4096, max_duration=60.0)`, `reset_target(*, pulse=0.1)`, `set_reset(asserted)`, `reset_state()` | | Flashing | `flash(...)`, `spi_flash(image, addr=0, *, erase=True, verify=True, hold_reset=False, sck=, mosi=, miso=, cs=)`, `open_spi(...)`, `open_motor_emulator(...)` | @@ -2129,6 +2142,7 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen | `PowerProfile` | `measure_power`, `PowerProfileSession.result` | see [Power profiles](#power-profiles) | | `PowerProfileSession` | `power_profile` (a context manager) | `start()`, `stop()`, `status()`, `result` | | `ResetState` | `reset_target`, `set_reset`, `reset_state` | `asserted`, `supported` | +| `MacAddresses` | `mac_addresses` | `eth_mac`, `wifi_mac` (None while not known), `has_wifi`, `source` (`pod`, `server` or empty) | | `LanTls` | `lan_tls`, `set_lan_tls_https_only`, `regenerate_lan_tls`, `set_lan_tls_cert` | `port`, `https_only`, `sessions`, `origin` (`generated`/`user`), `key`, `subject`, `san`, `not_after`, `sha256` (what clients pin), `error` (no certificate) | | `UsbCcStatus` | `usb_cc` | `orientation`, `advertised`, `advertised_current` (A), `cc1_voltage`, `cc2_voltage` (V) | | `PullState` | `pull_state`, `set_pull` | `la`, `enabled`, `direction`, `ohms`, `available` | diff --git a/packages/embeddedci/src/embeddedci/benchpod/__init__.py b/packages/embeddedci/src/embeddedci/benchpod/__init__.py index a17e070..1c4c15b 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/__init__.py +++ b/packages/embeddedci/src/embeddedci/benchpod/__init__.py @@ -135,7 +135,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin from .lowlevel import LowLevel from .power import PowerProfile, PowerProfileSession from .replay import DacHandle, Fault, ReplayHandle, Segment -from .results import Capture, CorrelatedCapture, LaCapture, LanTls, Trigger +from .results import Capture, CorrelatedCapture, LaCapture, LanTls, MacAddresses, Trigger from .transport.tls import delete_pin as forget_lan_tls, trust_lan_tls from .server_api import ServerApi, ServerApiError, ServerPermissionDeniedError from .state import ( @@ -246,6 +246,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin "Capabilities", "Capture", "LanTls", + "MacAddresses", "TlsPinMismatchError", "trust_lan_tls", "forget_lan_tls", diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index ed2687a..8a5831f 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -102,7 +102,7 @@ from .lowlevel import LowLevel from .power import PowerProfile, PowerProfileSession from .replay import DacHandle, Fault, ReplayHandle, normalize_fault -from .results import Capture, CorrelatedCapture, LaCapture, LanTls, Trigger +from .results import Capture, CorrelatedCapture, LaCapture, LanTls, MacAddresses, Trigger from .wiring import Signal, Wiring from .state import ( AdcRangeState, @@ -188,6 +188,11 @@ def _maybe_on_emulation(caps: Capabilities) -> bool: return bool(caps.sensors_digital and not _images_switchable(caps)) +def _mac_text(v: Any) -> Optional[str]: + """A MAC from a status field or a stored parameter: lowercase text, None when empty.""" + return v.strip().lower() if isinstance(v, str) and v.strip() else None + + def _dict(data: Any) -> Dict[str, Any]: return data if isinstance(data, dict) else {} @@ -414,6 +419,36 @@ def status(self) -> Dict[str, Any]: """The pod's status report: firmware version, board, network and advertised features.""" return _dict(self._transport.status()) + def mac_addresses(self, status: Optional[Mapping[str, Any]] = None) -> "MacAddresses": + """The pod's Ethernet and Wi-Fi MACs, for a network that hands out addresses only to + registered devices. + + From the pod's status (firmware after 3.10.7, LAN and USB: ``eth_mac``, ``wifi_mac``), else + from what embeddedci.com stored for it (recorded when the pod shipped and refreshed on + every connect; the cloud status is the short form, without them). Pass a ``status`` already + read to save a round trip. Fields are None when neither knows them. + """ + st = dict(status) if status is not None else {} + if status is None: + try: + st = self.status() + except BenchPodError: + st = {} + eth = _mac_text(st.get("eth_mac")) + if eth or "wifi_mac" in st: + return MacAddresses(eth_mac=eth, wifi_mac=_mac_text(st.get("wifi_mac")), + has_wifi="wifi_mac" in st, source="pod") + api = self._try_server_api() + if api is not None and self._device_name: + try: + params = api.device_parameters(self._device_name) + except BenchPodError: + params = {} + eth, wifi = _mac_text(params.get("net.eth_mac")), _mac_text(params.get("net.wifi_mac")) + if eth or wifi: + return MacAddresses(eth_mac=eth, wifi_mac=wifi, source="server") + return MacAddresses() + @property def capabilities(self) -> Capabilities: """The device's resolved :class:`Capabilities` (ADC scaling, DAC replay depth, flags). diff --git a/packages/embeddedci/src/embeddedci/benchpod/results.py b/packages/embeddedci/src/embeddedci/benchpod/results.py index cdd2c28..fb5307a 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/results.py +++ b/packages/embeddedci/src/embeddedci/benchpod/results.py @@ -367,6 +367,19 @@ def __len__(self) -> int: return max(len(self.adc), len(self.la)) +@dataclass(frozen=True) +class MacAddresses: + """The pod's MACs (:meth:`BenchPod.mac_addresses`), for a network that hands out addresses only + to registered devices. ``"aa:bb:cc:dd:ee:ff"``, or None when not known.""" + + eth_mac: Optional[str] = None + # The MAC the pod uses on Wi-Fi: the built-in Wi-Fi's (known once the pod scanned for Wi-Fi or + # joined a network) or, through a Wi-Fi bridge, the Ethernet MAC. None also on a pod without Wi-Fi. + wifi_mac: Optional[str] = None + has_wifi: Optional[bool] = None # None: the source does not say + source: str = "" # "pod" (its status), "server" (embeddedci.com's record) or "" + + @dataclass(frozen=True) class LanTls: """The pod's LAN API over TLS (:meth:`BenchPod.lan_tls`, firmware 3.9.3+).""" diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 2b77220..2ede4a5 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -140,6 +140,7 @@ "leased": "property", "loop_input": "(self, input_code: 'Optional[int]' = None, *, source: 'Optional[LoopSource]' = None, step: 'Optional[int]' = None) -> 'LoopState'", "loop_probe": "(self) -> '_control_loop.IVPoint'", + "mac_addresses": "(self, status: 'Optional[Mapping[str, Any]]' = None) -> \"'MacAddresses'\"", "measure_power": "(self, duration: 'float', *, efuse: 'Optional[Union[Efuse, int]]' = None, rate_hz: 'float' = 500.0, keep_samples: 'int' = 0) -> 'PowerProfile'", "module": "(self) -> 'ModuleInfo'", "open_can": "(self, *, bitrate: 'int' = 500000, mode: 'CanMode' = 'normal', term: 'bool' = False, fd: 'bool' = False, data_bitrate: 'Optional[int]' = None) -> '_can.CanBus'", @@ -777,6 +778,14 @@ "dac_mux_status": "(self) -> 'Dict[str, Any]'", "dac_set": "(self, code: 'int', *, divider: 'Optional[int]' = None) -> 'Dict[str, Any]'" }, + "MacAddresses": { + "__fields__": [ + "eth_mac", + "wifi_mac", + "has_wifi", + "source" + ] + }, "ModuleInfo": { "__fields__": [ "present", @@ -1339,6 +1348,7 @@ "LoopSource", "LoopState", "LowLevel", + "MacAddresses", "ModuleInfo", "MotorEmulator", "NoopBuildReporter", diff --git a/packages/embeddedci/tests/test_client_v2.py b/packages/embeddedci/tests/test_client_v2.py index 8bc2de1..691160d 100644 --- a/packages/embeddedci/tests/test_client_v2.py +++ b/packages/embeddedci/tests/test_client_v2.py @@ -577,3 +577,34 @@ def stream_chunks(self, req): from embeddedci.benchpod.transport.base import request_timeout assert request_timeout(t.commands[-1], 30) == 90 + + +# -- MAC addresses ----------------------------------------------------------------- + +def test_mac_addresses_from_the_status(): + bp, _ = _bp() + macs = bp.mac_addresses({"eth_mac": "02:35:C7:76:B7:9B", "wifi_mac": None}) + assert macs.eth_mac == "02:35:c7:76:b7:9b" and macs.wifi_mac is None + assert macs.has_wifi is True and macs.source == "pod" + macs = bp.mac_addresses({"eth_mac": "02:35:c7:76:b7:9b"}) + assert macs.has_wifi is False + + +def test_mac_addresses_fall_back_to_the_server(monkeypatch): + bp, _ = _bp() + + class Api: + def device_parameters(self, name): + assert name == "benchpod-30a9f1" + return {"net.eth_mac": "02:35:c7:76:b7:9b", "net.wifi_mac": "7c:e8:b1:c5:ca:6c"} + + monkeypatch.setattr(bp, "_try_server_api", lambda: Api()) + monkeypatch.setattr(bp, "_device_name", "benchpod-30a9f1") + macs = bp.mac_addresses({"short_form": True}) # the cloud status has no MACs + assert (macs.eth_mac, macs.wifi_mac, macs.source) == ("02:35:c7:76:b7:9b", "7c:e8:b1:c5:ca:6c", "server") + + +def test_mac_addresses_unknown(): + bp, _ = _bp() + macs = bp.mac_addresses() # old firmware, no server access + assert macs.eth_mac is None and macs.wifi_mac is None and macs.source == ""