| .. _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`_. |