is31fl3731.md (8604B)
1 # IS31FL3731 Driver {#is31fl3731-driver} 2 3 I²C Charlieplexed 16x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. 4 5 [IS31FL3731 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3731_DS.pdf) 6 7 ## Usage {#usage} 8 9 The IS31FL3731 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3731` driver set, and you would use those APIs instead. 10 11 However, if you need to use the driver standalone, add this to your `rules.mk`: 12 13 ```make 14 COMMON_VPATH += $(DRIVER_PATH)/led/issi 15 SRC += is31fl3731-mono.c # For single-color 16 SRC += is31fl3731.c # For RGB 17 I2C_DRIVER_REQUIRED = yes 18 ``` 19 20 ## Basic Configuration {#basic-configuration} 21 22 Add the following to your `config.h`: 23 24 |Define |Default |Description | 25 |----------------------------|-------------|----------------------------------------------------| 26 |`IS31FL3731_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| 27 |`IS31FL3731_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | 28 |`IS31FL3731_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | 29 |`IS31FL3731_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | 30 |`IS31FL3731_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | 31 |`IS31FL3731_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | 32 |`IS31FL3731_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | 33 |`IS31FL3731_DEGHOST` |*Not defined*|Enable ghost image prevention | 34 35 ### I²C Addressing {#i2c-addressing} 36 37 The IS31FL3731 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. 38 39 To configure this, set the `IS31FL3731_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: 40 41 |Define |Value | 42 |----------------------------|------| 43 |`IS31FL3731_I2C_ADDRESS_GND`|`0x74`| 44 |`IS31FL3731_I2C_ADDRESS_SCL`|`0x75`| 45 |`IS31FL3731_I2C_ADDRESS_SDA`|`0x76`| 46 |`IS31FL3731_I2C_ADDRESS_VCC`|`0x77`| 47 48 ### De-Ghosting {#de-ghosting} 49 50 This setting enables the de-ghosting feature on the IS31FL3731. See this [Application Note](https://www.lumissil.com/assets/pdf/core/IS31FL3731_AN.pdf) (p. 15) for more information. 51 52 To enable, add the following to your `config.h`: 53 54 ```c 55 #define IS31FL3731_DEGHOST 56 ``` 57 58 ## ARM/ChibiOS Configuration {#arm-configuration} 59 60 Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. 61 62 ## LED Mapping {#led-mapping} 63 64 In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`: 65 66 ```c 67 const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { 68 /* Driver 69 * | R G B */ 70 {0, C1_1, C1_2, C1_3}, 71 // etc... 72 }; 73 ``` 74 75 In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `CA1` pin, and their anodes on the `CA2`, `CA3` and `CA4` pins respectively. 76 77 For the single-color driver, the principle is the same, but there is only one channel: 78 79 ```c 80 const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { 81 /* Driver 82 * | V */ 83 {0, C1_1}, 84 // etc... 85 }; 86 ``` 87 88 These values correspond to the register indices as shown in the datasheet on page 11, figure 8. 89 90 ## API {#api} 91 92 ### `struct is31fl3731_led_t` {#api-is31fl3731-led-t} 93 94 Contains the PWM register addresses for a single RGB LED. 95 96 #### Members {#api-is31fl3731-led-t-members} 97 98 - `uint8_t driver` 99 The driver index of the LED, from 0 to 3. 100 - `uint8_t r` 101 The output PWM register address for the LED's red channel (RGB driver only). 102 - `uint8_t g` 103 The output PWM register address for the LED's green channel (RGB driver only). 104 - `uint8_t b` 105 The output PWM register address for the LED's blue channel (RGB driver only). 106 - `uint8_t v` 107 The output PWM register address for the LED (single-color driver only). 108 109 --- 110 111 ### `void is31fl3731_init(uint8_t index)` {#api-is31fl3731-init} 112 113 Initialize the LED driver. This function should be called first. 114 115 #### Arguments {#api-is31fl3731-init-arguments} 116 117 - `uint8_t index` 118 The driver index. 119 120 --- 121 122 ### `void is31fl3731_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3731-write-register} 123 124 Set the value of the given register. 125 126 #### Arguments {#api-is31fl3731-write-register-arguments} 127 128 - `uint8_t index` 129 The driver index. 130 - `uint8_t reg` 131 The register address. 132 - `uint8_t data` 133 The value to set. 134 135 --- 136 137 ### `void is31fl3731_select_page(uint8_t index, uint8_t page)` {#api-is31fl3731-select-page} 138 139 Change the current page for configuring the LED driver. 140 141 #### Arguments {#api-is31fl3731-select-page-arguments} 142 143 - `uint8_t index` 144 The driver index. 145 - `uint8_t page` 146 The page number to select. 147 148 --- 149 150 ### `void is31fl3731_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color} 151 152 Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3731_update_pwm_buffers()` after you are finished. 153 154 #### Arguments {#api-is31fl3731-set-color-arguments} 155 156 - `int index` 157 The LED index (ie. the index into the `g_is31fl3731_leds` array). 158 - `uint8_t red` 159 The red value to set. 160 - `uint8_t green` 161 The green value to set. 162 - `uint8_t blue` 163 The blue value to set. 164 165 --- 166 167 ### `void is31fl3731_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color-all} 168 169 Set the color of all LEDs (RGB driver only). 170 171 #### Arguments {#api-is31fl3731-set-color-all-arguments} 172 173 - `uint8_t red` 174 The red value to set. 175 - `uint8_t green` 176 The green value to set. 177 - `uint8_t blue` 178 The blue value to set. 179 180 --- 181 182 ### `void is31fl3731_set_value(int index, uint8_t value)` {#api-is31fl3731-set-value} 183 184 Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3731_update_pwm_buffers()` after you are finished. 185 186 #### Arguments {#api-is31fl3731-set-value-arguments} 187 188 - `int index` 189 The LED index (ie. the index into the `g_is31fl3731_leds` array). 190 - `uint8_t value` 191 The brightness value to set. 192 193 --- 194 195 ### `void is31fl3731_set_value_all(uint8_t value)` {#api-is31fl3731-set-value-all} 196 197 Set the brightness of all LEDs (single-color driver only). 198 199 #### Arguments {#api-is31fl3731-set-value-all-arguments} 200 201 - `uint8_t value` 202 The brightness value to set. 203 204 --- 205 206 ### `void is31fl3731_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3731-set-led-control-register-rgb} 207 208 Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3731_update_led_control_registers()` after you are finished. 209 210 #### Arguments {#api-is31fl3731-set-led-control-register-rgb-arguments} 211 212 - `uint8_t index` 213 The LED index (ie. the index into the `g_is31fl3731_leds` array). 214 - `bool red` 215 Enable or disable the red channel. 216 - `bool green` 217 Enable or disable the green channel. 218 - `bool blue` 219 Enable or disable the blue channel. 220 221 --- 222 223 ### `void is31fl3731_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3731-set-led-control-register-mono} 224 225 Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3731_update_led_control_registers()` after you are finished. 226 227 #### Arguments {#api-is31fl3731-set-led-control-register-mono-arguments} 228 229 - `uint8_t index` 230 The LED index (ie. the index into the `g_is31fl3731_leds` array). 231 - `bool value` 232 Enable or disable the LED. 233 234 --- 235 236 ### `void is31fl3731_update_pwm_buffers(uint8_t index)` {#api-is31fl3731-update-pwm-buffers} 237 238 Flush the PWM values to the LED driver. 239 240 #### Arguments {#api-is31fl3731-update-pwm-buffers-arguments} 241 242 - `uint8_t index` 243 The driver index. 244 245 --- 246 247 ### `void is31fl3731_update_led_control_registers(uint8_t index)` {#api-is31fl3731-update-led-control-registers} 248 249 Flush the LED control register values to the LED driver. 250 251 #### Arguments {#api-is31fl3731-update-led-control-registers-arguments} 252 253 - `uint8_t index` 254 The driver index.