Merge branch 'current' into next

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,5 +7,8 @@
 
 ## Checklist:
 
-  - [ ] Branch: `next` is for changes and new documentation that will go public with the next ESPHome release. Fixes, changes and adjustments for the current release should be created against `current`.
+  - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above.  
+    or
+  - [ ] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.
+
   - [ ] Link added in `/index.rst` when creating new documents for new components or cookbook.

changelog/2022.11.0.rst

@@ -107,6 +107,13 @@ Release 2022.11.2 - November 23
 - Avoid 128bit uuid loop for 16/32 bit uuids :esphomepr:`4068` by :ghuser:`bdraco`
 - Avoid creating a new espbt::ESPBTUUID each loop when registering for notify :esphomepr:`4069` by :ghuser:`bdraco`
 
+Release 2022.11.3 - November 24
+-------------------------------
+
+- fix missing library :esphomepr:`4051` by :ghuser:`ssieb`
+- Fix units for refresh: never :esphomepr:`4048` by :ghuser:`bkaufx`
+- Don't convert climate temperature step :esphomepr:`4082` by :ghuser:`jesserockz`
+
 Full list of changes
 --------------------
 

components/climate/bedjet.rst

@@ -18,8 +18,7 @@ This component supports the following functionality:
 
 This component uses the BLE peripheral on an ESP32, so you also need to enable
 this component. Please see the :doc:`/components/ble_client` docs for how to discover the MAC
-address of your BedJet device, or you can find the list of paired MAC addresses in
+address of your BedJet device.
-the "DEVICE LIST" section of the BedJet mobile application.
 
 Component/Hub
 -------------

components/climate/index.rst

@@ -7,7 +7,7 @@ Climate Component
 
 ESPHome has support for climate devices. Climate devices can represent different types of
 hardware, but the defining factor is that climate devices have a settable target temperature
-and can be put in different modes like HEAT, COOL, HEAT_COOL or OFF.
+and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OFF``.
 
 .. figure:: images/climate-ui.png
     :align: center
@@ -58,42 +58,6 @@ Advanced options:
   for a list of available options. Requires Home Assistant 2021.11 or newer.
   Set to ``""`` to remove the default entity category.
 
-MQTT options:
-
-- **action_state_topic** (*Optional*, string): The topic to publish
-  climate device action changes to.
-- **away_state_topic** (*Optional*, string): The topic to publish
-  away mode changes on.
-- **away_command_topic** (*Optional*, string): The topic to receive
-  away mode commands on.
-- **current_temperature_state_topic** (*Optional*, string): The topic to publish
-  current temperature changes to.
-- **fan_mode_state_topic** (*Optional*, string): The topic to publish
-  fan mode changes to.
-- **fan_mode_command_topic** (*Optional*, string): The topic to receive
-  fan mode commands on.
-- **mode_state_topic** (*Optional*, string): The topic to publish
-  climate device mode changes to.
-- **mode_command_topic** (*Optional*, string): The topic to receive
-  climate device mode commands on.
-- **swing_mode_state_topic** (*Optional*, string): The topic to publish
-  swing mode changes to.
-- **swing_mode_command_topic** (*Optional*, string): The topic to receive
-  swing mode commands on.
-- **target_temperature_state_topic** (*Optional*, string): The topic to publish
-  target temperature changes to.
-- **target_temperature_command_topic** (*Optional*, string): The topic to receive
-  target temperature commands on.
-- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish
-  higher target temperature changes to.
-- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive
-  higher target temperature commands on.
-- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish
-  lower target temperature changes to.
-- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
-  lower target temperature commands on.
-- All other options from :ref:`MQTT Component <config-mqtt-component>`.
-
 Climate Automation
 ------------------
 
@@ -189,7 +153,7 @@ advanced stuff.
 .. _climate-on_state_trigger:
 
 ``climate.on_state`` Trigger
-******************************************************
+****************************
 
 This trigger is activated each time the state of the climate device is updated 
 (for example, if the current temperature measurement or the mode set by the users changes).
@@ -202,6 +166,43 @@ This trigger is activated each time the state of the climate device is updated
         on_state:
         - logger.log: "State updated!"
 
