feat(k2_he): add OpenRGB protocol for per-key RGB control

[i-am-logger]

Description

Adds OpenRGB per-key RGB control to the Keychron K2 HE over raw HID, on the ansi/default keymap (the keychron keymap keeps VIA / Keychron Launcher unchanged).

• Per-key direct control via a custom RGB_MATRIX_OPENRGB_DIRECT effect.
• Built-in animations are exposed correctly: OpenRGB assigns mode values in its own fixed order, so an explicit OpenRGB↔QMK table (Direct last) translates GET_ENABLED_MODES / SET_MODE / GET_MODE_INFO instead of trusting QMK's effect numbering — so the mode names line up with the real effects.
• Replies are sent via kc_raw_hid_send(RAW_HID_SRC_USB, …) like the Keychron Launcher's KC_* handlers. The core raw_hid_send() is silently dropped by the active wireless host driver (NULL send_raw_hid) when the side switch is on BT/2.4G, so OpenRGB must send USB-direct.
• Host-side unit tests (keyboards/keychron/common/tests) compile openrgb.c against mocks and prove both the mode mapping and the USB-reply routing.

Supersedes #447 (which targeted the deprecated hall_effect_playground branch).

Types of Changes

• Core
• Bugfix
• New feature
• Keyboard (addition or update)

Issues Fixed or Closed by This PR

• Supersedes feat(k2_he): add OpenRGB protocol for per-key RGB control #447

Notes for @lokher

Three commits. The OpenRGB feature is self-contained in the first commit; the other two fix pre-existing CI failures on the 2025q3 base (confirmed on a clean base checkout, independent of this feature) and are isolated so you can split either into its own PR:

• feat(k2_he): add OpenRGB protocol… — the feature (incl. the mode mapping, USB-reply routing, and unit tests).
• chore: prune dangling keyboard aliases — removes ~783 keyboard_aliases.hjson entries whose target keyboards were removed from this fork, so ci-validate-aliases passes (Keychron aliases preserved).
• fix(wear_leveling): remove stray unlock — removes a wear_leveling_unlock() not present upstream that broke the WearLeveling*_OOB unit tests.

Checklist

• My code follows the code style of this project
• I have read the CONTRIBUTING document
• I have added tests to cover my changes
• I have tested the changes and verified that they work and don't break anything (built, lint-clean, host unit tests pass; OpenRGB protocol exercised on a real K2 HE over raw HID)

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds OpenRGB support for the Keychron K2 HE by enabling 64-byte Raw HID reports, wiring an OpenRGB command handler, and introducing an RGB Matrix “direct” effect for per-LED color control.

Changes:

• Make RAW_EPSIZE overridable and set it to 64 for the K2 HE ANSI config for OpenRGB Raw HID reports.
• Add an OpenRGB Raw HID protocol implementation (openrgb.c/.h) and route USB Raw HID packets to it.
• Add a new RGB Matrix effect (OPENRGB_DIRECT) and enable OpenRGB for the K2 HE (default keymap sets the mode at startup).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tmk_core/protocol/usb_descriptor.h	Allows overriding RAW_EPSIZE so keyboards can opt into 64-byte reports.
quantum/rgb_matrix/animations/rgb_matrix_effects.inc	Registers the new OpenRGB direct animation header.
quantum/rgb_matrix/animations/openrgb_direct_anim.h	Implements the OPENRGB_DIRECT RGB Matrix effect that applies per-LED colors.
keyboards/keychron/k2_he/rules.mk	Enables OpenRGB for the K2 HE build.
keyboards/keychron/k2_he/ansi/keymaps/default/keymap.c	Sets the keyboard to OPENRGB_DIRECT mode after init when OpenRGB is enabled.
keyboards/keychron/k2_he/ansi/config.h	Overrides Raw HID endpoint size to 64 bytes for OpenRGB.
keyboards/keychron/common/openrgb.h	Declares OpenRGB protocol constants and handler API.
keyboards/keychron/common/openrgb.c	Implements OpenRGB command handling and Raw HID responses.
keyboards/keychron/common/keychron_raw_hid.c	Routes incoming USB Raw HID packets to the OpenRGB handler.
keyboards/keychron/common/keychron_common.mk	Adds build toggles and sources for OpenRGB support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[CalcProgrammer1]

