diff options
Diffstat (limited to 'docs/ws2812_driver.md')
| -rw-r--r-- | docs/ws2812_driver.md | 62 |
1 files changed, 40 insertions, 22 deletions
diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index 8acac0b3aa..54e6e77d81 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -11,11 +11,12 @@ These LEDs are called "addressable" because instead of using a wire per color, e ## Supported Driver Types | | AVR | ARM | -|----------|--------------------|--------------------| +| -------- | ------------------ | ------------------ | | bit bang | :heavy_check_mark: | :heavy_check_mark: | | I2C | :heavy_check_mark: | | | SPI | | :heavy_check_mark: | | PWM | | :heavy_check_mark: | +| PIO | | :heavy_check_mark: | ## Driver configuration @@ -33,11 +34,11 @@ The default setting is 280 µs, which should work for most cases, but this can b Some variants of the WS2812 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. In this case, you can change the byte order by defining `WS2812_BYTE_ORDER` as one of the following values: -|Byte order |Known devices | -|---------------------------------|-----------------------------| -|`WS2812_BYTE_ORDER_GRB` (default)|Most WS2812's, SK6812, SK6805| -|`WS2812_BYTE_ORDER_RGB` |WS2812B-2020 | -|`WS2812_BYTE_ORDER_BGR` |TM1812 | +| Byte order | Known devices | +| --------------------------------- | ----------------------------- | +| `WS2812_BYTE_ORDER_GRB` (default) | Most WS2812's, SK6812, SK6805 | +| `WS2812_BYTE_ORDER_RGB` | WS2812B-2020 | +| `WS2812_BYTE_ORDER_BGR` | TM1812 | ### Bitbang @@ -54,13 +55,13 @@ WS2812_DRIVER = bitbang The WS2812 LED communication topology depends on a serialized timed window. Different versions of the addressable LEDs have differing requirements for the timing parameters, for instance, of the SK6812. You can tune these parameters through the definition of the following macros: -| Macro |Default | AVR | ARM | -|---------------------|--------------------------------------------|--------------------|--------------------| -|`WS2812_TIMING` |`1250` | :heavy_check_mark: | :heavy_check_mark: | -|`WS2812_T0H` |`350` | :heavy_check_mark: | :heavy_check_mark: | -|`WS2812_T0L` |`WS2812_TIMING - WS2812_T0H` | | :heavy_check_mark: | -|`WS2812_T1H` |`900` | :heavy_check_mark: | :heavy_check_mark: | -|`WS2812_T1L` |`WS2812_TIMING - WS2812_T1H` | | :heavy_check_mark: | +| Macro | Default | AVR | ARM | +| --------------- | ---------------------------- | ------------------ | ------------------ | +| `WS2812_TIMING` | `1250` | :heavy_check_mark: | :heavy_check_mark: | +| `WS2812_T0H` | `350` | :heavy_check_mark: | :heavy_check_mark: | +| `WS2812_T0L` | `WS2812_TIMING - WS2812_T0H` | | :heavy_check_mark: | +| `WS2812_T1H` | `900` | :heavy_check_mark: | :heavy_check_mark: | +| `WS2812_T1L` | `WS2812_TIMING - WS2812_T1H` | | :heavy_check_mark: | ### I2C Targeting boards where WS2812 support is offloaded to a 2nd MCU. Currently the driver is limited to AVR given the known consumers are ps2avrGB/BMC. To configure it, add this to your rules.mk: @@ -107,16 +108,16 @@ To adjust the baudrate at which the SPI peripheral is configured, users will nee Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported by hardware. -|Define |Default|Description | -|--------------------|-------|-------------------------------------| -|`WS2812_SPI_DIVISOR`|`16` |SPI source clock peripheral divisor | +| Define | Default | Description | +| -------------------- | ------- | ----------------------------------- | +| `WS2812_SPI_DIVISOR` | `16` | SPI source clock peripheral divisor | #### Testing Notes While not an exhaustive list, the following table provides the scenarios that have been partially validated: | | SPI1 | SPI2 | SPI3 | -|------|---------------------------------------------|-----------------------------------------|-----------------------| +| ---- | ------------------------------------------- | --------------------------------------- | --------------------- | | f072 | ? | B15 :heavy_check_mark: (needs SCK: B13) | N/A | | f103 | A7 :heavy_check_mark: | B15 :heavy_check_mark: | N/A | | f303 | A7 :heavy_check_mark: B5 :heavy_check_mark: | B15 :heavy_check_mark: | B5 :heavy_check_mark: | @@ -150,15 +151,32 @@ You must also turn on the PWM feature in your halconf.h and mcuconf.h While not an exhaustive list, the following table provides the scenarios that have been partially validated: -| | Status | -|-|-| -| f072 | ? | -| f103 | :heavy_check_mark: | -| f303 | :heavy_check_mark: | +| | Status | +| --------- | ------------------ | +| f072 | ? | +| f103 | :heavy_check_mark: | +| f303 | :heavy_check_mark: | | f401/f411 | :heavy_check_mark: | *Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.* +### PIO + +Targeting Raspberry Pi RP2040 boards only where WS2812 support is offloaded to an dedicated PIO implementation. This offloads processing of the WS2812 protocol from the MCU to a dedicated PIO program using DMA transfers. + +To configure it, add this to your rules.mk: + +```make +WS2812_DRIVER = vendor +``` + +Configure the hardware via your config.h: +```c +#define WS2812_PIO_USE_PIO1 // Force the usage of PIO1 peripheral, by default the WS2812 implementation uses the PIO0 peripheral +``` + +The WS2812 PIO programm uses 1 state machine, 4 instructions and does not use any interrupt handlers. + ### Push Pull and Open Drain Configuration The default configuration is a push pull on the defined pin. This can be configured for bitbang, PWM and SPI. |