diff options
Diffstat (limited to 'docs/feature_led_matrix.md')
| -rw-r--r-- | docs/feature_led_matrix.md | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 37f38cc6ed..37c74843aa 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -68,6 +68,109 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { 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-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). --- +### IS31FLCOMMON :id=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> +``` + +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 | +| `ISSIFL3743A` | [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 | +| `DRIVER_COUNT` | (Required) How many LED driver IC's are present | | +| `DRIVER_LED_TOTAL` | (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_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 + * | LED address + * | | */ + { 0, CS1_SW1 }, + { 0, CS2_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_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 __flash 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 :id=common-configuration |