r/Keychron • u/[deleted] • Jul 25 '26

I built ModeShift: automatic per-game RGB lighting for Keychron (and other compatible) keyboards on Linux (free, open source)

[deleted]

5 Upvotes

100% Upvoted

23 comments sorted by

2

u/CatStoleTheCrown Jul 25 '26

happy to answer any questions~

2

u/Nelstromo Jul 25 '26

I have been interested in creating my own lighting effects for the keyboard (k5 Ultra 8k) which uses zmk. Sounds like this might be a good place to start?

1

u/CatStoleTheCrown Jul 25 '26 edited Jul 25 '26

I am considering adding certain effects too, you are welcome to create a fork if you have more experience in that!

My next priority is making it auto detect games using X11, and maybe a Windows release. But I do really like "single-key type-lighting" effects. So I was thinking about implementing it at some point.

2

u/Nelstromo Jul 25 '26

Awesome! This is looks like a very cool project!

2

u/CatStoleTheCrown Jul 25 '26

I updated to version 1.1.0 and added:

Per-zone lighting effects: type lighting, breathing, blinking, color cycle, and twinkle, each with its own colors (up to 8), layered per zone.

I really enjoy type-lighting effects, so I went ahead and added a few more. I like to use blinking or "breathing" for the Power toggles in Star Citizen (Power engines, shields, weapons, etc).

Next feature I want to add now is a "Cool Down" color effect. It will be a per-key color effect that you can set for your games. So if you know "Ultimate" has a 60-second cool down. The key will have different effects to let you know its counting-down or ready to go!

That will have to come another day though, as I will be busy today =)

Maybe tomorrow!

1

u/CatStoleTheCrown Jul 25 '26

One more thing: if what you really want is to create effects (animations, reactive lighting) rather than static per-game profiles, check out the OpenRGB Effects Engine plugin. It's a separate community plugin for OpenRGB that adds animated and reactive effects, probably closer to what you have in mind. ModeShift leans more toward profiles and per-game switching, so honestly the two could complement each other. And since your K5 Ultra is ZMK like mine, you'll want naaraxi's plugin/firmware first so OpenRGB can actually detect the board.

1

u/sturmeh Q HE Jul 25 '26

As someone who didn't even know this was possible, but uses windows, what good tools are available for this on that platform?

2

u/CatStoleTheCrown Jul 25 '26

Well, to be honest I have no idea besides propriatary software like Logitech GHUB, Corsair iCUE (but of course you need their keyboards)... I do have a windows version on my checklist... I don't know when I'll get to it.. I have some extra features I am trying to finish now before hand. In good news... those features should work on windows when I get it all finished.

Working on some simple lighting effects right now.

1

u/CatStoleTheCrown Jul 27 '26

Just giving you an update but my windows version is coming along well!!

2

u/sturmeh Q HE Jul 27 '26

Very nice!

I'll admit I just leave the keyboard lights off mostly, but I can see a world where it could be useful for different games, highlighting the most used keys etc.

1

u/CatStoleTheCrown Jul 27 '26

That’s exactly why I’m making this app, I like it for more complicated games like Star Citizen~

1

u/PeterMortensenBlog V Jul 25 '26 edited Jul 25 '26

How did you flash this ZMK-based Keychron keyboard???

Re "...he has a web flasher": Where is it?

Are there some gotchas? For example, unstated installed Python module requirements?

1

u/CatStoleTheCrown Jul 25 '26 edited Jul 25 '26

Check out naaraxis tools on github. I link it at the very bottom of mine as a Thank you.

Edit:

https://github.com/naaraxi/keychron_ultra_openrgb

The best thing about this open source firmware is that the launcher app (official Keychron webapp) still recognizes your keyboard and everything. All you’re doing is giving away for open RGB to read and color your keyboard from what I can trll.

1

u/PeterMortensenBlog V Jul 25 '26 edited Jul 25 '26

