Some clarification added to external components. (#1165)

Co-authored-by: Maurice Makaay <mmakaay1@xs4all.net>
This commit is contained in:
Maurice Makaay 2021-05-13 13:05:54 +02:00 committed by Jesse Hills
parent 1267c2a26d
commit 37a67fd1aa
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A

View File

@ -5,8 +5,8 @@ External Components
:description: Instructions for setting up ESPHome External Components. :description: Instructions for setting up ESPHome External Components.
:keywords: External, Custom, Components, ESPHome :keywords: External, Custom, Components, ESPHome
You can easily import community components using the external components feature. Bundled components You can easily import community or personal components using the external components feature.
can be overridden using this feature. Bundled components can be overridden using this feature.
.. code-block:: yaml .. code-block:: yaml
@ -22,6 +22,11 @@ can be overridden using this feature.
- source: github://esphome/esphome@dev - source: github://esphome/esphome@dev
components: [ rtttl ] components: [ rtttl ]
# use all components from a local folder
- source:
type: local
path: my_components
Configuration variables: Configuration variables:
- **source**: The location of the components you want to retrieve. See :ref:`external-components_local` - **source**: The location of the components you want to retrieve. See :ref:`external-components_local`
@ -31,15 +36,15 @@ Configuration variables:
git options: git options:
- **url** (**Required**, url): Http git repository url. See :ref:`external-components_git`. - **url** (**Required**, url): HTTP git repository url. See :ref:`external-components_git`.
- **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used. - **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used.
local options: local options:
- **path** (**Required**): Path to use when using local components. See :ref:`external-components_local`. - **path** (**Required**): Path to use when using local components. See :ref:`external-components_local`.
- **components** (*Optional*, list): The list of components to retrieve from the external source. - **components** (*Optional*, list): The list of components to use from the external source.
Defaults to ``all``. By default, all available components are used.
- **refresh** (*Optional*, :ref:`time <config-time>`): The interval the source will be checked. Has no - **refresh** (*Optional*, :ref:`time <config-time>`): The interval the source will be checked. Has no
effect on ``local``. See :ref:`external-components_refresh`. for more info. Defaults to ``1day``. effect on ``local``. See :ref:`external-components_refresh`. for more info. Defaults to ``1day``.
@ -50,26 +55,48 @@ Configuration variables:
Local Local
----- -----
You can specify a local path for the external components, this is most useful if you want to manually You can specify a local path containing external components. This is most useful when developing a
control the origin of the files. component or if you want to manually control the origin of the files.
.. code-block:: yaml .. code-block:: yaml
external_components: external_components:
source: - source:
path: /copied_components path: /copied_components
# shorthand # shorthand
external_components: external_components:
source: my_components - source: my_components
Notice that relative paths are supported, so you can enter ``my_components`` as the source path and then Notice that relative paths are supported, so you can enter ``my_components`` as the source path and then
ESPHome will load components from a ``my_components`` folder in the same folder where your YAML configuration ESPHome will load components from a ``my_components`` folder in the same folder where your YAML configuration
is. is.
Example of local components
***************************
.. _external-components_git: Given the above example of ``my_components``, the folder structure must look like:
.. code-block:: text
<CONFIG_DIR>
├── node1.yaml
├── node2.yaml
└── my_components
├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
.. _external-components_git:
Git Git
--- ---
@ -120,7 +147,7 @@ repository:
│  ... │  ...
... ...
Http git repositories in general are supported with this configuration: HTTP git repositories in general are supported with this configuration:
.. code-block:: yaml .. code-block:: yaml
@ -130,7 +157,7 @@ Http git repositories in general are supported with this configuration:
url: http://repository_url/ url: http://repository_url/
ref: branch_or_tag ref: branch_or_tag
The source fields accepts a short hand **github://** resource: The source field accepts a short hand **github://** resource:
.. code-block:: yaml .. code-block:: yaml