Requests

QUERYAsk the box for state

QUERY asks for one piece of state, named by its what byte. Opcode 0x05.

QUERY 0x05 · payload 1 byte (2 for OPTIONS, REWRITE_ENTRY and PATCH_ENTRY)

Returns RESP

The box replies with a RESP carrying the same what and the requested data. Besides QUERY, only UPDATE and TRANSFER reply. Every other command is fire-and-forget.

Library bindings: query_version, query_health, device_info, caps, query_rate, query_stats, query_locks, query_catch, query_imperfect, query_movement_riding, query_bearing, query_emit_pace, the clip status query, firmware_info, query_rewrite, query_rewrite_entry, query_patches, query_patch_entry, and query_transforms.

what = 0 (read the version):

RESPReply from the box

RESP is the box's reply to a QUERY. Opcode 0x06.

RESP 0x06 · box → PC

Reply

At most one RESP per QUERY, its SEQ matching the request's.

VERSIONRESP payload, what = 0

The RESP payload when what = 0: protocol version, firmware version, base mac, then a length-delimited ASCII name tail. The tail is additive. An older box sends it empty.

QUERY what = 0 · RESP 11-byte header + name

Returns RESP

The box also sends this unprompted at boot and on the first frame it receives, as a ready signal. The mac identifies the same box across replugs and port renumbering. Library binding: query_version.

Firmware 3.4.6, protocol 9, MAC 123456789abc, name "Loki":

HEALTHRESP payload, what = 1

The RESP payload when what = 1: a two-byte flags word (u16, little-endian), each bit an independent status.

QUERY what = 1 · RESP 3 bytes

Returns RESP

With the first three bits set, input reaches the PC. Library binding: query_health.

Ready, with link, mouse, and clone all up (flags = 0x0007):

DEVICE_INFORESP payload, what = 2

The RESP payload when what = 2: the USB identity, kind, and product string read from the real device, otherwise invisible to the control PC. Every field is zero with nothing cloned. A clone with no HID interface reads primary_kind 0, with its identity filled in.

QUERY what = 2 · RESP 11-byte header + product

Returns RESP

Library binding: device_info.

A Logitech G502 (046D:C08B), USB 2.01, serial and BOS served, kind mouse, product "G502":

CAPSRESP payload, what = 3

The RESP payload when what = 3: one summary of the whole cloned device, mouse and keyboard, read from its HID report descriptors. Counts and yes/no flags only, never raw HID field offsets.

An INJECT for a usage the real device lacks reaches no report field. An absent class reads all-zero.

QUERY what = 3 · RESP 7 bytes

Returns RESP

Library binding: caps.

A 5-button mouse (X/Y/wheel, one interface) plus a 6-key Consumer keyboard (axis_flags = 0x07, kbd_flags = 0x02, keyboard change-driven):

RATERESP payload, what = 4

The RESP payload when what = 4: how fast the active input reports, plus the poll period the clone advertises. Which field to read depends on the input kind.

QUERY what = 4 · RESP 6 bytes

Returns RESP

A 1 kHz mouse reads ~1000 µs once learned. Library binding: query_rate.

A 1 kHz mouse, 1000 µs poll, estimator confident (flags = 0x01):

STATSRESP payload, what = 5

The RESP payload when what = 5: delivery counters, the only delivery feedback for fire-and-forget commands.

A nonzero tx_drops or tx_wedges means native input was dropped or stalled on the way to the PC. A nonzero link_rx_drops or host_rx_drops means a native report or injected delta was lost between the two chips.

relay_drops is counted apart from the native-input drop counters, so lost relayed traffic doesn't read as lost native input. The eight narrowed counters clamp at their max instead of wrapping. The three drop counts are full width.

session counts releases of host-set state. A change since the last read means some or all of it is gone and needs setting again.

Most releases drop all of it, and two drop part. Turning OPTION(IMPERFECT) off drops only rewrite rules, consuming packet triggers and queued clip transfers, unless the toggle also presents the clone again. A configuration switch by the game PC that unbinds a role (the mouse, the keyboard, the consumer control) drops only the locks, injected usages and owed motion held on that role.

QUERY what = 5 · RESP 31 bytes

Returns RESP

Library binding: query_stats.

