mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-10-31 08:31:29 +01:00
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:
parent
e6b2fbbddc
commit
eb950033a8
166
components/external_components.rst
Normal file
166
components/external_components.rst
Normal 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`
|
@ -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
|
||||
********************
|
||||
|
1
images/external_components.svg
Normal file
1
images/external_components.svg
Normal 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 |
@ -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
|
||||
-----------------
|
||||
|
Loading…
Reference in New Issue
Block a user