I recently picked up my Framework 16, and wanted to run OpenRGB on it so I could make my RGB keyboard synced with my audio. I’ve figured it out, so here’s a brief rundown on installing OpenRGB (in this example on Fedora), setting up a QMK environment, compiling and flashing your board.
PLEASE NOTE: VIA DOES NOT WORK WITH OPENRGB!
You can find precompiled binaries for the RGB ANSI Keyboard and the RGB Macropad HERE:
I’ll be potsing each step in a different post, but you can read the full steps on my github: Link to my readme.md
If you choose to compile it yourself (RECOMMENDED), follow the following steps in order. Otherwise, you can skip to Step 4 and use the precompiled binaries.
1. Compilation First Steps
You’re gonna need the bare essentials, which is a set-up QMK environment. These are the steps I followed to setup QMK, but if you run into any issues or this guide is outdated in whatever way, you can read the official documentation on setting up for your distro/os of choice HERE
Before running qmk setup, you should probably have the repo downloaded. As of 6/24/24, the commits have been merged into tagno25’s repository for OpenRGB, where all future updates should be pushed to. To download the repository, run
Now, run cd qmk_firmware and you’re ready to run qmk setup!
If you get mild warnings, some of those are to be expected.
Whenever I first setup QMK on my fedora install, qmk complains of “avr-gcc” being too new (which does not matter for the fw16’s boards anyways), and that git is not configured upstream. You can ignore both of these issues. You may also see warnings telling you to setup udev devices, while I recommend doing this, its not essential for the fw16 for reasons we’ll get to in a moment.
3. Compiling
Compilation is really easy. The following should be used for compiling with OpenRGB on the following keyboards
RGB Keyboard qmk compile -kb framework/ansi -km openrgb
Once compilation is finished, you can find the compiled firmwares in the root directory of the firmware git repo.
Flashing is relatively easy. All Framework QMK devices have similar reset activations. The following are the ones for the RGB Macropad and the RGB Keyboard (the only ones that really matter to this guide, but these apply to most framework keyboard devices)
WARNING: It is recommended to do these one at a time. Doing both together means you can’t tell the difference between the two devices and might accidentally flash the wrong firmware (that’s bad)
To power cycle the FW keyboards, remove the touchpad which will turn off power to all keyboard/macropad devices. Next, press and hold the reset buttons as described below.
RGB Macropad: Hold down the 6 and 2 keys while powering on the keyboard. The 6 key is positioned at (2,3) and the 2 key is positioned at (1,4), with the top left key being (0,0)
RGB Keyboard: Hold down the left and right ALT Keys
Finally, slide the touchpad back in while holding the reset keys. This will repower the device and put it into reset mode. To disable reset mode without flashing, just remove the touchpad and put it back.
Once into reset mode, a new drive should show up for flashing, called RPI-RP2, and should show up like a USB drive. To flash, drag the compiled or downloaded firmware file into this drive, and the device will automatically flash! With any luck, it should power back on with the new firmware
Once you’ve flashed your hardware, you should now find that VIA does not work. You can still change keymaps and macros, but it does require some code modification. (it’s really not much… Any basic C knowledge will get you a long way)
Next, we should set up OpenRGB. First, install OpenRGB via your distro’s package manager. For example, on Fedora, you would run
Once you boot up OpenRGB for the first time, it’ll complain of missing udev rules. You should ensure that you reboot after installing these udev rules. If OpenRGB still complains, it’s probably fine? Especially if it complains of missing I2C devices, as the FW16 doesnt have any I2C RGB devices, this warning can be ignored. Please read this for more information if you have any issues (you shouldn’t have any issues if you just install openrgb and reboot)
6. Setting Up OpenRGB
OpenRGB is pretty easy to setup. Once you’ve installed and launched it, the following is the easy steps on setting this up:
1. Go to the settings tab
2. Scroll down to OpenRGB QMK Protocol in the side list
3. Add your devices.
When adding these devices, you should set them up like the following table:
Keyboard
Macropad
Name
Framework Laptop 16 Keyboard Module - ANSI
Framework Laptop 16 RGB Macropad
USB VID
32ac
32ac
USB PID
0012
0013
Next, you should click “Save”, then “Save Profile” and save to a profile. Then, you can restart OpenRGB. OpenRGB should be working now! All features are supported, including Direct Mode!
Q: Help! Whenever I start OpenRGB after setting up the keyboard in QMK, it hangs forever and stops responding
A: Make sure you compiled the firmware with the keymap openrgb and not default or any others.
Q: OpenRGB gives me an I2C/USB error, and the keyboard doesn’t work
A: You need to make sure that you restarted after installing the udev rules. If you’re using the flatpak or appimage, you’ll need to manually install the OpenRGB I2C/USB UDEV rules. You can find more here
Q: How can I go back to the stock firmware?
A: Links to the stock firmware and instructions on flashing is provided during step 4
Q: Does this void my warranty?
A: I have no idea. I don’t think it’s possible to brick the keyboard, so probably not? It’s not like the flashing can detected anyways.
Q: Is there any way to get VIA to work with OpenRGB?
A: I doubt it. Projects like VIAL exist, but VIAL will need a lot more work to get to work with the FW16.
The mode drop down list doesn’t seem to be indexing correctly. Some of the modes towards the bottom of the list are misaligned by 3 positions. For example, Solid Reactive Wide triggers Digital Rain. Solid Reactive triggers Typing Heatmap. This also makes the last three modes inaccessible.
And toggling the LED view in Direct mode brings up a very confused keymap.
For example – attempting to change the color of ESC key will change the color of the physical A key instead.
I’ve previously used the Framework version of VIA to change the lighting mode but have not otherwise played with the QMK firmware.
The dropdown in OpenRGB is unfortunately handled by them: The order is so incorrect (even with me rearranging to allow direct mode to work at all) and is something that is handled on their side. The last 3 modes had to be unfortunately disabled because OpenRGB is hardcoded to expect Direct mode to be in slot 42. This would require an overhaul on their end to fix that, but I don’t think it’d be too hard to make a commit on that. The only problem is that changing it for one keyboard would break all QMK keyboards, so I’m not sure on that’s feasibility (I’ve never worked with QMK or OpenRGB before this project). As for the key layout color changing, I’ll look at the source and see if that has something to do with the keyboard layout being passed from QMK to OpenRGB, im not sure if that’s an issue with the firmware or with the rest. For now, you can just figure out by using the scroll wheel and setting the colors, but I’ll look into it. (This would be helped a lot if the framework code could get merged into the official QMK repo as well, since then porting would be a LOT easier)
Also, if you want to change the order of the effects and built it from source, you can do that by changing this file qmk_firmware/quantum/rgb_matrix/animations/rgb_matrix_effects.inc at f87fe594f8339003f7e4e8dd395dea17139224a3 · Knucklesfan/qmk_firmware · GitHub just don’t forget to leave direct mode in slot 42!
Update on this: turns out this is actually how the keys are laid out in the key layout, so this is actually fixable with a firmware update. I’m about half done remapping the keys to work properly, so this should be fixed tonight hopefully!
Second update: the changes I was making was doing more harm than good, so I’ll look into this tomorrow.
Thanks for the response! I can’t figure out how to fix the keymaps, so for now (until I pick this project back up) you can just scroll through the menu, manually tweak the colors until you figure out which key is which. I want to fix this later, so I’ll look into fixing it eventually. As for the brightness, it should work as intended, but if you can’t get that to work, you can just lower the brightness of the color itself.
This is awesome! But I can’t seem to get it working on Windows 11. I have flashed the firmware and I can see the devices in device manager with the matching USB VID and PIDs, but OpenRGB just doesn’t seem to do anything.
Also the “brightness” slider is all the way at zero in the OpenRGB UI, but that slider is disabled and I can’t interact with it or drag it up, so I’m assuming it shouldn’t matter…
