Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions packages/embeddedci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,27 @@ 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.

### LAN pairing

From firmware 4.0.1 the pod answers only status to a computer on Ethernet or Wi-Fi that is not
paired with it: anything else raises `PodNotPairedError` (`BP0081`, a `PodLockedError`). Pair this
computer once over the pod's USB cable, or through the cloud as an organization owner or admin:

```python
BenchPod("usb").pair() # the USB network adapter, or the console when it is off
BenchPod("embeddedci:bench-01").pair()
```

`benchpod setup` does the same. The SDK presents this computer's TLS client key on every
connection to port 8443: `client.key` and `client.crt` next to `known_pods.json`, made on first use
and shared with `benchpod` and the MCP server. A CI runner passes its own with
`BENCHPOD_CLIENT_KEY_PEM` (or `BENCHPOD_CLIENT_CERT` and `BENCHPOD_CLIENT_KEY`). Over USB,
`pair()` also pins the pod's LAN certificate for its LAN address.

`bp.lan_clients()` lists the paired computers (`LanClient.this` marks this one);
`lan_clients(add=..., spki_sha256=...)`, `remove=...` (a name, or 8+ hex digits of a key) and
`clear=True` change the list over USB or the cloud only. `set_lan_pairing(False)` turns pairing off.

### Console log level