+MQTT options:
+
+- **action_state_topic** (*Optional*, string): The topic to publish
+  climate device action changes to.
+- **away_state_topic** (*Optional*, string): The topic to publish
+  away mode changes on.
+- **away_command_topic** (*Optional*, string): The topic to receive
+  away mode commands on.
+- **current_temperature_state_topic** (*Optional*, string): The topic to publish
+  current temperature changes to.
+- **fan_mode_state_topic** (*Optional*, string): The topic to publish
+  fan mode changes to.
+- **fan_mode_command_topic** (*Optional*, string): The topic to receive
+  fan mode commands on.
+- **mode_state_topic** (*Optional*, string): The topic to publish
+  climate device mode changes to.
+- **mode_command_topic** (*Optional*, string): The topic to receive
+  climate device mode commands on.
+- **swing_mode_state_topic** (*Optional*, string): The topic to publish
+  swing mode changes to.
+- **swing_mode_command_topic** (*Optional*, string): The topic to receive
+  swing mode commands on.
+- **target_temperature_state_topic** (*Optional*, string): The topic to publish
+  target temperature changes to.
+- **target_temperature_command_topic** (*Optional*, string): The topic to receive
+  target temperature commands on.
+- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish
+  higher target temperature changes to.
+- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive
+  higher target temperature commands on.
+- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish
+  lower target temperature changes to.
+- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
+  lower target temperature commands on.
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+
 See Also
 --------
 

components/climate/thermostat.rst

@@ -6,10 +6,10 @@ Thermostat Climate Controller
     :image: air-conditioner.svg
 
 The ``thermostat`` climate platform allows you to control a climate control system in much the same manner as a
-physical thermostat. Its operation is similar to the :doc:`bang-bang <bang_bang>` controller; a sensor measures a value
+physical thermostat. Its operation is similar to the :doc:`Bang-Bang <bang_bang>` controller; a sensor measures a value
 (the air temperature) and the controller will try to keep this value within a range defined by the set point(s). To do this,
 the controller can activate devices like a heating unit and/or a cooling unit to change the value observed by the sensor.
-When configured for both heating and cooling, it is essentially two :doc:`bang-bang <bang_bang>` controllers in one; it
+When configured for both heating and cooling, it is essentially two :doc:`Bang-Bang <bang_bang>` controllers in one; it
 differs, however, in that interaction with the thermostat component is nearly identical to that of a real thermostat.
 
 This component can operate in one of two ways:
@@ -169,45 +169,6 @@ The thermostat controller uses the sensor to determine whether it should heat or
 
 - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
 
-Default Target Temperatures and Mode
-************************************
-
-These configuration items determine default values the thermostat controller should use when it starts.
-
-- **default_mode** (*Optional*, *Deprecated*, climate mode): The default climate mode the controller should
-  use if it is unable to restore it from memory. One of:
-
-  - ``off`` (default)
-  - ``heat_cool``
-  - ``cool``
-  - ``heat``
-  - ``dry``
-  - ``fan_only``
-  - ``auto``
-
-This value is used the first time your device starts after ESPHome is initially installed onto it. Add
-this option into your configuration if you want your thermostat component to start in a climate mode other
-than ``off``.  If this option is not configured, you'll need to manually change the climate mode later via
-the front end (Home Assistant), an ESPHome action, automation, or from within a lambda elsewhere in your
-device's configuration.
-
-- **default_target_temperature_low** (*Optional*, float): The default low target
-  temperature for the control algorithm. This can be dynamically set in the frontend later.
-- **default_target_temperature_high** (*Optional*, float): The default high target
-  temperature for the control algorithm. This can be dynamically set in the frontend later.
-
-**At least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
-**must be specified.**
-
-.. note::
-
-    **default_mode**, **default_target_temperature_low**, and **default_target_temperature_high** are
-    being removed in a future release. In the future you will need to migrate your configuration to using
-    a :ref:`preset <thermostat-preset>` which will allow for more flexibility and customisation
-
-Note that ``min_temperature`` and ``max_temperature`` from the base climate component are used to define
-the range of allowed temperature values in the thermostat component. See :doc:`/components/climate/index`.
-
 Heating and Cooling Actions
 ***************************
 
@@ -527,6 +488,9 @@ Additional Actions/Behavior
 - **min_fan_mode_switching_time** (*Required with any* ``fan_mode`` *action*, :ref:`config-time`): Minimum duration
   any given fan mode must be active before it may be changed.
 
+Note that ``min_temperature`` and ``max_temperature`` from the base climate component are used to define
+the range of allowed temperature values in the thermostat component. See :doc:`/components/climate/index`.
+
 Hysteresis Values
 *****************
 
@@ -547,15 +511,16 @@ Hysteresis Values
       adjustability and the defaults will probably not make sense for control of things like humidity. See
       :doc:`/components/climate/index`.
 
-Bang-bang vs. Thermostat
+Bang-Bang vs. Thermostat
 ------------------------
 
-Please see the :doc:`Bang-bang <bang_bang>` component's documentation for a detailed comparison of these two components.
+Please see the :doc:`Bang-Bang <bang_bang>` component's documentation for a detailed comparison of these two components.
 
 See Also
 --------
 
 - :doc:`/components/climate/index`
 - :doc:`/components/sensor/index`
