oep-client-python 0.0.1__py3-none-any.whl

oep_client/v1/esp32_targets.py

@@ -0,0 +1,137 @@
+"""The ESP32 I2C / SPI slave tools of oep-probe-arduino, custom interfaces revision 1:
+io.github.ch32-riscv-ug.esp32.i2c-target and io.github.ch32-riscv-ug.esp32.spi-target (OepP4I2cTarget.h /
+OepP4SpiTarget.h). A DUT's I2C / SPI controller talks to them; the host arms what they answer and reads what they got.
+Variable byte lists carry a count(u16) in front (oep-core §2.3)."""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from . import host as h, message as m
+from .core import Interface
+
+NS = "io.github.ch32-riscv-ug.esp32"
+
+
+@dataclass
+class I2cStatus:
+    flags: int          # bit0 started, bits 1-2 mode, bit4 armed, bits 5-7 frames queued
+    rx_frames: int
+    tx_slots: int
+    errors: int
+
+
+@dataclass
+class I2cRegisters:
+    sr: int
+    int_raw: int
+    fifo_st: int
+    ctr: int
+    slave_addr: int
+    filter_cfg: int
+    scl_stretch_conf: int
+
+
+class I2cTarget(Interface):
+    """The I2C target (E147-E150 contract): fixed rx (arm_rx with the exact length), framed rx (a 1-byte length header
+    transaction, then the payload), preloaded tx (slots the controller reads)."""
+    NAME = f"{NS}.i2c-target"
+    REVISION = 1
+    CONFIGURE, ARM_RX, READ_RX, PRELOAD_TX, STATUS, RESET, READ_HW, SET_STRETCH = 1, 2, 3, 4, 5, 6, 0x10, 0x11
+    MODE_FIXED_RX, MODE_FRAMED_RX, MODE_PRELOADED_TX = 1, 2, 3
+    ROLE_SDA, ROLE_SCL = 1, 2
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        super().__init__(hst, name, fn=fn)
+
+    def assignments(self, sda: int, scl: int) -> list[tuple[int, int, int]]:
+        return [(self.fn, self.ROLE_SDA, sda), (self.fn, self.ROLE_SCL, scl)]
+
+    def configure(self, address: int, mode: int) -> None:
+        self._call(self.CONFIGURE, struct.pack("<BB", address, mode))
+
+    def arm_rx(self, length: int) -> None:
+        self._call(self.ARM_RX, struct.pack("<H", length))
+
+    def read_rx(self) -> tuple[int, bytes]:
+        """-> (frames still queued after this one, the oldest frame or b"")."""
+        rd = m.Reader(self._call(self.READ_RX).payload)
+        pending, count = rd.take("BH")
+        data = rd.bytes(count)
+        rd.tail()
+        return pending, data
+
+    def preload_tx(self, data: bytes) -> int:
+        """-> the slots preloaded so far."""
+        rd = m.Reader(self._call(self.PRELOAD_TX, struct.pack("<H", len(data)) + data).payload)
+        slots = rd.u8()
+        rd.tail()
+        return slots
+
+    def status(self) -> I2cStatus:
+        rd = m.Reader(self._call(self.STATUS, locked=False).payload)
+        s = I2cStatus(*rd.take("BIBH"))
+        rd.tail()
+        return s
+
+    def reset(self) -> None:
+        self._call(self.RESET)
+
+    def set_stretch(self, stretch_us: int) -> None:
+        """Hold every hardware SCL stretch for stretch_us (0 = off); takes effect at the next configure()."""
+        self._call(self.SET_STRETCH, struct.pack("<I", stretch_us))
+
+    def read_hw(self) -> I2cRegisters:
+        """Debug view of the P4 I2C0 block (zeros on other chips)."""
+        rd = m.Reader(self._call(self.READ_HW, locked=False).payload)
+        r = I2cRegisters(*rd.take("7I"))
+        rd.tail()
+        return r
+
+
+@dataclass
+class SpiStatus:
+    flags: int          # bit0 started, bit1 armed, bits 2-3 mode, bit4 LSB first, bits 5-7 queued
+    transactions: int
+    errors: int
+
+
+class SpiTarget(Interface):
+    """The SPI target (SPI2_HOST, no DMA, <= 64 bytes): one CS-framed transaction at a time - arm() with the MISO
+    bytes, then read_rx() after the controller raised CS."""
+    NAME = f"{NS}.spi-target"
+    REVISION = 1
+    CONFIGURE, ARM, READ_RX, STATUS, RESET = 1, 2, 3, 4, 5
+    ROLE_SCK, ROLE_MOSI, ROLE_MISO, ROLE_CS = 1, 2, 3, 4
+    MSB_FIRST, LSB_FIRST = 0, 1
+
+    def __init__(self, hst: h.Host, fn: int | None = None, name: str | None = None):
+        super().__init__(hst, name, fn=fn)
+
+    def assignments(self, sck: int, mosi: int, miso: int, cs: int) -> list[tuple[int, int, int]]:
+        return [(self.fn, self.ROLE_SCK, sck), (self.fn, self.ROLE_MOSI, mosi), (self.fn, self.ROLE_MISO, miso),
+                (self.fn, self.ROLE_CS, cs)]
+
+    def configure(self, mode: int = 0, bit_order: int = 0) -> None:
+        self._call(self.CONFIGURE, struct.pack("<BB", mode, bit_order))
+
+    def arm(self, length: int, tx: bytes = b"") -> None:
+        self._call(self.ARM, struct.pack("<HH", length, len(tx)) + tx)
+
+    def read_rx(self) -> tuple[int, int, bytes]:
+        """-> (transactions still queued, bits clocked, the MOSI bytes) of the oldest finished transaction."""
+        rd = m.Reader(self._call(self.READ_RX).payload)
+        pending, bits, count = rd.take("BIH")
+        data = rd.bytes(count)
+        rd.tail()
+        return pending, bits, data
+
+    def status(self) -> SpiStatus:
+        rd = m.Reader(self._call(self.STATUS, locked=False).payload)
+        s = SpiStatus(*rd.take("BIH"))
+        rd.tail()
+        return s
+
+    def reset(self) -> None:
+        self._call(self.RESET)

