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