oep-client-python 0.0.34__py3-none-any.whl → 0.0.36__py3-none-any.whl

oep_client/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.0.34"
+__version__ = "0.0.36"

oep_client/capture.py

@@ -35,19 +35,26 @@ from __future__ import annotations
 import struct
 import time
 import zipfile
+from typing import NamedTuple
 from dataclasses import dataclass, field
 from fractions import Fraction
 
-from . import cobs, host as h, message as m, registry as reg
+from . import capture_blocks, cobs, host as h, message as m, registry as reg
 from .frames import FramingLost
-from .core import Interface, confirm
+from .core import Interface, confirm, describe
 
 _CAP = reg.FIXTURE_LOGIC
 _ANA = reg.FIXTURE_ANALOG
 _GRP = reg.FIXTURE_CAPTURE_GROUP
 # configure TLVs; bit 7 of a tag = critical (the probe must reject what it cannot do)
-MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER = (
-    _CAP.tlv["configure"][k] for k in ("mode", "rate", "samples", "segments", "trigger", "pretrigger"))
+MODE, RATE, SAMPLES, SEGMENTS, TRIGGER, PRETRIGGER, TRIGGER_OPTS, FORMAT, CARRIAGE, BLOCK_MAX = (
+    _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"]
+STREAM_BUFFER = _CAP.tlv["configure_answer"]["stream_buffer"]
+JUDGE_LATENCY = _CAP.tlv["configure_answer"]["judge_latency_ns"]
+DATA_FORMAT = _CAP.enum["data_format"]
+LOGIC_CARRIAGE = _CAP.enum["logic_carriage"]
 FRONTEND = _ANA.tlv["configure"]["frontend"]             # analog only
 ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, SCALE, SKEW, FRONTEND_USED, REFERENCE = (
     _ANA.tlv["configure_answer"][k] for k in (
@@ -60,7 +67,8 @@ REFERENCE_SOURCE = {v: k for k, v in _ANA.enum["reference_source"].items()}
 REFERENCE_MEASURED = {_ANA.enum["reference_how"]["nominal"]: False, _ANA.enum["reference_how"]["measured"]: True}
 CRITICAL = m.TAG_CRITICAL
 ONE_SHOT, REPEAT, STREAMING = (_CAP.enum["mode"][k] for k in ("one_shot", "repeat", "streaming"))
-IMMEDIATE, LEVEL, EDGE, CROSS_UP, CROSS_DOWN = range(5)
+IMMEDIATE, LEVEL, EDGE, LINKED = (_CAP.enum["trigger"][k] for k in ("immediate", "level", "edge", "linked"))
+CROSS_UP, CROSS_DOWN = _ANA.enum["trigger"]["cross_up"], _ANA.enum["trigger"]["cross_down"]
 STATE = _CAP.enum["state"]
 SEGMENT_SLIPPED = _CAP.enum["segment_flag"]["slipped"]
 STATUS_FLAGS = _CAP.enum["status_flag"]                    # dropped, slipped (reset at start)
@@ -123,6 +131,7 @@ class Status:
     flags: int                       # bit0 dropped, bit1 slipped - since start
     generation: int
     error: int | None = None         # state 6: why (ERRORS)
+    named: dict[str, bytes] = field(default_factory=dict)   # named extensions (core §2.2): a probe's own diagnostics
 
     def __iter__(self):
         return iter((self.state, self.serial_done, self.write_pos, self.flags))
@@ -157,6 +166,21 @@ class Config:
     frontend: dict[int, int] = field(default_factory=dict)     # analog: the frontend each channel took
     reference: tuple[str, int, bool | str] | None = None       # analog: (source, mV, measured; an unknown how as str)
     pretrigger: int = 0                                        # what this host asked
+    format: int = 0                                            # the data format in use (§1; absent: 0)
+    block: int = 0                                             # format 1 / 2: L
+    stream_buffer: int | None = None                           # streaming: the most bytes held unsent (§3.3; None: not said)
+    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)
+
+    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;
+        formats 1 / 2: pass their worst bandwidth, a lower bound). None when the probe does not say."""
+        if self.stream_buffer is None:
+            return None
+        rate = worst_bytes_per_s if worst_bytes_per_s is not None else float(self.rate) * (
+            self.width / 8 if self.width else len(self.order) * self.slot / 8)
+        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)."""
@@ -272,7 +296,7 @@ def take_pushes(link, fn: int) -> list[tuple[int, int, bytes, int | None, Segmen
 class Event:
     """A capture event (oep-if-capture §3.4, §4.2; core §10.2 role 0x03). `generation`: the start it was made in - a
     track's for a track's event, the group's for the group's stopped. kind "segment" has `segment`; "stopped" has
-    `reason` and `error`; "triggered" has `serial`, `trigger_index` and `trigger_ns`. An event of another kind (or a
+    `reason` and `error`; "triggered" has `serial`, `trigger_index`, `record`, `sample`, `trigger_ns` and `uncertainty_ns`. An event of another kind (or a
     group's other than stopped) keeps its fixed part in `raw` and generation None."""
     fn: int
     seq: int
@@ -284,6 +308,10 @@ class Event:
     serial: int | None = None
     trigger_index: int | None = None
     trigger_ns: int | None = None
+    record: int | None = None                # triggered: the trigger record's serial (None: no record, §3.10)
+    sample: int | None = None                # triggered: the original sample from the generation's start
+    uncertainty_ns: int | None = None        # triggered: trigger_ns's +-ns
+    trigger_fn: int | None = None            # a group's triggered: the track that judged it (0: force, timer)
     raw: bytes = b""
 
     @property
@@ -309,9 +337,14 @@ def unpack_event(frame: bytes, group: bool = False) -> Event:
         elif kind == EVENT_STOPPED:
             reason, error, generation = rd.take("BBI")
             e = Event(fn, seq, "stopped", generation, reason=reason, error=error)
+        elif kind == EVENT_TRIGGERED and group:                # §4.4: trigger_fn record trigger_ns uncertainty generation
+            trigger_fn, record, trigger_ns, uncertainty, generation = rd.take("HIQII")
+            e = Event(fn, seq, "triggered", generation, trigger_ns=trigger_ns, uncertainty_ns=uncertainty,
+                      record=None if record == NO_RECORD else record, trigger_fn=trigger_fn)
         elif kind == EVENT_TRIGGERED and not group:
-            serial, index, trigger_ns, generation = rd.take("IIQI")
-            e = Event(fn, seq, "triggered", generation, serial=serial, trigger_index=index, trigger_ns=trigger_ns)
+            serial, index, record, sample, trigger_ns, uncertainty, generation = rd.take("IIIQQII")
+            e = Event(fn, seq, "triggered", generation, serial=serial, trigger_index=index, trigger_ns=trigger_ns,
+                      record=None if record == NO_RECORD else record, sample=sample, uncertainty_ns=uncertainty)
         else:
             return Event(fn, seq, f"kind 0x{kind:02x}", None, raw=bytes(body))
     except m.ShortPayload as err:
@@ -320,6 +353,73 @@ def unpack_event(frame: bytes, group: bool = False) -> Event:
     return e
 
 
+NO_RECORD = 0xFFFFFFFF
+TRIGGER_RECORD_BYTES = 24                  # serial u32, sample u64, trigger_ns u64, uncertainty_ns u32 (§3.10)
+
+
+CAPTURE_DROPS = "io.github.open-embedded-probe.capture-drops"
+
+
+@dataclass(frozen=True)
+class CaptureDrops:
+    """The Arduino reference firmware's own diagnostics in a capture's status (named extension CAPTURE_DROPS, not an OEP
+    definition): where data a stream dropped went, since start - bytes no free stage took, bytes the transport would not
+    queue, DMA chunks rewritten before they were copied (a hole: the track stops in error), chunks the harvest queue had
+    no room for - then the way the data goes (1 the zero-copy stages, 0 the store), the stages held, and the memory a
+    capture draws on: internal RAM's and DMA-capable internal RAM's largest free blocks, PSRAM's total (0: none); then
+    the most the stream's buffer (the DMA ring, in PSRAM on a P4) held not yet sent since start (bytes; None from a
+    firmware before it)."""
+    no_stage_bytes: int
+    unqueued_bytes: int
+    dma_overruns: int
+    queue_overflows: int
+    zero_copy: bool
+    stages: int
+    internal_largest: int
+    dma_largest: int
+    psram_total: int
+    buffer_peak: int | None = None
+
+    FORMAT = "<IIIIBBIIII"
+    FORMAT_BEFORE_PEAK = "<IIIIBBIII"   # a firmware before buffer_peak (until 2026-10-20)
+
+    @classmethod
+    def unpack(cls, data: bytes) -> "CaptureDrops | None":
+        """-> its fields, or None for data of another length (a form this host does not know)."""
+        for form in (cls.FORMAT, cls.FORMAT_BEFORE_PEAK):
+            if len(data) == struct.calcsize(form):
+                f = struct.unpack(form, data)
+                return cls(*f[:4], bool(f[4]), *f[5:])
+        return None
+
+    @classmethod
+    def of(cls, status: "Status") -> "CaptureDrops | None":
+        data = status.named.get(CAPTURE_DROPS)
+        return None if data is None else cls.unpack(data)
+
+
+@dataclass(frozen=True)
+class TriggerOpts:
+    """configure's trigger_opts (§3.3): `arm` 1 looks once the pretrigger is there (0: at once, a short segment);
+    `rearm` 1 a trigger for every segment (streaming: a record for every event, §2.1, §3.10); `when` 1 a level
+    already true at arming counts; `hysteresis` (analog cross, in ADC values) back that far before the next crossing.
+    The defaults are every probe's; the others as describe's trigger opts says."""
+    arm: int = 1
+    rearm: int = 0
+    when: int = 0
+    hysteresis: int = 0
+
+
+@dataclass(frozen=True)
+class TriggerRecord:
+    """A trigger record (§3.10): serial (from 0 in the generation), the original sample from the generation's start,
+    trigger_ns and its uncertainty."""
+    serial: int
+    sample: int
+    trigger_ns: int
+    uncertainty_ns: int
+
+
 def take_events(link, fn: int) -> list[bytes]:
     """Remove this fn's event frames (role 0x03) from the link, oldest first."""
     mine, rest = [], []
@@ -337,7 +437,8 @@ def _config(payload: bytes, analog: bool) -> Config:
     c = Config()
     seen: set[int] = set()
     for tag, v in tlvs(payload):
-        if tag in (ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, REFERENCE):
+        if tag in (ACTUAL_RATE, LAYOUT, ACTUAL_SAMPLES, ACTUAL_SEGMENTS, REFERENCE, ANSWER_FORMAT, ANSWER_BLOCK, STREAM_BUFFER,
+                   JUDGE_LATENCY):
             if tag in seen:
                 continue
             seen.add(tag)
@@ -350,6 +451,14 @@ def _config(payload: bytes, analog: bool) -> Config:
         elif tag == LAYOUT and analog and len(v) >= 4 and len(v) == 4 + v[3]:
             c.slot, c.offset, c.bits, n = v[0], v[1], v[2], v[3]
             c.order = list(v[4:4 + n])
+        elif tag == ANSWER_FORMAT and len(v) == 1:
+            c.format = v[0]
+        elif tag == ANSWER_BLOCK and len(v) == 4:
+            c.block = struct.unpack("<I", v)[0]
+        elif tag == STREAM_BUFFER and len(v) == 4:
+            c.stream_buffer = struct.unpack("<I", v)[0]
+        elif tag == JUDGE_LATENCY and len(v) == 4:
+            c.judge_latency_ns = struct.unpack("<I", v)[0]
         elif tag == ACTUAL_SAMPLES and len(v) == 4:
             c.samples = struct.unpack("<I", v)[0]
         elif tag == ACTUAL_SEGMENTS and len(v) == 4:
@@ -376,8 +485,9 @@ class LogicCapture(Interface):
     NAME = "oep.fixture.logic"
     REVISION = 1
     ANALOG = False
-    CONFIGURE, START, STOP, FORCE, STATUS, READ, SEGMENTS, RELEASE, QUERY_OP = (
-        _CAP.op[k] for k in ("configure", "start", "stop", "force", "status", "read", "segments", "release", "query"))
+    CONFIGURE, START, STOP, FORCE, STATUS, READ, SEGMENTS, RELEASE, QUERY_OP, TRIGGERS = (
+        _CAP.op[k] for k in ("configure", "start", "stop", "force", "status", "read", "segments", "release", "query",
+                             "triggers"))
 
     generation: int | None = None         # the current capture's generation (start / status / the group's start)
 
@@ -389,11 +499,17 @@ class LogicCapture(Interface):
 
     def configure(self, *, rate: int, mode: int = ONE_SHOT, samples: int | None = None, segments: int | None = None,
                   trigger: tuple[int, int, int] | None = None, pretrigger: int | None = None, query: bool = False,
-                  frontends: dict[int, int] | None = None) -> Config:
+                  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:
         """-> 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.
+
         §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
         pretrigger of 0 without one is simply not sent."""
@@ -426,10 +542,24 @@ class LogicCapture(Interface):
             body += tlv(PRETRIGGER, struct.pack("<I", pretrigger))
         for role, fe in sorted((frontends or {}).items()):   # analog: the input range per channel (describe frontend)
             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["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))
+        if block_max is not None:
+            body += m.tlv(BLOCK_MAX | CRITICAL, struct.pack("<I", block_max))
+        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))
         # query is its own operation: the lock is decided per operation, before the payload is looked at
         op = self.QUERY_OP if query else self.CONFIGURE
         c = _config(self._call(op, body, locked=not query).payload, self.ANALOG)
         c.pretrigger = pretrigger or 0
+        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 mode == ONE_SHOT and not c.segments:
             c.segments = 1                                     # one-shot's answer has no actual_segments (§3.3)
         if not query:
@@ -468,13 +598,15 @@ class LogicCapture(Interface):
         A position that does not follow the previous push is a probe-side drop (a gap); a seq that skips is a lost frame.
         A push of another generation than this capture's (a leftover of the start before, oep-if-capture §3.4) is
         dropped; each push's segment_info goes to `segments`. The subscription ends with the lock, so the lock is kept alive every `keepalive_s` while collecting (a
-        stream longer than the lease otherwise stopped: 35 MB missing at the end of 10 s at 150 MHz with a 10 s lease)."""
+        stream longer than the lease otherwise stopped: 35 MB missing at the end of 10 s at 150 MHz with a 10 s lease) -
+        counted across calls with the same `into` (a host calling every 0.2 s lost its 30 s lease: each call began the
+        count again)."""
         if seconds is None and nbytes is None:
             raise ValueError("stream() needs seconds or nbytes")
         got = into or Received()
         deadline = time.monotonic() + seconds if seconds is not None else None
-        kept = time.monotonic()
-        expect_seq = getattr(got, "_seq", None)
+        kept = getattr(got, "_kept", None) or time.monotonic()   # on from the last call with the same `into`: a host
+        expect_seq = getattr(got, "_seq", None)                   # calling in short slices still keeps the lease
         event_seqs = getattr(got, "_events", set())   # events share the fn's seq (they stay on the link for the caller)
         while True:
             for e in link.events:
@@ -506,6 +638,7 @@ class LogicCapture(Interface):
             if keepalive_s and time.monotonic() - kept >= keepalive_s:
                 self.host.keepalive()
                 kept = time.monotonic()
+            got._kept = kept
             if nbytes is not None and len(got.data) >= nbytes:
                 return got
             if deadline is not None and time.monotonic() >= deadline:
@@ -559,9 +692,11 @@ class LogicCapture(Interface):
         generation a host that did not start the capture needs for read."""
         rd = m.Reader(self._call(self.STATUS, locked=False).payload)
         state, done, pos, flags, generation = rd.take("BIQBI")
-        error = rd.tail().get(STATUS_ERROR)                  # u8: another length is broken, not used (core §2.3)
+        tail = rd.tail()
+        error = tail.get(STATUS_ERROR)                       # u8: another length is broken, not used (core §2.3)
         self.generation = generation
-        return Status(state, done, pos, flags, generation, error[0] if error is not None and len(error) == 1 else None)
+        return Status(state, done, pos, flags, generation, error[0] if error is not None and len(error) == 1 else None,
+                      tail.named())
 
     def release(self, serial: int, generation: int | None = None) -> None:
         """Repeat: segments up to and including `serial` may be reused (of this generation; another one is rejected
@@ -584,6 +719,25 @@ class LogicCapture(Interface):
         rd.tail()
         return out, bool(more)
 
+    def triggers_page(self, from_serial: int = 0, generation: int | None = None) -> tuple[list[TriggerRecord], bool]:
+        """One answer's trigger records (§3.10) from `from_serial` on, paged as segments are. -> (records, more)."""
+        payload = struct.pack("<II", self._generation(generation), from_serial)
+        rd = m.Reader(self._call(self.TRIGGERS, payload, locked=False).payload)
+        more, count = rd.take("BB")
+        out = [TriggerRecord(*struct.unpack("<IQQI", rd.bytes(TRIGGER_RECORD_BYTES))) for _ in range(count)]
+        rd.tail()
+        return out, bool(more)
+
+    def triggers(self, from_serial: int = 0, generation: int | None = None) -> list[TriggerRecord]:
+        """Every trigger record kept from `from_serial` on; a jump in the serials is what was overwritten."""
+        out: list[TriggerRecord] = []
+        while True:
+            page, more = self.triggers_page(from_serial, generation)
+            out += page
+            if not more or not page:
+                return out
+            from_serial = (page[-1].serial + 1) & 0xFFFFFFFF
+
     def segments(self, from_serial: int = 0) -> list[Segment]:
         """Every segment record from `from_serial` on, following `more` (each next page from the last serial + 1,
         until more 0)."""
@@ -678,14 +832,53 @@ 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
-        n = c.segment_bytes(segment.samples)
-        data = self.read(segment.position, n, segment.generation or None)
+        if c.format == DATA_FORMAT["logic_blocks"]:
+            data = self._read_blocks(segment)
+        else:
+            data = self.read(segment.position, c.segment_bytes(segment.samples), segment.generation or None)
         if self.host.on_capture:
             record = CaptureRecord(self.fn, self.name, c, segment, data, self.armed_s, time.monotonic())
             for callback in list(self.host.on_capture):
                 callback(record)
         return data
 
+    def _read_blocks(self, segment: Segment) -> bytes:
+        """A format 1 segment's bytes: its length is not in its record (§1.3), so it ends where the next segment
+        begins, or at write_pos for the last; read at once, then cut by its blocks' headers."""
+        after = [s.position for s in self.segments((segment.serial + 1) & 0xFFFFFFFF)
+                 if s.generation == segment.generation and s.position > segment.position]
+        end = after[0] if after else self.status().write_pos
+        data = self.read(segment.position, end - segment.position, segment.generation or None)
+        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)."""
+        c = self.config
+        nb = (len(c.event_d) + 7) // 8
+        at = 0
+        for first in range(0, samples, c.block):
+            r = min(c.block, samples - first)
+            head = data[at:at + 2 * nb + 4]
+            if len(head) < 2 * nb + 4:
+                raise h.ProtocolError(f"format 1: the segment's bytes end inside block {first // c.block}")
+            fallbacks = bin(int.from_bytes(head[:nb], "little")).count("1")
+            n = int.from_bytes(head[2 * nb:], "little")
+            at += len(head) + (r * (len(c.raw_roles) + fallbacks) + 7) // 8 + capture_blocks.EVENT_BYTES * n
+        if at > len(data):
+            raise h.ProtocolError("format 1: the segment's bytes end inside its last block")
+        return at
+
+    def blocks(self, data: bytes, samples: int) -> list[capture_blocks.LogicBlock]:
+        """A format 1 segment's bytes -> its blocks (raw channels as bits, events channels as ticks, §1.3)."""
+        c = self.config
+        return capture_blocks.read_logic_blocks(data, samples, c.raw_roles, c.event_d, c.block)
+
+    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)."""
+        c = self.config
+        return capture_blocks.segment_columns(data, samples, c.raw_roles, c.event_d, c.block)
+
     # ---- the §3.0 layout ---------------------------------------------------------------------------------
     def channel(self, data: bytes, k: int, samples: int | None = None) -> list[int]:
         """Channel k's values, one per sample (§1.1 rules 1-3: bit i*w + pos[k] of the stream, bit j being bit j mod 8
