docs/feature_rgb_matrix.md

   1 # RGB Matrix Lighting
   2
   3 This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it.
   4
   5 If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
   6
   7 ## Driver configuration
   8
   9 ### IS31FL3731
  10
  11 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
  12
  13     RGB_MATRIX_ENABLE = IS31FL3731
  14
  15 Configure the hardware via your `config.h`:
  16
  17         // This is a 7-bit address, that gets left-shifted and bit 0
  18         // set to 0 for write, 1 for read (as per I2C protocol)
  19         // The address will vary depending on your wiring:
  20         // 0b1110100 AD <-> GND
  21         // 0b1110111 AD <-> VCC
  22         // 0b1110101 AD <-> SCL
  23         // 0b1110110 AD <-> SDA
  24         #define DRIVER_ADDR_1 0b1110100
  25         #define DRIVER_ADDR_2 0b1110110
  26
  27         #define DRIVER_COUNT 2
  28         #define DRIVER_1_LED_TOTAL 25
  29         #define DRIVER_2_LED_TOTAL 24
  30         #define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL
  31
  32 Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
  33
  34 Define these arrays listing all the LEDs in your `<keyboard>.c`:
  35
  36         const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
  37         /* Refer to IS31 manual for these locations
  38          *   driver
  39          *   |  R location
  40          *   |  |      G location
  41          *   |  |      |      B location
  42          *   |  |      |      | */
  43             {0, C1_3,  C2_3,  C3_3},
  44             ....
  45         }
  46
  47 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.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
  48
  49 ###  IS31FL3733
  50
  51 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
  52
  53     RGB_MATRIX_ENABLE = IS31FL3733
  54
  55 Configure the hardware via your `config.h`:
  56
  57         // This is a 7-bit address, that gets left-shifted and bit 0
  58         // set to 0 for write, 1 for read (as per I2C protocol)
  59         // The address will vary depending on your wiring:
  60         // 00 <-> GND
  61         // 01 <-> SCL
  62         // 10 <-> SDA
  63         // 11 <-> VCC
  64         // ADDR1 represents A1:A0 of the 7-bit address.
  65         // ADDR2 represents A3:A2 of the 7-bit address.
  66         // The result is: 0b101(ADDR2)(ADDR1)
  67         #define DRIVER_ADDR_1 0b1010000
  68         #define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons.
  69
  70         #define DRIVER_COUNT 1
  71         #define DRIVER_1_LED_TOTAL 64
  72         #define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL
  73
  74 Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1`
  75
  76 Define these arrays listing all the LEDs in your `<keyboard>.c`:
  77
  78         const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
  79         /* Refer to IS31 manual for these locations
  80          *   driver
  81          *   |  R location
  82          *   |  |       G location
  83          *   |  |       |       B location
  84          *   |  |       |       | */
  85             {0, B_1,    A_1,    C_1},
  86             ....
  87         }
  88
  89 Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
  90
  91 From this point forward the configuration is the same for all the drivers.
  92
  93         const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
  94         /* {row | col << 4}
  95          *    |           {x=0..224, y=0..64}
  96          *    |              |               modifier
  97          *    |              |                 | */
  98             {{0|(0<<4)},   {20.36*0, 21.33*0}, 1},
  99             {{0|(1<<4)},   {20.36*1, 21.33*0}, 1},
 100             ....
 101         }
 102
 103 The format for the matrix position used in this array is `{row | (col << 4)}`. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64. The easiest way to calculate these positions is:
 104
 105     x = 224 / ( NUMBER_OF_ROWS - 1 ) * ROW_POSITION
 106     y = 64 / (NUMBER_OF_COLS - 1 ) * COL_POSITION
 107
 108 Where all variables are decimels/floats.
 109
 110 `modifier` is a boolean, whether or not a certain key is considered a modifier (used in some effects).
 111
 112 ## Keycodes
 113
 114 All RGB keycodes are currently shared with the RGBLIGHT system:
 115
 116         * `RGB_TOG` - toggle
 117         * `RGB_MOD` - cycle through modes
 118         * `RGB_HUI` - increase hue
 119         * `RGB_HUD` - decrease hue
 120         * `RGB_SAI` - increase saturation
 121         * `RGB_SAD` - decrease saturation
 122         * `RGB_VAI` - increase value
 123         * `RGB_VAD` - decrease value
 124         * `RGB_SPI` - increase speed effect (no EEPROM support)
 125         * `RGB_SPD` - decrease speed effect (no EEPROM support)
 126
 127
 128         * `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
 129
 130 ## RGB Matrix Effects
 131
 132 These are the effects that are currently available:
 133
 134         enum rgb_matrix_effects {
 135             RGB_MATRIX_SOLID_COLOR = 1,
 136             RGB_MATRIX_ALPHAS_MODS,
 137             RGB_MATRIX_DUAL_BEACON,
 138             RGB_MATRIX_GRADIENT_UP_DOWN,
 139             RGB_MATRIX_RAINDROPS,
 140             RGB_MATRIX_CYCLE_ALL,
 141             RGB_MATRIX_CYCLE_LEFT_RIGHT,
 142             RGB_MATRIX_CYCLE_UP_DOWN,
 143             RGB_MATRIX_RAINBOW_BEACON,
 144             RGB_MATRIX_RAINBOW_PINWHEELS,
 145             RGB_MATRIX_RAINBOW_MOVING_CHEVRON,
 146             RGB_MATRIX_JELLYBEAN_RAINDROPS,
 147             RGB_MATRIX_DIGITAL_RAIN,
 148         #ifdef RGB_MATRIX_KEYPRESSES
 149             RGB_MATRIX_SOLID_REACTIVE,
 150             RGB_MATRIX_SPLASH,
 151             RGB_MATRIX_MULTISPLASH,
 152             RGB_MATRIX_SOLID_SPLASH,
 153             RGB_MATRIX_SOLID_MULTISPLASH,
 154         #endif
 155             RGB_MATRIX_EFFECT_MAX
 156         };
 157
 158 You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
 159
 160
 161 |Define                                             |Description                                 |
 162 |---------------------------------------------------|--------------------------------------------|
 163 |`#define DISABLE_RGB_MATRIX_ALPHAS_MODS`           |Disables `RGB_MATRIX_ALPHAS_MODS`           |
 164 |`#define DISABLE_RGB_MATRIX_DUAL_BEACON`           |Disables `RGB_MATRIX_DUAL_BEACON`           |
 165 |`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`      |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`      |
 166 |`#define DISABLE_RGB_MATRIX_RAINDROPS`             |Disables `RGB_MATRIX_RAINDROPS`             |
 167 |`#define DISABLE_RGB_MATRIX_CYCLE_ALL`             |Disables `RGB_MATRIX_CYCLE_ALL`             |
 168 |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT`      |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT`      |
 169 |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN`         |Disables `RGB_MATRIX_CYCLE_UP_DOWN`         |
 170 |`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON`        |Disables `RGB_MATRIX_RAINBOW_BEACON`        |
 171 |`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`     |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`     |
 172 |`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
 173 |`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS`   |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS`   |
 174 |`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN`          |Disables `RGB_MATRIX_DIGITAL_RAIN`          |
 175 |`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE`        |Disables `RGB_MATRIX_SOLID_REACTIVE`        |
 176 |`#define DISABLE_RGB_MATRIX_SPLASH`                |Disables `RGB_MATRIX_SPLASH`                |
 177 |`#define DISABLE_RGB_MATRIX_MULTISPLASH`           |Disables `RGB_MATRIX_MULTISPLASH`           |
 178 |`#define DISABLE_RGB_MATRIX_SOLID_SPLASH`          |Disables `RGB_MATRIX_SOLID_SPLASH`          |
 179 |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`     |Disables `RGB_MATRIX_SOLID_MULTISPLASH`     |
 180
 181
 182 ## Custom layer effects
 183
 184 Custom layer effects can be done by defining this in your `<keyboard>.c`:
 185
 186     void rgb_matrix_indicators_kb(void) {
 187         rgb_matrix_set_color(index, red, green, blue);
 188     }
 189
 190 A similar function works in the keymap as `rgb_matrix_indicators_user`.
 191
 192 ## Additional `config.h` Options
 193
 194         #define RGB_MATRIX_KEYPRESSES // reacts to keypresses (will slow down matrix scan by a lot)
 195         #define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (not recommened)
 196         #define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
 197         #define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
 198     #define RGB_MATRIX_SKIP_FRAMES 1 // number of frames to skip when displaying animations (0 is full effect) if not defined defaults to 1
 199     #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
 200
 201 ## EEPROM storage
 202
 203 The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
 204
 205     #define EECONFIG_RGB_MATRIX (uint32_t *)16
 206
 207 Where `16` is an unused index from `eeconfig.h`.
 208
 209 ## Suspended state
 210
 211 To use the suspend feature, add this to your `<keyboard>.c`:
 212
 213         void suspend_power_down_kb(void)
 214         {
 215             rgb_matrix_set_suspend_state(true);
 216         }
 217
 218         void suspend_wakeup_init_kb(void)
 219         {
 220             rgb_matrix_set_suspend_state(false);
 221         }