Merge branch 'current' into next

changelog/2023.10.0.rst

@@ -53,6 +53,11 @@ Release 2023.10.2 - October 24
 - fix canbus send config :esphomepr:`5585` by :ghuser:`ssieb`
 - Allow set climate preset to NONE :esphomepr:`5588` by :ghuser:`dentra`
 
+Release 2023.10.3 - October 24
+------------------------------
+
+- Set IP address `type` only when IPv4 and IPv6 are both enabled :esphomepr:`5595` by :ghuser:`kbx81`
+
 Breaking changes
 ----------------
 

components/binary_sensor/ble_presence.rst

@@ -5,8 +5,15 @@ ESP32 Bluetooth Low Energy Device
     :description: Instructions for setting up BLE binary sensors for the ESP32.
     :image: bluetooth.svg
 
-The ``ble_presence`` binary sensor platform lets you track the presence of a
+The ``ble_presence`` binary sensor platform lets you track the presence of a Bluetooth Low Energy device.
-Bluetooth Low Energy device.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. figure:: images/esp32_ble-ui.png
     :align: center

components/ble_client.rst

@@ -5,33 +5,31 @@ BLE Client
     :description: Configuration of the BLE client on ESP32.
     :image: bluetooth.svg
 
-The ``ble_client`` component enables connections to Bluetooth
+The ``ble_client`` component enables connections to Bluetooth Low Energy devices in order to query and
-Low Energy devices in order to query and control them. This
+control them. This component does not expose any sensors or output components itself, but merely manages
-component does not expose any sensors or output components itself,
+connections to them for use by other components.
-but merely manages connections to them for use by other components.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. note::
 
-    The BLE software stack on the ESP32 consumes a significant
+    A maximum of three devices is supported due to limitations in the ESP32 BLE stack. If you wish to
-    amount of RAM on the device. As such, you may experience
+    connect more devices, use additional ESP32 boards.
-    frequent crashes due to out-of-memory if you enable many
-    other components.
 
-    A maximum of three devices is supported due to limitations in the
+    This component supports devices that require a 6 digit PIN code for authentication.
-    ESP32 BLE stack. If you wish to connect more devices, use additional
-    ESP32 boards.
 
-    This component supports devices that require a 6 digit PIN code
+    Currently, devices connected with the client cannot be supported by other components based on
-    for authentication.
+    :doc:`/components/esp32_ble_tracker` as they listen to advertisements which are only sent by devices
-
-    Currently, devices connected with the client cannot be
-    supported by other components based on :doc:`/components/esp32_ble_tracker`
-    as they listen to advertisements which are only sent by devices
     without an active connection.
 
-Despite the last point above, the ``ble_client`` component requires
+Despite the last point above, the ``ble_client`` component requires the ``esp32_ble_tracker`` component in order
-the ``esp32_ble_tracker`` component in order to discover available
+to discover available client devices.
-client devices.
 
 .. code-block:: yaml
 

components/canbus.rst

@@ -171,12 +171,11 @@ There are several forms to use it:
       - canbus.send: 'hello'
 
       # Templated, return type is std::vector<uint8_t>
-      - canbus.send: !lambda
+      - canbus.send: !lambda return {0x00, 0x20, 0x42};
-          return {0x00, 0x20, 0x42};
 
 Configuration variables:
 
-- **data** (**Required**, binary data): Data to transmit, up to 8 bytes or
+- **data** (**Required**, binary data, :ref:`templatable <config-templatable>`): Data to transmit, up to 8 bytes or
   characters are supported by can bus per frame.
 - **canbus_id** (*Optional*): Optionally set the can bus id to use for transmitting
   the frame. Not needed if you are using only 1 can bus.

components/display/index.rst

@@ -185,6 +185,11 @@ Next, create a ``font:`` section in your configuration:
       - file: "fonts/tom-thumb.bdf"
         id: tomthumb
         
+      - file: 'gfonts://Material+Symbols+Outlined'
+        id: icon_font_50
+        size: 50
+        glyphs: ["\U0000e425"] # mdi-timer
+
     display:
       # ...
 
@@ -197,7 +202,8 @@ Configuration variables:
 
     **Google Fonts**:
 
-    Each Google Font will be downloaded once and cached for future use.
+    Each Google Font will be downloaded once and cached for future use. This can also be used to download Material 
+    Symbols or Icons as in the example above.
 
   - **family** (**Required**, string): The name of the Google Font family.
   - **weight** (*Optional*, enum): The weight of the font. Can be either the text name or the integer value:

components/esp32_ble.rst

@@ -8,6 +8,14 @@ BLE Component
 The ``esp32_ble`` component in ESPHome sets up the Bluetooth LE stack on the device so that a :doc:`esp32_ble_server`
 can run.
 
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
+
 .. code-block:: yaml
 
     # Example configuration

components/esp32_ble_beacon.rst

@@ -9,6 +9,13 @@ The ``esp32_ble_beacon`` component creates a Bluetooth Low Energy Beacon with yo
 Beacons are BLE devices that repeatedly just send out a pre-defined packet of data. This packet
 can then be received by devices like smartphones and can then be used to track a phone's location.
 
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/esp32_ble_server.rst

@@ -9,6 +9,14 @@ The ``esp32_ble_server`` component in ESPHome sets up a simple BLE GATT server t
 manufacturer and board. This component allows other components to create their own services to expose
 data and control.
 
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
+
 .. code-block:: yaml
 
     # Example configuration

components/esp32_ble_tracker.rst

@@ -5,11 +5,19 @@ ESP32 Bluetooth Low Energy Tracker Hub
     :description: Instructions for setting up ESP32 bluetooth low energy device trackers using ESPHome.
     :image: bluetooth.svg
 
-The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low
+The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low energy devices
-energy devices using your ESP32 node.
+using your ESP32 node.
 
-See :ref:`Setting up devices <esp32_ble_tracker-setting_up_devices>`
+See :ref:`Setting up devices <esp32_ble_tracker-setting_up_devices>` for information on how you can determine
-for information on how you can find out the MAC address of a device and track it using ESPHome.
+the MAC address of a device and track it using ESPHome.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/esp32_camera.rst

@@ -176,6 +176,12 @@ Test Setting:
 Configuration for Ai-Thinker Camera
 -----------------------------------
 
+.. warning::
+
+    GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM. 
+    Using this GPIO for other purposes (eg as a button) will trigger the watchdog.
+    Further information on pin notes can be found here: https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md
+
 .. code-block:: yaml
 
     # Example configuration entry
@@ -436,6 +442,33 @@ Configuration for ESP-EYE
       name: My Camera
       # ...
 
+Configuration for ESP32S3_EYE on `Freenove ESP32-S3-DevKitC-1 <https://github.com/Freenove/Freenove_ESP32_S3_WROOM_Board>`_
+---------------------------------------------------------------------------------------------------------------------------
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    external_components:
+      - source:
+          type: git
+          url: https://github.com/MichaKersloot/esphome_custom_components
+        components: [ esp32_camera ]
+
+    esp32_camera:
+      external_clock:
+        pin: GPIO15
+        frequency: 20MHz
+      i2c_pins:
+        sda: GPIO4
+        scl: GPIO5
+      data_pins: [GPIO11, GPIO9, GPIO8, GPIO10, GPIO12, GPIO18, GPIO17, GPIO16]
+      vsync_pin: GPIO6
+      href_pin: GPIO7
+      pixel_clock_pin: GPIO13
+
+      # Image settings
+      name: My Camera
+      # ...
 
 See Also
 --------

components/esp32_improv.rst

@@ -6,10 +6,17 @@ Improv via BLE
     :image: improv-social.png
 
 The ``esp32_improv`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
-for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy to receive the credentials.
+for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy (BLE) to receive the credentials.
 
 The ``esp32_improv`` component will automatically set up the :doc:`BLE Server <esp32_ble>`.
 
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/libretiny.rst

@@ -6,7 +6,7 @@ LibreTiny Platform
     :image: libretiny.svg
 
 This component contains platform-specific options for the `LibreTiny <https://docs.libretiny.eu/>`__ platform.
-It provides support for the following microcontrollers:
+It provides support for the following microcontrollers, commonly used in Tuya devices, amongst others:
 
 - **BK72xx**: BK7231T, BK7231N
 - **RTL87xx**: RTL8710BN, RTL8710BX
