qmk_firmware/docs/feature_led_matrix.md
James Young c66df16644
2020 November 28 Breaking Changes Update (#11053)
* Branch point for 2020 November 28 Breaking Change                                                

* Remove matrix_col_t to allow MATRIX_ROWS > 32 (#10183)                                           

* Add support for soft serial to ATmega32U2 (#10204)                                               

* Change MIDI velocity implementation to allow direct control of velocity value (#9940)            

* Add ability to build a subset of all keyboards based on platform.                                

* Actually use eeprom_driver_init().                                                               

* Make bootloader_jump weak for ChibiOS. (#10417)                                                  

* Joystick 16-bit support (#10439)                                                                 

* Per-encoder resolutions (#10259)                                                                 

* Share button state from mousekey to pointing_device (#10179)                                     

* Add hotfix for chibios keyboards not wake (#10088)                                               

* Add advanced/efficient RGB Matrix Indicators (#8564)                                             

* Naming change.                                                                                   

* Support for STM32 GPIOF,G,H,I,J,K (#10206)                                                       

* Add milc as a dependency and remove the installed milc (#10563)                                  

* ChibiOS upgrade: early init conversions (#10214)                                                 

* ChibiOS upgrade: configuration file migrator (#9952)                                             

* Haptic and solenoid cleanup (#9700)                                                              

* XD75 cleanup (#10524)                                                                            

* OLED display update interval support (#10388)                                                    

* Add definition based on currently-selected serial driver. (#10716)                               

* New feature: Retro Tapping per key (#10622)                                                      

* Allow for modification of output RGB values when using rgblight/rgb_matrix. (#10638)             

* Add housekeeping task callbacks so that keyboards/keymaps are capable of executing code for each main loop iteration. (#10530)

* Rescale both ChibiOS and AVR backlighting.                                                       

* Reduce Helix keyboard build variation (#8669)                                                    

* Minor change to behavior allowing display updates to continue between task ticks (#10750)        

* Some GPIO manipulations in matrix.c change to atomic. (#10491)                                   

* qmk cformat (#10767)                                                                             

* [Keyboard] Update the Speedo firmware for v3.0 (#10657)                                          

* Maartenwut/Maarten namechange to evyd13/Evy (#10274)                                             

* [quantum] combine repeated lines of code (#10837)                                                

* Add step sequencer feature (#9703)                                                               

* aeboards/ext65 refactor (#10820)                                                                 

* Refactor xelus/dawn60 for Rev2 later (#10584)                                                    

* add DEBUG_MATRIX_SCAN_RATE_ENABLE to common_features.mk (#10824)                                 

* [Core] Added `add_oneshot_mods` & `del_oneshot_mods` (#10549)                                    

* update chibios os usb for the otg driver (#8893)                                                 

* Remove HD44780 References, Part 4 (#10735)                                                       

* [Keyboard] Add Valor FRL TKL (+refactor) (#10512)                                                

* Fix cursor position bug in oled_write_raw functions (#10800)                                     

* Fixup version.h writing when using SKIP_VERSION=yes (#10972)                                     

* Allow for certain code in the codebase assuming length of string. (#10974)                       

* Add AT90USB support for serial.c (#10706)                                                        

* Auto shift: support repeats and early registration (#9826)                                       

* Rename ledmatrix.h to match .c file (#7949)                                                      

* Split RGB_MATRIX_ENABLE into _ENABLE and _DRIVER (#10231)                                        

* Split LED_MATRIX_ENABLE into _ENABLE and _DRIVER (#10840)                                        

* Merge point for 2020 Nov 28 Breaking Change
2020-11-28 12:02:18 -08:00

3.2 KiB

LED Matrix Lighting

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.

If you want to use RGB LED's you should use the RGB Matrix Subsystem instead.

Driver configuration

IS31FL3731

There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your rules.mk:

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
ISSI_TIMEOUT (Optional) How long to wait for i2c messages 100
ISSI_PERSISTENCE (Optional) Retry failed messages this many times 0
LED_DRIVER_COUNT (Required) How many LED driver IC's are present
LED_DRIVER_LED_COUNT (Required) How many LED lights are present across all drivers
LED_DRIVER_ADDR_1 (Required) Address for the first LED driver
LED_DRIVER_ADDR_2 (Optional) Address for the second LED driver
LED_DRIVER_ADDR_3 (Optional) Address for the third LED driver
LED_DRIVER_ADDR_4 (Optional) Address for the fourth LED driver

Here is an example using 2 drivers.

// 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:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define LED_DRIVER_ADDR_1 0b1110100
#define LED_DRIVER_ADDR_2 0b1110110

#define LED_DRIVER_COUNT 2
#define LED_DRIVER_1_LED_COUNT 25
#define LED_DRIVER_2_LED_COUNT 24
#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL

Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.

Define these arrays listing all the LEDs in your <keyboard>.c:

const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
 *   driver
 *   |  LED address
 *   |  | */
    {0, C3_3},
    ....
}

Where Cx_y is the location of the LED in the matrix defined by the datasheet 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 ).

Keycodes

All LED matrix keycodes are currently shared with the backlight system.

LED Matrix Effects

Currently no LED matrix effects have been created.

Custom layer effects

Custom layer effects can be done by defining this in your <keyboard>.c:

void led_matrix_indicators_kb(void) {
    led_matrix_set_index_value(index, value);
}

A similar function works in the keymap as led_matrix_indicators_user.

Suspended state

To use the suspend feature, add this to your <keyboard>.c:

void suspend_power_down_kb(void)
{
    led_matrix_set_suspend_state(true);
}

void suspend_wakeup_init_kb(void)
{
    led_matrix_set_suspend_state(false);
}