Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-01-09 19:48:25 +01:00
Code Issues Projects Releases Wiki Activity

Add deadline for custom components (#4446)

Browse Source
This commit is contained in:
Keith Burzinski 2024-11-18 01:59:11 -06:00 committed by GitHub
parent 075392ddba
commit 278196ace0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 38 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/binary_sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Binary Sensor
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/climate/custom.rst
View File

@ -9,8 +9,8 @@ Custom Climate
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/cover/custom.rst
View File

@ -9,8 +9,8 @@ Custom Cover
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/light/custom.rst
View File

@ -9,8 +9,8 @@ Custom Light Output
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/output/custom.rst
View File

@ -9,8 +9,8 @@ Custom Output
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Sensor Component
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/switch/custom.rst
View File

@ -9,8 +9,8 @@ Custom Switch
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
components/text_sensor/custom.rst
View File

@ -9,8 +9,8 @@ Custom Text Sensor
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
custom/custom_component.rst
View File

@ -9,8 +9,8 @@ Generic Custom Component
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
custom/i2c.rst
View File

@ -9,8 +9,8 @@ Custom I²C Device
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
custom/spi.rst
View File

@ -9,8 +9,8 @@ Custom SPI Device
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

4
custom/uart.rst
View File

@ -9,8 +9,8 @@ Custom UART Device
.. warning::
: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`.
will be removed from ESPHome in the ``2025.1.0`` 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`.

19
guides/contributing.rst
View File

@ -1017,7 +1017,10 @@ ESPHome's "custom component" mechanism is a holdover from Home Assistant's featu
: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:
Why are Custom Components Deprecated?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are several reasons for this change.
- Custom components are very fragile:
@ -1026,11 +1029,13 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
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.
- Custom components lack flexibility and almost always require C++ code changes when you want them to work even
*slightly* differently than the original author intended/designed. For example, a simple change of input units
(``cm`` to ``m``, for example) could require significant changes to the C++ code, depending on how the original
author designed the custom component.
- :doc:`/components/external_components` initially require a bit more effort by the developer but are ultimately more
robust and easier to use and share:
robust and are easier to use and share:
- Just like any other ESPHome component/platform:
@ -1044,7 +1049,8 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
- 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`?
What's the Difference?
^^^^^^^^^^^^^^^^^^^^^^
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
@ -1058,6 +1064,9 @@ In terms of implementation, custom components just lack the Python part of an ES
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.
What's Next?
^^^^^^^^^^^^
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)