Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-03-01 03:51:36 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #2519 from esphome/bump-2022.12.0b3

Browse Source 
2022.12.0b3
This commit is contained in:
Jesse Hills 2022-12-12 17:32:00 +13:00 committed by GitHub
commit c3ec3ee1d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 73 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxygen
View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 2022.12.0b2
PROJECT_NUMBER = 2022.12.0b3
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a

2
Makefile
View File

@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
ESPHOME_REF = 2022.12.0b2
ESPHOME_REF = 2022.12.0b3
.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

2
_static/version
View File

@ -1 +1 @@
2022.12.0b2
2022.12.0b3

1
changelog/2022.12.0.rst
View File

@ -50,6 +50,7 @@ Beta Changes
^^^^^^^^^^^^
- Fix ble parsing with zero padded advertisements :esphomepr:`4162` by :ghuser:`jesserockz`
- Increase watchdog timeout when starting OTA :esphomepr:`4172` by :ghuser:`jesserockz`
All changes
^^^^^^^^^^^

85
components/climate/pid.rst
View File

@ -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 <https://blog.opticontrols.com/archives/344>`__.
@ -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 </components/switch/template>` to start autotuning later:
2. Create a :doc:`template button </components/button/template>` 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 <https://blog.opticontrols.com/archives/344>`__
- :apiref:`pid/pid_climate.h`
- :apiref:`PID Autotuner <pid/pid_autotune.h>`
- :apiref:`PID Autotuner <pid/pid_autotuner.h>`
- :ghedit:`Edit`

2
conf.py
View File

@ -69,7 +69,7 @@ author = "ESPHome"
# The short X.Y version.
version = "2022.12"
# The full version, including alpha/beta/rc tags.
release = "2022.12.0b2"
release = "2022.12.0b3"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

2
custom/custom_component.rst
View File

@ -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
---------------------

5
guides/creators.rst
View File

@ -40,6 +40,7 @@ Example configuration
# This should point to the public location of this yaml file.
dashboard_import:
package_import_url: github://esphome/esphome-project-template/project-template-esp32.yaml@v6
import_full_config: false # or true
wifi:
# Set up a wifi access point
@ -72,9 +73,11 @@ Relevant Documentation
- ``wifi`` -> ``ap`` allows you to flash a device that will not contain any
credentials and they must be set by the user via either the ``ap`` + ``captive_portal`` or
the ``esp32_improv`` / ``improv_serial`` components.
- ``dashboard_import`` -> ``package_import_url`` - This should point to the public repository containing
- ``dashboard_import``
- ``package_import_url`` - This should point to the public repository containing
the configuration for the device so that the user's ESPHome dashboard can autodetect this device and
create a minimal YAML using :ref:`config-git_packages`.
- ``import_full_config`` - This signals if ESPHome should download the entire YAML file as the user's config YAML instead of referencing the package. Set this to `true` if you are creating a tutorial to let users easily tweak the whole configuration or be able to uncomment follow-up tutorial steps.
- ``improv_serial`` - :doc:`/components/improv_serial`
See Also

6
guides/supporters.rst
View File

@ -190,7 +190,6 @@ Contributors
- `Alex Solomaha (@CyanoFresh) <https://github.com/CyanoFresh>`__
- `Luar Roji (@cyberplant) <https://github.com/cyberplant>`__
- `Aleš Komárek (@cznewt) <https://github.com/cznewt>`__
- `d-two (@d-two) <https://github.com/d-two>`__
- `Dale Higgs (@dale3h) <https://github.com/dale3h>`__
- `damanti-me (@damanti-me) <https://github.com/damanti-me>`__
- `Daniel Bjørnbakk (@danibjor) <https://github.com/danibjor>`__
@ -608,6 +607,7 @@ Contributors
- `mnltake (@mnltake) <https://github.com/mnltake>`__
- `Matt N. (@mnoorenberghe) <https://github.com/mnoorenberghe>`__
- `Moritz Glöckl (@moritzgloeckl) <https://github.com/moritzgloeckl>`__
- `Chris Laplante (@mostthingsweb) <https://github.com/mostthingsweb>`__
- `Matthew Pettitt (@mpettitt) <https://github.com/mpettitt>`__
- `Sam Hughes (@MrEditor97) <https://github.com/MrEditor97>`__
- `Mariusz Kryński (@mrk-its) <https://github.com/mrk-its>`__
@ -887,13 +887,13 @@ Contributors
- `Wolfgang Tremmel (@wtremmel) <https://github.com/wtremmel>`__
- `Wumpf (@Wumpf) <https://github.com/Wumpf>`__
- `wysiwyng (@wysiwyng) <https://github.com/wysiwyng>`__
- `Mike (@xsnoopy) <https://github.com/xsnoopy>`__
- `Yaroslav (@Yarikx) <https://github.com/Yarikx>`__
- `Marcin Jaworski (@yawor) <https://github.com/yawor>`__
- `Pavel (@yekm) <https://github.com/yekm>`__
- `Atsuko Ito (@yottatsa) <https://github.com/yottatsa>`__
- `Nico B (@youknow0) <https://github.com/youknow0>`__
- `Yuval Aboulafia (@yuvalabou) <https://github.com/yuvalabou>`__
- `Björn Stenberg (@zagor) <https://github.com/zagor>`__
- `david reid (@zathras777) <https://github.com/zathras777>`__
- `Zebble (@Zebble) <https://github.com/Zebble>`__
- `ZJY (@zhangjingye03) <https://github.com/zhangjingye03>`__
@ -904,4 +904,4 @@ Contributors
- `Zack Barett (@zsarnett) <https://github.com/zsarnett>`__
- `Christian Zufferey (@zuzu59) <https://github.com/zuzu59>`__
*This page was last updated December 8, 2022.*
*This page was last updated December 12, 2022.*