diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst index 64dff13755..40d56a2499 100644 --- a/components/binary_sensor/custom.rst +++ b/components/binary_sensor/custom.rst @@ -9,8 +9,8 @@ Custom Binary Sensor .. warning:: :ref:`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`. + 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`. diff --git a/components/climate/custom.rst b/components/climate/custom.rst index e84d2a12ad..6fece0e1b9 100644 --- a/components/climate/custom.rst +++ b/components/climate/custom.rst @@ -9,8 +9,8 @@ Custom Climate .. warning:: :ref:`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`. + 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`. diff --git a/components/cover/custom.rst b/components/cover/custom.rst index 6c73147d8c..413333769d 100644 --- a/components/cover/custom.rst +++ b/components/cover/custom.rst @@ -9,8 +9,8 @@ Custom Cover .. warning:: :ref:`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`. + 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`. diff --git a/components/light/custom.rst b/components/light/custom.rst index 841a4b8609..748d6855f6 100644 --- a/components/light/custom.rst +++ b/components/light/custom.rst @@ -9,8 +9,8 @@ Custom Light Output .. warning:: :ref:`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`. + 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`. diff --git a/components/output/custom.rst b/components/output/custom.rst index 7df27556cf..631e61627c 100644 --- a/components/output/custom.rst +++ b/components/output/custom.rst @@ -9,8 +9,8 @@ Custom Output .. warning:: :ref:`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`. + 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`. diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst index f772b449ca..21d4edb6fd 100644 --- a/components/sensor/custom.rst +++ b/components/sensor/custom.rst @@ -9,8 +9,8 @@ Custom Sensor Component .. warning:: :ref:`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`. + 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`. diff --git a/components/switch/custom.rst b/components/switch/custom.rst index 7d69aaca89..984bc5f7f6 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -9,8 +9,8 @@ Custom Switch .. warning:: :ref:`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`. + 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`. diff --git a/components/text_sensor/custom.rst b/components/text_sensor/custom.rst index 05486e70bd..0823d708f5 100644 --- a/components/text_sensor/custom.rst +++ b/components/text_sensor/custom.rst @@ -9,8 +9,8 @@ Custom Text Sensor .. warning:: :ref:`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`. + 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`. diff --git a/custom/custom_component.rst b/custom/custom_component.rst index 0eeeab1a38..012c0132ef 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -9,8 +9,8 @@ Generic Custom Component .. warning:: :ref:`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`. + 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`. diff --git a/custom/i2c.rst b/custom/i2c.rst index 1eb79b94a3..cff3802110 100644 --- a/custom/i2c.rst +++ b/custom/i2c.rst @@ -9,8 +9,8 @@ Custom I²C Device .. warning:: :ref:`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`. + 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`. diff --git a/custom/spi.rst b/custom/spi.rst index eff5fb34b1..a004dc76b9 100644 --- a/custom/spi.rst +++ b/custom/spi.rst @@ -9,8 +9,8 @@ Custom SPI Device .. warning:: :ref:`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`. + 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`. diff --git a/custom/uart.rst b/custom/uart.rst index 22c2b8836f..6abfee7eb1 100644 --- a/custom/uart.rst +++ b/custom/uart.rst @@ -9,8 +9,8 @@ Custom UART Device .. warning:: :ref:`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`. + 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`. diff --git a/guides/contributing.rst b/guides/contributing.rst index fb1efcffec..50ac01446f 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -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)