diff --git a/changelog/2023.10.0.rst b/changelog/2023.10.0.rst index 21fdb1320..d6ce8c2c6 100644 --- a/changelog/2023.10.0.rst +++ b/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 ---------------- diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst index 9d75e472a..8f744dbb5 100644 --- a/components/binary_sensor/ble_presence.rst +++ b/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 -Bluetooth Low Energy device. +The ``ble_presence`` binary sensor platform lets you track the presence of a 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 diff --git a/components/ble_client.rst b/components/ble_client.rst index 7424ecf70..a14cdf5a8 100644 --- a/components/ble_client.rst +++ b/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 -Low Energy devices in order to query and control them. This -component does not expose any sensors or output components itself, -but merely manages connections to them for use by other components. +The ``ble_client`` component enables connections to Bluetooth Low Energy devices in order to query and +control them. This component does not expose any sensors or output components itself, 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 - amount of RAM on the device. As such, you may experience - 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 ESP32 BLE stack. If you wish to + connect more devices, use additional ESP32 boards. - A maximum of three devices is supported due to limitations in the - 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 for authentication. - This component supports devices that require a 6 digit PIN code - for authentication. - - 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 + 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 -the ``esp32_ble_tracker`` component in order to discover available -client devices. +Despite the last point above, the ``ble_client`` component requires the ``esp32_ble_tracker`` component in order +to discover available client devices. .. code-block:: yaml diff --git a/components/canbus.rst b/components/canbus.rst index 5ef35a3f7..9302c52e0 100644 --- a/components/canbus.rst +++ b/components/canbus.rst @@ -171,12 +171,11 @@ There are several forms to use it: - canbus.send: 'hello' # Templated, return type is std::vector - - canbus.send: !lambda - return {0x00, 0x20, 0x42}; + - canbus.send: !lambda return {0x00, 0x20, 0x42}; Configuration variables: -- **data** (**Required**, binary data): Data to transmit, up to 8 bytes or +- **data** (**Required**, binary data, :ref:`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. diff --git a/components/display/index.rst b/components/display/index.rst index f6a8535af..5e8bfd2b6 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -184,6 +184,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: diff --git a/components/esp32_ble.rst b/components/esp32_ble.rst index 325ce59f0..146d7e868 100644 --- a/components/esp32_ble.rst +++ b/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 diff --git a/components/esp32_ble_beacon.rst b/components/esp32_ble_beacon.rst index 79e350c7a..cd312cf88 100644 --- a/components/esp32_ble_beacon.rst +++ b/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 diff --git a/components/esp32_ble_server.rst b/components/esp32_ble_server.rst index 357b43aef..c4f1ca609 100644 --- a/components/esp32_ble_server.rst +++ b/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 diff --git a/components/esp32_ble_tracker.rst b/components/esp32_ble_tracker.rst index f1b59149d..fa32e37bd 100644 --- a/components/esp32_ble_tracker.rst +++ b/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 -energy devices using your ESP32 node. +The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low energy devices +using your ESP32 node. -See :ref:`Setting up devices ` -for information on how you can find out the MAC address of a device and track it using ESPHome. +See :ref:`Setting up devices ` for information on how you can determine +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 diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 8361f0daf..9bb2a20a7 100644 --- a/components/esp32_camera.rst +++ b/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 `_ +--------------------------------------------------------------------------------------------------------------------------- + +.. 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 -------- diff --git a/components/esp32_improv.rst b/components/esp32_improv.rst index ed53f0959..f12aa3d55 100644 --- a/components/esp32_improv.rst +++ b/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 `__ -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 `. +.. 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 diff --git a/components/libretiny.rst b/components/libretiny.rst index 4b531c54c..2d91c8325 100644 --- a/components/libretiny.rst +++ b/components/libretiny.rst @@ -6,7 +6,7 @@ LibreTiny Platform :image: libretiny.svg This component contains platform-specific options for the `LibreTiny `__ 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 ` -- **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 `__. Getting Started diff --git a/components/mcp23Sxx.rst b/components/mcp23Sxx.rst index ec579a573..c058eaf65 100644 --- a/components/mcp23Sxx.rst +++ b/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 :** diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst index 2afb3f9c0..d7dc646ad 100644 --- a/components/microphone/i2s_audio.rst +++ b/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 -:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. +The ``i2s_audio`` microphone platform allows you to receive audio via the the :doc:`/components/i2s_audio`. + +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 diff --git a/components/modbus.rst b/components/modbus.rst index 903a0b5b8..de0e6d300 100644 --- a/components/modbus.rst +++ b/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 ` to communicate. +ModBUS requires a :ref:`UART Bus ` 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. - If multiple modbus devices are attached 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. +- **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 to the same bus increasing this value can help avoiding to to overlapping reads. + 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) `__ - `Modbus RTU Protocol Description `__ - :ref:`uart` - :apiref:`modbus/modbus.h` diff --git a/components/modbus_controller.rst b/components/modbus_controller.rst index 8ac555411..e098ebb63 100644 --- a/components/modbus_controller.rst +++ b/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? `__ on stackexchange for more details +See `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 - Specify the modbus device address of the. +- **address** (**Required**, :ref:`config-id`): The ModBUS address of the slave device -- **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. +- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is ``0ms``. + 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: 0x1 ## address of the ModBUS slave device on the bus 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. -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. - - -.. code-block:: yaml - - 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 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 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 - std::vector 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::modbus_controller::ModbusCommandItem set_battery2_command = - esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(), - battery_settings2); - delay(200) ; - controller->queue_command(set_battery1_command); - delay(200) ; - controller->queue_command(set_battery2_command); - ESP_LOGI("ModbusLambda", "EPSOLAR Battery set"); - - uart: - id: mod_bus - tx_pin: 19 - rx_pin: 18 - baud_rate: 115200 - stop_bits: 1 - - modbus: - #flow_control_pin: 23 - send_wait_time: 200ms - id: mod_bus_epever - - modbus_controller: - - id: epever - ## the Modbus device addr - address: 0x1 - modbus_id: mod_bus_epever - command_throttle: 0ms - setup_priority: -10 - 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 + 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. + + .. code-block:: yaml + 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 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 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 + std::vector 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::modbus_controller::ModbusCommandItem set_battery2_command = + esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(), + battery_settings2); + delay(200) ; + controller->queue_command(set_battery1_command); + delay(200) ; + controller->queue_command(set_battery2_command); + ESP_LOGI("ModbusLambda", "EPSOLAR Battery set"); + + uart: + id: mod_bus + tx_pin: 19 + rx_pin: 18 + baud_rate: 115200 + stop_bits: 1 + + modbus: + #flow_control_pin: 23 + send_wait_time: 200ms + id: mod_bus_epever + + modbus_controller: + - id: epever + ## the Modbus device addr + address: 0x1 + modbus_id: mod_bus_epever + command_throttle: 0ms + setup_priority: -10 + 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 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 `__ - `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) `__ -- `Modbus RTU Protocol Description `__ +- `Genvex, Nibe, Alpha-Innotec heat recovery ventilation `__ - :ghedit:`Edit` diff --git a/components/output/ble_client.rst b/components/output/ble_client.rst index bda99d4e9..3aed40ed7 100644 --- a/components/output/ble_client.rst +++ b/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 -write a binary value to service characteristics of -BLE devices. +The ``ble_client`` component is a output that can write a binary value to service characteristics of BLE devices. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :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 diff --git a/components/sensor/ble_client.rst b/components/sensor/ble_client.rst index b579e305e..469c81099 100644 --- a/components/sensor/ble_client.rst +++ b/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 -query BLE devices for RSSI or specific values of service characteristics. +The ``ble_client`` component is a sensor platform that can query BLE devices for RSSI or specific +values of service characteristics. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :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 diff --git a/components/sensor/ble_rssi.rst b/components/sensor/ble_rssi.rst index 6fcee5840..724f96d61 100644 --- a/components/sensor/ble_rssi.rst +++ b/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 ` 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 diff --git a/components/sensor/bme680.rst b/components/sensor/bme680.rst index e5c008042..d4272e7de 100644 --- a/components/sensor/bme680.rst +++ b/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 `__ 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 -------- diff --git a/components/sensor/hlw8012.rst b/components/sensor/hlw8012.rst index cae261c94..42a462387 100644 --- a/components/sensor/hlw8012.rst +++ b/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 + + + + + +
voltage_divider:
current_resistor:
current_multiply:
+ +ESP measurements: + +.. raw:: html + + + + + +
Voltage: V
Power: W
Current: A
+ +Power meter measurements: + +.. raw:: html + + + + + +
Voltage: V
Power: W
Current: A
+ +New calibration values: + +.. raw:: html + + + + + +
voltage_divider:
current_resistor:
current_multiply:
+ +New ESP measurements: + +.. raw:: html + + + + + +
Voltage: V
Power: W
Current: A
+ + +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 -------- diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index 154d963b6..a6598befe 100644 --- a/components/sensor/ld2410.rst +++ b/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 diff --git a/components/sensor/pm1006.rst b/components/sensor/pm1006.rst index d594b4eb7..a240e71d3 100644 --- a/components/sensor/pm1006.rst +++ b/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 `_ + +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 -------- diff --git a/components/sensor/pulse_counter.rst b/components/sensor/pulse_counter.rst index a9ae0a16a..865cda92f 100644 --- a/components/sensor/pulse_counter.rst +++ b/components/sensor/pulse_counter.rst @@ -10,7 +10,7 @@ on any pin. On the ESP32, this sensor is even highly accurate because it's using the hardware `pulse counter peripheral `__ -on the ESP32. However, due to the use of the pulse counter peripheral, a maximum of 8 channels can be used! +on the ESP32. However, due to the use of the pulse counter peripheral, a maximum of 8 channels can be used! .. figure:: images/pulse-counter.png :align: center @@ -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. @@ -38,7 +38,6 @@ Configuration variables: - **falling_edge** (*Optional*): What to do when a falling edge is 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``. @@ -79,13 +78,12 @@ 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 --------------------- -When the total sensor is configured, the pulse_counter also reports the total -number of pulses measured. When used on a power meter, this can be used to -measure the total consumed energy in kWh. +When the total sensor is configured, the pulse_counter also reports the total +number of pulses measured. When used on a power meter, this can be used to +measure the total consumed energy in kWh. .. code-block:: yaml diff --git a/components/sensor/pulse_meter.rst b/components/sensor/pulse_meter.rst index d91fc5ad6..ecb3553e7 100644 --- a/components/sensor/pulse_meter.rst +++ b/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 `, but offering better resolution. -It measures the time between rising edges on a pin, for each pulse it outputs the frequency in pulses/min. +for the :doc:`pulse counter integration `. +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 - 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. +- **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this time is detected, it is discarded. Defaults to ``13us``. + + 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 `. Converting units ---------------- -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 -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: +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 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*: .. 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 -number of pulses measured. When used on a power meter, this can be used to -measure the total consumed energy in kWh. +When the total sensor is configured, ``pulse_meter`` also reports the total +number of pulses measured. .. 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" - unit_of_measurement: "kWh" - accuracy_decimals: 3 - filters: - - multiply: 0.001 + name: "Total Pulses" (Re)Setting the total pulse count --------------------------------- @@ -87,22 +88,27 @@ trying to match. .. code-block:: yaml - on_...: - then: - - pulse_meter.set_total_pulses: - id: pulse_meter_id - value: 12345 + api: + services: + - service: set_total + variables: + 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 🌟 `__. - :apiref:`pulse_meter/pulse_meter_sensor.h` - :ghedit:`Edit` diff --git a/components/sensor/total_daily_energy.rst b/components/sensor/total_daily_energy.rst index 66eb8b781..3fcd89581 100644 --- a/components/sensor/total_daily_energy.rst +++ b/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 - id: my_time + - platform: homeassistant + 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` diff --git a/components/speaker/i2s_audio.rst b/components/speaker/i2s_audio.rst index 3ece5e99a..c322f179b 100644 --- a/components/speaker/i2s_audio.rst +++ b/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 -:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. +The ``i2s_audio`` speaker platform allows you to receive audio via the the :doc:`/components/i2s_audio`. + +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 diff --git a/components/switch/ble_client.rst b/components/switch/ble_client.rst index cf3fd13d4..96b3599b9 100644 --- a/components/switch/ble_client.rst +++ b/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 -and disable a ``ble_client``. This has several uses, such as minimizing -battery usage or for allowing other clients (Eg phone apps) to connect to -the device. +The ``ble_client`` component is a switch platform that is used to enable and disable a ``ble_client``. This has +several uses, such as minimizing battery usage or for allowing other clients (Eg phone apps) to connect to the device. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :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 diff --git a/components/text_sensor/ble_scanner.rst b/components/text_sensor/ble_scanner.rst index 3d21c3df1..6b4c0873e 100644 --- a/components/text_sensor/ble_scanner.rst +++ b/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 ` 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 ` 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 diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst index 0eaffdf52..0a5fa2f54 100644 --- a/components/voice_assistant.rst +++ b/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: -------------- diff --git a/cookbook/power_meter.rst b/cookbook/power_meter.rst index 268e6d6e7..4ec3a985d 100644 --- a/cookbook/power_meter.rst +++ b/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 -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. +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 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 amount of pulses we receive. Then using ESPHome we can instantly have -the power meter show up in Home Assistant 🎉 +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 🎉 -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 `__ for inspiration). -And... that should already be it :) +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 `__ 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 - that is the case the photodiode can be replaced with the following connection. + Some energy meters have an exposed `S0 port `__ (which essentially just is a switch that closes), if 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 -:doc:`pulse counter sensor ` using below configuration: +For ESPHome, you can then use the :doc:`pulse meter sensor ` 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 -``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 😉 +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*. .. note:: - Photoresistors often have a bit of noise during their switching phases. So in certain situations, - 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: + 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: .. 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 -with these ``pulse_counter`` power meters. +.. note:: + + 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 ` 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 `__ 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 🌟 `__. - :ghedit:`Edit` diff --git a/guides/automations.rst b/guides/automations.rst index ddd45ac1a..8e585928e 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -568,8 +568,8 @@ Configuration variables: ``while`` Action ---------------- -This action is similar to the :ref:`if ` Action. The ``while`` action executes -a block until a given condition evaluates to false. +This action is similar to the :ref:`if ` Action. The ``while`` action loops +through a block as long as the given condition is true. .. code-block:: yaml diff --git a/guides/supporters.rst b/guides/supporters.rst index d5cacda28..12e360272 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -723,7 +723,6 @@ Contributors - `Mark Kuchel (@kuchel77) `__ - `Kyle Hill (@kylhill) `__ - `Limor "Ladyada" Fried (@ladyada) `__ -- `Luca Adrian L (@lal12) `__ - `Landon Rohatensky (@landonr) `__ - `Fredrik Lindqvist (@Landrash) `__ - `lanik (@lanik) `__ @@ -1236,6 +1235,7 @@ Contributors - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ - `yousaf465 (@yousaf465) `__ +- `Jevgeni Kiski (@yozik04) `__ - `Yuval Aboulafia (@yuvalabou) `__ - `Björn Stenberg (@zagor) `__ - `david reid (@zathras777) `__ diff --git a/images/pulse-counter_vs_pulse-meter.png b/images/pulse-counter_vs_pulse-meter.png new file mode 100644 index 000000000..87a713c3c Binary files /dev/null and b/images/pulse-counter_vs_pulse-meter.png differ