mchose: give the A7 V3 driver its settings writes

[jamezrin]

Stacked on #100, which this branch contains — review that one first, or this diff includes it.

Adds the write half of the V3 driver: polling, DPI (current value, per-stage values, active stage, stage count), lift-off, motion sync, angle snapping, ripple control, glass mode, power mode, angle tuning, sleep, debounce, profile switching and button remapping.

How every setter is built

This protocol has no partial update — each command replaces a whole block. So a setter reads the block, edits the decoded object, writes it, and reads back to confirm, throwing when the mouse reports something other than what it was told. A read that fails aborts rather than letting defaults be written over a working configuration.

Three things the hardware capture and the V2's history forced

The settings block's tail is not padding. M HUB writes ten zero bytes past the nine named fields. The real A7 V3 Ultra+ returns ten bytes of 0x08 there — the same value as both its debounce fields, so most likely the debounce for the remaining buttons. Those bytes are now decoded into the settings object and written straight back, so changing the sleep timer cannot quietly zero them.

The sensor byte is masked, never assigned. The A7 V2's bit 5 was never explained, and a writer that assigns the byte destroys whatever it held. The mode field is bounded by its two bits rather than by the three names MCHOSE gives them, so a mouse reporting the unnamed fourth state can still have everything else written; picking a new mode goes through the name lookup, which cannot produce it.

The DPI write and read do not order their fields the same way — the write puts hasSeparateY third, the read puts it fifth. Copying a decoded table into a write buffer swaps it with the stage count. The test fake models both orders so a driver that got it backwards would fail rather than agree with itself.

⚠️ Not sent to a device

The framing under these writes is proven — the mouse answers frames built by the same encoder — but the firmware's response to each write is not. The settle delay is the A7 V2's 400 ms rather than a measured figure, and whether any write needs a separate commit command is unknown (nothing in the vendor bundle suggests one; nothing rules it out). The user-facing status note says so, and the docs name both numbers to suspect first.

If you would rather this waited for a tester, say so and I will park it — the read-only driver on main is unaffected either way.

The button vocabulary is deliberately two entries wide, Default and Disabled, because those are the only encodings that appear in a real capture. Keyboard, media, DPI, macro and profile actions all exist in the protocol and stay unavailable until someone records what M HUB writes for them: a button is the one setting where a wrong guess can leave someone unable to click.

Testing

28 driver tests and 40 codec tests. The fake is now a small stateful device, so a write is visible to the read that follows and the driver's own verification is exercised rather than agreeing with itself. Coverage includes: the tail surviving an unrelated write, one sensor bit moving without disturbing the others, the untouched DPI stages coming back byte-identical, the active stage being pulled back when the list shortens, only the connected link being written, a rejected write sending nothing at all, and a firmware that ignores writes producing a thrown error rather than a false success.

npm run check passes apart from the two pre-existing src/drivers/corsair/hid.test.ts setDpi failures, which also fail on a clean main locally.

🤖 Generated with Claude Code

[jamezrin]

Pushed a follow-up that replaces the two-action button vocabulary with M HUB's own, 168 entries: mouse buttons and wheel, DPI switch and step, media transport, volume, screen brightness, copy/cut/paste, the four onboard-profile actions, and the keyboard.

The original "only what a capture proves" stance was needlessly conservative — the vendor bundle carries the whole vocabulary in the same seven tables the A7 V2's came from, so there was nothing left to guess at.

Reading them turned up two bugs that were already reaching users through the read-only display:

• "Disabled" was the wrong type. It was 0xff; the vendor's "forbidden" action is 0xfe. 0xff is a button carrying no assignment at all — what a stock A7 V3 Ultra+ reports for its DPI button — and M HUB never writes it. The old code would have sent a value the firmware itself never sends.
• The type names were the A7 V2's. Nothing carries over. This generation uses 0x00 mouse, 0x01 DPI, 0x05 wheel, 0x11/0x13 keyboard, 0x14 media, 0x16 system, 0x33 profile. A V3 button on a media action was being labelled with whatever the V2 puts at that number.

Letters, function keys and navigation keys are derived, not invented: the vendor's table covers punctuation, digits, numpad, locks and modifiers and leaves the rest to its on-screen keyboard, but its own shortcut entries spell out the same standard HID usages under the same type (Ctrl+A 0x04, Ctrl+C 0x06, Alt+F4 0x3d, Esc 0x29), so the usage page is confirmed rather than assumed. Macros stay unavailable — 0x23/0x24 are wide enough to carry a reference but the vendor lists nothing under them.

A button sitting on its own factory mask reads back as "Default" rather than as the click it happens to encode, and a type/value pair the tables don't cover is reported as unknown rather than named by guess.

docs/mchose-protocol.md now has the full type table, including the 0xfe vs 0xff distinction.

Tests: 71 across the codec and driver, all passing. npm run check is clean apart from the two pre-existing Corsair setDpi failures.

[jamezrin]

Merged #100's latest work into this branch, which adds the reply-handling fixes described there: a 1500 ms reply timeout to clear the firmware's fixed ~1.001 s deferral, recognition of the refusal frame the firmware sends for 0x0901, and the one-byte 0xff ask-again a stranded receiver returns. Those matter here too — a write's read-back verification runs through the same request path, so a missed reply would have been reported as a rejected write.