1.. zephyr:code-sample:: rgb-led
2   :name: PWM RGB LED
3   :relevant-api: pwm_interface
4
5   Drive an RGB LED using the PWM API.
6
7Overview
8********
9
10This is a sample app which drives an RGB LED using the :ref:`PWM API <pwm_api>`.
11
12There are three single-color component LEDs in an RGB LED. Each component LED
13is driven by a PWM port where the pulse width is changed from zero to the period
14indicated in Devicetree. Such period should be fast enough to be above the
15flicker fusion threshold (the minimum flicker rate where the LED is perceived as
16being steady). The sample causes each LED component to step from dark to max
17brightness. Three **for** loops (one for each component LED) generate a gradual
18range of color changes from the RGB LED, and the sample repeats forever.
19
20Requirements
21************
22
23The board must have red, green, and blue LEDs connected via PWM output channels.
24
25The LED PWM channels must be configured using the following :ref:`devicetree
26<dt-guide>` aliases, usually in the :ref:`BOARD.dts file
27<devicetree-in-out-files>`:
28
29- ``red-pwm-led``
30- ``green-pwm-led``
31- ``blue-pwm-led``
32
33You will see at least one of these errors if you try to build this sample for
34an unsupported board:
35
36.. code-block:: none
37
38   Unsupported board: red-pwm-led devicetree alias is not defined
39   Unsupported board: green-pwm-led devicetree alias is not defined
40   Unsupported board: blue-pwm-led devicetree alias is not defined
41
42See :zephyr_file:`boards/nxp/hexiwear/hexiwear_mk64f12.dts` for an example
43:file:`BOARD.dts` file which supports this sample.
44
45Wiring
46******
47
48No additional wiring is necessary if the required devicetree aliases refer to
49hardware that is already connected to LEDs on the board.
50
51Otherwise, LEDs should be connected to the appropriate PWM channels.
52
53Building and Running
54********************
55
56For example, to build and flash this board for :ref:`hexiwear`:
57
58.. zephyr-app-commands::
59   :zephyr-app: samples/basic/rgb_led
60   :board: hexiwear/mk64f12
61   :goals: build flash
62   :compact:
63
64Change ``hexiwear/mk64f12`` appropriately for other supported boards.
65