aboutsummaryrefslogtreecommitdiff
path: root/docs/ws2812_driver.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ws2812_driver.md')
-rw-r--r--docs/ws2812_driver.md50
1 files changed, 26 insertions, 24 deletions
diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md
index 8851c042f0..c445e2dbf6 100644
--- a/docs/ws2812_driver.md
+++ b/docs/ws2812_driver.md
@@ -1,4 +1,4 @@
-# WS2812 Driver :id=ws2812-driver
+# WS2812 Driver {#ws2812-driver}
This driver provides support for WorldSemi addressable RGB(W) LEDs, and compatible equivalents:
@@ -8,9 +8,9 @@ This driver provides support for WorldSemi addressable RGB(W) LEDs, and compatib
These LEDs are often called "addressable" because instead of using a wire per color (and per LED), each LED contains a small microchip that understands a special protocol sent over a single wire.
The LEDs can be chained together, and the remaining data is passed on to the next. In this way, you can easily control the color of many LEDs using a single GPIO.
-## Usage :id=usage
+## Usage {#usage}
-In most cases, the WS2812 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `ws2812` driver set, and you would use those APIs instead.
+In most cases, the WS2812 driver code is automatically included if you are using either the [RGBLight](feature_rgblight) or [RGB Matrix](feature_rgb_matrix) feature with the `ws2812` driver set, and you would use those APIs instead.
However, if you need to use the driver standalone, add the following to your `rules.mk`:
@@ -20,7 +20,7 @@ WS2812_DRIVER_REQUIRED = yes
You can then call the WS2812 API by including `ws2812.h` in your code.
-## Basic Configuration :id=basic-configuration
+## Basic Configuration {#basic-configuration}
Add the following to your `config.h`:
@@ -35,14 +35,14 @@ Add the following to your `config.h`:
|`WS2812_BYTE_ORDER`|`WS2812_BYTE_ORDER_GRB`|The byte order of the RGB data |
|`WS2812_RGBW` |*Not defined* |Enables RGBW support (except `i2c` driver) |
-### Timing Adjustment :id=timing-adjustment
+### Timing Adjustment {#timing-adjustment}
The WS2812 LED communication protocol works by encoding a "1" bit with a long high pulse (T<sub>1</sub>H), and a "0" bit with a shorter pulse (T<sub>0</sub>H). The total cycle length of a bit is the same.
The "reset" pulse (T<sub>RST</sub>) latches the sent RGB data to all of the LEDs and denotes a completed "frame".
Some WS2812 variants have slightly different timing parameter requirements, which can be accounted for if necessary using the above `#define`s in your `config.h`.
-### Byte Order :id=byte-order
+### Byte Order {#byte-order}
Some WS2812 variants may have their color components in a different physical or logical order. For example, the WS2812B-2020 has physically swapped red and green LEDs, which causes the wrong color to be displayed, because the default order of the bytes sent over the wire is defined as GRB.
If you find your LED colors are consistently swapped, you may need to change the byte order by adding the following to your `config.h`:
@@ -59,7 +59,7 @@ Where the byte order may be one of:
|`RGB` |WS2812B-2020 |
|`BGR` |TM1812 |
-### RGBW Support :id=rgbw-support
+### RGBW Support {#rgbw-support}
Rendering the color white with RGB LEDs is typically inconsistent due to inherent variations between each individual LED die. However, some WS2812 variants (such as SK6812RGBW) also possess a white LED along with the red, green, and blue channels, which allows for a more accurate white to be displayed.
@@ -80,11 +80,11 @@ To enable RGBW conversion, add the following to your `config.h`:
#define WS2812_RGBW
```
-## Driver Configuration :id=driver-configuration
+## Driver Configuration {#driver-configuration}
Driver selection can be configured in `rules.mk` as `WS2812_DRIVER`, or in `info.json` as `ws2812.driver`. Valid values are `bitbang` (default), `i2c`, `spi`, `pwm`, `vendor`, or `custom`. See below for information on individual drivers.
-### Bitbang Driver :id=bitbang-driver
+### Bitbang Driver {#bitbang-driver}
This is the default WS2812 driver. It operates by "bit-banging" ie. directly toggling the GPIO.
@@ -94,7 +94,7 @@ Please note that on AVR devices, due to the tight timing requirements longer cha
WS2812_DRIVER = bitbang
```
-### I2C Driver :id=i2c-driver
+### I2C Driver {#i2c-driver}
A specialized driver mainly used for PS2AVRGB (Bootmapper Client) boards, which possess an ATtiny85 that handles the WS2812 LEDs.
@@ -109,7 +109,7 @@ The following `#define`s apply only to the `i2c` driver:
|`WS2812_I2C_ADDRESS`|`0xB0` |The I2C address of the ATtiny85. |
|`WS2812_I2C_TIMEOUT`|`100` |The I2C timeout, in milliseconds.|
-### PIO Driver :id=pio-driver
+### PIO Driver {#pio-driver}
This driver is RP2040-only, and leverages the onboard PIO (programmable I/O) system and DMA to offload processing from the CPU.
@@ -119,7 +119,7 @@ The WS2812 PIO program uses one state machine, six instructions and one DMA inte
WS2812_DRIVER = vendor
```
-### PWM Driver :id=pwm-driver
+### PWM Driver {#pwm-driver}
This driver is ARM-only, and leverages the onboard PWM peripheral and DMA to offload processing from the CPU.
@@ -127,7 +127,7 @@ This driver is ARM-only, and leverages the onboard PWM peripheral and DMA to off
WS2812_DRIVER = pwm
```
-### SPI Driver :id=spi-driver
+### SPI Driver {#spi-driver}
This driver is ARM-only, and leverages the onboard SPI peripheral and DMA to offload processing from the CPU. The DI pin **must** be connected to the MOSI pin on the MCU, and all other SPI pins **must** be left unused. This is also very dependent on your MCU's SPI peripheral clock speed, and may or may not be possible depending on the MCU selected.
@@ -135,7 +135,7 @@ This driver is ARM-only, and leverages the onboard SPI peripheral and DMA to off
WS2812_DRIVER = spi
```
-## ChibiOS/ARM Configuration :id=arm-configuration
+## ChibiOS/ARM Configuration {#arm-configuration}
The following defines apply only to ARM devices:
@@ -144,7 +144,7 @@ The following defines apply only to ARM devices:
|`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
|`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)|
-### Push-Pull and Open Drain :id=push-pull-open-drain
+### Push-Pull and Open Drain {#push-pull-open-drain}
By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground.
@@ -156,7 +156,7 @@ To configure the DI pin for open drain configuration, add the following to your
#define WS2812_EXTERNAL_PULLUP
```
-### SPI Driver :id=arm-spi-driver
+### SPI Driver {#arm-spi-driver}
Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like:
@@ -181,7 +181,7 @@ The following `define`s apply only to the `spi` driver:
|`WS2812_SPI_DIVISOR` |`16` |The divisor used to adjust the baudrate |
|`WS2812_SPI_USE_CIRCULAR_BUFFER`|*Not defined*|Enable a circular buffer for improved rendering |
-#### Setting the Baudrate :id=arm-spi-baudrate
+#### Setting the Baudrate {#arm-spi-baudrate}
To adjust the SPI baudrate, you will need to derive the target baudrate from the clock tree provided by STM32CubeMX, and add the following to your `config.h`:
@@ -191,7 +191,7 @@ To adjust the SPI baudrate, you will need to derive the target baudrate from the
Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported on STM32 devices. Other MCUs may have similar constraints -- check the reference manual for your respective MCU for specifics.
-#### Circular Buffer :id=arm-spi-circular-buffer
+#### Circular Buffer {#arm-spi-circular-buffer}
A circular buffer can be enabled if you experience flickering.
@@ -201,7 +201,7 @@ To enable the circular buffer, add the following to your `config.h`:
#define WS2812_SPI_USE_CIRCULAR_BUFFER
```
-### PIO Driver :id=arm-pio-driver
+### PIO Driver {#arm-pio-driver}
The following `#define`s apply only to the PIO driver:
@@ -209,7 +209,7 @@ The following `#define`s apply only to the PIO driver:
|---------------------|-------------|---------------------------------------|
|`WS2812_PIO_USE_PIO1`|*Not defined*|Use the PIO1 peripheral instead of PIO0|
-### PWM Driver :id=arm-pwm-driver
+### PWM Driver {#arm-pwm-driver}
Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like:
@@ -235,15 +235,17 @@ The following `#define`s apply only to the `pwm` driver:
|`WS2812_PWM_DMAMUX_ID` |*Not defined* |The DMAMUX configuration for `TIMx_UP` - only required if your MCU has a DMAMUX peripheral|
|`WS2812_PWM_COMPLEMENTARY_OUTPUT`|*Not defined* |Whether the PWM output is complementary (`TIMx_CHyN`) |
-?> Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in `mcuconf.h` must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations.
+::: tip
+Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in `mcuconf.h` must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations.
+:::
-## API :id=api
+## API {#api}
-### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` :id=api-ws2812-setleds
+### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` {#api-ws2812-setleds}
Send RGB data to the WS2812 LED chain.
-#### Arguments :id=api-ws2812-setleds-arguments
+#### Arguments {#api-ws2812-setleds-arguments}
- `rgb_led_t *ledarray`
A pointer to the LED array.