@@ -49,7 +49,7 @@ Configuration variables:
 
   - :ref:`Advanced options <advanced-options>`
 
-- **family** (*Optional*, boolean): The family of LibreTiny-supported microcontrollers that is used on this board.
+- **family** (*Optional*, string): The family of LibreTiny-supported microcontrollers that is used on this board.
   One of ``bk7231n``, ``bk7231t``, ``rtl8710b``, ``rtl8720c``, ``bk7251``, ``bk7231q``.
   Defaults to the variant that is detected from the board, if a board that's unknown to ESPHome is used,
   this option is mandatory. **It's recommended not to include this option**.
@@ -58,8 +58,6 @@ Configuration variables:
 
     Support for the LibreTiny platform is still in development and there could be issues or missing components.
 
-    In particular, **MQTT is not supported yet**, because of reported stability issues.
-
     Please report any issues on `LibreTiny GitHub <https://github.com/kuba2k2/libretiny>`__.
 
 Getting Started

components/mcp23Sxx.rst

@@ -2,11 +2,11 @@ MCP23Sxx I/O Expander
 =====================
 
 .. seo::
-    :description: Instructions for setting up MCP23S08, MCP23S16 or MCP23S17 digital port expander in ESPHome. This is exactly the same API as the MCP230XX I/O Expander except talks on the SPI bus
+    :description: Instructions for setting up MCP23S08, MCP23S16 or MCP23S17 digital port expander in ESPHome. This series features exactly the same API as the MCP230xx I/O Expander (I²C)
     :image: mcp230xx.svg
 
 The Microchip MCP23Sxx series of general purpose, parallel I/O expansion for SPI bus applications.
-This is exactly the same API as the MCP23SXX I/O Expander except talks on the SPI bus
+This series features exactly the same API as the MCP230xx I/O Expander (I²C).
 
 **Supported Variants :**
 

components/microphone/i2s_audio.rst

@@ -5,8 +5,17 @@ I²S Audio Microphone
     :description: Instructions for setting up I²S based microphones in ESPHome.
     :image: i2s_audio.svg
 
-The ``i2s_audio`` microphone platform allows you to receive audio via the the
+The ``i2s_audio`` microphone platform allows you to receive audio via the the :doc:`/components/i2s_audio`.
-:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
+
+This platform only works on ESP32 based chips.
+
+.. warning::
+
+    Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
+    combination with Voice Assistant and/or other audio components.
 
 .. code-block:: yaml
 

components/modbus.rst

@@ -7,9 +7,9 @@ Modbus Component
     :description: Instructions for setting up Modbus in ESPHome.
     :keywords: Modbus
 
-The Modbus protocol is used by many consumer and industrial devices for communication.
+The ModBUS protocol is used by many consumer and industrial devices for communication.
 This component allows components in ESPHome to communicate to those devices.
-Modbus requires a :ref:`UART Bus <uart>` to communicate.
+ModBUS requires a :ref:`UART Bus <uart>` to communicate.
 
 .. code-block:: yaml
 
@@ -27,9 +27,9 @@ Configuration variables:
   This is useful for RS485 transceivers that do not have automatic flow control switching,
   like the common MAX485.
 
-- **send_wait_time** (*Optional*, :ref:`config-time`): Time in milliseconds before a new modbus command is sent if an answer from a previous command is pending. Defaults to 250 ms.
+- **send_wait_time** (*Optional*, :ref:`config-time`): Time in milliseconds before the next ModBUS command is sent if an answer from a previous command is pending. Defaults to 250 ms.
-  If multiple modbus devices are attached increasing this value can help avoiding to to overlapping reads.
+  If multiple ModBUS devices are attached to the same bus increasing this value can help avoiding to to overlapping reads.
-  When 2 devices are sending a command at the same the response read from uart can't be assigned to the proper design.
+  When two devices are sending a command at the same time the response read from UART can't be assigned to the proper design.
   This value defines the maximum queuing time for a command before it is send anyways.
   
 - **disable_crc** (*Optional*, boolean): Ignores a bad CRC if set to ``true``. Defaults to ``false``
@@ -44,7 +44,6 @@ See Also
 - :doc:`/components/switch/modbus_controller`
 - :doc:`/components/number/modbus_controller`
 - :doc:`/components/output/modbus_controller`
-- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) <https://devices.esphome.io/devices/epever_mptt_tracer_an>`__
 - `Modbus RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
 - :ref:`uart`
 - :apiref:`modbus/modbus.h`

components/modbus_controller.rst

@@ -2,28 +2,31 @@ Modbus Controller
 =================
 
 .. seo::
-    :description: Instructions for setting up the Modbus Controller component.
+    :description: Instructions for setting up the ModBUS Controller component.
     :image: modbus.png
 
-The ``modbus_controller`` component creates a RS485 connection to control a modbus device
+The ``modbus_controller`` component creates a RS485 connection to control a ModBUS slave device, letting your ESPHome node to act as a ModBUS master.
+You can access the coils and registers from your slave ModBUS device as sensors, switches or various other ESPHome components and present them to your favorite Home Automation system.
 
 .. figure:: /images/modbus.png
     :align: center
     :width: 25%
 
-The ``modbus_controller`` component uses the modbus component
+The ``modbus_controller`` component relies on the :doc:`/components/modbus`.
 
 
 
 Hardware setup
 --------------
-A RS 485 module connected to an ESP32, for example:
+You need an RS485 transceiver module:
 
 .. figure:: /images/rs485.jpg
 
-See `How is this RS485 Module Working? <https://electronics.stackexchange.com/questions/244425/how-is-this-rs485-module-working>`__ on stackexchange for more details
+See `How is this RS485 module working? <https://electronics.stackexchange.com/questions/244425/how-is-this-rs485-module-working>`__ on stackexchange for more details.
 
-The controller connects to the UART of the MCU. For ESP32  GPIO PIN 16 to TXD PIN 17 to RXD are the default ports but any other pins can be used as well. 3.3V to VCC and GND to GND.
+The transceiver connects to the UART of the MCU. For ESP32, pin ``16`` to ``TXD`` and pin ``17`` to ``RXD`` are the default ones but any other pins can be used as well. ``3.3V`` to ``VCC`` and naturally ``GND`` to ``GND``.
+
+On the bus side, you need 120 Ohm termination resistors at the ends of the bus cable as per ModBUS standard. Some transceivers have this already solderes onboard, and some slave devices may have them preinstalled with a jumper or a dip switch.
 
 .. note::
 
@@ -31,7 +34,7 @@ The controller connects to the UART of the MCU. For ESP32  GPIO PIN 16 to TXD PI
 
     For hardware serial only a limited set of pins can be used. Either ``tx_pin: GPIO1`` and ``rx_pin: GPIO3``  or ``tx_pin: GPIO15`` and ``rx_pin: GPIO13``.
 
-    The disadvantage of using the hardware uart is that you can't use serial logging because the serial logs would be sent to the modbus device and cause errors.
+    The disadvantage of using the hardware uart is that you can't use serial logging because the serial logs would be sent to the ModBUS device and cause errors.
 
     Serial logging can be disabled by setting ``baud_rate: 0``.
 
@@ -48,29 +51,27 @@ The controller connects to the UART of the MCU. For ESP32  GPIO PIN 16 to TXD PI
 Configuration variables:
 ------------------------
 
-- **modbus_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the modbus hub.
+- **modbus_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the ``modbus`` hub.
 
-- **address** (**Required**, :ref:`config-id`): The modbus address of the device
+- **address** (**Required**, :ref:`config-id`): The ModBUS address of the slave device
-  Specify the modbus device address of the.
 
-- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is 0ms
+- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is ``0ms``.
-  Because some modbus devices limit the rate of requests the interval between sending requests to the device can be modified.
+  Some ModBUS slave devices limit the rate of requests from the master, the interval between sending requests can be altered.
 
 - **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
   Defaults to 60 seconds.
 
-- **offline_skip_updates** (*Optional*, integer): When a controller doesn't respond to a command, it is
+- **offline_skip_updates** (*Optional*, integer): When a slave doesn't respond to a command, it is
   marked as offline, you can specify how many updates will be skipped while it is offline. If using a bus with multiple