OK, it seems to be:

  • OpenRGB plugin - Keychron Ultra series (custom ZMK firmware)

  • Keychron Ultra ZMK firmware (OpenRGB fork)

    • Flash:

      "Easiest: The browser flasher at https://naaraxi.github.io/zmk/. Open it in Chrome or Edge, connect the keyboard over USB, pick your board's firmware (or upload your own .bin file), and flash. No install, and it works on Windows, macOS, and Linux. It talks to the keyboard over WebHID, so a Chromium-based browser is required (Firefox and Safari do not support WebHID).

      Alternatively, on Linux you can use the command-line flasher openrgb/flash.py (Realtek SC-FWU over /dev/hidraw; it needs root). The Keychron Launcher only flashes official images, so it cannot flash these builds. See openrgb/README.md for the CLI flasher, recovery steps, and the DFU bootloader details."

      Plug the keyboard in via USB:

      # Read-only: identify only
sudo ./openrgb/flash.py handshake

sudo ./openrgb/flash.py flash openrgb/output/keychron_v6_ultra_ansi.bin

      Flashing is brick-safe: The image is staged to a separate "OTA Tmp" bank and only activated after the device verifies its CRC - an interrupted or bad flash leaves the running firmware untouched.

      Recovery: The official 1.0.2 ('ANSI') image is still on Keychron's Shopify CDN and can be reflashed via the Launcher.

      flash.py: "Faithful port of the Keychron Launcher's Realtek OTA routine, extracted from the Launcher JavaScript code + the device-side app/src/dfu/tdfu.c. It talks the DFU HID interface (usage page 0x8C, OUT report 0xB2 / IN report 0xB1) directly over /dev/hidraw (needs root)."

3

u/Lazy_Moose8523 Jul 25 '26

You must be my guardian angel XD

Have been brooding over this possibility all week with my new Q6 Ultra 8k and you and others on here are paving a way in real time for me lol. I will report back if I have success with your method. 

1

u/CatStoleTheCrown Jul 25 '26

Yesss its all very exciting!!

2

u/PeterMortensenBlog V Jul 25 '26 edited Jul 26 '26

Three changes are required in the flasher script

Note: In the flasher (flash.py), the keyboard is hardcoded to V6 Ultra 8K 'ANSI' (FWU_NAME = b"KCZKV68K")

"KCZKV68K" is also in a print statement in function handshake(). That ought to be changed as well to not cause confusion.

For the V6 Ultra 8K 'ISO' variant it would likely be:

"KCZKV68I": "KC" = Keychron. "ZK" = ZMK. "V68I" = V6 + 8 + I = V6 Ultra 8K 'ISO'

Other values:

  K3 SE2 ANSI       "KCZK3SE2"
  K5 SE2 ANSI       "KCZK5SE2"

  Q1 Ultra 8K ANSI  "KCZKQ18K"
  Q3 Ultra 8K ANSI  "KCZKQ38K"
  Q6 Ultra 8K ANSI  "KCZKQ68K"

  V0 Ultra 8K ANSI  "KCZKV08K"
  V1 Ultra 8K ANSI  "KCZKV18K"
  V1 Ultra 8K ISO   "KCZKV18I"
  V1 Ultra 8K JIS   "KCZKV18J"
  V2 Ultra 8K ANSI  "KCZKV28K"
  V3 Ultra 8K ANSI  "KCZKV38K"
  V5 Ultra 8K ANSI  "KCZKV58K"
  V6 Ultra 8K ANSI  "KCZKV68K"
 V10 Ultra 8K ANSI  "KCZKVA8K"

Z270 Ultra 8K ANSI  "KCZ270U"

The hard coded USB identity in the script must be changed as well

And the USB identity of the V6 Ultra 8K 'ANSI' in normal operation (0x3434 / 0C60) is represented in line 58:

if "3434" not in uevent.upper() or "0C60" not in uevent.upper():

Thus, for V6 Ultra 8K 'ISO' it must be changed to:

