Add CAP_LIGHT_COLOR (--light-color RRGGBB), with Corsair Virtuoso XT/SE support

[gdevenyi]

Implements light color support as agreed in #572.

Stacked on #570. The Virtuoso commit builds on it, so #570's commits (and merges of master and #570) show up in this diff until #570 lands; I'll rebase onto master then. The new work is the last two commits: Add CAP_LIGHT_COLOR (plumbing, reviewable on its own) and corsair_virtuoso_xt: implement light color.

Changes made

Following your answers in #572, point by point:

1. Separate capability. CAP_LIGHT_COLOR, CLI --light-color RRGGBB with a leading # accepted, appended at the end of CAPABILITIES_XLIST and of CAPABILITY_DESCRIPTORS. headsetcontrol_c.cpp now static_asserts the C enum against the C++ one — I went a little further than the count check you asked for and expanded CAPABILITIES_XLIST to assert every entry by name, plus the count. Deleting HSC_CAP_NOISE_FILTER from the header (the Added Rich Color Configuration #515 shape) fails the build with hsc_capability_t out of sync with capabilities: CAP_SIDETONE_STATUS; dropping the new entry fails with count differs.
2. Struct in the variant. LightColorSettings { uint8_t r, g, b; } in FeatureParam; HIDDevice::setLightColor(hid_device*, const LightColorSettings&); descriptor min/max nullopt, value hint <RRGGBB>. C API is hsc_set_light_color(h, r, g, b), C++ is Headset::setLightColor(). The int-vs-struct rule is written down in ADDING_A_CAPABILITY.md.
3. All zones. Zone count stays private to the device. 000000 is valid (on the Virtuoso it goes dark).
4. Effects untouched; LightsResult.mode as is.

-l with --light-color: the color request is last in the request table, so it runs after -l and wins. Documented in --help, the README usage section, and at the request table.

Output: actions carry color: "#rrggbb" in JSON, YAML and ENV, and value packs 0xRRGGBB. The value > 0 guard wasn't only in output_data.hpp — YAML and ENV each had their own inline copy, so fixing the one line would still have lost black in two formats. The rule now lives once in ActionData::hasValue(). It still omits 0 for other actions, since the equalizer returns success(0) to mean "no value"; -l 0 output is unchanged. api_version goes to 1.6 for the new field, since 4.1.0 shipped 1.5.

Also: test device implements it; ADDING_A_CAPABILITY.md says new capabilities append only and must be mirrored in the C header; LIBRARY_USAGE.md, ADDING_A_DEVICE.md and AGENTS.md list the capability (plus noise filter and sidetone status, which those lists had already missed); README table regenerated with --readme-helper.

Corsair Virtuoso XT/SE

-l stays the brightness switch from #570; --light-color paints the frame through handle 0 / resource 1. Checked on the XT:

• Close and reopen on open status 0x03, as in ckb-next. The XT does return 0x03 for an already-open handle; with the lighting handle deliberately left open, --light-color still succeeds and leaves it closed. The handle is also closed when the frame write fails.
• Brightness gates frames too — a green frame stays dark at brightness 0 and shows at 1000. So a color raises brightness ("color implies on"), and -l 0 --light-color 00ff00 ends up green.
• Restoring hardware mode replaces the frame with the headset's own effect immediately, so a color write stays in software mode. That makes -l 1 the way back to the user's effect.

One limitation you should weigh: on this headset the color is temporary. With nothing talking to it, the headset drops back to hardware mode by itself — still in software mode 45 s after --light-color, back in hardware mode by 90 s — and its own effect returns. OpenRGB's Bragi controller refreshes every 30 s for the same reason, and its hardware-mode write is commented out.

I looked for a way to store a hardware-mode color. A read-only sweep of every 16-bit property and resource ID on the XT found 33 properties and 6 resources, all below 0x100. The only plausible stores are resources 0x14 (6 bytes) and 0x2a (5 bytes), and both refuse reads — so their contents can't be backed up, and I didn't write to them. A capture of iCUE setting hardware lighting would be the safe way to find out, if iCUE offers that for this headset. The limitation is stated in the device header and in a README note.

If you'd rather not advertise a color that lasts about a minute, dropping the last commit leaves the plumbing standing on the test device alone.

Testing

• Unit suite green; clang-format 18 clean over every changed file.
• New tests: the hex parser; ActionData's value rule; the C and C++ API through the test device; CLI output in every format, including black and -l ordering. Reverting hasValue() to value > 0 fails the ActionData test, and doing so only in the YAML writer fails the CLI test.
• Virtuoso mock tests (tests/test_corsair_virtuoso.cpp): a failed color write restores hardware mode while a successful one stays in software mode; stale replies are discarded; probe errors are propagated.
• Hardware, through the CLI and confirmed visually: wired (0a62) — green after -l 0 in the same call, 000000 goes dark, -l 1 restores the headset's own effect; wireless (0a64) — magenta.

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 — RGB colour support: no capability can express a colour today #572

🤖 Generated with Claude Code

https://claude.ai/code/session_01BHCVMmAAeV5WGP7oYZsk3T

[Copilot]

🟡 Changes recommended

Unresolved moderate findings remain in API versioning and Virtuoso error and connection handling.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds CAP_LIGHT_COLOR with CLI, C/C++ APIs, serialization, documentation, tests, and Corsair Virtuoso XT/SE support.

Changes:

• Adds RGB parsing, capability plumbing, and public APIs.
• Implements color output across JSON, YAML, and ENV.
• Adds Corsair lighting control and test coverage.

Unresolved findings concern API versioning and Virtuoso error, cleanup, connectivity, and target-resolution handling.

File summaries