+- :doc:`Bang-Bang <bang_bang>`
 - :ref:`config-action`
 - :ghedit:`Edit`

components/copy.rst

@@ -137,6 +137,8 @@ Configuration variables:
 - **name** (**Required**, string): The name of the select.
 - All other options from :ref:`Select <config-select>`.
 
+.. _copy-sensor:
+
 Copy Sensor
 -----------
 

components/debug.rst

@@ -7,7 +7,7 @@ Debug Component
 
 The ``debug`` component can be used to debug problems with ESPHome. At startup, it prints
 a bunch of useful information like reset reason, free heap size, ESPHome version and so on.
-It also allows you get the same information as a text sensor, and to monitor the state of the
+It also allows you to get the same information as a text sensor, and to monitor the state of the
 ESP heap memory (free space, maximum free block size and fragmentation level) and the main-loop timing.
 
 .. figure:: images/debug.png

components/i2c.rst

@@ -61,15 +61,11 @@ Configuration variables:
          address: 0x76
          # ...
 
-       # If a I²C multiplexer is used all I²C devices can be additionally configured like:
+For I2C multiplexing see :doc:`/components/tca9548a`.
-       - platform: bmp280
-         multiplexer:
-           id: multiplex0
-           channel: 0
-         # ...
 
 See Also
 --------
 
+- :doc:`/components/tca9548a`
 - :apiref:`i2c/i2c.h`
 - :ghedit:`Edit`

components/light/index.rst

@@ -551,7 +551,7 @@ Configuration variables:
   - **green** (*Optional*, percentage): The green channel of the light, if applicable. Defaults to ``100%``.
   - **blue** (*Optional*, percentage): The blue channel of the light, if applicable. Defaults to ``100%``.
   - **white** (*Optional*, percentage): The white channel of the light, if applicable. Defaults to ``100%``.
-  - **color_temperature** (*Optional*, percentage): The color temperature of the light, if applicable. Defaults to ``100%``.
+  - **color_temperature** (*Optional*, float): The color temperature (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) of the light, if applicable.
   - **cold_white** (*Optional*, percentage): The cold white channel of the light, if applicable. Defaults to ``100%``.
   - **warm_white** (*Optional*, percentage): The warm white channel of the light, if applicable. Defaults to ``100%``.
   - **duration** (**Required**, :ref:`config-time`): The duration this color should be active.

components/mqtt.rst

@@ -166,7 +166,7 @@ retained messages for you:
 
 .. code-block:: bash
 
-    esphome configuration.yaml clean-mqtt
+    esphome clean-mqtt configuration.yaml
 
 With Docker:
 

components/output/pca9685.rst

@@ -82,6 +82,27 @@ Configuration variables:
   Use this if you have multiple PCA9685s you want to use at the same time.
 - All other options from :ref:`Output <config-output>`.
 
+
+Examples
+--------
+
+This output can be used for different PWM functions. E.g. output for light, fan etc.
+
+.. code-block:: yaml
+
+    pca9685:
+      frequency: 500
+
+    output:
+      - platform: pca9685
+        channel: 0
+        id: pwm01
+        
+    light:
+      - platform: monochromatic 
+        name: 'main light' 
+        output: pwm01
+
 See Also
 --------
 

components/select/tuya.rst

@@ -42,9 +42,9 @@ Based on this, you can create the select as follows:
         enum_datapoint: 2
         optimistic: true
         options:
-          0: Internal:
+          0: Internal
-          1: Floor:
+          1: Floor
-          2: Both:
+          2: Both
 
 Configuration variables:
 ------------------------

components/sensor/ade7953.rst

@@ -57,7 +57,7 @@ Configuration variables:
   :ref:`Sensor <config-sensor>`.
 - **active_power_a** (*Optional*): Use the power value of the A channel in watts. All options from
   :ref:`Sensor <config-sensor>`.
-- **active_power_b** (*Optional*): Use the power value of the A channel in watts. All options from
+- **active_power_b** (*Optional*): Use the power value of the B channel in watts. All options from
   :ref:`Sensor <config-sensor>`.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
 

components/sensor/bme680_bsec.rst

@@ -64,8 +64,8 @@ Configuration variables:
 
 - **address** (*Optional*, int): Manually specify the I^2C address of the sensor. Defaults to ``0x76``. Another address can be ``0x77``.
 