oep_client/v1/fake.py

@@ -0,0 +1,233 @@
+"""In-process fake probes that declare capabilities in the draft wire forms (no hardware).
+
+Each profile is a list of offered interfaces with their describe TLVs. The fake answers the core
+operations - confirm, list, describe - by encoding real payloads and paging them to its max_frame,
+so what `dump` shows is what a host would decode from a probe of that shape.
+
+The profiles are EXAMPLES of declarations, not a decision about which capabilities are standard.
+Wire forms: oep-core §7 (confirm with a revision range, list first / total u16 with oep.core as the first
+entry, describe first u16).
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from . import catalog, message as m, names, registry as reg
+from .catalog import (CHANNEL_GROUP, FEATURES, IMPLEMENTATION, MAX_CLOCK_HZ, MAX_LENGTH,
+                   MIN_CLOCK_HZ, ListEntry)
+
+CORE_FN = 0
+OP_CONFIRM, OP_LIST, OP_DESCRIBE = 0x01, 0x02, 0x03
+RESULT_HEADER = 5            # role(1) correlation(2) resolution(1) detail(1) in front of every payload
+REVISION = 1                 # the protocol revision confirm reports
+WINDOW, MAX_INFLIGHT = 4096, 4
+
+
+@dataclass(frozen=True)
+class Offered:
+    fn: int
+    instance: int
+    name: str
+    tlvs: tuple[bytes, ...] = ()
+    revision: int = 1
+    flags: int = 0
+
+
+class FakeProbe:
+    def __init__(self, label: str, max_frame: int, offered: list[Offered]):
+        self.label = label
+        self.max_frame = max_frame
+        self.offered = sorted(offered, key=lambda o: o.fn)
+        self.requests = 0
+        for o in self.offered:
+            names.validate(o.name)
+
+    # The one entry point a transport would call: (fn, op, payload) -> result payload.
+    def call(self, fn: int, op: int, payload: bytes = b"") -> bytes:
+        self.requests += 1
+        if fn != CORE_FN:
+            raise ValueError(f"fake: fn {fn} has no operations here")
+        if op == OP_CONFIRM:
+            if len(payload) < 6 or payload[:4] != m.CONFIRM_REQUEST:
+                raise ValueError("fake: confirm needs \"OEP?\" min_rev max_rev")
+            if not payload[4] <= REVISION <= payload[5]:
+                raise LookupError(f"fake: no revision in {payload[4]}..{payload[5]}")
+            return struct.pack("<4sBBHIB", m.CONFIRM_RESULT, REVISION, 0, self.max_frame, WINDOW, MAX_INFLIGHT)
+        if op == OP_LIST:
+            return self._list(*catalog.unpack_list_request(payload)[:3])
+        if op == OP_DESCRIBE:
+            if len(payload) < 4:
+                raise ValueError("fake: describe needs fn(u16) first(u16)")
+            target, first = struct.unpack_from("<HH", payload)
+            return self._describe(target, first)
+        raise ValueError(f"fake: core op 0x{op:02x} unknown")
+
+    def _list(self, prefix: str, exact: bool, first: int) -> bytes:
+        hits = [o for o in self.offered if names.matches(o.name, prefix, exact)]
+        budget = self.max_frame - RESULT_HEADER - 3
+        page, used = [], 0
+        for o in hits[first:]:
+            size = len(catalog.pack_entry(self._entry(o)))
+            if page and used + size > budget:
+                break
+            page.append(self._entry(o))
+            used += size
+        return catalog.pack_list_result(len(hits), page)
+
+    def _describe(self, fn: int, first: int) -> bytes:
+        o = next((x for x in self.offered if x.fn == fn), None)
+        if o is None:
+            raise ValueError(f"fake: fn {fn} not offered")
+        budget = self.max_frame - RESULT_HEADER - 1
+        out, sent = b"", 0
+        for t in o.tlvs[first:]:
+            if out and len(out) + len(t) > budget:
+                break
+            out += t
+            sent += 1
+        more = 1 if first + sent < len(o.tlvs) else 0
+        return bytes([more]) + out
+
+    @staticmethod
+    def _entry(o: Offered) -> ListEntry:
+        return ListEntry(o.fn, o.instance, o.revision, o.flags, o.name)
+
+
+# ---- example profiles ----------------------------------------------------
+# Names follow oep-spec docs/capability-name-hierarchy.ja.md (provisional, 2026-09-24): probe-wide
+# declarations in oep.core's describe, oep.wire.<link> to scan and attach, oep.target.riscv-dm and
+# oep.target.console on the connection, fixtures gpio / uart / capture, the ESP-IDF I2C and SPI
+# targets under the project's own name. Probe-wide tags (oep.core, interface-specific 0x40..):
+_CORE_TAGS = reg.CORE.tlv["describe"]
+CORE_FIRMWARE, CORE_MODEL, CORE_UNIT_ID, CORE_CHANNELS = (_CORE_TAGS[k] for k in ("firmware", "model", "unit_id", "channels"))
+CORE_RESERVED, CORE_PROFILE, CORE_LABEL = _CORE_TAGS["reserved"], _CORE_TAGS["profile"], _CORE_TAGS["label"]
+CORE_RESETS_ON_OPEN, CORE_TRANSPORT, CORE_OEP_PID = _CORE_TAGS["resets_on_open"], _CORE_TAGS["transport"], _CORE_TAGS["oep_pid"]
+TRANSPORT = reg.CORE.enum["transport_kind"]
+SERIAL_KINDS = {TRANSPORT["uart_bridge"], TRANSPORT["usb_cdc"], TRANSPORT["usb_serial_jtag"]}
+NS = "io.github.ch32-riscv-ug"
+MECHANISMS = reg.TARGET_CONSOLE.tlv["describe"]["mechanisms"]
+MAX_CONNECTIONS = reg.WIRE_RVSWD.tlv["describe"]["max_connections"]
+_CFG = reg.PROBE_CONFIG.tlv["describe"]
+
+
+def _transports(kinds: list[tuple[int, int]]) -> tuple[bytes, ...]:
+    """(kind, USB interface or 0xFF) per transport, index = position (core §7.5)."""
+    return tuple(catalog.tlv(CORE_TRANSPORT, bytes([i, k, itf])) for i, (k, itf) in enumerate(kinds))
+
+
+def _config(fn: int, instance: int, slots_max: int, modes: int = 0b111, storage: int = 4096) -> Offered:
+    """oep.probe.config's static declarations; slot_state / bind_state are added live by the endpoint."""
+    return Offered(fn, instance, "oep.probe.config", (
+        catalog.tlv(_CFG["storage"], struct.pack("<IBII", storage, 0, 0, 20)),
+        catalog.tlv(_CFG["items"], bytes(reg.PROBE_CONFIG.tlv["item"].values())),
+        catalog.u8(_CFG["slots_max"], slots_max), catalog.u8(_CFG["bind_modes"], modes)))
+
+
+def _roles(assign: dict[int, list[int]]) -> tuple[bytes, ...]:
+    return tuple(catalog.role_channels(r, ch) for r, ch in assign.items())
+
+
+def _label(channel: int, name: str) -> bytes:
+    return catalog.tlv(CORE_LABEL, struct.pack("<H", channel) + name.encode("ascii"))
+
+
+def _core(firmware: str, model: str, unit_id: bytes, channels: int, reserved: list[int], profile: str,
+          labels: dict[int, str], extra: tuple[bytes, ...] = ()) -> Offered:
+    base, bits = catalog.channels_to_bitmap(reserved)
+    return Offered(0, 0, "oep.core", (
+        catalog.text(CORE_FIRMWARE, firmware), catalog.text(CORE_MODEL, model), catalog.tlv(CORE_UNIT_ID, unit_id),
+        catalog.u16(CORE_CHANNELS, channels), catalog.tlv(CORE_RESERVED, struct.pack("<H", base) + bits),
+        catalog.text(CORE_PROFILE, profile)) + tuple(_label(c, n) for c, n in labels.items()) + extra)
+
+
+def p4_x035() -> FakeProbe:
+    """ESP32-P4 development probe on the CH32X035F8U6 jig (as wired on 2026-09-24), in the recommended USB shape
+    (probe guide §3.8): USB-Serial/JTAG (serial port 0), and on the HS port vendor bulk, HID and a CDC (serial port 3)
+    under the OEP VID:PID."""
+    reserved = [2, 24, 25, 54]                      # RVSWD SWDIO/SWCLK, USB-Serial/JTAG
+    pins = [p for p in range(55) if p not in reserved]
+    return FakeProbe("p4-x035", 1024, [
+        _core("3.0.0", "esp32-p4-devkit", bytes.fromhex("30eda0e31108"), 55, reserved, f"{NS}.p4-x035",
+              {2: "SWDIO", 54: "SWCLK", 51: "LED"},
+              _transports([(TRANSPORT["usb_serial_jtag"], 0xFF), (TRANSPORT["vendor_bulk"], 0),
+                           (TRANSPORT["hid"], 1), (TRANSPORT["usb_cdc"], 2)]) + (catalog.u8(CORE_OEP_PID, 1),)),
+        Offered(1, 1, "oep.wire.rvswd", (
+            catalog.channel_group(1, [(1, 2), (2, 54)]), catalog.u32(MAX_CLOCK_HZ, 5_000_000), catalog.u8(IMPLEMENTATION, 1),
+            catalog.u8(MAX_CONNECTIONS, 1))),
+        Offered(2, 1, "oep.target.riscv-dm", (catalog.u32(FEATURES, 0b1111), catalog.u8(IMPLEMENTATION, 1),
+                                              catalog.u16(MAX_LENGTH, 1000))),
+        Offered(3, 1, "oep.target.console", (catalog.tlv(MECHANISMS, bytes([0, 1, 2])),)),
+        Offered(4, 2, "oep.fixture.gpio", _roles({1: pins})),
+        Offered(5, 3, "oep.fixture.uart", _roles({1: pins, 2: pins}) + (
+            catalog.u32(MAX_CLOCK_HZ, 3_000_000), catalog.u8(IMPLEMENTATION, 2))),
+        Offered(6, 4, "oep.fixture.uart", _roles({1: pins, 2: pins}) + (
+            catalog.u32(MAX_CLOCK_HZ, 3_000_000), catalog.u8(IMPLEMENTATION, 2))),
+        Offered(7, 5, "oep.fixture.capture", _roles({k: pins for k in range(8)}) + (
+            catalog.u32(MAX_CLOCK_HZ, 20_000_000), catalog.u32(MIN_CLOCK_HZ, 1_000),
+            catalog.u16(MAX_LENGTH, 65000), catalog.u8(IMPLEMENTATION, 3))),
+        Offered(8, 6, f"{NS}.esp32.i2c-target", _roles({1: pins, 2: pins}) + (
+            catalog.u16(MAX_LENGTH, 128), catalog.u32(MAX_CLOCK_HZ, 1_000_000),
+            catalog.u32(FEATURES, 0b11), catalog.u8(IMPLEMENTATION, 2))),
+        Offered(9, 7, f"{NS}.esp32.spi-target", _roles({1: pins, 2: pins, 3: pins, 4: pins}) + (
+            catalog.u16(MAX_LENGTH, 64), catalog.u32(MAX_CLOCK_HZ, 3_000_000), catalog.u8(IMPLEMENTATION, 2))),
+        _config(10, 8, slots_max=1),
+    ])
+
+
+def esp32_v003() -> FakeProbe:
+    """A small probe with 64-byte frames over a 115200 bps UART bridge (its only transport, serial port 0):
+    classic ESP32 on a CH32V003 (SWIO) jig."""
+    reserved = [0, 1, 2, 3, 6, 7, 8, 9, 10, 11, 12, 15, 16]
+    wired = [4, 5, 13, 14, 17, 18, 19, 21, 22, 25, 26, 27, 32, 33]
+    return FakeProbe("esp32-v003", 64, [
+        _core("3.0.0", "esp32-d0wd", bytes.fromhex("0070070d9394"), 40, reserved, f"{NS}.esp32-v003",
+              {16: "SWIO", 23: "NRST", 22: "DUT TX", 21: "DUT RX"},
+              _transports([(TRANSPORT["uart_bridge"], 0xFF)])),
+        Offered(1, 1, "oep.wire.swio", (catalog.channel_group(1, [(1, 16)]), catalog.u8(IMPLEMENTATION, 1),
+                                        catalog.u8(MAX_CONNECTIONS, 1))),
+        Offered(2, 1, "oep.target.riscv-dm", (catalog.u32(FEATURES, 0b0111), catalog.u8(IMPLEMENTATION, 1),
+                                              catalog.u16(MAX_LENGTH, 40))),
+        Offered(3, 1, "oep.target.console", (catalog.tlv(MECHANISMS, bytes([0, 1, 2])),)),
+        Offered(4, 2, "oep.fixture.gpio", _roles({1: wired + [23]})),
+        Offered(5, 3, "oep.fixture.uart", _roles({1: wired, 2: wired}) + (
+            catalog.u32(MAX_CLOCK_HZ, 115_200), catalog.u8(IMPLEMENTATION, 2))),
+        Offered(6, 4, "oep.fixture.capture", _roles({k: wired for k in range(4)}) + (
+            catalog.u32(MAX_CLOCK_HZ, 2_000_000), catalog.u32(MIN_CLOCK_HZ, 400_000), catalog.u8(IMPLEMENTATION, 1))),
+        Offered(7, 5, f"{NS}.esp32.i2c-target", _roles({1: wired, 2: wired}) + (
+            catalog.u16(MAX_LENGTH, 16), catalog.u32(MAX_CLOCK_HZ, 100_000), catalog.u8(IMPLEMENTATION, 2))),
+        # Two fixed pin sets (an example of channel_group; GPIO23 is the DUT's NRST on this jig).
+        Offered(8, 6, f"{NS}.esp32.spi-target", (
+            catalog.channel_group(1, [(1, 18), (2, 19), (3, 5), (4, 4)]),
+            catalog.channel_group(2, [(1, 14), (2, 13), (3, 27), (4, 26)]),
+            catalog.u16(MAX_LENGTH, 32), catalog.u32(MAX_CLOCK_HZ, 3_000_000), catalog.u8(IMPLEMENTATION, 2))),
+        _config(9, 7, slots_max=1, modes=0b011, storage=1024),
+    ])
+
+
+def p4_bench() -> FakeProbe:
+    """A made-up bench probe with three RVSWD places and two seats (slots, the seat rule and the bind modes can be
+    exercised): USB-Serial/JTAG (serial port 0), vendor bulk, HID and a CDC (serial port 3) under the OEP VID:PID."""
+    reserved = [2, 3, 4, 5, 6, 7, 24, 25]
+    pins = [p for p in range(55) if p not in reserved]
+    return FakeProbe("p4-bench", 1024, [
+        _core("3.0.0", "esp32-p4-devkit", bytes.fromhex("30eda0e3b001"), 55, reserved, f"{NS}.p4-bench",
+              {2: "A SWDIO", 3: "A SWCLK", 4: "B SWDIO", 5: "B SWCLK", 6: "C SWDIO", 7: "C SWCLK"},
+              _transports([(TRANSPORT["usb_serial_jtag"], 0xFF), (TRANSPORT["vendor_bulk"], 0),
+                           (TRANSPORT["hid"], 1), (TRANSPORT["usb_cdc"], 2)]) + (catalog.u8(CORE_OEP_PID, 1),)),
+        Offered(1, 1, "oep.wire.rvswd", (
+            catalog.channel_group(1, [(1, 2), (2, 3)]), catalog.channel_group(2, [(1, 4), (2, 5)]),
+            catalog.channel_group(3, [(1, 6), (2, 7)]), catalog.u32(MAX_CLOCK_HZ, 5_000_000),
+            catalog.u8(IMPLEMENTATION, 1), catalog.u8(MAX_CONNECTIONS, 2))),
+        Offered(2, 1, "oep.target.riscv-dm", (catalog.u32(FEATURES, 0b1111), catalog.u8(IMPLEMENTATION, 1),
+                                              catalog.u16(MAX_LENGTH, 1000))),
+        Offered(3, 1, "oep.target.console", (catalog.tlv(MECHANISMS, bytes([0, 1, 2])),)),
+        Offered(4, 2, "oep.fixture.gpio", _roles({1: pins})),
+        Offered(5, 3, "oep.fixture.uart", _roles({1: pins, 2: pins}) + (
+            catalog.u32(MAX_CLOCK_HZ, 3_000_000), catalog.u8(IMPLEMENTATION, 2))),
+        _config(6, 4, slots_max=4),
+    ])
+
+
+PROFILES = {"p4-x035": p4_x035, "esp32-v003": esp32_v003, "p4-bench": p4_bench}

