mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-14 01:21:33 +01:00
PID Climate Controller (#432)
* PID Climate Controller * fix lint * fix merge * lint Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>
This commit is contained in:
Otto Winter
GitHub
parent
a82137dfe9
commit
b717d1ef5d
@ -47,6 +47,7 @@ Do note that the actions are only called when the current temperature leaves the
|
||||
# Example configuration entry
|
||||
climate:
|
||||
- platform: bang_bang
|
||||
name: "Bang Bang Climate Controller"
|
||||
sensor: my_temperature_sensor
|
||||
default_target_temperature_low: 20 °C
|
||||
default_target_temperature_high: 22 °C
|
||||
@ -92,7 +93,6 @@ Advanced options:
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`/components/binary_sensor/index`
|
||||
- :ref:`config-pin_schema`
|
||||
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
|
||||
- :doc:`/components/climate/index`
|
||||
- :apiref:`bang_bang/bang_bang_climate.h`
|
||||
- :ghedit:`Edit`
|
||||
|
||||
255
components/climate/pid.rst
Normal file
255
components/climate/pid.rst
Normal file
@ -0,0 +1,255 @@
|
||||
PID Climate
|
||||
===========
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up PID climate controllers with ESPHome.
|
||||
:image: function.png
|
||||
|
||||
The ``pid`` climate platform allows you to regulate a value with a
|
||||
`PID controller <https://en.wikipedia.org/wiki/PID_controller>`__.
|
||||
|
||||
PID controllers are good at modulating an output signal to get a sensor reading to a specified
|
||||
setpoint. For example, it can be used to modulate the power of a heating unit to get the
|
||||
temperature to a user-specified setpoint.
|
||||
|
||||
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 <https://blog.opticontrols.com/archives/344>`__.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
climate:
|
||||
- platform: pid
|
||||
name: "PID Climate Controller"
|
||||
sensor: temperature_sensor
|
||||
default_target_temperature: 21°C
|
||||
heat_output: heater
|
||||
control_parameters:
|
||||
kp: 0.49460
|
||||
ki: 0.00487
|
||||
kd: 12.56301
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
|
||||
temperature.
|
||||
- **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>`
|
||||
that increases the current temperature. At least one of ``heat_output`` and ``cool_output`` must
|
||||
be specified.
|
||||
- **cool_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
|
||||
that decreases the current temperature. At least one of ``heat_output`` and ``cool_output`` must
|
||||
be specified.
|
||||
- **control_parameters** (**Required**): Control parameters of the PID controller.
|
||||
|
||||
- **kp** (**Required**, float): The factor for the proportional term of the PID controller.
|
||||
- **ki** (*Optional*, float): The factor for the integral term of the PID controller.
|
||||
Defaults to ``0``.
|
||||
- **kd** (*Optional*, float): The factor for the derivative term of the PID controller.
|
||||
Defaults to ``0``.
|
||||
- **min_integral** (*Optional*, float): The maximum value of the integral term multiplied by
|
||||
``ki`` to prevent windup. Defaults to ``-1``.
|
||||
- **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by
|
||||
``ki`` to prevent windup. Defaults to ``1``.
|
||||
|
||||
- All other options from :ref:`Climate <config-climate>`.
|
||||
|
||||
.. _pid-setup:
|
||||
|
||||
PID Controller Setup
|
||||
--------------------
|
||||
|
||||
To set up a PID climate controller, you need a couple of components:
|
||||
|
||||
- A :ref:`Sensor <config-sensor>` to read the current temperature (``sensor``).
|
||||
- At least one :ref:`float output <config-output>` to drive for heating or cooling (or both).
|
||||
This could for example be a PWM output via ``slow_pwm`` (TODO) that drives a heating unit.
|
||||
|
||||
Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state
|
||||
in between for example 50% heating power).
|
||||
|
||||
.. 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.
|
||||
|
||||
.. _pid-autotune:
|
||||
|
||||
Autotuning
|
||||
----------
|
||||
|
||||
Finding suitable ``kp``, ``ki`` and ``kd`` control parameters for the PID controller manually
|
||||
needs some experience with PID controllers. ESPHome has an auto-tuning algorithm that automatically
|
||||
finds suitable PID parameters to start using an adaption of the Ziegler-Nichols method with
|
||||
relay autotuning (Åström and Hägglund).
|
||||
|
||||
To autotune the control parameters:
|
||||
|
||||
1. Set up the PID controller with all control parameters set to zero:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
climate:
|
||||
- platform: pid
|
||||
id: pid_climate
|
||||
name: "PID Climate Controller"
|
||||
sensor: temperature_sensor
|
||||
default_target_temperature: 21°C
|
||||
heat_output: heater
|
||||
control_parameters:
|
||||
kp: 0.0
|
||||
ki: 0.0
|
||||
kd: 0.0
|
||||
|
||||
2. Create a :doc:`template switch </components/switch/template>` to start autotuning later:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
switch:
|
||||
- platform: template
|
||||
name: "PID Climate Autotune"
|
||||
turn_on_action:
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
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 a bit of 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.
|
||||
|
||||
4. Set an appropriate setpoint (see above).
|
||||
|
||||
5. Click on the "PID Climate Autotune" and view the logs of the device.
|
||||
|
||||
You should see output like
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
PID Autotune:
|
||||
Autotune is still running!
|
||||
Status: Trying to reach 24.25 °C
|
||||
Stats so far:
|
||||
Phases: 4
|
||||
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.
|
||||
|
||||
This will continue for some time until data for 6 phases (or a bit more, depending on the data
|
||||
quality) have been acquired.
|
||||
|
||||
6. When the PID autotuner has succeeded, output like the one below can be seen:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
PID Autotune:
|
||||
State: Succeeded!
|
||||
All checks passed!
|
||||
Calculated PID parameters ("Ziegler-Nichols PID" rule):
|
||||
Calculated PID parameters ("Ziegler-Nichols PID" rule):
|
||||
|
||||
control_parameters:
|
||||
kp: 0.49460
|
||||
ki: 0.00487
|
||||
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.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
climate:
|
||||
- platform: pid
|
||||
# ...
|
||||
control_parameters:
|
||||
kp: 0.49460
|
||||
ki: 0.00487
|
||||
kd: 12.56301
|
||||
|
||||
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.
|
||||
|
||||
``climate.pid.autotune`` Action
|
||||
-------------------------------
|
||||
|
||||
This action starts the autotune process of the PID controller.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
# Basic
|
||||
- climate.pid.autotune: pid_climate
|
||||
|
||||
# Advanced
|
||||
- climate.pid.autotune:
|
||||
id: pid_climate
|
||||
noiseband: 0.25
|
||||
positive_output: 25%
|
||||
negative_output: -25%
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (**Required**, :ref:`config-id`): ID of the PID Climate to start autotuning for.
|
||||
- **noiseband** (*Optional*, float): The noiseband of the process (=sensor) variable. The value
|
||||
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.
|
||||
Defaults to ``-1.0``.
|
||||
|
||||
PID Climate Sensor
|
||||
------------------
|
||||
|
||||
Additionally, the PID climate platform provides an optional sensor platform to monitor
|
||||
the calculated PID parameters to help finding good PID values.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
sensor:
|
||||
- platform: pid
|
||||
name: "PID Climate Result"
|
||||
type: RESULT
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **name** (**Required**, string): The name of the sensor
|
||||
- **type** (**Required**, string): The value to monitor. One of
|
||||
|
||||
- ``RESULT`` - The resulting value (sum of P, I, and D terms).
|
||||
- ``ERROR`` - The calculated error (setpoint - process_variable)
|
||||
- ``PROPORTIONAL`` - The proportional term of the PID controller.
|
||||
- ``INTEGRAL`` - The integral term of the PID controller.
|
||||
- ``DERIVATIVE`` - The derivative term of the PID controller.
|
||||
- ``HEAT`` - The resulting heating power to the supplied to the ``heat_output``.
|
||||
- ``COOL`` - The resulting cooling power to the supplied to the ``cool_output``.
|
||||
|
||||
Advanced options:
|
||||
|
||||
- **climate_id** (*Optional*, :ref:`config-id`): The ID of the pid climate to get the values from.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- Ziegler-Nichols Method: Nichols, N. B. and J. G. Ziegler (1942), 'Optimum settings for automatic
|
||||
controllers', Transactions of the ASME, 64, 759-768
|
||||
- Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators',
|
||||
Proceedings of IFAC 9th World Congress, Budapest, 1867-1872
|
||||
- :doc:`/components/climate/index`
|
||||
- :apiref:`pid/pid_climate.h`
|
||||
- :apiref:`PID Autotuner <pid/pid_autotune.h>`
|
||||
- :ghedit:`Edit`
|
||||
1
images/function.svg
Normal file
1
images/function.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><path d="M15.6 5.29c-1.1-.1-2.07.71-2.17 1.82L13.18 10H16v2h-3l-.44 5.07a3.986 3.986 0 0 1-4.33 3.63 4.007 4.007 0 0 1-3.06-1.87l1.5-1.5c.24.74.9 1.31 1.73 1.38 1.1.1 2.07-.71 2.17-1.82L11 12H8v-2h3.17l.27-3.07c.19-2.2 2.13-3.83 4.33-3.63 1.31.11 2.41.84 3.06 1.87l-1.5 1.5c-.24-.74-.9-1.31-1.73-1.38z"/></svg>
|
||||
|
After Width: | Height: | Size: 373 B |
@ -303,6 +303,7 @@ Climate Components
|
||||
Climate Core, components/climate/index, folder-open.svg
|
||||
Bang Bang Controller, components/climate/bang_bang, air-conditioner.svg
|
||||
Custom Climate, components/climate/custom, language-cpp.svg
|
||||
PID Controller, components/climate/pid, function.svg
|
||||
IR Remote Climate, components/climate/ir_climate, air-conditioner-ir.svg
|
||||
|
||||
Misc Components
|
||||
|
||||
Loading…
Reference in New Issue
Block a user