Skip to content

Commit 4580d3a

Browse files
skullydazedskullydazed
authored
RGB improvements (qmk#1684)
* Allow the knight animation to be restricted to a portion of the LED strip * Add keys for jumping directly to particular animation modes * Remove orphaned break statements * Tweak the `RGB_MODE` buttons so they cycle through the same mode. * small indentation fix
1 parent 0ce45eb commit 4580d3a

File tree

8 files changed

+699
-95
lines changed

8 files changed

+699
-95
lines changed

‎docs/feature_rgblight.md

+101-29
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,107 @@
11
# RGB Lighting
22

3-
<!-- FIXME: Describe how to use RGB Lighting here. -->
3+
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:
44

5-
## RGB Under Glow Mod
5+
* WS2811 and variants (WS2812, WS2812B, WS2812C, etc)
6+
* SK6812RGBW
7+
8+
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.
9+
10+
## Selecting Colors
11+
12+
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.
13+
14+
![gitbook/images/color-wheel.svg]
15+
16+
If you would like to learn more about HSV you can start with the [wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV).
17+
18+
## Configuration
19+
20+
Before RGB Lighting can be used you have to enable it in `rules.mk`:
21+
22+
RGBLIGHT_ENABLE = yes
23+
24+
You can configure the behavior of the RGB lighting by defining values inside `config.h`.
25+
26+
### Required Configuration
27+
28+
At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected.
29+
30+
```c
31+
#define RGB_DI_PIN D7 // The pin the LED strip is connected to
32+
#define RGBLED_NUM 14 // Number of LEDs in your strip
33+
```
34+
35+
### Optional Configuration
36+
37+
You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define <Option> <Value>` in a `config.h` at the keyboard, revision, or keymap level.
38+
39+
| Option | Default Value | Description |
40+
|--------|---------------|-------------|
41+
| `RGBLIGHT_HUE_STEP` | 10 | How many hues you want to have available. |
42+
| `RGBLIGHT_SAT_STEP` | 17 | How many steps of saturation you'd like. |
43+
| `RGBLIGHT_VAL_STEP` | 17 | The number of levels of brightness you want. |
44+
45+
### Animations
46+
47+
If you have `#define RGBLIGHT_ANIMATIONS` in your `config.h` you will have a number of animation modes you can cycle through using the `RGB_MOD` key. You can also `#define` other options to tweak certain animations.
48+
49+
| Option | Default Value | Description |
50+
|--------|---------------|-------------|
51+
| `RGBLIGHT_ANIMATIONS` | | `#define` this to enable animation modes. |
52+
| `RGBLIGHT_EFFECT_SNAKE_LENGTH` | 4 | The number of LEDs to light up for the "snake" mode. |
53+
| `RGBLIGHT_EFFECT_KNIGHT_LENGTH` | 3 | The number of LEDs to light up for the "knight" mode. |
54+
| `RGBLIGHT_EFFECT_KNIGHT_OFFSET` | 0 | Start the knight animation this many LEDs from the start of the strip. |
55+
| `RGBLIGHT_EFFECT_KNIGHT_LED_NUM` | RGBLED_NUM | The number of LEDs to have the "knight" animation travel. |
56+
| `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` | 1000 | How long to wait between light changes for the "christmas" animation. Specified in ms. |
57+
| `RGBLIGHT_EFFECT_CHRISTMAS_STEP` | 2 | How many LED's to group the red/green colors by for the christmas mode. |
58+
59+
You can also tweak the behavior of the animations by defining these consts in your `keymap.c`. These mostly affect the speed different modes animate at.
60+
61+
```c
62+
// How long (in ms) to wait between animation steps for the breathing mode
63+
const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
64+
65+
// How long (in ms) to wait between animation steps for the rainbow mode
66+
const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
67+
68+
// How long (in ms) to wait between animation steps for the swirl mode
69+
const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
70+
71+
// How long (in ms) to wait between animation steps for the snake mode
72+
const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
73+
74+
// How long (in ms) to wait between animation steps for the knight modes
75+
const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
76+
77+
// These control which colors are selected for the gradient mode
78+
const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
79+
```
80+
81+
## RGB Lighting Keycodes
82+
83+
These control the RGB Lighting functionality.
84+
85+
| Long Name | Short Name | Description |
86+
|-----------|------------|-------------|
87+
||`RGB_TOG`|toggle on/off|
88+
||`RGB_MOD`|cycle through modes|
89+
||`RGB_HUI`|hue increase|
90+
||`RGB_HUD`|hue decrease|
91+
||`RGB_SAI`|saturation increase|
92+
||`RGB_SAD`|saturation decrease|
93+
||`RGB_VAI`|value (brightness) increase|
94+
||`RGB_VAD`|value (brightness) decrease|
95+
|`RGB_MODE_PLAIN`|`RGB_M_P `| Switch to the static no animation mode |
96+
|`RGB_MODE_BREATHE`|`RGB_M_B`| Switch to the breathing mode |
97+
|`RGB_MODE_RAINBOW`|`RGB_M_R`| Switch to the rainbow mode ||
98+
|`RGB_MODE_SWIRL`|`RGB_M_SW`| Switch to the swirl mode |
99+
|`RGB_MODE_SNAKE`|`RGB_M_SN`| Switch to the snake mode |
100+
|`RGB_MODE_KNIGHT`|`RGB_M_K`| Switch to the knight animation |
101+
|`RGB_MODE_XMAS`|`RGB_M_X`| Switch to the Christmas animation |
102+
|`RGB_MODE_GRADIENT`|`RGB_M_G`| Switch to the static gradient mode |
103+
104+
## Hardware Modification
6105

7106
![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
8107

@@ -17,33 +116,6 @@ In order to use the underglow animation functions, you need to have `#define RGB
17116
Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
18117

19118
#define RGB_DI_PIN F4 // The pin your RGB strip is wired to
20-
#define RGBLIGHT_ANIMATIONS // Require for fancier stuff (not compatible with audio)
21119
#define RGBLED_NUM 14 // Number of LEDs
22-
#define RGBLIGHT_HUE_STEP 10
23-
#define RGBLIGHT_SAT_STEP 17
24-
#define RGBLIGHT_VAL_STEP 17
25120

26121
You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
27-
28-
The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboards/planck/keymaps/yang/keymap.c`
29-
30-
### WS2812 Wiring
31-
32-
![WS2812 Wiring](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/WS2812-wiring.jpg)
33-
34-
Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
35-
36-
## RGB Lighting Keycodes
37-
38-
This controls the RGB Lighting functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting.
39-
40-
|Name|Description|
41-
|----|-----------|
42-
|`RGB_TOG`|toggle on/off|
43-
|`RGB_MOD`|cycle through modes|
44-
|`RGB_HUI`|hue increase|
45-
|`RGB_HUD`|hue decrease|
46-
|`RGB_SAI`|saturation increase|
47-
|`RGB_SAD`|saturation decrease|
48-
|`RGB_VAI`|value increase|
49-
|`RGB_VAD`|value decrease|

0 commit comments

Comments
 (0)