-- **temperature_offset** (*Optional*, float): Temperature offset if device is in enclosure and reads too high.
+- **temperature_offset** (*Optional*, float): Temperature offset if device is in enclosure and reads too high. This value is subtracted
-  Defaults to ``0``.
+  from the reading (e.g. if the sensor reads 5°C higher than expected, set this to ``5``) and also corrects the relative humidity readings. Defaults to ``0``.
 
 - **iaq_mode** (*Optional*, string): IAQ calculation mode. Default is ``static`` for static applications (e.g. fixed indoor devices).
   Can be ``mobile`` for mobile applications (e.g. carry-on devices).
@@ -174,6 +174,8 @@ For each sensor all other options from :ref:`Sensor <config-sensor>` and :ref:`T
         # Temperature offset
         # ------------------
         # Useful if device is in enclosure and reads too high
+        # For example if it reads 5C too high, set this to 5
+        # This also corrects the relative humidity readings
         # Default: 0
         temperature_offset: 0
 

components/sensor/dht.rst

@@ -6,17 +6,14 @@ DHT Temperature+Humidity Sensor
     :image: dht.jpg
     :keywords: DHT11, DHT21, DHT22, AMS2301, AM2302, RHT03, SI7021
 
-The DHT Temperature+Humidity sensor allows you to use your DHT11
+The DHT Temperature+Humidity sensor allows you to use your 
-(`datasheet <https://akizukidenshi.com/download/ds/aosong/DHT11.pdf>`__,
+
-`Adafruit <https://www.adafruit.com/product/386>`__), DHT21/DHT22
+- DHT11 (`datasheet <https://akizukidenshi.com/download/ds/aosong/DHT11.pdf>`__, `Adafruit <https://www.adafruit.com/product/386>`__), 
-(`datasheet <https://www.sparkfun.com/datasheets/Sensors/Temperature/DHT22.pdf>`__,
+- DHT21/DHT22 (`datasheet <https://www.sparkfun.com/datasheets/Sensors/Temperature/DHT22.pdf>`__, `Adafruit <https://www.adafruit.com/product/385>`__), 
-`Adafruit <https://www.adafruit.com/product/385>`__), AMS2301/AM2302
+- AMS2301/AM2302 (`datasheet <https://cdn-shop.adafruit.com/datasheets/Digital+humidity+and+temperature+sensor+AM2302.pdf>`__, `Adafruit <https://www.adafruit.com/product/393>`__), 
-(`datasheet <https://cdn-shop.adafruit.com/datasheets/Digital+humidity+and+temperature+sensor+AM2302.pdf>`__,
+- RHT03 (`datasheet <https://cdn.sparkfun.com/datasheets/Sensors/Weather/RHT03.pdf>`__, `SparkFun <https://cdn.sparkfun.com/datasheets/Sensors/Weather/RHT03.pdf>`__) and 
-`Adafruit <https://www.adafruit.com/product/393>`__), RHT03
+- SI7021 (one wire Sonoff version) (`datasheet <https://cdn.sparkfun.com/assets/b/1/b/8/5/Si7021-A20.pdf>`__, `SparkFun <https://cdn.sparkfun.com/assets/b/1/b/8/5/Si7021-A20.pdf>`__)
-(`datasheet <https://cdn.sparkfun.com/datasheets/Sensors/Weather/RHT03.pdf>`__,
+
-`SparkFun <https://cdn.sparkfun.com/datasheets/Sensors/Weather/RHT03.pdf>`__) and SI7021 (one wire Sonoff version)
-(`datasheet <https://cdn.sparkfun.com/assets/b/1/b/8/5/Si7021-A20.pdf>`__,
-`SparkFun <https://cdn.sparkfun.com/assets/b/1/b/8/5/Si7021-A20.pdf>`__)
 sensors with ESPHome.
 
 .. figure:: images/dht-full.jpg
@@ -62,6 +59,7 @@ Configuration variables:
   - **name** (**Required**, string): The name for the humidity sensor.
   - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
   - All other options from :ref:`Sensor <config-sensor>`.
+  
 
 - **model** (*Optional*, int): Manually specify the DHT model, can be
   one of ``AUTO_DETECT``, ``DHT11``, ``DHT22``, ``DHT22_TYPE2``, ``AM2302``, ``RHT03``, ``SI7021``
@@ -71,6 +69,10 @@ Configuration variables:
 
 .. note::
 
+    The default ``accuracy_decimals`` value of the *humidity* levels is ``0``, as the DHT11 for which this was 
+    originally written does not have a higher resolution. All other DHT sensors have a higher resolution, it's worth 
+    to configure them with ``accuracy_decimals: 1``.
+    
     If you're seeing lots of invalid temperature/humidity warnings in the logs, try manually setting the
     DHT model with the ``model:`` configuration variable. Other problems could be wrong pull-up resistor values
     on the DATA pin or too long cables.

components/sensor/ezo.rst

