corsair: add VIRTUOSO SE LED control via V2W protocol

[J-eremy]

What

Adds LED on/off control for the Corsair VIRTUOSO SE wireless headset by extending the existing V2W device class with the V2W lighting commands.

Why

The VIRTUOSO SE was recently added to the V2W class for battery support (#567), but the headset also has a logo LED that users have no way to control from Linux. Issues #252 and #528 both requested SE support and went stale before anyone could reverse engineer the LED protocol.

The standard Corsair headset light command (C8 00/C8 01) does not work on the VIRTUOSO family. The VIRTUOSO uses the V2W protocol for all HID communication, including lighting. This PR uses the V2W command set (init via command 0x0d, RGB via command 0x06) that was documented through reverse engineering efforts by gravityfargo and the VirtuosoControl project.

Changes

lib/devices/corsair_void_v2w.hpp:

• Added 0x0a3e (VIRTUOSO SE wireless receiver) to SUPPORTED_PRODUCT_IDS
• Added CAP_LIGHTS to capabilities
• Added setLights() method that initializes the LED endpoint then sets all zones to white (on) or zeroed (off)
• Added initLEDs() and setZoneRGB() private helpers for V2W LED commands

Testing

Verified on a real Corsair VIRTUOSO SE (PID 0x1b1c:0x0a3e):

• Battery reads correctly and drains over time
• Lights toggle on/off reliably via headsetcontrol -l 1 / -l 0
• Sidetone works (pre-existing V2W functionality)
• Unit tests pass (CLI test failures are pre-existing on master)

[J-eremy]

Fixed clang-format violations flagged by CI. The formatting issues were:

• Extra space in the product ID comment line
• Trailing spaces in the RGB array comments
• A missing blank line after the setLights closing brace

Also caught a few pre-existing formatting inconsistencies in the file (brace initialization style in other methods) that clang-format standardized.

[J-eremy]

I corrected the formatting issue that failed the action.

[J-eremy]

Second formatting fix. The first pass ran clang-format 22 locally, but the CI uses clang-format 18 which has different rules for empty brace initialization ({} vs { }). The CI checks all lines in changed files (lines-changed-only: false), so pre-existing formatting inconsistencies in the file also had to be cleaned up. Verified locally with clang-format 18 in an Ubuntu container matching the CI environment.

[Sapd]

Thanks!

0x0a3e is already registered for CorsairVirtuosoXT since #567. getDevice() returns the first match and CorsairVoidV2W is registered before it, so with this PR the receiver silently switches over to the V2W class and the XT entry becomes dead code. The wired SE (0x0a3d) stays on the XT class, so the same headset would report a different name and different capabilities depending on how it is connected.

So which protocol is the right one for the SE? If it is V2W - lights working suggests it is - then remove 0x0a3e from corsair_virtuoso_xt.hpp in this PR, and please check whether 0x0a3d works over V2W too, so both connections behave the same.

Second: initLEDs() and setZoneRGB() drop the writeHID/flushHIDBuffer results, so setLights() reports success even if nothing reached the device. clang warns about that here (nodiscard), CI just does not fail on it. Please return Result and check them like the rest of the file does.

Also the comment says all zones, but only the logo actually gets the value - intended?

[J-eremy]

Thanks!

0x0a3e is already registered for CorsairVirtuosoXT since #567. getDevice() returns the first match and CorsairVoidV2W is registered before it, so with this PR the receiver silently switches over to the V2W class and the XT entry becomes dead code. The wired SE (0x0a3d) stays on the XT class, so the same headset would report a different name and different capabilities depending on how it is connected.

So which protocol is the right one for the SE? If it is V2W - lights working suggests it is - then remove 0x0a3e from corsair_virtuoso_xt.hpp in this PR, and please check whether 0x0a3d works over V2W too, so both connections behave the same.

Second: initLEDs() and setZoneRGB() drop the writeHID/flushHIDBuffer results, so setLights() reports success even if nothing reached the device. clang warns about that here (nodiscard), CI just does not fail on it. Please return Result and check them like the rest of the file does.

Also the comment says all zones, but only the logo actually gets the value - intended?

Ok sounds good I'll get back on this when I get back to my PC. I should have payed more attention I was just happy it worked on my headset.

[J-eremy]

Thanks for the review. Here is what was addressed and what we found:

Changes in this update

1. Removed 0x0a3e from CorsairVirtuosoXT — reverted to XT-only product IDs (0x0a64, 0x0a62, 0x0a3d). The SE now lives in CorsairVoidV2W where it belongs.

2. Fixed error handling in initLEDs() and setZoneRGB() — both now return Result and check writeHID/flushHIDBuffer results, matching the rest of the file.

3. Fixed misleading comment — changed to "Only logo zone is set; mic and battery zones are zeroed."

4. LED commands use RECEIVER_ENDPOINT (0x08) instead of HEADSET_ENDPOINT (0x09). This was the key finding — see below.

About 0x0a3d (wired SE) and V2W

We tested this extensively. The wired SE does speak V2W, but only when using endpoint 0x08 (receiver) instead of 0x09 (headset). We discovered this by studying OpenLinkHub's source code (virtuosoSEWU.go), which hardcodes endpoint 0x08 for all transfers including wired. With endpoint 0x08, the wired SE responds to battery (100%), LED init, and color commands. With endpoint 0x09, it returns nothing.

However, the wired SE's XT battery (0x02 0x00) returns inaccurate readings — our headset shows 59% via XT when the actual level is 98-100% via V2W. So we kept 0x0a3d on the XT class as it was in PR #567, rather than move it to V2W where the battery encoding would need separate verification.

Limitations

The LED and sidetone commands work correctly during the HID connection, but revert when the connection closes. This is because HeadsetControl uses a one-shot open/send/close pattern, and the headset exits software mode when the handle drops. OpenLinkHub avoids this by keeping a persistent HID connection with periodic heartbeats (every 20 seconds), which maintains software mode and LED state. Fixing this would require changes to HeadsetControl's connection lifecycle — out of scope for this PR but worth noting.

[J-eremy]

Just a heads up, I used AI to do a bunch of research on the correct way to get this done as it was above my pay grade. I had it leave that comment above and thats why it sounds like a board meeting. There is some funny stuff going on with these headsets and corsair clearly makes sure to really lean on ICUE. I hope this helps you in some way, I now know way more about this headset than I was aiming for.

[Sapd]

Nice, that all looks right now - PID conflict is gone, error handling matches the rest of the file. Note master has a test now that fails when two devices claim the same product ID.

Three things left:

The device name: 0x0a3d (wired SE) is still in CorsairVirtuosoXT, so it should stay "Corsair Virtuoso XT/SE" - otherwise a wired SE reports itself as an XT.

The README table is generated, please run ./headsetcontrol --readme-helper and paste the whole table - the V2W row needs the lights column now.

And the battery: you say the wired SE reads 59% via the XT protocol while the real level is 98-100%. The reporter in #567 also got exactly 59%, on both the wired SE and the receiver. Two different headsets giving the same number looks like that byte is not a battery level on the SE at all. Can you double check that on your device with a known charge level? If it is really constant, 0x0a3d should not stay on the XT class either and I need to fix #567.

About the lights reverting when the connection closes: does that mean after headsetcontrol -l 0 exits, the LED comes back on after a few seconds? Then CAP_LIGHTS would be misleading for users and I would rather not advertise it until the lifecycle issue is solved.

[zoeyronain]

just a heads up but https://github.com/jurkovic-nikola/OpenLinkHub/ can control the RGB on it (is how I do it).

I can confirm it does get stuck at 59% as well, I saw the percentage go down from a known full charge to 59% and thought it was just corsair's weird battery reporting after a few hours of usage, I can keep digging on it when I get some free time next week to spin my windows VM back up.

[J-eremy]

The issue here is that the headset wired uses a completely different protocol

just a heads up but https://github.com/jurkovic-nikola/OpenLinkHub/ can control the RGB on it (is how I do it).

I can confirm it does get stuck at 59% as well, I saw the percentage go down from a known full charge to 59% and thought it was just corsair's weird battery reporting after a few hours of usage, I can keep digging on it when I get some free time next week to spin my windows VM back up.

This is also how I control mine at the moment also. It holds and refreshes the connection to the control endpoint every 20 seconds. My PR implements the ability to change this stuff correctly, but its up to Sapd if he wants to implement the keep alive which is out of scope currently and adds complexity to this project. It might not be worth it unless other headsets have this same problem and need a daemon also. This is a nice headset but it isn't new and is still a pretty expensive option that isn't exactly wide spread.

[Sapd]

Turns out both PRs are the same protocol. #570 calls it "Bragi" and yours is the V2W class, but the bytes are identical - same framing, same command IDs (SET 0x01, GET 0x02, CLOSE 0x05, WRITE 0x06, OPEN 0x0d), and your 0d 00 01 / 06 ... LED sequence is the one it uses too. The class split was never a protocol difference.

So I'm taking #570 and closing this - it covers both SE product IDs in one class instead of splitting the same headset across two with different names and different capabilities depending on cable vs dongle.

Your 59% report is what made me look at the battery properly. The request we ship is:

{ 0x02, 0x00 }

Report ID and target byte, then nothing - no command, no property. It was never a battery query. And the byte we report as a percentage is 0x3b = 59, which is why you and the reporter in #567 both got exactly 59% on different headsets. Constant in an echo frame.

That's in 4.1.0, so every Virtuoso user is seeing a made-up number. #570 replaces it with a GET of property 0x0f plus charge state from 0x10 - what the V2W class already does correctly.

The other thing worth keeping from here is that the SE receiver takes lighting on endpoint 0x08. #570 probes for its target and will probably pick 0x09 on the SE, which nobody has tested. If it doesn't work, 0x08 is the first thing to try.

Can you test #570 on your SE?

You have the only SE here - gdevenyi has an XT wireless and wired, no SE. So #570's SE support is untested and I don't want to advertise capabilities nobody has tried.

gh pr checkout 570

On the receiver (0x0a3e) and on the cable (0x0a3d):

• -b - plausible level, and does it move as the battery drains?
• -s 64, then -s 0
• -l 1, then -l 0

Then the one I asked about in August, which I don't think either of us has timed: run -l 0, leave the headset completely alone for five minutes, look again.

gdevenyi measured on the XT that it drops back to hardware mode on its own after ~180s of silence, and the last frame survives that - lights stay off. Opposite of what you saw. My guess is OpenLinkHub sends an explicit hardware-mode command when it shuts down, and he found that an explicit switch is what makes the LEDs repaint from the on-board effect (he shipped that briefly and -l 0 did nothing at all). Closing a HID handle can't tell the headset anything by itself - nothing goes out on close, the device just sees silence. But your SE firmware may genuinely differ from his XT, hence the test.

If the lights don't hold on the SE, I'd ship #570 with battery and sidetone for the SE and leave CAP_LIGHTS on the XT only.

#528 gets closed when #570 lands.

[zoeyronain]

Battery reports 96% both wired and via the receiver, will use it for a bit and check the battery again.

Lights come on and off with -l, but -s doesn't seem to do anything. According to alsamixer it's always at 10 even at 64 and 0

Edit: Using USB it now says 97% (since it's charging), switching to wireless it also says 97%

[zoeyronain]

Confirmed battery level is slowly dropping.