136 lines
3.6 KiB
ReStructuredText
136 lines
3.6 KiB
ReStructuredText
.. _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
|