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

QUERY 0x05 · payload 1 byte (2 for OPTIONS)

Returns RESP

The box replies with a RESP carrying the same what and the requested data, one per selector in the table above. QUERY is the only command that gets a reply; everything else 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_emit_pace, and the clip status query.

what = 0 (read the version):

+--------+--------+--------+--------+--------+--------+
| A5     | 05     | 00     | 01 00  | 00     | lo hi  |
+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | CRC16  |
+--------+--------+--------+--------+--------+--------+

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

RESP 0x06 · box → PC

Reply

You get exactly one RESP per QUERY. Its SEQ matches the request's and what echoes the selector, so you can pair a reply with its request and tell which kind it is. Each selector's payload is laid out below, with an example frame.

The RESP payload when what = 0. proto_ver is the protocol version (this documentation describes 3); the box reports its own firmware version, then its base mac, a stable per-box id, then a length-delimited ASCII name tail (a synthesized default when unset). The name is additive, so proto_ver stays 3: an older box just sends an empty tail.

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

Returns RESP

The box also sends this unprompted at startup, as a ready signal. The mac stays fixed for a box, so it identifies the same box across replugs and port renumbering; the name is its readable label. Library binding: query_version.

Firmware 3.0.0, protocol 3, MAC 123456789abc, name "Loki":

+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 0F 00  | 00     | 03     | 03     | 00     | 00     | ...    |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | proto  | major  | minor  | patch  | ...    |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| ...    | 12 34 56 78 9A BC  | 4C 6F 6B 69  | lo hi  |
+--------+--------------------+--------------+--------+
| ...    | mac (6 bytes)      | "Loki"       | CRC16  |
+--------+--------------------+--------------+--------+

The RESP payload when what = 1: a single flags byte, each bit an independent status.

QUERY what = 1 · RESP 2 bytes

Returns RESP

The first three bits set means the box is ready for input to reach the PC. Library binding: query_health.

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

+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 02 00  | 01     | 07     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | flags  | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 2: the USB identity, kind, and product string the box read from the real device. The clone shows up on the game PC, not here, so this is the only way the control PC can read it. The header is fixed at 11 bytes, then a length-delimited UTF-8 product tail (which may be empty). Every field is zero when nothing is attached.

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

Returns RESP

A vid of 0 means nothing is attached yet. Library binding: device_info.

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

+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 0F 00  | 02     | 6D 04  | 8B C0  | ...    |
+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | vid    | pid    | ...    |
+--------+--------+--------+--------+--------+--------+--------+--------+
| ...    | 10 01  | 01 02  | 03     | 02     | 47 35 30 32  | lo hi  |
+--------+--------+--------+--------+--------+--------------+--------+
| ...    | bcdDev | bcdUSB | flags  | kind   | "G502"       | CRC16  |
+--------+--------+--------+--------+--------+--------------+--------+

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. Use it to check before you act: an INJECT for a usage the device lacks is silently ignored, so the counts tell you what is real. A class that is not present 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):

+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 07 00  | 03     | 05     | 07     | 01     | 06     | 02     | 02     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | n_btn  | axis   | n_hid  | n_keys | kbdfl  | chgdrv | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 4: how fast the active input reports, plus the poll period the clone advertises. The answer is class-aware, so read the field that fits 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):

+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 06 00  | 04     | E8 03  | E8 03  | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | native | poll   | flags  | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 5: counters the box keeps about whether your commands were delivered. Commands are fire-and-forget with no acknowledgement, so these counters are the only way to tell that everything you sent landed. A nonzero tx_drops or tx_wedges means delivery slipped under load. Wide counters clamp at their max instead of wrapping around.

QUERY what = 5 · RESP 17 bytes

Returns RESP

inject_emits counts the no-halving / 1 kHz path. The rest are merge, queue, wakeup, reset, and reconfig counters. Library binding: query_stats.

4096 emits, no drops, no wedges:

