Logitech G522: port to Centurion, add lights, voice prompts and EQ

[thanosk]

Changes made

• Commit 1: ported Logitech G522 Lightspeed to the Centurion protocol.
• Lightly refactored G PRO X 2, because of the above bullet, but kept byte-identical traffic and behavior since I don't own it and can't test it.
• Introduced Centurion protocol behavior changes as opt-in option flags, G522 makes use of these new flags.
• G PRO X 2 would probably benefit from the exact_direct_length flag and the offline flags, perhaps a G PRO X 2 owner could test and enable them in the future to improve support as a courtesy, not a requirement.
• Offline detection and Timeout parity for G522.
• Shared battery parsing for both headsets.
• New Centurion feature: HeadsetMicMuteLed.
• Commit 2: add lights and voice prompts control for G522, also change behavior when setting timers, now respecting and not overwriting the current values of the timer "time until inactive" setting and the timer "time until off" setting.
• Commit 3: add equalizer presets and parametric EQ for G522.

Checklist

• I adjusted the README (if needed)
• For new features in HeadsetControl: I discussed it beforehand in Issues or Discussions and adhered to the wiki

Related to #488

[ChrisLauinger77]

I have the "G PRO X 2".
I take a look as soon as this is merged.

[thanosk]

Let me also post a more detailed description with the changes and explanations:

Changes made

The Logitech G522 LIGHTSPEED (046d:0b18) speaks the same Centurion protocol as the G PRO X 2. The only difference on the wire is the frame prefix: 50 23 instead of 51. This PR ports the G522 driver onto LogitechCenturionProtocol, then adds the features G HUB exposes. There are three commits in total.

1. Port to the Centurion protocol (no new features)

• LogitechCenturionProtocol gains a virtual centurionFramePrefix() (default {0x51}) and a CenturionOptions hook. Every option defaults to off:
  • exact_direct_length: correct length byte on direct (non-bridged) requests.
  • detect_connection_events: the bridge power event with "connected = 0" → DeviceOffline.
  • probe_offline_on_timeout: after a bridge ACK and then a timeout, query the bridge status. If no headset is connected → DeviceOffline.
  • lookup_features_by_id: resolve features with Root getFeature(id) instead of enumerating all ~36 features. This takes -b from about 0.75 s to about 0.08 s.
• The G522 enables all four options. The hand-built packet code (build*Command, is*Packet, parseBatteryResponse, which were public static) is replaced by Centurion requests.
• parseCenturionBatteryResponse() moves from the G PRO X 2 driver into the protocol class. The behavior is unchanged.

2. Lights, voice prompts, sidetone read-back, -i fix

• -l 0|1: lighting feature 0x0621. 0 sets a fixed black color, and 1 restores G HUB's default two-zone look. Colors are deliberately not exposed, so the CLI stays the same as for other devices. The setting is stored on the headset.
• -v 0|1: feature 0x060b. 0 means tones, not silence. You hear the difference on the BT/LIGHTSPEED switch. The setting is stored on the headset.
• Bare -s now reads the sidetone back (feature 0x0604, function 0). The device has 10 steps (0–9), so the value read back is rounded, e.g. -s 64 reads back as 56.
• -i used to reset the headset's two lighting timers ("dim after" and "lights off after") to "never". The auto-sleep write must carry all three timers (a 1-byte write is rejected), so -i now reads the current values first and only changes the sleep timer.

3. Equalizer presets, custom EQ and parametric EQ

• Playback EQ is feature 0x020d v2: a 3-byte header + 10 bands × freq_hi freq_lo Q gain_hi gain_lo.
  • Q = raw / 32.
  • Gain = (raw − 120) / 20 dB, so 0.05 dB steps within ±6 dB.
• -p 0..4: G HUB's built-in presets (Default, Bass Boost, Gaming, Gaming - FPS, Media). All 50 bands are byte-identical to the G HUB USB captures, and unit tests check this.
• -e g1,…,g10: 10 gains on the Default frequencies.
• --parametric-equalizer: up to 10 peaking bands. Missing bands fall back to Default, so reset restores Default.
• G HUB writes its own EQ preset to the headset when it connects. A preset set from HeadsetControl therefore stays until G HUB runs again.

Behavior changes for G522 users

• A headset that is switched off now reports "offline" instead of "Operation timed out".
• -i no longer clears the lighting timers.
• Battery state 1 is now reported as charging. This is the shared Centurion parser, the same as the G PRO X 2.
• While the headset charges over USB, the dongle reports no headset, so -b fails. The old driver also failed here (it timed out), so this isn't a regression.

G PRO X 2

Nothing changes on the wire. All new behavior is opt-in, and unit tests check that the G PRO X 2 frames are byte-identical with the default options (including the length byte of 65 on direct requests, and power events still being skipped). The G PRO X 2 would probably benefit from the same options, but I have no way to test that, so I left it to an owner of that headset.

Not included

• RGB colors and effects (kept to -l 0|1).
• Reading voice prompts back (function 0x40 returns the value, but there's no capability for it).
• Mic EQ (feature 0x0908).

Testing

• Unit tests: 45/45 protocol tests and ctest 2/2. Captured G HUB frames are used as fixtures for the lights, voice prompts, sidetone, auto-sleep, battery, power events, bridge status and all EQ presets.
• clang-format 18 is clean on the changed files.
• On a G522 on Linux:
  • -b
  • -s (set and read)
  • -i (the lighting timers are kept, checked by reading back)
  • --microphone-mute-led-brightness 0/1
  • -l 0/1, -v 0/1
  • -p, -e, --parametric-equalizer
  • headset off → offline

[ChrisLauinger77]

I tested the changes locally on my side - work like a charm (enabled the 4 flags)

[Sapd]

Verified the G PRO X 2 path: it overrides neither centurionFramePrefix() nor centurionOptions(), so it keeps the {0x51} prefix and all four flags off - the shipped traffic is master's. Its diff is format reflow plus parseCenturionBatteryResponse moved verbatim. Nothing else inherits Centurion. Build, tests, clang-format 18 and the README generator are clean.

@ChrisLauinger77 to be clear: "enabled the 4 flags" means you ran the PRO X 2 with the options on, which isn't what this PR ships by default. Did you also run it unmodified, and which commands - -b, -s, -i, -p, -e, --parametric-equalizer, and -b with the headset off?

Keeping the flags off here is right, it's what makes "PRO X 2 untouched" checkable. If all four work on the PRO X 2 I'd take a follow-up that turns them on there and deletes CenturionOptions - exact_direct_length=false only exists to preserve a wrong length byte (0x41 in a 64-byte frame).

Nits: sort the CenturionFeature enum numerically, HeadsetMicMuteLed 0x0601 went in before 0x060b while 0x0604 stays last. Wire tests for G522 setSidetone and the mic-mute LED would pin the bytes that moved from hardcoded indexes to discovery.

For the release notes: battery state 1 now counts as charging, -i no longer zeroes the lighting timers, headset off returns DeviceOffline instead of a timeout.