MX Master 4: haptics, wheel settings, friendly name and Easy-Switch

[weltern]

Implements the features discussed in #1. Codec in src/logitech/, drivers in
LogitechHidppClient, per the boundary agreed there.

Companion OpenMouse PR: OpenMouse-Project/openmouse#82 (device panel cards and artwork).

Device

Model	Logitech MX Master 4
Connection	Logi Bolt receiver 046d:c548, pairing slot 2
WPID / model id	B042 (B04200000000)
Firmware	LD 04.00, RBM 27.00 / RBM 27.03, HW 00.00
Protocol	HID++ 4.5, 45 features

Builds on #46, which brought Bolt support and the MX Master 3S. Its closing note
lists SmartShift, hi-res and thumb wheel, host switching and button remaps as
not yet implemented; the first three are here, and button remapping is held back
for a follow-up so this stays reviewable.

Evidence

Almost all of it came from watching Logi Options+ rather than guessing. The Bolt
receiver broadcasts replies to every open handle, and the low nibble of the
function byte carries the requester's software id — Options+ uses 0x0F. So
changing a setting in the vendor application and reading the reply gives the
function id and the byte layout directly. No packet capture involved.

Where something is inferred rather than observed, it says so below.

0x19B0 Haptic — not implemented in any public tool I can find

Read fn 0x01 / write fn 0x02, two bytes.

• Byte 1 is strength. The four Options+ presets write exactly 25, 45, 60 and
  100, each read straight back by the getter. Capability byte 3 reports 60,
  matching its Medium.
• Byte 0 is a flag bitmask — bit 0 haptics on/off, bit 1 battery saving.
  Established by flipping each Options+ switch and observing which bit moved:
  ten writes for ten toggles, and only those two pairs changed anything. Its
  per-context switches (Actions Ring, Gestures, Switch Screens) move no device
  byte at all, so those are decided in its own software. Bits 2-7 were zero
  throughout and their purpose is unknown, so writes carry them through.
• fn 0x04 plays an effect. Accepts 0x00–0x0E and 0x1B; everything
  else up to 0x3F answers INVALID_ARGUMENT. Sixteen ids but thirteen distinct
  sensations by hand — 0x00≡0x01 and 0x02≡0x03≡0x04. Options+ plays
  0x08 after a strength write and 0x00 after re-enabling haptics.
• Byte 1 of a play reply is a motor-busy flag, not a property of the effect.
  Playing one id from idle and again 120 ms after the longest effect answered
  0,0,0 then 1,1,1 for the same id.

0x2111 / 0x2121 / 0x2150 wheel settings

• 0x2111 carries three bytes in one write, so each setter reads the trio
  first. Byte 0 is the wheel's ratchet mode — the same thing the button behind
  the wheel toggles, and not SmartShift on/off. Byte 1 is the threshold,
  255 disabling SmartShift; proven by moving the Options+ sensitivity slider and
  watching only that byte follow (9% wrote 46, 75% wrote 15, mode fixed at 2).
• 0x2121 capabilities are [multiplier, flags]. Mode writes flip one bit and
  carry diversion through untouched — setting it routes the wheel to HID++ and
  stops it scrolling.
• 0x2150 invert support is the two-byte capability field at payload[4..5];
  this device answers 0x0003 there. Reading the single byte at payload[4]
  reports inversion unsupported on a device that demonstrably honours it.
• 0x2150 does not echo its write. Unlike 0x2111, 0x2121 and 0x19B0,
  the reply to fn 0x20 carries no payload, so a write is confirmed by
  re-reading fn 0x10. Confirming from the write reply reads the empty payload
  as "not inverted", which makes clearing inversion appear to succeed and
  setting it appear to fail while the device has applied both. Found on
  hardware.

0x0007 Device Friendly Name

