Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into next

This commit is contained in:
Jesse Hills 2023-10-30 13:59:32 +13:00
parent 7f89184726 a62d7ab193
commit aa35f6a2ea
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
34 changed files with 771 additions and 323 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
changelog/2023.10.0.rst
View File

@ -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
----------------

11
components/binary_sensor/ble_presence.rst
View File

@ -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

38
components/ble_client.rst
View File

@ -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

5
components/canbus.rst
View File

@ -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.

8
components/display/index.rst
View File

@ -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:

8
components/esp32_ble.rst
View File

@ -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

7
components/esp32_ble_beacon.rst
View File

@ -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

8
components/esp32_ble_server.rst
View File

@ -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

16
components/esp32_ble_tracker.rst
View File

@ -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

33
components/esp32_camera.rst
View File

@ -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
--------

9
components/esp32_improv.rst
View File

@ -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
components/libretiny.rst
View File

@ -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

4
components/mcp23Sxx.rst
View File

@ -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 :**

13
components/microphone/i2s_audio.rst
View File

@ -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

11
components/modbus.rst
View File

@ -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`

326
components/modbus_controller.rst
View File

@ -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**
@ -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<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
uint16_t((year << 8) | month)};
// Create a modbus command item with the time information as the payload
esphome::modbus_controller::ModbusCommandItem set_rtc_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
// Submit the command to the send queue
epever->queue_command(set_rtc_command);
ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
year + 2000);
}
// Battery settings
// Note: these values are examples only and apply my AGM Battery
std::vector<uint16_t> battery_settings1 = {
0, // 9000 Battery Type 0 = User
0x0073, // 9001 Battery Cap 0x55 == 115AH
0x012C, // 9002 Temp compensation -3V /°C/2V
0x05DC, // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
0x058C, // 9004 0x58C == 1480 Charging Limit Voltage 14,8
0x058C, // 9005 Over Voltage Reconnect Voltage 14,8
0x05BF, // 9006 Equalize Charging Voltage 14,6
0x05BE, // 9007 Boost Charging Voltage 14,7
0x0550, // 9008 Float Charging Voltage 13,6
0x0528, // 9009 Boost Reconnect Charging Voltage 13,2
0x04C4, // 900A Low Voltage Reconnect Voltage 12,2
0x04B0, // 900B Under Voltage Warning Reconnect Voltage 12,0
0x04BA, // 900c Under Volt. Warning Volt 12,1
0x04BA, // 900d Low Volt. Disconnect Volt. 11.8
0x04BA // 900E Discharging Limit Voltage 11.8
};
// Boost and equalization periods
std::vector<uint16_t> battery_settings2 = {
0x0000, // 906B Equalize Duration (min.) 0
0x0075 // 906C Boost Duration (aka absorb) 117 mins
};
esphome::modbus_controller::ModbusCommandItem set_battery1_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
battery_settings1);
esphome::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<uint16_t> rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
uint16_t((year << 8) | month)};
// Create a ModBUS command item with the time information as the payload
esphome::modbus_controller::ModbusCommandItem set_rtc_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data);
// Submit the command to the send queue
epever->queue_command(set_rtc_command);
ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month,
year + 2000);
}
// Battery settings
// Note: these values are examples only and apply my AGM Battery
std::vector<uint16_t> battery_settings1 = {
0, // 9000 Battery Type 0 = User
0x0073, // 9001 Battery Cap 0x55 == 115AH
0x012C, // 9002 Temp compensation -3V /°C/2V
0x05DC, // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0
0x058C, // 9004 0x58C == 1480 Charging Limit Voltage 14,8
0x058C, // 9005 Over Voltage Reconnect Voltage 14,8
0x05BF, // 9006 Equalize Charging Voltage 14,6
0x05BE, // 9007 Boost Charging Voltage 14,7
0x0550, // 9008 Float Charging Voltage 13,6
0x0528, // 9009 Boost Reconnect Charging Voltage 13,2
0x04C4, // 900A Low Voltage Reconnect Voltage 12,2
0x04B0, // 900B Under Voltage Warning Reconnect Voltage 12,0
0x04BA, // 900c Under Volt. Warning Volt 12,1
0x04BA, // 900d Low Volt. Disconnect Volt. 11.8
0x04BA // 900E Discharging Limit Voltage 11.8
};
// Boost and equalization periods
std::vector<uint16_t> battery_settings2 = {
0x0000, // 906B Equalize Duration (min.) 0
0x0075 // 906C Boost Duration (aka absorb) 117 mins
};
esphome::modbus_controller::ModbusCommandItem set_battery1_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
battery_settings1);
esphome::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 <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`

15
components/output/ble_client.rst
View File

@ -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

15
components/sensor/ble_client.rst
View File

@ -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

8
components/sensor/ble_rssi.rst
View File

@ -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

62
components/sensor/bme680.rst
View File

@ -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
--------

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.3 KiB

After

Width:  |  Height:  |  Size: 6.2 KiB

142
components/sensor/hlw8012.rst
View File

@ -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
--------

16
components/sensor/ld2410.rst
View File

@ -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

16
components/sensor/pm1006.rst
View File

@ -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
--------

12
components/sensor/pulse_counter.rst
View File

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/pcnt.html>`__
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

78
components/sensor/pulse_meter.rst
View File

@ -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_...:
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 🌟 <https://github.com/klaasnicolaas/home-assistant-glow/>`__.
- :apiref:`pulse_meter/pulse_meter_sensor.h`
- :ghedit:`Edit`

16
components/sensor/total_daily_energy.rst
View File

@ -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`

13
components/speaker/i2s_audio.rst
View File

@ -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

17
components/switch/ble_client.rst
View File

@ -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

19
components/text_sensor/ble_scanner.rst
View File

@ -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

8
components/voice_assistant.rst
View File

@ -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:
--------------

143
cookbook/power_meter.rst
View File

@ -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`

4
guides/automations.rst
View File

@ -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

2
guides/supporters.rst
View File

@ -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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB