Add ITE 829x (PID 0x8910) per-key RGB keyboard support + diagonal direction core 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 Uniwill Control Center Windows application (perkey_api.dll + LedKeyboardSetting.exe .NET IL) and validated through hardware testing.
Resolves #3045
What's new
- ITE 829x (PID
0x8910) detection via Usage Page0xFF89, Usage0xCC - Per-key Direct mode (6x20 matrix, 120 LEDs)
- 9 firmware modes with brightness and speed control
-
MODE_FLAG_HAS_RANDOM_COLORtoggle for random/custom color switching on Wave, Snake, Breathing, Flashing, Random - Wave with 8 directions (4 cardinal + 4 diagonal) and optional custom color
- Snake with 4 diagonal directions and optional custom color
- Scan with 2 custom band colors
- Fn Highlight with user-selectable color
- ClearColor command before per-key updates (required by firmware)
- Mode/brightness/speed change tracking to avoid redundant firmware commands
- KeyboardLayoutManager integration with KEYBOARD_SIZE_FULL layout
- Mode names follow Common Modes convention
- No kernel module dependency, works with standard
hid-genericviahidapi
OpenRGB core changes
- Added
MODE_FLAG_HAS_DIRECTION_DIAG(1 << 10) for diagonal direction support - Added
MODE_DIRECTION_UP_LEFT,MODE_DIRECTION_UP_RIGHT,MODE_DIRECTION_DOWN_LEFT,MODE_DIRECTION_DOWN_RIGHTenums (6-9) - UI: diagonal direction dropdown support in DirectionBox
Protocol
6-byte HID feature reports with report ID 0xCC: [CC, cmd, d0, d1, d2, d3]
| Command | Format | Description |
|---|---|---|
| Per-key color | [CC, 01, led_id, R, G, B] |
Set individual key color |
| Clear | [CC, 00, 0C, 00, 00, 00] |
Reset all keys (required before per-key) |
| Brightness/Speed | [CC, 09, brightness, speed, 00, 00] |
brightness 0x00-0x0A, speed 0x00-0x0A |
| Spectrum Cycle | [CC, 00, 02, 00, 00, 00] |
All keys cycle through spectrum |
| Wave |
[CC, 00, 04] + [CC, 15, slot, R, G, B]
|
Slot encodes direction (0x71-0x78 preset, 0xA1-0xA8 custom) |
| Random | [CC, 00, 09, 00, 00, 00] |
Random multicolor |
| Random Color | [CC, 18, A1, R, G, B] |
Random with custom color |
| Scan |
[CC, 00, 0A] + [CC, 17, A1/A2, R, G, B]
|
2 color bands |
| Snake |
[CC, 00, 0B] + [CC, 16, slot, R, G, B]
|
Slot encodes direction (0x71-0x74 preset, 0xA1-0xA4 custom) |
| Breathing | [CC, 0A, 00, 00, 00, 00] |
Random color breathing |
| Breathing Color | [CC, 0A, AA, R, G, B] |
Breathing with custom color |
| Flashing | [CC, 0B, 00, 00, 00, 00] |
Random color flashing |
| Flashing Color | [CC, 0B, AA, R, G, B] |
Flashing with custom color |
Wave direction slots:
| Preset | Custom | Direction |
|---|---|---|
| 0x71 | 0xA1 | Up-Left |
| 0x72 | 0xA2 | Up-Right |
| 0x73 | 0xA3 | Down-Left |
| 0x74 | 0xA4 | Down-Right |
| 0x75 | 0xA5 | Up |
| 0x76 | 0xA6 | Down |
| 0x77 | 0xA7 | Left |
| 0x78 | 0xA8 | Right |
Snake uses the same pattern with 4 diagonal slots (0x71-0x74 / 0xA1-0xA4).
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.
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 | Direction | Speed | Brightness |
|---|---|---|---|---|
| Direct | Per-key | - | - | Yes |
| Wave | Random or 1 custom | 8 directions | Yes | Yes |
| Breathing | Random or 1 custom | - | Yes | Yes |
| Flashing | Random or 1 custom | - | Yes | Yes |
| Random | Random or 1 custom | - | Yes | Yes |
| Scan | 2 custom | - | Yes | Yes |
| Snake | Random or 1 custom | 4 diagonals | 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 9 firmware modes + Direct + Off verified on hardware
- Per-key Direct mode verified with ClearColor before update
- Brightness and speed controls verified
- Random/custom color toggle verified on Wave, Snake, Breathing, Flashing, Random
- Wave 8 directions verified on hardware
- Snake 4 diagonal directions verified on hardware
- Scan dual-color bands verified on hardware
- 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)