Add a section about custom component deprecation (#4247)

This commit is contained in:
Keith Burzinski 2024-09-14 01:41:18 -05:00 committed by GitHub
parent 922ec42bf4
commit 02d9af543c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 121 additions and 60 deletions

View File

@ -8,9 +8,9 @@ Custom Binary Sensor
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom Climate
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom Cover
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom Light Output
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom Output
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -7,15 +7,13 @@ BMI160 Accelerometer/Gyroscope Sensor
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>`__,
`SparkFun`_) sensors with
ESPHome. The :ref:`I²C Bus <i2c>` is
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.
`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is 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 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
:align: center

Before

Width:  |  Height:  |  Size: 3.0 KiB

After

Width:  |  Height:  |  Size: 3.1 KiB

View File

@ -8,9 +8,9 @@ Custom Sensor Component
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -7,15 +7,13 @@ MPU6050 Accelerometer/Gyroscope Sensor
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>`__,
`SparkFun`_) sensors with
ESPHome. The :ref:`I²C Bus <i2c>` is
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.
`SparkFun`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is 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 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
:align: center

View File

@ -7,14 +7,13 @@ MPU6886 Accelerometer/Gyroscope Sensor
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>`__,
`M5Stack`_) sensors with
ESPHome. The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work.
`M5Stack`_) sensors with ESPHome. The :ref:`I²C Bus <i2c>` is 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.
The MPU6886 is built-in in various M5Stack units (e.g., M5Stick C, ATOM Matrix or M5Stack Core2).

View File

@ -8,9 +8,9 @@ Custom Switch
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom Text Sensor
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Generic Custom Component
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom I²C Device
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom SPI Device
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -8,9 +8,9 @@ Custom UART Device
.. warning::
Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
:doc:`/components/external_components`.
:ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
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`.

View File

@ -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
the ESPHome core via the defined interfaces (like ``Sensor``, ``BinarySensor`` and ``Switch``, among others).
.. _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
for new users; avoid naming keys and variables in this way.
.. _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
"add" to insert a piece of code explicitly, it will not be added to the ``main.cpp`` file!
.. _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;
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
******

View File

@ -1120,7 +1120,7 @@ Miscellaneous 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::