From 00b2ff07d3a50d1ea4177e650ee4d0d10ac43309 Mon Sep 17 00:00:00 2001 From: Chris Laplante Date: Sun, 11 Dec 2022 11:34:55 -0500 Subject: [PATCH 1/6] Fix 'See also CustomAPIDevice.' link (#2516) --- custom/custom_component.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 --------------------- From 2522c8a92fb341ded7d4b31c44f970f8a9e7d24d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=2E=20=C3=81rkosi=20R=C3=B3bert?= Date: Sun, 11 Dec 2022 17:45:42 +0100 Subject: [PATCH 2/6] Update pid.rst (#2517) * Update pid.rst * Update pid.rst --- components/climate/pid.rst | 85 +++++++++++++++++++++++++++----------- 1 file changed, 60 insertions(+), 25 deletions(-) diff --git a/components/climate/pid.rst b/components/climate/pid.rst index add12f42c..60b3de5a1 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 `__. @@ -73,7 +87,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. .. _pid-autotune: @@ -103,33 +117,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 @@ -143,11 +163,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: @@ -157,7 +181,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 @@ -165,9 +188,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 @@ -179,10 +204,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 ------------------------------- @@ -209,9 +238,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 --------------------------------------------- @@ -295,6 +329,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` From a6b6a1f2cdd66b4358e93f69c520746ba733e36a Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Fri, 9 Dec 2022 10:24:37 +1300 Subject: [PATCH 3/6] Add import_full_config to creators page (#2513) Co-authored-by: Paulus Schoutsen --- guides/creators.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/guides/creators.rst b/guides/creators.rst index e41e9ac2b..05389b7ca 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -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 From d87db7a94539e6d3e440ac2119b13077e2b1f0d7 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 12 Dec 2022 17:19:14 +1300 Subject: [PATCH 4/6] Bump version to 2022.12.0b3 --- Doxygen | 2 +- Makefile | 2 +- _static/version | 2 +- conf.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doxygen b/Doxygen index 051cadfe5..ac5344a8a 100644 --- a/Doxygen +++ b/Doxygen @@ -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 diff --git a/Makefile b/Makefile index 83d53a843..9744925e2 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/_static/version b/_static/version index d1dbdb667..e56d22923 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.12.0b2 \ No newline at end of file +2022.12.0b3 \ No newline at end of file diff --git a/conf.py b/conf.py index 1b8b3facb..a031082b2 100644 --- a/conf.py +++ b/conf.py @@ -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. From 36c87d712b7ad6f24a6da531ef24d7218e56f663 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 12 Dec 2022 17:20:02 +1300 Subject: [PATCH 5/6] Update changelog for 2022.12.0b3 --- changelog/2022.12.0.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog/2022.12.0.rst b/changelog/2022.12.0.rst index 54de8a2aa..f556034dd 100644 --- a/changelog/2022.12.0.rst +++ b/changelog/2022.12.0.rst @@ -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 ^^^^^^^^^^^ From 7e2be1e87337cebe317bec710bf1ccfa8feeb64c Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 12 Dec 2022 17:20:38 +1300 Subject: [PATCH 6/6] Update supporters for 2022.12.0b3 --- guides/supporters.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/supporters.rst b/guides/supporters.rst index 7b32aa423..4f35b7ad4 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -190,7 +190,6 @@ Contributors - `Alex Solomaha (@CyanoFresh) `__ - `Luar Roji (@cyberplant) `__ - `Aleš Komárek (@cznewt) `__ -- `d-two (@d-two) `__ - `Dale Higgs (@dale3h) `__ - `damanti-me (@damanti-me) `__ - `Daniel Bjørnbakk (@danibjor) `__ @@ -608,6 +607,7 @@ Contributors - `mnltake (@mnltake) `__ - `Matt N. (@mnoorenberghe) `__ - `Moritz Glöckl (@moritzgloeckl) `__ +- `Chris Laplante (@mostthingsweb) `__ - `Matthew Pettitt (@mpettitt) `__ - `Sam Hughes (@MrEditor97) `__ - `Mariusz Kryński (@mrk-its) `__ @@ -887,13 +887,13 @@ Contributors - `Wolfgang Tremmel (@wtremmel) `__ - `Wumpf (@Wumpf) `__ - `wysiwyng (@wysiwyng) `__ -- `Mike (@xsnoopy) `__ - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ - `Pavel (@yekm) `__ - `Atsuko Ito (@yottatsa) `__ - `Nico B (@youknow0) `__ - `Yuval Aboulafia (@yuvalabou) `__ +- `Björn Stenberg (@zagor) `__ - `david reid (@zathras777) `__ - `Zebble (@Zebble) `__ - `ZJY (@zhangjingye03) `__ @@ -904,4 +904,4 @@ Contributors - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated December 8, 2022.* +*This page was last updated December 12, 2022.*