aboutsummaryrefslogtreecommitdiff
path: root/docs/feature_rgb_matrix.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/feature_rgb_matrix.md')
-rw-r--r--docs/feature_rgb_matrix.md56
1 files changed, 28 insertions, 28 deletions
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 23082ef2a..7bc219347 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -1,22 +1,22 @@
1# RGB Matrix Lighting 1# RGB Matrix Lighting :id=rgb-matrix-lighting
2 2
3This 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. 3This 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 4
5If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead. 5If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
6 6
7## Driver configuration 7## Driver configuration :id=driver-configuration
8--- 8---
9### IS31FL3731 9### IS31FL3731 :id=is31fl3731
10 10
11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: 11There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
12 12
13```C 13```makefile
14RGB_MATRIX_ENABLE = IS31FL3731 14RGB_MATRIX_ENABLE = IS31FL3731
15``` 15```
16 16
17Configure the hardware via your `config.h`: 17Configure the hardware via your `config.h`:
18 18
19```C 19```c
20// This is a 7-bit address, that gets left-shifted and bit 0 20// This is a 7-bit address, that gets left-shifted and bit 0
21// set to 0 for write, 1 for read (as per I2C protocol) 21// set to 0 for write, 1 for read (as per I2C protocol)
22// The address will vary depending on your wiring: 22// The address will vary depending on your wiring:
@@ -39,7 +39,7 @@ Currently only 2 drivers are supported, but it would be trivial to support all 4
39 39
40Define these arrays listing all the LEDs in your `<keyboard>.c`: 40Define these arrays listing all the LEDs in your `<keyboard>.c`:
41 41
42```C 42```c
43const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { 43const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
44/* Refer to IS31 manual for these locations 44/* Refer to IS31 manual for these locations
45 * driver 45 * driver
@@ -55,19 +55,19 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
55Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now). 55Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
56 56
57--- 57---
58### IS31FL3733/IS31FL3737 58### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737
59 59
60!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`. 60!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
61 61
62There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: 62There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
63 63
64```C 64```makefile
65RGB_MATRIX_ENABLE = IS31FL3733 65RGB_MATRIX_ENABLE = IS31FL3733
66``` 66```
67 67
68Configure the hardware via your `config.h`: 68Configure the hardware via your `config.h`:
69 69
70```C 70```c
71// This is a 7-bit address, that gets left-shifted and bit 0 71// This is a 7-bit address, that gets left-shifted and bit 0
72// set to 0 for write, 1 for read (as per I2C protocol) 72// set to 0 for write, 1 for read (as per I2C protocol)
73// The address will vary depending on your wiring: 73// The address will vary depending on your wiring:
@@ -90,7 +90,7 @@ Currently only a single drivers is supported, but it would be trivial to support
90 90
91Define these arrays listing all the LEDs in your `<keyboard>.c`: 91Define these arrays listing all the LEDs in your `<keyboard>.c`:
92 92
93```C 93```c
94const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { 94const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
95/* Refer to IS31 manual for these locations 95/* Refer to IS31 manual for these locations
96 * driver 96 * driver
@@ -107,17 +107,17 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
107 107
108--- 108---
109 109
110### WS2812 110### WS2812 :id=ws2812
111 111
112There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: 112There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
113 113
114```C 114```makefile
115RGB_MATRIX_ENABLE = WS2812 115RGB_MATRIX_ENABLE = WS2812
116``` 116```
117 117
118Configure the hardware via your `config.h`: 118Configure the hardware via your `config.h`:
119 119
120```C 120```c
121// The pin connected to the data pin of the LEDs 121// The pin connected to the data pin of the LEDs
122#define RGB_DI_PIN D7 122#define RGB_DI_PIN D7
123// The number of LEDs connected 123// The number of LEDs connected
@@ -128,7 +128,7 @@ Configure the hardware via your `config.h`:
128 128
129From 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: 129From 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:
130 130
131```C 131```c
132const led_config_t g_led_config = { { 132const led_config_t g_led_config = { {
133 // Key Matrix to LED Index 133 // Key Matrix to LED Index
134 { 5, NO_LED, NO_LED, 0 }, 134 { 5, NO_LED, NO_LED, 0 },
@@ -146,7 +146,7 @@ const led_config_t g_led_config = { {
146 146
147The 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: 147The 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:
148 148
149```C 149```c
150x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION 150x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
151y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION 151y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
152``` 152```
@@ -157,7 +157,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
157 157
158`// 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. 158`// 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.
159 159
160## Flags 160## Flags :id=flags
161 161
162|Define |Description | 162|Define |Description |
163|------------------------------------|-------------------------------------------| 163|------------------------------------|-------------------------------------------|
@@ -169,7 +169,7 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
169|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. | 169|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. |
170|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. | 170|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. |
171 171
172## Keycodes 172## Keycodes :id=keycodes
173 173
174All RGB keycodes are currently shared with the RGBLIGHT system: 174All RGB keycodes are currently shared with the RGBLIGHT system:
175 175
@@ -189,11 +189,11 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
189 189
190* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system 190* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
191 191
192## RGB Matrix Effects 192## RGB Matrix Effects :id=rgb-matrix-effects
193 193
194All 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: 194All 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:
195 195
196```C 196```c
197enum rgb_matrix_effects { 197enum rgb_matrix_effects {
198 RGB_MATRIX_NONE = 0, 198 RGB_MATRIX_NONE = 0,
199 RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support 199 RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support
@@ -285,7 +285,7 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
285|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | 285|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` |
286 286
287 287
288## Custom RGB Matrix Effects 288## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
289 289
290By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. 290By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
291 291
@@ -294,7 +294,7 @@ To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks somethi
294`rgb_matrix_user.inc` should go in the root of the keymap directory. 294`rgb_matrix_user.inc` should go in the root of the keymap directory.
295`rgb_matrix_kb.inc` should go in the root of the keyboard directory. 295`rgb_matrix_kb.inc` should go in the root of the keyboard directory.
296 296
297```C 297```c
298// !!! DO NOT ADD #pragma once !!! // 298// !!! DO NOT ADD #pragma once !!! //
299 299
300// Step 1. 300// Step 1.
@@ -341,7 +341,7 @@ static bool my_cool_effect2(effect_params_t* params) {
341For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` 341For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
342 342
343 343
344## Colors 344## Colors :id=colors
345 345
346These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. 346These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
347 347
@@ -369,9 +369,9 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
369These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! 369These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
370 370
371 371
372## Additional `config.h` Options 372## Additional `config.h` Options :id=additional-configh-options
373 373
374```C 374```c
375#define RGB_MATRIX_KEYPRESSES // reacts to keypresses 375#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
376#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) 376#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
377#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects 377#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
@@ -386,21 +386,21 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
386#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set 386#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
387``` 387```
388 388
389## EEPROM storage 389## EEPROM storage :id=eeprom-storage
390 390
391The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with: 391The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
392 392
393```C 393```c
394#define EECONFIG_RGB_MATRIX (uint32_t *)28 394#define EECONFIG_RGB_MATRIX (uint32_t *)28
395``` 395```
396 396
397Where `28` is an unused index from `eeconfig.h`. 397Where `28` is an unused index from `eeconfig.h`.
398 398
399## Suspended state 399## Suspended state :id=suspended-state
400 400
401To use the suspend feature, add this to your `<keyboard>.c`: 401To use the suspend feature, add this to your `<keyboard>.c`:
402 402
403```C 403```c
404void suspend_power_down_kb(void) 404void suspend_power_down_kb(void)
405{ 405{
406 rgb_matrix_set_suspend_state(true); 406 rgb_matrix_set_suspend_state(true);