diff --git a/components/api.rst b/components/api.rst index 398c46b14..530130265 100644 --- a/components/api.rst +++ b/components/api.rst @@ -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 `__ A Python library that implements this protocol is `aioesphomeapi `__. +.. note:: + + **Actions** were previously called **Services**. ESPHome changed the name in line with + `Home Assistant `__ + but will continue to support YAML with ``services`` and ``homeassistant.service`` for the foreseeable future. + Documentation will only refer to **Actions**. + .. code-block:: yaml # Example configuration entry diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst index f983584cb..64dff1375 100644 --- a/components/binary_sensor/custom.rst +++ b/components/binary_sensor/custom.rst @@ -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`, 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`. diff --git a/components/climate/custom.rst b/components/climate/custom.rst index 1544fa9f1..e84d2a12a 100644 --- a/components/climate/custom.rst +++ b/components/climate/custom.rst @@ -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`, 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`. diff --git a/components/cover/custom.rst b/components/cover/custom.rst index c623a54f9..6c73147d8 100644 --- a/components/cover/custom.rst +++ b/components/cover/custom.rst @@ -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`, 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`. diff --git a/components/light/custom.rst b/components/light/custom.rst index 0ebf96564..841a4b860 100644 --- a/components/light/custom.rst +++ b/components/light/custom.rst @@ -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`, 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`. diff --git a/components/output/custom.rst b/components/output/custom.rst index ad37e1bf0..7df27556c 100644 --- a/components/output/custom.rst +++ b/components/output/custom.rst @@ -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`, 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`. diff --git a/components/sensor/bmi160.rst b/components/sensor/bmi160.rst index 0b55c6143..7b5c4cfe1 100644 --- a/components/sensor/bmi160.rst +++ b/components/sensor/bmi160.rst @@ -7,15 +7,13 @@ BMI160 Accelerometer/Gyroscope Sensor The ``bmi160`` sensor platform allows you to use your BMI160 Accelerometer/Gyroscope (`datasheet `__, -`SparkFun`_) sensors with -ESPHome. The :ref:`I²C Bus ` 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 ` 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` +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 diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst index ad52cbeb5..f772b449c 100644 --- a/components/sensor/custom.rst +++ b/components/sensor/custom.rst @@ -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`, 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`. diff --git a/components/sensor/mpu6050.rst b/components/sensor/mpu6050.rst index 101b07f90..a15ea330e 100644 --- a/components/sensor/mpu6050.rst +++ b/components/sensor/mpu6050.rst @@ -7,15 +7,13 @@ MPU6050 Accelerometer/Gyroscope Sensor The ``mpu6050`` sensor platform allows you to use your MPU6050 Accelerometer/Gyroscope (`datasheet `__, -`SparkFun`_) sensors with -ESPHome. The :ref:`I²C Bus ` 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 ` 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` +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 diff --git a/components/sensor/mpu6886.rst b/components/sensor/mpu6886.rst index 0714d779e..b0cff1450 100644 --- a/components/sensor/mpu6886.rst +++ b/components/sensor/mpu6886.rst @@ -7,14 +7,13 @@ MPU6886 Accelerometer/Gyroscope Sensor The ``mpu6886`` sensor platform allows you to use your MPU6886 Accelerometer/Gyroscope (`datasheet `__, -`M5Stack`_) sensors with -ESPHome. The :ref:`I²C Bus ` is -required to be set up in your configuration for this sensor to work. +`M5Stack`_) sensors with ESPHome. The :ref:`I²C Bus ` 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` +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). diff --git a/components/switch/custom.rst b/components/switch/custom.rst index 5e0823171..7d69aaca8 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -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`, 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`. diff --git a/components/text_sensor/custom.rst b/components/text_sensor/custom.rst index f0606e19d..05486e70b 100644 --- a/components/text_sensor/custom.rst +++ b/components/text_sensor/custom.rst @@ -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`, 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`. diff --git a/custom/custom_component.rst b/custom/custom_component.rst index a87dcb104..0eeeab1a3 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -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`, 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`. diff --git a/custom/i2c.rst b/custom/i2c.rst index 87940b8be..1eb79b94a 100644 --- a/custom/i2c.rst +++ b/custom/i2c.rst @@ -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`, 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`. diff --git a/custom/spi.rst b/custom/spi.rst index 6407d1d58..eff5fb34b 100644 --- a/custom/spi.rst +++ b/custom/spi.rst @@ -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`, 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`. diff --git a/custom/uart.rst b/custom/uart.rst index c4426cc2d..22c2b8836 100644 --- a/custom/uart.rst +++ b/custom/uart.rst @@ -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`, 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`. diff --git a/guides/contributing.rst b/guides/contributing.rst index f66c5a511..ab7598ff7 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -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 `__ and adapt them to fit the needs of your +custom component. For common hardware devices such as :doc:`sensors`, this is often a +reasonably trivial exercise and `we are happy to help you along! `__ + Extras ****** diff --git a/index.rst b/index.rst index 192a61bc6..fb936ba97 100644 --- a/index.rst +++ b/index.rst @@ -1128,7 +1128,7 @@ Miscellaneous Components Custom Components ----------------- -**Note: Custom Components are deprecated in favor of** :doc:`components/external_components`! +**Note:** :ref:`Custom Components are deprecated` in favor of :doc:`components/external_components`! .. imgtable::