Catch

CATCHAdd or remove one subscription-table entry

CATCH carries one table entry: address, direction, subscribe or unsubscribe, and how much of each packet to capture. Opcode 0x0B.

CATCH 0x0B · payload 6 bytes

Fire-and-forget

Classes 0-3 are the LOCK classes. Classes ≥4 are byte-oriented traffic.

snaplen is per entry: one subscription can take a 64-byte report whole while another cuts a bulk pipe to 16. A cut capture still carries the real length in true_len.

Input classes are captured at the emission merge point before any LOCK scale or injection, so a weighed or blocked input still reports its full native value.

EMIT is what the clone emitted after injection, locks, and the suppression gate.

Subscribe to every vendor interrupt endpoint, both directions, capturing the first 32 bytes of each packet (class = 6, id = 0xFFFF, snaplen = 32):

Subscribe to everything: class=0xFF, id=0xFFFF, dir=BOTH, state=1. Unsubscribe everything: the same with state=0, which clears the whole table in one frame:

A blanket (id = 0xFFFF) stays one wildcard entry, unlike a LOCK button or axis blanket, which expands per member. Library binding: catch_events.

TableMatching, capacity, refusals

Rank: an exact (class, id) entry, then a class blanket, then class = 0xFF. Ties go to the earlier entry. The highest-ranked entry supplies the snaplen.

  table (insertion order)
    #0  class = ANY        id = ALL     snaplen = 16
    #1  class = VEND_INTR  id = ALL     snaplen = 32
    #2  class = VEND_INTR  id = 0x83    snaplen = 0

  a 64-byte packet on vendor interrupt endpoint 0x83
    +- exact (class, id)?   #2  HIT  --> snaplen 0   -> all 64 bytes captured
    +- class blanket?       #1  (not reached)
    +- class = ANY?         #0  (not reached)

  the same 64-byte packet on endpoint 0x81
    +- exact (class, id)?       miss
    +- class blanket?       #1  HIT  --> snaplen 32  -> 32 bytes, true_len = 64
    +- class = ANY?         #0  (not reached)

  a control transaction on EP0
    +- exact (class, id)?       miss
    +- class blanket?           miss
    +- class = ANY?         #0  HIT  --> snaplen 16

The table holds 32 entries. No reply. A refused entry is absent from RESP(CATCH), whose header carries the table-full flag.

A subscription is PC-owned state, cleared by control-PC silence (the ~1 s timeout), a RESET, a mouse detach, a re-clone, inter-chip link loss, or an explicit unsubscribe. Every clear except the unsubscribe moves the session count.

The library's injection keepalive holds an open table past the silence timeout. The library re-asserts the whole table after the box clears it and across a control-link reconnect. The library's RESET ends the event stream.

The HEALTH CATCH_ON bit means the table is non-empty.

clk byteWhich chip's clock stamped an event

All three event frames lead with ts_us then clk. The two ESP32-S3s boot independently with unrelated timers, so a stamp compares only against another from the same domain.

Both clocks are box-local, unrelated to any control-PC clock.

Each clock wraps every ~71.6 minutes (a 32-bit microsecond counter) and returns to zero when its chip reboots. A value below the previous one is therefore a wrap, a reboot, or a domain change.

  clk = 0   HID_IN  ts_us = 1286497017   (host chip)
  clk = 0   HID_IN  ts_us = 1286544017   (host chip)
                            ----------
                    delta =      47000 µs / 1000 µs poll = 47 polls
                                            -> 46 polls where the device sent nothing

  clk = 1   EMIT    ts_us =  902114550   (device chip)
                    ^ smaller than the stamps above, and NOT earlier:
                      a different chip, a different epoch. Subtracting across
                      domains without the measured offset is meaningless.

RESP(CATCH) carries a measured offset between the two clocks, its drift rate, and the round trip that bounds its error.

Divide a gap by RESP(RATE)'s poll_period_us for a poll count, only if its CHANGE_DRIVEN flag is clear. A change-driven device's idle polls carry no report and can't be counted.

MOTION_EVENTOne native relative-axis snapshot, box → PC

While an AXIS subscription is active the box pushes a MOTION_EVENT for each native report whose motion changed. Opcode 0x0C.

SEQ is a rolling per-event counter shared with USAGE_EVENT and TRAFFIC_EVENT, stamped as each event is sent, so it orders a mixed stream.

SEQ doesn't detect drops: events drop before the stamp, so SEQ runs gapless. Losses are counted in RESP(CATCH).

MOTION_EVENT 0x0C · payload 13 bytes

Unsolicited

The stamp is taken when the real device's interrupt-IN transfer completes, so it is always the host chip's.

A native +10 right, no other motion (dx = 10):

USAGE_EVENTOne native held-usage snapshot, box → PC

While a BTN, KEY, or MEDIA subscription is active, the box pushes a USAGE_EVENT when that class changes. The event is a class-tagged snapshot of the usages currently held. Opcode 0x0F.

It's a full snapshot, not edge deltas, so a dropped frame self-corrects on the next one.

