X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Ffeature_rgblight.md;h=97a99599468bbaed73fd6e24340ea4134f8e1395;hb=dfab177f889fd6701e5f898c869be1bf3a2d0ef9;hp=0f1e649ef851ef238b1d590cac510c4b84594566;hpb=331288233dd5e613fa2c74b5ff6fdec94dcbdf5e;p=qmk_firmware.git diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 0f1e649ef..97a995994 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -1,144 +1,270 @@ # RGB Lighting -If you've installed addressable RGB lights on your keyboard you can control them with QMK. Currently we support the following addressable LEDs on Atmel AVR processors: +QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case. -* WS2811 and variants (WS2812, WS2812B, WS2812C, etc) -* SK6812RGBW +![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) -Some keyboards come with RGB LEDs pre-installed. Others have to have LEDs installed after the fact. See below for information on modifying your keyboard. +Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard. -## Selecting Colors +Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported): -QMK uses Hue, Saturation, and Value to set color rather than using RGB. You can use the color wheel below to see how this works. Changing the Hue will cycle around the circle. Saturation will affect the intensity of the color, which you can see as you move from the inner part to the outer part of the wheel. Value sets the overall brightness. + * WS2811, WS2812, WS2812B, WS2812C, etc. + * SK6812, SK6812MINI, SK6805 -HSV Color Wheel +These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs. -If you would like to learn more about HSV you can start with the [Wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV). +## Usage -## Configuration - -Before RGB Lighting can be used you have to enable it in `rules.mk`: +On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is not working for you, check that your `rules.mk` includes the following: - RGBLIGHT_ENABLE = yes +```make +RGBLIGHT_ENABLE = yes +``` -You can configure the behavior of the RGB lighting by defining values inside `config.h`. +At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these. -### Required Configuration +|Define |Description | +|---------------|---------------------------------------------------------------------------------------------------------| +|`RGB_DI_PIN` |The pin connected to the data pin of the LEDs | +|`RGBLED_NUM` |The number of LEDs connected | +|`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` | -At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected. +Then you should be able to use the keycodes below to change the RGB lighting to your liking. -```c -#define RGB_DI_PIN D7 // The pin the LED strip is connected to -#define RGBLED_NUM 14 // Number of LEDs in your strip -``` +### Color Selection -### Optional Configuration +QMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works. -You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define