+--------+--------+--------+--------+--------+--------------+
| A5     | 06     | 00     | 11 00  | 05     | 00 10 00 00  |
+--------+--------+--------+--------+--------+--------------+
| SOF    | TYPE   | SEQ    | LEN    | what   | inject_emits |
+--------+--------+--------+--------+--------+--------------+
| 00 00  | 00 00  | 00     | 00     | 00 00  | 00 00  | 00 00  | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+
| drops  | merges | maxdep | wedges | wakeup | resets | config | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 6: which physical inputs are currently locked by LOCK, as a variable list of entries, one per locked field across every class, so keyboard and media locks read the same as mouse ones. An empty list (n = 0) means nothing is locked.

QUERY what = 6 · RESP 2 + 4n bytes

Returns RESP

Read it to confirm a lock landed, or to mirror the box's lock state in a UI. Library binding: query_locks.

One entry: the wheel's negative (scroll-down) sign locked (class = 3 axis, id = 2 wheel, dirbits = 0x02):

+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 06 00  | 06     | 01     | 03     | 02 00  | 02     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | n      | class  | id     | dirbits| CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 7: the active CATCH subscription mask, plus the box-side count of event frames dropped under back-pressure. A zero mask means nothing is subscribed. Mirrors the CATCH_ON health bit.

QUERY what = 7 · RESP 6 bytes

Returns RESP

Read it to confirm a subscription landed, or to check whether you're losing events. Library binding: query_catch.

Motion and buttons subscribed, no drops (mask = 0x05):

+--------+--------+--------+--------+--------+--------+--------------+--------+
| A5     | 06     | 00     | 06 00  | 07     | 05     | 00 00 00 00  | lo hi  |
+--------+--------+--------+--------+--------+--------+--------------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | mask   | dropped      | CRC16  |
+--------+--------+--------+--------+--------+--------+--------------+--------+

The RESP payload when what = 9: the value of one persistent box OPTION, echoing the queried id. The value is id-specific, so the query takes the option's id as a second byte and each option is read on its own. 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.

Read it to tell why a clone is missing (over_capacity = 1, allowed = 0), or to confirm 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 pacing (id 2): the mode, the configured fixed rate, and the rate actually in effect.

Library binding: query_emit_pace.

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

+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 06     | 00     | 05 00  | 09     | 00     | 01     | 01     | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | what   | id     | allow  | overcap| imperf | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+--------+--------+

The RESP payload when what = 10: the buffered-clip ring depth, playback state, and full config, for host flow-control. A fixed 25-byte prefix, then the clip's held-usage snapshot (the same class-tagged list a USAGE_EVENT carries), then the config tail (autolock, flags, and the bound triggers). Read free before a CLIP_APPEND to avoid an overrun, and state to see a fault or that playback finished. Backs ClipHandle::query_status and query_config.

QUERY what = 10 · RESP 25-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), so buttons, keys, and media are reported one way. The config tail mirrors what CLIP_SET and CLIP_TRIGGER set, so a UI can read back the whole clip in one query. Library bindings: query_status (ClipStatus) and query_config (ClipSettings).

Idle, empty ring, no held usages, no autolock, no triggers (state = 0, free = 1024):

+--------+--------+--------+--------+--------+--------+--------------+
| A5     | 06     | 00     | 1C 00  | 0A     | 00     | 00 04 00 00  |
+--------+--------+--------+--------+--------+--------+--------------+
| SOF    | TYPE   | SEQ    | LEN    | what   | state  | free         |
+--------+--------+--------+--------+--------+--------+--------------+
| 00 04 00 00  | 00 00 00 00  | 00 00 00 00  | 00 00  | 00 00  | 00 00  |
+--------------+--------------+--------------+--------+--------+--------+
| total        | played       | ticks        | undrun | ovrrun | seqgap |
+--------------+--------------+--------------+--------+--------+--------+
| 00     | 00     | 00     | 00     | lo hi  |
+--------+--------+--------+--------+--------+
| held_n | autolk | flags  | n_trig | CRC16  |
+--------+--------+--------+--------+--------+