-  controllers, this avoids waiting for timeouts allowing to read other controllers in the same bus. When the controller
+  slaves, this avoids waiting for timeouts allowing to read other slaves in the same bus. When the slave
   responds to a command, it'll be marked online again.
 
 
 Example
 -------
-The following code create a modbus_controller hub talking to a modbus device at address 1 with 115200 bps
+The following code creates a ``modbus_controller`` hub talking to a ModBUS device at address ``1`` with ``115200`` bps
 
-
+ModBUS sensors can be directly defined (inline) under the ``modbus_controller`` hub or as standalone components
-Modbus sensors can be directly defined (inline) under the modbus_controller hub or as standalone components
 Technically there is no difference between the "inline" and the standard definitions approach.
 
 .. code-block:: yaml
@@ -88,8 +89,7 @@ Technically there is no difference between the "inline" and the standard definit
 
     modbus_controller:
       - id: epever
-        ## the Modbus device addr
+        address: 0x1   ## address of the ModBUS slave device on the bus
-        address: 0x1
         modbus_id: modbus1
         setup_priority: -10
 
@@ -100,7 +100,7 @@ Technically there is no difference between the "inline" and the standard definit
         id: rtc_clock
         internal: true
         register_type: holding
-        address: 0x9013
+        address: 0x9013    ## address of the register inside the ModBUS slave device
         register_count: 3
         raw_encode: HEXBYTES
         response_size: 6
@@ -208,7 +208,6 @@ To gather some of these bits as binary sensors in ESPHome, use ``bitmask``:
 
 
 
-
 Protocol decoding example
 -------------------------
 
@@ -298,9 +297,8 @@ Protocol decoding example
         accuracy_decimals: 0
 
 
-
 To minimize the required transactions all registers with the same base address are read in one request.
-The response is mapped to the sensor based on register_count and offset in bytes.
+The response is mapped to the sensor based on ``register_count`` and offset in bytes. For example:
 
 **Request**
 
@@ -331,7 +329,7 @@ The response is mapped to the sensor based on register_count and offset in bytes
 +--------+------------+--------------------+--------------------------------------------+
 | offset | data       | value (type)       | description                                |
 +========+============+====================+============================================+
-|  H     | 0x1  (01)  |                    | device address                             |
+|   H    | 0x1  (01)  |                    | device address                             |
 +--------+------------+--------------------+--------------------------------------------+
 |   H    | 0x4  (04)  |                    | function code                              |
 +--------+------------+--------------------+--------------------------------------------+
@@ -379,161 +377,157 @@ The response is mapped to the sensor based on register_count and offset in bytes
 +--------+------------+--------------------+--------------------------------------------+
 
 
+.. note::
 
-Note
+    Write support is only implemented for switches and selects.
-----
+    However the C++ code provides the required API to write to a ModBUS device.
 
-Write support is only implemented for switches and selects.
+    These methods can be called from a lambda.
-However the C++ code provides the required API to write to a modbus device.
 
-These methods can be called from a lambda.
+    Here is an example how to set config values to for an EPEVER Trace AN controller.
+    The code synchronizes the localtime of MCU to the epever controller
+    The time is set by writing 12 bytes to register 0x9013.
+    Then battery charge settings are sent.
     
-Here is an example how to set config values to for an EPEVER Trace AN controller.
+    .. code-block:: yaml
-The code synchronizes the localtime of MCU to the epever controller
-The time is set by writing 12 bytes to register 0x9013.
-Then battery charge settings are sent.
 
+        esphome:
+          on_boot:
+            ## configure controller settings at setup
+            ## make sure priority is lower than setup_priority of modbus_controller
+            priority: -100
+            then:
+              - lambda: |-
+                  // get local time and sync to controller
+                  time_t now = ::time(nullptr);
+                  struct tm *time_info = ::localtime(&now);
+                  int seconds = time_info->tm_sec;
+                  int minutes = time_info->tm_min;
+                  int hour = time_info->tm_hour;
+                  int day = time_info->tm_mday;
+                  int month = time_info->tm_mon + 1;
+                  int year = time_info->tm_year % 100;
+                  esphome::modbus_controller::ModbusController *controller = id(epever);
+                  // if there is no internet connection localtime returns year 70
+                  if (year != 70) {
+                    // create the payload
+                    std::vector<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
+                                                      uint16_t((year << 8) | month)};
+                    // Create a ModBUS command item with the time information as the payload
+                    esphome::modbus_controller::ModbusCommandItem set_rtc_command =
+                        esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
+                    // Submit the command to the send queue
+                    epever->queue_command(set_rtc_command);
+                    ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
+                            year + 2000);
+                  }
+                  // Battery settings
+                  // Note: these values are examples only and apply my AGM Battery
+                  std::vector<uint16_t> battery_settings1 = {
+                      0,       // 9000 Battery Type 0 =  User
+                      0x0073,  // 9001 Battery Cap 0x55 == 115AH
+                      0x012C,  // 9002 Temp compensation -3V /°C/2V
+                      0x05DC,  // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
+                      0x058C,  // 9004 0x58C == 1480 Charging Limit Voltage 14,8
+                      0x058C,  // 9005 Over Voltage Reconnect Voltage 14,8
+                      0x05BF,  // 9006 Equalize Charging Voltage 14,6
+                      0x05BE,  // 9007 Boost Charging Voltage 14,7
+                      0x0550,  // 9008 Float Charging Voltage 13,6
+                      0x0528,   // 9009 Boost Reconnect Charging Voltage 13,2
+                      0x04C4,  // 900A Low Voltage Reconnect Voltage 12,2
+                      0x04B0,  // 900B Under Voltage Warning Reconnect Voltage 12,0
+                      0x04BA,  // 900c Under Volt. Warning Volt 12,1
+                      0x04BA,  // 900d Low Volt. Disconnect Volt. 11.8
+                      0x04BA   // 900E Discharging Limit Voltage 11.8
+                  };
     
-.. code-block:: yaml
+                  // Boost and equalization periods
+                  std::vector<uint16_t> battery_settings2 = {
+                      0x0000,  // 906B Equalize Duration (min.) 0
+                      0x0075   // 906C Boost Duration (aka absorb) 117 mins
+                  };
+                  esphome::modbus_controller::ModbusCommandItem set_battery1_command =
+                      esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
+                                                                                                  battery_settings1);
     
-    esphome:
+                  esphome::modbus_controller::ModbusCommandItem set_battery2_command =
-      on_boot:
+                      esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(),
-        ## configure controller settings at setup
+                                                                                                  battery_settings2);
-        ## make sure priority is lower than setup_priority of modbus_controller
+                  delay(200) ;
-        priority: -100
+                  controller->queue_command(set_battery1_command);
-        then:
+                  delay(200) ;
-          - lambda: |-
+                  controller->queue_command(set_battery2_command);
-              // get local time and sync to controller
+                  ESP_LOGI("ModbusLambda", "EPSOLAR Battery set");
-              time_t now = ::time(nullptr);
-              struct tm *time_info = ::localtime(&now);
-              int seconds = time_info->tm_sec;
-              int minutes = time_info->tm_min;
-              int hour = time_info->tm_hour;
-              int day = time_info->tm_mday;
-              int month = time_info->tm_mon + 1;
-              int year = time_info->tm_year % 100;
-              esphome::modbus_controller::ModbusController *controller = id(epever);
-              // if there is no internet connection localtime returns year 70
-              if (year != 70) {
-                // create the payload
-                std::vector<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
-                                                  uint16_t((year << 8) | month)};
-                // Create a modbus command item with the time information as the payload
-                esphome::modbus_controller::ModbusCommandItem set_rtc_command =
-                    esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
-                // Submit the command to the send queue
-                epever->queue_command(set_rtc_command);
-                ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
-                        year + 2000);
-              }
-              // Battery settings
-              // Note: these values are examples only and apply my AGM Battery
-              std::vector<uint16_t> battery_settings1 = {
-                  0,       // 9000 Battery Type 0 =  User
-                  0x0073,  // 9001 Battery Cap 0x55 == 115AH
-                  0x012C,  // 9002 Temp compensation -3V /°C/2V
-                  0x05DC,  // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
-                  0x058C,  // 9004 0x58C == 1480 Charging Limit Voltage 14,8
-                  0x058C,  // 9005 Over Voltage Reconnect Voltage 14,8
-                  0x05BF,  // 9006 Equalize Charging Voltage 14,6
-                  0x05BE,  // 9007 Boost Charging Voltage 14,7
-                  0x0550,  // 9008 Float Charging Voltage 13,6
-                  0x0528,   // 9009 Boost Reconnect Charging Voltage 13,2
-                  0x04C4,  // 900A Low Voltage Reconnect Voltage 12,2
-                  0x04B0,  // 900B Under Voltage Warning Reconnect Voltage 12,0
-                  0x04BA,  // 900c Under Volt. Warning Volt 12,1
-                  0x04BA,  // 900d Low Volt. Disconnect Volt. 11.8
-                  0x04BA   // 900E Discharging Limit Voltage 11.8
-              };
     
