diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/Kconfig.shield b/boards/shields/seeed_grove_3axis_digital_accelerometer/Kconfig.shield new file mode 100644 index 0000000000000..c098d6cf2300a --- /dev/null +++ b/boards/shields/seeed_grove_3axis_digital_accelerometer/Kconfig.shield @@ -0,0 +1,5 @@ +# Copyright (c) 2024 TOKITA Hiroshi +# SPDX-License-Identifier: Apache-2.0 + +config SHIELD_SEEED_GROVE_LIS3DHTR + def_bool $(shields_list_contains,seeed_grove_lis3dhtr) diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/img/grove_3axis_digital_accelerometer_lis3dhtr.webp b/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/img/grove_3axis_digital_accelerometer_lis3dhtr.webp new file mode 100644 index 0000000000000..3a94ff39d733a Binary files /dev/null and b/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/img/grove_3axis_digital_accelerometer_lis3dhtr.webp differ diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/index.rst b/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/index.rst new file mode 100644 index 0000000000000..2c4ada84db480 --- /dev/null +++ b/boards/shields/seeed_grove_3axis_digital_accelerometer/doc/index.rst @@ -0,0 +1,60 @@ +.. _seeed_grove_3axis_digital_accelerometer: + +Seeed Studio Grove 3-Axis Digital Accelerometer +############################################### + +Overview +******** + +The Seeed Studio Grove 3-Axis Digital Accelerometer is a compact sensor module +that provides digital output of 3-axis acceleration. +There are several variations by the measurement range and chip. + +.. figure:: img/grove_3axis_digital_accelerometer_lis3dhtr.webp + :align: center + :alt: Grove - 3-Axis Digital Accelerometer (LIS3DHTR) + + Grove - 3-Axis Digital Accelerometer (LIS3DHTR) (Credit: Seeed Studio) + +These allows for easy integration with Grove connector system. +More information about the Grove connector system can be found at the +`Grove Ecosystem Introduction`_. + +Hardware +******** + +Currently the following models are supported: + +- seeed_grove_lis3dhtr: see `Grove - 3-Axis Digital Accelerometer (LIS3DHTR)`_ + +Programming +*********** + +Set ``--shield seeed_grove_accel_[sensor_model]`` when you invoke ``west build``. +For example: + +.. zephyr-app-commands:: + :zephyr-app: samples/sensor/sensor_shell + :board: m5stack_core2/esp32/procpu + :shield: seeed_grove_accel_lis3dhtr + :goals: build + +This shield can take a option to tweaking. +Such as connecting bus selection, i2c address, and etc. + +.. zephyr-app-commands:: + :zephyr-app: samples/sensor/sensor_shell + :board: wio_terminal/samd51p19a + :shield: seeed_grove_accel_lis3dhtr@1:addr=0x18 + :goals: build + +References +********** + +.. target-notes:: + +.. _Grove Ecosystem Introduction: + https://wiki.seeedstudio.com/Grove_System/ + +.. _Grove - 3-Axis Digital Accelerometer (LIS3DHTR): + https://wiki.seeedstudio.com/Grove-3-Axis-Digital-Accelerometer-LIS3DHTR/ diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel.overlay b/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel.overlay new file mode 100644 index 0000000000000..323ae5d6d63c6 --- /dev/null +++ b/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel.overlay @@ -0,0 +1,8 @@ +/* + * Copyright (c) 2024 TOKITA Hiroshi + * SPDX-License-Identifier: Apache-2.0 + */ + +/* For convenience, we use the same definitions as LIS3DHTR as the default for this series. */ + +#include "seeed_grove_accel.overlay" diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel_lis3dhtr.overlay b/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel_lis3dhtr.overlay new file mode 100644 index 0000000000000..49e3311baefae --- /dev/null +++ b/boards/shields/seeed_grove_3axis_digital_accelerometer/seeed_grove_accel_lis3dhtr.overlay @@ -0,0 +1,20 @@ +/* + * Copyright (c) 2024 TOKITA Hiroshi + * SPDX-License-Identifier: Apache-2.0 + */ + +#include +#include + +&SHIELD_CONN_N { + SHIELD_CONVENTIONAL_LABEL(lis3dh): lis3dh@SHIELD_ADDR_HEX { + compatible = "st,lis3dh", "st,lis2dh"; + reg = ; + +#if SHIELD_OPTION_EXISTS(IRQ_GPIO_PIN) || SHIELD_OPTION_EXISTS(IRQ_GPIO_PORT) + irq-gpios = <&SHIELD_OPTION_STRING_UNQUOTED(IRQ_GPIO_PORT) + SHIELD_OPTION(IRQ_GPIO_PIN) + SHIELD_OPTION_STRING_UNQUOTED(IRQ_GPIO_FLAG)>; +#endif + }; +}; diff --git a/boards/shields/seeed_grove_3axis_digital_accelerometer/shield.yml b/boards/shields/seeed_grove_3axis_digital_accelerometer/shield.yml new file mode 100644 index 0000000000000..d0833a3d1f88a --- /dev/null +++ b/boards/shields/seeed_grove_3axis_digital_accelerometer/shield.yml @@ -0,0 +1,26 @@ +shield: + name: seeed_grove_accel + full_name: Seeed Studio Grove - 3-Axis Digital Accelerometer + vendor: seeed + variants: + - name: lis3dhtr + full_name: Seeed Studio Grove - 3-Axis Digital Accelerometer (LIS3DHTR) + options: + addr: + default: 0x19 + irq-gpio-pin: + type: int + default: 0 + irq-gpio-port: + type: string + default: "gpio0" + irq-gpio-flag: + type: string + default: "GPIO_ACTIVE_HIGH" + options: + conn: + type: string + default: "grove_i2c" + addr: + type: int + default: 0x19 diff --git a/cmake/modules/shields.cmake b/cmake/modules/shields.cmake index 145f559b2922d..26d036a11e5a9 100644 --- a/cmake/modules/shields.cmake +++ b/cmake/modules/shields.cmake @@ -35,6 +35,15 @@ include(extensions) # Check that SHIELD has not changed. zephyr_check_cache(SHIELD WATCH) +set(GEN_SHIELD_DERIVED_OVERLAY_SCRIPT ${ZEPHYR_BASE}/scripts/build/gen_shield_derived_overlay.py) +set(GENERATED_SHIELDS_DIR ${PROJECT_BINARY_DIR}/include/generated/shields) + +# Add the directory derived overlay files to the SHIELD_DIRS output variable. +list(APPEND + SHIELD_DIRS + ${GENERATED_SHIELDS_DIR} +) + if(SHIELD) message(STATUS "Shield(s): ${SHIELD}") endif() @@ -44,7 +53,7 @@ if(DEFINED SHIELD) endif() # SHIELD-NOTFOUND is a real CMake list, from which valid shields can be popped. # After processing all shields, only invalid shields will be left in this list. -set(SHIELD-NOTFOUND ${SHIELD_AS_LIST}) +string(REGEX REPLACE "([@:][^;]*)" "" SHIELD-NOTFOUND "${SHIELD}") foreach(root ${BOARD_ROOT}) set(shield_dir ${root}/boards/shields) @@ -74,43 +83,76 @@ endforeach() # Process shields in-order if(DEFINED SHIELD) - foreach(s ${SHIELD_AS_LIST}) + foreach(shld ${SHIELD_AS_LIST}) + string(REGEX MATCH [[^([^@:]*)([@:].*)?$]] matched "${shld}") + set(s ${CMAKE_MATCH_1}) # name part + set(shield_opts ${CMAKE_MATCH_2}) # options part + if(NOT ${s} IN_LIST SHIELD_LIST) continue() endif() list(REMOVE_ITEM SHIELD-NOTFOUND ${s}) - # Add .overlay to the shield_dts_files output variable. - list(APPEND - shield_dts_files - ${SHIELD_DIR_${s}}/${s}.overlay - ) - # Add the shield's directory to the SHIELD_DIRS output variable. list(APPEND SHIELD_DIRS ${SHIELD_DIR_${s}} ) - # Search for shield/shield.conf file - if(EXISTS ${SHIELD_DIR_${s}}/${s}.conf) - list(APPEND - shield_conf_files - ${SHIELD_DIR_${s}}/${s}.conf - ) - endif() - - # Add board-specific .conf and .overlay files to their - # respective output variables. + # get board-specific .conf and .overlay filenames zephyr_file(CONF_FILES ${SHIELD_DIR_${s}}/boards - DTS shield_dts_files - KCONF shield_conf_files + DTS board_overlay_file + KCONF board_conf_file ) + zephyr_file(CONF_FILES ${SHIELD_DIR_${s}}/boards/${s} - DTS shield_dts_files - KCONF shield_conf_files + DTS board_shield_overlay_file + KCONF board_shield_conf_file ) + + get_filename_component(board_overlay_stem "${board_overlay_file}" NAME_WE) + get_filename_component(shield_overlay_stem "${board_shield_overlay_file}" NAME_WE) + + set(shield_conf_list + "${SHIELD_DIR_${s}}/${s}.conf" + "${board_conf_file}" + "${board_shield_conf_file}") + + set(shield_overlay_list + "${SHIELD_DIR_${s}}/${s}.overlay" + "${board_overlay_file}" + "${board_shield_overlay_file}") + + set(derived_overlay_list + "${GENERATED_SHIELDS_DIR}/${shld}.overlay" + "${GENERATED_SHIELDS_DIR}/${shld}_${board_overlay_stem}.overlay" + "${GENERATED_SHIELDS_DIR}/${shld}_${board_overlay_stem}_${shield_overlay_stem}.overlay") + + # Add board-specific .conf files to the shield_conf_files output variable. + foreach(src_conf ${shield_conf_list}) + if(EXISTS ${src_conf}) + list(APPEND shield_conf_files ${src_conf}) + endif() + endforeach() + + foreach(shield_overlay derived_overlay IN ZIP_LISTS shield_overlay_list derived_overlay_list) + if (EXISTS ${shield_overlay}) + # Generate a derived overlay for each file, reflecting the options. + execute_process(COMMAND + ${PYTHON_EXECUTABLE} + ${GEN_SHIELD_DERIVED_OVERLAY_SCRIPT} + "${shield_overlay}" + "--derived-overlay=${derived_overlay}" + "--shield-options=${shield_opts}" + COMMAND_ERROR_IS_FATAL ANY + ) + + # Add the derived overlay file to the shield_dts_files output variable. + list(APPEND shield_dts_files "${derived_overlay}") + endif() + endforeach() + endforeach() endif() diff --git a/doc/hardware/porting/shields.rst b/doc/hardware/porting/shields.rst index 6f3dff1be5fb8..7fe55c49ed9e1 100644 --- a/doc/hardware/porting/shields.rst +++ b/doc/hardware/porting/shields.rst @@ -17,15 +17,25 @@ under :zephyr_file:`boards/shields`: .. code-block:: none boards/shields/ + ├── shield.yml ├── .overlay ├── Kconfig.shield └── Kconfig.defconfig These files provides shield configuration as follows: +* **shield.yml**: This file defines the name of the shield, its variant + information, and the information it accepts if parameterized. + The :ref:`shield_yaml_format` section for details. + * **.overlay**: This file provides a shield description in devicetree format that is merged with the board's :ref:`devicetree ` before compilation. + The shield framework provides a mechanism for tweaking shield configurations at build time. + This capability allows developers to tailor shield behavior to specific use cases, + such as adjusting connections, setting hardware parameters, or enabling multiple + instances of the same shield with distinct configurations. + The :ref:`shield_parametrization` section for details. * **Kconfig.shield**: This file defines shield Kconfig symbols that will be used for default shield configuration. To ease use with applications, @@ -48,6 +58,158 @@ to provide a device nodelabel is the form _, for instance: ... }; + +.. _shield_yaml_format: + +Shield YAML Format +****************** + +The ``shield.yml`` file is the shield schema located in each shield directory. +It defines the shield's metadata. And also parameterization options, as described in later sections. + +YAML Schema Field Descriptions +============================== + +- **shield**: + A top-level key that groups all metadata and configuration details related to the shield. + +- **name**: + The short identifier or slug name for the shield. This name is a unique reference within the build system and configurations. + +- **full\_name**: + The complete, human-readable name of the shield. It provides a detailed description, including the vendor and functionality. + +- **vendor**: + The name of the company or organization that manufactures or provides the shield. + +- **options**: + A dictionary of customizable parameters for the shield. Each option defines a configurable property using the following fields: + This is similar to the YAML properties format for defining devicetree bindings, but the difference is that + type is limited to int, boolean and string only, and the default value is required. + + - **type**: + Specifies the data type of the option. Common types include ``int``, ``boolean`` and ``string``. + This field is required. + + - **default**: + Specifies the default value assigned to the option if no explicit value is provided during configuration. + This field is required except in the boolean case. + + - **description**: + Provides a human-readable explanation of the option's purpose and functionality. + +- **variants**: + A list of shield variations, each element having the same fields as the shield, excluding the variants. + These are interpreted as overlays on the base shield definition. + + +Example shield.yml File +----------------------- + +.. code-block:: yaml + + shield: + name: example_grove_i2c + full_name: Example Grove I2C Shield + vendor: example_vendor + options: + conn: + type: string + default: "grove_i2c" + description: Specifies the shield’s connection type. + addr: + type: int + default: 0x11 + description: Defines the I2C address for the shield. + irq-gpio-pin: + type: int + default: 0 + description: Specifies the GPIO pin used for interrupts. + +.. _shield_parametrization: + +Shield Parametrization +********************** + +The ``–shield`` option in the ``west build`` command allows shield options to be appended with a key-value +format after the shield name. +Using it, you can customize how a shield interacts with your hardware. +For example, you can specify the connection type, assign specific addresses for I2C, +or configure GPIO pins for interrupts. This ensures flexibility and adaptability across +a wide range of hardware configurations. + +Specifying Parameters +===================== + +Parameters are specified as part of the ``--shield`` argument using the following syntax: + +``[@][: