diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/config_options.md | 2 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 62 |
2 files changed, 64 insertions, 0 deletions
diff --git a/docs/config_options.md b/docs/config_options.md index f19df022af..661cfccce6 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -190,6 +190,8 @@ If you define these options you will enable the associated feature, which may in * pin the DI on the WS2812 is hooked-up to * `#define RGBLIGHT_ANIMATIONS` * run RGB animations +* `#define RGBLIGHT_LAYERS` + * Lets you define [lighting layers](feature_rgblight.md) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. * `#define RGBLED_NUM 12` * number of LEDs * `#define RGBLIGHT_SPLIT` diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 69a6aaaed6..a000241f8b 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -172,6 +172,62 @@ const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31}; const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; ``` +## Lighting Layers + +By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make +it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. + +To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently: + +```c +// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore! +const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS( + {6, 4, HSV_RED}, // Light 4 LEDs, starting with LED 6 + {12, 4, HSV_RED} // Light 4 LEDs, starting with LED 12 +); +// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active +const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS( + {9, 2, HSV_CYAN} +); +// Light LEDs 11 & 12 in purple when keyboard layer 2 is active +const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS( + {11, 2, HSV_PURPLE}, +); +// etc.. +``` + +We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence: + +```c +// Now define the array of layers. Later layers take precedence +const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST( + my_capslock_layer, + my_layer1_layer, // Overrides caps lock layer + my_layer2_layer // Overrides other layers +); + +void keyboard_post_init_user(void) { + // Enable the LED layers + rgblight_layers = my_rgb_layers; +} +``` + +Finally, we enable and disable the lighting layers whenever the state of the keyboard changes: + +```c +layer_state_t layer_state_set_user(layer_state_t state) { + // Both layers will light up if both kb layers are active + rgblight_set_layer_state(1, layer_state_cmp(state, 1)); + rgblight_set_layer_state(2, layer_state_cmp(state, 2)); + return state; +} + +bool led_update_user(led_t led_state) { + rgblight_set_layer_state(0, led_state.caps_lock); + return true; +} +``` + ## Functions If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include: @@ -263,6 +319,12 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2 |`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | |`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | +#### layer functions +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_get_layer_state(i)` |Returns `true` if lighting layer `i` is enabled | +|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` | + #### query |Function |Description | |-----------------------|-----------------| |