@@ -152,7 +152,7 @@ From :ref:`lambdas <config-lambda>`, you can interact with the sensor in various
 
   .. code-block:: cpp
 
-      id(ph_ezo).set_calibration_point_low(10.00);
+      id(ph_ezo).set_calibration_point_high(10.00);
 
 
 - ``clear_calibration()``: Clears all calibration points.

components/sensor/index.rst

@@ -392,7 +392,7 @@ Configuration variables:
 ******************************
 
 A simple `exponential moving average
-<https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average>`__ over the last few
+<https://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/quantile.htm>`__ over the last few
 values. It can be used to have a short update interval on the sensor but only push
 out an average on a specific interval (thus increasing resolution).
 

components/sensor/max31856.rst

@@ -6,7 +6,8 @@ MAX31856 Thermocouple Temperature Sensor
     :image: max31856.jpg
 
 The ``MAX31856`` temperature sensor allows you to use your MAX31856 Thermocouple
-temperature sensor (`datasheet <https://datasheets.maximintegrated.com/en/ds/MAX31856.pdf>`__) with ESPHome
+temperature sensor (`datasheet <https://datasheets.maximintegrated.com/en/ds/MAX31856.pdf>`__) with ESPHome.
+Although the chip supports multiple thermocouple types, this component only implements the ``K`` type.
 
 .. figure:: images/max31856-full.jpg
     :align: center
@@ -20,14 +21,14 @@ As the communication with the MAX31856 is done using SPI, you need
 to have an :ref:`spi bus <spi>` in your configuration with both **miso_pin** and **mosi_pin** set.
 
 - ``VIN`` connects to 5V (``3V3`` will output 3.3V), or directly connect ``3V3`` to 3.3V
-- ``3Vo`` is not used by ESPHome
+- ``3Vo`` not used by ESPHome
 - ``GND`` connects to ground
 - ``CLK`` connects to the SPI **clk_pin**
 - ``SDO`` connects to the SPI **miso_pin**
 - ``SDI`` connects to the SPI **mosi_pin**
 - ``CS`` connects to a free GPIO pin
-- ``FLT`` is not used by ESPHome
+- ``FLT`` not used by ESPHome
-- ``DRDY`` is not used by ESPHome
+- ``DRDY`` not used by ESPHome
 
 .. code:: yaml
 

components/sensor/mpl3115a2.rst

@@ -23,12 +23,12 @@ required to be set up in your configuration for this sensor to work.
 
     # Example configuration entry
     sensor:
-      - platform: mpl3115a2
+    - platform: mpl3115a2
-          temperature:
+      temperature:
-            name: "MPL3115A2 Temperature"
+        name: "MPL3115A2 Temperature"
-          pressure:
+      pressure:
-            name: "MPL3115A2 Pressure"
+        name: "MPL3115A2 Pressure"
-          update_interval: 10s
+      update_interval: 10s
 
 Configuration variables:
 ------------------------

components/sensor/wifi_signal.rst

@@ -23,6 +23,26 @@ measured in decibel-milliwatts (dBm). These values are always negative and the c
         name: "WiFi Signal Sensor"
         update_interval: 60s
 
