diff options
Diffstat (limited to 'docs/drivers')
-rw-r--r-- | docs/drivers/aw20216s.md | 133 | ||||
-rw-r--r-- | docs/drivers/is31fl3218.md | 194 | ||||
-rw-r--r-- | docs/drivers/is31fl3236.md | 228 | ||||
-rw-r--r-- | docs/drivers/is31fl3729.md | 300 | ||||
-rw-r--r-- | docs/drivers/is31fl3731.md | 254 | ||||
-rw-r--r-- | docs/drivers/is31fl3733.md | 338 | ||||
-rw-r--r-- | docs/drivers/is31fl3736.md | 322 | ||||
-rw-r--r-- | docs/drivers/is31fl3737.md | 310 | ||||
-rw-r--r-- | docs/drivers/is31fl3741.md | 310 | ||||
-rw-r--r-- | docs/drivers/is31fl3742a.md | 310 | ||||
-rw-r--r-- | docs/drivers/is31fl3743a.md | 320 | ||||
-rw-r--r-- | docs/drivers/is31fl3745.md | 320 | ||||
-rw-r--r-- | docs/drivers/is31fl3746a.md | 327 | ||||
-rw-r--r-- | docs/drivers/snled27351.md | 245 |
14 files changed, 3911 insertions, 0 deletions
diff --git a/docs/drivers/aw20216s.md b/docs/drivers/aw20216s.md new file mode 100644 index 0000000000..36a6d63c33 --- /dev/null +++ b/docs/drivers/aw20216s.md @@ -0,0 +1,133 @@ +# AW20216S Driver {#aw20216s-driver} + +SPI 18x12 LED matrix driver by Awinic. Supports a maximum of four drivers, each controlling up to 216 single-color LEDs, or 72 RGB LEDs. + +[AW20216S Datasheet](https://doc.awinic.com/doc/20230609wm/b6a9c70b-e1bd-495b-925f-bcbed3fc2620.pdf) + +## Usage {#usage} + +The AW20216S driver code is automatically included if you are using the [RGB Matrix](../features/rgb_matrix) feature with the `aw20216s` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led +SRC += aw20216s.c +SPI_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|-------------|-------------------------------------------------------------| +|`AW20216S_CS_PIN_1` |*Not defined*|The GPIO pin connected to the first driver's Chip Select pin | +|`AW20216S_CS_PIN_2` |*Not defined*|The GPIO pin connected to the second driver's Chip Select pin| +|`AW20216S_EN_PIN` |*Not defined*|The GPIO pin connected to the drivers' Enable pins | +|`AW20216S_SPI_MODE` |`0` |The SPI mode to use | +|`AW20216S_SPI_DIVISOR` |`4` |The SPI divisor to use | +|`AW20216S_SCALING_MAX` |`150` |The scaling value | +|`AW20216S_GLOBAL_CURRENT_MAX`|`150` |The global current control value | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. To adjust it, add the following to your `config.h`: + +```c +#define AW20216S_GLOBAL_CURRENT_MAX 150 +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure SPI](spi#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const aw20216s_led_t PROGMEM g_aw20216s_leds[AW20216S_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the first LED index on driver 0 has its red channel on `SW1_CS1`, green on `SW1_CS2` and blue on `SW1_CS3`. + +These values correspond to the matrix locations as shown in the datasheet on page 16, figure 16. + +## API {#api} + +### `struct aw20216s_led_t` {#api-aw20216s-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-aw20216s-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel. + - `uint8_t g` + The output PWM register address for the LED's green channel. + - `uint8_t b` + The output PWM register address for the LED's blue channel. + +--- + +### `void aw20216s_init(pin_t cs_pin)` {#api-aw20216s-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-aw20216s-init-arguments} + + - `pin_t cs_pin` + The GPIO connected to the Chip Select pin of the LED driver to initialize. + +--- + +### `void aw20216s_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-aw20216s-set-color} + +Set the color of a single LED. This function does not immediately update the LEDs; call `aw20216s_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-aw20216s-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_aw20216s_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void aw20216s_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-aw20216s-set-color-all} + +Set the color of all LEDs. + +#### Arguments {#api-aw20216s-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void aw20216s_update_pwm_buffers(pin_t cs_pin, uint8_t index)` {#api-aw20216s-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-aw20216s-update-pwm-buffers-arguments} + + - `pin_t cs_pin` + The GPIO connected to the Chip Select pin of the driver. + - `uint8_t index` + The index of the driver. diff --git a/docs/drivers/is31fl3218.md b/docs/drivers/is31fl3218.md new file mode 100644 index 0000000000..1c98069120 --- /dev/null +++ b/docs/drivers/is31fl3218.md @@ -0,0 +1,194 @@ +# IS31FL3218 Driver {#is31fl3218-driver} + +I²C LED driver by Lumissil. Supports up to 18 single-color LEDs, or 6 RGB LEDs. + +[IS31FL3218 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3218_DS.pdf) + +## Usage {#usage} + +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. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3218-mono.c # For single-color +SRC += is31fl3218.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|---------------------------------------------------| +|`IS31FL3218_SDB_PIN` |*Not defined*|The GPIO pin connected to the driver's shutdown pin| +|`IS31FL3218_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3218_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3218's 7-bit I²C address is `0x54`, available as `IS31FL3218_I2C_ADDRESS`. + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { +/* R G B */ + {OUT1, OUT2, OUT3}, + // etc... +}; +``` + +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. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3218_led_t PROGMEM g_is31fl3218_leds[IS31FL3218_LED_COUNT] = { +/* V */ + {OUT1}, + // etc... +}; +``` + +## API {#api} + +### `struct is31fl3218_led_t` {#api-is31fl3218-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3218-led-t-members} + + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3218_init(void)` {#api-is31fl3218-init} + +Initialize the LED driver. This function should be called first. + +--- + +### `void is31fl3218_write_register(uint8_t reg, uint8_t data)` {#api-is31fl3218-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3218-write-register-arguments} + + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3218_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color} + +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. + +#### Arguments {#api-is31fl3218-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3218_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3218-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3218-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3218_set_value(int index, uint8_t value)` {#api-is31fl3218-set-value} + +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. + +#### Arguments {#api-is31fl3218-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3218_set_value_all(uint8_t value)` {#api-is31fl3218-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3218-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3218_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3218-set-led-control-register-rgb} + +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. + +#### Arguments {#api-is31fl3218-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3218_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3218-set-led-control-register-mono} + +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. + +#### Arguments {#api-is31fl3218-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3218_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3218_update_pwm_buffers(void)` {#api-is31fl3218-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +--- + +### `void is31fl3218_update_led_control_registers(void)` {#api-is31fl3218-update-led-control-registers} + +Flush the LED control register values to the LED driver. diff --git a/docs/drivers/is31fl3236.md b/docs/drivers/is31fl3236.md new file mode 100644 index 0000000000..98e05e4abd --- /dev/null +++ b/docs/drivers/is31fl3236.md @@ -0,0 +1,228 @@ +# IS31FL3236 Driver {#is31fl3236-driver} + +I²C LED driver by Lumissil. Supports a maximum of four drivers, each controlling up to 36 single-color LEDs, or 12 RGB LEDs. + +[IS31FL3236 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3236_DS.pdf) + +## Usage {#usage} + +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. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3236-mono.c # For single-color +SRC += is31fl3236.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`IS31FL3236_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3236_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3236_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3236_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`IS31FL3236_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`IS31FL3236_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`IS31FL3236_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3236 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +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: + +|Define |Value | +|----------------------------|------| +|`IS31FL3236_I2C_ADDRESS_GND`|`0x3C`| +|`IS31FL3236_I2C_ADDRESS_SCL`|`0x3D`| +|`IS31FL3236_I2C_ADDRESS_SDA`|`0x3E`| +|`IS31FL3236_I2C_ADDRESS_VCC`|`0x3F`| + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { +/* Driver + | R G B */ + {0, OUT1, OUT2, OUT3}, + // etc... +}; +``` + +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. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3236_led_t PROGMEM g_is31fl3236_leds[IS31FL3236_LED_COUNT] = { +/* Driver + | V */ + {0, OUT1}, + // etc... +}; +``` + +## API {#api} + +### `struct is31fl3236_led_t` {#api-is31fl3236-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3236-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3236_init(uint8_t index)` {#api-is31fl3236-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3236-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3236_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3236-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3236-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3236_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color} + +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. + +#### Arguments {#api-is31fl3236-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3236_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3236-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3236-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3236_set_value(int index, uint8_t value)` {#api-is31fl3236-set-value} + +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. + +#### Arguments {#api-is31fl3236-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3236_set_value_all(uint8_t value)` {#api-is31fl3236-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3236-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3236_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3236-set-led-control-register-rgb} + +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. + +#### Arguments {#api-is31fl3236-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3236_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3236-set-led-control-register-mono} + +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. + +#### Arguments {#api-is31fl3236-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3236_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3236_update_pwm_buffers(uint8_t index)` {#api-is31fl3236-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3236-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3236_update_led_control_registers(uint8_t index)` {#api-is31fl3236-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3236-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3729.md b/docs/drivers/is31fl3729.md new file mode 100644 index 0000000000..32618d82d5 --- /dev/null +++ b/docs/drivers/is31fl3729.md @@ -0,0 +1,300 @@ +# IS31FL3729 Driver {#is31fl3729-driver} + +I²C 16x8/15x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 135 single-color LEDs, or 45 RGB LEDs. + +[IS31FL3729 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3729_DS.pdf) + +## Usage {#usage} + +The IS31FL3729 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3729` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3729-mono.c # For single-color +SRC += is31fl3729.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|--------------------------------------|----------------------------------------------------| +|`IS31FL3729_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3729_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3729_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3729_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3729_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3729_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3729_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3729_PWM_FREQUENCY` |`IS31FL3729_PWM_FREQUENCY_32K_HZ` |The PWM frequency of the LEDs | +|`IS31FL3729_SW_PULLDOWN` |`IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF`|The `SWx` pullup resistor value | +|`IS31FL3729_CS_PULLUP` |`IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF` |The `CSx` pulldown resistor value | +|`IS31FL3729_GLOBAL_CURRENT` |`0x40` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3729 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +To configure this, set the `IS31FL3729_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3729_I2C_ADDRESS_GND`|`0x34`| +|`IS31FL3729_I2C_ADDRESS_SCL`|`0x35`| +|`IS31FL3729_I2C_ADDRESS_SDA`|`0x36`| +|`IS31FL3729_I2C_ADDRESS_VCC`|`0x37`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3729_PWM_FREQUENCY IS31FL3729_PWM_FREQUENCY_32K_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|----------------| +|`IS31FL3729_PWM_FREQUENCY_55K_HZ` |55 kHz | +|`IS31FL3729_PWM_FREQUENCY_32K_HZ` |32 kHz (default)| +|`IS31FL3729_PWM_FREQUENCY_4K_HZ` |4 kHz | +|`IS31FL3729_PWM_FREQUENCY_2K_HZ` |2 kHz | +|`IS31FL3729_PWM_FREQUENCY_1K_HZ` |1 kHz | +|`IS31FL3729_PWM_FREQUENCY_500_HZ` |500 Hz | +|`IS31FL3729_PWM_FREQUENCY_250_HZ` |250 Hz | +|`IS31FL3729_PWM_FREQUENCY_80K_HZ` |80 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 18) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3729_SW_PULLDOWN IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF +#define IS31FL3729_CS_PULLUP IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3729_SW_PULLDOWN` are: + +|Define |Resistance | +|---------------------------------------|------------------------------| +|`IS31FL3729_SW_PULLDOWN_0_OHM` |None | +|`IS31FL3729_SW_PULLDOWN_0K5_OHM_SW_OFF`|0.5 kΩ in SWy off time | +|`IS31FL3729_SW_PULLDOWN_1K_OHM_SW_OFF` |1 kΩ in SWy off time | +|`IS31FL3729_SW_PULLDOWN_2K_OHM_SW_OFF` |2 kΩ in SWy off time (default)| +|`IS31FL3729_SW_PULLDOWN_1K_OHM` |1 kΩ | +|`IS31FL3729_SW_PULLDOWN_2K_OHM` |2 kΩ | +|`IS31FL3729_SW_PULLDOWN_4K_OHM` |4 kΩ | +|`IS31FL3729_SW_PULLDOWN_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3729_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------------------|------------------------------| +|`IS31FL3729_CS_PULLUP_0_OHM` |None | +|`IS31FL3729_CS_PULLUP_0K5_OHM_CS_OFF`|0.5 kΩ in CSx off time | +|`IS31FL3729_CS_PULLUP_1K_OHM_CS_OFF` |1 kΩ in CSx off time | +|`IS31FL3729_CS_PULLUP_2K_OHM_CS_OFF` |2 kΩ in CSx off time (default)| +|`IS31FL3729_CS_PULLUP_1K_OHM` |1 kΩ | +|`IS31FL3729_CS_PULLUP_2K_OHM` |2 kΩ | +|`IS31FL3729_CS_PULLUP_4K_OHM` |4 kΩ | +|`IS31FL3729_CS_PULLUP_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is 64, but if you need to adjust it, add the following to your `config.h`: + +```c +#define IS31FL3729_GLOBAL_CURRENT 0x40 +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3729_led_t PROGMEM g_is31fl3729_leds[IS31FL3729_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 9. + +## API {#api} + +### `struct is31fl3729_led_t` {#api-is31fl3729-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3729-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3729_init(uint8_t index)` {#api-is31fl3729-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3729-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3729_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3729-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3729-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3729_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3729_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3729_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3729-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3729_set_value(int index, uint8_t value)` {#api-is31fl3729-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3729_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3729_set_value_all(uint8_t value)` {#api-is31fl3729-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3729-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3729_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3729-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3729_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3729_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3729-set-scaling-register-mono} + +Configure the scaling registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3729_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3729-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3729_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3729_update_pwm_buffers(uint8_t index)` {#api-is31fl3729-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3729-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3729_update_scaling_registers(uint8_t index)` {#api-is31fl3729-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3729-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3731.md b/docs/drivers/is31fl3731.md new file mode 100644 index 0000000000..0d928a919e --- /dev/null +++ b/docs/drivers/is31fl3731.md @@ -0,0 +1,254 @@ +# IS31FL3731 Driver {#is31fl3731-driver} + +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. + +[IS31FL3731 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3731_DS.pdf) + +## Usage {#usage} + +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. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3731-mono.c # For single-color +SRC += is31fl3731.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`IS31FL3731_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3731_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3731_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3731_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`IS31FL3731_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`IS31FL3731_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`IS31FL3731_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | +|`IS31FL3731_DEGHOST` |*Not defined*|Enable ghost image prevention | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3731 has four possible 7-bit I²C addresses, depending on how the `AD` pin is connected. + +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: + +|Define |Value | +|----------------------------|------| +|`IS31FL3731_I2C_ADDRESS_GND`|`0x74`| +|`IS31FL3731_I2C_ADDRESS_SCL`|`0x75`| +|`IS31FL3731_I2C_ADDRESS_SDA`|`0x76`| +|`IS31FL3731_I2C_ADDRESS_VCC`|`0x77`| + +### De-Ghosting {#de-ghosting} + +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. + +To enable, add the following to your `config.h`: + +```c +#define IS31FL3731_DEGHOST +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { +/* Driver + * | R G B */ + {0, C1_1, C1_2, C1_3}, + // etc... +}; +``` + +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. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[IS31FL3731_LED_COUNT] = { +/* Driver + * | V */ + {0, C1_1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 11, figure 8. + +## API {#api} + +### `struct is31fl3731_led_t` {#api-is31fl3731-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3731-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3731_init(uint8_t index)` {#api-is31fl3731-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3731-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3731_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3731-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3731-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3731_select_page(uint8_t index, uint8_t page)` {#api-is31fl3731-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3731-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3731_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color} + +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. + +#### Arguments {#api-is31fl3731-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3731_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3731-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3731-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3731_set_value(int index, uint8_t value)` {#api-is31fl3731-set-value} + +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. + +#### Arguments {#api-is31fl3731-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3731_set_value_all(uint8_t value)` {#api-is31fl3731-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3731-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3731_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3731-set-led-control-register-rgb} + +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. + +#### Arguments {#api-is31fl3731-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3731_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3731-set-led-control-register-mono} + +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. + +#### Arguments {#api-is31fl3731-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3731_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3731_update_pwm_buffers(uint8_t index)` {#api-is31fl3731-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3731-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3731_update_led_control_registers(uint8_t index)` {#api-is31fl3731-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3731-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3733.md b/docs/drivers/is31fl3733.md new file mode 100644 index 0000000000..e299f785bd --- /dev/null +++ b/docs/drivers/is31fl3733.md @@ -0,0 +1,338 @@ +# IS31FL3733 Driver {#is31fl3733-driver} + +I²C 12x16 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 192 single-color LEDs, or 64 RGB LEDs. + +[IS31FL3733 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3733_DS.pdf) + +## Usage {#usage} + +The IS31FL3733 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3733` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3733-mono.c # For single-color +SRC += is31fl3733.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3733_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3733_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3733_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3733_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3733_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3733_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3733_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3733_SYNC_1` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3733_SYNC_2` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3733_SYNC_3` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3733_SYNC_4` |`IS31FL3733_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3733_PWM_FREQUENCY` |`IS31FL3733_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3733B only) | +|`IS31FL3733_SW_PULLUP` |`IS31FL3733_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3733_CS_PULLDOWN` |`IS31FL3733_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3733_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3733 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3733_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3733_I2C_ADDRESS_GND_GND`|`0x50`| +|`IS31FL3733_I2C_ADDRESS_GND_SCL`|`0x51`| +|`IS31FL3733_I2C_ADDRESS_GND_SDA`|`0x52`| +|`IS31FL3733_I2C_ADDRESS_GND_VCC`|`0x53`| +|`IS31FL3733_I2C_ADDRESS_SCL_GND`|`0x54`| +|`IS31FL3733_I2C_ADDRESS_SCL_SCL`|`0x55`| +|`IS31FL3733_I2C_ADDRESS_SCL_SDA`|`0x56`| +|`IS31FL3733_I2C_ADDRESS_SCL_VCC`|`0x57`| +|`IS31FL3733_I2C_ADDRESS_SDA_GND`|`0x58`| +|`IS31FL3733_I2C_ADDRESS_SDA_SCL`|`0x59`| +|`IS31FL3733_I2C_ADDRESS_SDA_SDA`|`0x5A`| +|`IS31FL3733_I2C_ADDRESS_SDA_VCC`|`0x5B`| +|`IS31FL3733_I2C_ADDRESS_VCC_GND`|`0x5C`| +|`IS31FL3733_I2C_ADDRESS_VCC_SCL`|`0x5D`| +|`IS31FL3733_I2C_ADDRESS_VCC_SDA`|`0x5E`| +|`IS31FL3733_I2C_ADDRESS_VCC_VCC`|`0x5F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3733 drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3733_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------|---------------------------| +|`IS31FL3733_SYNC_NONE` |No synchronization | +|`IS31FL3733_SYNC_MASTER`|Driver configured as master| +|`IS31FL3733_SYNC_SLAVE` |Driver configured as slave | + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3733B only) by adding the following to your `config.h`: + +```c +#define IS31FL3733_PWM_FREQUENCY IS31FL3733_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3733_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3733_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3733_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3733_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3733_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3733_SW_PULLUP IS31FL3733_PUR_0_OHM +#define IS31FL3733_CS_PULLDOWN IS31FL3733_PUR_0_OHM +``` + +Valid values for `IS31FL3733_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3733_PUR_0_OHM` |None (default)| +|`IS31FL3733_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3733_PUR_1K_OHM` |1 kΩ | +|`IS31FL3733_PUR_2K_OHM` |2 kΩ | +|`IS31FL3733_PUR_4K_OHM` |4 kΩ | +|`IS31FL3733_PUR_8K_OHM` |8 kΩ | +|`IS31FL3733_PUR_16K_OHM`|16 kΩ | +|`IS31FL3733_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3733_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3733_PDR_0_OHM` |None (default)| +|`IS31FL3733_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3733_PDR_1K_OHM` |1 kΩ | +|`IS31FL3733_PDR_2K_OHM` |2 kΩ | +|`IS31FL3733_PDR_4K_OHM` |4 kΩ | +|`IS31FL3733_PDR_8K_OHM` |8 kΩ | +|`IS31FL3733_PDR_16K_OHM`|16 kΩ | +|`IS31FL3733_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3733_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3733_led_t PROGMEM g_is31fl3733_leds[IS31FL3733_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 15, figure 9. + +## API {#api} + +### `struct is31fl3733_led_t` {#api-is31fl3733-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3733-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3733_init(uint8_t index)` {#api-is31fl3733-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3733-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3733_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3733-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3733-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3733_select_page(uint8_t index, uint8_t page)` {#api-is31fl3733-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3733-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3733_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3733-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3733_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3733_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3733-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3733-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3733_set_value(int index, uint8_t value)` {#api-is31fl3733-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3733_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3733_set_value_all(uint8_t value)` {#api-is31fl3733-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3733-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3733_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3733-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3733_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3733_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3733-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3733_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3733-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3733_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3733_update_pwm_buffers(uint8_t index)` {#api-is31fl3733-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3733-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3733_update_led_control_registers(uint8_t index)` {#api-is31fl3733-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3733-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3736.md b/docs/drivers/is31fl3736.md new file mode 100644 index 0000000000..b679a232cd --- /dev/null +++ b/docs/drivers/is31fl3736.md @@ -0,0 +1,322 @@ +# IS31FL3736 Driver {#is31fl3736-driver} + +I²C 12x8 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 96 single-color LEDs, or 32 RGB LEDs. + +[IS31FL3736 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3736_DS.pdf) + +## Usage {#usage} + +The IS31FL3736 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3736` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3736-mono.c # For single-color +SRC += is31fl3736.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3736_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3736_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3736_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3736_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3736_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3736_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3736_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3736_PWM_FREQUENCY` |`IS31FL3736_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3736B only) | +|`IS31FL3736_SW_PULLUP` |`IS31FL3736_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3736_CS_PULLDOWN` |`IS31FL3736_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3736_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3736 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3736_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3736_I2C_ADDRESS_GND_GND`|`0x50`| +|`IS31FL3736_I2C_ADDRESS_GND_SCL`|`0x51`| +|`IS31FL3736_I2C_ADDRESS_GND_SDA`|`0x52`| +|`IS31FL3736_I2C_ADDRESS_GND_VCC`|`0x53`| +|`IS31FL3736_I2C_ADDRESS_SCL_GND`|`0x54`| +|`IS31FL3736_I2C_ADDRESS_SCL_SCL`|`0x55`| +|`IS31FL3736_I2C_ADDRESS_SCL_SDA`|`0x56`| +|`IS31FL3736_I2C_ADDRESS_SCL_VCC`|`0x57`| +|`IS31FL3736_I2C_ADDRESS_SDA_GND`|`0x58`| +|`IS31FL3736_I2C_ADDRESS_SDA_SCL`|`0x59`| +|`IS31FL3736_I2C_ADDRESS_SDA_SDA`|`0x5A`| +|`IS31FL3736_I2C_ADDRESS_SDA_VCC`|`0x5B`| +|`IS31FL3736_I2C_ADDRESS_VCC_GND`|`0x5C`| +|`IS31FL3736_I2C_ADDRESS_VCC_SCL`|`0x5D`| +|`IS31FL3736_I2C_ADDRESS_VCC_SDA`|`0x5E`| +|`IS31FL3736_I2C_ADDRESS_VCC_VCC`|`0x5F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3736B only) by adding the following to your `config.h`: + +```c +#define IS31FL3736_PWM_FREQUENCY IS31FL3736_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3736_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3736_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3736_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3736_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3736_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 25) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3736_SW_PULLUP IS31FL3736_PUR_0_OHM +#define IS31FL3736_CS_PULLDOWN IS31FL3736_PDR_0_OHM +``` + +Valid values for `IS31FL3736_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3736_PUR_0_OHM` |None (default)| +|`IS31FL3736_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3736_PUR_1K_OHM` |1 kΩ | +|`IS31FL3736_PUR_2K_OHM` |2 kΩ | +|`IS31FL3736_PUR_4K_OHM` |4 kΩ | +|`IS31FL3736_PUR_8K_OHM` |8 kΩ | +|`IS31FL3736_PUR_16K_OHM`|16 kΩ | +|`IS31FL3736_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3736_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3736_PDR_0_OHM` |None (default)| +|`IS31FL3736_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3736_PDR_1K_OHM` |1 kΩ | +|`IS31FL3736_PDR_2K_OHM` |2 kΩ | +|`IS31FL3736_PDR_4K_OHM` |4 kΩ | +|`IS31FL3736_PDR_8K_OHM` |8 kΩ | +|`IS31FL3736_PDR_16K_OHM`|16 kΩ | +|`IS31FL3736_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3736_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3736_led_t PROGMEM g_is31fl3736_leds[IS31FL3736_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 16, figure 9. + +## API {#api} + +### `struct is31fl3736_led_t` {#api-is31fl3736-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3736-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3736_init(uint8_t index)` {#api-is31fl3736-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3736-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3736_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3736-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3736-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3736_select_page(uint8_t index, uint8_t page)` {#api-is31fl3736-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3736-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3736_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3736-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3736_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3736_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3736-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3736-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3736_set_value(int index, uint8_t value)` {#api-is31fl3736-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3736_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3736_set_value_all(uint8_t value)` {#api-is31fl3736-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3736-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3736_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3736-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3736_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3736_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3736-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3736_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3736-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3736_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3736_update_pwm_buffers(uint8_t index)` {#api-is31fl3736-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3736-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3736_update_led_control_registers(uint8_t index)` {#api-is31fl3736-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3736-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3737.md b/docs/drivers/is31fl3737.md new file mode 100644 index 0000000000..d23def237f --- /dev/null +++ b/docs/drivers/is31fl3737.md @@ -0,0 +1,310 @@ +# IS31FL3737 Driver {#is31fl3737-driver} + +I²C 12x12 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. + +[IS31FL3737 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3737_DS.pdf) + +## Usage {#usage} + +The IS31FL3737 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3737` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3737-mono.c # For single-color +SRC += is31fl3737.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3737_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3737_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3737_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3737_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3737_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3737_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3737_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3737_PWM_FREQUENCY` |`IS31FL3737_PWM_FREQUENCY_8K4_HZ`|The PWM frequency of the LEDs (IS31FL3737B only) | +|`IS31FL3737_SW_PULLUP` |`IS31FL3737_PUR_0_OHM` |The `SWx` pullup resistor value | +|`IS31FL3737_CS_PULLDOWN` |`IS31FL3737_PDR_0_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3737_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3737 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3737_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3737_I2C_ADDRESS_GND`|`0x50`| +|`IS31FL3737_I2C_ADDRESS_SCL`|`0x55`| +|`IS31FL3737_I2C_ADDRESS_SDA`|`0x5A`| +|`IS31FL3737_I2C_ADDRESS_VCC`|`0x5F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3737B only) by adding the following to your `config.h`: + +```c +#define IS31FL3737_PWM_FREQUENCY IS31FL3737_PWM_FREQUENCY_8K4_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|-----------------| +|`IS31FL3737_PWM_FREQUENCY_8K4_HZ` |8.4 kHz (default)| +|`IS31FL3737_PWM_FREQUENCY_4K2_HZ` |4.2 kHz | +|`IS31FL3737_PWM_FREQUENCY_26K7_HZ`|26.7 kHz | +|`IS31FL3737_PWM_FREQUENCY_2K1_HZ` |2.1 kHz | +|`IS31FL3737_PWM_FREQUENCY_1K05_HZ`|1.05 kHz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3737_SW_PULLUP IS31FL3737_PUR_0_OHM +#define IS31FL3737_CS_PULLDOWN IS31FL3737_PDR_0_OHM +``` + +Valid values for `IS31FL3737_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3737_PUR_0_OHM` |None (default)| +|`IS31FL3737_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3737_PUR_1K_OHM` |1 kΩ | +|`IS31FL3737_PUR_2K_OHM` |2 kΩ | +|`IS31FL3737_PUR_4K_OHM` |4 kΩ | +|`IS31FL3737_PUR_8K_OHM` |8 kΩ | +|`IS31FL3737_PUR_16K_OHM`|16 kΩ | +|`IS31FL3737_PUR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3737_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|--------------| +|`IS31FL3737_PDR_0_OHM` |None (default)| +|`IS31FL3737_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3737_PDR_1K_OHM` |1 kΩ | +|`IS31FL3737_PDR_2K_OHM` |2 kΩ | +|`IS31FL3737_PDR_4K_OHM` |4 kΩ | +|`IS31FL3737_PDR_8K_OHM` |8 kΩ | +|`IS31FL3737_PDR_16K_OHM`|16 kΩ | +|`IS31FL3737_PDR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3737_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `SW1` pin, and their anodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 15, figure 9. + +## API {#api} + +### `struct is31fl3737_led_t` {#api-is31fl3737-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3737-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3737_init(uint8_t index)` {#api-is31fl3737-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3737-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3737_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3737-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3737-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3737_select_page(uint8_t index, uint8_t page)` {#api-is31fl3737-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3737-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3737_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3737-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3737_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3737_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3737-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3737-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3737_set_value(int index, uint8_t value)` {#api-is31fl3737-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3737_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3737_set_value_all(uint8_t value)` {#api-is31fl3737-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3737-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3737_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3737-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3737_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3737_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3737-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3737_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3737-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3737_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3737_update_pwm_buffers(uint8_t index)` {#api-is31fl3737-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3737-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3737_update_led_control_registers(uint8_t index)` {#api-is31fl3737-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3737-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3741.md b/docs/drivers/is31fl3741.md new file mode 100644 index 0000000000..dce5c08b21 --- /dev/null +++ b/docs/drivers/is31fl3741.md @@ -0,0 +1,310 @@ +# IS31FL3741 Driver {#is31fl3741-driver} + +I²C 39x9 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 351 single-color LEDs, or 117 RGB LEDs. + +[IS31FL3741A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3741A_DS.pdf) + +## Usage {#usage} + +The IS31FL3741 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3741` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3741-mono.c # For single-color +SRC += is31fl3741.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|---------------------------------|----------------------------------------------------| +|`IS31FL3741_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3741_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3741_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3741_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3741_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3741_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3741_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3741_CONFIGURATION` |`1` |The value of the configuration register | +|`IS31FL3741_PWM_FREQUENCY` |`IS31FL3741_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs (IS31FL3741A only) | +|`IS31FL3741_SW_PULLUP` |`IS31FL3741_PUR_32K_OHM` |The `SWx` pullup resistor value | +|`IS31FL3741_CS_PULLDOWN` |`IS31FL3741_PDR_32K_OHM` |The `CSx` pulldown resistor value | +|`IS31FL3741_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3741 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3741_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|----------------------------|------| +|`IS31FL3741_I2C_ADDRESS_GND`|`0x30`| +|`IS31FL3741_I2C_ADDRESS_SCL`|`0x31`| +|`IS31FL3741_I2C_ADDRESS_SDA`|`0x32`| +|`IS31FL3741_I2C_ADDRESS_VCC`|`0x33`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted (for IS31FL3741A only) by adding the following to your `config.h`: + +```c +#define IS31FL3741_PWM_FREQUENCY IS31FL3741_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|---------------------------------|----------------| +|`IS31FL3741_PWM_FREQUENCY_29K_HZ`|29 kHz (default)| +|`IS31FL3741_PWM_FREQUENCY_3K6_HZ`|3.6 kHz | +|`IS31FL3741_PWM_FREQUENCY_1K8_HZ`|1.8 kHz | +|`IS31FL3741_PWM_FREQUENCY_900_HZ`|900 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pullup and pulldown resistor values on the `CSx` and `SWy` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 18) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3741_SW_PULLUP IS31FL3741_PUR_32K_OHM +#define IS31FL3741_CS_PULLDOWN IS31FL3741_PDR_32K_OHM +``` + +Valid values for `IS31FL3741_SW_PULLUP` are: + +|Define |Resistance | +|------------------------|---------------| +|`IS31FL3741_PUR_0_OHM` |None | +|`IS31FL3741_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3741_PUR_1K_OHM` |1 kΩ | +|`IS31FL3741_PUR_2K_OHM` |2 kΩ | +|`IS31FL3741_PUR_4K_OHM` |4 kΩ | +|`IS31FL3741_PUR_8K_OHM` |8 kΩ | +|`IS31FL3741_PUR_16K_OHM`|16 kΩ | +|`IS31FL3741_PUR_32K_OHM`|32 kΩ (default)| + +Valid values for `IS31FL3741_CS_PULLDOWN` are: + +|Define |Resistance | +|------------------------|---------------| +|`IS31FL3741_PDR_0_OHM` |None | +|`IS31FL3741_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3741_PDR_1K_OHM` |1 kΩ | +|`IS31FL3741_PDR_2K_OHM` |2 kΩ | +|`IS31FL3741_PDR_4K_OHM` |4 kΩ | +|`IS31FL3741_PDR_8K_OHM` |8 kΩ | +|`IS31FL3741_PDR_16K_OHM`|16 kΩ | +|`IS31FL3741_PDR_32K_OHM`|32 kΩ (default)| + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3741_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3741_led_t PROGMEM g_is31fl3741_leds[IS31FL3741_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3741_led_t` {#api-is31fl3741-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3741-led-t-members} + + - `uint32_t driver` + The driver index of the LED, from 0 to 3. + - `uint32_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint32_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint32_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint32_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3741_init(uint8_t index)` {#api-is31fl3741-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3741-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3741_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3741-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3741-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3741_select_page(uint8_t index, uint8_t page)` {#api-is31fl3741-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3741-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3741_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3741-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3741_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3741_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3741-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3741-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3741_set_value(int index, uint8_t value)` {#api-is31fl3741-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3741_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3741_set_value_all(uint8_t value)` {#api-is31fl3741-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3741-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3741_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-is31fl3741-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3741_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void is31fl3741_set_led_control_register(uint8_t index, bool value)` {#api-is31fl3741-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3741_update_led_control_registers()` after you are finished. + +#### Arguments {#api-is31fl3741-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3741_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void is31fl3741_update_pwm_buffers(uint8_t index)` {#api-is31fl3741-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3741-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3741_update_led_control_registers(uint8_t index)` {#api-is31fl3741-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-is31fl3741-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3742a.md b/docs/drivers/is31fl3742a.md new file mode 100644 index 0000000000..ebe648cba4 --- /dev/null +++ b/docs/drivers/is31fl3742a.md @@ -0,0 +1,310 @@ +# IS31FL3742A Driver {#is31fl3742a-driver} + +I²C 30x6 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 180 single-color LEDs, or 60 RGB LEDs. + +[IS31FL3742A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) + +## Usage {#usage} + +The IS31FL3742A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3742a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3742a-mono.c # For single-color +SRC += is31fl3742a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|----------------------------------|----------------------------------------------------| +|`IS31FL3742A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3742A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3742A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3742A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3742A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3742A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3742A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3742A_CONFIGURATION` |`0x31` |The value of the configuration register | +|`IS31FL3742A_PWM_FREQUENCY` |`IS31FL3742A_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs | +|`IS31FL3742A_SW_PULLDOWN` |`IS31FL3742A_PDR_8K_OHM` |The `SWx` pulldown resistor value | +|`IS31FL3742A_CS_PULLUP` |`IS31FL3742A_PUR_8K_OHM` |The `CSx` pullup resistor value | +|`IS31FL3742A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3742A has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `IS31FL3742A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|-----------------------------|------| +|`IS31FL3742A_I2C_ADDRESS_GND`|`0x30`| +|`IS31FL3742A_I2C_ADDRESS_SCL`|`0x31`| +|`IS31FL3742A_I2C_ADDRESS_SDA`|`0x32`| +|`IS31FL3742A_I2C_ADDRESS_VCC`|`0x33`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3742A_PWM_FREQUENCY IS31FL3742A_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|----------------------------------|----------------| +|`IS31FL3742A_PWM_FREQUENCY_29K_HZ`|29 kHz (default)| +|`IS31FL3742A_PWM_FREQUENCY_3K6_HZ`|3.6 kHz | +|`IS31FL3742A_PWM_FREQUENCY_1K8_HZ`|1.8 kHz | +|`IS31FL3742A_PWM_FREQUENCY_900_HZ`|900 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3742A_SW_PULLDOWN IS31FL3742A_PDR_8K_OHM +#define IS31FL3742A_CS_PULLUP IS31FL3742A_PUR_8K_OHM +``` + +Valid values for `IS31FL3742A_SW_PULLDOWN` are: + +|Define |Resistance | +|-------------------------|--------------| +|`IS31FL3742A_PDR_0_OHM` |None | +|`IS31FL3742A_PDR_0K5_OHM`|0.5 kΩ | +|`IS31FL3742A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3742A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3742A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3742A_PDR_8K_OHM` |8 kΩ (default)| +|`IS31FL3742A_PDR_16K_OHM`|16 kΩ | +|`IS31FL3742A_PDR_32K_OHM`|32 kΩ | + +Valid values for `IS31FL3742A_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------|--------------| +|`IS31FL3742A_PUR_0_OHM` |None | +|`IS31FL3742A_PUR_0K5_OHM`|0.5 kΩ | +|`IS31FL3742A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3742A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3742A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3742A_PUR_8K_OHM` |8 kΩ (default)| +|`IS31FL3742A_PUR_16K_OHM`|16 kΩ | +|`IS31FL3742A_PUR_32K_OHM`|32 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSx` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3742A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3742a_led_t PROGMEM g_is31fl3742a_leds[IS31FL3742A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3742a_led_t` {#api-is31fl3742a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3742a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3742a_init(uint8_t index)` {#api-is31fl3742a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3742a-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3742a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3742a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3742a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3742a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3742a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3742a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3742a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3742a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3742a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3742a_set_value(int index, uint8_t value)` {#api-is31fl3742a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3742a_set_value_all(uint8_t value)` {#api-is31fl3742a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3742a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3742a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3742a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3742a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3742a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3742a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3742a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3742a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3742a_update_pwm_buffers(uint8_t index)` {#api-is31fl3742a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3742a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3742a_update_scaling_registers(uint8_t index)` {#api-is31fl3742a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3742a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3743a.md b/docs/drivers/is31fl3743a.md new file mode 100644 index 0000000000..9ca55c5eeb --- /dev/null +++ b/docs/drivers/is31fl3743a.md @@ -0,0 +1,320 @@ +# IS31FL3743A Driver {#is31fl3743a-driver} + +I²C 18x11 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 198 single-color LEDs, or 66 RGB LEDs. + +[IS31FL3743A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) + +## Usage {#usage} + +The IS31FL3743A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3743a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3743a-mono.c # For single-color +SRC += is31fl3743a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|-------------------------------|----------------------------------------------------| +|`IS31FL3743A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3743A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3743A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3743A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3743A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3743A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3743A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3743A_SYNC_1` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3743A_SYNC_2` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3743A_SYNC_3` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3743A_SYNC_4` |`IS31FL3743A_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3743A_CONFIGURATION` |`0x01` |The value of the configuration register | +|`IS31FL3743A_SW_PULLDOWN` |`IS31FL3743A_PDR_2K_OHM_SW_OFF`|The `SWx` pulldown resistor value | +|`IS31FL3743A_CS_PULLUP` |`IS31FL3743A_PUR_2K_OHM_CS_OFF`|The `CSx` pullup resistor value | +|`IS31FL3743A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3743A has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3743A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|---------------------------------|------| +|`IS31FL3743A_I2C_ADDRESS_GND_GND`|`0x20`| +|`IS31FL3743A_I2C_ADDRESS_GND_SCL`|`0x21`| +|`IS31FL3743A_I2C_ADDRESS_GND_SDA`|`0x22`| +|`IS31FL3743A_I2C_ADDRESS_GND_VCC`|`0x23`| +|`IS31FL3743A_I2C_ADDRESS_SCL_GND`|`0x24`| +|`IS31FL3743A_I2C_ADDRESS_SCL_SCL`|`0x25`| +|`IS31FL3743A_I2C_ADDRESS_SCL_SDA`|`0x26`| +|`IS31FL3743A_I2C_ADDRESS_SCL_VCC`|`0x27`| +|`IS31FL3743A_I2C_ADDRESS_SDA_GND`|`0x28`| +|`IS31FL3743A_I2C_ADDRESS_SDA_SCL`|`0x29`| +|`IS31FL3743A_I2C_ADDRESS_SDA_SDA`|`0x2A`| +|`IS31FL3743A_I2C_ADDRESS_SDA_VCC`|`0x2B`| +|`IS31FL3743A_I2C_ADDRESS_VCC_GND`|`0x2C`| +|`IS31FL3743A_I2C_ADDRESS_VCC_SCL`|`0x2D`| +|`IS31FL3743A_I2C_ADDRESS_VCC_SDA`|`0x2E`| +|`IS31FL3743A_I2C_ADDRESS_VCC_VCC`|`0x2F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3743A drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3743A_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|-------------------------|---------------------------| +|`IS31FL3743A_SYNC_NONE` |No synchronization | +|`IS31FL3743A_SYNC_MASTER`|Driver configured as master| +|`IS31FL3743A_SYNC_SLAVE` |Driver configured as slave | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3743A_SW_PULLDOWN IS31FL3743A_PDR_2K_OHM_SW_OFF +#define IS31FL3743A_CS_PULLUP IS31FL3743A_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3743A_SW_PULLDOWN` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3743A_PDR_0_OHM` |None (default) | +|`IS31FL3743A_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3743A_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3743A_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3743A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3743A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3743A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3743A_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3743A_CS_PULLUP` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3743A_PUR_0_OHM` |None (default) | +|`IS31FL3743A_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3743A_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3743A_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3743A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3743A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3743A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3743A_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3743A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3743a_led_t PROGMEM g_is31fl3743a_leds[IS31FL3743A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 8. + +## API {#api} + +### `struct is31fl3743a_led_t` {#api-is31fl3743a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3743a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3743a_init(uint8_t index)` {#api-is31fl3743a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3743a-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3743a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3743a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3743a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3743a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3743a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3743a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3743a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3743a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3743a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3743a_set_value(int index, uint8_t value)` {#api-is31fl3743a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3743a_set_value_all(uint8_t value)` {#api-is31fl3743a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3743a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3743a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3743a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3743a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3743a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3743a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3743a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3743a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3743a_update_pwm_buffers(uint8_t index)` {#api-is31fl3743a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3743a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3743a_update_scaling_registers(uint8_t index)` {#api-is31fl3743a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3743a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3745.md b/docs/drivers/is31fl3745.md new file mode 100644 index 0000000000..f13f029bfe --- /dev/null +++ b/docs/drivers/is31fl3745.md @@ -0,0 +1,320 @@ +# IS31FL3745 Driver {#is31fl3745-driver} + +I²C 18x8 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 144 single-color LEDs, or 48 RGB LEDs. + +[IS31FL3745 Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) + +## Usage {#usage} + +The IS31FL3745 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3745` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3745-mono.c # For single-color +SRC += is31fl3745.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|------------------------------|----------------------------------------------------| +|`IS31FL3745_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3745_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3745_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3745_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3745_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3745_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3745_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3745_SYNC_1` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 0 | +|`IS31FL3745_SYNC_2` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 1 | +|`IS31FL3745_SYNC_3` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 2 | +|`IS31FL3745_SYNC_4` |`IS31FL3745_SYNC_NONE` |The sync configuration for driver 3 | +|`IS31FL3745_CONFIGURATION` |`0x31` |The value of the configuration register | +|`IS31FL3745_SW_PULLDOWN` |`IS31FL3745_PDR_2K_OHM_SW_OFF`|The `SWx` pulldown resistor value | +|`IS31FL3745_CS_PULLUP` |`IS31FL3745_PUR_2K_OHM_CS_OFF`|The `CSx` pullup resistor value | +|`IS31FL3745_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3745 has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3745_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|--------------------------------|------| +|`IS31FL3745_I2C_ADDRESS_GND_GND`|`0x20`| +|`IS31FL3745_I2C_ADDRESS_GND_SCL`|`0x21`| +|`IS31FL3745_I2C_ADDRESS_GND_SDA`|`0x22`| +|`IS31FL3745_I2C_ADDRESS_GND_VCC`|`0x23`| +|`IS31FL3745_I2C_ADDRESS_SCL_GND`|`0x24`| +|`IS31FL3745_I2C_ADDRESS_SCL_SCL`|`0x25`| +|`IS31FL3745_I2C_ADDRESS_SCL_SDA`|`0x26`| +|`IS31FL3745_I2C_ADDRESS_SCL_VCC`|`0x27`| +|`IS31FL3745_I2C_ADDRESS_SDA_GND`|`0x28`| +|`IS31FL3745_I2C_ADDRESS_SDA_SCL`|`0x29`| +|`IS31FL3745_I2C_ADDRESS_SDA_SDA`|`0x2A`| +|`IS31FL3745_I2C_ADDRESS_SDA_VCC`|`0x2B`| +|`IS31FL3745_I2C_ADDRESS_VCC_GND`|`0x2C`| +|`IS31FL3745_I2C_ADDRESS_VCC_SCL`|`0x2D`| +|`IS31FL3745_I2C_ADDRESS_VCC_SDA`|`0x2E`| +|`IS31FL3745_I2C_ADDRESS_VCC_VCC`|`0x2F`| + +### Multi-Driver Synchronization {#multi-driver-synchronization} + +Multiple IS31FL3745 drivers can be synchronized by connecting the `SYNC` pins together. One driver must be designated as the "master", and the others configured as "slave". + +To do this, set the `IS31FL3745_SYNC_n` defines accordingly in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------|---------------------------| +|`IS31FL3745_SYNC_NONE` |No synchronization | +|`IS31FL3745_SYNC_MASTER`|Driver configured as master| +|`IS31FL3745_SYNC_SLAVE` |Driver configured as slave | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3745_SW_PULLDOWN IS31FL3745_PDR_2K_OHM_SW_OFF +#define IS31FL3745_CS_PULLUP IS31FL3745_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3745_SW_PULLDOWN` are: + +|Define |Resistance | +|-------------------------------|------------------------------| +|`IS31FL3745_PDR_0_OHM` |None (default) | +|`IS31FL3745_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3745_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3745_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3745_PDR_1K_OHM` |1 kΩ | +|`IS31FL3745_PDR_2K_OHM` |2 kΩ | +|`IS31FL3745_PDR_4K_OHM` |4 kΩ | +|`IS31FL3745_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3745_CS_PULLUP` are: + +|Define |Resistance | +|-------------------------------|------------------------------| +|`IS31FL3745_PUR_0_OHM` |None (default) | +|`IS31FL3745_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3745_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3745_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3745_PUR_1K_OHM` |1 kΩ | +|`IS31FL3745_PUR_2K_OHM` |2 kΩ | +|`IS31FL3745_PUR_4K_OHM` |4 kΩ | +|`IS31FL3745_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3745_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3745_led_t PROGMEM g_is31fl3745_leds[IS31FL3745_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 12, figure 9. + +## API {#api} + +### `struct is31fl3745_led_t` {#api-is31fl3745-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3745-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3745_init(uint8_t index)` {#api-is31fl3745-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3745-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3745_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3745-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3745-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3745_select_page(uint8_t index, uint8_t page)` {#api-is31fl3745-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3745-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3745_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3745_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3745_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3745-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3745_set_value(int index, uint8_t value)` {#api-is31fl3745-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3745_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3745_set_value_all(uint8_t value)` {#api-is31fl3745-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3745-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3745_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3745-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3745_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3745_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3745-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3745_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3745-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3745_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3745_update_pwm_buffers(uint8_t index)` {#api-is31fl3745-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3745-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3745_update_scaling_registers(uint8_t index)` {#api-is31fl3745-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3745-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/is31fl3746a.md b/docs/drivers/is31fl3746a.md new file mode 100644 index 0000000000..bdd5c18357 --- /dev/null +++ b/docs/drivers/is31fl3746a.md @@ -0,0 +1,327 @@ +# IS31FL3746A Driver {#is31fl3746a-driver} + +I²C 18x4 LED matrix driver by Lumissil. Supports a maximum of four drivers, each controlling up to 72 single-color LEDs, or 24 RGB LEDs. + +[IS31FL3746A Datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) + +## Usage {#usage} + +The IS31FL3746A driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `is31fl3746a` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led/issi +SRC += is31fl3746a-mono.c # For single-color +SRC += is31fl3746a.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|-----------------------------|----------------------------------|----------------------------------------------------| +|`IS31FL3746A_SDB_PIN` |*Not defined* |The GPIO pin connected to the drivers' shutdown pins| +|`IS31FL3746A_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`IS31FL3746A_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`IS31FL3746A_I2C_ADDRESS_1` |*Not defined* |The I²C address of driver 0 | +|`IS31FL3746A_I2C_ADDRESS_2` |*Not defined* |The I²C address of driver 1 | +|`IS31FL3746A_I2C_ADDRESS_3` |*Not defined* |The I²C address of driver 2 | +|`IS31FL3746A_I2C_ADDRESS_4` |*Not defined* |The I²C address of driver 3 | +|`IS31FL3746A_CONFIGURATION` |`0x01` |The value of the configuration register | +|`IS31FL3746A_PWM_FREQUENCY` |`IS31FL3746A_PWM_FREQUENCY_29K_HZ`|The PWM frequency of the LEDs | +|`IS31FL3746A_SW_PULLDOWN` |`IS31FL3746A_PDR_2K_OHM_SW_OFF` |The `SWx` pulldown resistor value | +|`IS31FL3746A_CS_PULLUP` |`IS31FL3746A_PUR_2K_OHM_CS_OFF` |The `CSx` pullup resistor value | +|`IS31FL3746A_GLOBAL_CURRENT` |`0xFF` |The global current control value | + +### I²C Addressing {#i2c-addressing} + +The IS31FL3746A has 16 possible 7-bit I²C addresses, depending on how the `ADDR1` and `ADDR2` pins are connected. + +To configure this, set the `IS31FL3746A_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|---------------------------------|------| +|`IS31FL3746A_I2C_ADDRESS_GND_GND`|`0x60`| +|`IS31FL3746A_I2C_ADDRESS_GND_SCL`|`0x61`| +|`IS31FL3746A_I2C_ADDRESS_GND_SDA`|`0x62`| +|`IS31FL3746A_I2C_ADDRESS_GND_VCC`|`0x63`| +|`IS31FL3746A_I2C_ADDRESS_SCL_GND`|`0x64`| +|`IS31FL3746A_I2C_ADDRESS_SCL_SCL`|`0x65`| +|`IS31FL3746A_I2C_ADDRESS_SCL_SDA`|`0x66`| +|`IS31FL3746A_I2C_ADDRESS_SCL_VCC`|`0x67`| +|`IS31FL3746A_I2C_ADDRESS_SDA_GND`|`0x68`| +|`IS31FL3746A_I2C_ADDRESS_SDA_SCL`|`0x69`| +|`IS31FL3746A_I2C_ADDRESS_SDA_SDA`|`0x6A`| +|`IS31FL3746A_I2C_ADDRESS_SDA_VCC`|`0x6B`| +|`IS31FL3746A_I2C_ADDRESS_VCC_GND`|`0x6C`| +|`IS31FL3746A_I2C_ADDRESS_VCC_SCL`|`0x6D`| +|`IS31FL3746A_I2C_ADDRESS_VCC_SDA`|`0x6E`| +|`IS31FL3746A_I2C_ADDRESS_VCC_VCC`|`0x6F`| + +### PWM Frequency {#pwm-frequency} + +The PWM frequency can be adjusted by adding the following to your `config.h`: + +```c +#define IS31FL3746A_PWM_FREQUENCY IS31FL3746A_PWM_FREQUENCY_29K_HZ +``` + +Valid values are: + +|Define |Frequency | +|-----------------------------------|----------------| +|`IS31FL3746A_PWM_FREQUENCY_29K_HZ` |29 kHz (default)| +|`IS31FL3746A_PWM_FREQUENCY_14K5_HZ`|14.5 kHz | +|`IS31FL3746A_PWM_FREQUENCY_7K25_HZ`|7.25 kHz | +|`IS31FL3746A_PWM_FREQUENCY_3K63_HZ`|3.63 kHz | +|`IS31FL3746A_PWM_FREQUENCY_1K81_HZ`|1.81 kHz | +|`IS31FL3746A_PWM_FREQUENCY_906_HZ` |906 Hz | +|`IS31FL3746A_PWM_FREQUENCY_453_HZ` |453 Hz | + +### De-Ghosting {#de-ghosting} + +These settings control the pulldown and pullup resistor values on the `SWy` and `CSx` pins respectively, for the purposes of eliminating ghosting. Refer to the datasheet (p. 23) for more information on how and why this occurs. + +To adjust the resistor values, add the following to your `config.h`: + +```c +#define IS31FL3746A_SW_PULLDOWN IS31FL3746A_PDR_2K_OHM_SW_OFF +#define IS31FL3746A_CS_PULLUP IS31FL3746A_PUR_2K_OHM_CS_OFF +``` + +Valid values for `IS31FL3746A_SW_PULLDOWN` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3746A_PDR_0_OHM` |None | +|`IS31FL3746A_PDR_0K5_OHM_SW_OFF`|0.5 kΩ in SWx off time | +|`IS31FL3746A_PDR_1K_OHM_SW_OFF` |1 kΩ in SWx off time | +|`IS31FL3746A_PDR_2K_OHM_SW_OFF` |2 kΩ in SWx off time (default)| +|`IS31FL3746A_PDR_1K_OHM` |1 kΩ | +|`IS31FL3746A_PDR_2K_OHM` |2 kΩ | +|`IS31FL3746A_PDR_4K_OHM` |4 kΩ | +|`IS31FL3746A_PDR_8K_OHM` |8 kΩ | + +Valid values for `IS31FL3746A_CS_PULLUP` are: + +|Define |Resistance | +|--------------------------------|------------------------------| +|`IS31FL3746A_PUR_0_OHM` |None (default) | +|`IS31FL3746A_PUR_0K5_OHM_CS_OFF`|0.5 kΩ in CSy off time | +|`IS31FL3746A_PUR_1K_OHM_CS_OFF` |1 kΩ in CSy off time | +|`IS31FL3746A_PUR_2K_OHM_CS_OFF` |2 kΩ in CSy off time (default)| +|`IS31FL3746A_PUR_1K_OHM` |1 kΩ | +|`IS31FL3746A_PUR_2K_OHM` |2 kΩ | +|`IS31FL3746A_PUR_4K_OHM` |4 kΩ | +|`IS31FL3746A_PUR_8K_OHM` |8 kΩ | + +### Global Current Control {#global-current-control} + +This setting controls the current sunk by the `CSy` pins, from 0 to 255. By default, the value is the maximum (255), but if you need to lower it, add the following to your `config.h`: + +```c +#define IS31FL3746A_GLOBAL_CURRENT 0xFF +``` + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = { +/* Driver + * | R G B */ + {0, SW1_CS1, SW1_CS2, SW1_CS3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their anodes connected to the `SW1` pin, and their cathodes on the `CS1`, `CS2` and `CS3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const is31fl3746a_led_t PROGMEM g_is31fl3746a_leds[IS31FL3746A_LED_COUNT] = { +/* Driver + * | V */ + {0, SW1_CS1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 13, figure 8. + +## API {#api} + +### `struct is31fl3746a_led_t` {#api-is31fl3746a-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-is31fl3746a-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void is31fl3746a_init(uint8_t index)` {#api-is31fl3746a-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-is31fl3746a-init-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t sync` + Sync configuration of the LED driver. + +--- + +### `void is31fl3746a_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-is31fl3746a-write-register} + +Set the value of the given register. + +#### Arguments {#api-is31fl3746a-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void is31fl3746a_select_page(uint8_t index, uint8_t page)` {#api-is31fl3746a-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-is31fl3746a-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void is31fl3746a_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3746a_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-is31fl3746a-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void is31fl3746a_set_value(int index, uint8_t value)` {#api-is31fl3746a-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3746a_set_value_all(uint8_t value)` {#api-is31fl3746a-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-is31fl3746a-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void is31fl3746a_set_scaling_register(uint8_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-is31fl3746a-set-scaling-register-rgb} + +Configure the scaling registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-scaling-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t red` + The scaling value for the red channel. + - `uint8_t green` + The scaling value for the green channel. + - `uint8_t blue` + The scaling value for the blue channel. + +--- + +### `void is31fl3746a_set_scaling_register(uint8_t index, uint8_t value)` {#api-is31fl3746a-set-scaling-register-mono} + +Configure the scaling register for a single LED (single-color driver only). This function does not immediately update the LEDs; call `is31fl3746a_update_scaling_registers()` after you are finished. + +#### Arguments {#api-is31fl3746a-set-scaling-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_is31fl3746a_leds` array). + - `uint8_t value` + The scaling value for the LED. + +--- + +### `void is31fl3746a_update_pwm_buffers(uint8_t index)` {#api-is31fl3746a-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-is31fl3746a-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void is31fl3746a_update_scaling_registers(uint8_t index)` {#api-is31fl3746a-update-scaling-registers} + +Flush the scaling register values to the LED driver. + +#### Arguments {#api-is31fl3746a-update-scaling-registers-arguments} + + - `uint8_t index` + The driver index. diff --git a/docs/drivers/snled27351.md b/docs/drivers/snled27351.md new file mode 100644 index 0000000000..1d91182f7c --- /dev/null +++ b/docs/drivers/snled27351.md @@ -0,0 +1,245 @@ +# SNLED27351 Driver {#snled27351-driver} + +I²C 16x12 LED matrix driver by Sonix. Supports a maximum of four drivers, each controlling up to 192 single-color LEDs, or 64 RGB LEDs. + +A slightly modified version of this IC is also known as "CKLED2001". + +[SNLED27351 Datasheet](https://www.sonix.com.tw/files/1/D235860C0C037C28E050007F01001CBE) + +## Usage {#usage} + +The SNLED27351 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `snled27351` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led +SRC += snled27351-mono.c # For single-color +SRC += snled27351.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`SNLED27351_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`SNLED27351_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`SNLED27351_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`SNLED27351_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`SNLED27351_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`SNLED27351_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`SNLED27351_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | + +### I²C Addressing {#i2c-addressing} + +The SNLED27351 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `SNLED27351_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------------|------| +|`SNLED27351_I2C_ADDRESS_GND` |`0x74`| +|`SNLED27351_I2C_ADDRESS_SCL` |`0x75`| +|`SNLED27351_I2C_ADDRESS_SDA` |`0x76`| +|`SNLED27351_I2C_ADDRESS_VDDIO`|`0x77`| + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `<keyboardname>.c`: + +```c +const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = { +/* Driver + * | R G B */ + {0, CB1_CA1, CB1_CA2, CB1_CA3}, + // etc... +}; +``` + +In this example, the red, green and blue channels for the first LED index on driver 0 all have their cathodes connected to the `CB1` pin, and their anodes on the `CA1`, `CA2` and `CA3` pins respectively. + +For the single-color driver, the principle is the same, but there is only one channel: + +```c +const snled27351_led_t PROGMEM g_snled27351_leds[SNLED27351_LED_COUNT] = { +/* Driver + * | V */ + {0, CB1_CA1}, + // etc... +}; +``` + +These values correspond to the register indices as shown in the datasheet on page 13. + +## API {#api} + +### `struct snled27351_led_t` {#api-snled27351-led-t} + +Contains the PWM register addresses for a single RGB LED. + +#### Members {#api-snled27351-led-t-members} + + - `uint8_t driver` + The driver index of the LED, from 0 to 3. + - `uint8_t r` + The output PWM register address for the LED's red channel (RGB driver only). + - `uint8_t g` + The output PWM register address for the LED's green channel (RGB driver only). + - `uint8_t b` + The output PWM register address for the LED's blue channel (RGB driver only). + - `uint8_t v` + The output PWM register address for the LED (single-color driver only). + +--- + +### `void snled27351_init(uint8_t index)` {#api-snled27351-init} + +Initialize the LED driver. This function should be called first. + +#### Arguments {#api-snled27351-init-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void snled27351_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-snled27351-write-register} + +Set the value of the given register. + +#### Arguments {#api-snled27351-write-register-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t reg` + The register address. + - `uint8_t data` + The value to set. + +--- + +### `void snled27351_select_page(uint8_t index, uint8_t page)` {#api-snled27351-select-page} + +Change the current page for configuring the LED driver. + +#### Arguments {#api-snled27351-select-page-arguments} + + - `uint8_t index` + The driver index. + - `uint8_t page` + The page number to select. + +--- + +### `void snled27351_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-snled27351-set-color} + +Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `snled27351_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-snled27351-set-color-arguments} + + - `int index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void snled27351_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-snled27351-set-color-all} + +Set the color of all LEDs (RGB driver only). + +#### Arguments {#api-snled27351-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void snled27351_set_value(int index, uint8_t value)` {#api-snled27351-set-value} + +Set the brightness of a single LED (single-color driver only). This function does not immediately update the LEDs; call `snled27351_update_pwm_buffers()` after you are finished. + +#### Arguments {#api-snled27351-set-value-arguments} + + - `int index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `uint8_t value` + The brightness value to set. + +--- + +### `void snled27351_set_value_all(uint8_t value)` {#api-snled27351-set-value-all} + +Set the brightness of all LEDs (single-color driver only). + +#### Arguments {#api-snled27351-set-value-all-arguments} + + - `uint8_t value` + The brightness value to set. + +--- + +### `void snled27351_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-snled27351-set-led-control-register-rgb} + +Configure the LED control registers for a single LED (RGB driver only). This function does not immediately update the LEDs; call `snled27351_update_led_control_registers()` after you are finished. + +#### Arguments {#api-snled27351-set-led-control-register-rgb-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `bool red` + Enable or disable the red channel. + - `bool green` + Enable or disable the green channel. + - `bool blue` + Enable or disable the blue channel. + +--- + +### `void snled27351_set_led_control_register(uint8_t index, bool value)` {#api-snled27351-set-led-control-register-mono} + +Configure the LED control registers for a single LED (single-color driver only). This function does not immediately update the LEDs; call `snled27351_update_led_control_registers()` after you are finished. + +#### Arguments {#api-snled27351-set-led-control-register-mono-arguments} + + - `uint8_t index` + The LED index (ie. the index into the `g_snled27351_leds` array). + - `bool value` + Enable or disable the LED. + +--- + +### `void snled27351_update_pwm_buffers(uint8_t index)` {#api-snled27351-update-pwm-buffers} + +Flush the PWM values to the LED driver. + +#### Arguments {#api-snled27351-update-pwm-buffers-arguments} + + - `uint8_t index` + The driver index. + +--- + +### `void snled27351_update_led_control_registers(uint8_t index)` {#api-snled27351-update-led-control-registers} + +Flush the LED control register values to the LED driver. + +#### Arguments {#api-snled27351-update-led-control-registers-arguments} + + - `uint8_t index` + The driver index. |