docs/feature_led_matrix.md

   1 # LED Matrix Lighting
   2
   3 This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it.
   4
   5 If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead.
   6
   7 ## Driver configuration
   8
   9 ### IS31FL3731
  10
  11 There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
  12
  13     LED_MATRIX_ENABLE = IS31FL3731
  14
  15 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`:
  16
  17 | Variable | Description | Default |
  18 |----------|-------------|---------|
  19 | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages | 100 |
  20 | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
  21 | `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | |
  22 | `LED_DRIVER_LED_COUNT` | (Required) How many LED lights are present across all drivers | |
  23 | `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | |
  24 | `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | |
  25 | `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | |
  26 | `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | |
  27
  28 Here is an example using 2 drivers.
  29
  30         // This is a 7-bit address, that gets left-shifted and bit 0
  31         // set to 0 for write, 1 for read (as per I2C protocol)
  32         // The address will vary depending on your wiring:
  33         // 0b1110100 AD <-> GND
  34         // 0b1110111 AD <-> VCC
  35         // 0b1110101 AD <-> SCL
  36         // 0b1110110 AD <-> SDA
  37         #define LED_DRIVER_ADDR_1 0b1110100
  38         #define LED_DRIVER_ADDR_2 0b1110110
  39
  40         #define LED_DRIVER_COUNT 2
  41         #define LED_DRIVER_1_LED_COUNT 25
  42         #define LED_DRIVER_2_LED_COUNT 24
  43         #define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
  44
  45 Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
  46
  47 Define these arrays listing all the LEDs in your `<keyboard>.c`:
  48
  49         const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
  50         /* Refer to IS31 manual for these locations
  51          *   driver
  52          *   |  LED address
  53          *   |  | */
  54             {0, C3_3},
  55             ....
  56         }
  57
  58 Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
  59
  60 ## Keycodes
  61
  62 All LED matrix keycodes are currently shared with the [backlight system](feature_backlight.md).
  63
  64 ## LED Matrix Effects
  65
  66 Currently no LED matrix effects have been created.
  67
  68 ## Custom layer effects
  69
  70 Custom layer effects can be done by defining this in your `<keyboard>.c`:
  71
  72     void led_matrix_indicators_kb(void) {
  73         led_matrix_set_index_value(index, value);
  74     }
  75
  76 A similar function works in the keymap as `led_matrix_indicators_user`.
  77
  78 ## Suspended state
  79
  80 To use the suspend feature, add this to your `<keyboard>.c`:
  81
  82         void suspend_power_down_kb(void)
  83         {
  84             led_matrix_set_suspend_state(true);
  85         }
  86
  87         void suspend_wakeup_init_kb(void)
  88         {
  89             led_matrix_set_suspend_state(false);
  90         }