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