The latest development version of this page may be more current than this released 2.1.0 version.

WS2812 Sample Application

Overview

This sample application demonstrates basic usage of the WS2812 LED strip driver, for controlling LED strips using WS2812, WS2812b, SK6812, and compatible driver chips.

Requirements

  • LED strip using WS2812 or compatible, such as the NeoPixel Ring 12 from AdaFruit.

  • Zephyr board with SPI master driver. SPI communications must use 5V signaling, which may require a level translator, such as the 74AHCT125.

  • 5V power supply.

Wiring

  1. Ensure your Zephyr board, the 5V power supply, and the LED strip share a common ground.

  2. Connect the MOSI pin of your board’s SPI master to the data input pin of the first WS2812 IC in the strip.

  3. Connect the 5V power supply pin to the 5V input of the LED strip.

Building and Running

The sample application is located at samples/drivers/led_ws2812/ in the Zephyr source tree.

Configure For Your LED Strip

The first thing you need to do is make sure that the driver is configured to match the particular LED chips you’re using. For example, some chips have a “green, red, blue” color ordering on their data pin, while others have “red, green, blue, white”. Check your chip’s datasheet for your configuration (though given the number of competing implementations and knock-offs, some trial and error may be necessary).

To make sure the driver is set up properly for your chips, check the values of the following configuration options:

Refer to their help strings for details.

Configure For Your Board

Now check if your board is already supported, by looking for a file named boards/YOUR_BOARD_NAME.conf in the application directory.

If your board isn’t supported yet, you’ll need to configure the application as follows.

  1. Configure your board’s SPI master in a configuration file under boards/ in the sample directory.

    To provide additional configuration for some particular board, create a boards/YOUR_BOARD_NAME.conf file in the application directory. It will be merged into the application configuration.

    In this file, you must ensure that the SPI peripheral you want to use for this demo is enabled, and that its name is “ws2812_spi”. See boards/96b_carbon.conf for an example, and refer to your board’s configuration options to set up your desired SPI master.

  2. Set the number of LEDs in your strip in the application sources. This is determined by the macro STRIP_NUM_LEDS in the file src/main.c. The value in the file was chosen to work with the AdaFruit NeoPixel Ring 12.

  3. Make sure that the SPI timing will generate pulses of the appropriate widths. This involves setting the configuration options CONFIG_WS2812_STRIP_ONE_FRAME, and CONFIG_WS2812_STRIP_ZERO_FRAME. Refer to the Kconfig help for those options, as well as this blog post on WS2812 timing, for more details.

Then build and flash the application:

west build -b <board> samples/drivers/led_ws2812
west flash

Refer to your board’s documentation for alternative flash instructions if your board doesn’t support the flash target.

When you connect to your board’s serial console, you should see the following output:

***** BOOTING ZEPHYR OS v1.9.99 *****
[general] [INF] main: Found SPI device ws2812_spi
[general] [INF] main: Found LED strip device ws2812_strip
[general] [INF] main: Displaying pattern on strip