Add ITE 829x (PID 0x8910) per-key RGB keyboard support
Summary
Adds support for the ITE 829x keyboard controller (USB PID 0x8910, VID 0x048D) found in recent Clevo-based laptops such as XMG PRO E23, Clevo PD5x, and similar TUXEDO/Schenker models.
This extends the existing Clevo keyboard controller to handle both ITE 8291 and ITE 829x variants in the same codebase, as suggested in !3177 (comment by @CalcProgrammer1).
All firmware modes were reverse-engineered from the XMG Control Center Windows application (perkey_api.dll + LedKeyboardSetting.exe .NET IL) and implemented as faithfully as possible to match the original Windows behavior.
Resolves #3045
What's new
- ITE 829x (PID
0x8910) detection via Usage Page0xFF89, Usage0xCC - Per-key Direct mode (6x20 matrix, 120 LEDs)
- 13 firmware modes with brightness and speed control, faithful to the XMG Control Center
- Separate random/color variants for Breathing, Flashing, and Random (matching the Windows UI toggle)
- Wave with 8 color slots and Snake with 4 color slots (matching the Windows color palette system)
- Scan with 2 custom colors (matching the Windows dual-color band selector)
- Fn Highlight with user-selectable color (improved over Windows which hardcodes red)
- ClearColor command before per-key updates (required by firmware, discovered through protocol analysis)
- KeyboardLayoutManager integration with KEYBOARD_SIZE_FULL layout
- Mode names follow Common Modes convention
- No kernel module dependency - works with standard
hid-genericviahidapi
Protocol
Reverse-engineered from perkey_api.dll and the .NET LedKeyboardSetting.exe from the XMG Control Center Windows application. The ITE 829x uses 6-byte HID feature reports with report ID 0xCC:
| Command | Format | Description |
|---|---|---|
| Per-key color | [CC, 01, led_id, R, G, B] |
Set individual key color |
| Clear colors | [CC, 00, 0C] |
Reset all keys before per-key update |
| Brightness+Speed | [CC, 09, brightness, speed] |
brightness 0-10, speed 0-10 |
| Wave |
[CC, 00, 04] + up to 8 colors via [CC, 15, A1-A8, R, G, B]
|
Wave with multi-color |
| Breathing | [CC, 0A, 00] |
Random color breathing |
| Breathing Color | [CC, 0A, AA, R, G, B] |
Breathing with custom color |
| Flashing | [CC, 0B, 00] |
Random color flashing |
| Flashing Color | [CC, 0B, AA, R, G, B] |
Flashing with custom color |
| Random | [CC, 00, 09] |
Random multicolor animation |
| Random Color | [CC, 18, A1, R, G, B] |
Random with custom color |
| Scan |
[CC, 00, 0A] + 2 colors via [CC, 17, A1-A2, R, G, B]
|
Dual-color scan |
| Snake |
[CC, 00, 0B] + up to 4 colors via [CC, 16, A1-A4, R, G, B]
|
Snake with multi-color |
| Spectrum Cycle | [CC, 00, 02] |
All keys cycle through spectrum |
| Rainbow Wave | [CC, 00, 04] |
Rainbow gradient across keyboard |
| Fn Highlight |
[CC, 00, 0C] + per-key on Fn keys |
Highlight Fn-layer keys |
Key differences from ITE 8291
| ITE 8291 (0x600B) | ITE 829x (0x8910) | |
|---|---|---|
| Report | 8 bytes, no report ID | 6 bytes, report ID 0xCC |
| Colors | Row-based bulk (65B via OUT endpoint) | Per-key commands |
| Matrix | 6x21 = 126 LEDs | 6x20 = 120 LEDs |
| LED ID | Sequential (row * 21 + col) | Encoded: ((row & 7) << 5) | (col & 0x1F)
|
| Brightness | 0-50 | 0-10 |
Note on !3177
This MR takes a different approach from !3177 by integrating ITE 829x support into the existing Clevo keyboard controller rather than creating a separate controller directory. It also adds KeyboardLayoutManager support (KEYBOARD_SIZE_FULL), Common Mode naming, multi-color support for Wave/Snake/Scan, and separate random/color variants for each effect mode.
Limitations
Ripple mode is not implemented as it requires EC configuration via the proprietary Insyde DCHU BIOS interface, which is not accessible from userspace on Linux.
Modes
| Mode | Color | Speed | Brightness |
|---|---|---|---|
| Direct | Per-key | - | Yes |
| Wave | 8 custom | Yes | Yes |
| Breathing | - | Yes | Yes |
| Breathing Color | 1 custom | Yes | Yes |
| Flashing | - | Yes | Yes |
| Flashing Color | 1 custom | Yes | Yes |
| Random | - | Yes | Yes |
| Random Color | 1 custom | Yes | Yes |
| Scan | 2 custom | Yes | Yes |
| Snake | 4 custom | Yes | Yes |
| Spectrum Cycle | - | Yes | Yes |
| Rainbow Wave | - | Yes | Yes |
| Fn Highlight | 1 custom | - | Yes |
| Off | - | - | - |
Test plan
- Tested on XMG PRO E23 (Clevo PD5x) with ITE 8910 firmware 1.03.02
- Works with standard hid-generic driver (no kernel module needed)
- All 13 firmware modes + Off verified
- Per-key Direct mode verified with ClearColor before update
- Brightness and speed controls verified
- Custom colors verified on Breathing, Flashing, Random, Wave, Snake, Scan
- Wave 8-color, Snake 4-color, Scan dual-color verified
- Fn Highlight with custom color verified
- KeyboardLayoutManager FULL layout with named keys verified
- cppcheck clean, zero compiler warnings
- ITE 8291 (PID 0x600B) regression test (no hardware available)