[gdevenyi]

Changes made

The Virtuoso XT/SE turns out to speak Corsair's Bragi property protocol — the same one corsair_void_v2w.hpp already uses — just framed on HID report 0x02 of the vendor collection (Usage-Page 0xff42) instead of an unnumbered report. Reworking the device around that protocol replaces the single battery command with the documented property table and adds three capabilities:

Capability	How
CAP_SIDETONE	property 0x46 (enable) + 0x47 (volume, 0–1000 in steps of 10)
CAP_INACTIVE_TIME	property 0x0d (enable) + 0x0e (timeout in ms)
CAP_LIGHTS	brightness property 0x02 — 0 or 1000

Packet framing — [0] report ID 0x02, [1] target, [2] command (0x01 SET / 0x02 GET), [3] property, [5..] little-endian value. Replies come back on report 0x01 with the status in [3] (0x00 ok, 0x05 no such property, 0x09 write refused).

Software mode. Writes are refused with status 0x09 unless the headset is switched into software mode (property 0x03 = 2). Every write — lights included — is bracketed by an RAII guard that hands the headset straight back to hardware mode.

Lights follow ckb-next's updatergb_bragi(): brightness is the headset's own persisted setting and gates whatever effect it runs, so -l 0 writes 0 and -l 1 writes 1000. The user's own lighting effect comes back on -l 1, and off survives a power cycle. Setting a colour is a separate capability, in #572.

