98 lines
4.5 KiB
ReStructuredText
98 lines
4.5 KiB
ReStructuredText
Bang Bang Climate Controller
|
|
============================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up Bang Bang climate controllers with ESPHome.
|
|
:image: air-conditioner.png
|
|
|
|
The ``bang_bang`` climate platform allows you to regulate a value with a
|
|
`bang-bang controller <https://en.wikipedia.org/wiki/Bang%E2%80%93bang_control>`__ (also called hysteresis controller).
|
|
|
|
The operation principle of a bang_bang controller is quite simple. First, you specify an observable
|
|
value (for example the temperature of a room). The controller will try to keep this observed value
|
|
in a defined range. To do this, the controller can activate objects like a heating unit to change
|
|
the observed value.
|
|
|
|
The range that the controller will try to keep the observed value in can be controlled through the
|
|
front-end with the ``target_temperature_low`` and ``target_temperature_high`` values (see screenshot below).
|
|
As soon as the observed temperature dips below or above this range it will activate one of the
|
|
defined actions ``cool_action``, ``heat_action`` and ``idle_action``.
|
|
|
|
There are three types of bang bang controllers this platform can represent:
|
|
|
|
- **Heaters**: For devices where the observed temperature can only be increased.
|
|
|
|
- As soon as the temperature goes below the lower target temperature, ``heat_action`` will be called.
|
|
- When the temperature goes above the higher temperature, ``idle_action`` will be called.
|
|
|
|
- **Coolers**: For devices where the observed temperature can only be decreased.
|
|
|
|
- As soon as the temperature goes above the higher target temperature, ``cool_action`` will be called.
|
|
- When the temperature goes below the lower temperature, ``idle_action`` will be called.
|
|
|
|
- **Heater+Cooler**: For devices where the temperature can both actively be increased and decreased.
|
|
|
|
- When the current temperature is below the lower target temperature, ``heat_action`` is called.
|
|
- When the current temperature is within the target temperature range, ``idle_action`` is called.
|
|
- When the current temperature is above the higher target temperature, ``cool_action`` is called.
|
|
|
|
Do note that the actions are only called when the current temperature leaves the target temperature range.
|
|
|
|
.. figure:: images/climate-ui.png
|
|
:align: center
|
|
:width: 60.0%
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
climate:
|
|
- platform: bang_bang
|
|
sensor: my_temperature_sensor
|
|
default_target_temperature_low: 20 °C
|
|
default_target_temperature_high: 22 °C
|
|
|
|
heat_action:
|
|
- switch.turn_on: heater
|
|
idle_action:
|
|
- switch.turn_off: heater
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
|
|
- **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
|
|
the control algorithm. This can be dynamically set in the frontend later.
|
|
- **idle_action** (**Required**, :ref:`Action <config-action>`): The action to call when
|
|
the climate device wants to enter idle mode.
|
|
- **heat_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
|
|
the climate device wants to heating mode and increase the current temperature. At least one
|
|
of ``heat_action`` and ``cool_action`` need to be specified.
|
|
- **cool_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
|
|
the climate device wants to cooling mode and decrease the current temperature.
|
|
|
|
Advanced options:
|
|
|
|
- **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 during nighttime)
|
|
|
|
- **default_target_temperature_low** (**Required**, float): The default low target temperature for
|
|
the control algorithm during away mode.
|
|
- **default_target_temperature_high** (**Required**, float): The default high target temperature for
|
|
the control algorithm during away mode.
|
|
|
|
.. note::
|
|
|
|
While this platform uses the term temperature everywhere, it can also be used for other values.
|
|
For example, controlling humidity is also possible with this platform.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :doc:`/components/binary_sensor/index`
|
|
- :ref:`config-pin_schema`
|
|
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
|
|
- :ghedit:`Edit`
|