One of the most common questions we get is "how do I add RGB underglow to my keyboard?" We've developed the following step-by-step guide to help you through the process. This guide applies to all keyboards running QMK firmware on common ATMEGA32U4-based microcontrollers, such as the Pro Micro or Elite-C.
What will I need?
In additinon to your keyboard, you will need:
- About half an hour per RGB strip
Understanding the RGB strip
WS2812B RGB LED strip is very easy to use. Each marked section of plastic strip contains all of the components needed to support the attached RGB LED. The strip can be cut at any of the marked lines, making it super simple to get the exact length of strip needed for your build.
Beyond that, our only concern is understanding the pins, which are:
- VCC (+5V)
- DIN (Data In)
- DO (Data Out)
When wiring the strip, VCC and GND can be attached at any point along the strip. Use whatever position is convenient.
The connections for DIN and DO are more specific. If you look closely, you'll notice each section is marked with a black arrow. The arrow indicates the direction of the "data flow" away from the controller. The DIN line must be connected at the starting end of the strip, with the arrows pointing away from the connection. The DO pin is used to connect multiple strips together. The DO from the first strip is connected to the DIN on the next strip in the series. Any number of individual strips may be connected this way.
Wiring it all up
The first step is to decide how many LEDs you want to use and where they will be mounted. A single controller can push about 30-40 LEDs. Consider breaking up your total into a few separate strips in order to get maximum coverage. I prefer to go ahead and mount them in place immediately. This way, you can make your wiring as minimal as possible. Simply remove the paper backing on the strip to expose the adhesive. Press them firmly down on the surface and hold for about 20 seconds to ensure maximum adhesion. Be sure to orient the strips so the arrows make a logical progression away from the controller.
Cut your hookup wires to length. Remove about 2mm of insulation from each end, then tin each wire. Be sure to use some flux to help the solder flow. (Use eye protection and good ventilation. Solder fumes are nasty!) While you're at it, flux and tin each pad you plan to use on the LED strips as well. That will ensure everything stays clean and makes final soldering a breeze.
I prefer to start wiring with the DIN and DO connections first because they are in the middle of the three pads on the strip. They're easier to access if you don't have to work between the other wires. Beginning at the controller, run a line from the D3 pad (top left pad when controller is connector end up) to the DIN of the first LED strip. Because the LEDs will be referenced in sequence by the controller, you must solder to the cut end of the strip with the arrows facing away from the connection. At the other end of the strip, continue by connecting the DO pin to the DIN on the next strip, if applicable. Do the same for all remaining strips.
Back at the controller, we'll now run the lines for VCC and GND. The process is the same for each. Using VCC as the example, solder the line to the corresponding pin on the controller. See pinout diagrams for reference. On the LED strip you can solder to any VCC pad. It can be on the same end you connected the DIN line, or any other VCC pad on the strip that is convenient. Similarly, you can connect the VCC of any additional strips to each other in this way, making it easy to run power to all the strips in the series. See the diagrams for examples.
Note that split keyboards are wired exactly like two individual keyboards.
That's all there is to the wiring. Easy, right?
Editing the firmware
Now that all your fancy new hardware is installed, you'll need a way to control it. We'll need to make some edits to QMK to accomplish this. Setting up a QMK environment and compiling the firmware is beyond the scope of this article, but there are lots of good tutorials out there if you're just getting started.
You'll want to add lighting controls to a layer in your keymap.c file. See the QMK docs on lighting for reference. Typically, I add a minimal number of keys to one of my alternate layers. I like to add:
- RGB Toggle (RGB_TOG) - Toggle RGB lighting on or off
- RGB Mode (RGB_MOD) - Cycle through available lighting modes, reverse direction when Shift is held
- RGB Hue (RGB_HUI) - Increase hue (color), decrease hue when Shift is held
- RGB Saturation (RGB_SAI) - Increase saturation, decrease saturation when Shift is held
- RGB Vibrance (RGB_VAI) - Increase value (brightness), decrease value when Shift is held
With those few keys you can control everything nicely, but have a good look at the docs because there are lots of options.
This is where you enable the lighting and tell the keyboard what to expect in terms of how they are arranged. Enable the lighting by defining RGBLIGHT_SPLIT. Then at minimum, you must define the data pin the LED strip is connected to using RGB_DI_PIN. Then define the number of LEDs connected using RGBLED_NUM.
The final addition is to enable the RGB animation effects by adding RGBLIGHT_ANIMATIONS.
Optionally, if you're lighting a split keyboard there is one additional step. Use RGBLED_SPLIT to define the number of LEDs connected on each half.
Compile your firmware and burn it to each of the controllers. As soon as the controller resets, you should get a response from the lighting.