Wireless vs wired. A receiver relays commands to the headset paired with it (target 0x09); a wired headset answers for itself (target 0x08). Asking the wrong one is silent rather than an error. The registry shares one instance across product IDs and only records the ID it last matched on, so the product ID is used as a hint and then confirmed against the device — without that, a receiver and a wired headset plugged in at the same time break each other. (Plugging the USB-C cable into a Virtuoso XT doesn't just charge it; the headset re-enumerates as the wired product ID.)

Battery now reads BRAGI_BATTERY_LEVEL (0x0f, tenths of a percent) and reports charging from BRAGI_BATTERY_STATUS (0x10). The command 4.1.0 ships, { 0x02, 0x00 }, is a report ID and a target with no command or property, and the byte it prints is a constant 0x3b = 59 — which is why every report of this headset reads exactly 59%. Properties 0x11 and 0x12 decoding to exactly 0x1b1c and 0x0a62 confirm the property numbering matches ckb-next's Bragi table.

Testing

On a Virtuoso XT, in both wireless (0x0a64) and wired (0x0a62) modes:

• battery level and charging state, cross-checked against the charge cable
• sidetone across its range and off, inactive time set/disabled/restored, lights off/on — each verified by reading the property back, with mode confirmed back at hardware (1) after every write
• lights confirmed visually: off stays off in hardware mode, on restores the headset's own effect rather than white
• sidetone, sleep timer and brightness 0 all read back unchanged after a power cycle (confirmed as a real re-enumeration)
• a receiver with its headset on the cable reports offline rather than a bogus reading

The SE product IDs (0x0a3e, 0x0a3d) are untested here — that's gated on #568's author running this branch on his SE.

Out of scope

iCUE's equalizer and spatial audio are host-side DSP applied to the PC audio stream rather than device settings, so they aren't reachable from a HID tool. Light colour is #572.

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

Existing capabilities on a device that already had an entry, so no new feature to discuss.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BHCVMmAAeV5WGP7oYZsk3T

[Copilot]

🟡 Changes recommended

The updated device header introduces at least one build-breaking include issue and a behavior in setLights(false) that can leave the device stuck in software mode with undesirable side effects.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR reworks the Corsair Virtuoso XT/SE device implementation to use Corsair’s Bragi property protocol on the vendor HID report, expanding support beyond battery reporting to additional device capabilities.

Changes:

• Reimplemented Virtuoso XT/SE communication using Bragi property GET/SET framing and reply filtering.
• Added support for CAP_SIDETONE, CAP_INACTIVE_TIME, and CAP_LIGHTS, including software-mode bracketing for persistent settings writes.
• Updated README capability matrix and Corsair sidetone note to reflect XT/SE behavior.

File summaries

File	Description
README.md	Updates device capability table and Corsair sidetone guidance for Virtuoso XT/SE.
lib/devices/corsair_virtuoso_xt.hpp	Implements Bragi protocol framing, target resolution, and adds sidetone/lights/inactive-time capabilities (plus battery read rework).

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[gdevenyi]

Opened #572 in Ideas to discuss RGB colour support, since the Virtuoso XT's lighting hardware does full RGB (I cycled the zones red/green/blue while reverse-engineering it) but no capability in the project can express a colour. This PR stays as-is — static white for -l 1 — until there's a shape agreed there.

[Sapd]

Taking this one. The battery rework fixes a real bug. What 4.1.0 ships is

{ 0x02, 0x00 }

• report ID and target, no command, no property. The byte we print is 0x3b = 59, which is why #567's reporter and the author of #568 both got exactly 59%. 0x0f is what corsair_void_v2w.hpp reads too.

#568 is the same protocol. Closed it and asked its author to run this branch on his SE - that's the gate for the SE PIDs. CI is green.

Blocking:

1. PROP_BRIGHTNESS = 1000 is written unconditionally (line 238), before the on/off branch. -l 0 sets brightness to max and then paints black. On Corsair's other Bragi devices 0x02 is the persisted hardware-mode brightness, so this likely also overwrites whatever the user set in iCUE.

   Compare ckb-next led_bragi.c updatergb_bragi(): it writes 0x02 = 0 when the frame is all black and 1000 otherwise - "being able to just switch them off even in hw mode is really nice". I think that's the whole feature for a boolean: -l 0 = software mode, brightness 0, guard back to hardware mode; -l 1 = brightness 1000. Off survives a power cycle, on brings back the user's own effect instead of static white, and the headset is never left in software mode. Please test that on the XT. If it holds, drop writeLighting() from this PR - it comes back with #572.

2. Header (46-49) and the setLights comment state the idle drop-back as fact. Measured on one XT - say so.

Minor:

• resolveTarget() reads 0x0f and getBattery() reads it again. Return the probed value.
• 300 ms probe: a headset slower than that is reported offline, and its late reply is the first thing the next readReply() sees - there's no property echo to catch it. Worth a comment.
• writeLighting(): ckb-next closes and reopens on open status 0x03. Only relevant if the frame path stays.
• Sidetone: checked it survives a power cycle, or only the mode switch?

Replied on #572.

[gdevenyi]

Thanks — all addressed in 9f54a74, added as a new commit rather than a force-push so the delta is reviewable.

1. Brightness. Your design holds on the XT. -l is now software mode → brightness 0 or 1000 → guard back to hardware mode, and writeLighting() is gone from this PR. Tested visually and by readback, over both wired and wireless:

• -l 0: LEDs go off and stay off in hardware mode; mode reads back 1.
• -l 1: LEDs come back showing the headset's own effect, not white. I checked this straight after a power cycle, so nothing left over from the old frame implementation could be showing.
• Brightness 0 survives a power cycle — lights still off afterwards, and 0x02 reads back 0.

I should own why I didn't land on this myself: last session I had "evidence" that brightness doesn't gate the LEDs in hardware mode. Going back through it, two of the three runs crashed before writing anything (the hidraw node had moved when the headset changed transport), and the one that did run never entered software mode, so every write was refused. My probe also wasn't matching the command echo, which is why it "restored" brightness to 35500. It was worthless, and your reading of updatergb_bragi() was right.

2. Measured on one XT. The header no longer mentions the idle drop-back at all — nothing depends on it now that lights restore hardware mode. The guard's comment says it was seen on one unit and not relied on, and the power-cycle persistence is attributed the same way.

Minor:

• resolveTarget() now returns the level it probed; getBattery() doesn't read 0x0f twice.
• 300 ms probe: commented on both halves — a slower headset is reported offline, and since replies carry no property ID, its late reply can be taken by the next read for the same target and command.
• writeLighting() close/reopen on open status 0x03: moves with the frame path into the RGB colour support: no capability can express a colour today #572 PR, and I'll implement it there.
• Sidetone survives a power cycle. I set sidetone 780/1000, sleep 20 min and brightness 0, power-cycled (USB device number changed, so it genuinely re-enumerated), and all three read back unchanged. Restored afterwards.

[gdevenyi]

One more commit here, 8feff12, from Copilot's review of the stacked #580. Both findings were in code this PR introduces:

• Late replies are now discarded instead of documented. Replies carry no property ID, so a reply that outlived its request's timeout could be taken by the next request of the same kind. Every request now goes through transact(), which throws away anything already queued before writing. This replaces the comment added for your 300 ms probe point.
• resolveTarget() no longer turns every probe failure into "offline". Silence and "no such property" (a receiver answering for itself with no headset paired) still mean wrong target; a HID write failure or an unexpected status is returned.

Both come with mock tests in a new tests/test_corsair_virtuoso.cpp, whose mock makes each report readable only after a given number of writes so a stale reply can be modelled. Each test fails with its fix reverted. Checked on the XT over wireless: battery, sidetone, sleep timer and lights all read back.

[Sapd]

SE results came in on #568 from @zoeyronain, who has the hardware - worth reading, you weren't tagged.

Good: battery reads 96% wired and through the receiver, 97% charging, and they confirmed it dropping over a few hours. So the Bragi battery fix is verified on both SE PIDs.

Not good: -s does nothing on the SE. alsamixer shows the sidetone control pinned at 10 whether they set 64 or 0. This PR advertises CAP_SIDETONE for 0a3e/0a3d, and it also rewrites the README note to say the XT/SE are the Virtuosos that don't use the ALSA mixer for sidetone - their screenshot suggests the SE does.

Two asks: gate CAP_SIDETONE on the XT PIDs unless you can explain the SE result, and recheck that README note.

Also their lights test was 2026-09-11, so it was the old painted-frame code. Brightness-as-switch is still unverified on SE.

[zoeyronain]

@Sapd do you want me to test the latest code for the lights?

[zoeyronain]

wireless:

wired

[Sapd]

@zoeyronain thanks for testing.

Wireless alone looks right: battery 90% with BATTERY_CHARGING detected, -l 1 and -l 0 both succeed.

With the cable and the receiver both plugged in, everything fails:

0x0a3d (wired SE)  Error: [battery] Protocol error
0x0a3e (receiver)  Error: [battery] Device is offline or not responding

Same for -l 1.

@gdevenyi the receiver reporting offline is presumably right - you noted the headset re-enumerates as the wired PID when the cable goes in, so nothing is paired to it. The wired SE returning a protocol error is the problem, and that's the case resolveTarget() exists for. Note 8feff12 is what surfaced it - before that it would have come back as "offline" and looked like ordinary absence.

Still open from my last comment: -s does nothing on the SE (alsamixer pinned at 10), while this PR advertises CAP_SIDETONE for 0a3e/0a3d and rewrites the README note to say the XT/SE are the Virtuosos that don't use the ALSA mixer.

[Sapd]

Correcting myself: the wired SE is a regression from 8feff12 / 9f54a74, not something they surfaced.

@zoeyronain tested the same branch on 2026-09-11 (screenshots in #568, now closed). Both devices plugged in, before those two commits:

0x0a3d (wired SE)  BATTERY_CHARGING, 96%
0x0a3e (receiver)  offline

and -l 1 / -l 0 both reported success on 0x0a3d. On 2026-09-22, same setup, 0x0a3d returns a protocol error. So it worked - battery and lights - and broke between the two.

My guess is resolveTarget(): it now returns any unexpected status as a hard error instead of falling through to the other target, so a reply that used to mean "wrong target, try 0x09" aborts the call.

The receiver reporting offline is the same in both runs and is correct, nothing is paired to it once the headset re-enumerates on the cable.

Also from #568, J-eremy on 2026-09-03: "the headset wired uses a completely different protocol". That sits oddly with his 2026-08-28 note that the wired SE does speak V2W on endpoint 0x08. Both are in that thread.

Still open: -s does nothing on the SE while this advertises CAP_SIDETONE for 0a3e/0a3d.

Further SE testing should go here, #568 is closed.

[gdevenyi]

Both open points are addressed in 125fb7c. I also merged master in (d9d4832); the only conflict was the README table.

Wired SE regression: you're right that it came from 8feff12, and my claim there that "only two probe failures mean wrong target" was wrong. On the target it doesn't use, a wired SE answers in a way that comes out as a protocol error instead of staying silent. An XT stays silent, which is why I never saw this. With both the cable and the receiver plugged in, my XT returns charging on 0a62 and offline on 0a64, before and after this change. So the SE behaves differently, and I can't reproduce it here.

resolveTarget() now tries the other target after a protocol error too, and keeps the error. If neither target answers, the protocol error is what gets returned rather than "offline", so a real fault still isn't hidden. HID errors still fail at once without trying the other target. Two new mock cases:

• wired SE PID, 0x08 answers with status 0x09 and 0x09 answers OK → battery succeeds, and the follow-up request goes to 0x09. This fails with the fix reverted.
• both targets give a protocol error → ProtocolError, not DeviceOffline.

Sidetone: CAP_SIDETONE is now advertised for 0a64/0a62 only, following the Nova 7 pattern. I think the explanation is this: the XT has no ALSA sidetone control at all. amixer contents on both of my XT cards shows only PCM playback and headset capture. The SE's alsamixer screenshot shows one, so the SE must handle sidetone differently, and I have no evidence the Bragi properties do anything there. The README shows sidetone as x* with a footnote, and the ALSA note now reads "Virtuoso other than the XT", so the SE is back in it.

@zoeyronain, could you run this branch again with the cable and the receiver both plugged in? Please use -o json so the error message is visible (the plain output only says "Protocol error"):

headsetcontrol -b -o json
headsetcontrol -l 0
headsetcontrol -l 1

With the fix, the wired SE should report battery again. For the lights, please watch the headset: -l 0 should turn the LEDs off, and -l 1 should bring back the headset's own effect, not white. Your earlier lights test was the old painted-frame code, so brightness as the on/off switch is still untested on an SE.

[Sapd]

Both fixes check out here.

• Deleting the ProtocolError branch fails "a protocol error on one target should fall through to the other"; dropping the sidetone gate fails "the SE should not advertise sidetone". The gate matches the Nova 7 pattern and --readme-helper walks the product IDs, so x* is generated rather than written by hand.
• The whole README table matches the generator, not just your row, so the conflict resolution in d9d4832 is clean.
• The extra probe can't pick up the first target's late reply: transact() runs discardStaleReports() before every request. That was my worry with the fallthrough and 8feff12 already covers it.
• Sidetone explanation is plausible and the capability is off for the SE either way, so it costs nothing if it's wrong.

One thing your own mock says that your comment doesn't: the wired SE answers on 0x09 and refuses on 0x08, so for 0a3d the wired -> TARGET_SELF hint is backwards and the probe always pays for it. If zoeyronain confirms, hint 0x09 for the wired SE. Not blocking. It also clears up J-eremy's "completely different protocol" - a V2W endpoint and a Bragi target aren't the same thing, so his two notes never conflicted.

What's left is the SE, and only the lights. Brightness-as-the-switch has never run on one - zoeyronain's lights test was the painted-frame code - and brightness 0 persists, so an SE where -l 1 doesn't take leaves someone with dark LEDs and nothing in HeadsetControl to undo it. That's the one case I don't want to ship untested.

If zoeyronain doesn't get back to it I'll take this on the XT evidence: battery on the SE worked before the regression and 125fb7c puts it back, so lights would be the only thing going in unverified. Say so and I'll merge.

[zoeyronain]

headsetcontrol -b -o json:

Works

Lights wireless then wired

Works

Battery levels wired and wireless do change:

and if I try to adjust sidetone:

"What's left is the SE, and only the lights. Brightness-as-the-switch has never run on one - zoeyronain's lights test was the painted-frame code - and brightness 0 persists, so an SE where -l 1 doesn't take leaves someone with dark LEDs and nothing in HeadsetControl to undo it. That's the one case I don't want to ship untested."

Let me know how to check that, provided I can set it in OpenLinkHub and have it work in headset control still. just set the color on OLH, then turned it off and on in headset control and it's back to the default color.

[gdevenyi]

@zoeyronain thanks, that covers everything that was left.

• Battery: the wired SE reports BATTERY_CHARGING 99% again with the receiver plugged in too, and the receiver reports offline, which is correct. Wireless alone reads 98%. So 125fb7c fixes the regression on real hardware.
• Lights: -l 0 then -l 1 on both the receiver and the wired SE, and the LEDs came back. That is the brightness-0-and-back case Sapd didn't want to ship untested.
• Sidetone: no longer advertised on the SE, as intended.

About OpenLinkHub: getting the default color back is expected. As far as I can tell OpenLinkHub drives the LEDs in software mode, and HeadsetControl puts the headset back in hardware mode afterwards, so you see the effect stored on the headset rather than OpenLinkHub's color. Lights off and back on is all this PR does, so nothing more is needed for it.

@Sapd your hint point is in 99b8d48. The working battery read settles it: under 8feff12 the protocol error came from the first target tried, which was 0x08, and now that the code moves on to 0x09 the read succeeds. So the wired SE is addressed on 0x09 first, and only the wired XT uses 0x08. The fallthrough tests now use a stale wired-XT hint to get the refusal on 0x08, and there's a new case checking that the wired SE is probed on 0x09 first, with a single probe. That case fails with the old hint. Suite green, clang-format 18 clean.

From my side this is ready.