Host-set state: injection, locks, CATCH subscriptions, rewrite rules, transforms, the clip with its settings and triggers, and an LED override. The count is 0 at boot, announced by the ready hello. One release counts once, however many of these it clears. A release of everything counts only if a command other than QUERY or RESET arrived since the last count.

4096 emits, every drop counter at 0, session at 2:

LOCKSRESP payload, what = 6

The RESP payload when what = 6: native inputs currently weighed by LOCK, one entry per non-passing direction. An empty list (n = 0) means everything passes.

QUERY what = 6 · RESP 2 + 6n bytes

Returns RESP

Entries mirror the LOCK frame field for field, so a readback replays as commands.

The frame is the cap: 2 + 85 x 6 is exactly the 512-byte payload. The box's tables cap rows 1-4 at 59 combined, so they always fit. Keyboard usages are the one unbounded class: 252 of them, two edges each.

Library binding: query_locks.

One entry: the wheel's negative (scroll-down) sign blocked (class = 3 axis, id = 2 wheel, direction = 2, scale = 0):

CATCHRESP payload, what = 7

The RESP payload when what = 7: the active CATCH subscription, a fixed scalar header then the table, shaped like RESP(LOCKS). An empty table means nothing is subscribed, matching the CATCH_ON health bit.

QUERY what = 7 · RESP 19 + 7n bytes

Returns RESP

The box-wide dropped counts every lost event. The per-entry one attributes them to a subscription.

CATCH is fire-and-forget, so this reply is the only confirmation an entry landed. A refused entry is absent from the list. flags b0 marks a full 32-entry table as the reason. Library binding: query_catch.

The two ESP32-S3s boot independently with unrelated timers, and events carry stamps from both (the clk byte).

The box measures the difference with a four-timestamp exchange across the inter-chip link, stamped as each frame reaches the wire rather than when it is queued.

  device chip                              host chip
      t1  ------- request -------------------> t2
                                               |
      t4  <---------------- reply ------------ t3

      offset = ((t2 - t1) + (t3 - t4)) / 2
      delay  =  (t4 - t1) - (t3 - t2)     ->  the error bound is delay / 2

Applying the offset is optional. The clk byte on each event stays authoritative.

One entry, every mouse button, both edges, whole packet (class = 0, id = 0xFFFF, dir = 0, snaplen = 0), with no drops and no clock estimate taken yet:

OPTIONSRESP payload, what = 9

The RESP payload when what = 9: one persistent box OPTION value, echoing the queried id. Values are id-specific, so each option is read separately. An unknown id gets no reply.

QUERY what = 9, id · RESP varies

Returns RESP

The IMPERFECT opt-in (id 0) plus two derived clone-status bytes. Each is 0 or 1. A faithful clone reads all-zero.

The value shows why a clone is missing (over_capacity = 1, allowed = 0) or confirms an imperfect clone is live (clone_imperfect = 1). Library binding: query_imperfect.

The current MOVE_RIDE window (id 1).

Library binding: query_movement_riding.

The current EMIT pace and wire rate (id 2).

A force_hz set while IMPERFECT is off reads back with force_active 0 and advertised_hz still the native interval.

Library binding: query_emit_pace.

The current BEARING setting (id 4): window and geometry mode.

Library binding: query_bearing.

The current RENDER setting (id 5), and whether a render profile has been learned.

Nothing is rendered while ready reads 0. It also reads 0 while the box's two chips have not yet agreed which holds the motion. Until then, motion is relayed and injection takes the paced fill, whatever mode says.

Library binding: query_render.

The current SPREAD setting (id 6), and the interval injected deltas are released across.

span_us reads 0 while percent is 0, while no command period has been learned, and while the box's two chips have not yet agreed which holds the motion. In each case the whole delta is emitted on the next report the box emits.

Library binding: query_spread.

Reading id = 0: opted in, an over-capacity device attached and cloned imperfectly:

CLIPRESP payload, what = 10

The RESP payload when what = 10: the buffered-clip ring depth, playback state, and full config. A fixed prefix, then the clip's held-usage snapshot (the same class-tagged list a USAGE_EVENT carries), then the config tail.

QUERY what = 10 · RESP 31-byte prefix + held usages + config

Returns RESP