-              // Boost and equalization periods
+        uart:
-              std::vector<uint16_t> battery_settings2 = {
+          id: mod_bus
-                  0x0000,  // 906B Equalize Duration (min.) 0
+          tx_pin: 19
-                  0x0075   // 906C Boost Duration (aka absorb) 117 mins
+          rx_pin: 18
-              };
+          baud_rate: 115200
-              esphome::modbus_controller::ModbusCommandItem set_battery1_command =
+          stop_bits: 1
-                  esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
-                                                                                              battery_settings1);
     
-              esphome::modbus_controller::ModbusCommandItem set_battery2_command =
+        modbus:
-                  esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(),
+          #flow_control_pin: 23
-                                                                                              battery_settings2);
+          send_wait_time: 200ms
-              delay(200) ;
+          id: mod_bus_epever
-              controller->queue_command(set_battery1_command);
-              delay(200) ;
-              controller->queue_command(set_battery2_command);
-              ESP_LOGI("ModbusLambda", "EPSOLAR Battery set");
     
-    uart:
+        modbus_controller:
-      id: mod_bus
+          - id: epever
-      tx_pin: 19
+            ## the Modbus device addr
-      rx_pin: 18
+            address: 0x1
-      baud_rate: 115200
+            modbus_id: mod_bus_epever
-      stop_bits: 1
+            command_throttle: 0ms
+            setup_priority: -10
+            update_interval: ${updates}
     
-    modbus:
+        sensor:
-      #flow_control_pin: 23
+          - platform: modbus_controller
-      send_wait_time: 200ms
+            modbus_controller_id: epever
-      id: mod_bus_epever
+            id: array_rated_voltage
-
+            name: "array_rated_voltage"
-    modbus_controller:
+            address: 0x3000
-      - id: epever
+            unit_of_measurement: "V"
-        ## the Modbus device addr
+            register_type: read
-        address: 0x1
+            value_type: U_WORD
-        modbus_id: mod_bus_epever
+            accuracy_decimals: 1
-        command_throttle: 0ms
+            filters:
-        setup_priority: -10
+              - multiply: 0.01
-        update_interval: ${updates}
-
-    sensor:
-      - platform: modbus_controller
-        modbus_controller_id: epever
-        id: array_rated_voltage
-        name: "array_rated_voltage"
-        address: 0x3000
-        unit_of_measurement: "V"
-        register_type: read
-        value_type: U_WORD
-        accuracy_decimals: 1
-        filters:
-          - multiply: 0.01
-
-      - platform: modbus_controller
-        modbus_controller_id: epever
-        id: array_rated_current
-        name: "array_rated_current"
-        address: 0x3001
-        unit_of_measurement: "A"
-        register_type: read
-        value_type: U_WORD
-        accuracy_decimals: 2
-        filters:
-          - multiply: 0.01
-
-      - platform: modbus_controller
-        modbus_controller_id: epever
-        id: array_rated_power
-        name: "array_rated_power"
-        address: 0x3002
-        unit_of_measurement: "W"
-        register_type: read
-        value_type: U_DWORD_R
-        accuracy_decimals: 1
-        filters:
-          - multiply: 0.01
     
+          - platform: modbus_controller
+            modbus_controller_id: epever
+            id: array_rated_current
+            name: "array_rated_current"
+            address: 0x3001
+            unit_of_measurement: "A"
+            register_type: read
+            value_type: U_WORD
+            accuracy_decimals: 2
+            filters:
+              - multiply: 0.01
     
+          - platform: modbus_controller
+            modbus_controller_id: epever
+            id: array_rated_power
+            name: "array_rated_power"
+            address: 0x3002
+            unit_of_measurement: "W"
+            register_type: read
+            value_type: U_DWORD_R
+            accuracy_decimals: 1
+            filters:
+              - multiply: 0.01
 
 
 See Also
 --------
 
-- :doc:`/components/sensor/modbus_controller`
+- :doc:`/components/modbus`
 - :doc:`/components/binary_sensor/modbus_controller`
 - :doc:`/components/text_sensor/modbus_controller`
 - :doc:`/components/switch/modbus_controller`
 - :doc:`/components/number/modbus_controller`
 - :doc:`/components/output/modbus_controller`
+- `ModBUS RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
 - `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) <https://devices.esphome.io/devices/epever_mptt_tracer_an>`__
-- `Modbus RTU Protocol Description <https://www.modbustools.com/modbus.html>`__
+- `Genvex, Nibe, Alpha-Innotec heat recovery ventilation <https://devices.esphome.io/devices/Genvex-Nibe-AlphaInnotec-heat-recovery-ventilation>`__
 - :ghedit:`Edit`

components/output/ble_client.rst

@@ -5,12 +5,17 @@ BLE Client Binary Output
     :description: Writes a binary value to a BLE device.
     :image: bluetooth.svg
 
-The ``ble_client`` component is a output that can
+The ``ble_client`` component is a output that can write a binary value to service characteristics of BLE devices.
-write a binary value to service characteristics of
-BLE devices.
 
-For more information on BLE services and characteristics, see
+For more information on BLE services and characteristics, see :doc:`/components/ble_client`.
-:doc:`/components/ble_client`.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/sensor/ble_client.rst

@@ -5,11 +5,18 @@ BLE Client Sensor
     :description: Fetch numeric values from BLE devices.
     :image: bluetooth.svg
 
-The ``ble_client`` component is a sensor platform that can
+The ``ble_client`` component is a sensor platform that can query BLE devices for RSSI or specific
-query BLE devices for RSSI or specific values of service characteristics.
+values of service characteristics.
 
-For more information on BLE services and characteristics, see
+For more information on BLE services and characteristics, see :doc:`/components/ble_client`.
-:doc:`/components/ble_client`.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/sensor/ble_rssi.rst

@@ -10,6 +10,14 @@ The ``ble_rssi`` sensor platform lets you track the RSSI value or signal strengt
 BLE device. See :ref:`the binary sensor setup <esp32_ble_tracker-setting_up_devices>` for
 instructions for setting up this platform.
 
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
+
 .. code-block:: yaml
 
     # Example configuration entry

components/sensor/bme680.rst

@@ -103,6 +103,68 @@ configure this amount. Possible oversampling values:
 -  ``8x``
 -  ``16x`` (default)
 
+.. _bme680-advanced-configuration:
+
+Advanced Configuration
+----------------------
+
+Add indoor air quality (IAQ) calculation and IAQ label, based on the values in the `BME680 BSEC component </components/sensor/bme680_bsec.html?highlight=bme680#index-for-air-quality-iaq-measurement>`__ index.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: bme680
+        temperature:
+          name: "BME680 Temperature"
+          oversampling: 16x
+        pressure:
+          name: "BME680 Pressure"
+        humidity:
+          id: "humidity"
+          name: "BME680 Humidity"
+        gas_resistance:
+          id: "gas_resistance"
+          name: "BME680 Gas Resistance"
+        address: 0x77
+        update_interval: 60s
+      - platform: template
+        name: "BME680 Indoor Air Quality"
+        id: iaq
+        icon: "mdi:gauge"
+        # caulculation: comp_gas = log(R_gas[ohm]) + 0.04 log(Ohm)/%rh * hum[%rh]    
+        lambda: |-
+          return log(id(gas_resistance).state) + 0.04 *  id(humidity).state;
+    text_sensor:
+      - platform: template
+        name: "BME680 IAQ Classification"
+        icon: "mdi:checkbox-marked-circle-outline"
+        lambda: |-
+          if (int(id(iaq).state) <= 50) {
+            return {"Excellent"};
+          }
+          else if (int(id(iaq).state) <= 100) {
+            return {"Good"};
+          }
+          else if (int(id(iaq).state) <= 150) {
+            return {"Lightly polluted"};
+          }
+          else if (int(id(iaq).state) <= 200) {
+            return {"Moderately polluted"};
+          }
+          else if (int(id(iaq).state) <= 250) {
+            return {"Heavily polluted"};
+          }
+          else if (int(id(iaq).state) <= 350) {
+            return {"Severely polluted"};
+          }
+          else if (int(id(iaq).state) <= 500) {
+            return {"Extremely polluted"};
+          }
+          else {
+            return {"unknown"};
+          }
+
 See Also
 --------
 

