diff --git a/components/climate/pid.rst b/components/climate/pid.rst index 4b9539d53..37419b7dc 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -12,6 +12,20 @@ PID controllers are good at modulating an output signal to get a sensor reading setpoint. For example, it can be used to modulate the power of a heating unit to get the temperature to a user-specified setpoint. +.. note:: + + PID is like cruise control in the cars: it keeps the car's speed constant by continuously + adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill, + the system notices the load increase thus immediately gives more fuel to the engine; and when it + goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel + completely so that car speed remains as constant as possible. The calculation takes in consideration + constants like car weight, wind resistance etc. + + This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help + determining such constants, which mainly describe the heat loss of the room or building. Goal is to + keep the temperature as constant as possible, and smooth out oscillations otherwise produced by + classic thermostats. + Explaining how PID controllers work in detail is out of scope of this documentation entry, but there's a nice article explaining the function principle `here `__. @@ -110,7 +124,7 @@ To set up a PID climate controller, you need a couple of components: .. note:: The sensor should have a short update interval. The PID update frequency is tied to the update - interval of the sensor. Set a short ``update_interval`` like ``1s`` on the sensor. + interval of the sensor. Set a short ``update_interval`` like ``5s`` on the sensor. We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and using ``output_averaging_samples`` to calm the PID sensor from a noisy input sensor. @@ -210,33 +224,39 @@ To autotune the control parameters: ki: 0.0 kd: 0.0 -2. Create a :doc:`template switch ` to start autotuning later: +2. Create a :doc:`template button ` to start autotuning later: .. code-block:: yaml - switch: + button: - platform: template name: "PID Climate Autotune" - turn_on_action: + on_press: - climate.pid.autotune: pid_climate 3. Compile & Upload the new firmware. -Now you should have a climate entity called "PID Climate Controller" and a switch called -"PID Climate Autotune" visible in your frontend of choice. +Now you should have a climate entity called *PID Climate Controller* and a button called +*PID Climate Autotune* visible in your frontend of choice. The autotune algorithm works by repeatedly switching the heat/cool output to full power and off. -This induced an oscillation of the observed temperature and the measured period and amplitude -is automatically calculated. +This induces an oscillation of the observed temperature and the measured period and amplitude +is automatically calculated. To do this, it needs to observe at least 3 oscillation cycles. -But this also means you **have to set the setpoint** of the climate controller to a value the -device can reach. For example if the temperature of a room is to be controlled, the setpoint needs -to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the -climate device should be set to at least ~24°C so that an oscillation can be induced. +.. note:: -4. Set an appropriate setpoint (see above). + You **have to set the setpoint** of the climate controller to a value the + device can reach. For example if the temperature of a room is to be controlled, the setpoint needs + to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the + climate device should be set to at least ~24°C so that an oscillation can be induced. + + Also take care of external influences, like for example when room temperature is severely affected by + outdoor weather like sun, if it starts to warm up the room in parallel with the heating + autotune will likely fail or give false results. -5. Click on the "PID Climate Autotune" and view the logs of the device. +4. Set an appropriate setpoint (see note above) and turn on the climate controller (Heat, Cool or Auto). + +5. Click the *PID Climate Autotune* button and look at the the logs of the device. You should see output like @@ -250,11 +270,15 @@ climate device should be set to at least ~24°C so that an oscillation can be in Detected 5 zero-crossings # ... - For example, in the output above, the autotuner is driving the heating output at 100% - and trying to reach 24.25 °C. +.. note:: - This will continue for some time until data for 6 phases (or a bit more, depending on the data - quality) have been acquired. + In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C. + + This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on + the data quality) have been acquired. + + The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the + heating up and cooling down oscillations the required number of times. 6. When the PID autotuner has succeeded, output like the one below can be seen: @@ -264,7 +288,6 @@ climate device should be set to at least ~24°C so that an oscillation can be in State: Succeeded! All checks passed! Calculated PID parameters ("Ziegler-Nichols PID" rule): - Calculated PID parameters ("Ziegler-Nichols PID" rule): control_parameters: kp: 0.49460 @@ -272,9 +295,11 @@ climate device should be set to at least ~24°C so that an oscillation can be in kd: 12.56301 Please copy these values into your YAML configuration! They will reset on the next reboot. - # ... - Copy the values in ``control_parameters`` into your configuration. +As soon as the the autotune procedure finishes, the climate starts to work with the calculated parameters +so that expected operation can be immediately verified. + +If satisfied, copy the values in ``control_parameters`` into your configuration: .. code-block:: yaml @@ -286,10 +311,14 @@ climate device should be set to at least ~24°C so that an oscillation can be in ki: 0.00487 kd: 12.56301 +The *PID Climate Autotune* button can be removed from the config, if the results are satisfactory, +it's not needed anymore. + 7. Complete, compile & upload the updated firmware. - If the calculated PID parameters are not good, you can try some of the alternative parameters - printed below the main control parameters in the log output. +If the calculated PID parameters are not good, you can try some of the alternative parameters +printed below the main control parameters in the log output. + ``climate.pid.autotune`` Action ------------------------------- @@ -316,9 +345,14 @@ Configuration variables: of the PID controller must be able to reach this value. Defaults to ``0.25``. - **positive_output** (*Optional*, float): The positive output power to drive the heat output at. Defaults to ``1.0``. -- **negative_output** (*Optional*, float): The positive output power to drive the cool output at. +- **negative_output** (*Optional*, float): The negative output power to drive the cool output at. Defaults to ``-1.0``. +The ``positive_output`` and ``negative_output`` parameters can be used to compensate the heating or the +cooling process during the autotune, in the cases when they are not changing the temperature at the +same rate, resulting in a not symmetrical oscillation. The autotune result will print a message when +it's recommended to repeat the entire procedure with such parameters configured. + ``climate.pid.set_control_parameters`` Action --------------------------------------------- @@ -402,6 +436,7 @@ See Also Proceedings of IFAC 9th World Congress, Budapest, 1867-1872 - :doc:`/components/climate/index` - :doc:`/components/output/slow_pwm` +- `Principles of PID `__ - :apiref:`pid/pid_climate.h` -- :apiref:`PID Autotuner ` +- :apiref:`PID Autotuner ` - :ghedit:`Edit` diff --git a/custom/custom_component.rst b/custom/custom_component.rst index 7b65840e1..f623bde8f 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -123,7 +123,7 @@ Home Assistant, as well as starting services in Home Assistant. } }; -See also :apiclass:`CustomAPIDevice`. +See also :apiclass:`api::CustomAPIDevice`. MQTT Custom Component ---------------------