rgb_matrix.md (42752B)
1 # RGB Matrix Lighting {#rgb-matrix-lighting} 2 3 This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it. 4 5 If you want to use single color LED's you should use the [LED Matrix Subsystem](led_matrix) instead. 6 7 ## Driver Configuration {#driver-configuration} 8 9 RGB Matrix is an abstraction layer on top of an underlying LED driver API. The list of supported LED drivers is below; see the respective documentation for information on how to configure the driver. 10 11 |Driver |Max LEDs| 12 |-------------------------------------|--------| 13 |[APA102](../drivers/apa102) |? | 14 |[AW20216S](../drivers/aw20216s) |72 | 15 |[IS31FL3218](../drivers/is31fl3218) |6 | 16 |[IS31FL3236](../drivers/is31fl3236) |12 | 17 |[IS31FL3729](../drivers/is31fl3729) |45 | 18 |[IS31FL3731](../drivers/is31fl3731) |48 | 19 |[IS31FL3733](../drivers/is31fl3733) |64 | 20 |[IS31FL3736](../drivers/is31fl3736) |32 | 21 |[IS31FL3737](../drivers/is31fl3737) |48 | 22 |[IS31FL3741](../drivers/is31fl3741) |117 | 23 |[IS31FL3742A](../drivers/is31fl3742a)|60 | 24 |[IS31FL3743A](../drivers/is31fl3743a)|66 | 25 |[IS31FL3745](../drivers/is31fl3745) |48 | 26 |[IS31FL3746A](../drivers/is31fl3746a)|24 | 27 |[SNLED27351](../drivers/snled27351) |64 | 28 |[WS2812](../drivers/ws2812) |? | 29 30 To assign the RGB Matrix driver, add the following to your `rules.mk`, for example: 31 32 ```make 33 RGB_MATRIX_DRIVER = is31fl3218 34 ``` 35 36 ## Common Configuration {#common-configuration} 37 38 From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: 39 40 ```c 41 led_config_t g_led_config = { { 42 // Key Matrix to LED Index 43 { 5, NO_LED, NO_LED, 0 }, 44 { NO_LED, NO_LED, NO_LED, NO_LED }, 45 { 4, NO_LED, NO_LED, 1 }, 46 { 3, NO_LED, NO_LED, 2 } 47 }, { 48 // LED Index to Physical Position 49 { 188, 16 }, { 187, 48 }, { 149, 64 }, { 112, 64 }, { 37, 48 }, { 38, 16 } 50 }, { 51 // LED Index to Flag 52 1, 4, 4, 4, 4, 1 53 } }; 54 ``` 55 56 The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position: 57 58 ```c 59 x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION 60 y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION 61 ``` 62 63 Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout. 64 65 As mentioned earlier, the center of the keyboard by default is expected to be `{ 112, 32 }`, but this can be changed if you want to more accurately calculate the LED's physical `{ x, y }` positions. Keyboard designers can implement `#define RGB_MATRIX_CENTER { 112, 32 }` in their config.h file with the new center point of the keyboard, or where they want it to be allowing more possibilities for the `{ x, y }` values. Do note that the maximum value for x or y is 255, and the recommended maximum is 224 as this gives animations runoff room before they reset. 66 67 `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. 68 69 ## Flags {#flags} 70 71 |Define |Value |Description | 72 |----------------------------|------|-------------------------------------------------| 73 |`HAS_FLAGS(bits, flags)` |*n/a* |Evaluates to `true` if `bits` has all `flags` set| 74 |`HAS_ANY_FLAGS(bits, flags)`|*n/a* |Evaluates to `true` if `bits` has any `flags` set| 75 |`LED_FLAG_NONE` |`0x00`|If this LED has no flags | 76 |`LED_FLAG_ALL` |`0xFF`|If this LED has all flags | 77 |`LED_FLAG_MODIFIER` |`0x01`|If the LED is on a modifier key | 78 |`LED_FLAG_UNDERGLOW` |`0x02`|If the LED is for underglow | 79 |`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight | 80 |`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication | 81 82 ## Keycodes {#keycodes} 83 84 |Key |Aliases |Description | 85 |-------------------------------|---------|-----------------------------------| 86 |`QK_RGB_MATRIX_ON` |`RM_ON` |Turn on RGB Matrix | 87 |`QK_RGB_MATRIX_OFF` |`RM_OFF` |Turn off RGB Matrix | 88 |`QK_RGB_MATRIX_TOGGLE` |`RM_TOGG`|Toggle RGB Matrix on or off | 89 |`QK_RGB_MATRIX_MODE_NEXT` |`RM_NEXT`|Cycle through animations | 90 |`QK_RGB_MATRIX_MODE_PREVIOUS` |`RM_PREV`|Cycle through animations in reverse| 91 |`QK_RGB_MATRIX_HUE_UP` |`RM_HUEU`|Cycle through hue | 92 |`QK_RGB_MATRIX_HUE_DOWN` |`RM_HUED`|Cycle through hue in reverse | 93 |`QK_RGB_MATRIX_SATURATION_UP` |`RM_SATU`|Increase the saturation | 94 |`QK_RGB_MATRIX_SATURATION_DOWN`|`RM_SATD`|Decrease the saturation | 95 |`QK_RGB_MATRIX_VALUE_UP` |`RM_VALU`|Increase the brightness level | 96 |`QK_RGB_MATRIX_VALUE_DOWN` |`RM_VALD`|Decrease the brightness level | 97 |`QK_RGB_MATRIX_SPEED_UP` |`RM_SPDU`|Increase the animation speed | 98 |`QK_RGB_MATRIX_SPEED_DOWN` |`RM_SPDD`|Decrease the animation speed | 99 |`QK_RGB_MATRIX_FLAG_NEXT` |`RM_FLGN`|Cycle through flags | 100 |`QK_RGB_MATRIX_FLAG_PREVIOUS` |`RM_FLGP`|Cycle through flags in reverse | 101 102 ## RGB Matrix Effects {#rgb-matrix-effects} 103 104 All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available: 105 106 ```c 107 enum rgb_matrix_effects { 108 RGB_MATRIX_NONE = 0, 109 RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support 110 RGB_MATRIX_ALPHAS_MODS, // Static dual hue, speed is hue for secondary hue 111 RGB_MATRIX_GRADIENT_UP_DOWN, // Static gradient top to bottom, speed controls how much gradient changes 112 RGB_MATRIX_GRADIENT_LEFT_RIGHT, // Static gradient left to right, speed controls how much gradient changes 113 RGB_MATRIX_BREATHING, // Single hue brightness cycling animation 114 RGB_MATRIX_BAND_SAT, // Single hue band fading saturation scrolling left to right 115 RGB_MATRIX_BAND_VAL, // Single hue band fading brightness scrolling left to right 116 RGB_MATRIX_BAND_PINWHEEL_SAT, // Single hue 3 blade spinning pinwheel fades saturation 117 RGB_MATRIX_BAND_PINWHEEL_VAL, // Single hue 3 blade spinning pinwheel fades brightness 118 RGB_MATRIX_BAND_SPIRAL_SAT, // Single hue spinning spiral fades saturation 119 RGB_MATRIX_BAND_SPIRAL_VAL, // Single hue spinning spiral fades brightness 120 RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient 121 RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right 122 RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom 123 RGB_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in 124 RGB_MATRIX_CYCLE_OUT_IN_DUAL, // Full dual gradients scrolling out to in 125 RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradient Chevron shapped scrolling left to right 126 RGB_MATRIX_CYCLE_PINWHEEL, // Full gradient spinning pinwheel around center of keyboard 127 RGB_MATRIX_CYCLE_SPIRAL, // Full gradient spinning spiral around center of keyboard 128 RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard 129 RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard 130 RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halves of keyboard 131 RGB_MATRIX_FLOWER_BLOOMING, // Full tighter gradient of first half scrolling left to right and second half scrolling right to left 132 RGB_MATRIX_RAINDROPS, // Randomly changes a single key's hue 133 RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation 134 RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight amount at the same time, then shifts back 135 RGB_MATRIX_HUE_PENDULUM, // Hue shifts up a slight amount in a wave to the right, then back to the left 136 RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight amount and then back down in a wave to the right 137 RGB_MATRIX_PIXEL_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges 138 RGB_MATRIX_PIXEL_FLOW, // Pulsing RGB flow along LED wiring with random hues 139 RGB_MATRIX_PIXEL_RAIN, // Randomly light keys with random hues 140 RGB_MATRIX_TYPING_HEATMAP, // How hot is your WPM! 141 RGB_MATRIX_DIGITAL_RAIN, // That famous computer simulation 142 RGB_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit to hue & value then fades value out 143 RGB_MATRIX_SOLID_REACTIVE, // Static single hue, pulses keys hit to shifted hue then fades to current hue 144 RGB_MATRIX_SOLID_REACTIVE_WIDE, // Hue & value pulse near a single key hit then fades value out 145 RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE, // Hue & value pulse near multiple key hits then fades value out 146 RGB_MATRIX_SOLID_REACTIVE_CROSS, // Hue & value pulse the same column and row of a single key hit then fades value out 147 RGB_MATRIX_SOLID_REACTIVE_MULTICROSS, // Hue & value pulse the same column and row of multiple key hits then fades value out 148 RGB_MATRIX_SOLID_REACTIVE_NEXUS, // Hue & value pulse away on the same column and row of a single key hit then fades value out 149 RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS, // Hue & value pulse away on the same column and row of multiple key hits then fades value out 150 RGB_MATRIX_SPLASH, // Full gradient & value pulse away from a single key hit then fades value out 151 RGB_MATRIX_MULTISPLASH, // Full gradient & value pulse away from multiple key hits then fades value out 152 RGB_MATRIX_SOLID_SPLASH, // Hue & value pulse away from a single key hit then fades value out 153 RGB_MATRIX_SOLID_MULTISPLASH, // Hue & value pulse away from multiple key hits then fades value out 154 RGB_MATRIX_STARLIGHT, // LEDs turn on and off at random at varying brightness, maintaining user set color 155 RGB_MATRIX_STARLIGHT_SMOOTH, // LEDs slowly increase and decrease in brightness randomly 156 RGB_MATRIX_STARLIGHT_DUAL_HUE, // LEDs turn on and off at random at varying brightness, modifies user set hue by +- 30 157 RGB_MATRIX_STARLIGHT_DUAL_SAT, // LEDs turn on and off at random at varying brightness, modifies user set saturation by +- 30 158 RGB_MATRIX_RIVERFLOW, // Modification to breathing animation, offset's animation depending on key location to simulate a river flowing 159 RGB_MATRIX_EFFECT_MAX 160 }; 161 ``` 162 163 You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `config.h`: 164 165 166 |Define |Description | 167 |------------------------------------------------------|----------------------------------------------| 168 |`#define ENABLE_RGB_MATRIX_ALPHAS_MODS` |Enables `RGB_MATRIX_ALPHAS_MODS` | 169 |`#define ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Enables `RGB_MATRIX_GRADIENT_UP_DOWN` | 170 |`#define ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Enables `RGB_MATRIX_GRADIENT_LEFT_RIGHT` | 171 |`#define ENABLE_RGB_MATRIX_BREATHING` |Enables `RGB_MATRIX_BREATHING` | 172 |`#define ENABLE_RGB_MATRIX_BAND_SAT` |Enables `RGB_MATRIX_BAND_SAT` | 173 |`#define ENABLE_RGB_MATRIX_BAND_VAL` |Enables `RGB_MATRIX_BAND_VAL` | 174 |`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Enables `RGB_MATRIX_BAND_PINWHEEL_SAT` | 175 |`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Enables `RGB_MATRIX_BAND_PINWHEEL_VAL` | 176 |`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Enables `RGB_MATRIX_BAND_SPIRAL_SAT` | 177 |`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Enables `RGB_MATRIX_BAND_SPIRAL_VAL` | 178 |`#define ENABLE_RGB_MATRIX_CYCLE_ALL` |Enables `RGB_MATRIX_CYCLE_ALL` | 179 |`#define ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Enables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | 180 |`#define ENABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Enables `RGB_MATRIX_CYCLE_UP_DOWN` | 181 |`#define ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Enables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | 182 |`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN` |Enables `RGB_MATRIX_CYCLE_OUT_IN` | 183 |`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Enables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | 184 |`#define ENABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Enables `RGB_MATRIX_CYCLE_PINWHEEL` | 185 |`#define ENABLE_RGB_MATRIX_CYCLE_SPIRAL` |Enables `RGB_MATRIX_CYCLE_SPIRAL` | 186 |`#define ENABLE_RGB_MATRIX_DUAL_BEACON` |Enables `RGB_MATRIX_DUAL_BEACON` | 187 |`#define ENABLE_RGB_MATRIX_RAINBOW_BEACON` |Enables `RGB_MATRIX_RAINBOW_BEACON` | 188 |`#define ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Enables `RGB_MATRIX_RAINBOW_PINWHEELS` | 189 |`#define ENABLE_RGB_MATRIX_FLOWER_BLOOMING` |Enables `RGB_MATRIX_FLOWER_BLOOMING` | 190 |`#define ENABLE_RGB_MATRIX_RAINDROPS` |Enables `RGB_MATRIX_RAINDROPS` | 191 |`#define ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Enables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | 192 |`#define ENABLE_RGB_MATRIX_HUE_BREATHING` |Enables `RGB_MATRIX_HUE_BREATHING` | 193 |`#define ENABLE_RGB_MATRIX_HUE_PENDULUM` |Enables `RGB_MATRIX_HUE_PENDULUM` | 194 |`#define ENABLE_RGB_MATRIX_HUE_WAVE` |Enables `RGB_MATRIX_HUE_WAVE ` | 195 |`#define ENABLE_RGB_MATRIX_PIXEL_FRACTAL` |Enables `RGB_MATRIX_PIXEL_FRACTAL` | 196 |`#define ENABLE_RGB_MATRIX_PIXEL_FLOW` |Enables `RGB_MATRIX_PIXEL_FLOW` | 197 |`#define ENABLE_RGB_MATRIX_PIXEL_RAIN` |Enables `RGB_MATRIX_PIXEL_RAIN` | 198 |`#define ENABLE_RGB_MATRIX_STARLIGHT` |Enables `RGB_MATRIX_STARLIGHT` | 199 |`#define ENABLE_RGB_MATRIX_STARLIGHT_SMOOTH` |Enables `RGB_MATRIX_STARLIGHT_SMOOTH` | 200 |`#define ENABLE_RGB_MATRIX_STARLIGHT_DUAL_HUE` |Enables `RGB_MATRIX_STARLIGHT_DUAL_HUE` | 201 |`#define ENABLE_RGB_MATRIX_STARLIGHT_DUAL_SAT` |Enables `RGB_MATRIX_STARLIGHT_DUAL_SAT` | 202 |`#define ENABLE_RGB_MATRIX_RIVERFLOW` |Enables `RGB_MATRIX_RIVERFLOW` | 203 204 |Framebuffer Defines |Description | 205 |------------------------------------------------------|----------------------------------------------| 206 |`#define ENABLE_RGB_MATRIX_TYPING_HEATMAP` |Enables `RGB_MATRIX_TYPING_HEATMAP` | 207 |`#define ENABLE_RGB_MATRIX_DIGITAL_RAIN` |Enables `RGB_MATRIX_DIGITAL_RAIN` | 208 209 ::: tip 210 These modes introduce additional logic that can increase firmware size. 211 ::: 212 213 |Reactive Defines |Description | 214 |------------------------------------------------------|----------------------------------------------| 215 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` | 216 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE` |Enables `RGB_MATRIX_SOLID_REACTIVE` | 217 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_WIDE` | 218 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` | 219 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_CROSS` | 220 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`| 221 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` | 222 |`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`| 223 |`#define ENABLE_RGB_MATRIX_SPLASH` |Enables `RGB_MATRIX_SPLASH` | 224 |`#define ENABLE_RGB_MATRIX_MULTISPLASH` |Enables `RGB_MATRIX_MULTISPLASH` | 225 |`#define ENABLE_RGB_MATRIX_SOLID_SPLASH` |Enables `RGB_MATRIX_SOLID_SPLASH` | 226 |`#define ENABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Enables `RGB_MATRIX_SOLID_MULTISPLASH` | 227 228 ::: tip 229 These modes introduce additional logic that can increase firmware size. 230 ::: 231 232 233 ### RGB Matrix Effect Typing Heatmap {#rgb-matrix-effect-typing-heatmap} 234 235 This effect will color the RGB matrix according to a heatmap of recently pressed keys. Whenever a key is pressed its "temperature" increases as well as that of its neighboring keys. The temperature of each key is then decreased automatically every 25 milliseconds by default. 236 237 In order to change the delay of temperature decrease define `RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS`: 238 239 ```c 240 #define RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 50 241 ``` 242 243 As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`. 244 245 Limit the distance the effect spreads to surrounding keys. 246 247 ```c 248 #define RGB_MATRIX_TYPING_HEATMAP_SPREAD 40 249 ``` 250 251 Limit how hot surrounding keys get from each press. 252 253 ```c 254 #define RGB_MATRIX_TYPING_HEATMAP_AREA_LIMIT 16 255 ``` 256 257 Remove the spread effect entirely. 258 259 ```c 260 #define RGB_MATRIX_TYPING_HEATMAP_SLIM 261 ``` 262 263 It's also possible to adjust the tempo of *heating up*. It's defined as the number of shades that are 264 increased on the [HSV scale](https://en.wikipedia.org/wiki/HSL_and_HSV). Decreasing this value increases 265 the number of keystrokes needed to fully heat up the key. 266 267 ```c 268 #define RGB_MATRIX_TYPING_HEATMAP_INCREASE_STEP 32 269 ``` 270 271 ### RGB Matrix Effect Solid Reactive {#rgb-matrix-effect-solid-reactive} 272 273 Solid reactive effects will pulse RGB light on key presses with user configurable hues. To enable gradient mode that will automatically change reactive color, add the following define: 274 275 ```c 276 #define RGB_MATRIX_SOLID_REACTIVE_GRADIENT_MODE 277 ``` 278 279 Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RM_SPDU`/`RM_SPDD`). 280 281 ## Custom RGB Matrix Effects {#custom-rgb-matrix-effects} 282 283 By setting `RGB_MATRIX_CUSTOM_USER = yes` in `rules.mk`, new effects can be defined directly from your keymap or userspace, without having to edit any QMK core files. To declare new effects, create a `rgb_matrix_user.inc` file in the user keymap directory or userspace folder. 284 285 ::: tip 286 Hardware maintainers who want to limit custom effects to a specific keyboard can create a `rgb_matrix_kb.inc` file in the root of the keyboard directory, and add `RGB_MATRIX_CUSTOM_KB = yes` to the keyboard level `rules.mk`. 287 ::: 288 289 ```c 290 // !!! DO NOT ADD #pragma once !!! // 291 292 // Step 1. 293 // Declare custom effects using the RGB_MATRIX_EFFECT macro 294 // (note the lack of semicolon after the macro!) 295 RGB_MATRIX_EFFECT(my_cool_effect) 296 RGB_MATRIX_EFFECT(my_cool_effect2) 297 298 // Step 2. 299 // Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block 300 #ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS 301 302 // e.g: A simple effect, self-contained within a single method 303 static bool my_cool_effect(effect_params_t* params) { 304 RGB_MATRIX_USE_LIMITS(led_min, led_max); 305 for (uint8_t i = led_min; i < led_max; i++) { 306 rgb_matrix_set_color(i, 0xff, 0xff, 0x00); 307 } 308 return rgb_matrix_check_finished_leds(led_max); 309 } 310 311 // e.g: A more complex effect, relying on external methods and state, with 312 // dedicated init and run methods 313 static uint8_t some_global_state; 314 static void my_cool_effect2_complex_init(effect_params_t* params) { 315 some_global_state = 1; 316 } 317 static bool my_cool_effect2_complex_run(effect_params_t* params) { 318 RGB_MATRIX_USE_LIMITS(led_min, led_max); 319 for (uint8_t i = led_min; i < led_max; i++) { 320 rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff); 321 } 322 return rgb_matrix_check_finished_leds(led_max); 323 } 324 static bool my_cool_effect2(effect_params_t* params) { 325 if (params->init) my_cool_effect2_complex_init(params); 326 return my_cool_effect2_complex_run(params); 327 } 328 329 #endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS 330 ``` 331 332 To switch to your custom effect programmatically, simply call `rgb_matrix_mode()` and prepend `RGB_MATRIX_CUSTOM_` to the effect name you specified in `RGB_MATRIX_EFFECT()`. For example, an effect declared as `RGB_MATRIX_EFFECT(my_cool_effect)` would be referenced with: 333 334 ```c 335 rgb_matrix_mode(RGB_MATRIX_CUSTOM_my_cool_effect); 336 ``` 337 338 For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix/animations/`. 339 340 341 ## Colors {#colors} 342 343 These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. 344 345 |RGB |HSV | 346 |---------------------|---------------------| 347 |`RGB_AZURE` |`HSV_AZURE` | 348 |`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`| 349 |`RGB_BLUE` |`HSV_BLUE` | 350 |`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | 351 |`RGB_CORAL` |`HSV_CORAL` | 352 |`RGB_CYAN` |`HSV_CYAN` | 353 |`RGB_GOLD` |`HSV_GOLD` | 354 |`RGB_GOLDENROD` |`HSV_GOLDENROD` | 355 |`RGB_GREEN` |`HSV_GREEN` | 356 |`RGB_MAGENTA` |`HSV_MAGENTA` | 357 |`RGB_ORANGE` |`HSV_ORANGE` | 358 |`RGB_PINK` |`HSV_PINK` | 359 |`RGB_PURPLE` |`HSV_PURPLE` | 360 |`RGB_RED` |`HSV_RED` | 361 |`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | 362 |`RGB_TEAL` |`HSV_TEAL` | 363 |`RGB_TURQUOISE` |`HSV_TURQUOISE` | 364 |`RGB_WHITE` |`HSV_WHITE` | 365 |`RGB_YELLOW` |`HSV_YELLOW` | 366 367 These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list! 368 369 370 ## Naming 371 372 If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `rgb_matrix_get_mode_name` in the following manner: 373 374 In your keymap's `config.h`: 375 ```c 376 #define RGB_MATRIX_MODE_NAME_ENABLE 377 ``` 378 379 In your `keymap.c` 380 ```c 381 const char* effect_name = rgb_matrix_get_mode_name(rgb_matrix_get_mode()); 382 // do something with `effect_name`, like `oled_write_ln(effect_name, false);` 383 ``` 384 385 ::: info 386 `rgb_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled. 387 ::: 388 389 390 ## Additional `config.h` Options {#additional-configh-options} 391 392 ```c 393 #define RGB_MATRIX_MODE_NAME_ENABLE // enables rgb_matrix_get_mode_name() 394 #define RGB_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses) 395 #define RGB_MATRIX_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off 396 #define RGB_MATRIX_SLEEP // turn off effects when suspended 397 #define RGB_MATRIX_LED_PROCESS_LIMIT (RGB_MATRIX_LED_COUNT + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness) 398 #define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness) 399 #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255 400 #define RGB_MATRIX_DEFAULT_ON true // Sets the default enabled state, if none has been set 401 #define RGB_MATRIX_DEFAULT_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set 402 #define RGB_MATRIX_DEFAULT_HUE 0 // Sets the default hue value, if none has been set 403 #define RGB_MATRIX_DEFAULT_SAT 255 // Sets the default saturation value, if none has been set 404 #define RGB_MATRIX_DEFAULT_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set 405 #define RGB_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set 406 #define RGB_MATRIX_HUE_STEP 8 // The value by which to increment the hue per adjustment action 407 #define RGB_MATRIX_SAT_STEP 16 // The value by which to increment the saturation per adjustment action 408 #define RGB_MATRIX_VAL_STEP 16 // The value by which to increment the brightness per adjustment action 409 #define RGB_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action 410 #define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set 411 #define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right. 412 // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR 413 #define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards 414 #define RGB_MATRIX_FLAG_STEPS { LED_FLAG_ALL, LED_FLAG_KEYLIGHT | LED_FLAG_MODIFIER, LED_FLAG_UNDERGLOW, LED_FLAG_NONE } // Sets the flags which can be cycled through. 415 ``` 416 417 ## EEPROM storage {#eeprom-storage} 418 419 The EEPROM for it is currently shared with the LED Matrix system (it's generally assumed only one feature would be used at a time). 420 421 ## Callbacks {#callbacks} 422 423 ### Indicators {#indicators} 424 425 If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, then you can use the `rgb_matrix_indicators_kb` function on the keyboard level source file, or `rgb_matrix_indicators_user` function in the user `keymap.c`. 426 ```c 427 bool rgb_matrix_indicators_kb(void) { 428 if (!rgb_matrix_indicators_user()) { 429 return false; 430 } 431 rgb_matrix_set_color(index, red, green, blue); 432 return true; 433 } 434 ``` 435 436 In addition, there are the advanced indicator functions. These are aimed at those with heavily customized displays, where rendering every LED per cycle is expensive. Such as some of the "drashna" layouts. This includes a special macro to help make this easier to use: `RGB_MATRIX_INDICATOR_SET_COLOR(i, r, g, b)`. 437 438 ```c 439 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 440 RGB_MATRIX_INDICATOR_SET_COLOR(index, red, green, blue); 441 return false; 442 } 443 ``` 444 445 ### Indicator Examples {#indicator-examples} 446 447 Caps Lock indicator on alphanumeric flagged keys: 448 ```c 449 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 450 if (host_keyboard_led_state().caps_lock) { 451 for (uint8_t i = led_min; i < led_max; i++) { 452 if (g_led_config.flags[i] & LED_FLAG_KEYLIGHT) { 453 rgb_matrix_set_color(i, RGB_RED); 454 } 455 } 456 } 457 return false; 458 } 459 ``` 460 461 Layer indicator on all keys: 462 ```c 463 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 464 for (uint8_t i = led_min; i < led_max; i++) { 465 switch(get_highest_layer(layer_state|default_layer_state)) { 466 case 2: 467 rgb_matrix_set_color(i, RGB_BLUE); 468 break; 469 case 1: 470 rgb_matrix_set_color(i, RGB_YELLOW); 471 break; 472 default: 473 break; 474 } 475 } 476 return false; 477 } 478 ``` 479 480 Layer indicator only on keys with configured keycodes: 481 ```c 482 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 483 if (get_highest_layer(layer_state) > 0) { 484 uint8_t layer = get_highest_layer(layer_state); 485 486 for (uint8_t row = 0; row < MATRIX_ROWS; ++row) { 487 for (uint8_t col = 0; col < MATRIX_COLS; ++col) { 488 uint8_t index = g_led_config.matrix_co[row][col]; 489 490 if (index >= led_min && index < led_max && index != NO_LED && 491 keymap_key_to_keycode(layer, (keypos_t){col,row}) > KC_TRNS) { 492 rgb_matrix_set_color(index, RGB_GREEN); 493 } 494 } 495 } 496 } 497 return false; 498 } 499 ``` 500 501 ::: tip 502 Split keyboards will require layer state data syncing with `#define SPLIT_LAYER_STATE_ENABLE`. See [Data Sync Options](split_keyboard#data-sync-options) for more details. 503 ::: 504 505 #### Examples {#indicator-examples-2} 506 507 This example sets the modifiers to be a specific color based on the layer state. You can use a switch case here, instead, if you would like. This uses HSV and then converts to RGB, because this allows the brightness to be limited (important when using the WS2812 driver). 508 509 ```c 510 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 511 hsv_t hsv = {0, 255, 255}; 512 513 if (get_highest_layer(layer_state|default_layer_state) == 2) { 514 hsv = (hsv_t){130, 255, 255}; 515 } else { 516 hsv = (hsv_t){30, 255, 255}; 517 } 518 519 if (hsv.v > rgb_matrix_get_val()) { 520 hsv.v = rgb_matrix_get_val(); 521 } 522 rgb_t rgb = hsv_to_rgb(hsv); 523 524 for (uint8_t i = led_min; i < led_max; i++) { 525 if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER 526 rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b); 527 } 528 } 529 return false; 530 } 531 ``` 532 533 If you want to indicate a Host LED status (caps lock, num lock, etc), you can use something like this to light up the caps lock key: 534 535 ```c 536 bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 537 if (host_keyboard_led_state().caps_lock) { 538 RGB_MATRIX_INDICATOR_SET_COLOR(5, 255, 255, 255); // assuming caps lock is at led #5 539 } else { 540 RGB_MATRIX_INDICATOR_SET_COLOR(5, 0, 0, 0); 541 } 542 return false; 543 } 544 ``` 545 546 ::: tip 547 RGB indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](split_keyboard#data-sync-options) for more details. 548 ::: 549 550 #### Indicators without RGB Matrix Effect 551 552 If you want to just use RGB indicators without RGB matrix effect, it is not possible to disable the latter because toggling RGB off will disable everything. You can workaround it with solid effect and colors off using this init function: 553 ```c 554 void keyboard_post_init_user(void) { 555 rgb_matrix_mode_noeeprom(RGB_MATRIX_SOLID_COLOR); 556 rgb_matrix_sethsv_noeeprom(HSV_OFF); 557 } 558 ``` 559 560 ## API {#api} 561 562 ### `void rgb_matrix_toggle(void)` {#api-rgb-matrix-toggle} 563 564 Toggle RGB Matrix on or off. 565 566 --- 567 568 ### `void rgb_matrix_toggle_noeeprom(void)` {#api-rgb-matrix-toggle-noeeprom} 569 570 Toggle RGB Matrix on or off. New state is not written to EEPROM. 571 572 --- 573 574 ### `void rgb_matrix_enable(void)` {#api-rgb-matrix-enable} 575 576 Turn RGB Matrix on. 577 578 --- 579 580 ### `void rgb_matrix_enable_noeeprom(void)` {#api-rgb-matrix-enable-noeeprom} 581 582 Turn RGB Matrix on. New state is not written to EEPROM. 583 584 --- 585 586 ### `void rgb_matrix_disable(void)` {#api-rgb-matrix-disable} 587 588 Turn RGB Matrix off. 589 590 --- 591 592 ### `void rgb_matrix_disable_noeeprom(void)` {#api-rgb-matrix-disable-noeeprom} 593 594 Turn RGB Matrix off. New state is not written to EEPROM. 595 596 --- 597 598 ### `bool rgb_matrix_is_enabled(void)` {#api-rgb-matrix-is-enabled} 599 600 Get the current enabled state of RGB Matrix. 601 602 #### Return Value {#api-rgb-matrix-is-enabled-return} 603 604 `true` if RGB Matrix is enabled. 605 606 --- 607 608 ### `void rgb_matrix_set_color(uint8_t index, uint8_t r, uint8_t g, uint8_t b)` {#api-rgb-matrix-set-color} 609 610 Set the color of a single LED. 611 612 This function can only be run from within an effect or indicator callback, otherwise the currently running animation will simply overwrite it on the next frame. 613 614 #### Arguments {#api-rgb-matrix-set-color-arguments} 615 616 - `uint8_t index` 617 The LED index, from 0 to `RGB_MATRIX_LED_COUNT - 1`. 618 - `uint8_t r` 619 The red value to set. 620 - `uint8_t g` 621 The green value to set. 622 - `uint8_t b` 623 The blue value to set. 624 625 --- 626 627 ### `void rgb_matrix_set_color_all(uint8_t r, uint8_t g, uint8_t b)` {#api-rgb-matrix-set-color-all} 628 629 Set the color of all LEDs. 630 631 This function can only be run from within an effect or indicator callback, otherwise the currently running animation will simply overwrite it on the next frame. 632 633 #### Arguments {#api-rgb-matrix-set-color-all-arguments} 634 635 - `uint8_t r` 636 The red value to set. 637 - `uint8_t g` 638 The green value to set. 639 - `uint8_t b` 640 The blue value to set. 641 642 --- 643 644 ### `void rgb_matrix_mode(uint8_t mode)` {#api-rgb-matrix-mode} 645 646 Set the currently running effect. 647 648 #### Arguments {#api-rgb-matrix-mode-arguments} 649 650 - `uint8_t mode` 651 The effect to switch to. 652 653 --- 654 655 ### `void rgb_matrix_mode_noeeprom(uint8_t mode)` {#api-rgb-matrix-mode-noeeprom} 656 657 Set the currently running effect. New state is not written to EEPROM. 658 659 #### Arguments {#api-rgb-matrix-mode-noeeprom-arguments} 660 661 - `uint8_t mode` 662 The effect to switch to. 663 664 --- 665 666 ### `void rgb_matrix_step(void)` {#api-rgb-matrix-step} 667 668 Move to the next enabled effect. 669 670 --- 671 672 ### `void rgb_matrix_step_noeeprom(void)` {#api-rgb-matrix-step-noeeprom} 673 674 Move to the next enabled effect. New state is not written to EEPROM. 675 676 --- 677 678 ### `void rgb_matrix_step_reverse(void)` {#api-rgb-matrix-step-reverse} 679 680 Move to the previous enabled effect. 681 682 --- 683 684 ### `void rgb_matrix_step_reverse_noeeprom(void)` {#api-rgb-matrix-step-reverse-noeeprom} 685 686 Move to the previous enabled effect. New state is not written to EEPROM. 687 688 --- 689 690 ### `uint8_t rgb_matrix_get_mode(void)` {#api-rgb-matrix-get-mode} 691 692 Get the currently running effect. 693 694 #### Return Value {#api-rgb-matrix-get-mode-return} 695 696 The index of the currently running effect. 697 698 --- 699 700 ### `void rgb_matrix_increase_hue(void)` {#api-rgb-matrix-increase-hue} 701 702 Increase the global effect hue. 703 704 --- 705 706 ### `void rgb_matrix_increase_hue_noeeprom(void)` {#api-rgb-matrix-increase-hue-noeeprom} 707 708 Increase the global effect hue. New state is not written to EEPROM. 709 710 --- 711 712 ### `void rgb_matrix_decrease_hue(void)` {#api-rgb-matrix-decrease-hue} 713 714 Decrease the global effect hue. 715 716 --- 717 718 ### `void rgb_matrix_decrease_hue_noeeprom(void)` {#api-rgb-matrix-decrease-hue-noeeprom} 719 720 Decrease the global effect hue. New state is not written to EEPROM. 721 722 --- 723 724 ### `uint8_t rgb_matrix_get_hue(void)` {#api-rgb-matrix-get-hue} 725 726 Get the current global effect hue. 727 728 #### Return Value {#api-rgb-matrix-get-hue-return} 729 730 The current hue value, from 0 to 255. 731 732 --- 733 734 ### `void rgb_matrix_increase_sat(void)` {#api-rgb-matrix-increase-sat} 735 736 Increase the global effect saturation. 737 738 --- 739 740 ### `void rgb_matrix_increase_sat_noeeprom(void)` {#api-rgb-matrix-increase-sat-noeeprom} 741 742 Increase the global effect saturation. New state is not written to EEPROM. 743 744 --- 745 746 ### `void rgb_matrix_decrease_sat(void)` {#api-rgb-matrix-decrease-sat} 747 748 Decrease the global effect saturation. 749 750 --- 751 752 ### `void rgb_matrix_decrease_sat_noeeprom(void)` {#api-rgb-matrix-decrease-sat-noeeprom} 753 754 Decrease the global effect saturation. New state is not written to EEPROM. 755 756 --- 757 758 ### `uint8_t rgb_matrix_get_sat(void)` {#api-rgb-matrix-get-sat} 759 760 Get the current global effect saturation. 761 762 #### Return Value {#api-rgb-matrix-get-sat-return} 763 764 The current saturation value, from 0 to 255. 765 766 --- 767 768 ### `void rgb_matrix_increase_val(void)` {#api-rgb-matrix-increase-val} 769 770 Increase the global effect value (brightness). 771 772 --- 773 774 ### `void rgb_matrix_increase_val_noeeprom(void)` {#api-rgb-matrix-increase-val-noeeprom} 775 776 Increase the global effect value (brightness). New state is not written to EEPROM. 777 778 --- 779 780 ### `void rgb_matrix_decrease_val(void)` {#api-rgb-matrix-decrease-val} 781 782 Decrease the global effect value (brightness). 783 784 --- 785 786 ### `void rgb_matrix_decrease_val_noeeprom(void)` {#api-rgb-matrix-decrease-val-noeeprom} 787 788 Decrease the global effect value (brightness). New state is not written to EEPROM. 789 790 --- 791 792 ### `uint8_t rgb_matrix_get_val(void)` {#api-rgb-matrix-get-val} 793 794 Get the current global effect value (brightness). 795 796 #### Return Value {#api-rgb-matrix-get-val-return} 797 798 The current brightness value, from 0 to 255. 799 800 --- 801 802 ### `void rgb_matrix_increase_speed(void)` {#api-rgb-matrix-increase-speed} 803 804 Increase the effect speed. 805 806 --- 807 808 ### `void rgb_matrix_increase_speed_noeeprom(void)` {#api-rgb-matrix-increase-speed-noeeprom} 809 810 Increase the effect speed. New state is not written to EEPROM. 811 812 --- 813 814 ### `void rgb_matrix_decrease_speed(void)` {#api-rgb-matrix-decrease-speed} 815 816 Decrease the effect speed. 817 818 --- 819 820 ### `void rgb_matrix_decrease_speed_noeeprom(void)` {#api-rgb-matrix-decrease-speed-noeeprom} 821 822 Decrease the effect speed. New state is not written to EEPROM. 823 824 --- 825 826 ### `void rgb_matrix_set_speed(uint8_t speed)` {#api-rgb-matrix-set-speed} 827 828 Set the effect speed. 829 830 #### Arguments {#api-rgb-matrix-set-speed-arguments} 831 832 - `uint8_t speed` 833 The new speed to set, from 0 to 255. 834 835 --- 836 837 ### `void rgb_matrix_set_speed_noeeprom(uint8_t speed)` {#api-rgb-matrix-set-speed-noeeprom} 838 839 Set the effect speed. New state is not written to EEPROM. 840 841 #### Arguments {#api-rgb-matrix-set-speed-noeeprom-arguments} 842 843 - `uint8_t speed` 844 The new speed to set, from 0 to 255. 845 846 --- 847 848 ### `uint8_t rgb_matrix_get_speed(void)` {#api-rgb-matrix-get-speed} 849 850 Get the current effect speed. 851 852 #### Return Value {#api-rgb-matrix-get-speed-return} 853 854 The current effect speed, from 0 to 255. 855 856 --- 857 858 ### `void rgb_matrix_set_flags(led_flags_t flags)` {#api-rgb-matrix-set-flags} 859 860 Set the global effect flags. 861 862 #### Arguments {#api-rgb-matrix-set-flags-arguments} 863 864 - `led_flags_t flags` 865 The [flags](#flags) value to set. 866 867 --- 868 869 ### `void rgb_matrix_set_flags_noeeprom(led_flags_t flags)` {#api-rgb-matrix-set-flags-noeeprom} 870 871 Set the global effect flags. New state is not written to EEPROM. 872 873 #### Arguments {#api-rgb-matrix-set-flags-noeeprom-arguments} 874 875 - `led_flags_t flags` 876 The [flags](#flags) value to set. 877 878 --- 879 880 ### `void rgb_matrix_flags_step(void)` {#api-rgb-matrix-flags-step} 881 882 Move to the next flag combination. 883 884 --- 885 886 ### `void rgb_matrix_flags_step_noeeprom(void)` {#api-rgb-matrix-flags-step-noeeprom} 887 888 Move to the next flag combination. New state is not written to EEPROM. 889 890 --- 891 892 ### `void rgb_matrix_flags_step_reverse(void)` {#api-rgb-matrix-flags-step-reverse} 893 894 Move to the previous flag combination. 895 896 --- 897 898 ### `void rgb_matrix_flags_step_reverse_noeeprom(void)` {#api-rgb-matrix-flags-step-reverse-noeeprom} 899 900 Move to the previous flag combination. New state is not written to EEPROM. 901 902 --- 903 904 ### `uint8_t rgb_matrix_get_flags(void)` {#api-rgb-matrix-get-flags} 905 906 Get the current global effect flags. 907 908 #### Return Value {#api-rgb-matrix-get-flags-return} 909 910 The current effect [flags](#flags). 911 912 --- 913 914 ### `void rgb_matrix_sethsv(uint8_t h, uint8_t s, uint8_t v)` {#api-rgb-matrix-sethsv} 915 916 Set the global effect hue, saturation, and value (brightness). 917 918 ### Arguments {#api-rgb-matrix-sethsv-arguments} 919 920 - `uint8_t h` 921 The hue to set, from 0 to 255. 922 - `uint8_t s` 923 The saturation to set, from 0 to 255. 924 - `uint8_t v` 925 The value (brightness) to set, from 0 to 255. 926 927 --- 928 929 ### `void rgb_matrix_sethsv_noeeprom(uint8_t h, uint8_t s, uint8_t v)` {#api-rgb-matrix-sethsv-noeeprom} 930 931 Set the global effect hue, saturation, and value (brightness). New state is not written to EEPROM. 932 933 #### Arguments {#api-rgb-matrix-sethsv-noeeprom-arguments} 934 935 - `uint8_t h` 936 The hue to set, from 0 to 255. 937 - `uint8_t s` 938 The saturation to set, from 0 to 255. 939 - `uint8_t v` 940 The value (brightness) to set, from 0 to 255. 941 942 --- 943 944 ### `hsv_t rgb_matrix_get_hsv(void)` {#api-rgb-matrix-get-hsv} 945 946 Get the current global effect hue, saturation, and value (brightness). 947 948 #### Return Value {#api-rgb-matrix-get-hsv-return} 949 950 The current effect HSV as an `hsv_t` struct. 951 952 --- 953 954 ### `void rgb_matrix_reload_from_eeprom(void)` {#api-rgb-matrix-reload-from-eeprom} 955 956 Reload the effect configuration (enabled, mode and color) from EEPROM. 957 958 --- 959 960 ### `bool rgb_matrix_get_suspend_state(void)` {#api-rgb-matrix-get-suspend-state} 961 962 Get the current suspend state of RGB Matrix. 963 964 #### Return Value {#api-rgb-matrix-get-suspend-state-return} 965 966 `true` if RGB Matrix is currently in the suspended state. 967 968 --- 969 970 ### `bool rgb_matrix_indicators_kb(void)` {#api-rgb-matrix-indicators-kb} 971 972 Keyboard-level callback, invoked after current animation frame is rendered but before it is flushed to the LEDs. 973 974 #### Return Value {#api-rgb-matrix-indicators-kb-return} 975 976 Currently unused. 977 978 --- 979 980 ### `bool rgb_matrix_indicators_user(void)` {#api-rgb-matrix-indicators-user} 981 982 Keymap-level callback, invoked after current animation frame is rendered but before it is flushed to the LEDs. 983 984 #### Return Value {#api-rgb-matrix-indicators-user-return} 985 986 `true` to continue running the keyboard-level callback. 987 988 --- 989 990 ### `bool rgb_matrix_indicators_advanced_kb(uint8_t led_min, uint8_t led_max)` {#api-rgb-matrix-indicators-advanced-kb} 991 992 Keyboard-level callback, invoked after current animation frame is rendered but before it is flushed to the LEDs. 993 994 ### Arguments {#api-rgb-matrix-indicators-advanced-kb-arguments} 995 996 - `uint8_t led_min` 997 The index of the first LED in this batch. 998 - `uint8_t led_max` 999 The index of the last LED in this batch. 1000 1001 #### Return Value {#api-rgb-matrix-indicators-advanced-kb-return} 1002 1003 Currently unused. 1004 1005 --- 1006 1007 ### `bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max)` {#api-rgb-matrix-indicators-advanced-user} 1008 1009 Keymap-level callback, invoked after current animation frame is rendered but before it is flushed to the LEDs. 1010 1011 ### Arguments {#api-rgb-matrix-indicators-advanced-user-arguments} 1012 1013 - `uint8_t led_min` 1014 The index of the first LED in this batch. 1015 - `uint8_t led_max` 1016 The index of the last LED in this batch. 1017 1018 #### Return Value {#api-rgb-matrix-indicators-advanced-user-return} 1019 1020 `true` to continue running the keyboard-level callback.