components/sensor/hlw8012.rst

@@ -124,6 +124,148 @@ when SEL=1 voltage is measured. To accommodate this change use the following con
           name: "BL0937 Power"
         update_interval: 60s
 
+Calibration
+-----------
+
+What you need:
+
+- Your ESPHome power measurement plug
+- A calibrated power meter that can measure voltage, current, power and power factor
+- A large resistive load like an electric heater or kettle, ideally over 1000W
+
+Steps:
+
+- Find the currently used calibration values for ``current_resistor`` and ``voltage_divider`` in your device's YAML configuration or upload a new firmware with some known calibration values to the ESP.
+- Plug the ESP power measurement plug into the calibrated power meter.
+- Plug the load into the ESP plug.
+- Turn on the load and make sure the power factor (PF) displayed on the power meter is 1.0. If it's not, you need to pick a different load.
+- Wait for the readings to settle on both the power meter and the ESP.
+- Write down the voltage reading of the power meter and the ESP at the same time.
+- Write down the power reading of the power meter and the ESP at the same time.
+- Write down the current reading of the power meter and the ESP at the same time.
+- Use the calculator below to calculate the new calibration values for the ESP. These values will help it accurately measure power, voltage and current in the future.
+- Upload the new values to the ESP.
+
+Calibration values on the ESP:
+
+.. raw:: html
+
+    <table>
+    <tr><td>voltage_divider:</td><td><input type="text" inputmode="numeric" value="2351" id="voltage-divider" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
+    <tr><td>current_resistor:</td><td><input type="text" inputmode="numeric" value="0.001" id="current-resistor" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
+    <tr><td>current_multiply:</td><td><input type="text" inputmode="numeric" value="1" id="current-multiply" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"></td></tr>
+    </table>
+
+ESP measurements:
+
+.. raw:: html
+
+    <table>
+    <tr><td>Voltage:</td><td><input type="text" inputmode="numeric" id="sensor-voltage" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> V</td></tr>
+    <tr><td>Power:</td><td><input type="text" inputmode="numeric" id="sensor-power" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> W</td></tr>
+    <tr><td>Current:</td><td><input type="text" inputmode="numeric" id="sensor-current" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> A</td></tr>
+    </table>
+
+Power meter measurements:
+
+.. raw:: html
+
+    <table>
+    <tr><td>Voltage:</td><td><input type="text" inputmode="numeric" id="real-voltage" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> V</td></tr>
+    <tr><td>Power:</td><td><input type="text" inputmode="numeric" id="real-power" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> W</td></tr>
+    <tr><td>Current:</td><td><input type="text" inputmode="numeric" id="real-current" onchange="calc()" onkeypress="calc()" onpaste="calc()" oninput="calc()" style="width: 100px; max-width: 75vw;"> A</td></tr>
+    </table>
+
+New calibration values:
+
+.. raw:: html
+
+    <table>
+    <tr><td>voltage_divider:</td><td><input type="text" id="voltage-divider-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
+    <tr><td>current_resistor:</td><td><input type="text" id="current-resistor-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
+    <tr><td>current_multiply:</td><td><input type="text" id="current-multiply-new" onclick="this.focus();this.select()" style="width: 100px; max-width: 75vw;" readonly="readonly"></td></tr>
+    </table>
+
+New ESP measurements:
+
+.. raw:: html
+
+    <table>
+    <tr><td>Voltage:</td><td><input type="text" id="sensor-voltage-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> V</td></tr>
+    <tr><td>Power:</td><td><input type="text" id="sensor-power-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> W</td></tr>
+    <tr><td>Current:</td><td><input type="text" id="sensor-current-new" style="width: 100px; max-width: 75vw;" readonly="readonly"> A</td></tr>
+    </table>
+    <script>
+      function calc() {
+        let voltage_divider = parseFloat(document.getElementById("voltage-divider").value.replace(",", "."))
+        let current_resistor = parseFloat(document.getElementById("current-resistor").value.replace(",", "."))
+        let current_multiply = parseFloat(document.getElementById("current-multiply").value.replace(",", "."))
+        let real_voltage = parseFloat(document.getElementById("real-voltage").value.replace(",", "."))
+        let real_power = parseFloat(document.getElementById("real-power").value.replace(",", "."))
+        let real_current = parseFloat(document.getElementById("real-current").value.replace(",", "."))
+        let sensor_voltage = parseFloat(document.getElementById("sensor-voltage").value.replace(",", "."))
+        let sensor_power = parseFloat(document.getElementById("sensor-power").value.replace(",", "."))
+        let sensor_current = parseFloat(document.getElementById("sensor-current").value.replace(",", "."))
+        let calc_voltage = (document.getElementById("real-voltage").value !== "" || document.getElementById("sensor-voltage").value !== "")
+        let calc_power = (document.getElementById("real-power").value !== "" || document.getElementById("sensor-power").value !== "")
+        let calc_current = (document.getElementById("real-current").value !== "" || document.getElementById("sensor-current").value !== "")
+        let voltage_divider_new = voltage_divider;
+        let current_resistor_new = current_resistor;
+        let current_multiply_new = current_multiply;
+        if (calc_voltage) {
+          voltage_divider_new *= real_voltage / sensor_voltage;
+        }
+        if (calc_power) {
+          if (calc_voltage) {
+            current_resistor_new *= (sensor_power / sensor_voltage) / (real_power / real_voltage);
+          } else {
+            current_resistor_new *= sensor_power / real_power;
+          }
+        }
+        if (calc_current) {
+          if (calc_power) {
+            current_multiply_new *= (real_current / sensor_current) * (current_resistor_new / current_resistor);
+          } else {
+            current_resistor_new *= sensor_current / real_current;
+          }
+        }
+        document.getElementById("voltage-divider-new").value = voltage_divider_new;
+        document.getElementById("current-resistor-new").value = current_resistor_new;
+        document.getElementById("current-multiply-new").value = current_multiply_new;
+        let sensor_voltage_new = sensor_voltage * voltage_divider_new / voltage_divider
+        let sensor_power_new = sensor_power * (voltage_divider_new / current_resistor_new) / (voltage_divider / current_resistor)
+        let sensor_current_new = sensor_current * (current_multiply_new / current_resistor_new) / (current_multiply / current_resistor)
+        document.getElementById("sensor-voltage-new").value = Number(sensor_voltage_new.toFixed(8));
+        document.getElementById("sensor-power-new").value = Number(sensor_power_new.toFixed(8));
+        document.getElementById("sensor-current-new").value = Number(sensor_current_new.toFixed(8));
+      }
+    </script>
+
+Example Config:
+
+.. code-block:: yaml
+
+    substitutions:
+      voltage_divider: "2351"
+      current_resistor: "0.001"
+      current_multiply: "1.0"
+
+    sensor:
+      - platform: hlw8012
+        current_resistor: ${current_resistor}
+        voltage_divider: ${voltage_divider}
+        current:
+          name: "HLW8012 Current"
+          filters:
+            - multiply: ${current_multiply}
+        voltage:
+          name: "HLW8012 Voltage"
+        power:
+          name: "HLW8012 Power"
+        energy:
+          name: "HLW8012 Energy"
+        update_interval: 60s
+
 See Also
 --------
 

components/sensor/ld2410.rst

@@ -353,7 +353,7 @@ Configuration variables:
 Text Sensor
 -----------
 
-The ``ld2410`` text sensor allows you get information about your :doc:`ld2410`.
+The ``ld2410`` text sensor allows you to get information about your :doc:`ld2410`.
 
 .. code-block:: yaml
 
@@ -376,7 +376,7 @@ Configuration variables:
 Select
 -----------
 
-The ``ld2410`` select allows you control your :doc:`ld2410`.
+The ``ld2410`` select allows you to control your :doc:`ld2410`.
 
 .. code-block:: yaml
 