There's an open merge request on the OpenRGB side to implement Keychron's RGB protocol. I think this is the better solution, the OpenRGB QMK protocol is pretty basic and pretty old at this point. While it's still supported (and I just made some QMK Community Modules for it at https://gitlab.com/OpenRGBDevelopers/OpenRGB-QMK), Keychron's own protocol appears to support all the capabilities that OpenRGB needs according to this merge request: https://gitlab.com/CalcProgrammer1/OpenRGB/-/merge_requests/3290 so it would be best to update OpenRGB to support what the keyboard already supports.

I'm looking into merging this MR and trying to test it on my Keychron Q2, but I'm not sure the Q2 supports the same Keychron protocol.

[i-am-logger]

Thanks @CalcProgrammer1 — agree, native is the right direction. The K2 HE speaks the same native 0xA8 group as the Q1 HE 3290 targets, so I'm glad to test 3290 against it and add the K2 HE (0x3434:0x0E20) device entry — I've got the hardware.

I'll keep #476 open as a working stop-gap (it uses the current OpenRGB-QMK protocol) until native K2 HE support lands in OpenRGB, then close it in favor of that.

Note

Side note on the Q2: it's actually a few different boards — only the Max/HE variants expose 0xA8; the wired Q2 is the older OpenRGB-QMK one. Worth dumping its PID + checking for usage_page 0xFF60 before testing 3290 on it.

[CalcProgrammer1]

Do you know if it's possible to build a firmware for the wired Q2 that has the new protocol?

[i-am-logger]

Do you know if it's possible to build a firmware for the wired Q2 that has the new protocol?

Yes — it already exists in Keychron's QMK fork. The wired Q2 has a target with the native 0xA8 protocol; I just built it:

$ qmk compile -kb keychron/q2/ansi -km keychron 

compiles clean (~59 KB). The keychron keymap gives both the native 0xA8 group and VIA on (the 0x07/0x08 channel 3290 uses for mode/brightness). Flash that on your wired Q2 (PID stays 0x0110/0x0111), add that PID to 3290, and you could test it.

[i-am-logger]

@CalcProgrammer1 here is a confirmation

arm-none-eabi-nm .build/keychron_q2_ansi_keychron.elf | grep -E 'kc_rgb_matrix_rx|via_command_kb'

[CalcProgrammer1]

I'll look into that today. I was able to build custom firmware for my Q2 from the upstream QMK repo and include my community module for the OpenRGB protocol, but that route won't have support for Keychron's configuration tool. Does this PR allow both at the same time?

[CalcProgrammer1]

Hmm, the build fails for me:

Compiling: quantum/rgb_matrix/rgb_matrix.c                                                         In file included from quantum/rgb_matrix/animations/rgb_matrix_effects.inc:30,
                 from quantum/rgb_matrix/rgb_matrix.c:50:
quantum/rgb_matrix/animations/pixel_rain_anim.h: In function 'PIXEL_RAIN':
quantum/rgb_matrix/animations/pixel_rain_anim.h:16:25: error: variable 'region_mask' set but not used [-Werror=unused-but-set-variable=]
   16 |     static uint8_t      region_mask  = 0;
      |                         ^~~~~~~~~~~
cc1: all warnings being treated as errors
 [ERRORS]
 | 
 | 
 | 
make: *** [builddefs/common_rules.mk:362: .build/obj_keychron_q2_ansi_keychron/quantum/rgb_matrix/rgb_matrix.o] Error 1

This is with the default branch (2025q3).

[i-am-logger]

i'll take a look, i used my own branch so will check later

[i-am-logger]

I'll look into that today. I was able to build custom firmware for my Q2 from the upstream QMK repo and include my community module for the OpenRGB protocol, but that route won't have support for Keychron's configuration tool. Does this PR allow both at the same time?

yes, it does