Skip to content

Commit

Permalink
[docs] rgb: move sled1734x to drivers
Browse files Browse the repository at this point in the history
  • Loading branch information
@dexter93
dexter93 committed Sep 20, 2024
1 parent ca5b5ee commit 2025e94
Show file tree
Hide file tree
Showing 2 changed files with 198 additions and 61 deletions.
197 changes: 197 additions & 0 deletions docs/drivers/sled1734x.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
### SLED1734X Driver {#sled1734x-driver}

I²C 16x16 LED matrix driver by Sonix. Supports a maximum of four drivers, each controlling up to 256 single-color LEDs, or 70 RGB LEDs.


[SLED1734X Datasheet](https://www.sonix.com.tw/files/1/637E852205EF6BC3E050007F01007792)

## Usage {#usage}

The SLED1734X driver code is automatically included if you are using the [RGB Matrix](../features/rgb_matrix) feature with the `sled1734x` driver set, and you would use that API instead.

However, if you need to use the driver standalone, add this to your `rules.mk`:

```make
COMMON_VPATH += $(DRIVER_PATH)/led
SRC += sled1734x.c # For RGB
I2C_DRIVER_REQUIRED = yes
```

## Basic Configuration {#basic-configuration}

Add the following to your `config.h`:

|Define |Default |Description |
|----------------------------|-------------|----------------------------------------------------|
|`SLED1734X_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins|
|`SLED1734X_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds |
|`SLED1734X_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions |
|`SLED1734X_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 |
|`SLED1734X_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 |
|`SLED1734X_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 |
|`SLED1734X_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 |

### I²C Addressing {#i2c-addressing}

The SLED1734X has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected.

To configure this, set the `SLED1734X_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index:

|Define |Value |
|------------------------------|------|
|`SLED1734X_I2C_ADDRESS_GND` |`0x74`|
|`SLED1734X_I2C_ADDRESS_SCL` |`0x75`|
|`SLED1734X_I2C_ADDRESS_SDA` |`0x76`|
|`SLED1734X_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 sled1734x_led PROGMEM g_sled1734x_leds[SLED1734X_LED_COUNT] = {
/* Driver
* | R G B */
{0, CA3_D, CA1_D, CA2_D},
// 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 `D` pin, and their cathodes on the `CA1`, `CA2` and `CA3` pins respectively.

These values correspond to the register indices as shown in the datasheet on page 64.
At the moment, the driver supports MATRIX TYPE 3 only.

## API {#api}

### `struct sled1734x_led_t` {#api-sled1734x-led-t}

Contains the PWM register addresses for a single RGB LED.

#### Members {#api-sled1734x-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 sled1734x_init(uint8_t index)` {#api-sled1734x-init}

Initialize the LED driver. This function should be called first.

#### Arguments {#api-sled1734x-init-arguments}

- `uint8_t index`
The driver index.

---

### `void sled1734x_write_register(uint8_t index, uint8_t reg, uint8_t data)` {#api-sled1734x-write-register}

Set the value of the given register.

#### Arguments {#api-sled1734x-write-register-arguments}

- `uint8_t index`
The driver index.
- `uint8_t reg`
The register address.
- `uint8_t data`
The value to set.

---

### `void sled1734x_select_page(uint8_t index, uint8_t page)` {#api-sled1734x-select-page}

Change the current page for configuring the LED driver.

#### Arguments {#api-sled1734x-select-page-arguments}

- `uint8_t index`
The driver index.
- `uint8_t page`
The page number to select.

---

### `void sled1734x_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-sled1734x-set-color}

Set the color of a single LED (RGB driver only). This function does not immediately update the LEDs; call `sled1734x_update_pwm_buffers()` after you are finished.

#### Arguments {#api-sled1734x-set-color-arguments}

- `int index`
The LED index (ie. the index into the `g_sled1734x_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 sled1734x_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-sled1734x-set-color-all}

Set the color of all LEDs (RGB driver only).

#### Arguments {#api-sled1734x-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 sled1734x_set_led_control_register(uint8_t index, bool red, bool green, bool blue)` {#api-sled1734x-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 `sled1734x_update_led_control_registers()` after you are finished.

#### Arguments {#api-sled1734x-set-led-control-register-rgb-arguments}

- `uint8_t index`
The LED index (ie. the index into the `g_sled1734x_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 sled1734x_update_pwm_buffers(uint8_t index)` {#api-sled1734x-update-pwm-buffers}

Flush the PWM values to the LED driver.

#### Arguments {#api-sled1734x-update-pwm-buffers-arguments}

- `uint8_t index`
The driver index.

---

### `void sled1734x_update_led_control_registers(uint8_t index)` {#api-sled1734x-update-led-control-registers}

Flush the LED control register values to the LED driver.

#### Arguments {#api-sled1734x-update-led-control-registers-arguments}

- `uint8_t index`
The driver index.
62 changes: 1 addition & 61 deletions docs/features/rgb_matrix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ RGB Matrix is an abstraction layer on top of an underlying LED driver API. The l
|[IS31FL3745](../drivers/is31fl3745) |48 |
|[IS31FL3746A](../drivers/is31fl3746a)|24 |
|[SNLED27351](../drivers/snled27351) |64 |
|[SLED1734X](../drivers/sled1734x) |70 |
|[WS2812](../drivers/ws2812) |? |

To assign the RGB Matrix driver, add the following to your `rules.mk`, for example:
Expand All @@ -33,67 +34,6 @@ To assign the RGB Matrix driver, add the following to your `rules.mk`, for examp
RGB_MATRIX_DRIVER = is31fl3218
```

---
### SLED1734X {#sled1734x}

There is basic support for addressable RGB matrix lighting with the I2C SLED1734X RGB controller. To enable it, add this to your `rules.mk`:

```make
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = sled1734x
```

You can use between 1 and 4 SLED1734X IC's. Do not specify `DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:

| Variable | Description | Default |
|----------|-------------|---------|
| `SLED1734X_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
| `SLED1734X_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | |
| `SLED1734X_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | |
| `SLED1734X_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | |
| `SLED1734X_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | |
| `SLED1734X_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | |

Here is an example using 2 drivers.

```c
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 0b1110100 (0x74) AD <-> GND
// 0b1110111 (0x77) AD <-> VCC
// 0b1110101 (0x75) AD <-> SCL
// 0b1110110 (0x76) AD <-> SDA
#define SLED1734X_I2C_ADDRESS_1 SLED1734X_I2C_ADDRESS_GND
#define SLED1734X_I2C_ADDRESS_2 SLED1734X_I2C_ADDRESS_SDA

#define DRIVER_1_LED_TOTAL 25
#define DRIVER_2_LED_TOTAL 24
#define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
```
!> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_sled1734x_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_sled1734x_leds`.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
```c
const sled1734x_led PROGMEM g_sled1734x_leds[RGB_MATRIX_LED_COUNT] = {
/* Refer to SLED1734X manual for these locations
* driver
* | R location
* | | G location
* | | | B location
* | | | | */
{0, CA3_D, CA1_D, CA2_D},
....
}
```

Where `CZx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.sonix.com.tw/files/1/637E852205EF6BC3E050007F01007792) and the header file `drivers/led/sled1734x.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`).

---
## Common Configuration {#common-configuration}

Expand Down

0 comments on commit 2025e94

Please sign in to comment.