Add humidity support to climate (#3359)

components/climate/bang_bang.rst

@@ -70,6 +70,8 @@ Configuration variables:
 ------------------------
 
 - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
+- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
+  This is used for information only and does not influence temperature control.
 - **default_target_temperature_low** (**Required**, float): The default low target temperature for
   the control algorithm. This can be dynamically set in the frontend later.
 - **default_target_temperature_high** (**Required**, float): The default high target temperature for

components/climate/index.rst

@@ -15,6 +15,10 @@ and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OF
 
     Climate Device UI in Home Assistant.
 
+.. note::
+
+    Not all climate components support all possible features. Check the corresponding documentation page for details on what is supported.
+
 .. _config-climate:
 
 Base Climate Configuration
@@ -30,6 +34,15 @@ All climate platforms in ESPHome inherit from the climate configuration schema.
           min_temperature: 18
           max_temperature: 25
           temperature_step: 0.1
+          min_humidity: 30%
+          max_humidity: 99%
+      - platform: ...
+        visual:
+          min_temperature: 18
+          max_temperature: 25
+          temperature_step:
+            target_temperature: 0.5
+            current_temperature: 0.1
 
 Configuration variables:
 
@@ -55,6 +68,11 @@ Configuration variables:
     - **target_temperature** (**Required**, float): The granularity for target temperature
     - **current_temperature** (**Required**, float): The granularity for current temperature
 
+  - **min_humidity** (*Optional*, percentage): The minimum humidity the climate device can reach.
+    Used to set the range of the frontend gauge.
+  - **max_humidity** (*Optional*, percentage): The maximum humidity the climate device can reach.
+    Used to set the range of the frontend gauge.
+
 Advanced options:
 
 - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
@@ -74,6 +92,8 @@ MQTT options:
   climate device action changes to.
 - **current_temperature_state_topic** (*Optional*, string): The topic to publish
   current temperature changes to.
+- **current_humidity_state_topic** (*Optional*, string): The topic to publish
+  current humidity 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
@@ -102,19 +122,12 @@ MQTT options:
   lower target temperature changes to.
 - **target_temperature_low_command_topic** (*Optional*, string): The topic to receive
   lower target temperature commands on.
+- **target_humidity_state_topic** (*Optional*, string): The topic to publish
+  target humidity changes to.
+- **target_humidity_command_topic** (*Optional*, string): The topic to receive
+  target humidity commands on.
 - All other options from :ref:`MQTT Component <config-mqtt-component>`.
 
-.. code-block:: yaml
-
-    climate:
-      - platform: ...
-        visual:
-          min_temperature: 18
-          max_temperature: 25
-          temperature_step:
-            target_temperature: 0.5
-            current_temperature: 0.1
-
 Climate Automation
 ------------------
 
@@ -152,6 +165,8 @@ Configuration variables:
   lower target temperature of a climate device with a two-point target temperature.
 - **target_temperature_high** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
   higher target temperature of a climate device with a two-point target temperature.
+- **target_humidity** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
+  target humidity of a climate device.
 - **preset** (*Optional*, string, :ref:`templatable <config-templatable>`): Set the preset
   of the climate device. One of ``ECO``, ``AWAY``, ``BOOST``, ``COMFORT``, ``HOME``, ``SLEEP``,
   ``ACTIVITY``.
@@ -181,12 +196,16 @@ advanced stuff.
       id(my_climate).mode
       // Current temperature, type: float (degrees)
       id(my_climate).current_temperature
+      // Current humidity, type: float (percentage)
+      id(my_climate).current_humidity
       // Target temperature, type: float (degrees)
       id(my_climate).target_temperature
       // Lower Target temperature, type: float (degrees)
       id(my_climate).target_temperature_low
       // High Target temperature, type: float (degrees)
       id(my_climate).target_temperature_high
+      // Target humidity, type: float (percentage)
+      id(my_climate).target_humidity
       // Fan mode, type: FanMode (enum)
       id(my_climate).fan_mode
       // Custom Fan mode, type: string

components/climate/pid.rst

@@ -53,6 +53,8 @@ Configuration variables:
 
 - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
   temperature.
+- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
+  This is used for information only and does not influence temperature control.
 - **default_target_temperature** (**Required**, float): The default target temperature (setpoint)
   for the control algorithm. This can be dynamically set in the frontend later.
 - **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`

components/climate/thermostat.rst

@@ -168,6 +168,8 @@ Configuration Variables:
 The thermostat controller uses the sensor to determine whether it should heat or cool.
 
 - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
+- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity.
+  This is used for information only and does not influence temperature control.
 
 Heating and Cooling Actions
 ***************************