mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-09-21 03:21:20 +02:00
Merge branch 'current' into beta
This commit is contained in:
commit
0f6122ec36
@ -19,6 +19,13 @@ The ESPHome native API is based on a custom TCP protocol using protocol buffers.
|
|||||||
the protocol data structure definitions here: `api.proto <https://github.com/esphome/esphome/blob/dev/esphome/components/api/api.proto>`__
|
the protocol data structure definitions here: `api.proto <https://github.com/esphome/esphome/blob/dev/esphome/components/api/api.proto>`__
|
||||||
A Python library that implements this protocol is `aioesphomeapi <https://github.com/esphome/aioesphomeapi>`__.
|
A Python library that implements this protocol is `aioesphomeapi <https://github.com/esphome/aioesphomeapi>`__.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
**Actions** were previously called **Services**. ESPHome changed the name in line with
|
||||||
|
`Home Assistant <https://developers.home-assistant.io/blog/2024/07/16/service-actions/>`__
|
||||||
|
but will continue to support YAML with ``services`` and ``homeassistant.service`` for the foreseeable future.
|
||||||
|
Documentation will only refer to **Actions**.
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
# Example configuration entry
|
# Example configuration entry
|
||||||
|
@ -8,9 +8,9 @@ Custom Binary Sensor
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Climate
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Cover
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Light Output
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Output
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -7,15 +7,13 @@ BMI160 Accelerometer/Gyroscope Sensor
|
|||||||
|
|
||||||
The ``bmi160`` sensor platform allows you to use your BMI160 Accelerometer/Gyroscope
|
The ``bmi160`` sensor platform allows you to use your BMI160 Accelerometer/Gyroscope
|
||||||
(`datasheet <https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmi160-ds000.pdf>`__,
|
(`datasheet <https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmi160-ds000.pdf>`__,
|
||||||
`SparkFun`_) sensors with
|
`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
|
||||||
ESPHome. The :ref:`I²C Bus <i2c>` is
|
sensor to work.
|
||||||
required to be set up in your configuration for this sensor to work.
|
|
||||||
|
|
||||||
This component only does some basic filtering and no calibration. Due to the complexity of
|
|
||||||
this sensor and the amount of possible configuration options, you should probably
|
|
||||||
create a custom component by copying and modifying the existing code if you want a specific
|
|
||||||
new feature. Supporting all possible use-cases would be quite hard.
|
|
||||||
|
|
||||||
|
This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
|
||||||
|
of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
|
||||||
|
by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
|
||||||
|
be quite hard.
|
||||||
|
|
||||||
.. figure:: images/bmi160-full.jpg
|
.. figure:: images/bmi160-full.jpg
|
||||||
:align: center
|
:align: center
|
||||||
|
Before Width: | Height: | Size: 3.0 KiB After Width: | Height: | Size: 3.1 KiB |
@ -8,9 +8,9 @@ Custom Sensor Component
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -7,15 +7,13 @@ MPU6050 Accelerometer/Gyroscope Sensor
|
|||||||
|
|
||||||
The ``mpu6050`` sensor platform allows you to use your MPU6050 Accelerometer/Gyroscope
|
The ``mpu6050`` sensor platform allows you to use your MPU6050 Accelerometer/Gyroscope
|
||||||
(`datasheet <https://www.invensense.com/wp-content/uploads/2015/02/MPU-6000-Datasheet1.pdf>`__,
|
(`datasheet <https://www.invensense.com/wp-content/uploads/2015/02/MPU-6000-Datasheet1.pdf>`__,
|
||||||
`SparkFun`_) sensors with
|
`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
|
||||||
ESPHome. The :ref:`I²C Bus <i2c>` is
|
sensor to work.
|
||||||
required to be set up in your configuration for this sensor to work.
|
|
||||||
|
|
||||||
This component only does some basic filtering and no calibration. Due to the complexity of
|
|
||||||
this sensor and the amount of possible configuration options, you should probably
|
|
||||||
create a custom component by copying and modifying the existing code if you want a specific
|
|
||||||
new feature. Supporting all possible use-cases would be quite hard.
|
|
||||||
|
|
||||||
|
This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
|
||||||
|
of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
|
||||||
|
by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
|
||||||
|
be quite hard.
|
||||||
|
|
||||||
.. figure:: images/mpu6050-full.jpg
|
.. figure:: images/mpu6050-full.jpg
|
||||||
:align: center
|
:align: center
|
||||||
|
@ -7,14 +7,13 @@ MPU6886 Accelerometer/Gyroscope Sensor
|
|||||||
|
|
||||||
The ``mpu6886`` sensor platform allows you to use your MPU6886 Accelerometer/Gyroscope
|
The ``mpu6886`` sensor platform allows you to use your MPU6886 Accelerometer/Gyroscope
|
||||||
(`datasheet <https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/MPU-6886-000193%2Bv1.1_GHIC_en.pdf>`__,
|
(`datasheet <https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/MPU-6886-000193%2Bv1.1_GHIC_en.pdf>`__,
|
||||||
`M5Stack`_) sensors with
|
`M5Stack`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration for this
|
||||||
ESPHome. The :ref:`I²C Bus <i2c>` is
|
sensor to work.
|
||||||
required to be set up in your configuration for this sensor to work.
|
|
||||||
|
|
||||||
This component only does some basic filtering and no calibration. Due to the complexity of
|
This component only does some basic filtering and no calibration. Due to the complexity of this sensor and the amount
|
||||||
this sensor and the amount of possible configuration options, you should probably
|
of possible configuration options, you should probably create an :doc:`external component</components/external_components>`
|
||||||
create a custom component by copying and modifying the existing code if you want a specific
|
by copying and modifying the existing code if you want a specific new feature. Supporting all possible use cases would
|
||||||
new feature. Supporting all possible use-cases would be quite hard.
|
be quite hard.
|
||||||
|
|
||||||
The MPU6886 is built-in in various M5Stack units (e.g., M5Stick C, ATOM Matrix or M5Stack Core2).
|
The MPU6886 is built-in in various M5Stack units (e.g., M5Stick C, ATOM Matrix or M5Stack Core2).
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Switch
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom Text Sensor
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Generic Custom Component
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom I²C Device
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom SPI Device
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -8,9 +8,9 @@ Custom UART Device
|
|||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
|
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
|
||||||
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
|
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
|
||||||
:doc:`/components/external_components`.
|
it into your configuration with :doc:`/components/external_components`.
|
||||||
|
|
||||||
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
|
||||||
|
|
||||||
|
@ -647,6 +647,8 @@ The C++ part of the codebase is what's actually running on the microcontroller;
|
|||||||
of the codebase should first set up the communication interface to a sensor/component/etc. and then communicate with
|
of the codebase should first set up the communication interface to a sensor/component/etc. and then communicate with
|
||||||
the ESPHome core via the defined interfaces (like ``Sensor``, ``BinarySensor`` and ``Switch``, among others).
|
the ESPHome core via the defined interfaces (like ``Sensor``, ``BinarySensor`` and ``Switch``, among others).
|
||||||
|
|
||||||
|
.. _directory_structure:
|
||||||
|
|
||||||
Directory Structure
|
Directory Structure
|
||||||
*******************
|
*******************
|
||||||
|
|
||||||
@ -742,6 +744,8 @@ A few notes on validation:
|
|||||||
obscure shorthand. As an example, ``scrn_btn_inpt`` is indeed shorter but more difficult to understand, particularly
|
obscure shorthand. As an example, ``scrn_btn_inpt`` is indeed shorter but more difficult to understand, particularly
|
||||||
for new users; avoid naming keys and variables in this way.
|
for new users; avoid naming keys and variables in this way.
|
||||||
|
|
||||||
|
.. _code_generation:
|
||||||
|
|
||||||
Code Generation
|
Code Generation
|
||||||
***************
|
***************
|
||||||
|
|
||||||
@ -782,6 +786,8 @@ Next, there's a special method - ``cg.add`` - that you will often use. ``cg.add(
|
|||||||
C++ declared in the parentheses of ``cg.add()`` will be added to the generated code. Note that, if you do not call
|
C++ declared in the parentheses of ``cg.add()`` will be added to the generated code. Note that, if you do not call
|
||||||
"add" to insert a piece of code explicitly, it will not be added to the ``main.cpp`` file!
|
"add" to insert a piece of code explicitly, it will not be added to the ``main.cpp`` file!
|
||||||
|
|
||||||
|
.. _runtime:
|
||||||
|
|
||||||
Runtime
|
Runtime
|
||||||
*******
|
*******
|
||||||
|
|
||||||
@ -832,6 +838,66 @@ it then attempts to read back the measurement from the sensor.
|
|||||||
For any :apiclass:`Component` (which is nearly everything), the well-known ``set_timeout`` method is also available;
|
For any :apiclass:`Component` (which is nearly everything), the well-known ``set_timeout`` method is also available;
|
||||||
this can be a handy alternative to implemeting a state machine.
|
this can be a handy alternative to implemeting a state machine.
|
||||||
|
|
||||||
|
.. _a_note_about_custom_components:
|
||||||
|
|
||||||
|
A Note About Custom Components
|
||||||
|
******************************
|
||||||
|
|
||||||
|
*"I read that custom components are deprecated...so now what do I do???"*
|
||||||
|
|
||||||
|
ESPHome's "custom component" mechanism is a holdover from Home Assistant's feature by the same name. It existed before
|
||||||
|
:doc:`/components/external_components` and offered a way to "hack in" support for devices which were not officially
|
||||||
|
supported by ESPHome.
|
||||||
|
|
||||||
|
ESPHome has since deprecated this feature in favor of :doc:`/components/external_components` for several reasons:
|
||||||
|
|
||||||
|
- Custom components are very fragile:
|
||||||
|
|
||||||
|
- There is no validation. You can easily configure a custom component incorrectly and there will be no warning.
|
||||||
|
- Types are not checked. You might incorrectly pass a variable of an incorrect type or unit to a custom component
|
||||||
|
resulting in compiler errors, unexpected behavior and/or crashes.
|
||||||
|
- Custom components are difficult to use. You have to manually copy all of the custom component's files into *just
|
||||||
|
the right location* on your system or else you will receive compiler errors and the component won't work.
|
||||||
|
- Custom components almost always require C++ code changes when you want them to work even *slightly* differently
|
||||||
|
than the original author intended.
|
||||||
|
|
||||||
|
- :doc:`/components/external_components` initially require a bit more effort by the developer but are ultimately more
|
||||||
|
robust and easier to use and share:
|
||||||
|
|
||||||
|
- Just like any other ESPHome component/platform:
|
||||||
|
|
||||||
|
- They are configured entirely in YAML.
|
||||||
|
- Their YAML configuration is validated.
|
||||||
|
|
||||||
|
- They do not require the user to:
|
||||||
|
|
||||||
|
- Manually copy files onto their system.
|
||||||
|
- Touch/edit any C++ code.
|
||||||
|
|
||||||
|
- They tend to be more flexible since they are configured in YAML (as opposed to editing C++ code to make changes).
|
||||||
|
|
||||||
|
**So what is the difference between custom components and** :doc:`/components/external_components`?
|
||||||
|
|
||||||
|
Custom components are typically (more or less) just the :ref:`runtime` part of an ESPHome component/platform. On the
|
||||||
|
other hand, :doc:`/components/external_components` are just like any other ESPHome component -- the only difference is
|
||||||
|
that they are *external* in the sense that they are not "officially" a part of ESPHome.
|
||||||
|
|
||||||
|
In terms of implementation, custom components just lack the Python part of an ESPHome component, specifically:
|
||||||
|
|
||||||
|
- :ref:`config_validation`
|
||||||
|
- :ref:`code_generation`
|
||||||
|
|
||||||
|
As such, most custom components can be made into :doc:`/components/external_components` simply by adding the required
|
||||||
|
Python parts to make the custom component into a proper, complete ESPHome component.
|
||||||
|
|
||||||
|
We encourage all custom component developers to extend their custom component(s) into proper
|
||||||
|
:doc:`/components/external_components`; doing so will make your custom component easier to share and use. As you do so,
|
||||||
|
be sure to have a look at the the :ref:`contributing_to_esphome` section above as it walks through ESPHome (component)
|
||||||
|
architecture. In addition, it's often helpful to take a look at other, similar
|
||||||
|
`components <https://github.com/esphome/esphome/tree/dev/esphome/components>`__ and adapt them to fit the needs of your
|
||||||
|
custom component. For common hardware devices such as :doc:`sensors</components/sensor/index>`, this is often a
|
||||||
|
reasonably trivial exercise and `we are happy to help you along! <https://discord.gg/KhAMKrd>`__
|
||||||
|
|
||||||
Extras
|
Extras
|
||||||
******
|
******
|
||||||
|
|
||||||
|
@ -1128,7 +1128,7 @@ Miscellaneous Components
|
|||||||
Custom Components
|
Custom Components
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
**Note: Custom Components are deprecated in favor of** :doc:`components/external_components`!
|
**Note:** :ref:`Custom Components are deprecated<a_note_about_custom_components>` in favor of :doc:`components/external_components`!
|
||||||
|
|
||||||
.. imgtable::
|
.. imgtable::
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user