diff options
Diffstat (limited to 'docs/drivers')
-rw-r--r-- | docs/drivers/apa102.md | 47 | ||||
-rw-r--r-- | docs/drivers/aw20216s.md | 133 | ||||
-rw-r--r-- | docs/drivers/eeprom.md | 15 | ||||
-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 |
16 files changed, 3958 insertions, 15 deletions
diff --git a/docs/drivers/apa102.md b/docs/drivers/apa102.md index 88868a73b5..197b18869e 100644 --- a/docs/drivers/apa102.md +++ b/docs/drivers/apa102.md @@ -26,20 +26,51 @@ Add the following to your `config.h`: ## API {#api} -### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)` +### `void apa102_init(void)` {#api-apa102-init} -Send RGB data to the APA102 LED chain. +Initialize the LED driver. This function should be called first. -#### Arguments {#api-apa102-setleds-arguments} +--- + +### `void apa102_set_color(uint16_t index, uint8_t red, uint8_t green, uint8_t blue)` {#api-apa102-set-color} + +Set the color of a single LED. This function does not immediately update the LEDs; call `apa102_flush()` after you are finished. + +#### Arguments {#api-apa102-set-color-arguments} + + - `uint16_t index` + The LED index in the APA102 chain. + - `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 apa102_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-apa102-set-color-all} + +Set the color of all LEDs. + +#### Arguments {#api-apa102-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 apa102_flush(void)` {#api-apa102-flush} - - `rgb_led_t *start_led` - A pointer to the LED array. - - `uint16_t num_leds` - The length of the LED array. +Flush the PWM values to the LED chain. --- -### `void apa102_set_brightness(uint8_t brightness)` +### `void apa102_set_brightness(uint8_t brightness)` {#api-apa102-set-brightness} Set the global brightness. 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/eeprom.md b/docs/drivers/eeprom.md index 82630c501d..0ae258424f 100644 --- a/docs/drivers/eeprom.md +++ b/docs/drivers/eeprom.md @@ -119,13 +119,14 @@ This driver performs writes to the embedded flash storage embedded in the MCU. I Configurable options in your keyboard's `config.h`: -`config.h` override | Default | Description ------------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration. -`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting. -`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. -`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. -`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly. +`config.h` override | Default | Description +---------------------------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration. +`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting. +`#define WEAR_LEVELING_EFL_OMIT_LAST_SECTOR_COUNT` | `0` | Number of sectors to omit at the end of the flash. These sectors will not be allocated to the driver and the usable flash block will be offset, but keeping the set flash size. Useful on devices with bootloaders requiring a check flag at the end of flash to be present in order to confirm a valid, bootable firmware. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. +`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. +`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly. ::: warning If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding. 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. |