1.. _dt-inferred-bindings:
2.. _dt-zephyr-user:
3
4The ``/zephyr,user`` node
5#########################
6
7Zephyr's devicetree scripts handle the ``/zephyr,user`` node as a special case:
8you can put essentially arbitrary properties inside it and retrieve their
9values without having to write a binding. It is meant as a convenient container
10when only a few simple properties are needed.
11
12.. note::
13
14   This node is meant for sample code and user applications. It should not be
15   used in the upstream Zephyr source code for device drivers, subsystems, etc.
16
17Simple values
18*************
19
20You can store numeric or array values in ``/zephyr,user`` if you want them to
21be configurable at build time via devicetree.
22
23For example, with this devicetree overlay:
24
25.. code-block:: devicetree
26
27   / {
28	zephyr,user {
29		boolean;
30		bytes = [81 82 83];
31		number = <23>;
32		numbers = <1>, <2>, <3>;
33		string = "text";
34		strings = "a", "b", "c";
35	};
36   };
37
38You can get the above property values in C/C++ code like this:
39
40.. code-block:: C
41
42   #define ZEPHYR_USER_NODE DT_PATH(zephyr_user)
43
44   DT_PROP(ZEPHYR_USER_NODE, boolean) // 1
45   DT_PROP(ZEPHYR_USER_NODE, bytes)   // {0x81, 0x82, 0x83}
46   DT_PROP(ZEPHYR_USER_NODE, number)  // 23
47   DT_PROP(ZEPHYR_USER_NODE, numbers) // {1, 2, 3}
48   DT_PROP(ZEPHYR_USER_NODE, string)  // "text"
49   DT_PROP(ZEPHYR_USER_NODE, strings) // {"a", "b", "c"}
50
51Devices
52*******
53
54You can store :ref:`phandles <dt-phandles>` in ``/zephyr,user`` if you want to
55be able to reconfigure which devices your application uses in simple cases
56using devicetree overlays.
57
58For example, with this devicetree overlay:
59
60.. code-block:: devicetree
61
62   / {
63	zephyr,user {
64		handle = <&gpio0>;
65		handles = <&gpio0>, <&gpio1>;
66        };
67   };
68
69You can convert the phandles in the ``handle`` and ``handles`` properties to
70device pointers like this:
71
72.. code-block:: C
73
74   /*
75    * Same thing as:
76    *
77    * ... my_dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));
78    */
79   const struct device *my_device =
80   	DEVICE_DT_GET(DT_PROP(ZEPHYR_USER_NODE, handle));
81
82   /*
83    * Same thing as:
84    *
85    * ... *my_devices[] = {
86    *         DEVICE_DT_GET(DT_NODELABEL(gpio0)),
87    *         DEVICE_DT_GET(DT_NODELABEL(gpio1))
88    * };
89    */
90   const struct device *my_devices[] = {
91        DT_FOREACH_PROP_ELEM_SEP(ZEPHYR_USER_NODE, handles, DEVICE_DT_GET_BY_IDX, (,))
92   };
93
94GPIOs
95*****
96
97The ``/zephyr,user`` node is a convenient place to store application-specific
98GPIOs that you want to be able to reconfigure with a devicetree overlay.
99
100For example, with this devicetree overlay:
101
102.. code-block:: devicetree
103
104   #include <zephyr/dt-bindings/gpio/gpio.h>
105
106   / {
107	zephyr,user {
108		signal-gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
109        };
110   };
111
112You can convert the pin defined in ``signal-gpios`` to a ``struct
113gpio_dt_spec`` in your source code, then use it like this:
114
115.. code-block:: C
116
117   #include <zephyr/drivers/gpio.h>
118
119   #define ZEPHYR_USER_NODE DT_PATH(zephyr_user)
120
121   const struct gpio_dt_spec signal =
122           GPIO_DT_SPEC_GET(ZEPHYR_USER_NODE, signal_gpios);
123
124   /* Configure the pin */
125   gpio_pin_configure_dt(&signal, GPIO_OUTPUT_INACTIVE);
126
127   /* Set the pin to its active level */
128   gpio_pin_set_dt(&signal, 1);
129
130(See :c:struct:`gpio_dt_spec`, :c:macro:`GPIO_DT_SPEC_GET`, and
131:c:func:`gpio_pin_configure_dt` for details on these APIs.)
132