@@ -472,7 +472,7 @@ In order to calibrate your ``ld2410`` sensor perform the following:
 Home Assistant Card
 *******************
 
-For easy calibration process you can use the following custom manual card.
+For easy calibration process, you can use the following custom manual card.
 
 .. code-block:: yaml
 
@@ -502,13 +502,13 @@ For easy calibration process you can use the following custom manual card.
           - type: horizontal-stack
             cards:
               - type: entity
-                entity: 'sensor.DEVICE_distance_detection_cm'
+                entity: 'sensor.DEVICE_detection_distance'
                 name: distance
               - type: entity
-                entity: 'sensor.DEVICE_moving_distance_cm'
+                entity: 'sensor.DEVICE_moving_distance'
                 name: move
               - type: entity
-                entity: 'sensor.DEVICE_still_distance_cm'
+                entity: 'sensor.DEVICE_still_distance'
                 name: still
       - type: horizontal-stack
         cards:
@@ -529,11 +529,11 @@ For easy calibration process you can use the following custom manual card.
             name: presence
             state_color: true
           - type: entity
-            entity: 'binary_sensor.DEVICE_movement'
+            entity: 'binary_sensor.DEVICE_moving_target'
             name: movement
             state_color: true
           - type: entity
-            entity: 'binary_sensor.DEVICE_still'
+            entity: 'binary_sensor.DEVICE_still_target'
             name: still
             state_color: true
       - type: conditional

components/sensor/pm1006.rst

@@ -69,6 +69,22 @@ Example config:
           name: "Particulate Matter 2.5µm Concentration"
         update_interval: 20s
 
+
+If you run the PM1006 (2.5µm) or PM1006K (1, 2.5, 10µm) independent from the original MCU you need to send a serial command in the first 5 seconds after power is applied to the sensor. Otherwise the sensor will switch to PWM mode and does not repond to UART requests. A possibility to do this in ESPhome is to use an automation. `Source <https://community.home-assistant.io/t/ikea-vindriktning-air-quality-sensor/324599/300>`_
+
+Example config:
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    on_boot:
+      priority: 240
+      then:
+        - uart.write:
+            id: ikea #id of the uart bus used for the PM1006
+            data: [0x11, 0x02, 0x0B, 0x01, 0xE1]
+
+
 See Also
 --------
 

components/sensor/pulse_counter.rst

@@ -24,7 +24,7 @@ on the ESP32. However, due to the use of the pulse counter peripheral, a maximum
         pin: 12
         name: "Pulse Counter"
 
-Configuration variables:
+Configuration variables
 ------------------------
 
 - **pin** (**Required**, :ref:`config-pin`): The pin to count pulses on.
@@ -39,7 +39,6 @@ Configuration variables:
     detected. One of ``DISABLE``, ``INCREMENT`` and ``DECREMENT``.
     Defaults to ``DISABLE``.
 
-
 - **use_pcnt** (*Optional*, boolean): Use hardware ``PCNT`` pulse counter. Only supported on ESP32. Defaults to ``true``.
 
 - **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this
@@ -79,7 +78,6 @@ count the light pulses on a power meter, you can do the following:
         filters:
           - multiply: 0.06  # (60s/1000 pulses per kWh)
 
-
 Counting total pulses
 ---------------------
 

components/sensor/pulse_meter.rst

@@ -6,8 +6,14 @@ Pulse Meter Sensor
     :image: pulse.svg
 
 The pulse meter sensor allows you to count the number and frequency of pulses on any pin. It is intended to be a drop-in replacement
-for :doc:`integration sensor </components/sensor/pulse_counter>`, but offering better resolution.
+for the :doc:`pulse counter integration </components/sensor/pulse_counter>`.
-It measures the time between rising edges on a pin, for each pulse it outputs the frequency in pulses/min.
+Rather than counting pulses over a fixed time interval, the pulse meter sensor measures the time between pulses. The precise manner in which this is done depends on the ``internal_filter_mode`` option. This leads to a higher resolution, especially for low pulse rates, as the pulse counter sensor is limited by the number of pulses within a time interval.
+
+Here's a comparison of the two sensors; both are set to an update interval of 10 seconds (using the ``update_interval`` and the ``throttle_average`` option respectively):
+
+.. figure:: /images/pulse-counter_vs_pulse-meter.png
+    :align: center
+    :width: 50.0%
 
 .. code-block:: yaml
 
@@ -17,66 +23,61 @@ It measures the time between rising edges on a pin, for each pulse it outputs th
         pin: 12
         name: "Pulse Meter"
 
-Configuration variables:
+Configuration variables
 ------------------------
 
 - **pin** (**Required**, :ref:`config-pin`): The pin to count pulses on.
 - **name** (**Required**, string): The name of the sensor.
 
-- **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this
+- **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this   time is detected, it is discarded. Defaults to ``13us``.
-  time is detected, it’s discarded and no pulse is counted. Defaults to ``13us``. For S0 pulse meters that are used to meter power consumption 50-100 ms is a reasonable value.
+  
+  This acts as a debounce filter to eliminate input noise, so choose a value a little less than your expected minimum pulse width.
 
 - **internal_filter_mode** (*Optional*, string): Determines how the internal filter is applied.
-  One of ``EDGE`` and ``PULSE``. Defaults to ``EDGE``. In ``EDGE`` mode subsequent rising edges are compared and if they fall into an interval lesser than the internal filter value, the last one is discarded. In ``PULSE`` mode the rising edge is discarded if any further interrupts are detected before the internal_filter time has passed. In other words, a high pulse must be at least internal_filter long to be counted. This is useful if you are detecting long pulses that may bounces before and/or after the main pulse.  
+  One of ``EDGE`` or ``PULSE``. Defaults to ``EDGE``.
+  - In ``EDGE``  mode, subsequent rising edges are compared and if they fall into an interval lesser than the ``internal filter`` value, the last one is discarded. This is useful if your input signal bounces, but is otherwise clean.
+  - In ``PULSE`` mode, the rising edge is discarded if any further interrupts are detected before the ``internal_filter`` time has passed. In other words, a high pulse must be at least ``internal_filter`` long to be counted. This is useful if you have a noisy input signal that may have bounces before and/or after the main pulse.
 
-- **timeout** (*Optional*, :ref:`config-time`): If we don't see a pulse for this length of time, we assume 0 pulses/sec. Defaults to ``5 min``.
+- **timeout** (*Optional*, :ref:`config-time`): If we don't see a pulse for this length of time, we assume *0 pulses/s*. Defaults to ``5 min``.
 - **total** (*Optional*, :ref:`config-id`): An additional sensor that outputs the total number of pulses counted.
 - All other options from :ref:`Sensor <config-sensor>`.
 
 Converting units
 ----------------
 
-The sensor defaults to units of “pulses/min”. You can change this by using :ref:`sensor-filters`.
+The sensor defaults to units of *pulses/min*, You can change this by using :ref:`sensor-filters`.
-For example, if you’re using the pulse meter with a photodiode to
+For example, if you’re using the pulse meter with a photodiode to count the light pulses on a power meter that has an impulse constant of *10000 pulses / kWh*, you can use the following to output instantaneous usage in *W*:
-count the light pulses on a power meter that outputs 1000 pulses per kWh,
-you can use the following to output instantaneous usage in kW:
 
 .. code-block:: yaml
 
     # Example configuration entry
     sensor:
       - platform: pulse_meter
-        pin: 12
-        unit_of_measurement: 'kW'
         name: 'Electricity Usage'
+        id: sensor_pulse_meter # Optional ID, necessary if you want to calculate the total number of pulses.
+        unit_of_measurement: 'W'
+        device_class: power
+        state_class: measurement
+        internal_filter: 20ms # Assuming maximum load of 16 kW and 10000 impulses per kWh, any pulses faster than 22.5 ms would exceed load. -10% ~= 20 ms.
+        accuracy_decimals: 0
+        pin: 12
         filters:
-          - multiply: 0.06
+          - multiply: 6 # (60s / impulse constant) * (1000W / 1kW)
 
 Counting total pulses
 ---------------------
 
