From 8566e016b231a58b3e1b20a160393501d90a171c Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 23 Feb 2023 13:42:03 +1300 Subject: [PATCH 01/25] Bump version to 2023.2.4 --- Doxygen | 2 +- Makefile | 2 +- _static/version | 2 +- conf.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doxygen b/Doxygen index 4ac061f13..631d06214 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 = 2023.2.3 +PROJECT_NUMBER = 2023.2.4 # 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 3d39b2da9..f982c79e0 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2023.2.3 +ESPHOME_REF = 2023.2.4 .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 d240f54bd..43e46fe3a 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.2.3 \ No newline at end of file +2023.2.4 \ No newline at end of file diff --git a/conf.py b/conf.py index 1117cc088..deac8f8a0 100644 --- a/conf.py +++ b/conf.py @@ -69,7 +69,7 @@ author = "ESPHome" # The short X.Y version. version = "2023.2" # The full version, including alpha/beta/rc tags. -release = "2023.2.3" +release = "2023.2.4" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 16b32e87275e7d2c39b2dd2356bd22fa7d30373d Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 23 Feb 2023 13:42:22 +1300 Subject: [PATCH 02/25] Update changelog for 2023.2.4 --- changelog/2023.2.0.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/changelog/2023.2.0.rst b/changelog/2023.2.0.rst index fe3afa773..1d8bbc6be 100644 --- a/changelog/2023.2.0.rst +++ b/changelog/2023.2.0.rst @@ -73,6 +73,13 @@ Release 2023.2.3 - February 20 - Fix MQTT discovery for climate after preset implementation :esphomepr:`4451` by :ghuser:`jmichiel` - Update distribution manifest :esphomepr:`4459` by :ghuser:`jesserockz` +Release 2023.2.4 - February 23 +------------------------------ + +- BL0939 state_class set for energy sensors :esphomepr:`4463` by :ghuser:`konsulten` +- fix wiegand tag parity :esphomepr:`4476` by :ghuser:`ssieb` +- Fix multiple remote_receivers with triggers :esphomepr:`4477` by :ghuser:`jesserockz` + Full list of changes -------------------- From 820b73ca6e05d06404f39e3635df1c4d03454618 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 23 Feb 2023 13:42:50 +1300 Subject: [PATCH 03/25] Update supporters for 2023.2.4 --- guides/supporters.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/guides/supporters.rst b/guides/supporters.rst index 29187c06c..5146bcefd 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -299,6 +299,7 @@ Contributors - `Expaso (@Expaso) `__ - `Malte Franken (@exxamalte) `__ - `Fabian Affolter (@fabaff) `__ +- `Fabian (@Fabian-Schmidt) `__ - `Federico Ariel Castagnini (@facastagnini) `__ - `C W (@fake-name) `__ - `Florian idB (@fbeek) `__ @@ -416,6 +417,7 @@ Contributors - `James Duke (@jamesduke) `__ - `James Gao (@jamesgao) `__ - `James Lakin (@jamesorlakin) `__ +- `James Swift (@JamesSwift) `__ - `Juraj Andrássy (@JAndrassy) `__ - `Jan Grewe (@jangrewe) `__ - `János Rusiczki (@janosrusiczki) `__ @@ -628,6 +630,7 @@ Contributors - `myhomeiot (@myhomeiot) `__ - `Igor Scheller (@MyIgel) `__ - `Mynasru (@Mynasru) `__ +- `Mikhail Zakharov (@mzakharo) `__ - `Kevin Uhlir (@n0bel) `__ - `Erik Näsström (@Naesstrom) `__ - `H. Árkosi Róbert (@nagyrobi) `__ @@ -779,6 +782,7 @@ Contributors - `ShellAddicted (@ShellAddicted) `__ - `sherbang (@sherbang) `__ - `Shish (@shish) `__ +- `Shreyas Karnik (@shreyaskarnik) `__ - `SiliconAvatar (@SiliconAvatar) `__ - `Francisco J. Solis (@sisco0) `__ - `Derek Hageman (@Sizurka) `__ @@ -812,8 +816,6 @@ Contributors - `Jordan Vohwinkel (@sublime93) `__ - `sumirati (@sumirati) `__ - `swifty99 (@swifty99) `__ -- `Sybren A. Stüvel (@sybrenstuvel) `__ -- `Sympatron GmbH (@Sympatron) `__ - `synco (@synco) `__ - `Marcel Feix (@Syndlex) `__ - `Suryandaru Triandana (@syndtr) `__ @@ -861,7 +863,6 @@ Contributors - `tube0013 (@tube0013) `__ - `Alexey Vlasov (@turbulator) `__ - `Seppel Hardt (@tuxBurner) `__ -- `TVDLoewe (@TVDLoewe) `__ - `Thorsten von Eicken (@tve) `__ - `Ubi de Feo (@ubidefeo) `__ - `uPesy Electronics (@uPesy) `__ @@ -908,4 +909,4 @@ Contributors - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated February 20, 2023.* +*This page was last updated February 23, 2023.* From 68da2f66867769db200c86b9516d398b47cf9a9d Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Sun, 26 Feb 2023 21:46:01 +1300 Subject: [PATCH 04/25] Add friendly name to docs (#2707) --- components/esphome.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/components/esphome.rst b/components/esphome.rst index c5a25ac38..e56449962 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -29,6 +29,9 @@ Configuration variables: characters, digits and hyphens, and can be at most 24 characters long by default, or 31 characters long if ``name_add_mac_suffix`` is ``false``. See :ref:`esphome-changing_node_name`. +- **friendly_name** (*Optional*, string): This name is sent to the frontends. It is used + by Home Assistant as the integration name, device name, and is automatically prefixed to entities + where necessary. Advanced options: From 51ba47c6a6d6b9aba128a0e8720c7cb8727c682a Mon Sep 17 00:00:00 2001 From: Peter Kay <59865048+dougle03@users.noreply.github.com> Date: Sun, 26 Feb 2023 22:00:46 +0000 Subject: [PATCH 05/25] Update gps.rst (#2704) Multiple typos corrected --- components/gps.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/gps.rst b/components/gps.rst index b674cf1ff..a391a2c46 100644 --- a/components/gps.rst +++ b/components/gps.rst @@ -58,31 +58,31 @@ Configuration variables: - **longitude** (*Optional*): Include the Longitude as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the longitude sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **speed** (*Optional*): Include the measured speed as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the speed sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **course** (*Optional*): Include the measured course as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the course sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **altitude** (*Optional*): Include the measured altitude as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the altitude sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **satellites** (*Optional*): Include the number of tracking satellites being used as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the tracking satellites sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. From 7f5385981aa887d858c3a29431e8a9931867c6b9 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 28 Feb 2023 08:17:44 +1300 Subject: [PATCH 06/25] Fix adc link (#2710) --- components/sensor/adc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst index a8c03e99c..0b1267b9f 100644 --- a/components/sensor/adc.rst +++ b/components/sensor/adc.rst @@ -63,7 +63,7 @@ ESP32 Attenuation On the ESP32 the voltage measured with the ADC caps out at ~1.1V by default as the sensing range (attenuation of the ADC) is set to ``0db`` by default. Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``11db``. -There's more information `at the manufacturer's website `__. +There's more information `at the manufacturer's website `__. To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation `__ combines all available ranges to allow the best resolution without having to compromise on a specific attenuation. From 26f59b8540379d458ca32f3ba7f2adfe776f49b0 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 28 Feb 2023 09:02:42 +1300 Subject: [PATCH 07/25] Remove copy paste config var mistake on mics-4514 (#2711) --- components/sensor/mics_4514.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/components/sensor/mics_4514.rst b/components/sensor/mics_4514.rst index b337c59ef..05056f65d 100644 --- a/components/sensor/mics_4514.rst +++ b/components/sensor/mics_4514.rst @@ -35,7 +35,6 @@ This component exposes the different gas concentration sensors from the `MiCS-45 Configuration variables: ------------------------ -- **pin** (**Required**, :ref:`config-pin`): The pin where the DHT bus is connected. - **nitrogen_dioxide** (*Optional*): All options from :ref:`Sensor ` - **carbon_monoxide** (*Optional*): All options from :ref:`Sensor ` - **hydrogen** (*Optional*): All options from :ref:`Sensor ` From 5d25fac978857e556eb566b58a3a99eaf4a23a2e Mon Sep 17 00:00:00 2001 From: Ian Reinhart Geiser Date: Thu, 2 Mar 2023 16:32:29 -0500 Subject: [PATCH 08/25] Clarify what IAQ is (#2714) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Clarify what IAQ is Since standards are only for companies that lack a marketing department, I clarified some of the documentation around Bosch's definition of what IAQ means in their universe. There is a lot here and it was taken from their datasheet directly that I provided a link to anyway. I just wanted to include the important stuff to save people from surprises because like me they didn't bother to follow the links. I can remove the b-VOC stuff if it's too much noise, but I thought it clarified to the users what it might be measuring for. I also changed `2` to `₂` in `CO2` for the non-code snippets soothe the emotional damage incurred from doing too many school papers in LaTeX. * fix table --- components/sensor/bme680_bsec.rst | 90 +++++++++++++++++++++++-------- 1 file changed, 68 insertions(+), 22 deletions(-) diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst index fa7c0f5d7..d687c11ab 100644 --- a/components/sensor/bme680_bsec.rst +++ b/components/sensor/bme680_bsec.rst @@ -2,7 +2,7 @@ BME680 Temperature+Pressure+Humidity+Gas Sensor via BSEC ======================================================== .. seo:: - :description: Instructions for setting up BME680 temperature, humidity, pressure and gas sensors via BSEC. + :description: Instructions for setting up BME680 temperature, humidity, pressure, and gas sensors via BSEC. :image: bme680.jpg :keywords: BME680 @@ -12,12 +12,13 @@ Component/Hub The ``bme680_bsec`` sensor platform allows you to use your BME680 (`datasheet `__, `Adafruit`_) temperature, pressure and humidity and gas sensors with ESPHome via the Bosch Sensortec Environmental Cluster (BSEC) -software library. The use of Bosch's proprietary algorithms provides additional Indoor Air Quality (IAQ), CO2 equivalent and Breath -Volatile Organic Compounds (VOC) equivalent measurements. +software library. The use of Bosch's proprietary algorithms provide an Index for Air Quality (IAQ) measurement derived from the +gas resistance sensor's response to specific Volatile Organic Compounds (VOC). The BSEC software also provides estimated values +for CO₂ and Breath Volatile Organic Compounds (b-VOC) using a correlation between VOC and CO₂ in a human's exhaled breath. .. note:: - The Bosch BSEC library is only available for use after accepting its software license agreement. By enabling this component, + The BSEC library is only available for use after accepting its software license agreement. By enabling this component, you are explicitly agreeing to the terms of the `BSEC license agreement`_. You must not distribute any compiled firmware binaries that include this component. @@ -101,9 +102,9 @@ Configuration variables: Can be ``mobile`` for mobile applications (e.g. carry-on devices). - **sample_rate** (*Optional*, string): Sample rate. Default is ``lp`` for low power consumption, sampling every 3 seconds. - Can be ``ulp`` for ultra low power, sampling every 5 minutes. - This controls the sampling rate for gas-dependant sensors and will govern the interval at which the sensor heater is operated. - By default this rate will also be used for temperature, pressure and humidity sensors but these can be overridden on a per-sensor level if required. + Can be ``ulp`` for ultra-low power, sampling every 5 minutes. + This controls the sampling rate for gas-dependent sensors and will govern the interval at which the sensor heater is operated. + By default, this rate will also be used for temperature, pressure, and humidity sensors but these can be overridden on a per-sensor level if required. - **state_save_interval** (*Optional*, :ref:`config-time`): The minimum interval at which to save calibrated BSEC algorithm state to flash so that calibration doesn't have to start from zero on device restart. Defaults to ``6h``. @@ -117,21 +118,21 @@ Configuration variables: - **name** (**Required**, string): The name for the temperature sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - **name** (**Required**, string): The name for the pressure sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor. - **name** (**Required**, string): The name for the humidity sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **gas_resistance** (*Optional*): The information for the gas sensor. @@ -152,9 +153,9 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **co2_equivalent** (*Optional*): The information for the CO2 equivalent sensor. +- **co2_equivalent** (*Optional*): The information for the CO₂ equivalent sensor. - - **name** (**Required**, string): The name for the CO2 equivalent sensor. + - **name** (**Required**, string): The name for the CO₂ equivalent sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. @@ -188,7 +189,7 @@ Advanced configuration The following configuration shows all the available sensors and optional settings for the component. It also includes an example of filtering to guard against outliers, limit the number of updates sent to home assistant and reduce storage requirements in other systems such as influxdb used to store historical data. -For each sensor all other options from :ref:`Sensor ` and :ref:`TextSensor ` are also available for filtering, automation and so on. +For each sensor, all other options from :ref:`Sensor ` and :ref:`TextSensor ` are also available for filtering, automation and so on. .. code-block:: yaml @@ -204,7 +205,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # Temperature offset # ------------------ # Useful if device is in enclosure and reads too high - # For example if it reads 5C too high, set this to 5 + # For example, if it reads 5C too high, set this to 5 # This also corrects the relative humidity readings # Default: 0 temperature_offset: 0 @@ -213,7 +214,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # -------------------- # Available options: # - static (for fixed position devices) - # - mobile (for on person or other moveable devices) + # - mobile (for on a person or other moveable devices) # Default: static iaq_mode: static @@ -221,7 +222,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # ----------- # Available options: # - lp (low power - samples every 3 seconds) - # - ulp (ultra low power - samples every 5 minutes) + # - ulp (ultra-low power - samples every 5 minutes) # Default: lp sample_rate: ulp @@ -281,19 +282,63 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T name: "BME680 IAQ Accuracy" -Indoor Air Quality (IAQ) Measurement ------------------------------------- +Index for Air Quality (IAQ) Measurement +--------------------------------------- + +The measurements are expressed with an index scale ranging from 0 to 500. The index itself is deduced +from tests using ethanol gas, as well as important VOC in the exhaled breath of healthy humans. +The VOC values themselves are derived from several publications on breath analysis studies. The BSEC +software library defines the levels as follows: + ++-----------+---------------------+ +| IAQ Index | Air Quality | ++===========+=====================+ +| 0 - 50 | Excellent | ++-----------+---------------------+ +| 51 - 100 | Good | ++-----------+---------------------+ +| 101 - 150 | Lightly polluted | ++-----------+---------------------+ +| 151 - 200 | Moderately polluted | ++-----------+---------------------+ +| 201 - 250 | Heavily polluted | ++-----------+---------------------+ +| 251 - 350 | Severely polluted | ++-----------+---------------------+ +| > 351 | Extremely polluted | ++-----------+---------------------+ + +The selected b-VOC gasses are as follows: + ++--------------------+----------------+ +| Compound | Molar fraction | ++====================+================+ +| `Ethane`_ | 5 ppm | ++--------------------+----------------+ +| `Isoprene`_ | 10 ppm | ++--------------------+----------------+ +| `Ethanol`_ | 10 ppm | ++--------------------+----------------+ +| `Acetone`_ | 50 ppm | ++--------------------+----------------+ +| `Carbon Monoxide`_ | 15 ppm | ++--------------------+----------------+ + +.. _Ethane: https://en.wikipedia.org/wiki/Ethane +.. _Isoprene: https://en.wikipedia.org/wiki/Isoprene +.. _Ethanol: https://en.wikipedia.org/wiki/Ethanol +.. _Acetone: https://en.wikipedia.org/wiki/Acetone +.. _Carbon Monoxide: https://en.wikipedia.org/wiki/Carbon_monoxide -Indoor Air Quality measurements are expressed in the IAQ index scale with 25IAQ corresponding to typical good air and 250IAQ -indicating typical polluted air after calibration. .. _bsec-calibration: IAQ Accuracy and Calibration ---------------------------- -The BSEC algorithm automatically gathers data in order to calibrate the IAQ measurements. The IAQ Accuracy sensor will give one -of the following values: +The BSEC software automatically calibrates automatically in the background to provide consistent IAQ performance. The +calibration process considers the recent measurement history so that a value of 50 corresponds to a “typical good” +level and a value of 200 to a “typical polluted” level. The IAQ Accuracy sensor will give one of the following values: - ``Stabilizing``: The device has just started, and the sensor is stabilizing (this typically lasts 5 minutes) - ``Uncertain``: The background history of BSEC is uncertain. This typically means the gas sensor data was too @@ -310,6 +355,7 @@ See Also - :ref:`sensor-filters` - :doc:`bme680` - :apiref:`bme680_bsec/bme680_bsec.h` +- `BME680 Datasheet `__ - `BME680 VOC classification `__ - `BSEC Arduino Library `__ by `Bosch Sensortec `__ - `Bosch Sensortec Community `__ From cc426b972c857899fff7328d085fc84d309f1969 Mon Sep 17 00:00:00 2001 From: Tomas Klouda Date: Sun, 5 Mar 2023 14:49:01 +0100 Subject: [PATCH 09/25] Mention MH-Z14 as working with MH-Z19 library. (#2719) --- components/sensor/mhz19.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 2d4a3e7e8..58ab84a26 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -8,7 +8,7 @@ MH-Z19 CO_2 and Temperature Sensor The ``mhz19`` sensor platform allows you to use MH-Z19 CO_2 and temperature sensors (`refspace`_) with ESPHome. -The CO_2 measurement also works with the MH-Z16 sensor. +The CO_2 measurement also works with the MH-Z16 and MH-Z14 sensors. .. figure:: images/mhz19-full.jpg :align: center From 9f22bf66ff22e9ca7b8609ac0109eb29c3764667 Mon Sep 17 00:00:00 2001 From: Ian Reinhart Geiser Date: Sun, 5 Mar 2023 22:54:04 -0500 Subject: [PATCH 10/25] Clarify purpose of appending the mac address (#2721) --- components/esphome.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/components/esphome.rst b/components/esphome.rst index e56449962..bbd4781d2 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -29,7 +29,7 @@ Configuration variables: characters, digits and hyphens, and can be at most 24 characters long by default, or 31 characters long if ``name_add_mac_suffix`` is ``false``. See :ref:`esphome-changing_node_name`. -- **friendly_name** (*Optional*, string): This name is sent to the frontends. It is used +- **friendly_name** (*Optional*, string): This is the name sent to the frontend. It is used by Home Assistant as the integration name, device name, and is automatically prefixed to entities where necessary. @@ -321,10 +321,16 @@ The same procedure can be done for changing the static IP of a device. Adding the MAC address as a suffix to the device name ----------------------------------------------------- -Using ``name_add_mac_suffix`` allows the user to compile a single binary file to flash -many of the same device and they will all have unique names/hostnames. -Note that you will still need to create an individual YAML config file if you want to -OTA update the devices in the future. +Using ``name_add_mac_suffix`` allows :doc:`creators ` to +provision multiple devices at the factory with a single firmware and still +have unique identification for customer installs. + +.. note:: + + End users will need to create an individual YAML config file if they want to OTA update the + devices in the future. Creators can facilitate this process by providing ``dashboard_import`` URL + for end users. This allows them to easily update their devices as new features are made available + upstream. .. _esphome-creators_project: From bff961afc67e8beece0e1ae3a1e7088f9015b1ac Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 6 Mar 2023 19:42:36 +1300 Subject: [PATCH 11/25] Minor updates on sharing page (#2722) --- guides/creators.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/guides/creators.rst b/guides/creators.rst index dc8c459ab..134f2ce0e 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -7,6 +7,10 @@ Sharing ESPHome devices We have added configuration options to ESPHome to make it easier to create, configure, install and distribute devices running ESPHome. +No part of a "template" configuration should have any references to secrets, +or have passwords pre-applied. ESPHome makes it easy for the end-user to add these +themselves after they adopt the device into their own ESPHome dashboard. + Example configuration --------------------- @@ -14,10 +18,13 @@ Example configuration # These substitutions allow the end user to override certain values substitutions: - name: "project-template-32" + name: "project-template" + friendly_name: "Project Template" esphome: name: "${name}" + # Friendly names are used where appropriate in Home Assistant + friendly_name: "${friendly_name}" # Automatically add the mac address to the name # so you can use a single firmware for all devices name_add_mac_suffix: true From 6a90cd8cfcdf28ee66ded09c1da3da8858d467cd Mon Sep 17 00:00:00 2001 From: Carlos Garcia Saura Date: Mon, 6 Mar 2023 16:24:06 +0100 Subject: [PATCH 12/25] Improve example in SCD4X for ambient pressure compensation (#2645) * Update scd4x.rst * Update scd4x.rst * Update scd4x.rst * Improve calibration example --- components/sensor/scd4x.rst | 80 +++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 31 deletions(-) diff --git a/components/sensor/scd4x.rst b/components/sensor/scd4x.rst index 04796d3d3..a89624381 100644 --- a/components/sensor/scd4x.rst +++ b/components/sensor/scd4x.rst @@ -105,15 +105,19 @@ As of April 2022 the average fresh air Co² concentration is 419 ppm. value: 419 # outside average April 2022 id: my_scd41 -value can be a template +value can also be a template, for example to define a Home Assistant calibration service: .. code-block:: yaml - on_...: - then: - - scd4x._perform_forced_calibration_action: - value: !lambda "{ return 419 };" - id: my_scd41 + api: + services: + - service: calibrate_co2_value + variables: + co2_ppm: int + then: + - scd4x.perform_forced_calibration: + value: !lambda 'return co2_ppm;' + id: my_scd41 .. _factory_reset_action: @@ -129,39 +133,53 @@ This :ref:`action ` triggers a factory reset of the sensor. Calib then: - scd4x.factory_reset: my_scd41 -Automation ------------------ +Pressure compensation +--------------------- -Ambient pressure compensation compensation can be changed from :ref:`lambdas ` +A static ambient pressure value can be set with `ambient_pressure_compensation` or `altitude_compensation`. It can also be changed dynamically with :ref:`lambdas ` using `set_ambient_pressure_compensation()`, or by pointing `ambient_pressure_compensation_source` to a local pressure sensor. +Example with a local sensor +*************************** -``set_ambient_pressure_compensation( set_ambient_pressure_compensation(x / 1000.0);" + - platform: scd4x + measurement_mode: low_power_periodic + ambient_pressure_compensation_source: bme_pressure + temperature_offset: 0 + co2: + name: "CO2 level" + +Example with a remote sensor +**************************** + +This example creates a service `set_ambient_pressure` that can be called from Home Assistant: + +.. code-block:: yaml + + api: + services: + - service: set_ambient_pressure + variables: + pressure_mbar: int + then: + - lambda: "id(my_scd41)->set_ambient_pressure_compensation(pressure_mbar);" + + sensor: + - platform: scd4x + id: my_scd41 + measurement_mode: low_power_periodic + temperature_offset: 0 + co2: + name: "CO2 level" See Also From d1e790793058126bbb95d1f775828693c07560c1 Mon Sep 17 00:00:00 2001 From: Petr Kejval Date: Mon, 6 Mar 2023 20:23:01 +0100 Subject: [PATCH 13/25] Update resistance.rst (#2725) * Update resistance.rst Spent many hours to figure it out why my NTC reading are incorrect. Found out that ADC readings must be multiplied by 3.3 because built-in voltage divider on ADC pin on some boards. * Update resistance.rst --- components/sensor/resistance.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/components/sensor/resistance.rst b/components/sensor/resistance.rst index 21d42c2c4..cc6ce039e 100644 --- a/components/sensor/resistance.rst +++ b/components/sensor/resistance.rst @@ -44,6 +44,19 @@ is close to GND (DOWNSTREAM) or it is closer to VCC (UPSTREAM). id: source_sensor pin: A0 +Note: +------------------------ +Some boards like NodeMCUv2 needs to multiply ADC reading by 3.3 to provide accurate result because they have built-in voltage divider on ADC pin (https://arduino.stackexchange.com/a/71952) + +.. code-block:: yaml + + # Example source sensor: + - platform: adc + id: source_sensor + pin: A0 + filters: + - multiply: 3.3 + Configuration variables: ------------------------ From c50477f1d62f81b74743968d5c13cb54dbbb2b1d Mon Sep 17 00:00:00 2001 From: Sean Carolan Date: Tue, 7 Mar 2023 02:08:38 -0600 Subject: [PATCH 14/25] Removing default setting (#2716) `discovery: true` is on by default and therefore not required here. You only need this to set `discovery: false` --- components/mqtt.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/components/mqtt.rst b/components/mqtt.rst index 6ca647a19..3a415e461 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -149,7 +149,6 @@ discovery in your Home Assistant configuration with the following: # Example Home Assistant configuration.yaml entry mqtt: broker: ... - discovery: true And that should already be it 🎉 All devices defined through ESPHome should show up automatically in the entities section of Home Assistant. @@ -308,7 +307,6 @@ Also make sure to change the ``port`` of the mqtt broker. Most brokers use port mqtt: broker: test.mymqtt.local port: 8883 - discovery: true discovery_prefix: ${mqtt_prefix}/homeassistant log_topic: ${mqtt_prefix}/logs # Evaluate carefully skip_cert_cn_check @@ -353,7 +351,6 @@ MQTT can have some overrides for specific options. name: "Component Name" # Optional variables: retain: true - discovery: true availability: topic: livingroom/status payload_available: online From c56b23167943fd2eba2e8ec6440e04b1fa471574 Mon Sep 17 00:00:00 2001 From: Jeff <52110065+jazzmonger@users.noreply.github.com> Date: Tue, 7 Mar 2023 01:16:24 -0700 Subject: [PATCH 15/25] Update safe_mode.rst (#2713) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update safe_mode.rst * Update safe_mode.rst --------- Co-authored-by: H. Árkosi Róbert --- components/switch/safe_mode.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/components/switch/safe_mode.rst b/components/switch/safe_mode.rst index 73ae6384a..2f4ec695f 100644 --- a/components/switch/safe_mode.rst +++ b/components/switch/safe_mode.rst @@ -5,8 +5,7 @@ Safe Mode Switch :description: Instructions for setting up switches that can remotely reboot the ESP in ESPHome into safe mode. :image: restart.svg -The ``safe_mode`` switch allows you to remotely reboot your node into :ref:`Safe Mode `. This is useful in certain situations -where a misbehaving component is preventing Over-The-Air updates from completing successfully. +The ``safe_mode`` switch allows you to remotely reboot your node into :ref:`Safe Mode `. This is useful in certain situations where a misbehaving component, or low memoary state is preventing Over-The-Air updates from completing successfully. This component requires :ref:`OTA ` to be configured. From cac3e0f606bb4ae3ed6470052b6e8a1a6573d983 Mon Sep 17 00:00:00 2001 From: systeembeheerder <19684880+systeembeheerder@users.noreply.github.com> Date: Tue, 7 Mar 2023 09:17:39 +0100 Subject: [PATCH 16/25] Update modbus_controller.rst (#2708) S_QWORD is signed, not unsigned --- components/select/modbus_controller.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/select/modbus_controller.rst b/components/select/modbus_controller.rst index bbdaa79f0..4cc9244a6 100644 --- a/components/select/modbus_controller.rst +++ b/components/select/modbus_controller.rst @@ -40,7 +40,7 @@ Configuration variables: - ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first) - ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first) - ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) - - ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) + - ``S_QWORD`` (signed 64 bit integer from 4 registers = 64bit) - ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first) - ``U_QWORD_R`` (signed 64 bit integer from 4 registers low word first) From 61f79fba3a5c28c87c20722f66fbd7873e448502 Mon Sep 17 00:00:00 2001 From: Rob Adams Date: Tue, 7 Mar 2023 08:19:07 +0000 Subject: [PATCH 17/25] Fix typo in filter max docs (#2701) --- components/sensor/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/sensor/index.rst b/components/sensor/index.rst index edbcf8e10..42dd1b993 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -349,7 +349,7 @@ Configuration variables: when pushing out a value. Defaults to ``5``. - **send_every** (*Optional*, int): How often a sensor value should be pushed out. For - example, in above configuration the min is calculated after every 4th + example, in above configuration the max is calculated after every 4th received sensor value, over the last 7 received values. Defaults to ``5``. - **send_first_at** (*Optional*, int): By default, the very first raw value on boot is immediately From 9eb91e153e21bb6442f3a3cb96467c25dd218920 Mon Sep 17 00:00:00 2001 From: Anthony Keane Date: Tue, 7 Mar 2023 19:20:08 +1100 Subject: [PATCH 18/25] Update custom.rst (#2699) Adding ID reference cos I spent 3 hours trying to find why I got this error Couldn't find ID 'my_custom_switch'. Please check you have defined an ID with that name in your configuration. --- components/switch/custom.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/components/switch/custom.rst b/components/switch/custom.rst index ffea90bfe..a5837b94b 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -50,6 +50,7 @@ And in YAML: switches: name: "My Custom Switches" + id: my_custom_switch Configuration variables: From a28da87762a2c27ebf1715f34202cdf58707c97d Mon Sep 17 00:00:00 2001 From: Mathias Stock <89242257+Stock-M@users.noreply.github.com> Date: Tue, 7 Mar 2023 09:20:43 +0100 Subject: [PATCH 19/25] wrong name for the link (#2695) --- components/sensor/ee895.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst index f5b4f1b8a..d56db1579 100644 --- a/components/sensor/ee895.rst +++ b/components/sensor/ee895.rst @@ -7,7 +7,7 @@ EE895 CO₂, Temperature and Pressure Sensor The ``ee895`` sensor platform allows you to use your EE895 CO₂ (`datasheet `__, -`E+E TEE501 `__) sensor with ESPHome. +`E+E EE895 `__) sensor with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. We recommend the use of pull up resistors. .. figure:: images/EE895.png From f1f9be688711049edaf0f5434b1fdb84d030ca6b Mon Sep 17 00:00:00 2001 From: cinghialino Date: Tue, 7 Mar 2023 03:21:47 -0500 Subject: [PATCH 20/25] Update anova.rst (#2696) --- components/climate/anova.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/climate/anova.rst b/components/climate/anova.rst index a05daf1c9..0cfa3eac7 100644 --- a/components/climate/anova.rst +++ b/components/climate/anova.rst @@ -26,7 +26,7 @@ You cannot use the Anova app over BLE whilst this component is connected, you should disconnect it first. To setup a (dis-)connect switch, see :doc:`/components/switch/ble_client`. You need to specify unit_of_measurement as 'c' or 'f'. This ensures the stick's display -uses the unit you intend. All values within ESPHome are converted to Celcius so you may +uses the unit you intend. All values within ESPHome are converted to Celsius so you may need to do conversion again within the frontend if you use Fahrenheit. .. warning:: From 58831869de643c565684b46a8e454c7b91d7f407 Mon Sep 17 00:00:00 2001 From: Kamahat Date: Tue, 7 Mar 2023 09:22:27 +0100 Subject: [PATCH 21/25] small issue on unit used (#2693) small issue on unit used --- components/sensor/pulse_counter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/sensor/pulse_counter.rst b/components/sensor/pulse_counter.rst index a9ae0a16a..a4e505fb5 100644 --- a/components/sensor/pulse_counter.rst +++ b/components/sensor/pulse_counter.rst @@ -93,7 +93,7 @@ measure the total consumed energy in kWh. sensor: - platform: pulse_counter pin: 12 - unit_of_measurement: 'kW' + unit_of_measurement: 'Wh' name: 'Power Meter House' filters: - multiply: 0.06 # (60s/1000 pulses per kWh) From 7b4a42cfc03637fc0a6c96618e5b304e225d66ee Mon Sep 17 00:00:00 2001 From: AlexCPU Date: Tue, 7 Mar 2023 08:23:09 +0000 Subject: [PATCH 22/25] correct details in SEN5x documentation (#2692) * correct connector details in SEN5x documentation * remove Sen54 from section on NOx --- components/sensor/sen5x.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/sensor/sen5x.rst b/components/sensor/sen5x.rst index e0b5043d6..21f67f5f0 100644 --- a/components/sensor/sen5x.rst +++ b/components/sensor/sen5x.rst @@ -114,7 +114,7 @@ Configuration variables: - All other options from :ref:`Sensor `. -- **nox** (*Optional*): NOx Index. Note: Only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. +- **nox** (*Optional*): NOx Index. Note: Only available with Sen55. The sensor will be ignored on unsupported models. - **name** (**Required**, string): The name of the sensor. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. @@ -162,7 +162,7 @@ Configuration variables: Wiring: ------- -The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.5mm pitch. The cable needs this connector: +The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.25mm pitch. The cable needs this connector: .. figure:: images/jst6pin.png :align: center From 9407d6c02d323d93b62487d1577f38d0405b428d Mon Sep 17 00:00:00 2001 From: Alexander Turlov Date: Tue, 7 Mar 2023 03:36:12 -0500 Subject: [PATCH 23/25] Update air_gradient_diy_air_quality_sensor.rst (#2667) Corrected the link to YAML configuration on GitHub. --- cookbook/air_gradient_diy_air_quality_sensor.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/air_gradient_diy_air_quality_sensor.rst b/cookbook/air_gradient_diy_air_quality_sensor.rst index 2fc067c8a..be0071e60 100644 --- a/cookbook/air_gradient_diy_air_quality_sensor.rst +++ b/cookbook/air_gradient_diy_air_quality_sensor.rst @@ -37,7 +37,7 @@ Documentation: - `AirGradient Shop for the PCB or PCB plus components `__ - `AirGradient Setup Guide (3D printeable case, setup guide, etc.) `__ -`YAML configuration `__ +`YAML configuration `__ Soldering and setup video: From 3a86ec052e96698598900ed66d7bdfa155984c46 Mon Sep 17 00:00:00 2001 From: Steve Rodgers Date: Tue, 7 Mar 2023 00:47:45 -0800 Subject: [PATCH 24/25] Update diy.rst (#2706) Add configuration link for my 9 valve sprinkler controller --- guides/diy.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/guides/diy.rst b/guides/diy.rst index 5c328f1a1..b025b4531 100644 --- a/guides/diy.rst +++ b/guides/diy.rst @@ -122,3 +122,4 @@ Sample Configurations - `ESPHome Curtain/Cover/Shutter Switch from a noname Tuya switch `__ by :ghuser:`ludrao` - `ESPHome Free your Thomson Guardian gate controller `__ by :ghuser:`ludrao` - `Ambient Light Sensor tcs34725 example `__ by :ghuser:`RubenKelevra` +- `9 Valve Sprinkler Controller configuration `__ by :ghuser:`hwstar` From e4e133d3699ad6372c653cd84d37031149117b12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=2E=20=C3=81rkosi=20R=C3=B3bert?= Date: Tue, 7 Mar 2023 14:42:23 +0100 Subject: [PATCH 25/25] Update index.rst (#2726) --- components/climate/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/climate/index.rst b/components/climate/index.rst index 25c333cdc..ad2906b97 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -20,7 +20,7 @@ and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OF Base Climate Configuration -------------------------- -All climate platforms in ESPHome inherit from the climate configuration schema. +All climate platforms in ESPHome inherit from the climate configuration schema. In ESPHome, ``°C`` is assumed for all temperature values. Some platforms allow conversion or setting in ``°F``, this is specified separately. .. code-block:: yaml