From 73108cf7a9ebb4560f9bf7e06992f2d71641b777 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Sun, 26 Jul 2020 15:58:06 -0500 Subject: [PATCH] Update bang_bang doc, changelog fix (#667) Co-authored-by: Otto Winter --- changelog/v1.15.0.rst | 2 +- components/climate/bang_bang.rst | 94 ++++++++++++++++++++++++++++++- components/climate/thermostat.rst | 5 ++ 3 files changed, 97 insertions(+), 4 deletions(-) diff --git a/changelog/v1.15.0.rst b/changelog/v1.15.0.rst index c2e4cb293..91e1b856d 100644 --- a/changelog/v1.15.0.rst +++ b/changelog/v1.15.0.rst @@ -75,7 +75,7 @@ Notable Changes & New Features - Dashboard Interface Revamped - New Thermostat Controller implements ESPHome actions for all available Home Assistant climate actions, - climate modes, fan modes, and fan swing modes (#1061) + climate modes, fan modes, and fan swing modes (:esphomepr:`1105`) - Color (and grayscale) display support! (#1050) - SSD1325 component updated to facilitate use of grayscale diff --git a/components/climate/bang_bang.rst b/components/climate/bang_bang.rst index 7d4b194de..8dba520f7 100644 --- a/components/climate/bang_bang.rst +++ b/components/climate/bang_bang.rst @@ -8,7 +8,14 @@ Bang Bang Climate Controller The ``bang_bang`` climate platform allows you to regulate a value with a `bang-bang controller `__ (also called hysteresis controller). -The operation principle of a bang_bang controller is quite simple. First, you specify an observable +.. note:: + + A number of people have asked about the behavior of the bang-bang controller. In version 1.15, a + :doc:`thermostat ` component was added which behaves more like a common thermostat; it is + essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below + if you are not sure which is appropriate for your application. + +The bang-bang controller's principle of operation 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. @@ -57,8 +64,8 @@ Do note that the actions are only called when the current temperature leaves the idle_action: - switch.turn_off: heater -Configuration variables: ------------------------- +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 @@ -90,6 +97,87 @@ Advanced options: 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. +Bang-bang vs. Thermostat +------------------------ + +The behavior of the bang-bang controller is a topic that has surfaced on the ESPHome Discord server +countless times -- many people have been confused by what it does. While they are similar, there are +two key differences between the bang-bang component and the :doc:`thermostat ` component: + +- When actions are triggered +- How the set points are used by the controller + +Now is a good time to ensure you understand exactly how a bang-bang controller should behave; if you do not have +a clear understanding of this, be sure to check out the +`Wikipedia article `__. + +The Problem with Dual-Function Systems +************************************** + +If you are not attempting to operate a system that can both heat and cool, you'll likely want to skip to the next +section about user interface. + +As outlined above, in general: + +- As soon as the temperature goes below the *lower* target temperature, ``heat_action`` is called to activate heating. +- Heating will continue until the temperature reaches the *upper* target temperature, at which point ``idle_action`` is called to stop heating. +- As soon as the temperature goes above the *upper* target temperature, ``cool_action`` is called to activate cooling. +- Cooling will continue until the temperature reaches the *lower* target temperature, at which point ``idle_action`` is called to stop cooling. + +A single bang-bang controller may work well for systems that only heat or only cool; however, it begins to break down +when applied to systems that may both heat *and* cool. This is simply because both actions are tied to both set +points -- that is, the point at which heating stops *is also the point at which cooling begins*. The reverse is also +true: the point at which cooling stops *is also the point at which heating begins*. Let's look at an example: + +Consider a system that both heats and cools. The ``target_temperature_low`` set point is 20 °C while the +``target_temperature_high`` set point is 22 °C. The sensor reports that the temperature is 19.75 °C, so the controller +calls ``heat_action`` to activate heating. Heating continues until the temperature reaches ``target_temperature_high`` +(22 °C in this case). Once this temperature is achieved, ``idle_action`` is called to stop heating. *However*, should +temperature drift even slightly above ``target_temperature_high``--even just a fraction of a degree for a fraction of +a second--the controller will call ``cool_action`` to begin cooling. Now, cooling will continue until +``target_temperature_low`` is reached again, but, as before, should the temperature drift even slightly below +``target_temperature_low`` for even a fraction of a second, ``heat_action`` will be invoked again, and the cycle will +repeat. It will "ping-pong" between the two set points, potentially forever. Oscillation at the "edges" of the +hysteresis window, or going past the set point in either direction, should be expected; consider, for example, a heater +that is turned off after it reaches its set point. The heating element will remain hot (potentially for quite a while), +and as such will continue to heat the air until the element fully cools down to match the ambient air/room temperature. + +The :doc:`thermostat ` component differs in that there is hysteresis around *each* set point. For example, +if the ``target_temperature_low`` set point is 20 °C, and the (default) hysteresis value of 0.5 °C is used, +``heat_action`` is called at a temperature of 19.5 °C and ``idle_action`` is called at 20.5 °C. If cooling, as defined +by ``target_temperature_high``, is set to 22 °C, ``cool_action`` would be called at 22.5 °C and ``idle_action`` called +at 21.5 °C. Again, it is essentially two bang-bang controllers in one. + +Behavioral differences aside, there is another important difference between these two components: user interface. + +User Interface +************** + +The interaction with this component via the Home Assistant user interface is also different than what is seen on most +common residential thermostats. Generally speaking, most thermostats allow either one or two set points -- one of them +is associated with heating while the other with cooling, and this is exactly how the :doc:`thermostat ` +component uses them. If you set the "heat" set point to 20 °C, most people assume this means the heating system will +keep the temperature as close to 20 °C as possible. The same is true for the upper set point, for cooling: if you set +a temperature of 22 °C, most people assume the cooling system will keep the temperature as close to 22 °C as possible. + +The bang-bang controller does not use the set points this way. If you set the lower set point to 20 °C and set the +upper set point to 22 °C, then *the temperature will be brought as high as 22 °C but go no lower than 20 °C.* + +The behavior is not difficult to understand, but, as we've learned from many discussions on the Discord server, it +departs from what most people seem to expect. + +Which is Right for Me? +********************** + +It comes down to two points: + +- If you have a dual-function system (both heating and cooling), you'll almost certainly want to use the + :doc:`thermostat ` component. +- If you have a single-function system *and* have a specific need or desire to manually control both the upper and + lower bounds for hysteresis, use the bang-bang controller. + +In all other situations, the :doc:`thermostat ` component is probably best. + See Also -------- diff --git a/components/climate/thermostat.rst b/components/climate/thermostat.rst index cf4a2361a..47943879e 100644 --- a/components/climate/thermostat.rst +++ b/components/climate/thermostat.rst @@ -270,6 +270,11 @@ Advanced Options While this platform uses the term temperature everywhere, it can also be used to regulate other values. For example, controlling humidity is also possible with this platform. +Bang-bang vs. Thermostat +------------------------ + +Please see the :doc:`Bang-bang ` component's documentation for a detailed comparison of these two components. + See Also --------