is31fl3236.md (7770B)
1 # IS31FL3236 Driver {#is31fl3236-driver} 2 3 I²C LED driver by Lumissil. Supports a maximum of four drivers, each controlling up to 36 single-color LEDs, or 12 RGB LEDs. 4 5 [IS31FL3236 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3236_DS.pdf) 6 7 ## Usage {#usage} 8 9 The IS31FL3236 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3236` 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 += is31fl3236-mono.c # For single-color 16 SRC += is31fl3236.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 |`IS31FL3236_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| 27 |`IS31FL3236_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | 28 |`IS31FL3236_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | 29 |`IS31FL3236_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | 30 |`IS31FL3236_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | 31 |`IS31FL3236_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | 32 |`IS31FL3236_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | 33 34 ### I²C Addressing {#i2c-addressing} 35 36 The IS31FL3236 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. 37 38 To configure this, set the `IS31FL3236_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: 39 40 |Define |Value | 41 |----------------------------|------| 42 |`IS31FL3236_I2C_ADDRESS_GND`|`0x3C`| 43 |`IS31FL3236_I2C_ADDRESS_SCL`|`0x3D`| 44 |`IS31FL3236_I2C_ADDRESS_SDA`|`0x3E`| 45 |`IS31FL3236_I2C_ADDRESS_VCC`|`0x3F`| 46 47 ## ARM/ChibiOS Configuration {#arm-configuration} 48 49 Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. 50 51 ## LED Mapping {#led-mapping} 52 53 In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`: 54 55 ```c 56 const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { 57 /* Driver 58 | R G B */ 59 {0, OUT1, OUT2, OUT3}, 60 // etc... 61 }; 62 ``` 63 64 In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to `VCC`, and their cathodes on the `OUT1`, `OUT2` and `OUT3` pins respectively. 65 66 For the single-color driver, the principle is the same, but there is only one channel: 67 68 ```c 69 const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { 70 /* Driver 71 | V */ 72 {0, OUT1}, 73 // etc... 74 }; 75 ``` 76 77 ## API {#api} 78 79 ### `struct is31fl3236_led_t` {#api-is31fl3236-led-t} 80 81 Contains the PWM register addresses for a single RGB LED. 82 83 #### Members {#api-is31fl3236-led-t-members} 84 85 - `uint8_t driver` 86 The driver index of the LED, from 0 to 3. 87 - `uint8_t r` 88 The output PWM register address for the LED's red channel (RGB driver only). 89 - `uint8_t g` 90 The output PWM register address for the LED's green channel (RGB driver only). 91 - `uint8_t b` 92 The output PWM register address for the LED's blue channel (RGB driver only). 93 - `uint8_t v` 94 The output PWM register address for the LED (single-color driver only). 95 96 --- 97 98 ### `void is31fl3236_init(uint8_t index)` {#api-is31fl3236-init} 99 100 Initialize the LED driver. This function should be called first. 101 102 #### Arguments {#api-is31fl3236-init-arguments} 103 104 - `uint8_t index` 105 The driver index. 106 107 --- 108 109 ### `void is31fl3236_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3236-write-register} 110 111 Set the value of the given register. 112 113 #### Arguments {#api-is31fl3236-write-register-arguments} 114 115 - `uint8_t index` 116 The driver index. 117 - `uint8_t reg` 118 The register address. 119 - `uint8_t data` 120 The value to set. 121 122 --- 123 124 ### `void is31fl3236_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color} 125 126 Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3236_update_pwm_buffers()` after you are finished. 127 128 #### Arguments {#api-is31fl3236-set-color-arguments} 129 130 - `int index` 131 The LED index (ie. the index into the `g_is31fl3236_leds` array). 132 - `uint8_t red` 133 The red value to set. 134 - `uint8_t green` 135 The green value to set. 136 - `uint8_t blue` 137 The blue value to set. 138 139 --- 140 141 ### `void is31fl3236_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color-all} 142 143 Set the color of all LEDs (RGB driver only). 144 145 #### Arguments {#api-is31fl3236-set-color-all-arguments} 146 147 - `uint8_t red` 148 The red value to set. 149 - `uint8_t green` 150 The green value to set. 151 - `uint8_t blue` 152 The blue value to set. 153 154 --- 155 156 ### `void is31fl3236_set_value(int index, uint8_t value)` {#api-is31fl3236-set-value} 157 158 Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3236_update_pwm_buffers()` after you are finished. 159 160 #### Arguments {#api-is31fl3236-set-value-arguments} 161 162 - `int index` 163 The LED index (ie. the index into the `g_is31fl3236_leds` array). 164 - `uint8_t value` 165 The brightness value to set. 166 167 --- 168 169 ### `void is31fl3236_set_value_all(uint8_t value)` {#api-is31fl3236-set-value-all} 170 171 Set the brightness of all LEDs (single-color driver only). 172 173 #### Arguments {#api-is31fl3236-set-value-all-arguments} 174 175 - `uint8_t value` 176 The brightness value to set. 177 178 --- 179 180 ### `void is31fl3236_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3236-set-led-control-register-rgb} 181 182 Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3236_update_led_control_registers()` after you are finished. 183 184 #### Arguments {#api-is31fl3236-set-led-control-register-rgb-arguments} 185 186 - `uint8_t index` 187 The LED index (ie. the index into the `g_is31fl3236_leds` array). 188 - `bool red` 189 Enable or disable the red channel. 190 - `bool green` 191 Enable or disable the green channel. 192 - `bool blue` 193 Enable or disable the blue channel. 194 195 --- 196 197 ### `void is31fl3236_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3236-set-led-control-register-mono} 198 199 Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3236_update_led_control_registers()` after you are finished. 200 201 #### Arguments {#api-is31fl3236-set-led-control-register-mono-arguments} 202 203 - `uint8_t index` 204 The LED index (ie. the index into the `g_is31fl3236_leds` array). 205 - `bool value` 206 Enable or disable the LED. 207 208 --- 209 210 ### `void is31fl3236_update_pwm_buffers(uint8_t index)` {#api-is31fl3236-update-pwm-buffers} 211 212 Flush the PWM values to the LED driver. 213 214 #### Arguments {#api-is31fl3236-update-pwm-buffers-arguments} 215 216 - `uint8_t index` 217 The driver index. 218 219 --- 220 221 ### `void is31fl3236_update_led_control_registers(uint8_t index)` {#api-is31fl3236-update-led-control-registers} 222 223 Flush the LED control register values to the LED driver. 224 225 #### Arguments {#api-is31fl3236-update-led-control-registers-arguments} 226 227 - `uint8_t index` 228 The driver index.