diff options
Diffstat (limited to 'docs/feature_rgb_matrix.md')
| -rw-r--r-- | docs/feature_rgb_matrix.md | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 536609b39a..a021779d43 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -233,6 +233,115 @@ 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). --- +### IS31FLCOMMON :id=is31flcommon + +There is basic support for addressable RGB matrix lighting with a selection of I2C ISSI Lumissil RGB controllers through a shared common driver. To enable it, add this to your `rules.mk`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = <driver name> +``` + +Where `<driver name>` is the applicable LED driver chip as below + +| Driver Name | Data Sheet | Capability | +|-------------|------------|------------| +| `IS31FL3742A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) | 60 RGB, 30x6 Matrix | +| `ISSIFL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 66 RGB, 18x11 Matrix | +| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 48 RGB, 18x8 Matrix | +| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 24 RGB, 18x4 Matrix | + +You can use between 1 and 4 IC's. Do not specify `DRIVER_ADDR_<N>` define for IC's if not present on your keyboard. The `DRIVER_ADDR_1` default assumes that all Address pins on the controller have been connected to GND. Drivers that have SYNC functionality have the default settings to disable if 1 driver. If more than 1 drivers then `DRIVER_ADDR_1` will be set to Master and the remaining ones set to Slave. + +Configure the hardware via your `config.h`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `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 | | +| `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 | | +| `ISSI_CONFIGURATION` | (Optional) Configuration for the Configuration Register | | +| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | +| `ISSI_PULLDOWNUP` | (Optional) Configuration for the Pull Up & Pull Down Register | | +| `ISSI_TEMP` | (Optional) Configuration for the Tempature Register | | +| `ISSI_PWM_ENABLE` | (Optional) Configuration for the PWM Enable Register | | +| `ISSI_PWM_SET` | (Optional) Configuration for the PWM Setting Register | | +| `ISSI_SCAL_RED` | (Optional) Configuration for the RED LEDs in Scaling Registers | 0xFF | +| `ISSI_SCAL_BLUE` | (Optional) Configuration for the BLUE LEDs in Scaling Registers | 0xFF | +| `ISSI_SCAL_GREEN` | (Optional) Configuration for the GREEN LEDs in Scaling Registers | 0xFF | +| `ISSI_MANUAL_SCALING` | (Optional) If you wish to configure the Scaling Registers manually | | + + +Defaults + +| Variable | IS31FL3742A | IS31FL3743A | IS31FL3745 | IS31FL3746 | +|----------|-------------|-------------|------------|------------| +| `DRIVER_ADDR_1` | 0b0110000 | 0b0100000 | 0b0100000 | 0b1100000 | +| `ISSI_SSR_1` | 0x00 | 0x00 / 0x60 | 0x00 / 0xC0 | 0x00 | +| `ISSI_SSR_<2-4>` | 0x00 | 0x40 | 0x80 | 0x00 | +| `ISSI_CONFIGURATION` | 0x31 | 0x01 | 0x31 | 0x01 | +| `ISSI_PULLDOWNUP` | 0x55 | 0x33 | 0x33 | 0x33 | +| `ISSI_TEMP` | N/A | 0x00 | 0x00 | 0x00 | +| `ISSI_PWM_ENABLE` | N/A | N/A | N/A | 0x00 | +| `ISSI_PWM_SET` | 0x00 | N/A | N/A | 0x00 | + +Here is an example using 2 drivers. + +```c +#define DRIVER_ADDR_2 0b0100001 + +#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) +``` + +!> 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 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] = { +/* Refer to IS31 manual for these locations + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ + {0, CS1_SW1, CS2_SW1, CS3_SW1}, + .... +} +``` + +Where `CSx_SWx` is the location of the LED in the matrix defined by the datasheet. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). + +`ISSI_MANUAL_SCALING` is used to override the Scaling for individual LED's. By default they will be set as per `ISSI_SCAL_<colour>`. In `config.h` set how many LED's you want to manually set scaling for. +Eg `#define ISSI_MANUAL_SCALING 3` + +Then Define the array listing all the LEDs you want to override in your `<keyboard>.c`: + +```c +const is31_led __flash g_is31_scaling[ISSI_MANUAL_SCALING] = { + * LED Index + * | R scaling + * | | G scaling + * | | | B scaling + * | | | | */ + {5, 120, 155, 167}, + {9, 120, 155, 167}, + .... +} +``` + +Where LED Index is the position of the LED in the `g_is31_leds` array. The `scaling` value between 0 and 255 to be written to the Scaling Register. + +--- ### WS2812 :id=ws2812 @@ -457,6 +566,7 @@ enum rgb_matrix_effects { 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_PIXEL_FRACTAL, // Single hue fractal filled keys pulsing horizontally out to edges + RGB_MATRIX_PIXEL_FLOW, // Pulsing RGB flow along LED wiring with random hues RGB_MATRIX_PIXEL_RAIN, // Randomly light keys with random hues #if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS) RGB_MATRIX_TYPING_HEATMAP, // How hot is your WPM! @@ -512,6 +622,7 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_RGB_MATRIX_HUE_PENDULUM` |Enables `RGB_MATRIX_HUE_PENDULUM` | |`#define ENABLE_RGB_MATRIX_HUE_WAVE` |Enables `RGB_MATRIX_HUE_WAVE ` | |`#define ENABLE_RGB_MATRIX_PIXEL_FRACTAL` |Enables `RGB_MATRIX_PIXEL_FRACTAL` | +|`#define ENABLE_RGB_MATRIX_PIXEL_FLOW` |Enables `RGB_MATRIX_PIXEL_FLOW` | |`#define ENABLE_RGB_MATRIX_PIXEL_RAIN` |Enables `RGB_MATRIX_PIXEL_RAIN` | ?> These modes don't require any additional defines. @@ -707,6 +818,7 @@ Where `28` is an unused index from `eeconfig.h`. |`rgb_matrix_decrease_speed_noeeprom()` |Decrease the speed of the animations (not written to EEPROM) | |`rgb_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 | |`rgb_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) | +|`rgb_matrix_reload_from_eeprom()` |Reload the effect configuration (enabled, mode and color) from EEPROM | ### Change Color :id=change-color |Function |Description | |