A patch names a descriptor, an offset into it, and the bytes to write there. Opcode 0x1D.

PATCH 0x1D · payload 5 + n bytes

Fire-and-forget

A patch is stored under (section, cfg, index, offset) exactly as sent, ignored fields included, so send 0 in those.

A change is written to NVS at once and reaches the game PC at the clone's next presentation. A refused frame has no reply: read RESP(PATCHES) for the patch, or for FULL.

Set bcdDevice to 0x0200: section DEVICE, offset = 12, bytes 00 02:

+--------+--------+--------+--------+--------+--------+
| A5     | 1D     | 00     | 07 00  | 00     | 00     |
+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | section| cfg    |
+--------+--------+--------+--------+--------+--------+

+--------+--------+--------+--------+
| 00     | 0C 00  | 00 02  | lo hi  |
+--------+--------+--------+--------+
| index  | offset | bytes  | CRC16  |
+--------+--------+--------+--------+

Library binding: set_patch.

APPLY is a PATCH frame with section 0xFE; the rest of the payload is ignored.

PATCH 0x1D · payload 1 byte

Fire-and-forget

When the stored set differs from the one the clone serves, the box presents the clone again with a copy of the stored set and runs the checks. An emptied set presents it unpatched.

Present the stored set:

+--------+--------+--------+--------+--------+--------+
| A5     | 1D     | 01     | 01 00  | FE     | lo hi  |
+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | section| CRC16  |
+--------+--------+--------+--------+--------+--------+

Library binding: apply_patch.

CLEAR is a PATCH frame with section 0xFF. It runs with the opt-in off and with the device unplugged.

PATCH 0x1D · payload 1 byte

Fire-and-forget

Either way RESP(PATCHES) then reads with REFUSED and FULL clear. With the device unplugged, CLEAR erases the key of the last device attached since boot, or nothing after a boot with none attached.

Erase the set:

+--------+--------+--------+--------+--------+--------+
| A5     | 1D     | 02     | 01 00  | FF     | lo hi  |
+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | section| CRC16  |
+--------+--------+--------+--------+--------+--------+

Library binding: clear_patch.

The clone serves the set it was last presented with, every section included. A presentation copies the stored set, runs the checks and re-enumerates the clone on the game PC.

  PATCH   --> stored set        NVS, read back by QUERY(PATCHES)
                  |
                  |  presentation: attach, APPLY, CLEAR, opt-in toggle
                  v
              served set        what the game PC reads at enumeration

RESP(PATCHES) lists the stored set; its flags say whether the clone serves it.

A patch writes over bytes the descriptor already has, except STRING, which replaces the string. One that would run past the descriptor's end is skipped whole, never truncated.

  device descriptor   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11
  offset 12, 2 bytes                                      xx xx                  lands
  offset 17, 2 bytes                                                     xx xx   past the end: skipped

With two STRING patches on one index, the one listed first in RESP(PATCHES) is served. An overwrite moves a patch to the end of that list.

A set that fails a check the device passes without it is refused: the clone is presented unpatched and one LOG line names the check. A device that fails without the set is refused as any device is.

  patched descriptors
        |
        +-- the clone checks every device faces
        +-- framing: length and type fields
        +-- bcdUSB against BOS
        +-- wDescriptorLength against the report descriptor, every configuration
        +-- wMaxPacketSize against the report, the configuration in force
        |
        +-- all hold   -->  clone served patched, PATCHES b0, HEALTH PATCH_ON
        +-- one fails  -->  clone served unpatched, PATCHES b1 + b2, one LOG line

The set stays stored with PATCHES b2 set until it changes, and APPLY skips it until then. Change or remove the failing patch and APPLY, or CLEAR the set.

OPTION(IMPERFECT) gates whether the stored set reaches the clone.

A toggle presents the clone again when that changes the set it serves. When the clone needs the opt-in for anything else, the device chip reboots and re-clones, as the option describes.

While the clone serves a patched set, HEALTH sets PATCH_ON (0x0200) and QUERY(OPTIONS, 0) reports clone_imperfect = 1. A refused set sets neither.

A set is stored per device, loaded when that device attaches, and kept until a removal, a CLEAR, or a RESET with the NVS flag erases it.

remove      a PATCH with zero bytes at the patch's key
CLEAR       a PATCH with section 0xFF: the whole set
RESET       a RESET carrying the NVS flag: the whole store