USAGE_EVENT 0x0F · payload 8 + 3n bytes

Unsolicited

Each entry is 3 bytes, and the snapshot is n of them. All are one class, since one native report is one class.

Only held usages that match the table appear. If none match, no event is sent.

A snapshot lists what is currently held, so the release of a usage is the snapshot that no longer names it. Without cls, "all buttons released" and "all keys released" are the same bytes.

The box resolves each usage against its entry's direction. While another subscriber holds a wider entry, though, the box sends an event on both edges, and only dir tells them apart.

Route by class, not by the usages present, and diff successive snapshots for the usages of interest. Matching on present usages misses the release edge while another subscription's usage is held.

Left Shift held while pressing A (a keys snapshot, two usages both class = 1: Left Shift id = 0xE1, then A id = 0x04):

TRAFFIC_EVENTByte-oriented class traffic, box → PC

One frame type carries every traffic class, 4-11. Opcode 0x16.

TRAFFIC_EVENT 0x16 · payload 12 + n bytes

Unsolicited

  frame LEN = 12 + 16   ->  16 bytes arrived
  true_len  = 64        ->  the packet was 64 bytes
                            ------------------------
                            48 bytes were cut by snaplen, not absent from the wire

  frame LEN = 12 + 4    ->  4 bytes arrived
  true_len  = 4         ->  the packet really was 4 bytes long

An event is one packet, except a HID_IN or EMIT event on a HID endpoint. That event carries a report of ≤64 bytes whole, however many packets it took. A longer report comes a packet at a time.

  the device sends            HID_IN              the PC takes               EMIT

  [ 32 ] [ ZLP ]      -->  32 bytes, b1     [ 32 ] [ ZLP ]         -->  32 bytes, b1
  [ 32 ] [ 32 ]       -->  64 bytes         [ 32 ] [ 32 ]          -->  64 bytes
  [ ZLP ]             -->   0 bytes, b1     [ ZLP ]                -->   0 bytes, b1
  [ ZLP ]             -->   0 bytes, b1     a report of the box's  -->  its bytes (b1 if it ends in one)

  vendor endpoint: one event a packet, so [ 64 ] [ ZLP ] is 64 bytes, then 0 bytes with b1

CONTROL carries one event per completed transaction: bytes is [setup 8][data ...] and dir is the data stage's direction.

The event is the transaction as the game PC received it, the same on every control endpoint. A request served from the box's value cache still produces an event.

  bytes = A1 01 00 01 00 00 08 00   01 00 00 00 00 00 00 00
          '------ setup (8) ------'   '---- data stage -------'
          HID GET_REPORT(Input)       dir = 1 (IN), flags = 0 (completed OK)

CLIP_XFER carries one event per control transfer a clip sent to the real device, in CONTROL's shape: bytes is [setup 8][IN data].

Only a transfer the box sent raises an event. The rest are counted in RESP(CLIP).

BUS carries [a][b] in bytes with the kind in flags, and true_len is the operand count.

The same events drive HEALTH bits and STATS counters. Here they carry a timestamp and their place in the stream.

The box suspends the real device on SUSPEND and resumes it on RESUME. A device the PC armed for remote wakeup wakes the PC through the clone.

A 64-byte vendor interrupt report arriving IN on endpoint 0x83, captured under a snaplen = 16 entry (16 bytes present, so payload LEN = 28):

A SET_INTERFACE bus event on interface 1, alternate setting 2 (two operand bytes, so payload LEN = 14):

A SET_REPORT on EP0 that a STALL rule refused: flags = 0x81, RULE with handshake 1 (STALL), and the two data bytes the PC sent (payload LEN = 22):

Rules and tapsTap positions around the rewrite table

Flags bit 7, RULE, marks a packet a rewrite rule acted on at the event's class: changed its bytes, dropped it, answered it or refused it. A PASS, or a PATCH that changed no byte, leaves the bit clear.

  packet
     |
     +--> tap: HID_IN, HID_OUT, vendor OUT    the bytes as they arrived
     v
  [ rewrite table ]                           RULE set when the rule acts
     |
     +--> tap: vendor IN, EMIT                the bytes delivered
     v
  game PC or real device

CLIP_XFER carries a transfer status in its flags byte and never RULE: a clip's transfer runs past every rule.

DeliveryBest-effort, ranked, and counted per entry

Events drain through strict-priority queues.

  BTN KEY MEDIA AXIS BUS    -->  [ queue 0 ]  --+
  HID_IN HID_OUT                                |
  VEND_INTR EMIT            -->  [ queue 1 ]  --+--->  control link, 6 Mbaud
  CONTROL CLIP_XFER         -->  [ queue 2 ]  --+
  VEND_BULK                 -->  [ queue 3 ]  --+

  strict priority: each queue drains fully before the next

Under a busy mouse, bulk can go undrained indefinitely: the control link can't carry bulk plus input.

Under back-pressure the box drops events rather than stall the report path, so the stream never delays reports to the game PC. Every drop is counted per entry in RESP(CATCH).