<spanclass="line"><span>b -= w</span></span></code></pre></div><p>Thus, an RGB triplet of <code>255,255,255</code> will simply turn on the white LED fully (<code>0,0,0,255</code>).</p><p>To enable RGBW conversion, add the following to your <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> WS2812_RGBW</span></span></code></pre></div><h2id="driver-configuration"tabindex="-1">Driver Configuration <aclass="header-anchor"href="#driver-configuration"aria-label="Permalink to "Driver Configuration {#driver-configuration}""></a></h2><p>Driver selection can be configured in <code>rules.mk</code> as <code>WS2812_DRIVER</code>, or in <code>info.json</code> as <code>ws2812.driver</code>. Valid values are <code>bitbang</code> (default), <code>i2c</code>, <code>spi</code>, <code>pwm</code>, <code>vendor</code>, or <code>custom</code>. See below for information on individual drivers.</p><h3id="bitbang-driver"tabindex="-1">Bitbang Driver <aclass="header-anchor"href="#bitbang-driver"aria-label="Permalink to "Bitbang Driver {#bitbang-driver}""></a></h3><p>This is the default WS2812 driver. It operates by "bit-banging" ie. directly toggling the GPIO.</p><p>Please note that on AVR devices, due to the tight timing requirements longer chains and/or heavy CPU loads may cause visible lag. Unfortunately this driver is usually the only option for AVR.</p><divclass="language-make vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">make</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">WS2812_DRIVER = bitbang</span></span></code></pre></div><h3id="i2c-driver"tabindex="-1">I2C Driver <aclass="header-anchor"href="#i2c-driver"aria-label="Permalink to "I2C Driver {#i2c-driver}""></a></h3><p>A specialized driver mainly used for PS2AVRGB (Bootmapper Client) boards, which possess an ATtiny85 that handles the WS2812 LEDs.</p><divclass="language-make vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">make</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">WS2812_DRIVER = i2c</span></span></code></pre></div><p>The following <code>#define</code>s apply only to the <code>i2c</code> driver:</p><table><thead><tr><th>Define</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>WS2812_I2C_ADDRESS</code></td><td><code>0xB0</code></td><td>The I2C address of the ATtiny85.</td></tr><tr><td><code>WS2812_I2C_TIMEOUT</code></td><td><code>100</code></td><td>The I2C timeout, in milliseconds.</td></tr></tbody></table><h3id="pio-driver"tabindex="-1">PIO Driver <aclass="header-anchor"href="#pio-driver"aria-label="Permalink to "PIO Driver {#pio-driver}""></a></h3><p>This driver is RP2040-only, and leverages the onboard PIO (programmable I/O) system and DMA to offload processing from the CPU.</p><p>The WS2812 PIO program uses one state machine, six instructions and one DMA interrupt handler callback. Due to the implementation the time resolution for this driver is 50 ns - any value not specified in this interval will be rounded to the next matching interval.</p><divclass="language-make vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">make</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">WS2812_DRIVER = vendor</span></span></code></pre></div><h3id="pwm-driver"tabindex="-1">PWM Driver <aclass="header-anchor"href="#pwm-driver"aria-label="Permalinkto&qu
<spanclass="line has-focus"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> STM32_SPI_USE_SPI1</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TRUE</span></span></code></pre></div></div></div><p>The following <code>define</code>s apply only to the <code>spi</code> driver:</p><table><thead><tr><th>Define</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>WS2812_SPI_DRIVER</code></td><td><code>SPID1</code></td><td>The SPI driver to use</td></tr><tr><td><code>WS2812_SPI_MOSI_PAL_MODE</code></td><td><code>5</code></td><td>The MOSI pin alternative function to use</td></tr><tr><td><code>WS2812_SPI_SCK_PIN</code></td><td><em>Not defined</em></td><td>The SCK pin - required for F072 and possibly others</td></tr><tr><td><code>WS2812_SPI_SCK_PAL_MODE</code></td><td><code>5</code></td><td>The SCK pin alternative function to use - required for F072 and possibly others</td></tr><tr><td><code>WS2812_SPI_DIVISOR</code></td><td><code>16</code></td><td>The divisor used to adjust the baudrate</td></tr><tr><td><code>WS2812_SPI_USE_CIRCULAR_BUFFER</code></td><td><em>Not defined</em></td><td>Enable a circular buffer for improved rendering</td></tr></tbody></table><h4id="arm-spi-baudrate"tabindex="-1">Setting the Baudrate <aclass="header-anchor"href="#arm-spi-baudrate"aria-label="Permalink to "Setting the Baudrate {#arm-spi-baudrate}""></a></h4><p>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 <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> WS2812_SPI_DIVISOR</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 16</span></span></code></pre></div><p>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.</p><h4id="arm-spi-circular-buffer"tabindex="-1">Circular Buffer <aclass="header-anchor"href="#arm-spi-circular-buffer"aria-label="Permalink to "Circular Buffer {#arm-spi-circular-buffer}""></a></h4><p>A circular buffer can be enabled if you experience flickering.</p><p>To enable the circular buffer, add the following to your <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> WS2812_SPI_USE_CIRCULAR_BUFFER</span></span></code></pre></div><h3id="arm-pio-driver"tabindex="-1">PIO Driver <aclass="header-anchor"href="#arm-pio-driver"aria-label="Permalink to "PIO Driver {#arm-pio-driver}""></a></h3><p>The following <code>#define</code>s apply only to the PIO driver:</p><table><thead><tr><th>Define</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>WS2812_PIO_USE_PIO1</code></td><td><em>Not defined</em></td><td>Use the PIO1 peripheral instead of PIO0</td></tr></tbody></table><h3id="arm-pwm-driver"tabindex="-1">PWM Driver <aclass="header-anchor"href="#arm-pwm-driver"aria-label="Permalink to "PWM Driver {#arm-pwm-driver}""></a></h3><p>Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like:</p><divclass="vp-code-group vp-adaptive-theme"><divclass="tabs"><inputtype="radio"name="group-6WgZm"id="tab-VwMC2ZQ"checked="checked"><labelfor="tab-VwMC2ZQ">halconf.h</label><inputtype="radio"name="group-6WgZm"i
<spanclass="line has-focus"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> STM32_PWM_USE_TIM2</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TRUE</span></span></code></pre></div></div></div><p>The following <code>#define</code>s apply only to the <code>pwm</code> driver:</p><table><thead><tr><th>Define</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>WS2812_PWM_DRIVER</code></td><td><code>PWMD2</code></td><td>The PWM driver to use</td></tr><tr><td><code>WS2812_PWM_CHANNEL</code></td><td><code>2</code></td><td>The PWM channel to use</td></tr><tr><td><code>WS2812_PWM_PAL_MODE</code></td><td><code>2</code></td><td>The pin alternative function to use</td></tr><tr><td><code>WS2812_PWM_DMA_STREAM</code></td><td><code>STM32_DMA1_STREAM2</code></td><td>The DMA Stream for <code>TIMx_UP</code></td></tr><tr><td><code>WS2812_PWM_DMA_CHANNEL</code></td><td><code>2</code></td><td>The DMA Channel for <code>TIMx_UP</code></td></tr><tr><td><code>WS2812_PWM_DMAMUX_ID</code></td><td><em>Not defined</em></td><td>The DMAMUX configuration for <code>TIMx_UP</code> - only required if your MCU has a DMAMUX peripheral</td></tr><tr><td><code>WS2812_PWM_COMPLEMENTARY_OUTPUT</code></td><td><em>Not defined</em></td><td>Whether the PWM output is complementary (<code>TIMx_CHyN</code>)</td></tr></tbody></table><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Using a complementary timer output (<code>TIMx_CHyN</code>) is possible only for advanced-control timers (1, 8 and 20 on STM32). Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations.</p></div><h2id="api"tabindex="-1">API <aclass="header-anchor"href="#api"aria-label="Permalink to "API {#api}""></a></h2><h3id="api-ws2812-init"tabindex="-1"><code>void ws2812_init(void)</code><aclass="header-anchor"href="#api-ws2812-init"aria-label="Permalink to "`void ws2812_init(void)` {#api-ws2812-init}""></a></h3><p>Initialize the LED driver. This function should be called first.</p><hr><h3id="api-ws2812-set-color"tabindex="-1"><code>void ws2812_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)</code><aclass="header-anchor"href="#api-ws2812-set-color"aria-label="Permalink to "`void ws2812_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-ws2812-set-color}""></a></h3><p>Set the color of a single LED. This function does not immediately update the LEDs; call <code>ws2812_flush()</code> after you are finished.</p><h4id="api-ws2812-set-color-arguments"tabindex="-1">Arguments <aclass="header-anchor"href="#api-ws2812-set-color-arguments"aria-label="Permalink to "Arguments {#api-ws2812-set-color-arguments}""></a></h4><ul><li><code>int index</code><br> The LED index in the WS2812 chain.</li><li><code>uint8_t red</code><br> The red value to set.</li><li><code>uint8_t green</code><br> The green value to set.</li><li><code>uint8_t blue</code><br> The blue value to set.</li></ul><hr><h3id="api-ws2812-set-color-all"tabindex="-1"><code>void ws812_set_color_all(uint8_t red, uint8_t green, uint8_t blue)</code><aclass="header-anchor"href="#api-ws2812-set-color-all"aria-label="Permalink to "`void ws812_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-ws2812-set-color-all}""></a></h3><p>Set the color of all LEDs.</p><h4id="api-ws2812-set-color-all-arguments"tabindex="-1">Arguments <aclass="header-anchor"href="#api-ws2812-set-color-all-arguments"aria-label="Permalink to "Arguments {#api-ws2812-set-color-all-arguments}""></a></h4><ul><li><code>uint8_t red</code><br> The red value to set.</li><li><code>uint8_t green</code><br> The green value to set.</li><li><code>uint8_t blue</code><br> The blue value to set.</li></ul><hr><h3id="api-ws2812-flush"tabindex="-1"><code>void ws2812_flush(void)</code><aclass="header-anchor"href="#api-ws2812-flush"aria-label="Permalinkto"`voidws2812_flush(
