1.. _shields:
2
3Shields
4#######
5
6Shields, also known as "add-on" or "daughter boards", attach to a board
7to extend its features and services for easier and modularized prototyping.
8In Zephyr, the shield feature provides Zephyr-formatted shield
9descriptions for easier compatibility with applications.
10
11Shield porting and configuration
12********************************
13
14Shield configuration files are available in the board directory
15under :zephyr_file:`/boards/shields`:
16
17.. code-block:: none
18
19   boards/shields/<shield>
20   ├── <shield>.overlay
21   ├── Kconfig.shield
22   └── Kconfig.defconfig
23
24These files provides shield configuration as follows:
25
26* **<shield>.overlay**: This file provides a shield description in devicetree
27  format that is merged with the board's :ref:`devicetree <dt-guide>`
28  before compilation.
29
30* **Kconfig.shield**: This file defines shield Kconfig symbols that will be
31  used for default shield configuration. To ease use with applications,
32  the default shield configuration here should be consistent with those in
33  the :ref:`default_board_configuration`.
34
35* **Kconfig.defconfig**: This file defines the default shield configuration. It
36  is made to be consistent with the :ref:`default_board_configuration`. Hence,
37  shield configuration should be done by keeping in mind that features
38  activation is application responsibility.
39
40Board compatibility
41*******************
42
43Hardware shield-to-board compatibility depends on the use of well-known
44connectors used on popular boards (such as Arduino and 96boards).  For
45software compatibility, boards must also provide a configuration matching
46their supported connectors.
47
48This should be done at two different level:
49
50* Pinmux: Connector pins should be correctly configured to match shield pins
51
52* Devicetree: A board :ref:`devicetree <dt-guide>` file,
53  :file:`BOARD.dts` should define a node alias for each connector interface.
54  For example, for Arduino I2C:
55
56.. code-block:: devicetree
57
58        #define arduino_i2c i2c1
59
60        aliases {
61                arduino,i2c = &i2c1;
62        };
63
64Note: With support of dtc v1.4.2, above will be replaced with the recently
65introduced overriding node element:
66
67.. code-block:: devicetree
68
69        arduino_i2c:i2c1{};
70
71Board specific shield configuration
72-----------------------------------
73
74If modifications are needed to fit a shield to a particular board or board
75revision, you can override a shield description for a specific board by adding
76board or board revision overriding files to a shield, as follows:
77
78.. code-block:: none
79
80   boards/shields/<shield>
81   └── boards
82       ├── <board>_<revision>.overlay
83       ├── <board>.overlay
84       ├── <board>.defconfig
85       ├── <board>_<revision>.conf
86       └── <board>.conf
87
88
89Shield activation
90*****************
91
92Activate support for one or more shields by adding the matching -DSHIELD arg to
93CMake command
94
95  .. zephyr-app-commands::
96     :zephyr-app: your_app
97     :shield: "x_nucleo_idb05a1 x_nucleo_iks01a1"
98     :goals: build
99
100
101Alternatively, it could be set by default in a project's CMakeLists.txt:
102
103.. code-block:: none
104
105	set(SHIELD x_nucleo_iks01a1)
106
107Shield variants
108***************
109
110Some shields may support several variants or revisions. In that case, it is
111possible to provide multiple version of the shields description:
112
113.. code-block:: none
114
115   boards/shields/<shield>
116   ├── <shield_v1>.overlay
117   ├── <shield_v1>.defconfig
118   ├── <shield_v2>.overlay
119   └── <shield_v2>.defconfig
120
121In this case, a shield-particular revision name can be used:
122
123  .. zephyr-app-commands::
124     :zephyr-app: your_app
125     :shield: shield_v2
126     :goals: build
127
128You can also provide a board-specific configuration to a specific shield
129revision:
130
131.. code-block:: none
132
133   boards/shields/<shield>
134   ├── <shield_v1>.overlay
135   ├── <shield_v1>.defconfig
136   ├── <shield_v2>.overlay
137   ├── <shield_v2>.defconfig
138   └── boards
139       └── <shield_v2>
140           ├── <board>.overlay
141           └── <board>.defconfig
142
143GPIO nexus nodes
144****************
145
146GPIOs accessed by the shield peripherals must be identified using the
147shield GPIO abstraction, for example from the ``arduino-header-r3``
148compatible.  Boards that provide the header must map the header pins
149to SOC-specific pins.  This is accomplished by including a `nexus
150node`_ that looks like the following into the board devicetree file:
151
152.. _nexus node:
153    https://github.com/devicetree-org/devicetree-specification/blob/4b1dac80eaca45b4babf5299452a951008a5d864/source/devicetree-basics.rst#nexus-nodes-and-specifier-mapping
154
155.. code-block:: none
156
157    arduino_header: connector {
158            compatible = "arduino-header-r3";
159            #gpio-cells = <2>;
160            gpio-map-mask = <0xffffffff 0xffffffc0>;
161            gpio-map-pass-thru = <0 0x3f>;
162            gpio-map = <0 0 &gpioa 0 0>,    /* A0 */
163                       <1 0 &gpioa 1 0>,    /* A1 */
164                       <2 0 &gpioa 4 0>,    /* A2 */
165                       <3 0 &gpiob 0 0>,    /* A3 */
166                       <4 0 &gpioc 1 0>,    /* A4 */
167                       <5 0 &gpioc 0 0>,    /* A5 */
168                       <6 0 &gpioa 3 0>,    /* D0 */
169                       <7 0 &gpioa 2 0>,    /* D1 */
170                       <8 0 &gpioa 10 0>,   /* D2 */
171                       <9 0 &gpiob 3 0>,    /* D3 */
172                       <10 0 &gpiob 5 0>,   /* D4 */
173                       <11 0 &gpiob 4 0>,   /* D5 */
174                       <12 0 &gpiob 10 0>,  /* D6 */
175                       <13 0 &gpioa 8 0>,   /* D7 */
176                       <14 0 &gpioa 9 0>,   /* D8 */
177                       <15 0 &gpioc 7 0>,   /* D9 */
178                       <16 0 &gpiob 6 0>,   /* D10 */
179                       <17 0 &gpioa 7 0>,   /* D11 */
180                       <18 0 &gpioa 6 0>,   /* D12 */
181                       <19 0 &gpioa 5 0>,   /* D13 */
182                       <20 0 &gpiob 9 0>,   /* D14 */
183                       <21 0 &gpiob 8 0>;   /* D15 */
184    };
185
186This specifies how Arduino pin references like ``<&arduino_header 11
1870>`` are converted to SOC gpio pin references like ``<&gpiob 4 0>``.
188
189In Zephyr GPIO specifiers generally have two parameters (indicated by
190``#gpio-cells = <2>``): the pin number and a set of flags.  The low 6
191bits of the flags correspond to features that can be configured in
192devicetree.  In some cases it's necessary to use a non-zero flag value
193to tell the driver how a particular pin behaves, as with:
194
195.. code-block:: none
196
197    drdy-gpios = <&arduino_header 11 GPIO_ACTIVE_LOW>;
198
199After preprocessing this becomes ``<&arduino_header 11 1>``.  Normally
200the presence of such a flag would cause the map lookup to fail,
201because there is no map entry with a non-zero flags value.  The
202``gpio-map-mask`` property specifies that, for lookup, all bits of the
203pin and all but the low 6 bits of the flags are used to identify the
204specifier.  Then the ``gpio-map-pass-thru`` specifies that the low 6
205bits of the flags are copied over, so the SOC GPIO reference becomes
206``<&gpiob 4 1>`` as intended.
207
208See `nexus node`_ for more information about this capability.
209