diff options
Diffstat (limited to 'docs/feature_rgb_matrix.md')
| -rw-r--r-- | docs/feature_rgb_matrix.md | 89 |
1 files changed, 50 insertions, 39 deletions
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 31f0a2cbc5..a7ef55b4bc 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -23,7 +23,7 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_<N>` de | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | | `ISSI_3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | | `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | | `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | @@ -45,17 +45,17 @@ Here is an example using 2 drivers. #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 25 #define DRIVER_2_LED_TOTAL 24 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_is31_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_is31_leds`. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -90,7 +90,7 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | | `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | | `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | @@ -131,17 +131,17 @@ Here is an example using 2 drivers. #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 58 #define DRIVER_2_LED_TOTAL 10 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. Currently only 4 drivers are supported, but it would be trivial to support all 8 combinations. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -164,7 +164,7 @@ There is basic support for addressable RGB matrix lighting with the I2C IS31FL37 RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3737 ``` -You can use between 1 and 2 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_2` define for second IC if not present on your keyboard. +You can use between 1 and 4 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. Configure the hardware via your `config.h`: @@ -177,9 +177,11 @@ Configure the hardware via your `config.h`: | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | | `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | +| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | +| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | The IS31FL3737 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows: @@ -212,16 +214,16 @@ Here is an example using 2 drivers. #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 30 #define DRIVER_2_LED_TOTAL 36 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -233,7 +235,7 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now). +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1`, `2`, or `3` for now). --- ### IS31FLCOMMON :id=is31flcommon @@ -263,7 +265,7 @@ Configure the hardware via your `config.h`: | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | | `DRIVER_ADDR_1` | (Optional) Address for the first RGB driver | | | `DRIVER_ADDR_<N>` | (Required) Address for the additional RGB drivers | | | `ISSI_SSR_<N>` | (Optional) Configuration for the Spread Spectrum Register | | @@ -300,17 +302,17 @@ Here is an example using 2 drivers. #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 66 #define DRIVER_2_LED_TOTAL 42 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led __flash g_is31_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -361,7 +363,7 @@ Configure the hardware via your `config.h`: // The pin connected to the data pin of the LEDs #define RGB_DI_PIN D7 // The number of LEDs connected -#define DRIVER_LED_TOTAL 70 +#define RGB_MATRIX_LED_COUNT 70 ``` ?> There are additional configuration options for ARM controllers that offer increased performance over the default bitbang driver. Please see [WS2812 Driver](ws2812_driver.md) for more information. @@ -385,7 +387,7 @@ Configure the hardware via your `config.h`: // The pin connected to the clock pin of the LEDs #define RGB_CI_PIN D6 // The number of LEDs connected -#define DRIVER_LED_TOTAL 70 +#define RGB_MATRIX_LED_COUNT 70 ``` --- @@ -408,7 +410,7 @@ You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC | `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | | | `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | | `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | | `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | | `AW_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | @@ -426,15 +428,15 @@ Here is an example using 2 drivers. #define DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 66 #define DRIVER_2_LED_TOTAL 32 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. +!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const aw_led PROGMEM g_aw_leds[DRIVER_LED_TOTAL] = { +const aw_led PROGMEM g_aw_leds[RGB_MATRIX_LED_COUNT] = { /* Each AW20216 channel is controlled by a register at some offset between 0x00 * and 0xD7 inclusive. * See drivers/awinic/aw20216.h for the mapping between register offsets and @@ -791,10 +793,9 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master #define RGB_MATRIX_KEYPRESSES // reacts to keypresses #define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) #define RGB_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects -#define RGB_DISABLE_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off -#define RGB_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects +#define RGB_MATRIX_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off #define RGB_DISABLE_WHEN_USB_SUSPENDED // turn off effects when suspended -#define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness) +#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) #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) #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 #define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set @@ -824,7 +825,7 @@ Where `28` is an unused index from `eeconfig.h`. |Function |Description | |--------------------------------------------|-------------| |`rgb_matrix_set_color_all(r, g, b)` |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgb_matrix_set_color(index, r, g, b)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) | +|`rgb_matrix_set_color(index, r, g, b)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `RGB_MATRIX_LED_COUNT` (not written to EEPROM) | ### Disable/Enable Effects :id=disable-enable-effects |Function |Description | @@ -889,16 +890,21 @@ Where `28` is an unused index from `eeconfig.h`. If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that: ```c -void rgb_matrix_indicators_kb(void) { +bool rgb_matrix_indicators_kb(void) { + if (!rgb_matrix_indicators_user()) { + return false; + } rgb_matrix_set_color(index, red, green, blue); + return true; } ``` 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)`. ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { RGB_MATRIX_INDICATOR_SET_COLOR(index, red, green, blue); + return false; } ``` @@ -906,21 +912,22 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { Caps Lock indicator on alphanumeric flagged keys: ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { if (host_keyboard_led_state().caps_lock) { - for (uint8_t i = led_min; i <= led_max; i++) { + for (uint8_t i = led_min; i < led_max; i++) { if (g_led_config.flags[i] & LED_FLAG_KEYLIGHT) { rgb_matrix_set_color(i, RGB_RED); } } } + return false; } ``` Layer indicator on all keys: ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { - for (uint8_t i = led_min; i <= led_max; i++) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { + for (uint8_t i = led_min; i < led_max; i++) { switch(get_highest_layer(layer_state|default_layer_state)) { case 2: rgb_matrix_set_color(i, RGB_BLUE); @@ -932,12 +939,13 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { break; } } + return false; } ``` Layer indicator only on keys with configured keycodes: ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { if (get_highest_layer(layer_state) > 0) { uint8_t layer = get_highest_layer(layer_state); @@ -945,13 +953,14 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { for (uint8_t col = 0; col < MATRIX_COLS; ++col) { uint8_t index = g_led_config.matrix_co[row][col]; - if (index >= led_min && index <= led_max && index != NO_LED && + if (index >= led_min && index < led_max && index != NO_LED && keymap_key_to_keycode(layer, (keypos_t){col,row}) > KC_TRNS) { rgb_matrix_set_color(index, RGB_GREEN); } } } } + return false; } ``` @@ -962,7 +971,7 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { 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). ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { HSV hsv = {0, 255, 255}; if (layer_state_is(layer_state, 2)) { @@ -976,23 +985,25 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } RGB rgb = hsv_to_rgb(hsv); - for (uint8_t i = led_min; i <= led_max; i++) { + for (uint8_t i = led_min; i < led_max; i++) { if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b); } } + return false; } ``` 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: ```c -void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { +bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { if (host_keyboard_led_state().caps_lock) { RGB_MATRIX_INDICATOR_SET_COLOR(5, 255, 255, 255); // assuming caps lock is at led #5 } else { RGB_MATRIX_INDICATOR_SET_COLOR(5, 0, 0, 0); } + return false; } ``` |