1.. zephyr:code-sample:: button
2   :name: Button
3   :relevant-api: gpio_interface
4
5   Handle GPIO inputs with interrupts.
6
7Overview
8********
9
10A simple button demo showcasing the use of GPIO input with interrupts.
11The sample prints a message to the console each time a button is pressed.
12
13.. NOTE:: If you are looking into an implementation of button events with
14   debouncing, check out :ref:`input` and :zephyr:code-sample:`input-dump`
15   instead.
16
17Requirements
18************
19
20The board hardware must have a push button connected via a GPIO pin. These are
21called "User buttons" on many of Zephyr's :ref:`boards`.
22
23The button must be configured using the ``sw0`` :ref:`devicetree <dt-guide>`
24alias, usually in the :ref:`BOARD.dts file <devicetree-in-out-files>`. You will
25see this error if you try to build this sample for an unsupported board:
26
27.. code-block:: none
28
29   Unsupported board: sw0 devicetree alias is not defined
30
31You may see additional build errors if the ``sw0`` alias exists, but is not
32properly defined.
33
34The sample additionally supports an optional ``led0`` devicetree alias. This is
35the same alias used by the :zephyr:code-sample:`blinky` sample. If this is provided, the LED
36will be turned on when the button is pressed, and turned off off when it is
37released.
38
39Devicetree details
40==================
41
42This section provides more details on devicetree configuration.
43
44Here is a minimal devicetree fragment which supports this sample. This only
45includes a ``sw0`` alias; the optional ``led0`` alias is left out for
46simplicity.
47
48.. code-block:: devicetree
49
50   / {
51   	aliases {
52   		sw0 = &button0;
53   	};
54
55   	soc {
56   		gpio0: gpio@0 {
57   			status = "okay";
58   			gpio-controller;
59   			#gpio-cells = <2>;
60   			/* ... */
61   		};
62   	};
63
64   	buttons {
65   		compatible = "gpio-keys";
66   		button0: button_0 {
67   			gpios = < &gpio0 PIN FLAGS >;
68   			label = "User button";
69   		};
70   		/* ... other buttons ... */
71   	};
72   };
73
74As shown, the ``sw0`` devicetree alias must point to a child node of a node
75with a "gpio-keys" :ref:`compatible <dt-important-props>`.
76
77The above situation is for the common case where:
78
79- ``gpio0`` is an example node label referring to a GPIO controller
80-  ``PIN`` should be a pin number, like ``8`` or ``0``
81- ``FLAGS`` should be a logical OR of :ref:`GPIO configuration flags <gpio_api>`
82  meant to apply to the button, such as ``(GPIO_PULL_UP | GPIO_ACTIVE_LOW)``
83
84This assumes the common case, where ``#gpio-cells = <2>`` in the ``gpio0``
85node, and that the GPIO controller's devicetree binding names those two cells
86"pin" and "flags" like so:
87
88.. code-block:: yaml
89
90   gpio-cells:
91     - pin
92     - flags
93
94This sample requires a ``pin`` cell in the ``gpios`` property. The ``flags``
95cell is optional, however, and the sample still works if the GPIO cells
96do not contain ``flags``.
97
98Building and Running
99********************
100
101This sample can be built for multiple boards, in this example we will build it
102for the nucleo_f103rb board:
103
104.. zephyr-app-commands::
105   :zephyr-app: samples/basic/button
106   :board: nucleo_f103rb
107   :goals: build
108   :compact:
109
110After startup, the program looks up a predefined GPIO device, and configures the
111pin in input mode, enabling interrupt generation on falling edge. During each
112iteration of the main loop, the state of GPIO line is monitored and printed to
113the serial console. When the input button gets pressed, the interrupt handler
114will print an information about this event along with its timestamp.
115