From ca96dd49e192c40b37e4829cdf56c3eaef7d8bcc Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Tue, 7 May 2024 00:16:56 -0500 Subject: [PATCH] Change "integration" -> "component", minor copy fixes (#3790) --- components/binary_sensor/custom.rst | 28 +++--- components/climate/custom.rst | 26 ++++-- components/copy.rst | 8 +- components/cover/custom.rst | 29 +++--- components/cover/tuya.rst | 2 +- components/demo.rst | 12 +-- components/dfplayer.rst | 5 +- components/display/index.rst | 2 +- components/display/lcd_display.rst | 8 +- components/display/max7219.rst | 4 +- components/display/max7219digit.rst | 4 +- components/display/waveshare_epaper.rst | 2 +- .../display_menu/graphical_display_menu.rst | 2 +- components/display_menu/index.rst | 6 +- components/display_menu/lcd_menu.rst | 2 +- components/fingerprint_grow.rst | 2 +- components/gps.rst | 4 +- components/light/custom.rst | 26 ++++-- components/light/neopixelbus.rst | 2 +- components/micronova.rst | 2 +- components/mqtt.rst | 5 +- components/output/ac_dimmer.rst | 7 +- components/output/custom.rst | 22 +++-- components/output/sigma_delta_output.rst | 2 +- components/sensor/ads1115.rst | 2 +- components/sensor/airthings_ble.rst | 3 +- components/sensor/as3935.rst | 2 +- components/sensor/bl0940.rst | 4 +- components/sensor/bl0942.rst | 4 +- components/sensor/ccs811.rst | 2 +- components/sensor/cse7766.rst | 2 +- components/sensor/custom.rst | 25 +++-- components/sensor/dsmr.rst | 2 +- components/sensor/growatt_solar.rst | 2 +- components/sensor/havells_solar.rst | 2 +- components/sensor/hlw8012.rst | 8 +- components/sensor/inkbird_ibsth1_mini.rst | 2 +- components/sensor/mcp3204.rst | 7 +- components/sensor/mmc5983.rst | 3 +- components/sensor/mopeka_pro_check.rst | 2 +- components/sensor/mopeka_std_check.rst | 2 +- components/sensor/mqtt_subscribe.rst | 2 +- components/sensor/pulse_meter.rst | 2 +- components/sensor/pzem004t.rst | 2 +- components/sensor/pzemac.rst | 2 +- components/sensor/pzemdc.rst | 2 +- components/sensor/ruuvitag.rst | 2 +- components/sensor/sdm_meter.rst | 2 +- components/sensor/selec_meter.rst | 2 +- components/sensor/smt100.rst | 6 +- components/servo.rst | 2 +- components/switch/custom.rst | 26 ++++-- components/text_sensor/custom.rst | 28 +++--- components/text_sensor/mqtt_subscribe.rst | 2 +- components/tm1651.rst | 6 +- custom/custom_component.rst | 27 ++++-- custom/i2c.rst | 20 ++-- custom/spi.rst | 20 ++-- custom/uart.rst | 20 ++-- guides/contributing.rst | 28 +++--- guides/faq.rst | 93 +++++++++++++------ 61 files changed, 343 insertions(+), 237 deletions(-) diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst index d2ee55fdc..f983584cb 100644 --- a/components/binary_sensor/custom.rst +++ b/components/binary_sensor/custom.rst @@ -1,22 +1,28 @@ Custom Binary Sensor ==================== +.. seo:: + :description: Instructions for setting up Custom C++ binary sensors with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom binary sensors in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here and binary sensors are very similar -to sensors internally. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom binary sensors in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here and binary +sensors are very similar to sensors internally. The example below is an example of a custom binary sensor; this custom sensor is essentially the same as the gpio binary sensor. diff --git a/components/climate/custom.rst b/components/climate/custom.rst index e4d86f19e..1544fa9f1 100644 --- a/components/climate/custom.rst +++ b/components/climate/custom.rst @@ -1,21 +1,27 @@ Custom Climate ============== +.. seo:: + :description: Instructions for setting up Custom C++ climate components with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom climate devices in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom climate devices in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. The example below is an example of a custom climate device - all climate devices must override two methods (:apiclass:`Climate `): diff --git a/components/copy.rst b/components/copy.rst index 93f21c6d4..5cc7191c8 100644 --- a/components/copy.rst +++ b/components/copy.rst @@ -1,11 +1,11 @@ -Copy Integration -================ +Copy Component +============== .. seo:: - :description: Instructions for setting up the copy integration in ESPHome + :description: Instructions for setting up the copy component in ESPHome :image: content-copy.svg -The ``copy`` integration can be used to copy an existing component (like a sensor, switch, etc.) +The ``copy`` component can be used to copy an existing component (like a sensor, switch, etc.) and create a duplicate mirroring the source's state and forwarding actions such as turning on to the source. For each of the supported platforms, the configuration consists of the required configuration diff --git a/components/cover/custom.rst b/components/cover/custom.rst index 4b49dbc5c..c623a54f9 100644 --- a/components/cover/custom.rst +++ b/components/cover/custom.rst @@ -1,24 +1,29 @@ Custom Cover ============ +.. seo:: + :description: Instructions for setting up Custom C++ covers with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom covers in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. -The example below is an example of a custom cover - all covers must override -two methods: +This component can be used to create custom covers in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. + +The example below is an example of a custom cover - all covers must override two methods: - ``get_traits``: This should return a :apiclass:`CoverTraits ` object representing the capabilities of the cover. diff --git a/components/cover/tuya.rst b/components/cover/tuya.rst index 2293cdd63..917b87545 100644 --- a/components/cover/tuya.rst +++ b/components/cover/tuya.rst @@ -45,7 +45,7 @@ Configuration variables: Supported devices ----------------- -Tuya cover devices known to be supported by this integration: +Tuya cover devices known to be supported by this component: - Tuya ``M515EGWT`` (motor for bead chain roller blinds) diff --git a/components/demo.rst b/components/demo.rst index faccce99f..65eef4b51 100644 --- a/components/demo.rst +++ b/components/demo.rst @@ -1,12 +1,12 @@ -Demo Integration -================ +Demo Component +============== .. seo:: - :description: Instructions for setting up the demo integration in ESPHome + :description: Instructions for setting up the demo component in ESPHome :image: description.svg -The ``demo`` integration can be used for testing to generate sample instances of many -different integrations (sensors, lights, ...) +The ``demo`` component can be used for testing to generate sample instances of many +different components (sensors, lights, ...) .. figure:: images/demo-ui.png :align: center @@ -20,7 +20,7 @@ different integrations (sensors, lights, ...) Configuration variables: ------------------------ -This integration has no configuration variables +This component has no configuration variables See Also -------- diff --git a/components/dfplayer.rst b/components/dfplayer.rst index 9b2f5e655..fadc1c232 100644 --- a/components/dfplayer.rst +++ b/components/dfplayer.rst @@ -2,7 +2,7 @@ DF-Player mini ============== .. seo:: - :description: Instructions for setting up DF Player Mini integration in ESPHome. + :description: Instructions for setting up DF Player Mini component in ESPHome. :image: dfplayer.svg The ``dfplayer`` (`datasheet `__), component @@ -14,8 +14,7 @@ allows you to play sound and music stored in an SD card or USB flash drive. DF-Player mini Module. -For this integration to work you need to have set up a :ref:`UART bus ` -in your configuration. +For this component to work you need to have set up a :ref:`UART bus ` in your configuration. Overview -------- diff --git a/components/display/index.rst b/components/display/index.rst index d6f443eba..c9b39e072 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -2,7 +2,7 @@ Display Component ================= .. seo:: - :description: Instructions for setting up the display integration. + :description: Instructions for setting up the display component. :image: folder-open.svg The ``display`` component houses ESPHome's powerful rendering and display diff --git a/components/display/lcd_display.rst b/components/display/lcd_display.rst index 005de6c4c..530b13b23 100644 --- a/components/display/lcd_display.rst +++ b/components/display/lcd_display.rst @@ -2,12 +2,12 @@ Character-Based LCD Display =========================== .. seo:: - :description: Instructions for setting up character-based HD44780 LCD displays. + :description: Instructions for setting up character-based HD44780 LCDs. :image: lcd.jpg -The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCD displays -with ESPHome. This integration is only for LCD displays that display individual characters on a screen -(usually 8-40 columns and 2-4 rows), and not for LCD displays that can control each pixel individually. +The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCDs +with ESPHome. This component is only for LCDs that display individual characters on a screen +(usually 8-40 columns and 2-4 rows), and not for LCDs that can control each pixel individually. .. figure:: images/lcd-hello_world.jpg :align: center diff --git a/components/display/max7219.rst b/components/display/max7219.rst index ad1b1c6c5..11e069f1c 100644 --- a/components/display/max7219.rst +++ b/components/display/max7219.rst @@ -8,7 +8,7 @@ MAX7219 7-Segment Display The ``max7219`` display platform allows you to use MAX7219 7-segment display drivers ( `datasheet `__, `hobbycomponents `__) -with ESPHome. Please note that this integration is *only* for 7-segment display, not matrix configurations. +with ESPHome. Please note that this component is *only* for 7-segment display, not matrix configurations. .. figure:: images/max7219-full.jpg :align: center @@ -16,7 +16,7 @@ with ESPHome. Please note that this integration is *only* for 7-segment display, MAX7219 7-Segment Display. -As the communication with the MAX7219 is done using SPI for this integration, you need +As the communication with the MAX7219 is done using SPI for this component, you need to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** set (miso_pin is not required). Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and CS to your set ``cs_pin`` and finally GND to GND. diff --git a/components/display/max7219digit.rst b/components/display/max7219digit.rst index 2c7923c43..650ef878e 100644 --- a/components/display/max7219digit.rst +++ b/components/display/max7219digit.rst @@ -5,7 +5,7 @@ MAX7219 Digit Display :description: Instructions for setting up MAX7219 Digit displays. :image: max7219digit.jpg -The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this integration +The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this component is *only* for the digit "matrix" display, for the 7 segment display see :doc:`max7219`. .. figure:: images/max7219digit.png @@ -14,7 +14,7 @@ is *only* for the digit "matrix" display, for the 7 segment display see :doc:`ma MAX7219 Digit Display. -As the communication with the MAX7219 Digit is done using SPI for this integration, you need +As the communication with the MAX7219 Digit is done using SPI for this component, you need to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** set (miso_pin is not required). Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and CS to your set ``cs_pin`` and finally GND to GND. diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index 44a194a81..ca58e9fd2 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -23,7 +23,7 @@ single-color E-Ink displays are implemented and of those only a few modules. Waveshare E-Paper 2.9 Inch E-Paper Display. -The communication ESPHome has chosen to use for this integration is 4-wire :ref:`SPI `, as it's the most stable +The communication ESPHome has chosen to use for this component is 4-wire :ref:`SPI `, as it's the most stable and high-speed. So you need to make sure your board is set to the 4-wire SPI mode and have an ``spi:`` section in your configuration. diff --git a/components/display_menu/graphical_display_menu.rst b/components/display_menu/graphical_display_menu.rst index 751769d8f..9949b8b4e 100644 --- a/components/display_menu/graphical_display_menu.rst +++ b/components/display_menu/graphical_display_menu.rst @@ -19,7 +19,7 @@ ESPHome node, without the requirement of a network connection. Overview -------- -The integration implements the :ref:`Display Menu ` integration providing +The component implements the :ref:`Display Menu ` component providing a hierarchical menu primarily intended to be controlled either by a rotary encoder with a button or a five-button joystick controller. diff --git a/components/display_menu/index.rst b/components/display_menu/index.rst index 752c2ae94..9a38ecbf8 100644 --- a/components/display_menu/index.rst +++ b/components/display_menu/index.rst @@ -7,7 +7,7 @@ Display Menu .. _display_menu: -The integration provides a menu primarily intended to be controlled either by a rotary encoder +The component provides a menu primarily intended to be controlled either by a rotary encoder with a button or a five-button joystick controller. It allows to navigate a hierarchy of items and submenus with the ability to change the values and execute commands. The menu can be activated and deactivated on demand, allowing alternating between using the screen for @@ -17,8 +17,8 @@ Overview -------- This document describes the configuration and automations common for the components implementing -this integration. At the moment the character based LCD displays are supported using -the :ref:`lcd_menu ` integration and an instance of this is used in the configuration +this component. At the moment the character based LCD displays are supported using +the :ref:`lcd_menu ` component and an instance of this is used in the configuration examples. diff --git a/components/display_menu/lcd_menu.rst b/components/display_menu/lcd_menu.rst index 676c6d474..9645ece37 100644 --- a/components/display_menu/lcd_menu.rst +++ b/components/display_menu/lcd_menu.rst @@ -19,7 +19,7 @@ ESPHome node, without the requirement of a network connection. Overview -------- -The integration implements the :ref:`Display Menu ` integration providing +The component implements the :ref:`Display Menu ` component providing a hierarchical menu primarily intended to be controlled either by a rotary encoder with a button or a five-button joystick controller. diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst index c36a2e2c1..56435d509 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -2,7 +2,7 @@ Grow Fingerprint Reader ======================= .. seo:: - :description: Instructions for setting up Grow Fingerprint Reader integration in ESPHome. + :description: Instructions for setting up Grow Fingerprint Reader component in ESPHome. :image: fingerprint.svg The ``fingerprint_grow`` component allows you to use your R307, R503, R503-RGB, ZFM-20, ... fingerprint sensors with ESPHome. diff --git a/components/gps.rst b/components/gps.rst index a391a2c46..0f6834a71 100644 --- a/components/gps.rst +++ b/components/gps.rst @@ -2,7 +2,7 @@ GPS Component ============= .. seo:: - :description: Instructions for setting up GPS integration in ESPHome. + :description: Instructions for setting up GPS component in ESPHome. :image: crosshairs-gps.svg The ``gps`` component allows you to connect GPS modules to your ESPHome project. @@ -16,7 +16,7 @@ Any GPS module that uses the standardized NMEA communication protocol will work. .. _Adafruit: https://www.adafruit.com/product/746 -For this integration to work you need to have set up a :ref:`UART bus ` +For this component to work you need to have set up a :ref:`UART bus ` in your configuration - only the RX pin should be necessary. .. code-block:: yaml diff --git a/components/light/custom.rst b/components/light/custom.rst index 03353f6f1..0ebf96564 100644 --- a/components/light/custom.rst +++ b/components/light/custom.rst @@ -1,21 +1,27 @@ Custom Light Output =================== +.. seo:: + :description: Instructions for setting up Custom C++ lights with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom lights in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom lights in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. All internal stuff (like effects, transitions etc) is handled by the light core and cannot be overridden. Light outputs are only responsible for displaying some state diff --git a/components/light/neopixelbus.rst b/components/light/neopixelbus.rst index 271af0c6e..701fa7337 100644 --- a/components/light/neopixelbus.rst +++ b/components/light/neopixelbus.rst @@ -18,7 +18,7 @@ in ESPHome for individually addressable lights like NeoPixel or WS2812. It is very similar to the :doc:`fastled` platform. In fact, most addressable lights are supported through both light platforms. The difference is that they use different libraries: while the fastled platform uses -the `FastLED `__ library, this integration uses +the `FastLED `__ library, this component uses the `NeoPixelBus `__ library internally. .. code-block:: yaml diff --git a/components/micronova.rst b/components/micronova.rst index 8ccda83bd..f350588c2 100644 --- a/components/micronova.rst +++ b/components/micronova.rst @@ -18,7 +18,7 @@ The :ref:`UART ` must be configured with a baud rate 1200, 8 data bits, 2 Also, switching your stove on or off can behave different on the various MicroNova flavours. - Use this integration at your own risk. + Use this component at your own risk. Connecting your stove --------------------- diff --git a/components/mqtt.rst b/components/mqtt.rst index 154a492bd..c255d8ef2 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -184,13 +184,12 @@ Home Assistant generates entity names for all discovered devices based on entity entity name (e.g. ``sensor.uptime``). Numeric suffixes are appended to entity names when multiple devices use the same name for a sensor, making it harder to distinguish between similar sensors on different devices. Home Assistant 2021.12 allows MQTT devices to change -this behaviour by specifying ``object_id`` discovery attribute which replaces the sensor +this behaviour by specifying the ``object_id`` discovery attribute which replaces the sensor name part of the generated entity name. Setting ``discovery_object_id_generator: device_name`` -in ESPHome MQTT integration configuration will cause Home Assistant to include device name +in the ESPHome MQTT component configuration will cause Home Assistant to include device name in the generated entity names (e.g. ``sensor.uptime`` becomes ``sensor._uptime``), making it easier to distinguish the entities in various entity lists. - .. _mqtt-defaults: Defaults diff --git a/components/output/ac_dimmer.rst b/components/output/ac_dimmer.rst index b70474852..1a7c2b1a3 100644 --- a/components/output/ac_dimmer.rst +++ b/components/output/ac_dimmer.rst @@ -2,7 +2,7 @@ AC Dimmer Component =================== .. seo:: - :description: Instructions for setting up AC Dimmer integration in ESPHome. + :description: Instructions for setting up AC Dimmer component in ESPHome. :image: ac_dimmer.svg .. warning:: @@ -16,9 +16,8 @@ AC Dimmer Component The ``ac_dimmer`` component allows you to connect a dimmable light or other load which supports phase control dimming to your ESPHome project. -There are several already made boards which are compatible with this integration, -for example the `RobotDyn dimmer -`__. +There are several already made boards which are compatible with this component, such as the +`RobotDyn dimmer `__. .. figure:: images/robotdyn_dimmer.jpg :align: center diff --git a/components/output/custom.rst b/components/output/custom.rst index 501d46725..ad37e1bf0 100644 --- a/components/output/custom.rst +++ b/components/output/custom.rst @@ -1,17 +1,25 @@ Custom Output ============= +.. seo:: + :description: Instructions for setting up Custom C++ outputs with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom binary and float :doc:`outputs ` +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom binary and float :doc:`outputs ` in ESPHome using the C++ (Arduino) API. Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. diff --git a/components/output/sigma_delta_output.rst b/components/output/sigma_delta_output.rst index 9884f00b9..1201f981c 100644 --- a/components/output/sigma_delta_output.rst +++ b/components/output/sigma_delta_output.rst @@ -1,7 +1,7 @@ Sigma-Delta Output ================== -This integration uses `sigma-delta modulation `__ +This component uses `sigma-delta modulation `__ to output a floating-point value on a binary output. Unlike with :doc:`/components/output/slow_pwm`, it is possible to update the output value with each update cycle, not just at the end of a longer period. diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index cc1640bcc..3e2eb83c4 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -36,7 +36,7 @@ Configuration variables: - **address** (**Required**, int): The i²c address of the sensor. See :ref:`I²C Addresses ` for more information. - **continuous_mode** (*Optional*, boolean): Set if the ADS1115 should continuously measure voltages or - only measure them when an update is called. Please enable this for the :doc:`ct_clamp` integration. + only measure them when an update is called. Please enable this for the :doc:`ct_clamp` component. Defaults to ``off``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ADS1115 Hub. Use this if you want to use multiple ADS1115 hubs at once. diff --git a/components/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst index c29f966b4..e6fad15e7 100644 --- a/components/sensor/airthings_ble.rst +++ b/components/sensor/airthings_ble.rst @@ -135,8 +135,7 @@ Battery Level Reporting *********************** If you wish to have the 'percentage of battery life remaining' -reported as a sensor, you can make use of the :ref:`copy-sensor` -integration. +reported as a sensor, you can make use of the :ref:`copy-sensor` component. The examples below are based on standard alkaline-chemistry batteries; if you use other types of batteries you may need to adjust the diff --git a/components/sensor/as3935.rst b/components/sensor/as3935.rst index 7bc0aa4f0..d38520faa 100644 --- a/components/sensor/as3935.rst +++ b/components/sensor/as3935.rst @@ -19,7 +19,7 @@ Component/Hub The AS3935 can be configured to use either the SPI **or** I²C protocol for data communication. First choose which communication method you want to use for the sensor, set the SI pin for the appropriate -level and set up the ESPHome integration for the chosen communication method. +level and set up the ESPHome component for the chosen communication method. Module Pins ----------- diff --git a/components/sensor/bl0940.rst b/components/sensor/bl0940.rst index 9ee4eed3d..6053fddf1 100644 --- a/components/sensor/bl0940.rst +++ b/components/sensor/bl0940.rst @@ -1,5 +1,5 @@ Belling BL0940 Energy Monitor -================================== +============================= .. seo:: :description: Instructions for setting up BL0940 power monitors. @@ -16,7 +16,7 @@ Belling BL0940 Energy Monitor The ``bl0940`` sensor platform allows you to use BL0940 energy monitors sensors with ESPHome. These are used in some Tuya-devices (e.g. the power metering BW-SHP10) -The communication with this integration is done over a :ref:`UART bus `. +The communication with this component is done via a :ref:`UART `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 4800 with 1 stop bit. diff --git a/components/sensor/bl0942.rst b/components/sensor/bl0942.rst index 47220333c..b2757725e 100644 --- a/components/sensor/bl0942.rst +++ b/components/sensor/bl0942.rst @@ -1,5 +1,5 @@ Belling BL0942 Energy Monitor -================================== +============================= .. seo:: :description: Instructions for setting up BL0942 power monitors. @@ -9,7 +9,7 @@ Belling BL0942 Energy Monitor The ``bl0942`` sensor platform allows you to use BL0942 energy monitors sensors with ESPHome. These are used in some Tuya-devices (e.g. Aubess Tuya WiFi Mini Smart Switch With Energy Monitor) -The communication with this integration is done over a :ref:`UART bus `. +The communication with this component is done via a :ref:`UART `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 4800 with 1 stop bit. diff --git a/components/sensor/ccs811.rst b/components/sensor/ccs811.rst index 831d95ea8..95b4bde42 100644 --- a/components/sensor/ccs811.rst +++ b/components/sensor/ccs811.rst @@ -23,7 +23,7 @@ The ``ccs811`` sensor platform allows you to use CCS811 eCO_2 and volatile organ .. _Adafruit: https://www.adafruit.com/product/3566 The communication with this sensor is done via :ref:`I²C Bus `, so you need to have -an ``i2c:`` section in your config for this integration to work. +an ``i2c:`` section in your config for this component to work. .. code-block:: yaml diff --git a/components/sensor/cse7766.rst b/components/sensor/cse7766.rst index dcf6acd73..5b820555d 100644 --- a/components/sensor/cse7766.rst +++ b/components/sensor/cse7766.rst @@ -9,7 +9,7 @@ CSE7766 Power Sensor The ``cse7766`` sensor platform allows you to use your CSE7766 voltage/current and power sensors (`datasheet `__) sensors with ESPHome. This sensor is commonly found in Sonoff POW R2. CSE7759B is similar to CSE7766 -and works with this integration. +and works with this component. .. note:: diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst index 76caada78..ad52cbeb5 100644 --- a/components/sensor/custom.rst +++ b/components/sensor/custom.rst @@ -1,16 +1,6 @@ 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`. - - You can find some basic documentation on creating your own components - at :ref:`contributing_to_esphome`. - .. seo:: :description: Instructions for setting up Custom C++ sensors with ESPHome. :image: language-cpp.svg @@ -18,11 +8,18 @@ Custom Sensor Component .. warning:: - While I do try to keep the ESPHome configuration options as stable as possible - and back-port them, the ESPHome API is less stable. If something in the APIs needs - to be changed in order for something else to work, I will do so. + 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`. -So, you just set up ESPHome for your ESP32/ESP8266, but sadly ESPHome is missing a sensor integration + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. + +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +So, you just set up ESPHome for your ESP32/ESP8266, but sadly ESPHome is missing a sensor component you'd really like to have 😕. It's pretty much impossible to support every single sensor, as there are simply too many. That's why ESPHome has a really simple API for you to create your own **custom sensors** 🎉 diff --git a/components/sensor/dsmr.rst b/components/sensor/dsmr.rst index 0f664b0e7..0181270e0 100644 --- a/components/sensor/dsmr.rst +++ b/components/sensor/dsmr.rst @@ -11,7 +11,7 @@ Component/Hub The DSMR component connects to Dutch Smart Meters which comply to DSMR (Dutch Smart Meter Requirements), also known as ‘Slimme meter’ or ‘P1 port’. -This integration supports plain non encrypted telegrams and also encrypted as used in Luxembourg. +This component supports plain non encrypted telegrams and also encrypted as used in Luxembourg. In case your equipment has encryption you must get a 32 character long encryption key from your energy company. This component is passive, it does not transmit any data to your equipment, the equipment always transmits diff --git a/components/sensor/growatt_solar.rst b/components/sensor/growatt_solar.rst index b44244688..5aefa3623 100644 --- a/components/sensor/growatt_solar.rst +++ b/components/sensor/growatt_solar.rst @@ -14,7 +14,7 @@ The ``Growatt Inverter`` sensor platform allows you to use growatt inverter data Growatt Logo -The communication with this integration is done over a :ref:`UART bus ` using :ref:`Modbus `. +The communication with this component is done over a :ref:`UART bus ` using :ref:`Modbus `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/havells_solar.rst b/components/sensor/havells_solar.rst index 5338e6f5e..dec07ff51 100644 --- a/components/sensor/havells_solar.rst +++ b/components/sensor/havells_solar.rst @@ -16,7 +16,7 @@ with ESPHome. Havells On Grid Solar Inverter. -The communication with this integration is done over a :ref:`UART bus ` using :ref:`Modbus `. +The communication with this component is done via a :ref:`UART ` using :ref:`Modbus `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/hlw8012.rst b/components/sensor/hlw8012.rst index eb1dcf0f7..4a635e7f7 100644 --- a/components/sensor/hlw8012.rst +++ b/components/sensor/hlw8012.rst @@ -9,12 +9,14 @@ HLW8012 Power Sensor The ``hlw8012`` sensor platform allows you to use your HLW8012 voltage/current and power sensors (`datasheet `__) sensors with ESPHome. This sensor is commonly found in Sonoff POWs. CSE7759 and BL0937 are similar to HLW8012 -and work with this integration. Beware that CSE7759B is different and should be used -with the :doc:`CSE7766 ` integration. +and work with this component. Beware that CSE7759B is different and should be used with the +:doc:`CSE7766 ` component. .. note:: - SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins. + SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains + voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent + any use of the dangerous digital pins. This sensor has two data outputs which both encode values using the frequency of a modulated signal: CF and CF1. CF's frequency is proportional to the (active) power measured and CF1 is proportional to the current/voltage. Using diff --git a/components/sensor/inkbird_ibsth1_mini.rst b/components/sensor/inkbird_ibsth1_mini.rst index 4b641aab5..530fc4e5a 100644 --- a/components/sensor/inkbird_ibsth1_mini.rst +++ b/components/sensor/inkbird_ibsth1_mini.rst @@ -107,7 +107,7 @@ entry like in the configuration example at the top. .. note:: - The ESPHome Inkbird IBS-TH1/TH2 integration listens passively to packets the device sends by itself. + The ESPHome Inkbird IBS-TH1/TH2 component listens passively to packets the device sends by itself. ESPHome therefore has no impact on the battery life of the device. See Also diff --git a/components/sensor/mcp3204.rst b/components/sensor/mcp3204.rst index b8239a977..117b9359f 100644 --- a/components/sensor/mcp3204.rst +++ b/components/sensor/mcp3204.rst @@ -6,10 +6,9 @@ MCP3204 & MCP3208 12-Bit A/D Converters :keywords: MCP3204 MCP3208 :image: mcp3204.jpg -The Microchip Technology Inc. MCP3204 & MCP3208 -devices are successive approximation 12-bit Analog-to-Digital (A/D) converters with on-board sample and -hold circuitry. This integration is common for both device types. -configure both devices as MCP3204 and observe the maximum number of channels as per variant used. +The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D) +converters with on-board sample and hold circuitry. This component is common for both device types. +Configure both devices as MCP3204 and observe the maximum number of channels as per variant used. .. figure:: images/mcp3204.jpg :align: center diff --git a/components/sensor/mmc5983.rst b/components/sensor/mmc5983.rst index c29a5b37a..b061354d0 100644 --- a/components/sensor/mmc5983.rst +++ b/components/sensor/mmc5983.rst @@ -8,8 +8,7 @@ MMC5983 Magnetometer :image: mmc5983.jpg :keywords: MMC5983 -The ``mmc5983`` integration allows you to use your MMC5983 triple-axis magnetometer -(`datasheet`_, `SparkFun`_) with ESPHome. +The ``mmc5983`` component allows you to use your MMC5983 triple-axis magnetometer (`datasheet`_, `SparkFun`_) with ESPHome. The :ref:`I²C Bus ` is required to be set up for this sensor to work. The device supports 400kHz operation, so you may specify up to ``frequency: 400kHz`` in your ``i2c`` configuration. diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index d5b8b8406..ec003a832 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -144,7 +144,7 @@ Then just copy the address (``D3:75:F2:DC:16:91``) into a new .. note:: - The ESPHome Mopeka Pro Check BLE integration listens passively to packets the Mopeka/Lippert device sends by itself. + The ESPHome Mopeka Pro Check BLE component listens passively to packets the Mopeka/Lippert device sends by itself. ESPHome therefore has no impact on the battery life of the device. See Also diff --git a/components/sensor/mopeka_std_check.rst b/components/sensor/mopeka_std_check.rst index 43911030e..e9f7f6f6d 100644 --- a/components/sensor/mopeka_std_check.rst +++ b/components/sensor/mopeka_std_check.rst @@ -138,7 +138,7 @@ Then just copy the address (``D3:75:F2:DC:16:91``) into a new .. note:: - The ESPHome Mopeka Standard Check BLE integration listens passively to packets the Mopeka device sends by itself. + The ESPHome Mopeka Standard Check BLE component listens passively to packets the Mopeka device sends by itself. ESPHome therefore has no impact on the battery life of the device. See Also diff --git a/components/sensor/mqtt_subscribe.rst b/components/sensor/mqtt_subscribe.rst index c004949fb..ae8e723e0 100644 --- a/components/sensor/mqtt_subscribe.rst +++ b/components/sensor/mqtt_subscribe.rst @@ -10,7 +10,7 @@ The ``mqtt_subscribe`` sensor platform allows you to get external data into ESPH The sensor will subscribe to messages on the given MQTT topic and parse each message into a floating point number. -Please note this integration only works with MQTT topics that have numeric data! Each time +Please note this component only works with MQTT topics that have numeric data! Each time a message that is not a number is published a warning will be shown. Please use the MQTT subscribe text sensor for importing arbitrary text into the ESPHome ecosystem. diff --git a/components/sensor/pulse_meter.rst b/components/sensor/pulse_meter.rst index 102a20163..5941c377b 100644 --- a/components/sensor/pulse_meter.rst +++ b/components/sensor/pulse_meter.rst @@ -6,7 +6,7 @@ Pulse Meter Sensor :image: pulse.svg The pulse meter sensor allows you to count the number and frequency of pulses on any pin. It is intended to be a drop-in replacement -for the :doc:`pulse counter integration `. +for the :doc:`pulse counter component `. Rather than counting pulses over a fixed time interval, the pulse meter sensor measures the time between pulses. The precise manner in which this is done depends on the ``internal_filter_mode`` option. This leads to a higher resolution, especially for low pulse rates, as the pulse counter sensor is limited by the number of pulses within a time interval. Here's a comparison of the two sensors. The pulse meter is the smoother line. Both are set to an update interval of 10 seconds (using the ``update_interval`` and the ``throttle_average`` option respectively): diff --git a/components/sensor/pzem004t.rst b/components/sensor/pzem004t.rst index 2e339e37a..b35d2c6ae 100644 --- a/components/sensor/pzem004t.rst +++ b/components/sensor/pzem004t.rst @@ -24,7 +24,7 @@ ESPHome. The PZEM-004, however, is still working (and selling) with this protocol and does not use modbus. For using the newer V3 variant of this sensor please see :doc:`pzemac `. -The communication with this integration is done over a :ref:`UART bus `. +The communication with this component is done via a :ref:`UART `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/pzemac.rst b/components/sensor/pzemac.rst index cebb686a1..cd3ee42dc 100644 --- a/components/sensor/pzemac.rst +++ b/components/sensor/pzemac.rst @@ -37,7 +37,7 @@ for more information. This page refers to version V3 of the PZEM004T. For using the older V1 variant of this sensor please see :doc:`pzem004t `. -The communication with this integration is done over a :ref:`UART bus ` using :ref:`Modbus `. +The communication with this component is done via a :ref:`UART ` using :ref:`Modbus `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/pzemdc.rst b/components/sensor/pzemdc.rst index 6a7d29091..c2a9edc0e 100644 --- a/components/sensor/pzemdc.rst +++ b/components/sensor/pzemdc.rst @@ -15,7 +15,7 @@ Peacefair PZEM-00X DC Energy Monitor The ``pzemdc`` sensor platform allows you to use various DC Peacefair PZEM energy monitors with ESPHome. The supported models are: PZEM-003, PZEM-014, PZEM-016 and PZEM-017. -The communication with this integration is done over a :ref:`UART bus `. +The communication with this component is via a :ref:`UART `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/ruuvitag.rst b/components/sensor/ruuvitag.rst index 92a3ae9d7..b38f80740 100644 --- a/components/sensor/ruuvitag.rst +++ b/components/sensor/ruuvitag.rst @@ -176,7 +176,7 @@ Then just copy the address (``FF:56:D3:2F:7D:E8``) into a new .. note:: - The ESPHome Ruuvi BLE integration listens passively to packets the RuuviTag device sends by itself. + The ESPHome Ruuvi BLE component listens passively to packets the RuuviTag device sends by itself. ESPHome therefore has no impact on the battery life of the device. See Also diff --git a/components/sensor/sdm_meter.rst b/components/sensor/sdm_meter.rst index 44067ca03..fa3192694 100644 --- a/components/sensor/sdm_meter.rst +++ b/components/sensor/sdm_meter.rst @@ -16,7 +16,7 @@ with ESPHome. SDM230M Energy Monitor. -The communication with this integration is done over a :ref:`UART bus ` using the :ref:`Modbus protocol ` +The communication with this component is done via a :ref:`UART ` using the :ref:`Modbus protocol ` over RS485 wiring. You will need an RS485 to UART converter for communication. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600bps. diff --git a/components/sensor/selec_meter.rst b/components/sensor/selec_meter.rst index 392583905..fb268dffa 100644 --- a/components/sensor/selec_meter.rst +++ b/components/sensor/selec_meter.rst @@ -16,7 +16,7 @@ with ESPHome. Selec EM2M Energy Monitor. -The communication with this integration is done over a :ref:`UART bus ` using :ref:`Modbus `. +The communication with this component is done via a :ref:`UART ` using :ref:`Modbus `. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. diff --git a/components/sensor/smt100.rst b/components/sensor/smt100.rst index 93e7567fc..cfabbd757 100644 --- a/components/sensor/smt100.rst +++ b/components/sensor/smt100.rst @@ -1,5 +1,5 @@ SMT100 Soil Moisture Sensor -================================ +=========================== .. seo:: :description: Instructions for setting up SMT100 soil moisture and temperature sensor @@ -14,7 +14,9 @@ The SMT100 sensor platform allows you to use the SMT100 soil moisture and temper :width: 50.0% -The communication with this integration is done over a UART bus using a simple ASCII protocol. You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 9600. +The communication with this component is done via a :ref:`UART ` using a simple ASCII protocol. You must +therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set to some pins on your +board and the baud rate set to 9600. .. code-block:: yaml diff --git a/components/servo.rst b/components/servo.rst index 89939fba4..271a78d95 100644 --- a/components/servo.rst +++ b/components/servo.rst @@ -9,7 +9,7 @@ The ``servo`` component allows you to use servo motors with ESPHome. Servos are motor controllers that contain all the electronics necessary for driving the motor and provide a simple PWM interface to control the motor. -This integration works with both continuous-rotation and absolute servos and has a similar +This component works with both continuous-rotation and absolute servos and has a similar interface to the Arduino Servo library. First, create an :ref:`output component ` (here ``esp8266_pwm``) for the pin the diff --git a/components/switch/custom.rst b/components/switch/custom.rst index 1f9344980..5e0823171 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -1,21 +1,27 @@ Custom Switch ============= +.. seo:: + :description: Instructions for setting up Custom C++ switches with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom switches in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom switches in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. The example below is an example of a custom switch; this custom switch is essentially the same as the gpio switch implementation. diff --git a/components/text_sensor/custom.rst b/components/text_sensor/custom.rst index e43e31f7d..f0606e19d 100644 --- a/components/text_sensor/custom.rst +++ b/components/text_sensor/custom.rst @@ -1,22 +1,28 @@ Custom Text Sensor ================== +.. seo:: + :description: Instructions for setting up Custom C++ text sensors with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create custom text sensors in ESPHome -using the C++ (Arduino) API. +.. warning:: -Please first read :doc:`/components/sensor/custom` guide, -the same principles apply here and text sensors are very similar -to sensors internally. + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + +This component can be used to create custom text sensors in ESPHome using the C++ (Arduino) API. + +Please first read :doc:`/components/sensor/custom` guide, the same principles apply here and text +sensors are very similar to sensors internally. The example below is an example of a custom text sensor which constantly publishes the message "Hello World!". diff --git a/components/text_sensor/mqtt_subscribe.rst b/components/text_sensor/mqtt_subscribe.rst index 306955c70..17a6d5966 100644 --- a/components/text_sensor/mqtt_subscribe.rst +++ b/components/text_sensor/mqtt_subscribe.rst @@ -31,7 +31,7 @@ Configuration variables: Example Usage for Displays -------------------------- -This integration is especially useful for displays, to show external data on the display. +This component is especially useful for displays, to show external data on the display. Please note you have to use the ``.c_str()`` method on the ``.state`` object together with the ``%s`` format to use it in ``printf`` expressions. diff --git a/components/tm1651.rst b/components/tm1651.rst index adc334661..8ace6218d 100644 --- a/components/tm1651.rst +++ b/components/tm1651.rst @@ -10,9 +10,9 @@ TM1651 Battery Display Battery Display --------------- -The ``tm1651`` display platform allows you to use battery display units based on TM1651 chip, like -`this one `__ -with ESPHome. Currently integration supports level and brightness setting. All updates can be made via lambda expressions. +The ``tm1651`` display platform allows you to use battery display units based on the TM1651 chip such as +`this one `__ with ESPHome. This component supports the level +and brightness settings. All updates can be made via lambda expressions. .. figure:: images/tm1651-battery-display.jpg :align: center diff --git a/custom/custom_component.rst b/custom/custom_component.rst index 5544f3aac..72e23baf9 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -1,20 +1,29 @@ Generic Custom Component ======================== +.. seo:: + :description: Instructions for setting up Custom C++ components with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. -This integration can be used to create generic custom components in ESPHome -using the C++ (Arduino) API. This integration should be used in cases where +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. + + +This component can be used to create generic custom components in ESPHome +using the C++ (Arduino) API. This component should be used in cases where none of ESPHome's abstraction layers (for example the "sensor", "binary sensor", -"switch", etc concepts) work well for your integration. +"switch", etc concepts) work well for your component. Please first read :doc:`/components/sensor/custom` guide, the same principles apply here. diff --git a/custom/i2c.rst b/custom/i2c.rst index 7b556a9ba..87940b8be 100644 --- a/custom/i2c.rst +++ b/custom/i2c.rst @@ -1,15 +1,23 @@ Custom I²C Device ================= +.. seo:: + :description: Instructions for setting up Custom C++ I2C devices with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. + +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. Lots of devices communicate using the I²C protocol. If you want to integrate a device into ESPHome that uses this protocol you can pretty much use almost diff --git a/custom/spi.rst b/custom/spi.rst index 1653a282c..6407d1d58 100644 --- a/custom/spi.rst +++ b/custom/spi.rst @@ -1,15 +1,23 @@ Custom SPI Device ================= +.. seo:: + :description: Instructions for setting up Custom C++ SPI devices with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. + +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. Lots of devices communicate using the SPI protocol. If you want to integrate a device into ESPHome that uses this protocol you can pretty much use almost diff --git a/custom/uart.rst b/custom/uart.rst index 57c52bcf0..40b71b668 100644 --- a/custom/uart.rst +++ b/custom/uart.rst @@ -1,15 +1,23 @@ Custom UART Device ================== +.. seo:: + :description: Instructions for setting up Custom C++ UART devices with ESPHome. + :image: language-cpp.svg + :keywords: C++, Custom + .. 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`. + 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`. + You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`. + +.. warning:: + + While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less + stable. If something in the APIs needs to be changed in order for something else to work, we will do so. Lots of devices communicate using the UART protocol. If you want to integrate a device into ESPHome that uses this protocol you can pretty much use almost diff --git a/guides/contributing.rst b/guides/contributing.rst index fc38f75b1..97a8a7791 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -485,7 +485,7 @@ Let's leave what's written in those files for (2.), but for now you should also whenever a component is loaded, all the C++ source files in the folder of the component are automatically copied into the generated PlatformIO project. So you just need to add the C++ source files in the folder and the ESPHome core will copy them with no additional code required -by the integration developer. +by the component developer. .. note:: @@ -520,7 +520,7 @@ called ``CONFIG_SCHEMA``. An example of such a schema is shown below: This variable is automatically loaded by the ESPHome core and validated against. The underlying system ESPHome uses for this is `voluptuous `__. Going into how to validate is out of scope for this guide, but the best way to learn is to look -at examples of how similar integrations validate user input. +at examples of how similar components validate user input. A few point on validation: @@ -537,7 +537,7 @@ After the user input has been successfully validated, the last step of the Pytho is called: Code generation. As you may know, ESPHome converts the user's configuration into C++ code (you can see the generated -code under ``/src/main.cpp``). Each integration must define its own ``to_code`` method +code under ``/src/main.cpp``). Each component must define its own ``to_code`` method that converts the user input to C++ code. This method is also automatically loaded and invoked by the ESPHome core. An example of @@ -555,10 +555,10 @@ such a method can be seen below: Again, going into all the details of ESPHome code generation would be out-of-scope. However, ESPHome's code generation is 99% syntactic sugar - and again it's probably best to study other -integrations and just copy what they do. +components and just copy what they do. There's one important concept for the ``to_code`` method: coroutines with ``yield``. -First the problem that leads to coroutines: In ESPHome, integrations can declare (via ``cg.Pvariable``) and access variables +First the problem that leads to coroutines: In ESPHome, components can declare (via ``cg.Pvariable``) and access variables (``cg.get_variable()``) - but sometimes when one part of the code base requests a variable it has not been declared yet because the code for the component creating the variable has not run yet. @@ -575,14 +575,14 @@ If you do not call "add" a piece of code explicitly, it will not be added to the ********** Okay, the Python part of the codebase is now complete - now let's talk about the C++ part of -creating a new integration. +creating a new component. -The two major parts of any integration roughly are: +The two major parts of any component roughly are: - Setup Phase - Run Phase -When you create a new integration, your new component will inherit from :apiclass:`Component`. +When you create a new component, your new component will inherit from :apiclass:`Component`. That class has a special ``setup()`` method that will be called once to set up the component - at the time the ``setup()`` method is called, all the setters generated by the Python codebase have already run and the all fields are set for your class. @@ -590,7 +590,7 @@ have already run and the all fields are set for your class. The ``setup()`` method should set up the communication interface for the component and check if communication works (if not, it should call ``mark_failed()``). -Again, look at examples of other integrations to learn more. +Again, look at examples of other components to learn more. The next thing that will be called with your component is ``loop()`` (or ``update()`` for a :apiclass:`PollingComponent`). In these methods you should retrieve the latest data from the @@ -621,11 +621,11 @@ loader. These are: - ``AUTO_LOAD``: Automatically load a component if the user hasn't added it manually. - ``MULTI_CONF``: Mark this component to accept an array of configurations. If this is an integer instead of a boolean, validation will only permit the given number of entries. -- ``CONFLICTS_WITH``: Mark a list of components as conflicting with this integration. If the user +- ``CONFLICTS_WITH``: Mark a list of components as conflicting with this component. If the user has one of them in the config, a validation error will be generated. -- ``ESP_PLATFORMS``: Provide a list of allowed ESP types this integration works with. -- ``CODEOWNERS``: GitHub usernames or team names of people that are responsible for this integration. +- ``ESP_PLATFORMS``: Provide a list of allowed ESP types this component works with. +- ``CODEOWNERS``: GitHub usernames or team names of people that are responsible for this component. You should add at least your GitHub username here, as well as anyone who helped you to write code that is being included. @@ -663,8 +663,8 @@ Standard for the esphome-core codebase: like ``Wire`` there's a problem because then the component may not modular (i.e. not possible to create two instances of a component on one ESP) -- Integrations **must** use the provided abstractions like ``Sensor``, ``Switch`` etc. - Integration should specifically **not** directly access other components like for example +- Components **must** use the provided abstractions like ``sensor``, ``switch`` etc. + Components should specifically **not** directly access other components like for example publish to MQTT topics. - Implementations for new devices should contain reference links for the datasheet and other sample diff --git a/guides/faq.rst b/guides/faq.rst index 61bc3a12b..a7b9abe9c 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -73,12 +73,14 @@ Tips for using ESPHome .. |include| replace:: ``!include`` .. _include: https://www.home-assistant.io/docs/configuration/splitting_configuration/ -I can't get flashing over USB to work. --------------------------------------- +I can't get flashing over USB to work +------------------------------------- .. _esphome-esptool: -ESPHome depends on the operating system the tool is running on to recognize the ESP. This can sometimes fail. Common causes are that you may not have the drivers installed (see :ref:`here `) or you are trying to upload from a Docker container and did not mount the ESP device into your container using ``--device=/dev/ttyUSB0``. +ESPHome depends on the operating system the tool is running on to recognize the ESP. This can sometimes fail. Common +causes are that you may not have the drivers installed (see :ref:`here `) or you are trying to +upload from a Docker container and did not mount the ESP device into your container using ``--device=/dev/ttyUSB0``. First, you need to get the firmware file to flash. For the Home Assistant add-on based installs you can use the ``Manual download`` method of the Dashboard (click ``Install`` in the overflow icon with the three dots @@ -90,10 +92,18 @@ Second, you need to put the ESP in :ref:`programming mode ` Third, to flash a firmware file downloaded from Home Assistant add-on Dashboard, you can use: -- `ESPHome Web `__ web-based installer, which requires a browser that supports WebSerial, like Google Chrome or Microsoft Edge. Connect the board to your computer, make sure it's detected as a :ref:`serial port `, and press **Connect**. Give the requested permission in the browser and in the popup box that appears, select the serial device which connects to your ESP. Then press **Install**, and browse for the binary file you downloaded from the Dashboard in the step above. Note that the file will be processed locally, it won't be uploaded to any cloud service. -- *esptool* `from the GitHub repository `__, package from your distro or install it yourself with ``pip install esptool`` (in case of Linux). +- `ESPHome Web `__ web-based installer, which requires a browser that supports WebSerial, like + Google Chrome or Microsoft Edge. Connect the board to your computer, make sure it's detected as a + :ref:`serial port `, and press **Connect**. Give the requested permission in the browser and in + the pop-up box that appears, select the serial device which connects to your ESP. Then press **Install**, and browse + for the binary file you downloaded from the Dashboard in the step above. Note that the file will be processed + locally, it won't be uploaded to any cloud service. +- *esptool* `from the GitHub repository `__, package from your distro or + install it yourself with ``pip install esptool`` (in case of Linux). -Before using ``esptool``, make sure you know which serial port your programming adapter is connected to. In Linux use the ``dmesg`` command afer you plug the device into the USB port to see the name of the newly detected serial port. In Windows check the Device Manager to see if a new serial port appears when you plug it in and note the COM number. +Before using ``esptool``, make sure you know which serial port your programming adapter is connected to. In Linux use +the ``dmesg`` command afer you plug the device into the USB port to see the name of the newly detected serial port. +In Windows check the Device Manager to see if a new serial port appears when you plug it in and note the COM number. Erase flash: @@ -109,15 +119,19 @@ Program flash with your firmware binary: .. note:: - If you're just seeing ``Connecting....____....`` on the screen and the flashing fails, check for these: + If you're just seeing ``Connecting....____....`` on the screen and flashing fails: - - the device name of the port has changed while you were re-plugging it too fast (eg. changed from ``/dev/ttyUSB0`` to ``/dev/ttyUSB1``). - - double check the UART wires are connected correctly if flashing using an external programmer (RX of programmer to TX of the ESP and vice-versa). + - verify that the device name of the port has not changed while you were re-plugging it too fast (eg. changed + from ``/dev/ttyUSB0`` to ``/dev/ttyUSB1``). + - double check the UART wires are connected correctly if flashing using an external programmer (RX of programmer to + TX of the ESP and vice-versa). - for some devices you need to keep ``GPIO0`` and ``GND`` connected at least until flashing has begun. - for some devices you need to power-cycle in programming mode after erasing flash, they don't auto-reset. - - it also might be a sign that ESP is defect or cannot be programmed. + - it also might be a sign that ESP is defective, damaged or otherwise cannot be programmed. - If you're in an RF noisy environment or your UART wires are a bit long, flashing can fail during transfer. Don't worry, an ESP won't brick just because of that. Put it again in programming mode and flash with a reduced baudrate for safer transfers: + If you're in an RF noisy environment or your UART wires are a bit long, flashing can fail during transfer. Don't + worry, an ESP won't brick just because of that. Put it again in programming mode and flash with a reduced baudrate + for safer transfers: ``esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 your_node_firmware.bin`` @@ -277,7 +291,7 @@ Some steps that can help with the issue: of the networking code. For this reason, we advise using a lower log level for production purposes. - Related to this, seems to be the number of clients that are simultaneously connected to the native - API server on the device. These might for example be Home Assistant (via the ESPHome integration) and + API server on the device. These might for example be Home Assistant (via the ESPHome component) and the log viewer on the web dashboard. In production, you will likely only have a single connection from Home Assistant, making this less of an issue. But beware that attaching a log viewer might have impact. @@ -367,14 +381,16 @@ And a docker compose file looks like this: .. _docker-reference-notes: .. note:: - By default ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature to work you need to enable host networking mode. + By default ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature to work you + need to enable host networking mode. On MacOS the networking mode ("-net=host" option) doesn't work as expected. You have to use another way to launch the dashboard with a port mapping option and use alternative to mDNS to have the online/offline stat (see below) mDNS might not work if your Home Assistant server and your ESPHome nodes are on different subnets. - If your router supports Avahi (eg. OpenWRT or pfSense), you are able to get mDNS working over different subnets following the steps below: + If your router supports Avahi (eg. OpenWRT or pfSense), you are able to get mDNS working over different subnets + following the steps below: 1. Enable Avahi on both subnets (install Avahi modules on OpenWRT or pfSense). 2. Enable UDP traffic from ESPHome node's subnet to 224.0.0.251/32 on port 5353. @@ -387,15 +403,22 @@ And a docker compose file looks like this: .. _faq-notes_on_disabling_mdns: Notes on disabling mDNS ------------------------------------------------------------------------------- -Some of ESPHome's functionalities rely on mDNS, so naturally :doc:`disabling ` it will cause these features to stop working. -Generally speaking, disabling mDNS without setting a :ref:`static IP address ` (or a static DHCP lease) is bound to cause problems. This is due to the fact that mDNS is used to find the IP address of each ESPHome nodes. +----------------------- +Some of ESPHome's functionalities rely on mDNS, so naturally :doc:`disabling ` it will cause these +features to stop working. +Generally speaking, disabling mDNS without setting a :ref:`static IP address ` (or a static DHCP lease) +is bound to cause problems. This is due to the fact that mDNS is used to find the IP address of each ESPHome nodes. - You will not be able to use the node's hostname to ping, find it's IP address or connect to it. -- Automatic discovery in Home Assistant when using :doc:`native API ` relies on mDNS broadcast messages to detect presence of new ESPHome nodes. If you need to use the native API with mDNS disabled, then you will have to use a static IP address and manually add the ESPHome integration with the fixed IP address. +- Automatic discovery in Home Assistant when using :doc:`native API ` relies on mDNS broadcast + messages to detect presence of new ESPHome nodes. If you need to use the native API with mDNS disabled, then you will + have to use a static IP address and manually add the ESPHome component with the fixed IP address. -- Online status detection in ESPHome's dashboard by default uses mDNS, so disabling mDNS will cause the ESPHome dashboard to show the status of the nodes created without mDNS support to be always offline. Currently, this does not affect any functionality, however if you want to see the online/offline status you could configure ESPHome to ping each node instead. See the :ref:`notes in the Docker Reference section ` for more information. +- Online status detection in ESPHome's dashboard by default uses mDNS, so disabling mDNS will cause the ESPHome + dashboard to show the status of the nodes created without mDNS support to be always offline. Currently, this does not + affect any functionality, however if you want to see the online/offline status you could configure ESPHome to ping + each node instead. See the :ref:`notes in the Docker Reference section ` for more information. Can Configuration Files Be Recovered From The Device? ----------------------------------------------------- @@ -411,25 +434,37 @@ Always back up all your files! Why shouldn't I use underscores in my device name? -------------------------------------------------- -The top level ``name:`` field in your .yaml file defines the node name(/hostname) on the local network. According to `RFC1912 `_, underscore characters (``_``) in hostnames are not valid. In reality some local DNS/DHCP setups will be ok with underscores and some will not. If connecting via a static IP address, there will probably be no issues. In some cases, initial setup using an underscore works, but later the connection might fail when Home Assistant restarts or if you change router hardware. Recommendation: use hyphen (``-``) instead of underscore if you can. +The top level ``name:`` field in your .yaml file defines the node name(/hostname) on the local network. According to +`RFC1912 `_, underscore characters (``_``) in hostnames are not valid. +In reality some local DNS/DHCP setups will be ok with underscores and some will not. If connecting via a static IP +address, there will probably be no issues. In some cases, initial setup using an underscore works, but later the +connection might fail when Home Assistant restarts or if you change router hardware. +Recommendation: use hyphen (``-``) instead of underscore if you can. -Important: follow these `instructions `_ to use the ``use_address`` parameter when renaming a live device, as the connection to an existing device will only work with the old name until the name change is complete. +Important: follow these `instructions `_ to use the +``use_address`` parameter when renaming a live device, as the connection to an existing device will only +work with the old name until the name change is complete. .. _strapping-warnings: Why am I getting a warning about strapping pins? --------------------------------------------------- +------------------------------------------------ -The ESP chips have special "strapping pins" that are read during the bootup procedure and determine how it boots up. They define whether the ESP boots into a special "flashing mode" or normal boot and a couple of other internal settings. +The ESP chips have special "strapping pins" that are read during the bootup procedure and determine how it boots up. +They define whether the ESP boots into a special "flashing mode" or normal boot and a couple of other internal settings. If an external pullup/down changes the configured voltage levels boot failures or hard to diagnose issues can happen. -While the use of them in software is not a problem, if there's something attached to the pins (particularly if they're not floating during the bootup) you may run into problems. -It's recommended to avoid them unless you have a pressing need to use them and you have reviewed the expected boot voltage levels of these pins from the ESP datasheet. +While the use of them in software is not a problem, if there's something attached to the pins (particularly if they're +not floating during the bootup) you may run into problems. +It's recommended to avoid them unless you have a pressing need to use them and you have reviewed the expected boot +voltage levels of these pins from the ESP datasheet. -Some development boards connect GPIO 0 to a button, often labeled "boot". Holding this button while the ESP is turning on will cause it to go into bootloader mode. Once the ESP is fully booted up, this button can be used as a normal input safely. +Some development boards connect GPIO 0 to a button, often labeled "boot". Holding this button while the ESP is +turning on will cause it to go into bootloader mode. Once the ESP is fully booted up, this button can be used +as a normal input safely. -Strapping pins should be safe to use as outputs if they are *only* connected to other devices that have hi-impedance inputs -with no pull-up or pull-down resistors. Note that I2C clock and data lines *do* have pull-up resistors and are not -safe on strapping pins. +Strapping pins should be safe to use as outputs if they are *only* connected to other devices that have hi-impedance +inputs with no pull-up or pull-down resistors. Note that I2C clock and data lines *do* have pull-up resistors and are +not safe on strapping pins. If you are absolutely sure that your use of strapping pins is safe, and want to suppress the warning, you can add ``ignore_strapping_warning: true`` to the relevant pin configurations.