File	Summary
tests/test_utilities.cpp	Tests RGB parsing
tests/test_output_formats.cpp	Tests color and value serialization
tests/test_library_api.cpp	Tests C/C++ APIs
tests/test_cli_output.cpp	Tests CLI output and ordering
README.md	Documents color support and device behavior
lib/utility.hpp	Declares the color parser
lib/utility.cpp	Implements color parsing
lib/result_types.hpp	Adds light color result types
lib/headsetcontrol.hpp	Adds the C++ color API
lib/headsetcontrol.cpp	Implements the C++ color API
lib/headsetcontrol_c.h	Adds the C API and capability enum
lib/headsetcontrol_c.cpp	Implements the C API and enum checks
lib/feature_handlers.hpp	Registers color handling
lib/devices/hid_device.hpp	Adds the device color method
lib/devices/headsetcontrol_test.hpp	Adds test-device support
lib/devices/corsair_virtuoso_xt.hpp	Implements Virtuoso lighting control
lib/device.hpp	Adds capability and RGB parameter plumbing
lib/capability_descriptors.hpp	Adds capability metadata
docs/LIBRARY_USAGE.md	Documents library APIs
docs/ADDING_A_DEVICE.md	Updates capability guidance
docs/ADDING_A_CAPABILITY.md	Documents capability implementation rules
cli/output/output.cpp	Emits structured color fields
cli/output/output_data.hpp	Adds color-aware value handling
cli/main.cpp	Parses and schedules color actions
AGENTS.md	Updates capability guidance

Review details

Suppressed comments (3)

cli/output/output.cpp:103

• Adding action.color changes the structured output schema, but API_VERSION remains 1.5 (line 29). docs/LIBRARY_USAGE.md:97-104 defines minor-version increments for additions, so clients cannot distinguish this schema from the old 1.5 format; bump the version and update the corresponding documentation/fixtures.

        action.color  = std::format("#{:02x}{:02x}{:02x}", c.r, c.g, c.b);

lib/devices/corsair_virtuoso_xt.hpp:133

• When the headset is charging, this new branch returns BATTERY_CHARGING, but the CLI's --connected implementation in cli/main.cpp:1209-1210 only treats BATTERY_AVAILABLE as connected. Consequently headsetcontrol --connected reports false for a connected Virtuoso while it is charging; the connectivity check should accept both available and charging statuses.

        auto status = BATTERY_AVAILABLE;
        if (auto charge_state = readProperty(device_handle, resolved->target, PROP_BATTERY_STATUS);
            charge_state && *charge_state == CHARGE_STATE_CHARGING) {
            status = BATTERY_CHARGING;

lib/devices/corsair_virtuoso_xt.hpp:453

• resolveTarget treats every failed readProperty as evidence that the candidate was wrong and discards the error. If both probes hit an HID, permission, or protocol failure, the caller is incorrectly told that the headset is offline; only a silent timeout/offline result should trigger the alternate probe, while other errors should be propagated.

        for (const uint8_t candidate : { hinted, alternate }) {
            if (auto level = readProperty(
                    device_handle, candidate, PROP_BATTERY_LEVEL, TARGET_PROBE_TIMEOUT_MS)) {
                return ResolvedTarget { .target = candidate, .battery_level = *level };
            }

• Files reviewed: 25/25 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]

Fixed in d79a316. SoftwareModeGuard gained dismiss(), and the color path now takes a guard like every other write, dismissing it only once the frame is written. A successful color stays in software mode, so the frame stays visible; a failed brightness or frame write hands the headset back to hardware mode.

test_corsair_virtuoso.cpp covers both halves with a mock: a clean write takes six requests and never restores hardware mode, and a failed frame write still closes the handle and then restores it. Dropping the guard fails the failure case, and dropping dismiss() fails the success case. On the XT, --light-color still leaves the headset in software mode.

[gdevenyi]

Fixed — in #570 (8feff12), since that's where this code comes from, merged in here. The previous review there settled for a comment; this replaces the comment with a fix.

Every request now goes through transact(), which throws away anything already queued (non-blocking reads, bounded) before writing. Nothing read before a request goes out can be its reply, so it only ever discards stale replies and the volume events readReply() skipped anyway. The handle commands for the lighting frame use it too. A battery read still takes about 0.2 s on the XT.

The test mock makes each report readable only after a given number of writes, which is what distinguishes a stale reply from a real one. With a stale charge-state reply queued before getBattery(), the level comes out right; without the discard, the stale 1 is read as the battery level and the test fails.

[gdevenyi]

Addressing the three findings Copilot suppressed in its summary:

API version — fixed, now 1.6 (d79a316). Action entries gained color, and 4.1.0 already shipped API 1.5, so this can't fold into 1.5 the way #560's sidetone field did before that release. Following #549: the constant gets its note, and the LIBRARY_USAGE.md example and serializer fixture follow.

resolveTarget() swallowing errors — fixed, in #570 (8feff12) and merged here. Only two probe failures now mean "wrong target": silence, and "no such property", which is a receiver answering for itself with no headset behind it. Anything else — a failed HID write, an unexpected status — is returned as is instead of becoming "offline". The mock tests check all three cases, including that treating only silence as "wrong target" would regress a receiver with its headset off from "offline" to "not supported".

--connected reporting a charging headset as disconnected — real, but not changed here. It's not specific to this PR: checkDeviceConnected() has treated only BATTERY_AVAILABLE as connected since the C version (info.status != BATTERY_AVAILABLE → false), and that applies to all 22 device files that report BATTERY_CHARGING. The Virtuoso only meets it now because #570 made it report charging at all. Counting charging as connected is a one-line change, but it alters the meaning of --connected for every device, so I'd rather not slip it into a light-color PR. @Sapd — happy to send it separately if you agree charging should count as connected.