diff options
author | Ryan <[email protected]> | 2024-07-15 12:03:30 +1000 |
---|---|---|
committer | GitHub <[email protected]> | 2024-07-15 12:03:30 +1000 |
commit | 85447bd53b15b0be387336169feae1c7ff87f15c (patch) | |
tree | 5e28f54a13cd9e9b3f47489ea7fcb3be46c47241 /docs/features | |
parent | 21b9b70c503da69d2567af100c3d5e3544664e4b (diff) | |
download | qmk_firmware-85447bd53b15b0be387336169feae1c7ff87f15c.tar.gz qmk_firmware-85447bd53b15b0be387336169feae1c7ff87f15c.zip |
LED drivers: extract documentation from LED/RGB Matrix pages (#23630)
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/led_matrix.md | 188 | ||||
-rw-r--r-- | docs/features/rgb_matrix.md | 558 |
2 files changed, 47 insertions, 699 deletions
diff --git a/docs/features/led_matrix.md b/docs/features/led_matrix.md index f6587f7b3e..756cc11e2b 100644 --- a/docs/features/led_matrix.md +++ b/docs/features/led_matrix.md @@ -4,176 +4,32 @@ This feature allows you to use LED matrices driven by external drivers. It hooks If you want to use RGB LED's you should use the [RGB Matrix Subsystem](rgb_matrix) instead. -## Driver configuration {#driver-configuration} ---- -### IS31FL3731 {#is31fl3731} - -There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 LED controller. To enable it, add this to your `rules.mk`: +## Driver Configuration {#driver-configuration} + +LED 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. + +|Driver |Max LEDs| +|-------------------------------------|--------| +|[IS31FL3218](../drivers/is31fl3218) |18 | +|[IS31FL3236](../drivers/is31fl3236) |36 | +|[IS31FL3729](../drivers/is31fl3729) |135 | +|[IS31FL3731](../drivers/is31fl3731) |144 | +|[IS31FL3733](../drivers/is31fl3733) |192 | +|[IS31FL3736](../drivers/is31fl3736) |96 | +|[IS31FL3737](../drivers/is31fl3737) |144 | +|[IS31FL3741](../drivers/is31fl3741) |351 | +|[IS31FL3742A](../drivers/is31fl3742a)|180 | +|[IS31FL3743A](../drivers/is31fl3743a)|198 | +|[IS31FL3745](../drivers/is31fl3745) |144 | +|[IS31FL3746A](../drivers/is31fl3746a)|72 | +|[SNLED27351](../drivers/snled27351) |192 | + +To assign the LED Matrix driver, add the following to your `rules.mk`, for example: ```make -LED_MATRIX_ENABLE = yes -LED_MATRIX_DRIVER = is31fl3731 -``` - -You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `LED_MATRIX_LED_COUNT` | (Required) How many LED lights are present across all drivers | | -| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first LED driver | | -| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second LED driver | | -| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third LED driver | | -| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth LED driver | | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 AD <-> GND -// 01 AD <-> SCL -// 10 AD <-> SDA -// 11 AD <-> VCC -// ADDR represents A1:A0 of the 7-bit address. -// The result is: 0b11101(ADDR) -#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND -#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA - -#define LED_DRIVER_1_LED_TOTAL 25 -#define LED_DRIVER_2_LED_TOTAL 24 -#define LED_MATRIX_LED_COUNT (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL) -``` - -::: warning -Note the parentheses, this is so when `LED_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() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. -::: - -For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | LED address - * | | */ - { 0, C1_1 }, - { 0, C1_15 }, - // ... -} -``` - -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-mono.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). - ---- -### IS31FLCOMMON {#is31flcommon} - -There is basic support for addressable LED matrix lighting with a selection of I2C ISSI Lumissil LED controllers through a shared common driver. To enable it, add this to your `rules.mk`: - -```makefile -LED_MATRIX_ENABLE = yes -LED_MATRIX_DRIVER = <driver name> +LED_MATRIX_DRIVER = is31fl3218 ``` -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) | 180 LED, 30x6 Matrix | -| `IS31FL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 198 LED, 18x11 Matrix | -| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 144 LED, 18x8 Matrix | -| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 72 LED, 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 remaiing 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 | -| `LED_MATRIX_LED_COUNT` | (Required) How many LED lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Optional) Address for the first LED driver | | -| `DRIVER_ADDR_<N>` | (Required) Address for the additional LED 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_LED ` | (Optional) Configuration for the LEDs 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_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 42 -#define LED_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -Note the parentheses, this is so when `LED_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 PROGMEM g_is31_leds[LED_MATRIX_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | LED address - * | | */ - { 0, SW1_CS1 }, - { 0, SW1_CS2 }, - // ... -} -``` - -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_LED`. 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 PROGMEM g_is31_scaling[ISSI_MANUAL_SCALING] = { -/* LED Index - * | Scaling - * | | */ - {5, 120}, - {9, 120}, - .... -} -``` - -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. - ---- - ## Common Configuration {#common-configuration} 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: diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md index aef766ebd2..bc14bb6277 100644 --- a/docs/features/rgb_matrix.md +++ b/docs/features/rgb_matrix.md @@ -4,543 +4,35 @@ This feature allows you to use RGB LED matrices driven by external drivers. It h If you want to use single color LED's you should use the [LED Matrix Subsystem](led_matrix) instead. -## Driver configuration {#driver-configuration} ---- -### IS31FL3731 {#is31fl3731} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3731 -``` - -You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 AD <-> GND -// 01 AD <-> SCL -// 10 AD <-> SDA -// 11 AD <-> VCC -// ADDR represents A1:A0 of the 7-bit address. -// The result is: 0b11101(ADDR) -#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND -#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA - -#define DRIVER_1_LED_TOTAL 25 -#define DRIVER_2_LED_TOTAL 24 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -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 `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. - -Define these arrays listing all the LEDs in your `<keyboard>.c`: - -```c -const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, C1_3, C2_3, C3_3}, - .... -} -``` - -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). - ---- -### IS31FL3733 {#is31fl3733} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3733 -``` - -You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3733_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3733_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3733_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | -| `IS31FL3733_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3733_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3733_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3733_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3733_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3733_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3733_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | -| `IS31FL3733_SYNC_1` | (Optional) Sync configuration for the first RGB driver | 0 | -| `IS31FL3733_SYNC_2` | (Optional) Sync configuration for the second RGB driver | 0 | -| `IS31FL3733_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | -| `IS31FL3733_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 (`IS31FL3733_SWPULLUP`/`IS31FL3733_CSPULLUP` are given the value of `IS31FL3733_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3733_SWPULLUP/IS31FL3733_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3733_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3733_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3733_PUR_3KR` | The 3k Ohm resistor used at all times | -| `IS31FL3733_PUR_4KR` | The 4k Ohm resistor used at all times | -| `IS31FL3733_PUR_8KR` | The 8k Ohm resistor used at all times | -| `IS31FL3733_PUR_16KR` | The 16k Ohm resistor used at all times | -| `IS31FL3733_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 ADDRn <-> GND -// 01 ADDRn <-> SCL -// 10 ADDRn <-> SDA -// 11 ADDRn <-> VCC -// ADDR1 represents A1:A0 of the 7-bit address. -// ADDR2 represents A3:A2 of the 7-bit address. -// The result is: 0b101(ADDR2)(ADDR1) -#define IS31FL3733_I2C_ADDRESS_1 IS31FL3733_I2C_ADDRESS_GND_GND -#define IS31FL3733_I2C_ADDRESS_2 IS31FL3733_I2C_ADDRESS_GND_VCC - -#define DRIVER_1_LED_TOTAL 58 -#define DRIVER_2_LED_TOTAL 10 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -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 is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -Where `SWx_CSy` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/led/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). - ---- -### IS31FL3736 {#is31fl3736} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3736 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3736 -``` -You can use between 1 and 4 IS31FL3736 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`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3736_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3736_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3736_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3736B only | 0 | -| `IS31FL3736_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3736_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3736_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3736_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3736_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3736_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3736_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | - -The IS31FL3736 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 (`IS31FL3736_SWPULLUP`/`IS31FL3736_CSPULLUP` are given the value of `IS31FL3736_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3736_SWPULLUP/IS31FL3736_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3736_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3736_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3736_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3736_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3736_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 00 ADDRn <-> GND -// 01 ADDRn <-> SCL -// 10 ADDRn <-> SDA -// 11 ADDRn <-> VCC -// ADDR1 represents A1:A0 of the 7-bit address. -// ADDR2 represents A3:A2 of the 7-bit address. -// The result is: 0b101(ADDR2)(ADDR1) -#define IS31FL3736_I2C_ADDRESS_1 IS31FL3736_I2C_ADDRESS_GND_GND -#define IS31FL3736_I2C_ADDRESS_2 IS31FL3736_I2C_ADDRESS_GND_SCL - -#define DRIVER_1_LED_TOTAL 30 -#define DRIVER_2_LED_TOTAL 32 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -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 is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` -### IS31FL3737 {#is31fl3737} - -There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = is31fl3737 -``` -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`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `IS31FL3737_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `IS31FL3737_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `IS31FL3737_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 | -| `IS31FL3737_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `IS31FL3737_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `IS31FL3737_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `IS31FL3737_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | -| `IS31FL3737_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | -| `IS31FL3737_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | -| `IS31FL3737_I2C_ADDRESS_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 (`IS31FL3737_SWPULLUP`/`IS31FL3737_CSPULLUP` are given the value of `IS31FL3737_PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `IS31FL3737_SWPULLUP/IS31FL3737_CSPULLUP` | Description | -|----------------------|-------------| -| `IS31FL3737_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `IS31FL3737_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `IS31FL3737_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3737_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `IS31FL3737_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | - -Here is an example using 2 drivers. - -```c -// This is a 7-bit address, that gets left-shifted and bit 0 -// set to 0 for write, 1 for read (as per I2C protocol) -// The address will vary depending on your wiring: -// 0000 ADDR <-> GND -// 0101 ADDR <-> SCL -// 1010 ADDR <-> SDA -// 1111 ADDR <-> VCC -// ADDR represents A3:A0 of the 7-bit address. -// The result is: 0b101(ADDR) -#define IS31FL3737_I2C_ADDRESS_1 IS31FL3737_I2C_ADDRESS_GND -#define IS31FL3737_I2C_ADDRESS_2 IS31FL3737_I2C_ADDRESS_SCL - -#define DRIVER_1_LED_TOTAL 30 -#define DRIVER_2_LED_TOTAL 36 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` -::: warning -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 is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -Where `SWx_CSy` 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 {#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 | -| `IS31FL3743A` | [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 | -| `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 | | -| `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 Temperature 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_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 42 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -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 PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { -/* Refer to IS31 manual for these locations - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - {0, SW1_CS1, SW1_CS2, SW1_CS3}, - .... -} -``` - -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 PROGMEM 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 {#ws2812} - -There 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`: +## Driver Configuration {#driver-configuration} + +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. + +|Driver |Max LEDs| +|-------------------------------------|--------| +|[APA102](../drivers/apa102) |? | +|[AW20216S](../drivers/aw20216s) |72 | +|[IS31FL3218](../drivers/is31fl3218) |6 | +|[IS31FL3236](../drivers/is31fl3236) |12 | +|[IS31FL3729](../drivers/is31fl3729) |45 | +|[IS31FL3731](../drivers/is31fl3731) |48 | +|[IS31FL3733](../drivers/is31fl3733) |64 | +|[IS31FL3736](../drivers/is31fl3736) |32 | +|[IS31FL3737](../drivers/is31fl3737) |48 | +|[IS31FL3741](../drivers/is31fl3741) |117 | +|[IS31FL3742A](../drivers/is31fl3742a)|60 | +|[IS31FL3743A](../drivers/is31fl3743a)|66 | +|[IS31FL3745](../drivers/is31fl3745) |48 | +|[IS31FL3746A](../drivers/is31fl3746a)|24 | +|[SNLED27351](../drivers/snled27351) |64 | +|[WS2812](../drivers/ws2812) |? | + +To assign the RGB Matrix driver, add the following to your `rules.mk`, for example: ```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = ws2812 -``` - -Configure the hardware via your `config.h`: - -```c -// The pin connected to the data pin of the LEDs -#define WS2812_DI_PIN D7 -// The number of LEDs connected -#define RGB_MATRIX_LED_COUNT 70 +RGB_MATRIX_DRIVER = is31fl3218 ``` -::: tip -There are additional configuration options for ARM controllers that offer increased performance over the default bitbang driver. Please see [WS2812 Driver](../drivers/ws2812) for more information. -::: - ---- - -### APA102 {#apa102} - -There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = apa102 -``` - -Configure the hardware via your `config.h`: - -```c -// The pin connected to the data pin of the LEDs -#define APA102_DI_PIN D7 -// The pin connected to the clock pin of the LEDs -#define APA102_CI_PIN D6 -// The number of LEDs connected -#define RGB_MATRIX_LED_COUNT 70 -``` - ---- -### AW20216S {#aw20216s} -There is basic support for addressable RGB matrix lighting with the SPI AW20216S RGB controller. To enable it, add this to your `rules.mk`: - -```make -RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = aw20216s -``` - -You can use up to 2 AW20216S IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `AW20216S_CS_PIN_1` | (Required) MCU pin connected to first RGB driver chip select line | B13 | -| `AW20216S_CS_PIN_2` | (Optional) MCU pin connected to second RGB driver chip select line | | -| `AW20216S_EN_PIN_1` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 | -| `AW20216S_EN_PIN_2` | (Optional) MCU pin connected to second RGB driver hardware enable line | | -| `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 | | -| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `AW20216S_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | -| `AW20216S_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | -| `AW20216S_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | -| `AW20216S_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | - -Here is an example using 2 drivers. - -```c -#define AW20216S_CS_PIN_1 B13 -#define AW20216S_CS_PIN_2 B14 -// Hardware enable lines may be connected to the same pin -#define AW20216S_EN_PIN_1 C13 -#define AW20216S_EN_PIN_2 C13 - -#define DRIVER_1_LED_TOTAL 66 -#define DRIVER_2_LED_TOTAL 32 -#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) -``` - -::: warning -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 aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { -/* Each AW20216S channel is controlled by a register at some offset between 0x00 - * and 0xD7 inclusive. - * See drivers/led/aw20216s.h for the mapping between register offsets and - * driver pin locations. - * driver - * | R location - * | | G location - * | | | B location - * | | | | */ - { 0, SW1_CS1, SW1_CS2, SW1_CS3 }, - { 0, SW1_CS4, SW1_CS5, SW1_CS6 }, - { 0, SW1_CS7, SW1_CS8, SW1_CS9 }, - { 0, SW1_CS10, SW1_CS11, SW1_CS12 }, - { 0, SW1_CS13, SW1_CS14, SW1_CS15 }, - ... - { 1, SW1_CS1, SW1_CS2, SW1_CS3 }, - { 1, SW1_CS13, SW1_CS14, SW1_CS15 }, - { 1, SW1_CS16, SW1_CS17, SW1_CS18 }, - { 1, SW2_CS4, SW2_CS5, SW2_CS6 }, - ... -}; -``` - ---- - ## Common Configuration {#common-configuration} 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: |