-When the total sensor is configured, pulse_meter also reports the total
+When the total sensor is configured, ``pulse_meter`` also reports the total
-number of pulses measured. When used on a power meter, this can be used to
+number of pulses measured.
-measure the total consumed energy in kWh.
 
 .. code-block:: yaml
 
     # Example configuration entry
     sensor:
       - platform: pulse_meter
-        pin: 12
+      # ...
-        unit_of_measurement: 'kW'
-        name: 'Electricity Usage'
-        internal_filter: 100ms
-        accuracy_decimals: 3
-        filters:
-          - multiply: 0.06
         total:
-          name: "Electricity Total"
+          name: "Total Pulses"
-          unit_of_measurement: "kWh"
-          accuracy_decimals: 3
-          filters:
-            - multiply: 0.001
 
 (Re)Setting the total pulse count
 ---------------------------------
@@ -87,22 +88,27 @@ trying to match.
 
 .. code-block:: yaml
 
-    on_...:
+    api:
-      then:
+      services:
-        - pulse_meter.set_total_pulses:
+        - service: set_total
-            id: pulse_meter_id
+          variables:
-            value: 12345
+            new_total: int
+          then:
+            - pulse_counter.set_total_pulses:
+                id: sensor_pulse_meter
+                value: !lambda 'return new_total;'
 
 .. note::
 
     This value is the raw count of pulses, and not the value you see after the filters
-    are applied.
-
 
 See Also
 --------
 
 - :ref:`sensor-filters`
 - :doc:`/components/sensor/pulse_counter`
+- :doc:`/components/sensor/total_daily_energy`
+- :doc:`/cookbook/power_meter`
+- `Home Assistant Glow 🌟 <https://github.com/klaasnicolaas/home-assistant-glow/>`__.
 - :apiref:`pulse_meter/pulse_meter_sensor.h`
 - :ghedit:`Edit`

components/sensor/total_daily_energy.rst

@@ -17,8 +17,15 @@ daily energy usage in ``Wh`` or ``kWh``.
     # Example configuration entry
     sensor:
       - platform: total_daily_energy
-        name: "Total Daily Energy"
+        name: 'Total Daily Energy'
         power_id: my_power
+        unit_of_measurement: 'kWh'
+        state_class: total_increasing
+        device_class: energy
+        accuracy_decimals: 3
+        filters:
+          # Multiplication factor from W to kW is 0.001
+          - multiply: 0.001
 
       # The power sensor to convert, can be any power sensor
       - platform: hlw8012
@@ -28,8 +35,8 @@ daily energy usage in ``Wh`` or ``kWh``.
 
     # Enable time component to reset energy at midnight
     time:
-      - platform: sntp
+      - platform: homeassistant
-        id: my_time
+        id: homeassistant_time
 
 Configuration variables:
 ------------------------
@@ -70,6 +77,9 @@ See Also
 - :ref:`sensor-filters`
 - :doc:`hlw8012`
 - :doc:`cse7766`
+- :doc:`/components/sensor/pulse_counter`
+- :doc:`/components/sensor/pulse_meter`
+- :doc:`/components/time/homeassistant`
 - :doc:`/cookbook/power_meter`
 - :apiref:`total_daily_energy/total_daily_energy.h`
 - :ghedit:`Edit`

components/speaker/i2s_audio.rst

@@ -5,8 +5,17 @@ I²S Audio Speaker
     :description: Instructions for setting up I²S based speakers in ESPHome.
     :image: i2s_audio.svg
 
-The ``i2s_audio`` speaker platform allows you to receive audio via the the
+The ``i2s_audio`` speaker platform allows you to receive audio via the the :doc:`/components/i2s_audio`.
-:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
+
+This platform only works on ESP32 based chips.
+
+.. warning::
+
+    Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
+    combination with Voice Assistant and/or other audio components.
 
 .. code-block:: yaml
 

components/switch/ble_client.rst

@@ -5,13 +5,18 @@ BLE Client Switch
     :description: Control the state of BLE clients.
     :image: bluetooth.svg
 
-The ``ble_client`` component is a switch platform that is used to enable
+The ``ble_client`` component is a switch platform that is used to enable and disable a ``ble_client``. This has
-and disable a ``ble_client``. This has several uses, such as minimizing
+several uses, such as minimizing battery usage or for allowing other clients (Eg phone apps) to connect to the device.
-battery usage or for allowing other clients (Eg phone apps) to connect to
-the device.
 
-For more information on BLE services and characteristics, see
+For more information on BLE services and characteristics, see :doc:`/components/ble_client`.
-:doc:`/components/ble_client`.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/text_sensor/ble_scanner.rst

@@ -7,11 +7,22 @@ ESP32 Bluetooth Low Energy Scanner
     :keywords: ESP32
 
 The ``ble_scanner`` text sensor platform lets you track reachable BLE devices.
-See the :ref:`BLE Tracker Configuration variables <config-esp32_ble_tracker>` for
-instructions for setting up scan parameters.
-The sensor platform is similar to :doc:`/components/sensor/ble_rssi` but in contrast to that platform, this text sensor sends out all raw BLE scan information and does not filter devices.
 
-The data this sensor publishes is intended to be processed by the remote (for example an MQTT client) and sends the data in JSON format.
+See the :ref:`BLE Tracker Configuration variables <config-esp32_ble_tracker>` for instructions for setting up scan parameters.
+
+The sensor platform is similar to :doc:`/components/sensor/ble_rssi` but in contrast to that platform, this text
+sensor sends out all raw BLE scan information and does not filter devices.
+
+The data this sensor publishes is intended to be processed by the remote (for example an MQTT client) and sends
+the data in JSON format.
+
+.. warning::
+
+    The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
+    audio components are most likely to cause issues.
 
 .. code-block:: yaml
 

components/voice_assistant.rst

@@ -11,6 +11,14 @@ ESPHome devices with a microphone are able to stream the audio to Home Assistant
 
     Voice Assistant requires Home Assistant 2023.5 or later.
 
+.. warning::
+
+    Audio and voice components consume a significant amount of resources (RAM, CPU) on the device.
+    
+    **Crashes are likely to occur** if you include too many additional components in your device's
+    configuration. In particular, Bluetooth/BLE components are known to cause issues when used in
+    combination with Voice Assistant and/or other audio components.
+
 Configuration:
 --------------
 

cookbook/power_meter.rst

@@ -5,20 +5,11 @@ Non-Invasive Power Meter
     :description: Instructions for hacking your power meter at home to measure your power usage.
     :image: power_meter.jpg
 
-So an essential part of making your home smart is knowing how much power it uses over
+So an essential part of making your home smart is knowing how much power it uses over the day. Tracking this can be difficult, often you need to install a completely new power meter which can often cost a bunch of money. However, quite a few power meters have a red LED on the front that blinks every time that one Wh has been used.
-the day. Tracking this can be difficult, often you need to install a completely new
-power meter which can often cost a bunch of money. However, quite a few power meters
-have a red LED on the front that blinks every time that one Wh has been used.
 
-The simple idea therefore is: Why don't we just abuse that functionality to make the power-meter
+The simple idea therefore is: Why don't we just abuse that functionality to make the power-meter IoT enabled? We just have to hook up a simple photoresistor in front of that aforementioned LED and track the number of pulses we receive. Then using ESPHome we can instantly have the power meter show up in Home Assistant 🎉
-IoT enabled? We just have to hook up a simple photoresistor in front of that aforementioned
-LED and track the amount of pulses we receive. Then using ESPHome we can instantly have
-the power meter show up in Home Assistant 🎉
 
-Hooking it all up is quite easy: Just buy a suitable photoresistor (make sure the wave length
+Hooking it all up is quite easy: Just buy a suitable photoresistor (make sure the wave length approximately matches the one from your power meter). Then connect it using a simple variable resistor divider (see `this article <https://blog.udemy.com/arduino-ldr/>`__ for inspiration). And... that should already be it :)
-approximately matches the one from your power meter). Then connect it using a simple variable
-resistor divider (see `this article <https://blog.udemy.com/arduino-ldr/>`__ for inspiration).
-And... that should already be it :)
 
 .. figure:: images/power_meter-header.jpg
     :align: center
@@ -26,8 +17,7 @@ And... that should already be it :)
 
 .. note::
 
-    Some energy meters have an exposed S0 port (which essentially just is a switch that closes), if
+    Some energy meters have an exposed `S0 port <https://en.wikipedia.org/wiki/S_interface/>`__ (which essentially just is a switch that closes), if that is the case the photodiode can be replaced with the following connection.
-    that is the case the photodiode can be replaced with the following connection.
 
     .. code-block::
 
