is31fl3218.md (6430B)
1 # IS31FL3218 Driver {#is31fl3218-driver} 2 3 I²C LED driver by Lumissil. Supports up to 18 single-color LEDs, or 6 RGB LEDs. 4 5 [IS31FL3218 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3218_DS.pdf) 6 7 ## Usage {#usage} 8 9 The IS31FL3218 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3218` 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 += is31fl3218-mono.c # For single-color 16 SRC += is31fl3218.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 |`IS31FL3218_SDB_PIN` |*Not defined*|The GPIO pin connected to the driver's shutdown pin| 27 |`IS31FL3218_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | 28 |`IS31FL3218_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | 29 30 ### I²C Addressing {#i2c-addressing} 31 32 The IS31FL3218's 7-bit I²C address is `0x54`, available as `IS31FL3218_I2C_ADDRESS`. 33 34 ## ARM/ChibiOS Configuration {#arm-configuration} 35 36 Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. 37 38 ## LED Mapping {#led-mapping} 39 40 In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`: 41 42 ```c 43 const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { 44 /* R G B */ 45 {OUT1, OUT2, OUT3}, 46 // etc... 47 }; 48 ``` 49 50 In this example, the red, green and blue channels for the first LED index all have their anodes connected to `VCC`, and their cathodes on the `OUT1`, `OUT2` and `OUT3` pins respectively. 51 52 For the single-color driver, the principle is the same, but there is only one channel: 53 54 ```c 55 const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { 56 /* V */ 57 {OUT1}, 58 // etc... 59 }; 60 ``` 61 62 ## API {#api} 63 64 ### `struct is31fl3218_led_t` {#api-is31fl3218-led-t} 65 66 Contains the PWM register addresses for a single RGB LED. 67 68 #### Members {#api-is31fl3218-led-t-members} 69 70 - `uint8_t r` 71 The output PWM register address for the LED's red channel (RGB driver only). 72 - `uint8_t g` 73 The output PWM register address for the LED's green channel (RGB driver only). 74 - `uint8_t b` 75 The output PWM register address for the LED's blue channel (RGB driver only). 76 - `uint8_t v` 77 The output PWM register address for the LED (single-color driver only). 78 79 --- 80 81 ### `void is31fl3218_init(void)` {#api-is31fl3218-init} 82 83 Initialize the LED driver. This function should be called first. 84 85 --- 86 87 ### `void is31fl3218_write_register(uint8_t reg, uint8_t data)` {#api-is31fl3218-write-register} 88 89 Set the value of the given register. 90 91 #### Arguments {#api-is31fl3218-write-register-arguments} 92 93 - `uint8_t reg` 94 The register address. 95 - `uint8_t data` 96 The value to set. 97 98 --- 99 100 ### `void is31fl3218_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color} 101 102 Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3218_update_pwm_buffers()` after you are finished. 103 104 #### Arguments {#api-is31fl3218-set-color-arguments} 105 106 - `int index` 107 The LED index (ie. the index into the `g_is31fl3218_leds` array). 108 - `uint8_t red` 109 The red value to set. 110 - `uint8_t green` 111 The green value to set. 112 - `uint8_t blue` 113 The blue value to set. 114 115 --- 116 117 ### `void is31fl3218_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color-all} 118 119 Set the color of all LEDs (RGB driver only). 120 121 #### Arguments {#api-is31fl3218-set-color-all-arguments} 122 123 - `uint8_t red` 124 The red value to set. 125 - `uint8_t green` 126 The green value to set. 127 - `uint8_t blue` 128 The blue value to set. 129 130 --- 131 132 ### `void is31fl3218_set_value(int index, uint8_t value)` {#api-is31fl3218-set-value} 133 134 Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3218_update_pwm_buffers()` after you are finished. 135 136 #### Arguments {#api-is31fl3218-set-value-arguments} 137 138 - `int index` 139 The LED index (ie. the index into the `g_is31fl3218_leds` array). 140 - `uint8_t value` 141 The brightness value to set. 142 143 --- 144 145 ### `void is31fl3218_set_value_all(uint8_t value)` {#api-is31fl3218-set-value-all} 146 147 Set the brightness of all LEDs (single-color driver only). 148 149 #### Arguments {#api-is31fl3218-set-value-all-arguments} 150 151 - `uint8_t value` 152 The brightness value to set. 153 154 --- 155 156 ### `void is31fl3218_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3218-set-led-control-register-rgb} 157 158 Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3218_update_led_control_registers()` after you are finished. 159 160 #### Arguments {#api-is31fl3218-set-led-control-register-rgb-arguments} 161 162 - `uint8_t index` 163 The LED index (ie. the index into the `g_is31fl3218_leds` array). 164 - `bool red` 165 Enable or disable the red channel. 166 - `bool green` 167 Enable or disable the green channel. 168 - `bool blue` 169 Enable or disable the blue channel. 170 171 --- 172 173 ### `void is31fl3218_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3218-set-led-control-register-mono} 174 175 Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3218_update_led_control_registers()` after you are finished. 176 177 #### Arguments {#api-is31fl3218-set-led-control-register-mono-arguments} 178 179 - `uint8_t index` 180 The LED index (ie. the index into the `g_is31fl3218_leds` array). 181 - `bool value` 182 Enable or disable the LED. 183 184 --- 185 186 ### `void is31fl3218_update_pwm_buffers(void)` {#api-is31fl3218-update-pwm-buffers} 187 188 Flush the PWM values to the LED driver. 189 190 --- 191 192 ### `void is31fl3218_update_led_control_registers(void)` {#api-is31fl3218-update-led-control-registers} 193 194 Flush the LED control register values to the LED driver.