RGB colour support: no capability can express a colour today

[gdevenyi]

The gap

CAP_LIGHTS is the only lighting capability, and it is strictly boolean — lib/capability_descriptors.hpp declares it min_value = 0, max_value = 1, -l <0|1>. There is no capability anywhere in CAPABILITIES_XLIST that can express a colour, so no device in the project can set one, however capable its hardware.

That's a real limitation for headsets whose selling point is RGB. Users install HeadsetControl to get off vendor software and find that the LEDs can only be switched on — and "on" has to mean whatever static colour the device implementation picked.

Why I'm raising it now

While adding support for the Corsair Virtuoso XT (#570) I reverse-engineered its lighting. The hardware side works: it speaks Corsair's Bragi protocol, and driving the lighting handle with a 9-byte planar RGB frame cycles the earcup zones through red, green and blue exactly as asked. I confirmed it visually on real hardware.

I deliberately did not ship that in #570, because there is nowhere in the API to put a colour. setLights(handle, bool) is all the interface offers, so my implementation paints static white for "on" and black for "off" — the hardware can do far more than the interface can ask for.

I doubt Corsair is alone here. Several already-supported families (Logitech G633/G933, SteelSeries Arctis, other Corsair devices) have addressable lighting that the current interface can't reach either.

The design questions

I'd rather agree the shape before writing anything, since this touches the shared plumbing rather than one device.

1. Extend CAP_LIGHTS, or add a separate capability?

Extending keeps one flag and one concept ("lighting"), and -l could accept either 0/1 or a colour. A separate CAP_LIGHTS_COLOR keeps the boolean semantics untouched and lets devices advertise the two independently — plenty of devices can toggle lighting but not colour, and the capability bitmask is how the README table and --capabilities are generated. I lean toward a separate capability for that reason, but it does add a second lighting flag.

2. Parameter representation.

There's already a precedent for non-scalar parameters: FeatureParam is std::variant<std::monostate, int, EqualizerSettings, ParametricEqualizerSettings>, and CAP_EQUALIZER sets min_value/max_value to nullopt with a <curve> value hint. A colour would follow the same pattern — a small LightingColor struct in the variant, with #RRGGBB / RRGGBB on the CLI.

3. Zones.

Most headsets have more than one LED zone (the Virtuoso has three). Is a single colour applied to all zones enough for v1, with per-zone left as a later extension? I'd argue yes — it covers the common request and avoids designing a zone-addressing scheme before there are multiple implementations to generalise from.

4. Effects.

Out of scope in my view. LightsResult already carries an optional mode string, but effects are where vendor protocols diverge hardest, and a static colour is the thing people actually ask for.

Surfaces this would touch

CAPABILITIES_XLIST and the capability enum, CAPABILITY_DESCRIPTORS, FeatureHandlerRegistry, FeatureParam, HIDDevice's virtual interface, both public APIs (headsetcontrol.hpp and headsetcontrol_c.h), the JSON/YAML/ENV serialisers, and the README table.

Offer

Happy to implement whichever shape you prefer, with the Corsair Virtuoso XT as the first implementation since I have the hardware and the protocol already worked out — it would give the feature a tested device from day one rather than landing untested. If you'd rather not take this on at all, that's a completely fine answer too, and I'll note the limitation in the device docs instead.

[Sapd]

Go ahead. Answers:

1. Separate capability. CAP_LIGHT_COLOR, --light-color RRGGBB (accept a leading # too). Singular, to match --light. Append at the end of CAPABILITIES_XLIST - never mid-list. headsetcontrol_c.h mirrors the enum by value and nothing checks they agree, which is how Added Rich Color Configuration #515 broke the C ABI. Add a static_assert(HSC_NUM_CAPABILITIES == NUM_CAPABILITIES) in headsetcontrol_c.cpp while you're there.

2. Struct in the variant, like the equalizer. LightColorSettings { uint8_t r, g, b; }. The device virtual takes const LightColorSettings&, not three bytes, so a zone field can be added later without touching signatures. Descriptor: min/max nullopt, value_hint <RRGGBB>. C API: hsc_set_light_color(h, r, g, b) - scalars, so the ABI doesn't move when zones arrive.

   I don't want a general ParamKind in the descriptor table for this. The rule is simpler: int is for scalars in a range, everything else is a typed struct in the variant. That covers colour and it's also the fix for Add Sony InZone H9 II  #569's bitmask.

3. All zones in v1. Keep the zone count private to the device. Per-zone later = optional zone in the struct, hsc_set_light_zone_color(), and a zone:RRGGBB CLI form. Turn off Microphone LED for Corsair Virtuoso (SE or other) #422 wants the mic LED off on this exact hardware, so that's the first per-zone use - don't build it, just don't foreclose it. 000000 must be valid; a device may treat it as off.

4. Effects out of scope, agreed. LightsResult.mode stays as is.

Interaction with -l: colour implies on. Both in one call - -l runs first in request order, colour last, so colour wins. Document it, no error. On the Virtuoso, if brightness 0x02 works the way ckb-next uses it (see #570), -l is the brightness switch and --light-color is the frame.

Output: add color: "#rrggbb" to the action object in JSON/YAML/ENV; value packs 0xRRGGBB. ActionData drops value when it's 0 (output_data.hpp:95), so black would vanish - fix that guard.

Also: test device implements it, a unit test for the hex parser, and a line in ADDING_A_CAPABILITY.md that new capabilities append only.