Skip to content

Add Keychron RGB handler to the theme keyboard pipeline - #9545

Open
ueltyx wants to merge 1 commit into
omacom:quattrofrom
ueltyx:keychron-rgb-sync
Open

Add Keychron RGB handler to the theme keyboard pipeline#9545
ueltyx wants to merge 1 commit into
omacom:quattrofrom
ueltyx:keychron-rgb-sync

Conversation

@ueltyx

@ueltyx ueltyx commented Sep 1, 2026

Copy link
Copy Markdown

Summary

Adds Keychron RGB support to the existing keyboard.rgb theme pipeline, following the omarchy-theme-set-keyboard-asus-rog / -f16 handler pattern exactly.

Keychron's own firmware (V/Q/K "Ultra" and "Max" series, protocol v11+) implements the VIA raw-HID protocol on a vendor config channel (USB usage page 0xFF60, usage 0x61). It is the same lighting command set the Framework 16 handler already speaks via qmk_hid: solid effect ([7,3,2,1]), HSV color ([7,3,4,h,s]), NVRAM save ([9,3]). The protocol was extracted from Keychron's own Launcher web app (WebHID client) — no firmware flashing, no reverse-engineered vendor blobs.

Changes

  • bin/omarchy-keychron-rgb — transport: bash + embedded Python (stdlib only, no new packages, nothing to compile). Auto-discovers the config channel by vendor 3434 + usage-page signature and round-trip-probes it, so it works across models and connection modes (with cable and dongle both enumerated, one channel is a dead end depending on the keyboard's mode switch — the probe picks the live one).
  • bin/omarchy-hw-keychron — hardware detect (USB vendor 3434), hw-* pattern.
  • bin/omarchy-theme-set-keyboard-keychron — the handler; no-op without a Keychron present.
  • bin/omarchy-theme-set-keyboard — dispatch entry.
  • default/udev/keychron-rgb.rules + install/hardware/keychron-rgb.sh + migration — vendor-wide uaccess rule (also unblocks the official Keychron Launcher web app), mirroring framework/qmk-hid.sh.
  • install/hardware/all.sh — install wiring.

Verified behavior

Tested on a Keychron V1 Ultra 8K (ZMK-based, 3434:0c10) plus Ultra-Link 8K 2.4GHz dongle (3434:d028):

  • All 22 stock themes switched back-to-back; keyboard color read back over HID and matched the theme color byte-exact every time, including Tokyo Night's hand-picked keyboard.rgb (ff00ff) overriding the accent template.
  • User-created themes work automatically (accent template → staged keyboard.rgb).
  • Connection matrix: wired works; 2.4GHz dongle works (it tunnels the config channel; needs a radio-wake timeout, handled); Bluetooth intentionally holds the last synced color — the stock firmware exposes no config channel over BT (confirmed via the BT HID descriptor, the GATT service tree, and the Launcher client being WebHID/USB-only).
  • No-op cost on non-Keychron machines: one sysfs grep; the handler exits before spawning the transport.

Testing

  • ./test/cli — 116 ok, 0 failures (includes metadata lint for the new commands).
  • ./test/shell — 2905 ok, 0 failures.
  • End-to-end on real hardware as described above.

Transparency

This contribution was developed end-to-end with AI assistance (an agentic CLI coding assistant): protocol extraction from the Launcher bundle, tool implementation, and the automated 22-theme verification. The submitter performed all hardware verification on their machine.

One natural follow-up (not in this PR to keep it scoped): a udev RUN+ on the rule could invoke the handler on (re)plug, re-syncing the keyboard at boot and whenever it returns from wireless to wired. Happy to add if wanted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant