8eb734cd82
The Zephyr configuration system uses many different files in many different formats. It makes it a lot easier for users to understand what these files do if when we use the correct file extensions. To this end we rename the dts.fixup files to the correct file extension '.h'. This is a breaking change for out-of-tree fixup files. Such files will be detected and given an appropriate error message. Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>
82 lines
2.4 KiB
ReStructuredText
82 lines
2.4 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 :file:`/boards/shields`:
|
|
|
|
.. code-block:: none
|
|
|
|
boards/shields/<shield>
|
|
├── Kconfig.shield
|
|
├── Kconfig.defconfig
|
|
├── <shield>.overlay
|
|
└── dts_fixup.h
|
|
|
|
These files provides shield configuration as follows:
|
|
|
|
* **Kconfig.shield**: This file defines the shield's config flag
|
|
(CONFIG_SHIELD_X). Applications use this flag to trigger the shield
|
|
configuration on top of the board configuration, enabling each shield
|
|
component or sensor driver.
|
|
|
|
* **Kconfig.defconfig**: This file provides conditional configuration of
|
|
specific driver default configurations, offering flexibility for broad
|
|
board support.
|
|
|
|
* **<shield>.overlay**: This file provides a shield description in device tree
|
|
format that is merged with the board's device tree information before
|
|
compilation.
|
|
|
|
* **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
|
|
|
|
* Device tree: A board 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{};
|
|
|
|
|
|
Shield activation
|
|
*****************
|
|
|
|
Activate support for a shield by enabling the corresponding Kconfig shield
|
|
option in the application's prj.conf file.
|
|
|
|
.. code-block:: none
|
|
|
|
#CONFIG_SHIELD_X_NUCLEO_IKS01A2=y
|