1.. zephyr:code-sample:: led-ws2812
2   :name: WS2812 LED strip
3   :relevant-api: led_strip_interface
4
5   Control an LED strip using a WS2812 (or compatible) driver chip.
6
7Overview
8********
9
10This sample application demonstrates basic usage of the WS2812 LED
11strip driver, for controlling LED strips using WS2812, WS2812b,
12SK6812, Everlight B1414 and compatible driver chips.
13
14Requirements
15************
16
17.. _NeoPixel Ring 12 from AdaFruit: https://www.adafruit.com/product/1643
18.. _74AHCT125: https://cdn-shop.adafruit.com/datasheets/74AHC125.pdf
19
20- LED strip using WS2812 or compatible, such as the `NeoPixel Ring 12
21  from AdaFruit`_.
22
23- Note that 5V communications may require a level translator, such as the
24  `74AHCT125`_.
25
26- LED power strip supply. It's fine to power the LED strip off of your board's
27  IO voltage level even if that's below 5V; the LEDs will simply be dimmer in
28  this case.
29
30Wiring
31******
32
33#. Ensure your Zephyr board, and the LED strip share a common ground.
34#. Connect the LED strip control pin (either I2S SDOUT, SPI MOSI or GPIO) from
35   your board to the data input pin of the first WS2812 IC in the strip.
36#. Power the LED strip at an I/O level compatible with the control pin signals.
37
38Wiring on a thingy52
39********************
40
41The thingy52 has integrated NMOS transistors, that can be used instead of a level shifter.
42The I2S driver supports inverting the output to suit this scheme, using the ``out-active-low`` dts
43property. See the overlay file
44:zephyr_file:`samples/drivers/led_ws2812/boards/thingy52_nrf52832.overlay` for more detail.
45
46Building and Running
47*********************
48
49.. _blog post on WS2812 timing: https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/
50
51This sample's source directory is :zephyr_file:`samples/drivers/led_ws2812/`.
52
53To make sure the sample is set up properly for building, you must:
54
55- select the correct WS2812 driver backend for your SoC. This currently should
56  be :kconfig:option:`CONFIG_WS2812_STRIP_SPI` unless you are using an nRF51 SoC, in
57  which case it will be :kconfig:option:`CONFIG_WS2812_STRIP_GPIO`.
58  For the nRF52832, the SPI peripheral might output some garbage at the end of
59  transmissions, and that might confuse older WS2812 strips. Use the I2S driver
60  in those cases.
61
62- create a ``led-strip`` :ref:`devicetree alias <dt-alias-chosen>`, which refers
63  to a node in your :ref:`devicetree <dt-guide>` with a
64  ``worldsemi,ws2812-i2s``, ``worldsemi,ws2812-spi`` or
65  ``worldsemi,ws2812-gpio`` compatible. The node must be properly configured for
66  the driver backend (I2S, SPI or GPIO) and daisy chain length (number of WS2812
67  chips).
68
69For example devicetree configurations for each compatible, see
70:zephyr_file:`samples/drivers/led_ws2812/boards/thingy52_nrf52832.overlay`,
71:zephyr_file:`samples/drivers/led_ws2812/boards/nrf52dk_nrf52832.overlay` and
72:zephyr_file:`samples/drivers/led_ws2812/boards/nrf51dk_nrf51422.overlay`.
73
74Some boards are already supported out of the box; see the :file:`boards`
75directory for this sample for details.
76
77The sample updates the LED strip periodically. The update frequency can be
78modified by changing the :kconfig:option:`CONFIG_SAMPLE_LED_UPDATE_DELAY`.
79
80Then build and flash the application:
81
82.. zephyr-app-commands::
83   :zephyr-app: samples/drivers/led_ws2812
84   :board: <board>
85   :goals: flash
86   :compact:
87
88When you connect to your board's serial console, you should see the
89following output:
90
91.. code-block:: none
92
93   ***** Booting Zephyr OS build v2.1.0-rc1-191-gd2466cdaf045 *****
94   [00:00:00.005,920] <inf> main: Found LED strip device WS2812
95   [00:00:00.005,950] <inf> main: Displaying pattern on strip
96
97Supported drivers
98*****************
99
100This sample uses different drivers depending on the selected board:
101
102I2S driver:
103
104- thingy52_nrf52832
105
106SPI driver:
107
108- mimxrt1050_evk
109- mimxrt1050_evk_qspi
110- nrf52dk_nrf52832
111- nucleo_f070rb
112- nucleo_g071rb
113- nucleo_h743zi
114- nucleo_l476rg
115
116GPIO driver (cortex-M0 only):
117
118- bbc_microbit
119- nrf51dk_nrf51422
120
121References
122**********
123
124- `RGB LED strips: an overview <http://nut-bolt.nl/2012/rgb-led-strips/>`_
125- `74AHCT125 datasheet
126  <https://cdn-shop.adafruit.com/datasheets/74AHC125.pdf>`_
127- An excellent `blog post on WS2812 timing`_.
128