@@ -36,45 +26,130 @@ And... that should already be it :)
         .    |
         .    +--------- GPIO12
 
-For ESPHome, you can then use the
+For ESPHome, you can then use the :doc:`pulse meter sensor </components/sensor/pulse_meter>` using below configuration:
-:doc:`pulse counter sensor </components/sensor/pulse_counter>` using below configuration:
 
 .. code-block:: yaml
 
     sensor:
-      - platform: pulse_counter
+      - platform: pulse_meter
+        name: 'Power'
+        id: sensor_pulse_meter # Optional ID, necessary if you want to calculate the total daily energy
+        unit_of_measurement: 'W'
+        device_class: power
+        state_class: measurement
+        accuracy_decimals: 0
         pin: GPIO12
-        unit_of_measurement: 'kW'
-        name: 'Power Meter'
         filters:
-          - multiply: 0.06  # (60s/1000 pulses per kWh)
+          - multiply: 6 # (60s / impulse constant) * (1000W / 1kW)
 
-Adjust ``GPIO12`` to match your set up of course. The output from the pulse counter sensor is in
+Adjust ``GPIO12`` to match your set up of course. The output from the pulse counter sensor is in pulses/min and we also know that 10000 pulses from the LED should equal 1kWh of power usage. Thus, rearranging the expression yields a proportional factor of 6 from pulses/min to *W*.
-``pulses/min`` and we also know that 1000 pulses from the LED should equal 1kWh of power usage.
-Thus, rearranging the expression yields a proportional factor of ``0.06`` from ``pulses/min`` to
-``kW``.
-
-And if a technician shows up and he looks confused about what the heck you have done to your
-power meter, tell them about ESPHome 😉
 
 .. note::
 
-    Photoresistors often have a bit of noise during their switching phases. So in certain situations,
+    The ``pulse_meter`` sensor sends an update every time a pulse is detected. This can quickly lead to sub-second updates which can be a bit much for Home Assistant to handle. To avoid this, you can use the ``average_throttle`` filter to only send updates up to a desired interval:
-    a single power meter tick can result in many pulses being counted. This effect is especially big on
-    ESP8266s. If you're experiencing this, try enabling the ``internal_filter:`` filter option:
 
     .. code-block:: yaml
 
         sensor:
-          - platform: pulse_counter
+          - platform: pulse_meter
             # ...
-            internal_filter: 10us
+            filters:
+              - average_throttle: 10s
+              - filter_out: NaN
 
-See :doc:`/components/sensor/total_daily_energy` for counting up the total daily energy usage
+.. note::
-with these ``pulse_counter`` power meters.
+
+    The ``pulse_meter`` sensor has an internal filter that is used to debounce the input signal. This filter is set to ``13us`` by default. To increase the safety margin, you can increase this value. For this you need to know the *minimum pulse width* that you can expect to see from your power meter within the expected load range.
+
+    The minimum pulse width threshold is determined by considering the upper limit of the *load* the meter is designed to handle, as well as the meter's *impulse constant* (x pulses / kWh). Here's the calculation involved:
+
+    - **Load Limit in Watts**: Establish the *upper load limit* that the meter is designed to measure. For example, if the limit is 16 kW (16,000 Watts), this becomes a reference point.
+
+    - **Pulse Rate Calculation**: Determine the pulse rate corresponding to this load limit. For this we need to know the impulse constant. In our example, the power meter has an impulse constant of 10000 pulses/kWh, resulting in 160000 pulses per hour at the maximum 16 kW load, i.e. 44.4 pulses/second.
+
+    - **Minimum Pulse Width Calculation**: Use the pulse rate to calculate the minimum pulse width threshold. In our example, with a maximum pulse rate of 44.4/sec, the minimum pulse width we expect to see is approximately 22.5 milliseconds. Choose a slightly smaller value than this to avoid missing pulses.
+
+    .. code-block:: yaml
+
+        sensor:
+          - platform: pulse_meter
+            # ...
+            internal_filter: 20ms
+
+If a technician shows up and he looks confused about what the heck you have done to your power meter, tell them about ESPHome 😉
+
+Counting total generated energy
+-------------------------------
+
+When the total sensor is configured, ``pulse_meter`` also reports the total number of pulses measured. When used on a power meter, this can be used to measure the total transmitted energy in kWh.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: pulse_meter
+      # ...
+        total:
+          name: "Electricity Total"
+          unit_of_measurement: "kWh"
+          device_class: energy
+          state_class: total_increasing
+          accuracy_decimals: 3
+          filters:
+            - multiply: 0.0001  # (1/10000 pulses per kWh)
+            # - average_throttle: 10s
+            # - filter_out: NaN
+
+(Re)Setting the total energy value
+----------------------------------
+
+Using this action, you are able to reset/set the total pulse count. This can be useful if you would like the ``total`` sensor to match what you see on your meter you are trying to match.
+
+.. code-block:: yaml
+
+    api:
+      services:
+        - service: set_total
+          variables:
+            new_total: int
+          then:
+            - pulse_counter.set_total_pulses:
+                id: sensor_pulse_meter
+                value: !lambda 'return new_total * 1000;'
+
+Tracking Total Daily Energy
+---------------------------
+
+Additionally you can also calculate the total daily energy generated, for which you can use the :doc:`Total Daily Energy </components/sensor/total_daily_energy>` using below configuration:
+
+.. code-block:: yaml
+
+    sensor:
+     #(...)
+      - platform: total_daily_energy
+        name: 'Total Daily Energy'
+        id: sensor_total_daily_energy
+        power_id: sensor_energy_pulse_meter
+        unit_of_measurement: 'kWh'
+        state_class: total_increasing
+        device_class: energy
+        accuracy_decimals: 3
+        filters:
+          # Multiplication factor from W to kW is 0.001
+          - multiply: 0.001
+    
+    time:
+      - platform: homeassistant
+        id: homeassistant_time
+
+While you can in theory also do this with the home assistant `integration <https://www.home-assistant.io/integrations/integration/>`__ integration, the benefit of this is that it continues to integrate the power during times home assistant is unable to work with values, i.e. during updates, restarts and so on.
 
 See Also
 --------
 
 - :doc:`/components/sensor/pulse_counter`
+- :doc:`/components/sensor/pulse_meter`
+- :doc:`/components/sensor/total_daily_energy`
+- :doc:`/components/time/homeassistant`
+- `Home Assistant Glow 🌟 <https://github.com/klaasnicolaas/home-assistant-glow/>`__.
 - :ghedit:`Edit`

guides/automations.rst

@@ -568,8 +568,8 @@ Configuration variables:
 ``while`` Action
 ----------------
 
-This action is similar to the :ref:`if <if_action>` Action. The ``while`` action executes
+This action is similar to the :ref:`if <if_action>` Action. The ``while`` action loops
-a block until a given condition evaluates to false.
+through a block as long as the given condition is true.
 
 .. code-block:: yaml
 

guides/supporters.rst

@@ -723,7 +723,6 @@ Contributors
 - `Mark Kuchel (@kuchel77) <https://github.com/kuchel77>`__
 - `Kyle Hill (@kylhill) <https://github.com/kylhill>`__
 - `Limor "Ladyada" Fried (@ladyada) <https://github.com/ladyada>`__
-- `Luca Adrian L (@lal12) <https://github.com/lal12>`__
 - `Landon Rohatensky (@landonr) <https://github.com/landonr>`__
 - `Fredrik Lindqvist (@Landrash) <https://github.com/Landrash>`__
 - `lanik (@lanik) <https://github.com/lanik>`__
@@ -1236,6 +1235,7 @@ Contributors
 - `Yaroslav (@Yarikx) <https://github.com/Yarikx>`__
 - `Marcin Jaworski (@yawor) <https://github.com/yawor>`__
 - `yousaf465 (@yousaf465) <https://github.com/yousaf465>`__
+- `Jevgeni Kiski (@yozik04) <https://github.com/yozik04>`__
 - `Yuval Aboulafia (@yuvalabou) <https://github.com/yuvalabou>`__
 - `Björn Stenberg (@zagor) <https://github.com/zagor>`__
 - `david reid (@zathras777) <https://github.com/zathras777>`__