mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-25 17:17:54 +01:00
Some clarification added to external components. (#1165)
Co-authored-by: Maurice Makaay <mmakaay1@xs4all.net>
This commit is contained in:
parent
1267c2a26d
commit
37a67fd1aa
@ -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
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user