From 0c725017638ec86011191bf835735fb6c569d298 Mon Sep 17 00:00:00 2001 From: donicrosby Date: Mon, 1 Nov 2021 19:40:01 -0400 Subject: Enable de-ghosting for RGB/LED matrix on all ISSI LED drivers (#14508) * Initial work for de-ghost enable * Dumb mistake with the redefine * Added Copywrite stuff on source files * Fixed whitespace errors * Added support for all ISSI LED drivers * Updated docs for support for ISSI LED driver pull-up pull-down * Applied clang format * Added 'boolean' flag to enable de-ghosting for the is31fl3731 IC * Fixed some of the grammer in the docs * Fixed comment placement and grammer of comment * Fixed whitespace errors from lint Co-authored-by: donicrosby --- docs/feature_rgb_matrix.md | 47 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) (limited to 'docs/feature_rgb_matrix.md') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index fa06e46e4a..cad7c50f18 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -21,6 +21,7 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_` de |----------|-------------|---------| | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | | `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 | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | @@ -85,6 +86,8 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_` de | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | | `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | +| `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 | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | @@ -96,6 +99,18 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_` de | `DRIVER_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | | `DRIVER_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 | +The IS31FL3733 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: + +| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description | +|----------------------|-------------| +| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | +| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | +| `PUR_3KR` | The 3k Ohm resistor used at all times | +| `PUR_4KR` | The 4k Ohm resistor used at all times | +| `PUR_8KR` | The 8k Ohm resistor used at all times | +| `PUR_16KR` | The 16k Ohm resistor used at all times | +| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | + Here is an example using 2 drivers. ```c @@ -156,11 +171,25 @@ 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 | +| `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 | | | `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | | `DRIVER_ADDR_2` | (Optional) Address for the second 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: + +| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description | +|----------------------|-------------| +| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | +| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | +| `PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | +| `PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | +| `PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | +| `PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | +| `PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | +| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | Here is an example using 2 drivers. @@ -184,7 +213,7 @@ Here is an example using 2 drivers. ``` !> 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`. -Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. +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 `.c`: @@ -343,7 +372,7 @@ x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION ``` -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. +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. 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. @@ -386,7 +415,7 @@ All RGB keycodes are currently shared with the RGBLIGHT system: * `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system. -`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped. +`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped. !> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. @@ -423,7 +452,7 @@ enum rgb_matrix_effects { RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight ammount at the same time, then shifts back RGB_MATRIX_HUE_PENDULUM, // Hue shifts up a slight ammount in a wave to the right, then back to the left - RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight ammount and then back down in a wave to the right + RGB_MATRIX_HUE_WAVE, // Hue shifts up a slight ammount and then back down in a wave to the right RGB_MATRIX_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges #if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS) RGB_MATRIX_TYPING_HEATMAP, // How hot is your WPM! @@ -698,7 +727,7 @@ Where `28` is an unused index from `eeconfig.h`. ### Indicators :id=indicators -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: +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) { rgb_matrix_set_color(index, red, green, blue); @@ -753,18 +782,18 @@ This example sets the modifiers to be a specific color based on the layer state. ```c void 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)) { hsv = {130, 255, 255}; } else { hsv = {30, 255, 255}; } - + if (hsv.v > rgb_matrix_get_val()) { hsv.v = rgb_matrix_get_val(); } RGB rgb = hsv_to_rgb(hsv); - + 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); @@ -773,7 +802,7 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } ``` -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: +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) { -- cgit v1.2.3