Thermostat enhancements 2 doc update (#1360)

components/climate/thermostat.rst

@@ -139,6 +139,7 @@ Examples:
 Got all that? Great. Let's take a closer look at some configuration.
 
 Configuration Variables:
+------------------------
 
 The thermostat controller uses the sensor to determine whether it should heat or cool.
 
@@ -182,15 +183,24 @@ These are triggered when the climate control **action** is changed by the thermo
   the climate device should enter its idle state (not cooling, not heating).
 - **heat_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
   the climate device should enter heating mode to increase the current temperature.
+- **supplemental_heating_action** (*Optional*, :ref:`Action <config-action>`): The action
+  to call when the climate device should activate supplemental heating to (more aggressively)
+  increase the current temperature. *This action is called repeatedly at an interval defined by*
+  ``max_heating_run_time`` *(see below).*
 - **cool_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
   the climate device should enter cooling mode to decrease the current temperature.
+- **supplemental_cooling_action** (*Optional*, :ref:`Action <config-action>`): The action
+  to call when the climate device should activate supplemental cooling to (more aggressively)
+  decrease the current temperature. *This action is called repeatedly at an interval defined by*
+  ``max_cooling_run_time`` *(see below).*
 - **dry_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
   the climate device should perform its drying (dehumidification) action. The thermostat
   controller does not trigger this action; it is invoked by ``dry_mode`` (see below).
 - **fan_only_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
-  the climate device should activate its fan only (but does not heat or cool). The thermostat
-  controller triggers this action based on the upper target temperature when set to
-  ``fan_only_mode`` (see below).
+  the climate device should activate its fan only (but does not heat or cool). When ``fan_only_cooling``
+  is set to ``false``, the thermostat controller immediately triggers this action when set to
+  ``fan_only_mode``; however, when ``fan_only_cooling`` is set to ``true``, this action is called
+  based on the upper target temperature (similar to ``cool_action`` above).
 - All other options from :ref:`Climate <config-climate>`.
 
 **At least one of** ``cool_action``, ``fan_only_action``, ``heat_action``, **and** ``dry_action``
@@ -266,13 +276,20 @@ These should be used to control the fan only, if available.
 - **swing_both_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
   should oscillate in horizontal and vertical directions.
 
-Advanced Options
-****************
+Advanced Configuration/Behavior:
+--------------------------------
 
-**Set Point Options/Behavior**
+Set Point Options/Behavior
+**************************
 
 - **set_point_minimum_differential** (*Optional*, float): For dual-point/dual-function systems, the minimum
-  required temperature difference between the heat and cool set points.
+  required temperature difference between the heat and cool set points. Defaults to 0.5 °C.
+- **supplemental_cooling_delta** (*Required with* ``supplemental_cooling_action``, float): When the temperature
+  difference between the upper set point and the current temperature exceeds this value,
+  ``supplemental_cooling_action`` will be called immediately.
+- **supplemental_heating_delta** (*Required with* ``supplemental_heating_action``, float): When the temperature
+  difference between the lower set point and the current temperature exceeds this value,
+  ``supplemental_heating_action`` will be called immediately.
 - **away_config** (*Optional*): Additionally specify target temperature range settings for away mode.
   Away mode can be used to have a second set of target temperatures (for example, while the user is
   away or sleeping/at night).
@@ -285,17 +302,56 @@ Advanced Options
 **If configured, at least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
 **must be specified in the away mode configuration.**
 
-**Additional Actions/Behavior**
+Additional Actions/Behavior
+***************************
 
+- **target_temperature_change_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the
+  thermostat's target temperature(s) is/are changed.
+- **startup_delay** (*Optional*, boolean): If set to ``true``, when ESPHome starts, ``min_cooling_off_time``,
+  ``min_fanning_off_time``, and ``min_heating_off_time`` must elapse before each respective action may be invoked.
+  This option provides a way to prevent damage to equipment (for example) disrupted by a power interruption.
+  Defaults to ``false``.
+- **fan_only_action_uses_fan_mode_timer** (*Optional*, boolean): If set to ``true``, the ``fan_only_action`` will
+  share the same delay timer used for all ``fan_mode`` actions. The minimum fan switching delay is then determined
+  by ``min_fan_mode_switching_time`` (see below). This is useful when ``fan_only_action`` controls the same physical
+  fan as the ``fan_mode`` actions, common in forced-air HVAC systems.
 - **fan_only_cooling** (*Optional*, boolean): If set to ``true``, when in the ``fan_only_mode`` climate mode,
   the ``fan_only_action`` will only be called when the observed temperature exceeds the upper set point plus
   ``cool_deadband``. When set to ``false`` (the default), ``fan_only_action`` is called immediately when
-  ``fan_only_mode`` is activated, regardless of the current temperature or set points.
-- **target_temperature_change_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the
-  thermostat's target temperature(s) is/are changed.
+  ``fan_only_mode`` is activated, regardless of the current temperature or set points. Defaults to ``false``.
+- **fan_with_cooling** (*Optional*, boolean): If set to ``true``, ``fan_only_action`` will be called whenever
+  ``cool_action`` is called. This is useful for forced-air systems where the fan typically runs with cooling.
+  Defaults to ``false``.
+- **fan_with_heating** (*Optional*, boolean): If set to ``true``, ``fan_only_action`` will be called whenever
+  ``heat_action`` is called. This is useful for forced-air systems where the fan typically runs with heating.
+  Defaults to ``false``.
+- **max_cooling_run_time** (*Required with* ``supplemental_cooling_action``, :ref:`config-time`): Duration after
+  which ``supplemental_cooling_action`` will be called when cooling is active. Note that
+  ``supplemental_cooling_action`` will be called repeatedly at an interval defined by this parameter, as well,
+  enabling multiple stages of supplemental (auxiliary/emergency) cooling.
+- **max_heating_run_time** (*Required with* ``supplemental_heating_action``, :ref:`config-time`): Duration after
+  which ``supplemental_heating_action`` will be called when heating is active. Note thermostat
+  ``supplemental_heating_action`` will be called repeatedly at an interval defined by this parameter, as well,
+  enabling multiple stages of supplemental (auxiliary/emergency) heating.
+- **min_cooling_off_time** (*Required with* ``cool_action``, :ref:`config-time`): Minimum duration the cooling action
+  must be disengaged before it may be engaged.
+- **min_cooling_run_time** (*Required with* ``cool_action``, :ref:`config-time`): Minimum duration the cooling action
+  must be engaged before it may be disengaged.
+- **min_fanning_off_time** (*Required with* ``fan_only_action``, :ref:`config-time`): Minimum duration the fanning
+  action must be disengaged before it may be engaged.
+- **min_fanning_run_time** (*Required with* ``fan_only_action``, :ref:`config-time`): Minimum duration the fanning
+  action must be engaged before it may be disengaged.
+- **min_heating_off_time** (*Required with* ``heat_action``, :ref:`config-time`): Minimum duration the heating action
+  must be disengaged before it may be engaged.
+- **min_heating_run_time** (*Required with* ``heat_action``, :ref:`config-time`): Minimum duration the heating action
+  must be engaged before it may be disengaged.
+- **min_idle_time** (*Required*, :ref:`config-time`): Minimum duration the idle action must be active before calling
+  another climate action.
+- **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.
 
-
-**Hysteresis Values**
+Hysteresis Values
+*****************
 
 - **cool_deadband** (*Optional*, float): The minimum temperature differential (temperature above the set point)
   before calling the cooling :ref:`action <config-action>`. Defaults to 0.5 °C.
@@ -305,11 +361,6 @@ Advanced Options
   before calling the heating :ref:`action <config-action>`. Defaults to 0.5 °C.
 - **heat_overrun** (*Optional*, float): The minimum temperature differential (heating beyond the set point)
   before calling the idle :ref:`action <config-action>`. Defaults to 0.5 °C.
-- **hysteresis** (*Optional*, float): This configuration option provides a one-line way to configure *all* "deadband"
-  and "overrun" values identified above. Note that the above configuration options each take precedence over this
-  value. *This option is deprecated and may be removed in a future release.*
-
-
 
 .. note::