fn 0x00 reports current and maximum lengths (11 of 14 here), fn 0x01 returns
the text headed by the requested offset, fn 0x03 writes it back. Names are
validated before any bytes go out, and the result is read back afterwards —
firmware that acknowledges a write and keeps its old value would otherwise look
like a successful rename.

0x1815 / 0x1814 Easy-Switch

0x1815 fn 0x00 answers [capabilities(2), hostCount, currentHost]. The two
leading capability bytes matter: reading the counts one byte earlier reports
eight slots on a device whose slots 3 and up refuse outright. This unit reports
three slots, two paired, sitting on slot 0.

requestHostSwitch(slot) follows the shape agreed in #1. It validates the slot
against HOSTS INFO first and resolves once the command reached the device —
either acknowledged, or having timed out because the mouse left before it could
answer. Disconnection is the expected success path, so the method promises
only that the switch was requested. A refusal from a mouse that is still present
is surfaced rather than mistaken for departure. An empty slot is refused: it
would leave the mouse unreachable until someone presses the button underneath.

What is deliberately not here

• 0x19C0 Force Sensing Button is dormant config, not a pressure stream.
  With a positive control proving the watcher live, it emitted nothing and its
  values never moved while the panel was pressed. The Actions Ring panel is an
  ordinary 0x1B04 control, cid 0x01A0, which Options+ diverts.
• Easy-Switch host names. 0x1815 fn 0x02 returns six non-text bytes per
  slot regardless of the reported name length — an address, not a label. The
  remaining function ids there are reportedly set-name, move and delete-host, and
  a blind call to the last would unpair one of the user's computers, so I stopped.
• 0x0020 Config Change. fn 0x00 reads a cookie and fn 0x01 writes it,
  proven by writing this device's original value back. It is a marker
  applications write to notice each other, not a notification from the mouse.
• 0x1701, 0x1602, 0x00D1 — present and flagged plain, unidentified.
  0x1701 has three functions answering 01 00 0A; 0x1602 takes no function
  with empty arguments; 0x00D1 returns an identical 00 81 92 01 plus twelve
  FF bytes on three separate functions. Recorded as unknown rather than guessed.
• Everything the firmware flags hidden or engineering — 22 of the 45 — was never
  probed.

Not present on this device, in case it saves a lookup: 0x2202,
0x8060/0x8061, 0x8100, 0x1001, 0x1F20, 0x6501.

Testing

• npm run check green: 352 tests, including new codec tests for every byte
  layout above and driver tests for the paths that cannot be exercised by hand.
• Host switching has fake-HID tests for both outcomes — the mouse
  acknowledging, and the mouse leaving before it can — plus a refusal from a
  still-present device, a report that never reaches the transport, and every
  rejected slot.
• OpenMouse builds and its full suite passes against a local install of this
  package.
• On hardware (MX Master 4 over Bolt): haptic strength across all four
  presets, both haptic flags independently, effect playback, wheel mode,
  SmartShift threshold and off, hi-res scrolling, scroll inversion, thumb-wheel
  inversion, rename with a round trip back to the original, and a host switch
  including the return trip via the button underneath.

One observation, not addressed here

getFeature performs a fresh root round-trip on every call, with 44 call sites
in the Logitech driver. A steady-state refresh on this device spends most of its
traffic there. I have cached what this PR adds — Easy-Switch state, the friendly
name and the wheel capability flags are read once per connection — but left
getFeature alone, since changing it affects every device and belongs in its own
change. Happy to open that separately if it would be welcome.

Unknowns and assumptions that remain

• 0x19B0 byte 0 bits 2-7: always zero here, purpose unknown, carried through.
• 0x19B0 fn 0x03 returns all zeros; unused on this firmware as far as I can tell.
• The 0x2111 capability reply 01 0A 4B 0E reads as a 10..75 threshold range.
  That is inferred from both observed Options+ values falling inside it, not
  confirmed.
• Haptic strength is accepted anywhere in 0..100; only the four preset values
  have been exercised.