The held snapshot lists the usages the clip is currently forcing down, one class-tagged entry each (3 bytes). ticks and the six counters count since boot and wrap.

A packet trigger reads back as the command that set it with hits spliced in after mlen and bit0 (present) clear. A host replays it by setting bit0. The whole reply is ≤507 bytes, inside one frame.

Library bindings: query_status (ClipStatus) and query_config (ClipSettings).

Idle, empty 64 KB ring, no held usages, no autolock, no triggers of either kind (state = 0, free = 65536):

One packet trigger entry: HID_IN id 0x0102, IN, TOGGLE, consume and RUN, selector 1, hits saturated.

04 02 01 01 05 06 01 02 FF FF 07 20 FF 20
   class=4 HID_IN   id=0x0102   dir=1 IN   action=5 TOGGLE   flags=0x06   slen=1   mlen=2
   hits=65535   match=07 20   mask=FF 20

FIRMWARERESP payload, what = 11

The RESP payload when what = 11: both chips' versions, the slot each is running, and what is staged.

The only source of the host chip's version. VERSION reports the device chip alone.

Read it before an UPDATE: slot_size is the largest image a chip will take, and a chip whose state is pending-verify refuses to open one.

QUERY what = 11 · RESP 17 bytes

Returns RESP

Library binding: firmware_info.

Both chips on 3.4.6, device on ota_1, host on ota_0, both images valid, nothing staged:

REWRITERESP payload, what = 12

The RESP payload when what = 12: a REWRITE table summary, a four-byte header then twelve bytes per rule in table order.

QUERY what = 12 · RESP 4 + 12n bytes

Returns RESP

A line carries no match, mask or payload bytes. Read those with QUERY(REWRITE_ENTRY). HEALTH sets REWRITE_ON (0x0100) while the list is non-empty.

The table is PC-owned session state on the same lifecycle as locks, so an empty list can mean the box released it. session counts that release. Library binding: query_rewrite.

One rule, DROP on EMIT endpoint 1, after 42 hits, with the table not full:

REWRITE_ENTRYRESP payload, what = 13

The RESP payload when what = 13: one rule in full. The QUERY carries [13][index], where index is the rule's line in RESP(REWRITE).

QUERY what = 13 · RESP 11 + 2 x mlen + plen bytes

Returns RESP

Past the first two bytes it is a REWRITE payload that reinstalls the rule. An index ≥n gets no reply. Library binding: query_rewrite_entry.

Rule 0, the DROP on EMIT endpoint 1:

PATCHESRESP payload, what = 14

The RESP payload when what = 14: a stored PATCH set summary, a three-byte header then seven bytes per patch in set order. An overwrite moves a patch to the end.

QUERY what = 14 · RESP 3 + 7n bytes

Returns RESP

A line carries no patch bytes. Read those with QUERY(PATCH_ENTRY). HEALTH sets PATCH_ON (0x0200) while b0 is set.

The list is the stored set. The clone serves the same set while b1 is clear, and none while b0 is clear. With the real device unplugged, the list is the last attached device's set. Library binding: query_patches.

One applied patch, bcdDevice in the device descriptor (offset = 12, len = 2):

PATCH_ENTRYRESP payload, what = 15

The RESP payload when what = 15: one patch in full. The QUERY carries [15][entry], where entry is the patch's line in RESP(PATCHES).

QUERY what = 15 · RESP 7 + len bytes

Returns RESP

Past the first two bytes it is a PATCH payload that restores the patch. An entry ≥n gets no reply. Library binding: query_patch_entry.

Entry 0, the bcdDevice patch setting 0x0200:

TRANSFORMSRESP payload, what = 16

The RESP payload when what = 16: the installed TRANSFORM table, a three-byte header then seven bytes per entry in install order.

QUERY what = 16 · RESP 3 + 7n bytes

Returns RESP

An entry mirrors the TRANSFORM frame field for field except the state byte, so a readback replays as commands.

HEALTH sets its TRANSFORM_ON bit (0x0400) while the table is non-empty.

The table is PC-owned session state on the same lifecycle as locks and the catch subscription, so an empty list can mean the box released it. session counts that release. Library binding: query_transforms.

One entry, X and Y swapped (op = 1, source (axis 3, id 0), dest (axis 3, id 1)), with the table not full: