oep-client-python 0.0.53__py3-none-any.whl → 0.0.55__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.53"
+__version__ = "0.0.55"

oep_client/__main__.py

@@ -125,6 +125,17 @@ def main(argv=None) -> int:
     rs.add_argument("--reopen-s", type=float, default=0.0, metavar="S",
                     help="when the probe is not back within its restart_max_ms, open it again for up to S more seconds "
                          "(your reopen: a host where the device returns late, e.g. WSL re-attaching it through usbipd)")
+    ca = sub.add_parser("call", help="run any interface's op: by number with the request as hex bytes, or by the name and "
+                                     "fields its describe gives (core §7.4 op_name / op_field)")
+    ca.add_argument("probe", help="a probe: oep://UNIT_ID[?via=...], a serial port, tcp://HOST:PORT or usb")
+    ca.add_argument("interface", help="the interface's name (io.github.you.thing); its fn is looked up")
+    ca.add_argument("op", help="the op: a number (0x10) or its name")
+    ca.add_argument("args", nargs="*", help="NAME=VALUE per field (integers 10 or 0x, bools true / false, lists 1,2,3, "
+                                             "bytes hex, text as it is), or the request as hex bytes")
+    ca.add_argument("--text", action="store_true", help="the request is ARGS joined by spaces, as UTF-8 bytes")
+    ca.add_argument("--wait", type=float, metavar="S", help="the op is a job (oep::SimpleInterface::job): wait up to S "
+                                                            "seconds for it by the interface's status op, then show that")
+    ca.add_argument("--json", action="store_true")
     fd = sub.add_parser("find", help="probes on the local network that announce _oep._tcp (DNS-SD over mDNS)")
     fd.add_argument("--timeout", type=float, default=2.0, help="seconds to listen for answers (default 2)")
     fd.add_argument("--engine", choices=("auto", "zeroconf", "minimal"), default="auto",
@@ -157,6 +168,8 @@ def main(argv=None) -> int:
         return _restart_cmd(args)
     if args.command == "find":
         return _find_cmd(args)
+    if args.command == "call":
+        return _call_cmd(args)
 
     confirm = (0, 1)
     if args.virtual:
@@ -237,6 +250,82 @@ def _restart_cmd(args) -> int:
     return 0
 
 
+# ---- oep call -----------------------------------------------------------------------------------------------------
+
+def _field_value(field, text: str):
+    from . import call as c
+    t = field.type
+    if t & c.LIST:
+        items = [x for x in text.replace(" ", "").split(",") if x]
+        return [(x.lower() in ("1", "true")) if (t & ~c.LIST) == c.T["bool"] else int(x, 0) for x in items]
+    if t == c.T["bool"]:
+        if text.lower() not in ("0", "1", "true", "false"):
+            raise SystemExit(f"oep call: {field.name} takes true or false")
+        return text.lower() in ("1", "true")
+    if t == c.T["bytes"]:
+        return bytes.fromhex(text)
+    if t == c.T["text"]:
+        return text
+    return int(text, 0)
+
+
+def _call_cmd(args) -> int:
+    import json
+    from . import call as c
+    hst = _open_host(args.probe)
+    try:
+        forms = c.ops(hst, args.interface)
+    except c.NotOffered as e:
+        raise SystemExit(f"oep call: {e}") from None
+    op: int | str = int(args.op, 0) if args.op[:1].isdigit() else args.op
+    form = forms.get(op) if isinstance(op, int) else next((f for f in forms.values() if f.name == op), None)
+    payload, fields = None, {}
+    if args.text:
+        payload = " ".join(args.args).encode()
+    elif form is not None and form.form and (any("=" in a for a in args.args) or not args.args):
+        by_name = {f.name: f for f in form.request}
+        for item in args.args:
+            name, eq, value = item.partition("=")
+            if not eq or name not in by_name:
+                raise SystemExit(f"oep call: {form.signature()}: give NAME=VALUE for its fields ({item!r})")
+            fields[name] = _field_value(by_name[name], value)
+    else:
+        try:
+            payload = bytes.fromhex("".join(args.args))
+        except ValueError:
+            raise SystemExit("oep call: the request as hex bytes (its describe gives this op no fields)") from None
+    if not (form is not None and form.lock_free):
+        core.take(hst, 10000 + int((args.wait or 0) * 1000), owner="oep call")   # a job's wait inside the lease
+    try:
+        if args.wait is not None:
+            r = c.call_wait(hst, args.interface, op, payload, timeout=args.wait, **fields)
+        else:
+            r = c.call(hst, args.interface, op, payload, **fields)
+    except (c.JobFailed, c.JobCancelled, c.JobTimeout, c.ProbeRestarted) as e:
+        st = getattr(e, "status", {})
+        print(json.dumps({"result": type(e).__name__, "why": str(e), "status": st}, default=str) if args.json
+              else f"{type(e).__name__}  {e}")
+        return 1
+    except TypeError as e:
+        raise SystemExit(f"oep call: {e}") from None
+    except c.NotOffered as e:
+        raise SystemExit(f"oep call: {e}") from None
+    except c.CommandFailed as e:
+        out = {"result": "failed", "op": e.op, "fields": e.fields, "payload": e.payload.hex()}
+        print(json.dumps(out, default=str) if args.json else f"failed  {e}" + ("" if e.fields else f"  {e.payload.hex()}"))
+        return 1
+    except c.CommandRejected as e:
+        print(json.dumps({"result": "rejected", "op": e.op, "why": str(e)}) if args.json else f"rejected  {e}")
+        return 1
+    shown = {k: (v.hex() if isinstance(v, bytes) else v) for k, v in r.items()}
+    if args.json:
+        print(json.dumps({"result": "completed", "revision": r.revision, "fields": shown, "payload": r.payload.hex()}))
+    else:
+        body = "  ".join(f"{k}={v}" for k, v in shown.items()) if shown or (form and form.form) else r.payload.hex()
+        print(f"completed  rev {r.revision}  {body}".rstrip())
+    return 0
+
+
 # ---- oep pins -----------------------------------------------------------------------------------------------------
 
 def _pins_cmd(args) -> int:

oep_client/brokers.py

@@ -0,0 +1,149 @@
+"""Finding a broker that serves a probe, and opening a session that shares its lock (OEP host guide §7.1, §7.2).
+
+A broker publishes itself in the user's directory `oep/brokers/<unit_id>.json`: where to connect (`endpoints`, each with
+a `kind`; `tcp` is transports §1's TCP form) and the sharing extensions it takes (`share`). A tool tries, in order:
+
+1. the environment variable `OEP_BROKER` (`<host>:<port>`), for a broker on another machine or a test;
+2. the file: each endpoint of a kind it knows, checking that fn 0's describe names the file's unit_id (a dead broker's
+   port may now be another probe's broker);
+3. the probe itself.
+
+The tool joins with the sharing extension `oep.probe.share` (critical): sessions and resources are the client's, the
+broker holds the probe's lock and lease. A tool never deletes a broker's files: only the broker holding
+`<unit_id>.lock` removes or rewrites `<unit_id>.json`, and `<unit_id>.lock` stays.
+
+    from oep_client import brokers
+    hst = brokers.open_host("30eda0e31108", owner="my-tool")   # through the broker when one serves it, else directly
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SHARE = "oep.probe.share"             # host guide §7.1
+ENV = "OEP_BROKER"                    # host guide §7.2: <host>:<port>, before the file
+LEASE_MS = 60000
+
+
+def directory() -> Path:
+    """The user's broker directory (host guide §7.2): Linux $XDG_RUNTIME_DIR/oep/brokers, else
+    $TMPDIR/oep-<uid>/brokers (/tmp without TMPDIR); macOS $TMPDIR/oep/brokers; Windows %LOCALAPPDATA%\\oep\\brokers."""
+    if sys.platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local") / "oep" / "brokers"
+    if sys.platform == "darwin":
+        return Path(os.environ.get("TMPDIR") or tempfile.gettempdir()) / "oep" / "brokers"
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime:
+        return Path(runtime) / "oep" / "brokers"
+    return Path(os.environ.get("TMPDIR") or "/tmp") / f"oep-{os.getuid()}" / "brokers"
+
+
+def _private(path: Path) -> bool:
+    """The directory is the user's own and closed to others (0700); not checked on Windows (its ACLs)."""
+    if sys.platform == "win32":
+        return path.is_dir()
+    try:
+        st = path.stat()
+    except OSError:
+        return False
+    return stat.S_ISDIR(st.st_mode) and st.st_uid == os.getuid() and stat.S_IMODE(st.st_mode) & 0o077 == 0
+
+
+@dataclass
+class Broker:
+    """One broker as its file (or OEP_BROKER) names it."""
+    unit_id: str
+    endpoints: list[dict] = field(default_factory=list)
+    share: list[str] = field(default_factory=list)
+    pid: int | None = None
+    implementation: dict = field(default_factory=dict)
+
+    def tcp(self) -> list[tuple[str, int]]:
+        """The endpoints this client can use: kind tcp, `host:port`. Other kinds are skipped."""
+        out = []
+        for e in self.endpoints:
+            if isinstance(e, dict) and e.get("kind") == "tcp" and isinstance(e.get("address"), str):
+                host, _, port = e["address"].rpartition(":")
+                if host and port.isdigit():
+                    out.append((host, int(port)))
+        return out
+
+
+def find(unit_id: str, *, environ=None, base: Path | None = None) -> Broker | None:
+    """The broker for this probe: OEP_BROKER, else its file in the user's directory, else None. Not connected yet."""
+    environ = os.environ if environ is None else environ
+    unit = unit_id.lower()
+    forced = environ.get(ENV)
+    if forced:
+        return Broker(unit, [{"kind": "tcp", "address": forced}], [SHARE])
+    if unit.startswith("x-"):
+        return None                               # not unique: never keyed by (core §7.5)
+    folder = base or directory()
+    if not _private(folder):
+        return None
+    try:
+        doc = json.loads((folder / f"{unit}.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(doc, dict) or str(doc.get("unit_id", "")).lower() != unit:
+        return None
+    share = [s for s in doc.get("share") or [] if isinstance(s, str)]
+    endpoints = [e for e in doc.get("endpoints") or [] if isinstance(e, dict)]
+    pid = doc.get("pid") if isinstance(doc.get("pid"), int) else None
+    impl = doc.get("implementation") if isinstance(doc.get("implementation"), dict) else {}
+    return Broker(unit, endpoints, share, pid, impl)
+
+
+def connect(broker: Broker, *, timeout: float = 3.0):
+    """A Host on the first endpoint that answers with the broker's unit_id in fn 0's describe, not opened; None when
+    none does (a dead broker, or its port reused by another probe's broker)."""
+    from . import core, host as oh, link
+    for address, port in broker.tcp():
+        try:
+            lk = link.SerialLink.on_stream(link.TcpStream(address, port), "length", timeout)
+        except OSError:
+            continue
+        lk.resend = False                         # the broker retries towards the probe itself (link.open_host)
+        lk.transport = "tcp"
+        h = oh.Host(lk.send)
+        lk.attach_host(h)
+        h.link = lk
+        try:
+            same = (core.unit_id(h) or "").lower() == broker.unit_id
+        except Exception:
+            same = False
+        if same:
+            return h
+        lk.close()
+    return None
+
+
+def open_host(unit_id: str, owner: str, *, lease_ms: int = LEASE_MS, direct: str | None = None, environ=None):
+    """An opened Host on the probe: sharing the broker's lock when one serves it (host guide §7.2), else the probe
+    itself (`direct`, default oep://<unit_id>). A broker that does not take oep.probe.share is used without it."""
+    from . import host as oh, link, message as m
+    broker = find(unit_id, environ=environ)
+    h = connect(broker) if broker else None
+    if h is not None:
+        try:
+            if SHARE in broker.share:
+                try:
+                    h.open(lease_ms, owner=owner, extensions=[SHARE])
+                    return h
+                except oh.Unsupported as e:
+                    if e.tag != m.TAG_NAMED_EXTENSION | m.TAG_CRITICAL:
+                        raise
+            h.open(lease_ms, owner=owner)
+            return h
+        except Exception:
+            h.link.close()
+            raise
+    h = link.open_host(direct or f"oep://{unit_id}")
+    h.open(lease_ms, owner=owner)
+    return h

oep_client/call.py

@@ -0,0 +1,284 @@
+"""Call any interface's op by its number, or by the name and fields its describe gives (oep-core §7.4 op_name /
+op_field) - an interface this host has no module for, such as a sketch's oep::SimpleInterface.
+
+    from oep_client import link, core
+    from oep_client.call import call
+    hst = link.open_host("/dev/ttyACM0")
+    core.take(hst, 10000, owner="my-test")
+    r = call(hst, "io.github.yourname.mine", "add", a=2, b=3)
+    r["sum"], r.sum, r.revision                     # the success fields by name; the interface's revision
+    call(hst, "io.github.yourname.mine", 0x10, b"\\x02\\0\\0\\0\\x03\\0\\0\\0").payload   # by number, the bytes as they are
+
+Errors: InterfaceMissing / RevisionMismatch / OpMissing (all NotOffered: a test can turn them into a skip),
+CommandRejected (the probe refused it: the reason), CommandFailed (completed failed: code and message when the op
+gives them).
+
+A job (oep::SimpleInterface::job: it starts work on the probe's worker and answers at once) and its status op:
+
+    st = call_wait(hst, "io.github.yourname.mine", "collect", count=3, timeout=10)
+    st.start_ns, st.end_ns                          # on the probe's clock (a capture's markers' one)
+    # wait=: a stream's wait (acquire.Request(during=...)) keeps the capture collecting while this waits
+
+JobFailed (the job's Worker::fail: code, message), JobCancelled, JobTimeout (cancel sent first), ProbeRestarted (its
+boot_id changed while the job ran)."""
+
+from __future__ import annotations
+
+import struct
+import time
+from typing import Any, Callable
+
+from . import catalog, core, host as h
+
+T = catalog.OP_FIELD_TYPES
+LIST = catalog.OP_FIELD_LIST
+_INT = {T["u8"]: "<B", T["u16"]: "<H", T["u32"]: "<I", T["u64"]: "<Q",
+        T["i8"]: "<b", T["i16"]: "<h", T["i32"]: "<i", T["i64"]: "<q", T["bool"]: "<B"}
+
+
+class NotOffered(LookupError):
+    """The probe does not offer what was asked: no such interface, another revision, no such op."""
+
+
+class InterfaceMissing(NotOffered):
+    pass
+
+
+class RevisionMismatch(NotOffered):
+    def __init__(self, interface: str, revision: int, wanted: int):
+        super().__init__(f"{interface} is revision {revision} on this probe, {wanted} asked")
+        self.revision, self.wanted = revision, wanted
+
+
+class OpMissing(NotOffered):
+    pass
+
+
+class CommandRejected(h.Rejected):
+    """The probe refused the op (resolution rejected): `result.detail` is the reason (core §4.3)."""
+
+    def __init__(self, op: str, result):
+        super().__init__(result)
+        self.op = op
+        self.args = (f"{op}: {result.describe()}",)
+
+
+class CommandFailed(h.Failed):
+    """The op ran and did not work (completed failed / partial): `fields` the failed part decoded (code, message for
+    an oep::SimpleInterface op), `payload` the bytes."""
+
+    def __init__(self, op: str, result, fields: dict | None):
+        why = f"{op}: {result.describe()}"
+        if fields and "code" in fields:
+            why += f" (code {fields['code']}" + (f": {fields['message']}" if fields.get("message") else "") + ")"
+        super().__init__(result, why)
+        self.op, self.fields, self.payload = op, fields or {}, result.payload
+        self.code, self.message = self.fields.get("code"), self.fields.get("message")
+
+
+class JobFailed(h.OepError):
+    """The job ended failed: `code` and `message` from its Worker::fail(), `status` the status op's fields."""
+
+    def __init__(self, op: str, status: dict):
+        super().__init__(f"{op}: failed (code {status.get('code')}"
+                         + (f": {status['message']}" if status.get("message") else "") + ")")
+        self.op, self.status, self.code, self.message = op, status, status.get("code"), status.get("message")
+
+
+class JobCancelled(h.OepError):
+    """The job stopped on a cancel (`status` the status op's fields)."""
+
+    def __init__(self, op: str, status: dict):
+        super().__init__(f"{op}: cancelled")
+        self.op, self.status = op, status
+
+
+class JobTimeout(h.OepError, TimeoutError):
+    """The job still ran at the timeout; a cancel was sent (`status` the last status op's fields)."""
+
+    def __init__(self, op: str, timeout: float, status: dict):
+        super().__init__(f"{op}: still running after {timeout} s (cancel sent)")
+        self.op, self.status = op, status
+
+
+class ProbeRestarted(h.OepError):
+    """The probe's boot_id changed while the job ran (core §6.5): it restarted, the job with it."""
+
+
+# The status op's state (oep::Worker::State): the firmware's convention, not the registry's
+JOB_STATES = {"idle": 0, "running": 1, "done": 2, "failed": 3, "cancelled": 4}
+
+
+class CallResult(dict):
+    """The success fields by name (a dict, and attributes), the raw payload, the interface's revision and the op."""
+
+    def __init__(self, fields: dict, payload: bytes, revision: int, op: catalog.OpForm | int):
+        super().__init__(fields)
+        self.payload, self.revision, self.op = payload, revision, op
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+def encode(fields: list[catalog.OpField], values: dict) -> bytes:
+    """A request's fixed part from values by field name (ints, bools, bytes, str, lists of ints / bools)."""
+    missing = [f.name for f in fields if f.name not in values]
+    extra = sorted(set(values) - {f.name for f in fields})
+    if missing or extra:
+        raise TypeError(f"fields {', '.join(f'{f.name}: {f.type_name}' for f in fields) or 'none'}"
+                        + (f"; missing {missing}" if missing else "") + (f"; not fields {extra}" if extra else ""))
+    out = b""
+    for f in fields:
+        v = values[f.name]
+        if f.type & LIST:
+            items = list(v)
+            out += struct.pack("<H", len(items)) + b"".join(struct.pack(_INT[f.type & ~LIST], int(x)) for x in items)
+        elif f.type == T["bytes"]:
+            b = bytes(v)
+            out += struct.pack("<H", len(b)) + b
+        elif f.type == T["text"]:
+            b = str(v).encode()
+            out += struct.pack("<H", len(b)) + b
+        elif f.type in _INT:
+            out += struct.pack(_INT[f.type], int(v))
+        else:
+            raise TypeError(f"{f.name}: type {f.type} unknown to this host")
+    return out
+
+
+def decode(fields: list[catalog.OpField], payload: bytes) -> tuple[dict, bytes]:
+    """A fixed part's fields by name, and what follows them (the TLVs)."""
+    out, at = {}, 0
+    for f in fields:
+        if f.type & LIST:
+            (n,) = struct.unpack_from("<H", payload, at)
+            fmt = _INT[f.type & ~LIST]
+            w = struct.calcsize(fmt)
+            vals = [struct.unpack_from(fmt, payload, at + 2 + i * w)[0] for i in range(n)]
+            out[f.name] = [bool(x) for x in vals] if (f.type & ~LIST) == T["bool"] else vals
+            at += 2 + n * w
+        elif f.type in (T["bytes"], T["text"]):
+            (n,) = struct.unpack_from("<H", payload, at)
+            if at + 2 + n > len(payload):
+                raise h.ShortPayload(f"{f.name}: {n} bytes, the answer ends before")
+            raw = payload[at + 2:at + 2 + n]
+            out[f.name] = raw.decode("utf-8", "replace") if f.type == T["text"] else raw
+            at += 2 + n
+        else:
+            fmt = _INT[f.type]
+            out[f.name] = struct.unpack_from(fmt, payload, at)[0]
+            if f.type == T["bool"]:
+                out[f.name] = bool(out[f.name])
+            at += struct.calcsize(fmt)
+    return out, payload[at:]
+
+
+def ops(hst: h.Host, interface: str | int) -> dict[int, catalog.OpForm]:
+    """The op_name / op_field an interface's describe gives (by op number; empty when it gives none)."""
+    fn = interface if isinstance(interface, int) else _fn(hst, interface)
+    return catalog.decode_description(b"".join(catalog.tlv(t, v) for t, v in core.describe(hst, fn))).op_forms
+
+
+def _fn(hst: h.Host, interface: str) -> int:
+    try:
+        return core.find(hst, interface)
+    except LookupError as e:
+        raise InterfaceMissing(str(e)) from None
+
+
+def call(hst: h.Host, interface: str, op: int | str, payload: bytes | None = None, *, locked: bool | None = None,
+         revision: int | None = None, expect_ms: int = 0, **fields) -> CallResult:
+    """Run `op` (a number, or a name from the describe's op_name) of `interface` on the session `hst` holds.
+    payload: the request as bytes (then no fields); otherwise the fields by name, packed as op_field says.
+    locked: send it in the session (default: unless op_name says lock_free). revision: the one expected."""
+    fn = _fn(hst, interface)
+    rev = core.revision(hst, interface, fn)
+    if revision is not None and rev != revision:
+        raise RevisionMismatch(interface, rev, revision)
+    forms = ops(hst, fn)
+    if isinstance(op, str):
+        form = next((f for f in forms.values() if f.name == op), None)
+        if form is None:
+            raise OpMissing(f"{interface} has no op named {op!r}" + (f" (it names {', '.join(f.name for f in forms.values())})"
+                                                                     if forms else " (its describe names none)"))
+        code = form.op
+    else:
+        code, form = op, forms.get(op)
+    label = form.name if form else f"0x{code:02x}"
+    if not core.offers(hst, fn, code):
+        raise OpMissing(f"{interface} does not offer op {label}")
+    if payload is None:
+        if fields:
+            if form is None or not form.form:
+                raise TypeError(f"{interface} {label}: its describe gives no fields; pass payload= as bytes")
+            payload = encode(form.request, fields)
+        elif form is not None and form.form and form.request:
+            payload = encode(form.request, fields)        # raises: the fields it needs
+        else:
+            payload = b""
+    elif fields:
+        raise TypeError("payload= or fields, not both")
+    if locked is None:
+        locked = not (form is not None and form.lock_free)
+    try:
+        r = hst.request(fn, code, payload, locked=locked, expect_ms=expect_ms)
+    except h.Rejected as e:
+        raise CommandRejected(label, e.result) from None
+    if r.succeeded:
+        got = decode(form.success, r.payload)[0] if form is not None and form.form else {}
+        return CallResult(got, r.payload, rev, form or code)
+    failed = None
+    if r.ran and form is not None and form.form and form.failed:
+        try:
+            failed = decode(form.failed, r.payload)[0]
+        except (struct.error, h.ShortPayload):
+            failed = None                                  # a failed answer without its fields (a firmware bug)
+    raise CommandFailed(label, r, failed)
+
+
+def call_wait(hst: h.Host, interface: str, op: int | str, payload: bytes | None = None, *, timeout: float,
+              wait: Callable[[float], None] | None = None, interval: float = 0.05, status: str = "status",
+              cancel: str = "cancel", revision: int | None = None, **fields) -> CallResult:
+    """Start the job `op` (as call()) and wait for it by its `status` op: the status's fields when it ended done.
+    wait(seconds) sleeps between the status reads (time.sleep by default; a stream's wait keeps a capture going)."""
+    boot = hst.clock().boot_id
+    started = call(hst, interface, op, payload, revision=revision, **fields)
+    code = started.op.op if isinstance(started.op, catalog.OpForm) else started.op
+    label = started.op.name if isinstance(started.op, catalog.OpForm) else f"0x{code:02x}"
+    pause = wait or time.sleep
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            st = call(hst, interface, status)
+        except (h.OepError, OSError):
+            _restarted(hst, boot, label)
+            raise
+        if st["op"] != code or st["state"] == JOB_STATES["idle"]:
+            _restarted(hst, boot, label)
+            raise ProbeRestarted(f"{label}: the status names op {st['op']} in state {st['state']}, not this job")
+        if st["state"] != JOB_STATES["running"]:
+            break
+        if time.monotonic() >= deadline:
+            try:
+                call(hst, interface, cancel)
+            except (h.OepError, OSError):
+                pass                                       # the timeout is the error to report
+            raise JobTimeout(label, timeout, dict(st))
+        pause(interval)
+    if st["state"] == JOB_STATES["failed"]:
+        raise JobFailed(label, dict(st))
+    if st["state"] == JOB_STATES["cancelled"]:
+        raise JobCancelled(label, dict(st))
+    return st
+
+
+def _restarted(hst: h.Host, boot: int, label: str) -> None:
+    try:
+        now = hst.clock().boot_id
+    except (h.OepError, OSError):
+        return
+    if now != boot:
+        raise ProbeRestarted(f"{label}: the probe restarted while the job ran (boot_id {boot:#x} -> {now:#x})")

oep_client/catalog.py

@@ -32,6 +32,13 @@ MIN_CLOCK_HZ = _COMMON["min_clock_hz"]     # u32
 FEATURES = _COMMON["features"]             # u32, bits defined by the interface
 CHANNEL_GROUP = _COMMON["channel_group"]   # group(u8) n(u8) then n x (role(u8), channel(u16)): a fixed pin set
 OPS = _COMMON["ops"]                       # base(u8) bitmap: the ops this fn offers (core §1.2, §7.4)
+OP_NAME = _COMMON["op_name"]               # op(u8) flags(u8) name: an op's name (core §7.4, optional)
+OP_FIELD = _COMMON["op_field"]             # op(u8) part(u8) type(u8) name: one field of an op's fixed part (core §7.4)
+OP_NAME_FORM = reg.CORE.enum["op_name_flag"]["form"]
+OP_NAME_LOCK_FREE = reg.CORE.enum["op_name_flag"]["lock_free"]
+OP_FIELD_PARTS = reg.CORE.enum["op_field_part"]          # request / success / failed
+OP_FIELD_TYPES = reg.CORE.enum["op_field_type"]          # u8 ... text, and the list bit
+OP_FIELD_LIST = OP_FIELD_TYPES["list"]
 assert OPS == m.TAG_OPS
 CRITICAL = 0x80
 INTERFACE_TAG_FIRST = 0x40
@@ -197,6 +204,50 @@ def text(tag: int, s: str) -> bytes:
     return tlv(tag, s.encode("ascii"))
 
 
+class OpField:
+    """One field of an op's fixed part (core §7.4 op_field): its name and type (registry op_field_type)."""
+
+    def __init__(self, name: str, type: int):
+        self.name, self.type = name, type
+
+    @property
+    def type_name(self) -> str:
+        names = {v: k for k, v in OP_FIELD_TYPES.items() if k != "list"}
+        base = self.type & ~OP_FIELD_LIST
+        label = names.get(base, f"type{base}")
+        return label + "[]" if self.type & OP_FIELD_LIST else label
+
+    def __repr__(self) -> str:
+        return f"{self.name}: {self.type_name}"
+
+
+@dataclass
+class OpForm:
+    """An op's name and, with form, its request / success / failed fixed parts' fields (core §7.4)."""
+
+    op: int
+    name: str
+    flags: int
+    request: list[OpField] = field(default_factory=list)
+    success: list[OpField] = field(default_factory=list)
+    failed: list[OpField] = field(default_factory=list)
+
+    @property
+    def form(self) -> bool:
+        return bool(self.flags & OP_NAME_FORM)
+
+    @property
+    def lock_free(self) -> bool:
+        return bool(self.flags & OP_NAME_LOCK_FREE)
+
+    def signature(self) -> str:
+        """measure(mode: u8) -> temp: i32, hum: u32 (the name alone without form)"""
+        if not self.form:
+            return self.name
+        s = f"{self.name}({', '.join(map(repr, self.request))})"
+        return s + (" -> " + ", ".join(map(repr, self.success)) if self.success else "")
+
+
 @dataclass
 class Description:
     """Common tags decoded; interface-specific and unknown tags kept raw, in order."""
@@ -212,11 +263,13 @@ class Description:
     specific: list[tuple[int, bytes]] = field(default_factory=list)
     unknown_critical: list[int] = field(default_factory=list)
     broken: list[int] = field(default_factory=list)   # common tags whose value is not their defined length (not used)
+    op_forms: dict[int, OpForm] = field(default_factory=dict)   # op -> its op_name / op_field (core §7.4)
 
 
 def decode_description(data: bytes) -> Description:
     d = Description()
     seen: set[int] = set()
+    fields: list[tuple[int, int, int, str]] = []         # op_field (op, part, type, name), in the describe's order
     for tag, value in split_tlv(data):
         if tag & CRITICAL:
             continue                                # bit 7 in an answer: an unknown tag, skipped (core §2.2)
@@ -248,11 +301,28 @@ def decode_description(data: bytes) -> Description:
                 d.ops_invalid = why
             else:
                 d.ops = unpack_ops(value)
+        elif t == OP_NAME:
+            if len(value) < 3:
+                d.broken.append(tag)
+                continue
+            if value[0] in d.op_forms:
+                continue                                    # a second op_name for an op: the first is used
+            d.op_forms[value[0]] = OpForm(value[0], value[2:].decode("ascii", "replace"), value[1])
+        elif t == OP_FIELD:
+            if len(value) < 4:
+                d.broken.append(tag)
+                continue
+            fields.append((value[0], value[1], value[2], value[3:].decode("ascii", "replace")))
         elif t >= INTERFACE_TAG_FIRST:
             d.specific.append((tag, value))
         elif tag & CRITICAL:
             d.unknown_critical.append(tag)
         # an unknown non-critical common tag is skipped
+    parts = {OP_FIELD_PARTS["request"]: "request", OP_FIELD_PARTS["success"]: "success", OP_FIELD_PARTS["failed"]: "failed"}
+    for op, part, type_, name in fields:                   # only an op named with form takes its fields
+        form = d.op_forms.get(op)
+        if form is not None and form.form and part in parts:
+            getattr(form, parts[part]).append(OpField(name, type_))
     for role in d.roles:
         d.roles[role] = sorted(set(d.roles[role]))
     if d.ops_invalid:

oep_client/conformance/__init__.py

@@ -145,7 +145,7 @@ def checker_sources_sha256():
             for name in CHECKER_SOURCES}
 
 
-REVIEWED_CORE_SHA256 = '0408d232e728bb9692ab1c24cefa1fdbf109c35aeebd378034d86c0f4d19789a'   # oep-spec docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = '81cffc532f2626812b109d0aa5eef81636799011f410a8bc2fb9ea520fcbf4bc'   # oep-spec docs/oep-core.ja.md
 
 
 def require_reviewed_contract(registry, spec=None):