.. _shields:

Shields
#######

Shields, also known as "add-on" or "daughter boards", attach to a board
to extend its features and services for easier and modularized prototyping.
In Zephyr, the shield feature provides Zephyr-formatted shield
descriptions for easier compatibility with applications.

Shield porting and configuration
********************************

Shield configuration files are available in the board directory
under :zephyr_file:`/boards/shields`:

.. code-block:: none

   boards/shields/<shield>
   ├── <shield>.overlay
   ├── <shield>.conf
   └── dts_fixup.h

These files provides shield configuration as follows:

* **<shield>.overlay**: This file provides a shield description in devicetree
  format that is merged with the board's devicetree information before
  compilation.

* **<shield>.conf**: This file defines values for Kconfig symbols that are
  required for default shield configuration. To ease use with applications,
  the default shield configuration here should be consistent with those in
  the :ref:`default_board_configuration`.

* **dts_fixup.h**: This is a fixup file to bind board components definitions with
  application in a generic fashion to enable shield compatibility across boards

Board compatibility
*******************

Hardware shield-to-board compatibility depends on the use of well-known
connectors used on popular boards (such as Arduino and 96boards).  For
software compatibility, boards must also provide a configuration matching
their supported connectors.

This should be done at two different level:

* Pinmux: Connector pins should be correctly configured to match shield pins

* Devicetree: A board :ref:`device-tree` file should define a node alias for
  each connector interface. For example, for Arduino I2C:

.. code-block:: none

        #define arduino_i2c i2c1

        aliases {
                arduino,i2c = &i2c1;
        };

Note: With support of dtc v1.4.2, above will be replaced with the recently
introduced overriding node element:

.. code-block:: none

        arduino_i2c:i2c1{};

Board specific shield configuration
-----------------------------------

If modifications are needed to fit a shield to a particular board, you can
override a shield description for a specific board by adding board-overriding
files to a shield, as follows:

.. code-block:: none

   boards/shields/<shield>
   └── <boards>
       ├── board.overlay
       └── board.conf


Shield activation
*****************

Activate support for a shield by adding the matching -DSHIELD arg to CMake
command

  .. zephyr-app-commands::
     :zephyr-app: your_app
     :shield: x_nucleo_iks01a1
     :goals: build


Alternatively, it could be set by default in a project's CMakeLists.txt:

.. code-block:: none

	set(SHIELD x_nucleo_iks01a1)

Shield variants
***************

Some shields may support several variants or revisions. In that case, it is
possible to provide multiple version of the shields description:

.. code-block:: none

   boards/shields/<shield>
   ├── <shield_v1>.overlay
   ├── <shield_v1>.conf
   ├── <shield_v2>.overlay
   └── <shield_v2>.conf

In this case, a shield-particular revision name can be used:

  .. zephyr-app-commands::
     :zephyr-app: your_app
     :shield: shield_v2
     :goals: build

You can also provide a board-specific configuration to a specific shield
revision:

.. code-block:: none

   boards/shields/<shield>
   ├── <shield_v1>.overlay
   ├── <shield_v1>.conf
   ├── <shield_v2>.overlay
   ├── <shield_v2>.conf
   └── <boards>
       └── <shield_v2>
           ├── board.overlay
           └── board.conf