mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-26 17:27:47 +01:00
Merge branch 'current' into next
This commit is contained in:
Jesse Hills
commit
aa35f6a2ea
@ -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
|
||||
----------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
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 <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.
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 <esp32_ble_tracker-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 <esp32_ble_tracker-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
|
||||
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 :**
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
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) <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`
|
||||
|
||||
@ -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
|
||||
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**
|
||||
|
||||
@ -379,12 +377,10 @@ 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.
|
||||
However the C++ code provides the required API to write to a ModBUS device.
|
||||
|
||||
These methods can be called from a lambda.
|
||||
|
||||
@ -393,7 +389,6 @@ 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:
|
||||
@ -418,7 +413,7 @@ Then battery charge settings are sent.
|
||||
// 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
|
||||
// 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
|
||||
@ -523,17 +518,16 @@ Then battery charge settings are sent.
|
||||
- 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`
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 4.3 KiB After Width: | Height: | Size: 6.2 KiB |
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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.
|
||||
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 </components/sensor/pulse_counter>`.
|
||||
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 <config-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_...:
|
||||
api:
|
||||
services:
|
||||
- service: set_total
|
||||
variables:
|
||||
new_total: int
|
||||
then:
|
||||
- pulse_meter.set_total_pulses:
|
||||
id: pulse_meter_id
|
||||
value: 12345
|
||||
- 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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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:
|
||||
--------------
|
||||
|
||||
|
||||
@ -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 <https://blog.udemy.com/arduino-ldr/>`__ 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 <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
|
||||
that is the case the photodiode can be replaced with the following connection.
|
||||
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.
|
||||
|
||||
.. code-block::
|
||||
|
||||
@ -36,45 +26,130 @@ And... that should already be it :)
|
||||
. |
|
||||
. +--------- GPIO12
|
||||
|
||||
For ESPHome, you can then use the
|
||||
:doc:`pulse counter sensor </components/sensor/pulse_counter>` using below configuration:
|
||||
For ESPHome, you can then use the :doc:`pulse meter sensor </components/sensor/pulse_meter>` 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 </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`
|
||||
|
||||
@ -568,8 +568,8 @@ Configuration variables:
|
||||
``while`` Action
|
||||
----------------
|
||||
|
||||
This action is similar to the :ref:`if <if_action>` Action. The ``while`` action executes
|
||||
a block until a given condition evaluates to false.
|
||||
This action is similar to the :ref:`if <if_action>` Action. The ``while`` action loops
|
||||
through a block as long as the given condition is true.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
||||
@ -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>`__
|
||||
|
||||
BIN
images/pulse-counter_vs_pulse-meter.png
Normal file
BIN
images/pulse-counter_vs_pulse-meter.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.3 KiB |
Loading…
Reference in New Issue
Block a user