@@ -811,6 +1004,119 @@ class GroupStatus:
     state: int
     start_ns: int | None             # None before the group's first start
     generation: int = 0              # the group's (§4.1; 0 before its first start)
+    trigger: tuple[int, int, int] | None = None   # §4.4, once the event happened: (fn judging, 0 force / timer; ns; +-ns)
+
+
+GROUP_BIND = _GRP.tlv["bind"]
+COND = _GRP.enum["trigger_cond"]
+COND_SRC = _GRP.enum["cond_src"]
+
+
+@dataclass(frozen=True)
+class Cond:
+    """A condition of the trigger source (§4.4): built with level() / edge() / cross_up() / cross_down() / above() /
+    below() / timer(). `fn` the bound track (0 for timer), `role` its plan role, `kind` enum trigger_cond, `args` the
+    type's arguments packed."""
+    fn: int
+    role: int
+    kind: int
+    args: bytes
+    src: int = COND_SRC["track"]
+
+    @staticmethod
+    def level(track: "LogicCapture", role: int, level: int, when: int = 0) -> "Cond":
+        return Cond(track.fn, role, COND["level"], struct.pack("<BB", level, when))
+
+    @staticmethod
+    def edge(track: "LogicCapture", role: int, edge: int = 0) -> "Cond":
+        """edge 0 rising, 1 falling, 2 both."""
+        return Cond(track.fn, role, COND["edge"], struct.pack("<B", edge))
+
+    @staticmethod
+    def cross_up(track: "LogicCapture", role: int, value: int, hysteresis: int = 0) -> "Cond":
+        return Cond(track.fn, role, COND["cross_up"], struct.pack("<II", value, hysteresis))
+
+    @staticmethod
+    def cross_down(track: "LogicCapture", role: int, value: int, hysteresis: int = 0) -> "Cond":
+        return Cond(track.fn, role, COND["cross_down"], struct.pack("<II", value, hysteresis))
+
+    @staticmethod
+    def above(track: "LogicCapture", role: int, value: int, hysteresis: int = 0, when: int = 0) -> "Cond":
+        return Cond(track.fn, role, COND["above"], struct.pack("<IIB", value, hysteresis, when))
+
+    @staticmethod
+    def below(track: "LogicCapture", role: int, value: int, hysteresis: int = 0, when: int = 0) -> "Cond":
+        return Cond(track.fn, role, COND["below"], struct.pack("<IIB", value, hysteresis, when))
+
+    @staticmethod
+    def timer(ns: int) -> "Cond":
+        """ns after the stage was entered."""
+        return Cond(0, 0, COND["timer"], struct.pack("<Q", ns), COND_SRC["track"])
+
+
+@dataclass(frozen=True)
+class Stage:
+    """A stage (§4.4): its terms are OR'd, a term's conditions AND'd; `count` times the OR becomes true; `within_ns`
+    from entering it (0 none); `on_timeout` 0 back to stage 0 when it passes, 1 the "should come" stage (its OR in
+    time goes back to stage 0, the time passing makes it hold). `aborts`: terms that send it back to stage 0."""
+    terms: list[list[Cond]]
+    count: int = 1
+    within_ns: int = 0
+    on_timeout: int = 0
+    aborts: list[list[Cond]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class TriggerSource:
+    """The group's trigger source (§4.4): stages in order, the last one holding is the event."""
+    stages: list[Stage]
+    holdoff_ns: int = 0
+    arm: int = 1
+    rearm: int = 0
+
+    def tlvs(self) -> bytes:
+        """The bind TLVs, every one critical (§4.4)."""
+        out = m.tlv(GROUP_BIND["trigger_source"] | CRITICAL,
+                    struct.pack("<BQBB", len(self.stages), self.holdoff_ns, self.arm, self.rearm))
+        for k, st in enumerate(self.stages):
+            out += m.tlv(GROUP_BIND["stage"] | CRITICAL, struct.pack("<BIQB", k, st.count, st.within_ns, st.on_timeout))
+            for part, terms in ((0, st.terms), (1, st.aborts)):
+                for term, conds in enumerate(terms):
+                    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)
+        return out
+
+
+class TriggerCaps(NamedTuple):
+    """capture-group describe's trigger_caps (§4.4, tag 0x41): what its trigger source takes - a declaration (core §7.3),
+    bind's answer is the probe's word. `types`: the condition types (enum trigger_cond, bit k = type k); `protocols`:
+    serial's (bit k = protocol k); trigger_out_latency_ns None: no trigger_out."""
+    max_stages: int
+    max_terms: int
+    max_conds: int
+    cross_track: bool
+    types: int
+    protocols: int
+    trigger_out_latency_ns: int | None
+
+    FORMAT = "<BBBBIBI"
+
+    @classmethod
+    def unpack(cls, v: bytes) -> "TriggerCaps | None":
+        """-> its fields, or None for a value of another length (a form this host does not know)."""
+        if len(v) != struct.calcsize(cls.FORMAT):
+            return None
+        st, te, co, ct, types, prot, lat = struct.unpack(cls.FORMAT, v)
+        return cls(st, te, co, bool(ct), types, prot, None if lat == 0xFFFFFFFF else lat)
+
+    def takes(self, kind: int) -> bool:
+        """Whether the condition type `kind` (COND[...]) is declared."""
+        return 0 <= kind < 32 and bool(self.types >> kind & 1)
+
+    def kinds(self) -> list[str]:
+        """The declared condition types by name (COND), in number order."""
+        return [name for name, k in sorted(COND.items(), key=lambda kv: kv[1]) if self.takes(k)]
 
 
 class CaptureGroup(Interface):
