From 1578be61f1a77ee94622ee3189f8cc1014ed0957 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Tue, 13 Feb 2024 09:45:31 +1300 Subject: [PATCH 01/84] Bump version to 2024.3.0-dev --- Doxygen | 2 +- _static/version | 2 +- conf.py | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doxygen b/Doxygen index 8c5682359..c6b59fcb9 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 = 2024.1.0-dev +PROJECT_NUMBER = 2024.3.0-dev # 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/_static/version b/_static/version index dd273dfb1..c209704ee 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.1.0-dev \ No newline at end of file +2024.3.0-dev \ No newline at end of file diff --git a/conf.py b/conf.py index 6133991d7..ac43bb84a 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ author = "ESPHome" # built documents. # # The short X.Y version. -version = "2024.1" +version = "2024.3" # The full version, including alpha/beta/rc tags. -release = "2024.1.0-dev" +release = "2024.3.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 49afad2a6566888d9d4b93b1bde1cb440a64663c Mon Sep 17 00:00:00 2001 From: kahrendt Date: Sun, 18 Feb 2024 00:50:52 -0500 Subject: [PATCH 02/84] probability cutoff is a percentage (#3609) --- components/micro_wake_word.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/micro_wake_word.rst b/components/micro_wake_word.rst index 21103d56e..68e0b4280 100644 --- a/components/micro_wake_word.rst +++ b/components/micro_wake_word.rst @@ -38,7 +38,7 @@ Configuration variables: The below two options are provided by the JSON file, but can be overridden in YAML. -- **probability_cutoff** (*Optional*, float): The probability cutoff for the wake word detection. +- **probability_cutoff** (*Optional*, percentage): The probability cutoff for the wake word detection. If the probability of the wake word is below this value, the wake word is not detected. A larger value reduces the number of false accepts but increases the number of false rejections. - **sliding_window_average_size** (*Optional*, int): The size of the sliding window average for the wake word detection. A small value lowers latency but may increase the number of false accepts. From 491c33fc154cc40787b4299f9505f44b0cbe13ba Mon Sep 17 00:00:00 2001 From: bisbastuner <104585618+bisbastuner@users.noreply.github.com> Date: Sun, 18 Feb 2024 19:44:29 +0100 Subject: [PATCH 03/84] Add documentation about the new supply_voltage option (#3607) --- components/sensor/bme680_bsec.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst index e0b3146c4..a182b1ec1 100644 --- a/components/sensor/bme680_bsec.rst +++ b/components/sensor/bme680_bsec.rst @@ -10,8 +10,8 @@ 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) +(`datasheet `__, +`Adafruit`_, `Pimoroni`_) 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 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. @@ -34,6 +34,8 @@ The :ref:`I²C ` is required to be set up in your configuration for this se .. _Adafruit: https://www.adafruit.com/product/3660 +.. _Pimoroni: https://shop.pimoroni.com/products/bme680-breakout + .. code-block:: yaml # Minimal example configuration with common sensors @@ -101,6 +103,9 @@ Configuration variables: - **iaq_mode** (*Optional*, string): IAQ calculation mode. Default is ``static`` for static applications (e.g. fixed indoor devices). Can be ``mobile`` for mobile applications (e.g. carry-on devices). +- **supply_voltage** (*Optional*, string): Supply voltage of the sensor. Default is ``3.3V``. + Can be set to ``1.8V`` if your sensor is 1.8V-powered (e.g. the Pimoroni PIM357 BME680 Breakout module). + - **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-dependent sensors and will govern the interval at which the sensor heater is operated. @@ -231,6 +236,14 @@ For each sensor, all other options from :ref:`Sensor ` and :ref:` # Default: static iaq_mode: static + # Supply voltage + # -------------------- + # Available options: + # - 3.3V + # - 1.8V + # Default: 3.3V + supply_voltage: 3.3V + # Sample rate # ----------- # Available options: @@ -423,7 +436,7 @@ The selected b-VOC gasses are as follows: IAQ Accuracy and Calibration ---------------------------- -The BSEC software automatically calibrates automatically in the background to provide consistent IAQ performance. The +The BSEC software automatically calibrates 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: From 8fd1f43376f78641f80be1a11b1642cd696f5eda Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Mon, 19 Feb 2024 11:53:00 +1300 Subject: [PATCH 04/84] microWakeWord: Add minimum_esphome_version as optional field (#3612) --- components/micro_wake_word.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/components/micro_wake_word.rst b/components/micro_wake_word.rst index 68e0b4280..c541f72cc 100644 --- a/components/micro_wake_word.rst +++ b/components/micro_wake_word.rst @@ -61,7 +61,7 @@ Model JSON } } -The model JSON file contains the following fields that are all **required**: +The model JSON file contains the following fields that are all **required** unless otherwise specified: - **type** (string): The type of the model. This should always be ``micro``. - **wake_word** (string): The wake word that the model is trained to detect. @@ -74,6 +74,7 @@ The model JSON file contains the following fields that are all **required**: - **probability_cutoff** (float): The probability cutoff for the wake word detection. If the probability of the wake word is below this value, the wake word is not detected. - **sliding_window_average_size** (int): The size of the sliding window average for the wake word detection. + - **minimum_esphome_version** (*Optional* version): The minimum ESPHome version required to use this model. Automations From 7d8c3c757afeb180933fc850af9bf4ad8cd39c91 Mon Sep 17 00:00:00 2001 From: Anton Viktorov Date: Mon, 19 Feb 2024 02:25:02 +0100 Subject: [PATCH 05/84] INA226 - new options added for ADC configuration; Fixed improper work with signed values (#3608) --- components/sensor/ina226.rst | 37 +++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/components/sensor/ina226.rst b/components/sensor/ina226.rst index 20139f41f..abe591eb9 100644 --- a/components/sensor/ina226.rst +++ b/components/sensor/ina226.rst @@ -7,10 +7,8 @@ INA226 DC current and power sensor :keywords: ina226 The ``ina226`` sensor platform allows you to use your INA226 DC Current and Power Sensor -(`datasheet `__, -`eBay`_) sensors with -ESPHome. The :ref:`I²C Bus ` is -required to be set up in your configuration for this sensor to work. +(`datasheet `__, `eBay`_) sensors with ESPHome. +The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. .. figure:: images/ina226-full.jpg @@ -28,6 +26,8 @@ required to be set up in your configuration for this sensor to work. - platform: ina226 address: 0x40 shunt_resistance: 0.1 ohm + max_current: 3.2A + update_interval: 60s current: name: "INA226 Current" power: @@ -36,28 +36,35 @@ required to be set up in your configuration for this sensor to work. name: "INA226 Bus Voltage" shunt_voltage: name: "INA226 Shunt Voltage" - max_current: 3.2A - update_interval: 60s Configuration variables: ------------------------ -- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x40``. +- **address** (*Optional*, integer): Manually specify the I²C address of the sensor. Defaults to ``0x40``. - **shunt_resistance** (*Optional*, float): The value of the shunt resistor on the board for current calculation. Defaults to ``0.1 ohm``. - **max_current** (*Optional*, float): The maximum current you are expecting. ESPHome will use this to configure the sensor optimally. Defaults to ``3.2A``. -- **current** (*Optional*): Use the current value of the sensor in amperes. All options from - :ref:`Sensor `. -- **power** (*Optional*): Use the power value of the sensor in watts. All options from - :ref:`Sensor `. -- **bus_voltage** (*Optional*): Use the bus voltage (voltage of the high side contact) value of the sensor in V. - All options from :ref:`Sensor `. -- **shunt_voltage** (*Optional*): Use the shunt voltage (voltage across the shunt resistor) value of the sensor in V. - All options from :ref:`Sensor `. +- **adc_time** (*Optional*, :ref:`config-time`): The time in microseconds to perform a single ADC conversion. + Defaults to ``1100us``. Valid values are ``140us``, ``204us``, ``332us``, ``588us``, ``1100us``, ``2116us``, + ``4156us``, ``8244us``. +- **adc_averaging** (*Optional*, integer): Selects ADC sample averaging count. Defaults to ``4``. Valid values are + ``1``, ``4``, ``16``, ``64``, ``128``, ``256``, ``512``, ``1024``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +Sensors +------- +The component offers four sensors. You can configure all or any subset of them. Each configured sensor +is reported separately on each update_interval. The ``name`` option is required for each sensor configured. +All other options from :ref:`Sensor `. + +- **current** (*Optional*): Calculated current output, Amperes. +- **power** (*Optional*): Calculated power output, Watts. +- **bus_voltage** (*Optional*): Bus voltage output (voltage of the high side contact), Volts. +- **shunt_voltage** (*Optional*): Shunt voltage (voltage across the shunt resistor) value of the sensor, Volts. + + See Also -------- From 6bae4e4037f39fe34fd4df771d73c8f5801cb322 Mon Sep 17 00:00:00 2001 From: "Kevin P. Fleming" Date: Mon, 19 Feb 2024 18:24:49 -0500 Subject: [PATCH 06/84] New component: ADE7880 voltage/current/power/energy sensor (#3123) --- components/sensor/ade7880.rst | 311 ++++++++++++++++++++++++++++++++++ images/ade7880.svg | 1 + index.rst | 1 + 3 files changed, 313 insertions(+) create mode 100644 components/sensor/ade7880.rst create mode 100644 images/ade7880.svg diff --git a/components/sensor/ade7880.rst b/components/sensor/ade7880.rst new file mode 100644 index 000000000..aca0c5a90 --- /dev/null +++ b/components/sensor/ade7880.rst @@ -0,0 +1,311 @@ +ADE7880 Power Sensor +==================== + +.. seo:: + :description: Instructions for setting up ADE7880 energy metering sensors + :keywords: ADE7880, Shelly 3EM + +The ``ade7880`` sensor platform allows you to use ADE7880 +voltage/current/power sensors (`datasheet`_) with ESPHome. This sensor +chip is commonly found in Shelly 3EM and 3EM Pro devices. + +Communication with the chip is over an :ref:`I2C bus `, so +you need to have an ``i2c:`` entry in your configuration with both +``sda`` and ``scl`` set. It is also recommended to set the I2C +``frequency`` to ``200kHz`` or higher, if the board containing the +chip can support it (this speed has been verified to work in the +Shelly 3EM). While this is not necessary, if a significant number of +the ``ade7880`` individual sensors (e.g. more than six) are enabled, +the time consumed by the I2C transactions can be substantial and +result in warning messages in the ESPHome logs. + +The ADE7880 chip can measure up to three power phases, along with a +neutral. Current can be measured on all four inputs, while voltage and +power can be measured on the power phases. Current is measured using +CT clamps. + +While the chip is designed for 3-phase AC power, the phase inputs are +independent of each other, so the chip can be used with single-phase +and two-phase AC power circuits as well (or a mixture of them). + +Instantaneous vs. Accumulated Sensors +------------------------------------- + +The digital signal processor (DSP) in the ADE7880 executes its +computations 8,000 times per second. As a result, each sensor listed +below as 'instantaneous' reports the computed value from the most +recent DSP cycle; it does not report an average over the time period +since the last update. + +Each sensor listed as 'accumulated' below reports the sum of all +computed values since the last update. + +The update interval defaults to 60 seconds, but can be lowered if you +wish to have more frequent readings; this will increase the load (and +database growth) of the connected Home Assistant correspondingly. + +Configuration Variables +----------------------- + +- **irq1_pin** (**Required**, :ref:`Pin Schema `): + The GPIO pin that the ADE7880's IRQ1 output is connected to. The + ``ade7880`` component uses this input to determine when the ADE7880 + chip has completed its power-up and reset cycles. + +- **irq0_pin** (*Optional*, :ref:`Pin Schema `): + The GPIO pin that the ADE7880's IRQ0 output is connected to, if + any. The ``ade7880`` component does not use this input, but if the + IRQ0 output is connected to a GPIO and that GPIO is *not* configured + as an ``input``, the chip will produce excessive heat and its + lifetime could be shortened. The simplest way to ensure that the + GPIO pin is properly connected is to supply it here, but if you wish + to configure it elsewhere in your configuration that is a reasonable + alternative. + +- **reset_pin** (*Optional*, :ref:`Pin Schema `): + The GPIO pin that the ADE7880's RESET input is connected to, if + any. If this pin is configured, the ``ade7880`` component will use + it to initiate a 'hardware reset' of the chip when needed; if this + pin is not configured, the component will attempt to initiate a + 'software reset' of the chip when needed, but this could fail if the + chip is not responding properly to the I2C bus. + +- **frequency** (*Optional*, string): The AC line frequency of the + supply voltage. The supported range is ``45Hz`` to + ``65Hz``. Defaults to ``50Hz``. + +- **phase_a** (*Optional*): The configuration variables for the 'A' + phase inputs of the chip. Refer to the configuration examples below + for the `simple` and `detailed` sensor configuration options. + + - **name** (*Optional*, string): The name of the phase, which will + be used a prefix in the names of all of the phase's sensors. + + - **voltage** (instantaneous) (*Optional*): Report the RMS voltage + value of this phase in volts (V). In detailed configuration mode, + all options from :ref:`Sensor ` are supported. + + - **current** (instantaneous) (*Optional*): Report the RMS current + value of this phase in amperes (A). In detailed configuration + mode, all options from :ref:`Sensor ` are + supported. + + - **active_power** (instantaneous) (*Optional*): Report the active + (consumed) power value of this phase in watts (W). In detailed + configuration mode, all options from :ref:`Sensor ` + are supported. + + - **apparent_power** (instantaneous) (*Optional*): Report the + apparent (voltage multiplied by current) power value of this phase + in volt-amperes (VA). In detailed configuration mode, all options + from :ref:`Sensor ` are supported. + + - **power_factor** (instantaneous) (*Optional*): Report the power + factor value of this phase as a percentage (%). In detailed + configuration mode, all options from :ref:`Sensor ` + are supported. + + - **forward_active_energy** (accumulated) (*Optional*): Report the + forward active energy value of this phase in watt-hours (Wh). In + detailed configuration mode, all options from :ref:`Sensor + ` are supported. + + - **reverse_active_energy** (accumulated) (*Optional*): Report the + reverse active energy value of this phase in + volt-ampere-reactive-hours (VARh). In detailed configuration mode, + all options from :ref:`Sensor ` are supported. + + - **calibration** (**Required**): The calibration values necessary + for this phase's sensors to report correct values. + + - **current_gain** (**Required**, integer): The value for the + ``AIGAIN`` calibration register. + + - **voltage_gain** (**Required**, integer): The value for the + ``AVGAIN`` calibration register. + + - **power_gain** (**Required**, integer): The value for the + ``APGAIN`` calibration register. + + - **phase_angle** (**Required**, integer): The value for the + ``APHCAL`` calibration register. + +- **phase_b** (*Optional*): The configuration variables for the 'B' + phase inputs of the chip. Identical to ``phase_a``. + +- **phase_c** (*Optional*): The configuration variables for the 'C' + phase inputs of the chip. Identical to ``phase_a``. + +- **neutral** (*Optional*): The configuration variables for the + 'neutral' phase of the chip. + + - **name** (*Optional*, string): The name of the phase, which will + be used a prefix in the names of all of the phase's sensors. + + - **current** (instantaneous) (**Required**): Report the RMS current + value of the neutral in amperes (A). In detailed configuration + mode, all options from :ref:`Sensor ` are + supported. + + - **calibration** (**Required**): The calibration values necessary + for this phase's sensors to report correct values. + + - **current_gain** (**Required**, integer): The value for the + ``NIGAIN`` calibration register. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval + to report the sensor values. Defaults to ``60s``. + +- **i2c_id** (*Optional*, :ref:`config-id`): Specify the ID of the + :ref:`I2C Component ` if your configuration includes multiple + I2C buses. + +Calibration +----------- + +These sensors needs calibration to report correct values. For the +Shelly 3EM and 3EM Pro devices, the calibration is performed during +manufacturing, and the calibration data is included in the firmware +stored in the device. See the `Shelly 3EM`_ section of the ESPHome +Devices site for details on how to obtain the calibration data for a +3EM device. + +Configuration Examples +---------------------- + +There are two sensor configuration modes supported: *simple* and +*detailed*. The mode can be chosen for each sensor indepedently from +all other sensors. + +The *simple* mode is useful when you have no need to provide IDs for +sensors, or to override any of the default sensor settings (unit of +measurement, device class, state class, decimal accuracy). The value +provided for each sensor variable will be the sensor's name +(optionally prefixed with the phase name, if it has been +configured). + +.. code-block:: yaml + + # Example simple sensor configuration mode + sensor: + - platform: ade7880 + irq0_pin: + number: GPIO13 + irq1_pin: + number: GPIO5 + phase_a: + name: Room Heater + voltage: Voltage + current: Current + active_power: Active Power + power_factor: Power Factor + forward_active_energy: Forward Active Energy + reverse_active_energy: Reverse Active Energy + calibration: + current_gain: 3116628 + voltage_gain: -757178 + power_gain: -1344457 + phase_angle: 188 + +Because the phase name 'Room Heater' was configured, the resulting +names for the various sensors will be 'Room Heater Voltage', 'Room +Heater Current', etc. + +.. code-block:: yaml + + # Example detailed sensor configuration mode + sensor: + - platform: ade7880 + irq0_pin: + number: GPIO13 + irq1_pin: + number: GPIO5 + phase_a: + voltage: Voltage + current: + name: Current + accuracy_decimals: 0 + active_power: Active Power + power_factor: + id: ade_power_factor + name: Power Factor + forward_active_energy: Forward Active Energy + reverse_active_energy: Reverse Active Energy + calibration: + current_gain: 3116628 + voltage_gain: -757178 + power_gain: -1344457 + phase_angle: 188 + +In this example, the ``accuracy_decimals`` variable for the +``current`` sensor has been specified (overriding the default), and an +``ID`` has been specified for the ``power_factor`` sensor. The +remaining sensors for the 'A' phase are configured using 'simple' +configuration mode. + +.. code-block:: yaml + + # Example full platform configuration + sensor: + - platform: ade7880 + irq0_pin: + number: GPIO13 + irq1_pin: + number: GPIO5 + reset_pin: + number: GPIO16 + frequency: 60Hz + phase_a: + name: Phase A + voltage: Voltage + current: Current + active_power: Active Power + power_factor: Power Factor + forward_active_energy: Forward Active Energy + reverse_active_energy: Reverse Active Energy + calibration: + current_gain: 3116628 + voltage_gain: -757178 + power_gain: -1344457 + phase_angle: 188 + phase_b: + name: Phase B + voltage: Voltage + current: Current + active_power:: Active Power + power_factor: Power Factor + forward_active_energy: Forward Active Energy + reverse_active_energy: Reverse Active Energy + calibration: + current_gain: 3133655 + voltage_gain: -755235 + power_gain: -1345638 + phase_angle: 188 + phase_c: + name: Phase C + voltage: Voltage + current: Current + active_power: Active Power + power_factor: Power Factor + forward_active_energy: Forward Active Energy + reverse_active_energy: Reverse Active Energy + calibration: + current_gain: 3111158 + voltage_gain: -743813 + power_gain: -1351437 + phase_angle: 180 + neutral: + name: Test 3 Unused + current: Current + calibration: + current_gain: 3011156 + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`ade7880/ade7880.h` +- :ghedit:`Edit` + +.. _datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADE7880.pdf +.. _`Shelly 3EM`: https://devices.esphome.io/devices/Shelly-3EM diff --git a/images/ade7880.svg b/images/ade7880.svg new file mode 100644 index 000000000..db17e1b65 --- /dev/null +++ b/images/ade7880.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index ec3967c43..9c169c5ce 100644 --- a/index.rst +++ b/index.rst @@ -262,6 +262,7 @@ Electricity *********** .. imgtable:: + ADE7880, components/sensor/ade7880, ade7880.svg, Voltage & Current & Power ADE7953, components/sensor/ade7953, ade7953.svg, Power ATM90E26, components/sensor/atm90e26, atm90e26.jpg, Voltage & Current & Power ATM90E32, components/sensor/atm90e32, atm90e32.jpg, Voltage & Current & Power From 26a717af0aeaa7667b4b2b5db43ad9f1cc4c6feb Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Tue, 20 Feb 2024 15:38:28 -0600 Subject: [PATCH 07/84] Update VA docs to add on_idle action (#3572) --- components/voice_assistant.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst index c59d57a5f..b3c487f36 100644 --- a/components/voice_assistant.rst +++ b/components/voice_assistant.rst @@ -64,6 +64,8 @@ Configuration: (voice response) playback starts. Requires ``speaker`` to be configured. - **on_tts_stream_end** (*Optional*, :ref:`Automation `): An automation to perform when audio stream (voice response) playback ends. Requires ``speaker`` to be configured. +- **on_idle** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant is idle (no other actions/states are in progress). - **on_error** (*Optional*, :ref:`Automation `): An automation to perform when the voice assistant has encountered an error. The error code and message are available to automations as the variables ``code`` and ``message``. From 46790fd346395c8f911385256776e3a5a8986520 Mon Sep 17 00:00:00 2001 From: Stephen Tierney Date: Wed, 21 Feb 2024 15:10:07 +1100 Subject: [PATCH 08/84] LTR390 - Multiple fixes (sensor name, descriptions and notes) (#3585) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/sensor/ltr390.rst | 51 +++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/components/sensor/ltr390.rst b/components/sensor/ltr390.rst index 3a0a751ed..4b6933d75 100644 --- a/components/sensor/ltr390.rst +++ b/components/sensor/ltr390.rst @@ -21,10 +21,14 @@ The :ref:`I²C Bus ` is required to be set up in your configuration for thi sensor: - platform: ltr390 - uv: + uv_index: name: "UV Index" + uv: + name: "UV Sensor Counts" light: name: "Light" + ambient_light: + name: "Light Sensor Counts" Configuration variables: ------------------------ @@ -33,8 +37,8 @@ Configuration variables: - **uv** (*Optional*): Sensor counts for the UV sensor (#). All options from :ref:`Sensor `. - **light** (*Optional*): Lux of ambient light (lx). All options from :ref:`Sensor `. - **ambient_light** (*Optional*): Sensor counts for the Ambient light sensor (#). All options from :ref:`Sensor `. -- **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. See table below for details. Default is ``"X3"``. -- **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. See table below for details. Default is ``18``. +- **gain** (*Optional*, string): Adjusts the sensitivity of the sensor. A larger value means higher sensitivity. Default is ``"X18"``, see table below for options. +- **resolution** (*Optional*, int): ADC resolution. Higher resolutions require longer sensor integration times. Default is ``20``, see table below for options. - **window_correction_factor** (*Optional*, float): Window correction factor. Use larger values when using under tinted windows. Default is ``1.0``, must be ``>= 1.0``. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Default is ``0x53``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the @@ -45,7 +49,7 @@ Lux and UVI Formulas .. math:: - \text{lux} = \frac{0.6 \times \text{als}}{\text{gain} \times \text{int}} \times \text{wfac} + \text{lux} = \frac{0.6 \times \text{als}}{\text{gain} \times \frac{\text{int}}{100} } \times \text{wfac} .. math:: @@ -53,11 +57,22 @@ Lux and UVI Formulas where: -- ``als`` and ``uv`` are the sensor values -- ``gain`` is the amount of gain, see the table below for details -- ``int`` is the integration time in 100s of ms and is tied to the resolution, see the table below for details -- ``sensitivity`` has the value ``2300`` and is the sensor's count per UVI -- ``wfac`` is the window correction factor +- ``als`` and ``uv`` are the sensor values. +- ``gain`` is the sensor gain, see the table below for details. +- ``int`` is the integration time in ms and is tied to the resolution, see the table below for details. +- ``sensitivity`` is the sensor's count per UVI. See note below for details. +- ``wfac`` is the window correction factor. + +It is recommended to use the defaults of ``X18`` gain and resolution of 20 bits when UV Index sensing is required since +the data sheet only provides accurate conversion formula for this combination. The UVI value is linearly scaled from +this reference point when using other combinations of gain and resolution, which may be slightly inaccurate. The scaling +formula is: + +.. math:: + + \text{sensitivity} = 2300 \times \frac{\text{gain}}{18} \times \frac{\text{int}}{400} + +where :math:`2300` is the sensor count per UVI at the default configuration. Gain ---- @@ -66,7 +81,7 @@ Gain :widths: 25 25 :header-rows: 1 - * - Gain Parameter + * - Configuration value - gain * - X1 - 1 @@ -83,28 +98,28 @@ Gain Resolution ---------- -.. list-table:: Resolution +.. list-table:: :widths: 25 25 10 :header-rows: 1 - * - Resolution Parameter (bits) + * - Configuration value + - Resolution (bits) - Integration Time (ms) - - int * - 16 + - 16 - 25 - - 0.25 * - 17 + - 17 - 50 - - 0.5 * - 18 + - 18 - 100 - - 1 * - 19 + - 19 - 200 - - 2 * - 20 + - 20 - 400 - - 4 See Also -------- From ce7d691779c8a733c8bb4756c8ee55d3208d2a6b Mon Sep 17 00:00:00 2001 From: Stefan Rado <628587+kroimon@users.noreply.github.com> Date: Thu, 22 Feb 2024 04:03:17 +0100 Subject: [PATCH 09/84] Add documentation for uponor_smatrix component (#3381) --- components/uponor_smatrix.rst | 138 ++++++++++++++++++++++++++++++++++ images/uponor.svg | 4 + index.rst | 1 + 3 files changed, 143 insertions(+) create mode 100644 components/uponor_smatrix.rst create mode 100644 images/uponor.svg diff --git a/components/uponor_smatrix.rst b/components/uponor_smatrix.rst new file mode 100644 index 000000000..8da3617b8 --- /dev/null +++ b/components/uponor_smatrix.rst @@ -0,0 +1,138 @@ +Uponor Smatrix Base Pulse Underfloor Heating +============================================ + +.. seo:: + :description: Instructions for setting up an Uponor Smatrix Base Pulse underfloor heating control system in ESPHome. + :keywords: Uponor Smatrix, HCS, Thermostat + +The Uponor Smatrix component allows you to integrate an Uponor Smatrix Base Pulse underfloor heating control system in ESPHome without the need for an Smatrix Pulse Com R-208 communication module. +It directly communicates with the controller and thermostats via the RS485 thermostat bus. + +Connecting to the bus +--------------------- + +This component is able to communicate directly with the RS485 thermostat bus. For that, you will need to connect an RS485 to TTL converter to a UART bus of your ESPHome device. + +The RS485 side of the converter can either be connected to one of the A/B terminals on the controller or on one of the thermostats. +The +/- terminals provide 5 volts and can be used to power your ESPHome device. + +The :ref:`UART Component ` must be configured with a baud rate of 19200, 8 data bits, no parity, 1 stop bit. + +.. _uponor-gettingstarted: + +Getting started +--------------- + +The controller and the thermostats have unique addresses used for communication that are not displayed anywhere but can only be found when scanning the bus. +Start with a basic configuration that just contains the UART and Uponor hub components. Make sure that the UART pins are configured according to your wiring and the baud rate is set to 19200. + +.. code-block:: yaml + + uponor_smatrix: + +When you upload this configuration to your ESPHome device and connect it to the Uponor Smatrix bus, it will print a list of detected addresses to the log output. + +.. code-block:: text + + [00:00:00][C][uponor_smatrix:019]: Uponor Smatrix + [00:00:00][C][uponor_smatrix:020]: System address: 0x110B + [00:00:00][C][uponor_smatrix:031]: Detected unknown device addresses: + [00:00:00][C][uponor_smatrix:033]: 0xDE62 + [00:00:00][C][uponor_smatrix:033]: 0xDDFF + [00:00:00][C][uponor_smatrix:033]: 0xDE72 + [00:00:00][C][uponor_smatrix:033]: 0xDE4A + [00:00:00][C][uponor_smatrix:033]: 0xDE13 + +With that you can then add ``climate`` or ``sensor`` components for the detected devices. Optionally, you can also statically add the detected system address to your ``uponor_smatrix`` configuration. + +.. code-block:: yaml + + uponor_smatrix: + address: 0x110B + + climate: + - platform: uponor_smatrix + address: 0xDE13 + name: Thermostat Living Room + + +Controller/Hub component +------------------------ + +The main ``uponor_smatrix`` component is responsible for the communication with the controller and thermostats and distributes data to the climate and sensor components described below. + +It is also able to synchronize the date and time of the thermostats with a time source in case your system has thermostats that can be programmed with a time schedule. + +.. code-block:: yaml + + uponor_smatrix: + address: 0x110B + uart_id: my_uart + time_id: my_time + +Configuration variables: +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **address** (*Optional*, int): The 16 bit system/controller address. This will be automatically detected from the bus if not specified. See :ref:`uponor-gettingstarted` on how to find the address. +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want to use multiple UART buses. +- **time_id** (*Optional*, :ref:`config-id`): Specify the ID of the :doc:`Time Component