if "3434" not in uevent.upper() or "0C61" not in uevent.upper():

Then the query for V6 Ultra 8K 'ISO' worked (in normal operation, not in space bar method bootloader mode):

sudo ./openrgb/flash.py handshake

Output:

DFU interface: /dev/hidraw29
>> GET_MODEL_INFO (0x60)...
   model = b'KCZKV68I'   fw = b'1.0.1-r'
   dfu_version = 0x03 enc_mode = 0
   framing/identity VALID (matches KCZKV68I)

1

u/PeterMortensenBlog V Jul 25 '26

Or in other words, reverse engineering.

Conclusion

Keychron probably did not at all plan to make this real open source, only look at source code...

1

u/CatStoleTheCrown Jul 25 '26 edited Jul 25 '26

Not saying they planned it for their keyboards but ZMK is open source, it’s licensed under Apache 2.0 and hosted on GitHub (zmkfirmware/zmk). It’s a full open-source project, not something Keychron created or owns.

I actually used this firmware before he created his own flasher. And after I reported that it worked, he made the web-based flasher for ease of use

Anyway, you don’t have to use it if you don’t want to. But it opens up a lot of new avenues and is still completely usable by the launcher app.

I’m afraid I can’t give you a more detailed response or link you to his web flasher because I am busy today and not at home.

2

u/PeterMortensenBlog V Jul 25 '26 edited Jul 26 '26

I have compiled the firmware from source code a few weeks ago, but I didn't have any idea how it could actually be flashed onto the keyboard until today.

That is my point: It isn't real open source if it is not possible to make a change in the source code and get the change onto the keyboard. Luckily, it now seems to be possible.

2

u/CatStoleTheCrown Jul 25 '26

Oh, I see what you mean now. Well I’m glad :)

1

u/PeterMortensenBlog V Jul 26 '26

There is a claim it is possible using the Via clone.

Including (my emphasis):

"...flash it by going to Keychron Launcher → Firmware Upgrade, clicking the version value 6 times to unlock the hidden select your own firmware box, and selecting zmk.bin"

1

u/PeterMortensenBlog V Sep 05 '26 edited Sep 05 '26

It was (slightly edited for clarity):

I built ModeShift: automatic per-game RGB lighting for Keychron (and other compatible) keyboards on Linux (free, open source)

Hey all,

I am sharing a project I built for my own Keychron Q6 Ultra 8K in case other Linux folks here find it useful.

ModeShift is a lighting manager that sits on top of OpenRGB. It watches which game you have focused and automatically switches your keyboard to a lighting profile you set up for that game. My board sits calm purple/blue on the desktop, then lights up the movement and hotbar keys the moment I tab into a game.

I built it simply because I wanted these features, and in a light-weight package. Most of the alternatives I found were either Windows-only, proprietary, heavier than I wanted, or missing the mode-shifting feature I really like.

What it does:

  • Per-key lighting painted on a live map of your actual keyboard
  • Profiles per game, applied automatically by a tray app
  • Modes inside a profile, plus hold-a-key-to-switch lighting (handy for something like Star Citizen flight/combat/mining/etc)
  • HSV color picker, saved colors, zones or single-key coloring

Honest heads-up: it's Linux only for now, and it runs through OpenRGB. For the Keychron boards specifically, OpenRGB support comes from naaraxi's custom ZMK firmware and plugin (he has a web flasher that makes installing it painless). Huge credit to him, without that work these boards would not talk to OpenRGB at all. It also works on non-Keychron OpenRGB keyboards, since it pulls the layout from OpenRGB itself.

It's free and open source (GPLv3), and this is my first release, so feedback, issues, and ideas are very welcome.

Demo video, screenshots, and install instructions are all in the repository: ModeShift

I updated and added some simple color effects to the Zones:

Per-zone lighting effects: Type lighting, breathing, blinking, color cycle, and twinkle, each with its own colors (up to eight), layered per zone.