add External components docs (#1107)

* Add external_components

* fixes

* fix indent

* fix misplaced directive

* add full config before shorthands

* adding a bit more info

* update contributing use external components
This commit is contained in:
Guillermo Ruffino 2021-05-07 15:02:08 -03:00 committed by GitHub
parent e6b2fbbddc
commit eb950033a8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 173 additions and 4 deletions

View File

@ -0,0 +1,166 @@
External Components
===================
.. seo::
:description: Instructions for setting up ESPHome External Components.
:keywords: External, Custom, Components, ESPHome
You can easily import community components using the external components feature. Bundled components
can be overridden using this feature.
.. code-block:: yaml
external_components:
# use rtttl and dfplayer from ESPHome's dev branch in GitHub
- source:
type: git
url: https://github.com/esphome/esphome
ref: dev
components: [ rtttl, dfplayer ]
# equivalent shorthand for GitHub
- source: github://esphome/esphome@dev
components: [ rtttl ]
Configuration variables:
- **source**: The location of the components you want to retrieve. See :ref:`external-components_local`
and :ref:`external-components_git`.
- **type** (**Required**): Repository type. One of ``local``, ``git``.
git options:
- **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.
local options:
- **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.
Defaults to ``all``.
- **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``.
.. _external-components_local:
Local
-----
You can specify a local path for the external components, this is most useful if you want to manually
control the origin of the files.
.. code-block:: yaml
external_components:
source:
path: /copied_components
# shorthand
external_components:
source: my_components
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
is.
.. _external-components_git:
Git
---
Retrieving components from git is the easiest way to use components not included in ESPHome by default.
The source components should be inside a ``components`` folder or inside an ``esphome/components``
folder. The latter makes sharing a component from a forked ESPHome repository easier.
Example of git repositories
***************************
For repositories where you share one or a few components:
.. code-block:: text
components
  ├── my_component1
  │   ├── __init__.py
  │   ├── component1.cpp
  │   ├── component1.h
  │   └── sensor.py
  └── my_component2
     ├── __init__.py
     ├── component2.cpp
     ├── component2.h
     └── switch.py
example_component1.yaml <- not required but recommended
README.md
or, this structure is also supported, which makes handy to share components from a **forked** ESPHome
repository:
.. code-block:: text
esphome
├── components
│   ├── my_component1
│   │   ├── __init__.py
│   │   ├── component1.cpp
│   │   ├── component1.h
│   │   └── sensor.py
│   ├── my_component2
│   │   ├── __init__.py
│   │   ├── component2.cpp
│   │   ├── component2.h
│   │   └── switch.py
│  ...
...
Http git repositories in general are supported with this configuration:
.. code-block:: yaml
external_components:
source:
type: git
url: http://repository_url/
ref: branch_or_tag
The source fields accepts a short hand **github://** resource:
.. code-block:: yaml
external_components:
# shorthand
source: github://<user or org>/<repository name>[@<branch or tag>]
Under the hood, during validation, ESPHome will clone the git repository into the hidden ``.esphome``
folder and components will then be loaded from this local copy. The local path of the cloned repository
varies per repository name and ref name, so repositories with different refs are considered different
repositories and updated independently.
.. _external-components_refresh:
Refresh
*******
Components are initially cloned into a cache directory, then the repository is checked for updates
(via *git pull*) after the ``refresh:`` time passes since last check.
You can make ESPHome check the repository every time by setting this option to ``0s``, however since
ESPHome is validating the configuration continuously while using the dashboard or the vscode extension,
it is not recommended to set this value to less than a few minutes to avoid validation slow down and
excessive repository checks.
Likewise, you can set this setting to ``never`` and ESPHome will never
**update** the repository, useful e.g. when ``ref`` points to a **tag**.
See Also
--------
- :ghedit:`Edit`

View File

@ -414,10 +414,11 @@ by the integration developer.
.. note::
Additionally, ESPHome has a ``custom_components`` mechanism like
`Home Assistant does <https://developers.home-assistant.io/docs/creating_component_index>`__.
So for testing you can also create a new ``custom_components`` folder inside of your ESPHome
config folder and create new integrations in there.
For testing you can use :doc:`/components/external_components`.
ESPHome also has a ``custom_components`` mechanism like `Home Assistant does
<https://developers.home-assistant.io/docs/creating_component_index>`__. However this is
discouraged in favor of :doc:`/components/external_components`.
2. Config Validation
********************

View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24" width="24"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M3.9 12c0-1.7 1.4-3.1 3.1-3.1h4V7H7c-2.8 0-5 2.2-5 5s2.2 5 5 5h4v-1.9H7c-1.7 0-3.1-1.4-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.7 0 3.1 1.4 3.1 3.1s-1.4 3.1-3.1 3.1h-4V17h4c2.8 0 5-2.2 5-5s-2.2-5-5-5z"/></svg>

After

Width:  |  Height:  |  Size: 339 B

View File

@ -85,6 +85,7 @@ Core Components
Native API, components/api, server-network.svg
Power Supply, components/power_supply, power.svg
Deep Sleep, components/deep_sleep, hotel.svg
External Components, components/external_components, external_components.svg
Sensor Components
-----------------