README.rst
1.. zephyr:code-sample:: blinky
2 :name: Blinky
3 :relevant-api: gpio_interface
4
5 Blink an LED forever using the GPIO API.
6
7Overview
8********
9
10The Blinky sample blinks an LED forever using the :ref:`GPIO API <gpio_api>`.
11
12The source code shows how to:
13
14#. Get a pin specification from the :ref:`devicetree <dt-guide>` as a
15 :c:struct:`gpio_dt_spec`
16#. Configure the GPIO pin as an output
17#. Toggle the pin forever
18
19See :zephyr:code-sample:`pwm-blinky` for a similar sample that uses the PWM API instead.
20
21.. _blinky-sample-requirements:
22
23Requirements
24************
25
26Your board must:
27
28#. Have an LED connected via a GPIO pin (these are called "User LEDs" on many of
29 Zephyr's :ref:`boards`).
30#. Have the LED configured using the ``led0`` devicetree alias.
31
32Building and Running
33********************
34
35Build and flash Blinky as follows, changing ``reel_board`` for your board:
36
37.. zephyr-app-commands::
38 :zephyr-app: samples/basic/blinky
39 :board: reel_board
40 :goals: build flash
41 :compact:
42
43After flashing, the LED starts to blink and messages with the current LED state
44are printed on the console. If a runtime error occurs, the sample exits without
45printing to the console.
46
47Build errors
48************
49
50You will see a build error at the source code line defining the ``struct
51gpio_dt_spec led`` variable if you try to build Blinky for an unsupported
52board.
53
54On GCC-based toolchains, the error looks like this:
55
56.. code-block:: none
57
58 error: '__device_dts_ord_DT_N_ALIAS_led_P_gpios_IDX_0_PH_ORD' undeclared here (not in a function)
59
60Adding board support
61********************
62
63To add support for your board, add something like this to your devicetree:
64
65.. code-block:: DTS
66
67 / {
68 aliases {
69 led0 = &myled0;
70 };
71
72 leds {
73 compatible = "gpio-leds";
74 myled0: led_0 {
75 gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
76 };
77 };
78 };
79
80The above sets your board's ``led0`` alias to use pin 13 on GPIO controller
81``gpio0``. The pin flags :c:macro:`GPIO_ACTIVE_HIGH` mean the LED is on when
82the pin is set to its high state, and off when the pin is in its low state.
83
84Tips:
85
86- See :dtcompatible:`gpio-leds` for more information on defining GPIO-based LEDs
87 in devicetree.
88
89- If you're not sure what to do, check the devicetrees for supported boards which
90 use the same SoC as your target. See :ref:`get-devicetree-outputs` for details.
91
92- See :zephyr_file:`include/zephyr/dt-bindings/gpio/gpio.h` for the flags you can use
93 in devicetree.
94
95- If the LED is built in to your board hardware, the alias should be defined in
96 your :ref:`BOARD.dts file <devicetree-in-out-files>`. Otherwise, you can
97 define one in a :ref:`devicetree overlay <set-devicetree-overlays>`.
98
