oep-client-python 0.0.38__py3-none-any.whl → 0.0.40__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.38"
+__version__ = "0.0.40"

oep_client/__main__.py

@@ -1,6 +1,6 @@
 """The oep command: what a probe offers (dump) and its settings (settings, core §13).
 
-  oep dump --port /run/board-identify/by-id/<probe>        oep dump --virtual p4-x035 --prefix oep.target --json
+  oep dump --port /dev/ttyACM0                              oep dump --virtual p4-x035 --prefix oep.target --json
   oep settings show <probe>               (every value, the storage state; lock-free)
   oep settings items <probe>              (what each owner declares: names, forms, choices)
   oep settings set <probe> core channel.GPIO23.label=v003.nrst channel.GPIO20.idle=pull-up [--save]
@@ -101,11 +101,19 @@ def main(argv=None) -> int:
                     "see which channels follow it (never touched without this)")
     pn.add_argument("--exclude", default="", help="channels never to read, scan or hold, comma-separated")
     pn.add_argument("--wire", choices=("swio", "rvswd", "swd"), default="swio")
-    pn.add_argument("--steps", default="classify,hold,scan,identify,reset,labels",
-                    help="the steps to run, comma-separated (default all: classify, hold, scan, identify, reset, labels)")
+    pn.add_argument("--pairs", default="",
+                    help="the pairs to scan instead of what classify allows: SWDIO:SWCLK,... (swio: SWIO,...); the host's "
+                    "word - no reading decides")
+    pn.add_argument("--steps", default="classify,hold,scan,identify,map,reset,labels",
+                    help="the steps to run, comma-separated (default all: classify, hold, scan, identify, map, reset, "
+                    "labels)")
+    pn.add_argument("--budget", type=float, default=55.0, help="seconds the whole run may take (default 55); a wider "
+                    "scan wants more (pairs go the nearest first: about 0.1 s each over rvswd)")
+    pn.add_argument("--all-pairs", action="store_true", help="scan every pair, not only up to the first that answers "
+                    "(a second target shows; needs the time)")
     pn.add_argument("--save", action="store_true", help="write the suggested labels (settings set, then save)")
-    pn.add_argument("--name", help="the host's connection profile name: labels <name>.nrst / <name>.power_hi (a probe "
-                    "serving several targets; default: nrst / power_hi)")
+    pn.add_argument("--name", help="the host's connection profile name: labels <name>.swdio / <name>.swclk (or "
+                    "<name>.swio), <name>.nrst, <name>.power_hi; the probe is then opened as oep://<unit_id>/<name>")
     pn.add_argument("--json", action="store_true", help="the report as JSON (the steps' lines go to stderr)")
     ck = sub.add_parser("clock", help="the probe's clock (fn 0 clock, core §7.6) against this host's: lock-free")
     ck.add_argument("probe", help="a probe: a serial port, tcp://HOST:PORT or usb[:VID:PID[:SERIAL]]")
@@ -238,8 +246,15 @@ def _pins_cmd(args) -> int:
     hst = _open_host(args.probe)
     try:
         core.take(hst, 10000, owner="oep pins")
+        pairs = None
+        if args.pairs:
+            pairs = []
+            for item in args.pairs.replace(" ", "").split(","):
+                dio, _, clk = item.partition(":")
+                pairs.append((int(dio, 0), int(clk, 0) if clk else 0xFFFF))
         finder = pins.PinFinder(hst, wire=args.wire, power=args.power, exclude=exclude, say=say, probe=args.probe,
-                                save=args.save, name=args.name)
+                                save=args.save, name=args.name, pairs=pairs, budget_s=args.budget,
+                                all_pairs=args.all_pairs)
         report = finder.run(steps=tuple(s for s in args.steps.split(",") if s))
         say(f"done in {report.elapsed_s:.1f} s")
         if args.json:
@@ -253,7 +268,7 @@ def _pins_cmd(args) -> int:
         return 2
     finally:
         hst.link.close()
-    return 0 if report.resolution == 'unique-candidate' else 1
+    return 0 if report.resolution in ('unique-candidate', 'unique-in-partial') else 1   # one target found
 
 
 # ---- oep linktest -------------------------------------------------------------------------------------------------

oep_client/capture.py

@@ -1,4 +1,4 @@
-"""oep.fixture.logic / oep.fixture.analog / oep.fixture.capture-group revision 1 (oep-spec a09fa45
+"""oep.fixture.logic / oep.fixture.analog / oep.fixture.capture-group revision 1 (oep-spec
 interfaces/oep-if-capture.ja.md: §1 layouts, §2 segments, §3 operations, §3.7 calibration, §4 groups). Numbers from
 `registry`.
 
@@ -51,6 +51,13 @@ MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER, TRIGGER_OPTS, FORMAT, CARRIA
     _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger", "trigger_opts",
                                        "format", "carriage", "block_max"))
 ANSWER_FORMAT, ANSWER_BLOCK = _CAP.tlv["configure_answer"]["format"], _CAP.tlv["configure_answer"]["block"]
+ANSWER_FORMAT_NAME = _CAP.tlv["configure_answer"]["format_name"]
+# §3.8 / §3.9, optional (a probe declares them in its describe): configure TLVs by name, sent critical
+OPTION_TLV = {**_CAP.tlv["configure"], **_ANA.tlv["configure"]}
+LOGIC_USED = {k: _CAP.tlv["configure_answer"][k] for k in ("threshold_used", "glitch_used", "timebase")}
+ANALOG_USED = {k: _ANA.tlv["configure_answer"][k] for k in ("coupling_used", "offset_used", "bandwidth_used",
+                                                            "resolution_used", "oversample_used")}
+NO_QUALIFIER = 0xFF                                        # clock: qualifier_role none (§3.8)
 STREAM_BUFFER = _CAP.tlv["configure_answer"]["stream_buffer"]
 JUDGE_LATENCY = _CAP.tlv["configure_answer"]["judge_latency_ns"]
 DATA_FORMAT = _CAP.enum["data_format"]
@@ -172,6 +179,11 @@ class Config:
     judge_latency_ns: int | None = None   # judging a group's trigger source condition, the longest to know it (§3.3, §4.4)
     raw_roles: list[int] = field(default_factory=list)         # format 1: the raw channels' roles (as asked)
     event_d: dict[int, int] = field(default_factory=dict)      # format 1: events role -> D (as asked)
+    carriage: dict[int, tuple[int, int]] = field(default_factory=dict)   # format 2: role -> (kind, D) (as asked)
+    format_name: str | None = None                             # format 0xFF: the named format in use
+    timebase: Fraction | None = None                           # format 3: the delta's tick rate (Hz)
+    external_clock: bool = False                               # sampled on a clock line (actual_rate 0 / 1, §3.8)
+    used: dict[str, dict[int, int] | int] = field(default_factory=dict)   # §3.8's *_used: name -> group/role -> value
 
     def tolerable_delay_s(self, worst_bytes_per_s: float | None = None) -> float | None:
         """Streaming: how long the host may stop reading before the probe drops (§3.3: stream_buffer over the data rate;
@@ -183,7 +195,9 @@ class Config:
         return self.stream_buffer / rate if rate else None
 
     def segment_bytes(self, samples: int) -> int:
-        """Length of a segment of `samples` samples in the stream (§1.1 rule 4, §1.2 rule 3)."""
+        """Length of a segment of `samples` samples in the stream (§1.1 rule 4, §1.2 rule 3; format 2: its blocks, §1.4)."""
+        if self.format == DATA_FORMAT["analog_blocks"]:
+            return capture_blocks.analog_segment_bytes(samples, self.order, self.carriage, self.block, self.bits)
         if self.width:
             return (samples * self.width + 7) // 8
         return samples * len(self.order) * self.slot // 8
@@ -437,6 +451,27 @@ def take_events(link, fn: int) -> list[bytes]:
     return mine
 
 
+def _options(options: dict) -> bytes:
+    """§3.8 / §3.9's configure TLVs, critical but overflow (configure's `options`)."""
+    forms = {"threshold": "<iI", "glitch_filter": "<I", "coupling": "<B", "offset": "<i", "bandwidth": "<I"}
+    out = b""
+    for name, value in options.items():
+        tag = OPTION_TLV[name] | (0 if name == "overflow" else CRITICAL)   # overflow: §3.3's table, as block_max
+        if name in forms:                                  # per group / role
+            for key, v in sorted(value.items()):
+                out += m.tlv(tag, bytes([key]) + struct.pack(forms[name], *(v if isinstance(v, tuple) else (v,))))
+        elif name == "clock":
+            role, edge, qualifier, level = value
+            out += m.tlv(tag, bytes([role, edge, NO_QUALIFIER if qualifier is None else qualifier, level]))
+        elif name == "oversample":
+            out += m.tlv(tag, struct.pack("<H", value))
+        elif name == "data_path":
+            out += m.tlv(tag, bytes(value))
+        else:                                              # resolution, overflow: u8
+            out += m.tlv(tag, bytes([value]))
+    return out
+
+
 def _config(payload: bytes, analog: bool) -> Config:
     """configure's answer TLVs (§3.3). A tag that does not repeat is taken from its first copy only, and a value not of
     its defined length (layout: its count and length) is broken and not used - nor replaced by a later copy (core
@@ -452,6 +487,7 @@ def _config(payload: bytes, analog: bool) -> Config:
         if tag == ACTUAL_RATE and len(v) == 8:
             num, den = struct.unpack("<II", v)
             c.rate = Fraction(num, den) if den else c.rate
+            c.external_clock = num == 0                        # 0 / 1: sampled on a clock, no time (§3.8)
         elif tag == LAYOUT and not analog and len(v) >= 2 and len(v) == 2 + v[1]:
             c.width, n = v[0], v[1]
             c.positions = list(v[2:2 + n])
@@ -478,6 +514,27 @@ def _config(payload: bytes, analog: bool) -> Config:
             c.skew_ns[role] = ns
         elif tag == FRONTEND_USED and analog and len(v) == 2:
             c.frontend[v[0]] = v[1]
+        elif tag == ANSWER_FORMAT_NAME:
+            c.format_name = c.format_name or v.decode("ascii", "replace")
+        elif not analog and tag == LOGIC_USED["timebase"] and len(v) == 8:
+            num, den = struct.unpack("<II", v)
+            c.timebase = Fraction(num, den) if den else None
+        elif not analog and tag == LOGIC_USED["threshold_used"] and len(v) == 9:
+            group, mv, hyst = struct.unpack("<BiI", v)
+            c.used.setdefault("threshold_used", {})[group] = (mv, hyst)
+        elif not analog and tag == LOGIC_USED["glitch_used"] and len(v) == 5:
+            group, ns = struct.unpack("<BI", v)
+            c.used.setdefault("glitch_used", {})[group] = ns
+        elif analog and tag in (ANALOG_USED["coupling_used"], ANALOG_USED["offset_used"], ANALOG_USED["bandwidth_used"]):
+            name = next(k for k, t in ANALOG_USED.items() if t == tag)
+            form = {"coupling_used": "<BB", "offset_used": "<Bi", "bandwidth_used": "<BI"}[name]
+            if len(v) == struct.calcsize(form):
+                role, value = struct.unpack(form, v)
+                c.used.setdefault(name, {})[role] = value
+        elif analog and tag == ANALOG_USED["resolution_used"] and len(v) == 1:
+            c.used["resolution_used"] = v[0]
+        elif analog and tag == ANALOG_USED["oversample_used"] and len(v) == 2:
+            c.used["oversample_used"] = struct.unpack("<H", v)[0]
         elif tag == REFERENCE and analog and len(v) == 6:
             source, mv, how = struct.unpack("<BIB", v)
             # how: nominal False, measured True; an unknown value is shown as it is, not as nominal (core §2.4)
@@ -508,14 +565,23 @@ class LogicCapture(Interface):
                   trigger: tuple[int, int, int] | None = None, pretrigger: int | None = None, query: bool = False,
                   frontends: dict[int, int] | None = None, trigger_opts: TriggerOpts | None = None,
                   data_format: int = 0, events: dict[int, int] | None = None, roles: list[int] | None = None,
-                  block_max: int | None = None) -> Config:
+                  block_max: int | None = None, carriage: dict[int, tuple[int, int]] | None = None,
+                  format_name: str | None = None, options: dict | None = None) -> Config:
         """-> the probe's actual values. A value the probe cannot honour is refused: host.Unsupported, .tag = the TLV as
         sent (§3.3). The TLVs go without the critical bit (§3.3). Read Config.samples / .segments: the probe rounds
         samples down.
 
         Format 1 (logic blocks, §1.3): `data_format` DATA_FORMAT["logic_blocks"], `events` role -> D for the channels
         carried as events (the others raw), `roles` the plan's roles (to name the raw channels), `block_max` the
-        longest block. Format 4 (test counter) needs nothing else. These go critical.
+        longest block (§3.3's table: without the critical bit). Format 2 (analog blocks, §1.4): `carriage` role ->
+        (kind, D), kind a bit set of capture_blocks.PACKED / MINMAX / SUM (the roles not named packed). Format 4 (test
+        counter) needs nothing else. Format 0xFF: `format_name`. The others go critical.
+
+        `options` (§3.8 / §3.9, critical; a probe without one refuses it): "threshold" group -> (mv, hysteresis_mv),
+        "glitch_filter" group -> ns, "clock" (role, edge, qualifier role or None, qualifier level), "coupling" role ->
+        kind, "offset" role -> mV, "bandwidth" role -> Hz, "resolution" bits, "oversample" ratio, "data_path" (path,
+        mux, kind), "overflow" 0 / 1 (plain: §3.3's table). The answer's values in use: Config.used, by the answer TLV's
+        name.
 
         §3.3's contract is checked before anything is sent (ValueError): `samples` is needed in one-shot and repeat
         and not taken in streaming, `segments` is repeat's only, `pretrigger` needs a trigger (type other than 0) - a
@@ -551,12 +617,19 @@ class LogicCapture(Interface):
             body += tlv(FRONTEND, bytes([role, fe]))
         if data_format:                                      # critical: a probe without it refuses (§3.3)
             body += m.tlv(FORMAT | CRITICAL, bytes([data_format]))
+        if (data_format == DATA_FORMAT["named"]) != (format_name is not None):
+            raise ValueError("capture configure: format 0xFF goes with its format_name, and only it (oep-if-capture §3.3)")
+        if format_name is not None:
+            body += m.tlv(OPTION_TLV["format_name"] | CRITICAL, format_name.encode("ascii"))
+        body += _options(options or {})
         if data_format == DATA_FORMAT["logic_blocks"] and roles is None:
             raise ValueError("capture configure: format 1 needs the plan's roles (to name the raw channels)")
         for role, d in sorted((events or {}).items()):
             body += m.tlv(CARRIAGE | CRITICAL, struct.pack("<BBI", role, LOGIC_CARRIAGE["events"], d))
+        for role, (kind, d) in sorted((carriage or {}).items()):
+            body += m.tlv(CARRIAGE | CRITICAL, struct.pack("<BBI", role, kind, d))
         if block_max is not None:
-            body += m.tlv(BLOCK_MAX | CRITICAL, struct.pack("<I", block_max))
+            body += m.tlv(BLOCK_MAX, struct.pack("<I", block_max))   # §3.3's table: every probe takes it
         if trigger_opts is not None:                         # critical: a probe without it refuses (§3.3)
             o = trigger_opts
             body += m.tlv(TRIGGER_OPTS | CRITICAL, struct.pack("<BBBI", o.arm, o.rearm, o.when, o.hysteresis))
@@ -567,6 +640,8 @@ class LogicCapture(Interface):
         if data_format == DATA_FORMAT["logic_blocks"]:
             c.event_d = dict(events or {})
             c.raw_roles = [r for r in sorted(roles) if r not in c.event_d]
+        if c.format == DATA_FORMAT["analog_blocks"]:
+            c.carriage = {r: kd for r, kd in (carriage or {}).items() if kd[0] != capture_blocks.PACKED}
         if mode == ONE_SHOT and not c.segments:
             c.segments = 1                                     # one-shot's answer has no actual_segments (§3.3)
         if not query:
@@ -843,7 +918,7 @@ class LogicCapture(Interface):
         """The segment's bytes (of its generation); every Host.on_capture callback gets them as a CaptureRecord (a run
         recorder, e.g. pytest-embedded-wireskein, without this package knowing it)."""
         c = self.config
-        if c.format == DATA_FORMAT["logic_blocks"]:
+        if c.format in (DATA_FORMAT["logic_blocks"], DATA_FORMAT["state_timed"]):
             data = self._read_blocks(segment)
         else:
             data = self.read(segment.position, c.segment_bytes(segment.samples), segment.generation or None)
@@ -863,8 +938,11 @@ class LogicCapture(Interface):
         return data[:self._blocks_length(data, segment.samples)]
 
     def _blocks_length(self, data: bytes, samples: int) -> int:
-        """The bytes the blocks of `samples` samples take at the start of `data` (from their headers, §1.3)."""
+        """The bytes the blocks of `samples` samples take at the start of `data` (from their headers, §1.3; format 3:
+        its entries, §3.8)."""
         c = self.config
+        if c.format == DATA_FORMAT["state_timed"]:
+            return capture_blocks.state_timed_length(data, samples, c.width)
         nb = (len(c.event_d) + 7) // 8
         at = 0
         for first in range(0, samples, c.block):
@@ -884,6 +962,15 @@ class LogicCapture(Interface):
         c = self.config
         return capture_blocks.read_logic_blocks(data, samples, c.raw_roles, c.event_d, c.block)
 
+    def state_timed(self, data: bytes, samples: int) -> list[tuple[int, int]]:
+        """A format 3 segment's bytes -> (ticks from start, state) per sample (§3.8; Config.timebase the tick rate)."""
+        return capture_blocks.read_state_timed(data, samples, self.config.width)
+
+    def analog_blocks(self, data: bytes, samples: int) -> list[capture_blocks.AnalogBlock]:
+        """A format 2 segment's bytes -> its blocks (each channel packed values or its intervals' summaries, §1.4)."""
+        c = self.config
+        return capture_blocks.read_analog_blocks(data, samples, c.order, c.carriage, c.block, c.bits)
+
     def columns(self, data: bytes, samples: int) -> dict:
         """A format 1 segment's bytes -> role -> its raw bits or its EventColumn over the whole segment, without blocks
         (capture_blocks.segment_columns; needs numpy)."""
@@ -1021,6 +1108,9 @@ class GroupStatus:
 GROUP_BIND = _GRP.tlv["bind"]
 COND = _GRP.enum["trigger_cond"]
 COND_SRC = _GRP.enum["cond_src"]
+SERIAL_PROTOCOL, SERIAL_EVENT = _GRP.enum["serial_protocol"], _GRP.enum["serial_event"]
+PIN_ROLE = _GRP.enum["pin_role"]                          # the group's own plan roles: trig_in, trig_out
+NO_ROLE = 0xFF
 
 
 @dataclass(frozen=True)
@@ -1064,6 +1154,43 @@ class Cond:
         """ns after the stage was entered."""
         return Cond(0, 0, COND["timer"], struct.pack("<Q", ns), COND_SRC["track"])
 
+    @staticmethod
+    def pulse(track: "LogicCapture | None", role: int, level: int, cond: int, min_ns: int = 0, max_ns: int = 0) -> "Cond":
+        """A run at `level`: cond 0 longer than min_ns (the instant it gets there), 1 at most max_ns, 2 within min_ns ..
+        max_ns (at its end). `track` None: the group's external input `role` (trig_in)."""
+        return Cond(track.fn if track else 0, role, COND["pulse"], struct.pack("<BBQQ", level, cond, min_ns, max_ns),
+                    COND_SRC["track"] if track else COND_SRC["external"])
+
+    @staticmethod
+    def analog_pulse(track: "AnalogCapture", role: int, value: int, side: int, cond: int, min_ns: int = 0,
+                     max_ns: int = 0, hysteresis: int = 0) -> "Cond":
+        """A run below (side 0) / above (side 1) `value`, timed as pulse()."""
+        return Cond(track.fn, role, COND["analog_pulse"], struct.pack("<IIBBQQ", value, hysteresis, side, cond, min_ns, max_ns))
+
+    @staticmethod
+    def pattern(track: "LogicCapture", levels: dict[int, int], when: int = 0) -> "Cond":
+        """The track's roles at these levels together (role -> 0 / 1; bit k of mask / value is role k)."""
+        n = max(levels) // 8 + 1
+        mask = sum(1 << r for r in levels).to_bytes(n, "little")
+        value = sum(v << r for r, v in levels.items()).to_bytes(n, "little")
+        return Cond(track.fn, 0, COND["pattern"], bytes([n]) + mask + value + bytes([when]))
+
+    @staticmethod
+    def uart(track: "LogicCapture", role: int, baud: int, match: bytes = b"", mask: bytes | None = None,
+             event: int = SERIAL_EVENT["match"], bits: int = 8, parity: int = 0, flags: int = 0) -> "Cond":
+        """serial, UART on RX `role`: the bytes `match` (under `mask`, default all bits), or an event (framing, parity,
+        break)."""
+        mask = mask if mask is not None else b"\xff" * len(match)
+        return Cond(track.fn, role, COND["serial"], struct.pack("<BBBBIBBBB", SERIAL_PROTOCOL["uart"], event, NO_ROLE,
+                                                                NO_ROLE, baud, bits, parity, flags, len(match)) + mask + match)
+
+    @staticmethod
+    def external(kind: str, role: int = PIN_ROLE["trig_in"], **args) -> "Cond":
+        """A condition on the group's external input (trig_in): level(level, when) or edge(edge)."""
+        packed = struct.pack("<BB", args.get("level", 1), args.get("when", 0)) if kind == "level" else \
+            struct.pack("<B", args.get("edge", 0))
+        return Cond(0, role, COND[kind], packed, COND_SRC["external"])
+
 
 @dataclass(frozen=True)
 class Stage:
@@ -1084,6 +1211,7 @@ class TriggerSource:
     holdoff_ns: int = 0
     arm: int = 1
     rearm: int = 0
+    trigger_out: tuple[int, int] | None = None              # (width_ns, polarity) on the group's trig_out role
 
     def tlvs(self) -> bytes:
         """The bind TLVs, every one critical (§4.4)."""
@@ -1096,6 +1224,8 @@ class TriggerSource:
                     for c in conds:
                         out += m.tlv(GROUP_BIND["cond"] | CRITICAL,
                                      struct.pack("<BBBBHBB", k, part, term, c.src, c.fn, c.role, c.kind) + c.args)
+        if self.trigger_out is not None:
+            out += m.tlv(GROUP_BIND["trigger_out"] | CRITICAL, struct.pack("<BIB", PIN_ROLE["trig_out"], *self.trigger_out))
         return out
 
 

oep_client/capture_blocks.py

@@ -1,5 +1,6 @@
 # SPDX-License-Identifier: MIT
-"""Reading a capture's data formats beyond 0 (oep-if-capture §1): format 1, the logic blocks (§1.3).
+"""Reading a capture's data formats beyond 0 (oep-if-capture §1): format 1, the logic blocks (§1.3), and format 2, the
+analog blocks (§1.4).
 
 A segment of format 1 is a run of blocks of L original samples (the last one r = samples mod L). Each block gives:
 
@@ -19,7 +20,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import NamedTuple
 
-from . import host as h
+from . import host as h, registry as reg
 
 try:
     import numpy as _np
@@ -292,3 +293,123 @@ def worst_bytes(R: int, event_d: list[int], block: int) -> int:
     """The most bytes one block of L samples takes (§1.3): 2 ceil(E/8) + 4 + L R / 8 + sum min(L/8, (L/D) 4)."""
     E = len(event_d)
     return 2 * ((E + 7) // 8) + 4 + block * R // 8 + sum(min(block // 8, block // d * EVENT_BYTES) for d in event_d)
+
+
+# ---- format 2, the analog blocks (§1.4) ----------------------------------------------------------------------------
+PACKED, MINMAX, SUM = (reg.FIXTURE_ANALOG.enum["analog_carriage"][k] for k in ("packed", "minmax", "sum"))
+
+
+@dataclass
+class AnalogChannel:
+    """One channel's part of a format 2 block (§1.4): `values` (packed, lossless), or per interval of D (the last one
+    partial: its points from the block's r) `mins` / `maxs` and / or `sums` (summaries)."""
+    kind: int
+    d: int
+    values: list[int] = field(default_factory=list)
+    mins: list[int] = field(default_factory=list)
+    maxs: list[int] = field(default_factory=list)
+    sums: list[int] = field(default_factory=list)
+
+    def points(self, r: int) -> list[int]:
+        """The original samples each interval covers (a sum over its points is their mean)."""
+        return [min(self.d, r - lo) for lo in range(0, r, self.d)]
+
+
+@dataclass
+class AnalogBlock:
+    """One block of a format 2 segment: samples `first` .. `first + samples - 1`, role -> its part."""
+    first: int
+    samples: int
+    channels: dict[int, AnalogChannel] = field(default_factory=dict)
+
+
+def _part_bits(r: int, kind: int, d: int, b: int) -> int:
+    if kind == PACKED:
+        return r * b
+    per = (2 * b if kind & MINMAX else 0) + (b + (d - 1).bit_length() if kind & SUM else 0)
+    return -(-r // d) * per
+
+
+def analog_block_bytes(r: int, order: list[int], carriage: dict[int, tuple[int, int]], b: int) -> int:
+    """The bytes of one format 2 block of r samples: every channel's part, each ending on a byte (§1.4)."""
+    return sum((_part_bits(r, *carriage.get(k, (PACKED, 1)), b) + 7) // 8 for k in order)
+
+
+def analog_segment_bytes(samples: int, order: list[int], carriage: dict[int, tuple[int, int]], block: int,
+                         b: int) -> int:
+    """A format 2 segment's bytes: whole blocks of L, the last of what is left (§1.4; a fixed size)."""
+    whole, rest = divmod(samples, block)
+    return (whole * analog_block_bytes(block, order, carriage, b)
+            + (analog_block_bytes(rest, order, carriage, b) if rest else 0))
+
+
+def read_analog_blocks(data: bytes, samples: int, order: list[int], carriage: dict[int, tuple[int, int]],
+                       block: int, b: int) -> list[AnalogBlock]:
+    """A format 2 segment's bytes (§1.4) -> its blocks. `order`: the layout's order, `carriage`: role -> (kind, d) as
+    configured (the others packed), `block`: the answer's L, `b`: the layout's b. Bytes left over, or too few, raise
+    ProtocolError."""
+    if len(data) != analog_segment_bytes(samples, order, carriage, block, b):
+        raise h.ProtocolError(f"format 2: {len(data)} bytes for {samples} samples "
+                              f"({analog_segment_bytes(samples, order, carriage, block, b)} expected)")
+    out, pos = [], 0
+    for first in range(0, samples, block):
+        r = min(block, samples - first)
+        blk = AnalogBlock(first, r)
+        for k in order:
+            kind, d = carriage.get(k, (PACKED, 1))
+            nbytes = (_part_bits(r, kind, d, b) + 7) // 8
+            acc, at = int.from_bytes(data[pos:pos + nbytes], "little"), 0
+            pos += nbytes
+
+            def take(bits: int) -> int:
+                nonlocal at
+                v = acc >> at & ((1 << bits) - 1)
+                at += bits
+                return v
+            c = AnalogChannel(kind, d)
+            if kind == PACKED:
+                c.values = [take(b) for _ in range(r)]
+            else:
+                for _ in range(-(-r // d)):
+                    if kind & MINMAX:
+                        c.mins.append(take(b))
+                        c.maxs.append(take(b))
+                    if kind & SUM:
+                        c.sums.append(take(b + (d - 1).bit_length()))
+            blk.channels[k] = c
+        out.append(blk)
+    return out
+
+
+# ---- format 3, the timed states (§3.8) -----------------------------------------------------------------------------
+ESCAPE = 0xFFFFFFFF                      # a delta that only moves time on: its state is no sample
+
+
+def read_state_timed(data: bytes, samples: int, w: int) -> list[tuple[int, int]]:
+    """A format 3 segment's bytes -> (ticks from start, state) for each of its `samples` samples: the first delta
+    counts from start, the others from the sample before, an escape (0xFFFFFFFF) moves time on without a sample.
+    Bytes left over, or too few, raise ProtocolError."""
+    size = 4 + (w + 7) // 8
+    out, pos, ticks = [], 0, 0
+    while len(out) < samples:
+        if pos + size > len(data):
+            raise h.ProtocolError(f"format 3: {len(out)} of {samples} samples in {len(data)} bytes")
+        delta = int.from_bytes(data[pos:pos + 4], "little")
+        ticks += delta
+        if delta != ESCAPE:
+            out.append((ticks, int.from_bytes(data[pos + 4:pos + size], "little") & ((1 << w) - 1)))
+        pos += size
+    if pos != len(data):
+        raise h.ProtocolError(f"format 3: {len(data) - pos} bytes past the segment's {samples} samples")
+    return out
+
+
+def state_timed_length(data: bytes, samples: int, w: int) -> int:
+    """The bytes `samples` samples of format 3 take at the start of `data` (escapes included)."""
+    size, pos, n = 4 + (w + 7) // 8, 0, 0
+    while n < samples:
+        if pos + size > len(data):
+            raise h.ProtocolError("format 3: the segment's bytes end inside its entries")
+        n += int.from_bytes(data[pos:pos + 4], "little") != ESCAPE
+        pos += size
+    return pos

oep_client/conformance.py

@@ -144,7 +144,7 @@ def checker_sources_sha256():
             for name in CHECKER_SOURCES}
 
 
-REVIEWED_CORE_SHA256 = '4c5dcdcc779c5ba0ee85060a33b2b629deddad3e8f8f1a22e18bdeea9d471bdc'   # oep-spec a09fa45 docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = 'd63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14'   # oep-spec 02c08c9 docs/oep-core.ja.md
 
 
 def require_reviewed_contract(registry, spec=None):
@@ -157,6 +157,23 @@ def require_reviewed_contract(registry, spec=None):
                 'checker migration required: core document differs from the reviewed checker contract')
 
 
+def required_core_ops(registry, declared, describe):
+    """fn 0's required ops (core §11): the eight core ops always; get with settings, state with save, network with a netif
+    (core §13, transports §7.3). declared: the ops fn 0 declares; describe: fn 0's describe TLVs by tag."""
+    core = {row['name']: row['code'] for row in registry['core']['op']}
+    required = {core[name] for name in ('confirm', 'list', 'describe', 'clock', 'open', 'end', 'keepalive', 'lock_state')}
+    if 'get' not in core:   # a registry without the settings (core §13): nothing more to require
+        return required
+    setting, netif = registry['describe_common'].get('setting'), registry['core']['tlv']['describe'].get('netif')
+    if declared & {core[name] for name in ('get', 'set', 'unset', 'save', 'state')} or setting in describe:
+        required.add(core['get'])
+    if core['save'] in declared:
+        required.add(core['state'])
+    if netif in describe:
+        required.add(core['network'])
+    return required
+
+
 def spec_identity(path):
     path = Path(path).resolve(strict=True)
     raw = (path / 'registry/oep-v1.toml').read_bytes()
@@ -376,7 +393,7 @@ class Checks:
         tag = self.reg['describe_common']['ops']
         require(tag in values, 'core describe missing current ops tag')
         declared = ops(values[tag])
-        require(set(self.core.values()) <= declared, 'mandatory core operation absent')
+        require(required_core_ops(self.reg, declared, values) <= declared, 'mandatory core operation absent')
         self.transport_declarations()
         channels = values.get(self.reg['core']['tlv']['describe']['channels'], b'\0\0')
         require(len(channels) == 2, 'channels must be u16')

oep_client/conformance_capture_serial.py

@@ -17,8 +17,8 @@ def refused_stale(reply):
     return reply[3:5]==b'\0\4' and refusal_carries('unavailable',reply[5:],b'\1\1\0\6')
 from .conformance_host_deadline import reviewed_identity as core_identity
 
-REVIEWED={'interfaces/oep-if-capture.ja.md':'430950c71e6bbd78b9e8233db075a99ab6587ad99b37aae30132d6e66eced9d9',
-          'interfaces/oep-if-common.ja.md':'4f1cfb88de976f5e934a0526edda3fbf302b51243b43c7faac0b3531d2f9975a'}
+REVIEWED={'interfaces/oep-if-capture.ja.md':'ffd89a6a1abf006aea788a6b47b270e6ac0e6d8190a716f4123c4f499bd3a61e',
+          'interfaces/oep-if-common.ja.md':'25fed0b1b8b7f246a8b71d02cea810249803b1c3c1e9c3df466c04f38687f70c'}
 
 def reviewed_identity(path):
     identity=core_identity(path)

oep_client/conformance_capture_timeline.py

@@ -1,6 +1,6 @@
 """Selected-SPEC cross-rate immediate group acquisition checks with an independent waveform oracle.
 
-Self-contained for capture a09fa45: no imports of probe encoders, Host decoders,
+Self-contained for capture: no imports of probe encoders, Host decoders,
 the bench endpoint or the other capture checkers. Layouts are decoded from the
 configure answers; the waveform and clock are the documented fixture's.
 """

oep_client/conformance_core_fixed_fields.py

@@ -3,7 +3,7 @@ import struct
 from .conformance import require
 from .conformance_host_core import HostCoreShapeChecks,CORE_OPS,fixed_vectors,result,field
 
-# Reviewed from core §1.1/4.3/6.4/7 (oep-spec a09fa45: confirm and list entries carry no flags), not inferred from a generated schema.
+# Reviewed from core §1.1/4.3/6.4/7 (confirm and list entries carry no flags), not inferred from a generated schema.
 # Each tuple lists all mandatory request fields and fixed response prefixes.
 CORE_SHAPES=(
  ('confirm',1,(('magic',4),('min_rev',1),('max_rev',1)),(('magic',4),('revision',1),('max_frame',2),('window',4),('max_inflight',1),('boot_id',4))),

oep_client/conformance_core_smoke.py

@@ -8,7 +8,7 @@ import struct
 from .conformance import ops, require, tlvs
 from . import conformance as _helpers
 
-REVIEWED_CORE_SHA256 = '4c5dcdcc779c5ba0ee85060a33b2b629deddad3e8f8f1a22e18bdeea9d471bdc'  # oep-spec a09fa45 docs/oep-core.ja.md
+REVIEWED_CORE_SHA256 = 'd63f99f1809146ad41f1643526c81417b366d7a9d85af3845daee6654a229a14'  # oep-spec 02c08c9 docs/oep-core.ja.md
 
 
 class CoreSmokeChecks:
@@ -85,7 +85,8 @@ class CoreSmokeChecks:
         identity = values.get(tags['unit_id'], b'').decode('ascii')
         require(identity.lower() == self.unit.lower() and 1 <= len(identity) <= 32 and
                 all(c in 'abcdefghijklmnopqrstuvwxyz0123456789-' for c in identity), 'unit_id')
-        require(set(self.core.values()) <= ops(values.get(self.reg['describe_common']['ops'], b'')), 'core ops')
+        declared = ops(values.get(self.reg['describe_common']['ops'], b''))
+        require(_helpers.required_core_ops(self.reg, declared, values) <= declared, 'core ops')
         maximum = values.get(tags['max_op_ms'], b'')
         require(len(maximum) == 4 and 1 <= int.from_bytes(maximum, 'little') <= 600000, 'max_op_ms')
         require(any(t == tags['transport'] and len(v) == 3 and v[0] == self.observed['confirm']['transport']