@@ -820,19 +1126,36 @@ class CaptureGroup(Interface):
     uncertainty place it)."""
     NAME = "oep.fixture.capture-group"
     REVISION = 1
-    BIND, START, STOP, STATUS = (_GRP.op[k] for k in ("bind", "start", "stop", "status"))
+    BIND, START, STOP, STATUS, FORCE = (_GRP.op[k] for k in ("bind", "start", "stop", "status", "force"))
     EVENT_STOPPED = _GRP.event["stopped"]
     NO_TIME = 0xFFFFFFFFFFFFFFFF
 
-    def bind(self, tracks: list[LogicCapture]) -> None:
-        """Bind these (configured, immediate-trigger) tracks; [] unbinds. A track with a trigger of its own is refused
-        here before sending (ValueError, §4.1); the probe refuses a track not in state 1/4/6 or modes apart
-        (unavailable cause 6, `.fn`), one in another group (cause 4) and more than it takes together (cause 2)."""
+    def bind(self, tracks: list[LogicCapture], source: TriggerSource | None = None) -> None:
+        """Bind these configured tracks; [] unbinds. Without `source` they start at once (immediate triggers): a track
+        with a trigger of its own is refused here before sending (ValueError, §4.1). With `source` (§4.4, describe
+        features bit 0) every track has the linked trigger (with its own pretrigger) and the group's event starts them.
+        The probe refuses a track not in state 1/4/6 or modes apart (unavailable cause 6, `.fn`), one in another group
+        (cause 4) and more than it takes together (cause 2)."""
         for t in tracks:
-            if t.config is not None and t.config.pretrigger:
+            if source is None and t.config is not None and t.config.pretrigger:
                 raise ValueError(f"capture-group bind: fn {t.fn} has a trigger of its own - a group starts its tracks "
                                  "at once (oep-if-capture §4.1)")
-        self._call(self.BIND, struct.pack(f"<B{len(tracks)}H", len(tracks), *(t.fn for t in tracks)))
+        self._call(self.BIND, struct.pack(f"<B{len(tracks)}H", len(tracks), *(t.fn for t in tracks))
+                   + (source.tlvs() if source is not None else b""))
+
+    def force(self) -> None:
+        """§4.4: waiting for the event, it happens now (nothing otherwise)."""
+        self._call(self.FORCE)
+
+    TRIGGER_CAPS = _GRP.tlv["describe"]["trigger_caps"]
+
+    def trigger_caps(self) -> TriggerCaps | None:
+        """describe's trigger_caps (§4.4): what the group's trigger source takes; None when the probe declares none (no
+        trigger source, or a form this host does not know). A declaration: bind still has the last word (§4.3)."""
+        for tag, v in describe(self.host, self.fn):
+            if tag == self.TRIGGER_CAPS:
+                return TriggerCaps.unpack(v)
+        return None
 
     generation: int | None = None     # the group's current generation (start / status, §4.1)
     stale_events: int = 0             # the group's events of an earlier generation that events() dropped
@@ -869,9 +1192,11 @@ class CaptureGroup(Interface):
     def status(self) -> GroupStatus:
         rd = m.Reader(self._call(self.STATUS, locked=False).payload)
         state, start, generation = rd.take("BQI")
-        rd.tail()
+        tail = rd.tail()
         self.generation = generation
-        return GroupStatus(state, None if start == self.NO_TIME else start, generation)
+        trig = tail.get(_GRP.tlv["status_answer"]["trigger"])
+        trigger = struct.unpack("<HQI", trig) if trig is not None and len(trig) == 14 else None
+        return GroupStatus(state, None if start == self.NO_TIME else start, generation, trigger)
 
     def events(self, link) -> list[Event]:
         """The group's own events waiting on the link (taken off it; stopped, §4.2), the current group generation's