How much the pod prints on its USB console (firmware newer than 3.10.12, feature `log_level`).
Expand Down Expand Up @@ -359,6 +380,8 @@ macs = bp.mac_addresses() # MacAddresses(eth_mac='02:35:c7:76:b7:9b', wifi_
| `BENCHPOD_LIFT_DAC_LIMITS` | pytest sessions | `1` clears the pod's DAC output limits for the session and restores the same limits at the end, even when tests fail (only with the output stage switched off) |
| `BENCHPOD_TLS` | network connections | `auto` (default), `on` or `off`: TLS to the pod's LAN API on 8443, see [TLS on the LAN](#tls-on-the-lan) |
| `BENCHPOD_TLS_CA` | network connections over TLS | PEM file of CA certificates: verify the pod's certificate and host name instead of pinning it |
| `BENCHPOD_CLIENT_KEY_PEM` | network connections over TLS | This computer's TLS client certificate and key, PEM, for [LAN pairing](#lan-pairing) (a CI secret; `benchpod lan-clients add --new-key` prints one) instead of `client.key`/`client.crt` |
| `BENCHPOD_CLIENT_CERT`, `BENCHPOD_CLIENT_KEY` | network connections over TLS | The same as two files |
| `BENCHPOD_STALL_TIMEOUT` | flashing | seconds with no SWD traffic before a flash attempt is aborted and retried (default 60) |
| `BENCHPOD_SENSOR_LIBRARY` | no `version` argument / `--benchpod-sensor-library` | sensor library version: `latest` or a release such as `0.2.0` (default: the version the SDK pins), see [Emulated sensors](#emulated-sensors) |
| `BENCHPOD_LEASE` | connecting | a lease id to join instead of taking a new lease (set by `benchpod ci` for its child processes), see [Device leases](#device-leases) |
Expand Down Expand Up @@ -2610,6 +2633,7 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen
| `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) |
| `LanClients` | `lan_clients`, `pair` | `pairing` (computers on the LAN must be paired), `count`, `max`, `clients` (`LanClient`: `name`, `spki_sha256`, `this`), `has(spki_sha256)` |
| `UsbCcStatus` | `usb_cc` | `orientation`, `advertised`, `advertised_current` (A), `cc1_voltage`, `cc2_voltage` (V) |
| `PullState` | `pull_state`, `set_pull` | `la`, `enabled`, `direction`, `ohms`, `available`, `supported`, `strength` (digital v3r4) |
| `LaPinState` | `la_pins`, `configure_gpio`, `la_dir` | `la`, `function`, `gpio`, `level`, `pull`, `pull_ohms`, `pull_on`, `pull_dirs`, `dir`, `warn`, `warnings`, `in_use` |
Expand Down
1 change: 1 addition & 0 deletions packages/embeddedci/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ classifiers = [
]
dependencies = [
"pyserial>=3.5",
"cryptography>=41",
]

[project.optional-dependencies]
Expand Down
6 changes: 5 additions & 1 deletion packages/embeddedci/src/embeddedci/benchpod/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin
PodLeasedError,
PodLeaseLostError,
PodLockedError,
PodNotPairedError,
PullConflictError,
ReplyTooLargeError,
PullDirectionError,
Expand Down Expand Up @@ -142,7 +143,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, MacAddresses, Trigger
from .results import Capture, CorrelatedCapture, LaCapture, LanClient, LanClients, 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 (
Expand Down Expand Up @@ -359,6 +360,9 @@ def test_boots(benchpod_target, firmware): # fixtures from the pytest plugin
"ServerApiError",
"ServerPermissionDeniedError",
"PodLockedError",
"PodNotPairedError",
"LanClient",
"LanClients",
"PodBusyError",
"PodLeasedError",
"PodLeaseLostError",
Expand Down
76 changes: 75 additions & 1 deletion packages/embeddedci/src/embeddedci/benchpod/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,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, MacAddresses, Trigger
from .results import Capture, CorrelatedCapture, LaCapture, LanClient, LanClients, LanTls, MacAddresses, Trigger
from .wiring import Signal, Wiring
from .state import (
AdcRangeState,
Expand All @@ -134,6 +134,8 @@
from .transport import Transport, open_transport
from .transport.cloud import CloudTransport
from .transport.tcp import TcpTransport
from .transport import client_identity
from .transport import tls as _tls
from . import pod_lease as _pod_lease

if TYPE_CHECKING: # pragma: no cover
Expand Down Expand Up @@ -1329,6 +1331,78 @@ def lan_tls(self) -> "LanTls":
:class:`UnsupportedFeatureError` on older firmware."""
return LanTls.from_reply(self.command({"cmd": "lan_tls"}))

# -- LAN pairing ----------------------------------------------------------

def lan_clients(self, *, add: Optional[str] = None, spki_sha256: Optional[str] = None,
remove: Optional[str] = None, clear: bool = False) -> "LanClients":
"""The computers paired with the pod for use over Ethernet and Wi-Fi (firmware 4.0.1+).

Over the LAN the pod answers only status to a computer that is not paired
(:class:`PodNotPairedError`). ``add`` (a name) with ``spki_sha256`` pairs a key,
``remove`` unpairs the computers with that name or the one key starting with those hex
digits (8 or more), ``clear`` unpairs all; each change needs USB (the console or the USB
network) or the cloud (an organization owner or admin), never the LAN. Returns the list;
:attr:`LanClient.this` marks this computer. To pair this computer, :meth:`pair`."""
req: Dict[str, Any] = {"cmd": "lan_clients"}
if add is not None:
if not spki_sha256:
raise ValueError("lan_clients(add=...) needs spki_sha256")
req.update(add=client_identity.sanitize_name(add), spki_sha256=spki_sha256.lower())
elif remove is not None:
req["remove"] = str(remove)
elif clear:
req["clear"] = True
data = self.command(req)
mine = self._client_key_hash()
clients = list((data or {}).get("clients") or [])
total = int((data or {}).get("count") or 0)
while 0 < len(clients) < total: # the pod sends 12 a reply
more = self.command({"cmd": "lan_clients", "offset": len(clients)})
page = list((more or {}).get("clients") or [])
if not page:
break
clients.extend(page)
if isinstance(data, dict):
data = dict(data, clients=clients)
return LanClients.from_reply(data, mine)

def pair(self, name: Optional[str] = None) -> "LanClients":
"""Pair this computer with the pod (firmware 4.0.1+), so it may drive the pod over Ethernet
and Wi-Fi, not only read its status. Run it once over USB (``BenchPod("usb")``: the USB
network adapter or the console) or the cloud (``"embeddedci:<device>"``, as an
organization owner or admin); ``benchpod setup`` does the same. ``name`` defaults to this
computer's host name. Over USB it also pins the pod's LAN certificate for its LAN address,
so later LAN connections check they reach this very pod. Returns the list."""
key = client_identity.client_key_hash()
out = self.lan_clients(add=name or client_identity.pairing_name(), spki_sha256=key)
self._pin_lan_certificate()
return out

def set_lan_pairing(self, on: bool) -> bool:
"""Turn LAN pairing on (the default) or off (every computer on the network may use the pod,
as before firmware 4.0.1). Over USB or the cloud only. Returns the new setting."""
data = self.command({"cmd": "lan_policy", "pairing": bool(on)})
return bool((data or {}).get("pairing"))

def _client_key_hash(self) -> str:
try:
return client_identity.client_key_hash()
except Exception:
return ""

def _pin_lan_certificate(self) -> None:
"""After pairing over USB: pin the pod's certificate for its LAN address (best effort)."""
try:
sha = str((self.command({"cmd": "lan_tls"}) or {}).get("sha256") or "")
ip = str((self._transport.status() or {}).get("ip") or "")
except Exception:
return
if len(sha) == 64 and ip and not _tls.is_usb_link(ip):
try:
_tls.set_pin(ip, sha)
except (OSError, ValueError):
pass

def set_lan_tls_https_only(self, on: bool) -> "LanTls":
"""Turn HTTPS-only on (plaintext 8080 refused on Ethernet and Wi-Fi; the USB link keeps it)
or off. Turning it off needs a TLS, USB or cloud connection: over plaintext Ethernet or Wi-Fi
Expand Down
Loading