+To additionally display signal strength in percentage use the :ref:`copy-sensor` (it's not possible to add the same sensor twice, because it has a static ``uniqueid`` reported to Home Assistant):
+
+.. code-block:: yaml
+
+    # Example configuration entry with 2 sensors and filter
+    sensor:
+      - platform: wifi_signal # Reports the WiFi signal strength/RSSI in dB
+        name: "WiFi Signal dB"
+        id: wifi_signal_db
+        update_interval: 60s
+        entity_category: "diagnostic"
+        
+      - platform: copy # Reports the WiFi signal strength in %
+        source_id: wifi_signal_db
+        name: "WiFi Signal Percent"
+        filters:
+          - lambda: return min(max(2 * (x + 100.0), 0.0), 100.0);
+        unit_of_measurement: "Signal %"
+        entity_category: "diagnostic"
+
 Configuration variables:
 ------------------------
 

cookbook/mirabella-genio-bulb.rst

@@ -248,10 +248,6 @@ variable ``output_component1``.
 3.4 CWWW Mirabella Genio Downlights
 ***********************************
 
-Kmart also sell a `downlight option <https://www.kmart.com.au/product/mirabella-genio-wi-fi-dimmable-9w-led-downlight/2754331>`__, which works quite well however the PWM method that is used is different to the way the CWWW lights in ESPHome works.
-
-A `project by ssieb <https://github.com/ssieb/custom_components/tree/master/cwww2>`__ resolves this using a custom component.
-
 .. code-block:: yaml
 
     esphome:

devices/sonoff.rst

@@ -350,6 +350,28 @@ Sonoff Mini
     GPIO16, Optional sensor
 
 
+Sonoff THR316D
+--------------
+
+.. pintable::
+
+    GPIO0, Button,
+    GPIO21, Relay 1,
+    GPIO4, Relay 2,
+    GPIO27, Optionnal sensor power ON/OFF,
+    GPIO25, sensor,
+    GPIO16, Power LED,
+    GPIO15, Wifi LED (inverted),
+    GPIO13, Cycle LED (inverted),
+    GPIO23, Display Read,
+    GPIO18, Display Write,
+    GPIO5, Display Data,
+    GPIO17, Display CS,
+    
+    GPIO1, UART TX pin (for log)
+    GPIO3, UART RX pin (for log)
+
+
 Shelly 1
 --------
 

guides/configuration-types.rst

@@ -176,7 +176,24 @@ validating your configuration, ESPHome will automatically replace all occurrence
 by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or
 ``${substitution_key}`` (same).
 
-Additionally, you can use the YAML ``<<`` syntax to create a single YAML file from which a number
+Two substitution passes are performed allowing compound replacements.
+
+.. code-block:: yaml
+
+    substitutions:
+      foo: yellow
+      bar_yellow_value: !secret yellow_secret
+      bar_green_value: !secret green_secret
+    
+    something:
+      test: ${bar_${foo}_value}
+
+.. _YAML-insertion-operator:
+
+YAML insertion operator
+***********************
+
+Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number
 of nodes inherit:
 
 .. code-block:: yaml
@@ -210,6 +227,44 @@ of nodes inherit:
     - Place them in a subdirectory (dashboard only shows files in top-level directory)
     - Prepend a dot to the filename, like ``.base.yaml``
 
+.. _substitute-include-variables:
+
+Substitute !include variables
+*****************************
+
+ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file.
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: gpio
+        id: button1
+        pin: GPIO16
+        on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax
+      - platform: gpio
+        id: button2
+        pin: GPIO4
+        on_multi_click: !include
+          # multi-line syntax
+          file: on-multi-click.yaml
+          vars:
+            id: 2
+            
+``on-multi-click.yaml``:
+
+.. code-block:: yaml
+
+    - timing: !include click-single.yaml 
+      then:
+        - mqtt.publish:
+            topic: ${device_name}/button${id}/status
+            payload: single
+    - timing: !include click-double.yaml
+      then:
+        - mqtt.publish:
+            topic: ${device_name}/button${id}/status
+            payload: double
+
 .. _command-line-substitutions:
 
 Command line substitutions

guides/faq.rst

@@ -385,7 +385,7 @@ And a docker compose file looks like this:
 
 Notes on disabling mDNS
 ------------------------------------------------------------------------------
-Some of ESPHome's functionalities rely on mDNS, so naturally :ref:`disabling <wifi-configuration_variables>` it will cause these features to stop working.
+Some of ESPHome's functionalities rely on mDNS, so naturally :doc:`disabling </components/mdns>` it will cause these features to stop working.
 Generally speaking, disabling mDNS without setting a :ref:`static IP address <wifi-manual_ip>` (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.

guides/getting_started_hassio.rst

@@ -76,6 +76,10 @@ The configuration files for ESPHome can be found and edited under ``<HOME_ASSIST
 For example the configuration for the ``garage-door`` node in the picture above can be found
 in ``/config/esphome/garage-door.yaml``.
 
+.. note::
+
+    Since Home Assistant add-ons run as indvidual containers, accessing these through command line is not very straightforward, but it's possible. To do that, install Home Assistant's SSH addon, configure a username and a password, and disable `Protection Mode` (please assess the risks you take with that). Then, for example to access the logs form a device through an SSH client, log in, and you can use a command like `docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/garage-door.yaml`. See :doc:`getting_started_command_line` for more.
+
 Now go ahead and use one of the :ref:`devices guides <devices>` to extend your configuration.
 
 Adding some (basic) features

guides/supporters.rst

@@ -897,4 +897,4 @@ Contributors
 - `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__
 - `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
 
-*This page was last updated November 23, 2022.*
+*This page was last updated November 24, 2022.*

images/rp2040.svg

@@ -1,62 +1 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" id="svg8" width="409.873" height="94.488" version="1.1" viewBox="0 0 108.446 25"><metadata id="metadata5"/><g id="layer1"><path id="rect833" style="stroke-width:.133497" d="m 5,0 h 98.44565 c 2.77,0 5,2.23 5,5 v 15 c 0,2.77 -2.23,5 -5,5 H 5 C 2.23,25 0,22.77 0,20 V 5 C 0,2.23 2.23,0 5,0 Z"/><g id="text837" aria-label="RP2040" style="font-size:10.5833px;line-height:1.25;letter-spacing:1.08479px;fill:#fffffc;stroke-width:.264583"><path d="m 15.353522,20.665705 -2.686758,-3.973693 h -1.44498 v 3.973693 H 5.8934233 V 4.8612442 h 7.6087187 q 2.190047,0 3.815649,0.7224896 1.625601,0.7224896 2.506135,2.0771577 0.880535,1.354668 0.880535,3.1608925 0,1.693335 -0.767646,2.957691 -0.767645,1.264357 -2.212624,2.009425 l 3.318937,4.876805 z m -0.02258,-9.843921 q 0,-0.8805346 -0.541867,-1.3546684 -0.541865,-0.4967117 -1.6256,-0.4967117 h -1.941691 v 3.7027591 h 1.941691 q 1.083735,0 1.625602,-0.474134 0.541867,-0.496711 0.541867,-1.377245 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path414"/><path d="m 31.407412,4.8612442 q 2.190046,0 3.815648,0.7224896 1.625602,0.7224896 2.506136,2.0771577 0.880534,1.354668 0.880534,3.1608925 0,1.806224 -0.880534,3.160892 -0.880534,1.354668 -2.506136,2.077157 -1.625602,0.72249 -3.815648,0.72249 h -2.280358 v 3.883382 H 23.798693 V 4.8612442 Z m -0.338667,7.8119188 q 1.083734,0 1.625601,-0.474134 0.541868,-0.496711 0.541868,-1.377245 0,-0.8805346 -0.541868,-1.3546684 -0.541867,-0.4967117 -1.625601,-0.4967117 h -1.941691 v 3.7027591 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path416"/><path d="m 48.228949,16.533967 h 5.328361 v 4.131738 H 40.891163 v -3.273781 l 5.712184,-5.283206 q 0.745067,-0.699912 0.993423,-1.196623 0.248356,-0.496712 0.248356,-0.9708456 0,-0.5870228 -0.4064,-0.9031121 -0.383823,-0.338667 -1.12889,-0.338667 -0.72249,0 -1.354668,0.3838226 -0.632179,0.3838227 -0.970846,1.0837341 L 39.965474,8.1576031 q 0.903112,-1.693335 2.641602,-2.6641805 1.738491,-0.9934232 4.199471,-0.9934232 1.873958,0 3.318937,0.6096006 1.444979,0.6096006 2.25778,1.7384907 0.812801,1.12889 0.812801,2.5964471 0,1.3095122 -0.564445,2.4609802 -0.541867,1.12889 -2.144891,2.573869 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path418"/><path d="m 62.882996,21.02695 q -2.099736,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528714,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.92569,-1.8739574 2.528714,-2.8448029 1.625601,-0.9934232 3.725337,-0.9934232 2.099735,0 3.702759,0.9934232 1.625602,0.9708455 2.528714,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.903112,1.85138 -2.528714,2.844803 -1.603024,0.970846 -3.702759,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path420"/><path d="m 85.665039,13.824631 h 2.099735 v 4.131738 h -2.099735 v 2.709336 h -5.170317 v -2.709336 h -8.195741 v -3.38667 l 6.705606,-9.7084548 h 5.463828 l -5.960539,8.9633868 h 2.144891 v -2.415825 h 5.012272 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path422"/><path d="m 96.751789,21.02695 q -2.099735,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528713,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.925689,-1.8739574 2.528713,-2.8448029 1.625602,-0.9934232 3.725337,-0.9934232 2.099736,0 3.702761,0.9934232 1.6256,0.9708455 2.52871,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.90311,1.85138 -2.52871,2.844803 -1.603025,0.970846 -3.702761,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z" style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'" id="path424"/></g></g></svg>
-<svg
-   width="108.44565mm"
-   height="25.000002mm"
-   viewBox="0 0 108.44565 25.000002"
-   version="1.1"
-   id="svg8"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:dc="http://purl.org/dc/elements/1.1/">
-  <defs
-     id="defs2" />
-  <metadata
-     id="metadata5">
-    <rdf:RDF>
-      <cc:Work
-         rdf:about="">
-        <dc:format>image/svg+xml</dc:format>
-        <dc:type
-           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-      </cc:Work>
-    </rdf:RDF>
-  </metadata>
-  <g
-     id="layer1">
-    <path
-       id="rect833"
-       style="stroke-width:0.133497"
-       d="m 5,0 h 98.44565 c 2.77,0 5,2.23 5,5 v 15 c 0,2.77 -2.23,5 -5,5 H 5 C 2.23,25 0,22.77 0,20 V 5 C 0,2.23 2.23,0 5,0 Z" />
-    <g
-       aria-label="RP2040"
-       id="text837"
-       style="font-size:10.5833px;line-height:1.25;letter-spacing:1.08479px;fill:#fffffc;stroke-width:0.264583">
-      <path
-         d="m 15.353522,20.665705 -2.686758,-3.973693 h -1.44498 v 3.973693 H 5.8934233 V 4.8612442 h 7.6087187 q 2.190047,0 3.815649,0.7224896 1.625601,0.7224896 2.506135,2.0771577 0.880535,1.354668 0.880535,3.1608925 0,1.693335 -0.767646,2.957691 -0.767645,1.264357 -2.212624,2.009425 l 3.318937,4.876805 z m -0.02258,-9.843921 q 0,-0.8805346 -0.541867,-1.3546684 -0.541865,-0.4967117 -1.6256,-0.4967117 h -1.941691 v 3.7027591 h 1.941691 q 1.083735,0 1.625602,-0.474134 0.541867,-0.496711 0.541867,-1.377245 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path414" />
-      <path
-         d="m 31.407412,4.8612442 q 2.190046,0 3.815648,0.7224896 1.625602,0.7224896 2.506136,2.0771577 0.880534,1.354668 0.880534,3.1608925 0,1.806224 -0.880534,3.160892 -0.880534,1.354668 -2.506136,2.077157 -1.625602,0.72249 -3.815648,0.72249 h -2.280358 v 3.883382 H 23.798693 V 4.8612442 Z m -0.338667,7.8119188 q 1.083734,0 1.625601,-0.474134 0.541868,-0.496711 0.541868,-1.377245 0,-0.8805346 -0.541868,-1.3546684 -0.541867,-0.4967117 -1.625601,-0.4967117 h -1.941691 v 3.7027591 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path416" />
-      <path
-         d="m 48.228949,16.533967 h 5.328361 v 4.131738 H 40.891163 v -3.273781 l 5.712184,-5.283206 q 0.745067,-0.699912 0.993423,-1.196623 0.248356,-0.496712 0.248356,-0.9708456 0,-0.5870228 -0.4064,-0.9031121 -0.383823,-0.338667 -1.12889,-0.338667 -0.72249,0 -1.354668,0.3838226 -0.632179,0.3838227 -0.970846,1.0837341 L 39.965474,8.1576031 q 0.903112,-1.693335 2.641602,-2.6641805 1.738491,-0.9934232 4.199471,-0.9934232 1.873958,0 3.318937,0.6096006 1.444979,0.6096006 2.25778,1.7384907 0.812801,1.12889 0.812801,2.5964471 0,1.3095122 -0.564445,2.4609802 -0.541867,1.12889 -2.144891,2.573869 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path418" />
-      <path
-         d="m 62.882996,21.02695 q -2.099736,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528714,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.92569,-1.8739574 2.528714,-2.8448029 1.625601,-0.9934232 3.725337,-0.9934232 2.099735,0 3.702759,0.9934232 1.625602,0.9708455 2.528714,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.903112,1.85138 -2.528714,2.844803 -1.603024,0.970846 -3.702759,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path420" />
-      <path
-         d="m 85.665039,13.824631 h 2.099735 v 4.131738 h -2.099735 v 2.709336 h -5.170317 v -2.709336 h -8.195741 v -3.38667 l 6.705606,-9.7084548 h 5.463828 l -5.960539,8.9633868 h 2.144891 v -2.415825 h 5.012272 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path422" />
-      <path
-         d="m 96.751789,21.02695 q -2.099735,0 -3.725337,-0.970846 -1.603024,-0.993423 -2.528713,-2.844803 -0.903112,-1.873957 -0.903112,-4.447827 0,-2.573869 0.903112,-4.4252485 0.925689,-1.8739574 2.528713,-2.8448029 1.625602,-0.9934232 3.725337,-0.9934232 2.099736,0 3.702761,0.9934232 1.6256,0.9708455 2.52871,2.8448029 0.92569,1.8513795 0.92569,4.4252485 0,2.57387 -0.92569,4.447827 -0.90311,1.85138 -2.52871,2.844803 -1.603025,0.970846 -3.702761,0.970846 z m 0,-4.267205 q 1.806224,0 1.806224,-3.996271 0,-3.9962703 -1.806224,-3.9962703 -1.806224,0 -1.806224,3.9962703 0,3.996271 1.806224,3.996271 z"
-         style="font-weight:900;font-size:22.5778px;font-family:Montserrat;-inkscape-font-specification:'Montserrat Heavy'"
-         id="path424" />
-    </g>
-  </g>
-</svg>