logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

is31fl3731.md (8604B)

    

  1. # IS31FL3731 Driver {#is31fl3731-driver}
  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.
  5. [IS31FL3731 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3731_DS.pdf)
  7. ## Usage {#usage}
  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.
  11. However, if you need to use the driver standalone, add this to your `rules.mk`:
  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. ```
  20. ## Basic Configuration {#basic-configuration}
  22. Add the following to your `config.h`:
  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                       |
  35. ### I²C Addressing {#i2c-addressing}
  37. The IS31FL3731 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected.
  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:
  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`|
  48. ### De-Ghosting {#de-ghosting}
  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.
  52. To enable, add the following to your `config.h`:
  54. ```c
  55. #define IS31FL3731_DEGHOST
  56. ```
  58. ## ARM/ChibiOS Configuration {#arm-configuration}
  60. Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level.
  62. ## LED Mapping {#led-mapping}
  64. In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboard>.c`:
  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. ```
  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.
  77. For the single-color driver, the principle is the same, but there is only one channel:
  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. ```
  88. These values correspond to the register indices as shown in the datasheet on page 11, figure 8.
  90. ## API {#api}
  92. ### `struct is31fl3731_led_t` {#api-is31fl3731-led-t}
  94. Contains the PWM register addresses for a single RGB LED.
  96. #### Members {#api-is31fl3731-led-t-members}
  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).
  109. ---
  111. ### `void is31fl3731_init(uint8_t index)` {#api-is31fl3731-init}
  113. Initialize the LED driver. This function should be called first.
  115. #### Arguments {#api-is31fl3731-init-arguments}
  117.  - `uint8_t index`  
  118.    The driver index.
  120. ---
  122. ### `void is31fl3731_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3731-write-register}
  124. Set the value of the given register.
  126. #### Arguments {#api-is31fl3731-write-register-arguments}
  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.
  135. ---
  137. ### `void is31fl3731_select_page(uint8_t index, uint8_t page)` {#api-is31fl3731-select-page}
  139. Change the current page for configuring the LED driver.
  141. #### Arguments {#api-is31fl3731-select-page-arguments}
  143.  - `uint8_t index`  
  144.    The driver index.
  145.  - `uint8_t page`  
  146.    The page number to select.
  148. ---
  150. ### `void is31fl3731_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color}
  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.
  154. #### Arguments {#api-is31fl3731-set-color-arguments}
  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.
  165. ---
  167. ### `void is31fl3731_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color-all}
  169. Set the color of all LEDs (RGB driver only).
  171. #### Arguments {#api-is31fl3731-set-color-all-arguments}
  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.
  180. ---
  182. ### `void is31fl3731_set_value(int index, uint8_t value)` {#api-is31fl3731-set-value}
  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.
  186. #### Arguments {#api-is31fl3731-set-value-arguments}
  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.
  193. ---
  195. ### `void is31fl3731_set_value_all(uint8_t value)` {#api-is31fl3731-set-value-all}
  197. Set the brightness of all LEDs (single-color driver only).
  199. #### Arguments {#api-is31fl3731-set-value-all-arguments}
  201.  - `uint8_t value`  
  202.    The brightness value to set.
  204. ---
  206. ### `void is31fl3731_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3731-set-led-control-register-rgb}
  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.
  210. #### Arguments {#api-is31fl3731-set-led-control-register-rgb-arguments}
  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.
  221. ---
  223. ### `void is31fl3731_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3731-set-led-control-register-mono}
  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.
  227. #### Arguments {#api-is31fl3731-set-led-control-register-mono-arguments}
  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.
  234. ---
  236. ### `void is31fl3731_update_pwm_buffers(uint8_t index)` {#api-is31fl3731-update-pwm-buffers}
  238. Flush the PWM values to the LED driver.
  240. #### Arguments {#api-is31fl3731-update-pwm-buffers-arguments}
  242.  - `uint8_t index`  
  243.    The driver index.
  245. ---
  247. ### `void is31fl3731_update_led_control_registers(uint8_t index)` {#api-is31fl3731-update-led-control-registers}
  249. Flush the LED control register values to the LED driver.
  251. #### Arguments {#api-is31fl3731-update-led-control-registers-arguments}
  253.  - `uint8_t index`  
  254.    The driver index.