.. _led_ws2812_sample:

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
************

.. _NeoPixel Ring 12 from AdaFruit: https://www.adafruit.com/product/1643
.. _74AHCT125: https://cdn-shop.adafruit.com/datasheets/74AHC125.pdf

- 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
  signalling, which may require a level translator, such as the
  `74AHCT125`_.

- 5V power supply.

Wiring
******

#. Ensure your Zephyr board, the 5V power supply, and the LED strip
   share a common ground.
#. Connect the MOSI pin of your board's SPI master to the data input
   pin of the first WS2812 IC in the strip.
#. Connect the 5V power supply pin to the 5V input of the LED strip.

Building and Running
********************

.. _blog post on WS2812 timing: https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/

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:

- :option:`CONFIG_WS2812_RED_ORDER`
- :option:`CONFIG_WS2812_GRN_ORDER`
- :option:`CONFIG_WS2812_BLU_ORDER`
- :option:`CONFIG_WS2812_WHT_ORDER` (available if your chips have a white
  channel by setting :option:`CONFIG_WS2812_HAS_WHITE_CHANNEL` to ``y``).

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.

#. 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.

#. 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.

#. Make sure that the SPI timing will generate pulses of the
   appropriate widths. This involves setting the configuration options
   :option:`CONFIG_WS2812_STRIP_SPI_BAUD_RATE`,
   :option:`CONFIG_WS2812_STRIP_ONE_FRAME`, and
   :option:`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:

.. code-block:: bash

   $ cd ~/zephyr
   $ source zephyr-env.sh
   $ cd samples/drivers/led_ws2812
   $ BOARD=your_board make flash

Refer to your :ref:`board's documentation <boards>` 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:

.. code-block:: none

   ***** 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

References
**********

- `RGB LED strips: an overview <http://nut-bolt.nl/2012/rgb-led-strips/>`_
- `74AHCT125 datasheet
  <https://cdn-shop.adafruit.com/datasheets/74AHC125.pdf>`_
- An excellent `blog post on WS2812 timing`_.