oep_client/v1/fake_serial.py

@@ -0,0 +1,105 @@
+"""The byte side of a fake probe's serial port (oep-core §3.1, §3.4): COBS frames and raw bytes on one port.
+
+`FakeSerialPort(endpoint, index)` is serial port `index` of an `endpoint.Endpoint`. Bytes from the host go to
+`feed`; what the probe sends comes from `output`. It does what a probe does:
+
+- a candidate runs from a 0x00 to the next 0x00; if it decodes and its CRC matches it is a request, otherwise it
+  (with its leading 0x00) is raw bytes, and the closing 0x00 starts the next candidate; bytes outside a candidate
+  are raw at once; a candidate that stops for 200 ms (`tick`) is raw; an empty candidate (0x00 0x00) is nothing
+- raw bytes go to the endpoint's bind for this port (`Endpoint.port_input`)
+- answers go out as 0x00 <COBS> 0x00, ahead of raw chunks (`Endpoint.port_output`); one writer, never a raw byte
+  inside a frame
+
+`answer_filter(n, message) -> bytes | None` may change how the n-th answer (1-based) goes on the wire: the framed
+bytes to send, or None to send nothing (fault injection for tests).
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from . import cobs, registry as reg
+
+GAP_MS = reg.TIMING["probe_frame_gap_ms"]
+
+
+class FakeSerialPort:
+    def __init__(self, ep, index: int, answer_filter: Callable[[int, bytes], bytes | None] | None = None):
+        self.ep, self.index = ep, index
+        self.answer_filter = answer_filter
+        self.cand: bytearray | None = None           # the candidate so far, its leading 0x00 included
+        self.last_ms = 0
+        self.limit = 2 * ep.probe.max_frame + 16     # longer than any COBS frame of max_frame: raw
+        self.frames: list[bytes] = []                # framed answers waiting to go out
+        self.answers = 0
+
+    def feed(self, data: bytes) -> None:
+        now = self.ep.now()
+        self._gap(now)
+        raw = bytearray()
+        for b in data:
+            if b == 0:
+                if self.cand is not None:
+                    self._close(raw)
+                self.cand = bytearray(b"\x00")
+            elif self.cand is not None:
+                self.cand.append(b)
+                if len(self.cand) > self.limit:
+                    raw += self.cand
+                    self.cand = None
+            else:
+                raw.append(b)
+        self.last_ms = now
+        self._raw(raw)
+
+    def _close(self, raw: bytearray) -> None:
+        body = bytes(self.cand[1:])
+        self.cand = None
+        if not body:
+            return                                   # 0x00 0x00: an empty frame
+        try:
+            msg = cobs.unframe(body)
+        except cobs.CorruptFrame:
+            raw += b"\x00" + body                    # not a frame: raw, the leading 0x00 too
+            return
+        self._raw(raw)                               # the raw bytes before the frame go first
+        raw.clear()
+        try:
+            result = self.ep.handle(msg, self.index)
+        except ValueError:
+            return                                   # not a request (a role the probe does not take): dropped
+        if result is None:
+            return
+        self.answers += 1
+        wire = cobs.frame(result)
+        if self.answer_filter is not None:
+            wire = self.answer_filter(self.answers, result)
+        if wire:
+            self.frames.append(wire)
+
+    def _gap(self, now: int) -> None:
+        if self.cand is not None and now - self.last_ms >= GAP_MS:
+            raw, self.cand = bytes(self.cand), None
+            self._raw(bytearray(raw))
+
+    def _raw(self, raw: bytearray) -> None:
+        if raw:
+            self.ep.port_input(self.index, bytes(raw))
+
+    def tick(self) -> None:
+        self._gap(self.ep.now())
+        self.ep.tick()
+
+    def output(self, room: int = 4096) -> bytes:
+        """What the probe sends now: waiting answers first, then raw bytes by the bind (up to `room` in all)."""
+        out = bytearray()
+        while self.frames and len(out) + len(self.frames[0]) <= max(room, len(self.frames[0])):
+            out += self.frames.pop(0)
+            if len(out) >= room:
+                return bytes(out)
+        while len(out) < room:
+            chunk = self.ep.port_output(self.index, min(self.ep.CHUNK, room - len(out)))
+            if not chunk:
+                break
+            out += chunk
+        return bytes(out)