Merge branches 'current' and 'next' of github.com:esphome/esphome-docs into next

This commit is contained in:
Jesse Hills 2021-11-15 11:03:23 +13:00
commit 32758d988e
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
44 changed files with 559 additions and 25 deletions

View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 2021.10.3
PROJECT_NUMBER = 2021.12.0-dev
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a

View File

@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
ESPHOME_REF = 2021.10.3
ESPHOME_REF = dev
.PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

View File

@ -1 +1 @@
2021.10.3
2021.12.0-dev

View File

@ -0,0 +1,85 @@
CAP1188 Capacitive Touch Sensor
===============================
.. seo::
:description: Instructions for setting up CAP1188 Capacitive Touch Sensor
:image: cap1188.jpg
:keywords: CAP1188
.. _cap1188-component:
Component/Hub
-------------
The ``cap1188`` sensor platform allows you to use your CAP1188
(`datasheet <https://cdn-shop.adafruit.com/datasheets/CAP1188.pdf>`__,
`Adafruit`_) Capacitive Touch Sensor with ESPHome. The :ref:`I²C <i2c>` bus is
required to be set up in your configuration for this sensor to work.
.. figure:: images/cap1188-full.jpg
:align: center
:width: 75%
CAP1188 Capacitive Touch Sensor. Image by `Adafruit`_.
.. _Adafruit: https://learn.adafruit.com/adafruit-cap1188-breakout/overview
.. code-block:: yaml
# Example configuration entry
cap1188:
id: cap1188_component
address: 0x29
reset_pin: 14
touch_threshold: 0x40
allow_multiple_touches: 0x80
binary_sensor:
- platform: cap1188
id: touch_key0
channel: 0
name: "Touch Key 0"
Configuration variables:
------------------------
The configuration is made up of two parts: The central component, and individual Binary sensors per channel.
- **address** (*Optional*, integer): The I²C address of the sensor. Defaults to ``0x29``.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor.
- **reset_pin** (*Optional*, :ref:`config-pin`): Set the pin that is used to reset the CAP1188 board on boot.
- **touch_threshold** (*Optional*, integer): The touch threshold for all channels. This defines the sensitivity for touch detection.
- ``0x00``: Maximum sensitivity - Most sensitive to touch
- ``0x20``: Default sensitivity
- ``0x40``: Medium sensitivity (I used this sensitivity when being used through a 3mm sheet of plastic)
- ``0x80``: Minimum sensitivity - Least sensitive to touch
- **allow_multiple_touches** (*Optional*, boolean): Whether to allow multitouch. Defaults to off.
Binary Sensor
-------------
The ``cap1188`` binary sensor allows you to use your CAP1188 with ESPHome.
First, setup a :ref:`cap1188-component` and then use this binary sensor platform to create individual
binary sensors for each touch sensor.
Configuration variables:
- **name** (*Optional*, string): The name for the binary sensor.
- **cap1188_id** (*Optional*, :ref:`config-id`): The ID of the CAP1188 defined above. Useful for multiple CAP1188's on the I²C bus.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **channel** (**Required**, integer): The channel number the CAP1188 the touchkey is connected to.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
.. note::
SPI is not currently supported. I²C must be used at this time.
See Also
--------
- :ref:`sensor-filters`
- :apiref:`cap1188/cap1188.h`
- `Adafruit CAP1188 Library <https://github.com/adafruit/Adafruit_CAP1188_Library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

Binary file not shown.

After

Width:  |  Height:  |  Size: 168 KiB

View File

@ -60,6 +60,10 @@ Advanced options:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _binary_sensor-filters:

View File

@ -42,5 +42,7 @@ See Also
--------
- :doc:`wifi`
- :doc:`improv_serial`
- :doc:`esp32_improv`
- :apiref:`captive_portal/captive_portal.h`
- :ghedit:`Edit`

View File

@ -53,6 +53,10 @@ Advanced options:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
MQTT options:
@ -180,6 +184,21 @@ advanced stuff.
// etc. see API reference
call.perform();
.. _climate-on_state_trigger:
``climate.on_state`` Trigger
******************************************************
This trigger is activated each time the state of the climate device is updated
(for example, if the current temperature measurement or the mode set by the users changes).
.. code-block:: yaml
climate:
- platform: midea # or any other platform
# ...
on_state:
- logger.log: "State updated!"
See Also
--------

View File

@ -96,11 +96,23 @@ This platform utilises the library's generic one-size-fits-all API, which might
Additional configuration must be specified for this platform:
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``
- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba``
- **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto``
- **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto``
- **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to.
- **min_temperature** (**Required**, float): The minimum temperature that the AC unit supports being set to.
- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient temperature.
.. note::
- The ``greeyac`` protocol supports a feature Gree calls "I-Feel". The handheld remote control
has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the
AC unit. If a ``sensor`` is provided in the configuration with this model, the sensor's temperature will be
transmitted to the ``greeyac`` device in the same manner as the original remote controller. How often the
temperature is transmitted is determined by the ``update_interval`` assigned to the ``sensor``. Note that
``update_interval`` must be less than 10 minutes or the ``greeyac`` device will revert to using its own
internal temperature sensor; a value of 2 minutes seems to work well. See :doc:`/components/sensor/index`
for more information.
.. _ir-receiver_id:

View File

@ -40,6 +40,10 @@ Advanced options:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
MQTT options:

View File

@ -56,6 +56,8 @@ Configuration variables:
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.

View File

@ -35,7 +35,9 @@ individually.
So, first a few basics: When setting up a display platform in ESPHome there will be a configuration
option called ``lambda:`` which will be called every time ESPHome wants to re-render the display.
In there, you can write code like in any :ref:`lambda <config-lambda>` in ESPHome. Display
In each cycle, the display is automatically cleared before the lambda is executed. You can disable
this behavior by setting ``auto_clear_enabled: false``.
In the lambda, you can write code like in any :ref:`lambda <config-lambda>` in ESPHome. Display
lambdas are additionally passed a variable called ``it`` which represents the rendering engine object.
.. code-block:: yaml

View File

@ -66,6 +66,8 @@ Configuration variables:
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
to use multiple SPI buses.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **num_chip_lines** (*Optional*, integer): Number of lines if you want to use the displays in Multiline Mode. Defaults to ``1`` Example: https://github.com/esphome/esphome/pull/1622#issue-836179156
- **chip_lines_style** (*Optional*): How are the lines in Multiline Mode connected? Possible values are ``zigzag`` and ``snake``. Defaults to ``snake``
.. _display-max7219digit_lambda:

View File

@ -34,6 +34,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
Connection Options:
@ -312,7 +316,7 @@ Configuration for TTGO-Camera Mini
# Image settings
name: My Camera
# ...
Configuration for ESP-EYE
----------------------------------

View File

@ -0,0 +1,38 @@
ESP32 Camera Web Server Component
=================================
.. seo::
:description: Instructions for setting up the ESP32 Camera Web Server in ESPHome
:image: camera.png
The ``esp32_camera_web_server`` component allows you to use expose web server of
ESP32-based camera boards in ESPHome that directly can be integrated into external
surveillance or PVR software.
At a given time only one stream can be served, but multiple snapshots. The stream
or snapshot can be accessed via `http://<ip>:<port>/`.
.. code-block:: yaml
# Example configuration entry
esp32_camera_web_server:
- port: 8080
mode: stream
- port: 8081
mode: snapshot
Configuration variables:
------------------------
- **port** (**Required**, string): The serving port.
- **mode** (**Required**, string): The operation mode.
One of these values:
- ``snapshot``
- ``stream``
See Also
--------
- :apiref:`esp32_camera_web_server/esp32_camera_web_server.h`
- :ghedit:`Edit`

View File

@ -1,8 +1,8 @@
Improv
======
Improv via BLE
==============
.. seo::
:description: Instructions for setting up Improv WiFi in ESPHome.
:description: Instructions for setting up Improv via BLE in ESPHome.
:image: improv-social.png
The ``esp32_improv`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
@ -35,6 +35,7 @@ See Also
--------
- :doc:`wifi`
- :doc:`improv_serial`
- :doc:`captive_portal`
- `Improv Wi-Fi <https://www.improv-wifi.com/>`__
- :apiref:`esp32_improv/esp32_improv_component.h`

View File

@ -22,6 +22,10 @@ Bundled components can be overridden using this feature.
- source: github://esphome/esphome@dev
components: [ rtttl ]
# equivalent shorthand for GitHub pull request
- source: github://pr#2639
components: [ rtttl ]
# use all components from a local folder
- source:
type: local
@ -165,6 +169,14 @@ The source field accepts a short hand **github://** resource:
# shorthand
source: github://<user or org>/<repository name>[@<branch or tag>]
The source field also accepts a short hand **github://** pull request from the ESPHome repository:
.. code-block:: yaml
external_components:
# shorthand
source: github://pr#<number>
Under the hood, during validation, ESPHome will clone the git repository into the hidden ``.esphome``
folder and components will then be loaded from this local copy. The local path of the cloned repository
varies per repository name and ref name, so repositories with different refs are considered different

View File

@ -36,6 +36,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
MQTT options:

View File

@ -0,0 +1,33 @@
Improv via Serial
=================
.. seo::
:description: Instructions for setting up Improv via Serial in ESPHome.
:image: improv-social.png
The ``improv_serial`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
for configuring Wi-Fi on an ESPHome device by using a serial connection to the device, eg. USB.
The ``improv_serial`` component requires the serial ``logger`` to be configured.
.. code-block:: yaml
# Example configuration entry
wifi:
# ...
improv_serial:
No configuration variables.
See Also
--------
- :doc:`wifi`
- :doc:`captive_portal`
- :doc:`esp32_improv`
- `Improv Wi-Fi <https://www.improv-wifi.com/>`__
- :apiref:`improv_serial/improv_serial_component.h`
- :ghedit:`Edit`

View File

@ -67,6 +67,10 @@ Advanced options:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _light-toggle_action:

View File

@ -43,6 +43,9 @@ Configuration variables:
- **discovery_prefix** (*Optional*, string): The prefix to use for Home
Assistants MQTT discovery. Should not contain trailing slash.
Defaults to ``homeassistant``.
- **use_abbreviations** (*Optional*, boolean): Whether to use
`Abbreviations <https://www.home-assistant.io/docs/mqtt/discovery/>`__
in discovery messages. Defaults to ``true``.
- **topic_prefix** (*Optional*, string): The prefix used for all MQTT
messages. Should not contain trailing slash. Defaults to
``<APP_NAME>``.

View File

@ -38,6 +38,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
Automations:

View File

@ -106,6 +106,27 @@ Configuration variables:
with for infrared signals. Defaults to ``0Hz``.
- All other options from :ref:`remote_transmitter-transmit_action`.
.. _remote_transmitter-transmit_pronto:
``remote_transmitter.transmit_pronto`` Action
*********************************************
This :ref:`action <config-action>` sends a raw code to a remote transmitter specified in Pronto format.
.. code-block:: yaml
on_...:
- remote_transmitter.transmit_pronto:
data: "0000 006D 0010 0000 0008 0020 0008 0046 000A 0020 0008 0020 0008 001E 000A 001E 000A 0046 000A 001E 0008 0020 0008 0020 0008 0046 000A 0046 000A 0046 000A 001E 000A 001E 0008 06C3"
Configuration variables:
- **data** (**Required**, string): The raw code to send specified as a string.
A lot of remote control Pronto codes can be found on http://remotecentral.com
- All other options from :ref:`remote_transmitter-transmit_action`.
``remote_transmitter.transmit_jvc`` Action
******************************************

View File

@ -38,6 +38,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
Automations:

View File

@ -30,7 +30,8 @@ Configuration variables:
Or on the ESP8266 alternatively also ``VCC``, see :ref:`adc-esp8266_vcc`.
- **name** (**Required**, string): The name of the voltage sensor.
- **attenuation** (*Optional*): Only on ESP32. Specify the ADC
attenuation to use. See :ref:`adc-esp32_attenuation`.
attenuation to use. See :ref:`adc-esp32_attenuation`. Defaults to ``0db``.
- **raw** (*Optional*): Allows to read the raw ADC output without any conversion or calibration. Defaults to ``false``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval
to check the sensor. Defaults to ``60s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
@ -52,22 +53,23 @@ Configuration variables:
- multiply: 3.3
.. _adc-esp32_attenuation:
ESP32 Attenuation
-----------------
On the ESP32, the voltage measured with the ADC caps out at 1.1V by default as the sensing range
or the attenuation of the ADC is set to ``0db`` by default.
On the ESP32 the voltage measured with the ADC caps out at ~1.1V by default as the sensing range (attenuation of the ADC) is set to ``0db`` by default.
Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``11db``.
There's more information `at the manufacturer's website <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc.html#_CPPv425adc1_config_channel_atten14adc1_channel_t11adc_atten_t>`__.
To measure voltages higher than 1.1V, set ``attenuation`` to one of the `following values
<https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/adc.html#_CPPv225adc1_config_channel_atten14adc1_channel_t11adc_atten_t>`__:
To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation
<https://github.com/esphome/esphome/blob/dev/esphome/components/adc/adc_sensor.cpp>`__ combines all available ranges to allow the best resolution without having to compromise on a specific attenuation.
.. note::
In our tests, the usable ADC range was from ~0.075V to ~3.12V (with the ``attenuation: auto`` setting), and anything outside that range capped out at either end.
Even though the measurements are calibrated, the range *limits* are variable among chips due to differences in the internal voltage reference.
- ``0db`` for a full-scale voltage of 1.1V (default)
- ``2.5db`` for a full-scale voltage of 1.5V
- ``6db`` for a full-scale voltage of 2.2V
- ``11db`` for a full-scale voltage of 3.9V
.. _adc-esp8266_vcc:

View File

@ -0,0 +1,74 @@
CSE7761 Power Sensor
====================
.. seo::
:description: Instructions for setting up CSE7761 power sensors for the Sonoff Dual R3 v1.x
:image: cse7761.png
:keywords: cse7761, Sonoff Dual R3
The ``cse7761`` sensor platform allows you to use your CSE7761 voltage/current and power sensors
with ESPHome. This sensor is commonly found in Sonoff Dual R3 v1.x.
.. note::
SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins.
As the communication with the CSE7761 done using UART, you need
to have an :ref:`UART bus <uart>` in your configuration with the ``tx_pin`` and ``rx_pin`` connected to the CSE7761.
Additionally, you need to set the baud rate to 38400 and parity to ``EVEN``.
.. code-block:: yaml
# Example configuration entry
# Disable logging over serial
logger:
baud_rate: 0
uart:
tx_pin: GPIO25
rx_pin: GPIO26
baud_rate: 38400
parity: EVEN
sensor:
- platform: cse7761
voltage:
name: 'CSE7761 Voltage'
current_1:
name: 'CSE7761 Current 1'
current_2:
name: 'CSE7761 Current 2'
active_power_1:
name: 'CSE7761 Active Power 1'
active_power_2:
name: 'CSE7761 Active Power 2'
update_interval: 5s
.. note::
The configuration above should work for Sonoff Dual R3 v1.x.
Configuration variables:
------------------------
- **voltage** (*Optional*): Use the voltage value of the sensor in V (RMS).
All options from :ref:`Sensor <config-sensor>`.
- **current_1** (*Optional*): Use the current value of the channel 1 in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **current_2** (*Optional*): Use the current value of the channel 2 in amperes. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_1** (*Optional*): Use the (active) power value of the channel 1 in watts. All options from
:ref:`Sensor <config-sensor>`.
- **active_power_2** (*Optional*): Use the (active) power value of the channel 2 in watts. All options from
:ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
to use multiple UART buses.
See Also
--------
- :ref:`sensor-filters`
- :apiref:`cse7761/cse7761.h`
- :ghedit:`Edit`

View File

@ -62,6 +62,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
Automations:

View File

@ -17,6 +17,7 @@ This platform supports three sensor types, which you need to specify using the `
value:
- ``PMSX003`` for generic PMS5003, PMS7003, ...; these sensors support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` output.
- ``PMS5003S`` for PMS5003ST. These support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` and ``formaldehyde``.
- ``PMS5003T`` for PMS5003T. These support ``pm_2_5``, ``temperature`` and ``humidity``.
- ``PMS5003ST`` for PMS5003ST. These support ``pm_2_5``, ``temperature``, ``humidity`` and ``formaldehyde``.
@ -68,7 +69,7 @@ Configuration variables:
All options from :ref:`Sensor <config-sensor>`.
- **humidity** (*Optional*): Use the humidity value in % for the ``PMS5003T`` and ``PMS5003ST``.
All options from :ref:`Sensor <config-sensor>`.
- **formaldehyde** (*Optional*): Use the formaldehyde (HCHO) concentration in µg per cubic meter for the ``PMS5003ST``.
- **formaldehyde** (*Optional*): Use the formaldehyde (HCHO) concentration in µg per cubic meter for the ``PMS5003S`` and ``PMS5003ST``.
All options from :ref:`Sensor <config-sensor>`.
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
to use multiple UART buses.

View File

@ -59,6 +59,17 @@ Configuration variables:
the knob further will not decrease the number. Defaults to no minimum.
- **max_value** (*Optional*, int): The maximum value this rotary encoder will go to, turning
the knob further will not increase the number. Defaults to no maximum.
- **publish_initial_value** (*Optional*, boolean): Controls whether the value is published
upon start of ESPHome. By default the value is only published when it changes, causing an
"unknown" value at first. If you set this option to true, the value is published once after
boot and when it changes. Defaults to ``false``.
- **restore_mode** (*Optional*): Control how the Rotary Encoder attempts to restore state on bootup.
For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the
:doc:`esphome section </components/esphome>`.
- ``RESTORE_DEFAULT_ZERO`` (Default) - Attempt to restore state and default to zero (0) if not possible to restore.
- ``ALWAYS_ZERO`` - Always initialize the counter with value zero (0).
- **on_clockwise** (*Optional*, :ref:`Automation <automation>`): Actions to be performed when
the knob is turned clockwise. See :ref:`sensor-rotary_encoder-triggers`.
- **on_anticlockwise** (*Optional*, :ref:`Automation <automation>`): Actions to be performed when

View File

@ -153,12 +153,14 @@ Setting Up Devices
To set up RuuviTag devices you first need to find their MAC Address so that
ESPHome can identify them. So first, create a simple configuration without any
``ruuvitag`` entries like so:
``ruuvitag`` entries but with ``ruuvi_ble`` enabled like so:
.. code-block:: yaml
esp32_ble_tracker:
ruuvi_ble:
After uploading the ESP32 will immediately try to scan for BLE devices.
When it detects these sensors, it will automatically parse the BLE message
print a message like this one:

View File

@ -42,6 +42,7 @@ required to be set up in your configuration for this sensor to work.
name: "TCS34725 Color Temperature"
gain: 1x
integration_time: 2.4ms
glass_attenuation_factor: 1.0
address: 0x29
update_interval: 60s
@ -63,7 +64,10 @@ Configuration variables:
- **gain** (*Optional*): Set the gain for the internal ADCs to work better in certain low-light conditions. Valid
values are ``1x`` (default), ``4x``, ``16x``, ``60x`` (highest gain).
- **integration_time** (*Optional*): The amount of time the light sensor is exposed. Valid values are
``2.4ms`` (default), ``24ms``, ``50ms``, ``101ms``, ``154ms``, ``700ms``.
``2.4ms`` (default), ``24ms``, ``50ms``, ``101ms``, ``120ms``, ``154ms``, ``180ms``, ``199ms``,
``240ms``, ``300ms``, ``360ms``, ``401ms``, ``420ms``, ``480ms``, ``499ms``, ``540ms``, ``600ms``, ``614ms``.
- **glass_attenuation_factor** (*Optional*): The attenuation factor of glass if it's behind some glass facia.
Default is ``1.0`` means ``100%`` transmissivity. ``2`` means ``50%`` transmissivity etc.
- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x29``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.

View File

@ -458,6 +458,8 @@ To find the MAC Address so that ESPHome can identify the device, you can create
esp32_ble_tracker:
xiaomi_ble:
After uploading, the ESP32 will immediately try to scan for BLE devices. When it detects a new sensor, it will automatically parse the BLE message print a message like this one:
.. code::

View File

@ -38,6 +38,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, All other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _switch-toggle_action:

View File

@ -32,6 +32,10 @@ Configuration variables:
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, All other options from :ref:`MQTT Component <config-mqtt-component>`.
Automations:

View File

@ -58,6 +58,7 @@ Configuration variables:
- **parity** (*Optional*): The parity used on the UART bus. Options: ``NONE``, ``EVEN``, ``ODD``. Defaults to ``NONE``.
- **stop_bits** (*Optional*, int): The number of stop bits to send. Options: 1, 2. Defaults to 1.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this UART hub if you need multiple UART hubs.
- **debug** (*Optional*, mapping): Options for debugging communication on the UART hub, see :ref:`uart-debugging`.
ESP32 options:
@ -110,6 +111,70 @@ This :ref:`Action <config-action>` sends a defined UART signal to the given UART
id: my_second_uart
data: 'other data'
.. _uart-debugging:
Debugging
---------
If you need insight in the communication that is being sent and/or received over a UART bus, then you can make use
of the debugging feature.
.. code-block:: yaml
# Example configuration entry
uart:
baud_rate: 115200
debug:
direction: BOTH
dummy_receiver: false
after:
bytes: 60
sequence:
- lambda: UARTDebug::log_hex(direction, bytes, ':');
- **direction** (*Optional*, enum): The direction of communication to debug, one of: "RX" (receive, incoming),
"TX" (send, outgoing) or "BOTH". Defaults to "BOTH".
- **dummy_receiver** (*Optional*, boolean): Whether or not to enable the dummy receiver feature. The debugger
will only accumulate bytes that are actually read or sent by a UART device component. This feature is
useful when you want to debug all incoming communication, while no UART device component is configured
for the UART bus (yet). This is especially useful for developers. Normally you'd want to leave this
option disabled. Defaults to false.
- **after** (*Optional*, mapping): The debugger accumulates bytes of communication. This option defines when
to trigger publishing the accumulated bytes. The possible options are:
- **bytes** (*Optional*, int): Trigger after accumulating the specified number of bytes. Defaults to 256.
- **timeout** (*Optional*, :ref:`config-time`): Trigger after no communication has been seen during the
specified timeout, while one or more bytes have been accumulated. Defaults to 100ms.
- **sequence** (*Optional*, string or list of bytes): Trigger after the specified sequence of bytes is
detected in the communication.
- **sequence** (*Required*, :ref:`config-action`): Action(s) to perform for publishing debugging data. The
actions can make use of the following variables:
- **direction**: ``uart::UART_DIRECTION_RX`` or ``uart::UART_DIRECTION_TX``
- **bytes**: ``std::vector<uint8_t>`` containing the accumulated bytes
**Helper functions for logging**
Helper functions are provided to make logging of debug data in various formats easy:
- **UARTDebug::log_hex(direction, bytes, char separator)** Log the bytes as hex values, separated by the provided
separator character.
- **UARTDebug::log_string(direction, bytes)** Log the bytes as string values, escaping unprintable characters.
- **UARTDebug::log_int(direction, bytes, char separator)** Log the bytes as integer values, separated by the provided
separator character.
- **UARTDebug::log_binary(direction, bytes, char separator)** Log the bytes as ``<binary> (<hex>)`` values,
separated by the provided separator character.
**Logger buffer size**
Beware that the ``logger`` component uses a limited buffer size of 512 bytes by default. If the UART
debugger log lines become too long, then you will notice that they end up truncated in the log output.
In that case, either make sure that the debugger outputs less data per log line (e.g. by setting the
``after.bytes`` option to a lower value) or increase the logger buffer size using the logger
``tx_buffer_size`` option.
See Also
--------

View File

@ -50,6 +50,7 @@ Configuration variables:
- **username** (**Required**, string): The username to use for authentication.
- **password** (**Required**, string): The password to check for authentication.
- **ota** (*Optional*, boolean): Turn on or off the OTA feature inside webserver. Strongly not suggested without enabled authentication settings. Default: `true`
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. note::
@ -67,12 +68,14 @@ Configuration variables:
Example web_server configuration with CSS and JS included from esphome-docs.
CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface.
Force to turn off OTA function because the missing authentication.
.. code-block:: yaml
# Example configuration entry
web_server:
port: 80
ota: false
css_include: "../../../esphome-docs/_static/webserver-v1.min.css"
css_url: ""
js_include: "../../../esphome-docs/_static/webserver-v1.min.js"

View File

@ -67,9 +67,9 @@ author = "Otto Winter"
# built documents.
#
# The short X.Y version.
version = "2021.10"
version = "2021.12"
# The full version, including alpha/beta/rc tags.
release = "2021.10.3"
release = "2021.12.0-dev"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

View File

@ -102,6 +102,22 @@ Sonoff Dual R2 v1.4
GPIO10, Button on the case,
GPIO13, Blue LED (inverted)
Sonoff Dual R3 v1.x
-------------------
.. pintable::
GPIO27, Relay #1,
GPIO14, Relay #2,
GPIO0, Button,
GPIO13, Blue LED (inverted),
GPIO32, SW Input #1 (inverted),
GPIO33, SW Input #2 (inverted),
GPIO25, UART TX pin (for power sensor)
GPIO26, UART RX pin (for power sensor)
See :doc:`/components/sensor/cse7761` for measuring power.
Sonoff Pow R1
-------------

View File

@ -561,6 +561,30 @@ Configuration variables:
- **condition** (**Required**): The condition to check whether to execute. See :ref:`Conditions <config-condition>`.
- **then** (**Required**, :ref:`config-action`): The action to perform until the condition evaluates to false.
.. _repeat_action:
``repeat`` Action
-----------------
This action allows you to repeat a block a given number of times.
For example, the automation below will flash the light five times.
.. code-block:: yaml
on_...:
- repeat:
count: 5
then:
- light.turn_on: some_light
- delay: 1s
- light.turn_off: some_light
- delay: 10s
Configuration variables:
- **count** (**Required**, integer): The number of times the action should be repeated.
- **then** (**Required**, :ref:`config-action`): The action to repeat.
.. _wait_until_action:
``wait_until`` Action

View File

@ -47,6 +47,10 @@ Example configuration
esp32_improv:
authorizer: none
logger:
improv_serial:
Relevant Documentation
----------------------
@ -61,6 +65,7 @@ Relevant Documentation
- ``dashboard_import`` -> ``package_import_url`` - This should point to the public repository containing
the configuration for the device so that the user's ESPHome dashboard can autodetect this device and
create a minimal YAML using :ref:`config-git_packages`.
- ``improv_serial`` - :doc:`/components/improv_serial`
See Also
--------

BIN
images/cap1188.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

49
images/cse7761.svg Normal file
View File

@ -0,0 +1,49 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
width="261.333"
height="60"
version="1.1"
id="svg8"
sodipodi:docname="cse7761.svg"
inkscape:version="1.1.1 (3bf5ae0d25, 2021-09-20)"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<defs
id="defs12" />
<sodipodi:namedview
id="namedview10"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
showgrid="false"
inkscape:zoom="4.1777075"
inkscape:cx="120.04191"
inkscape:cy="26.928644"
inkscape:window-width="2560"
inkscape:window-height="1349"
inkscape:window-x="0"
inkscape:window-y="30"
inkscape:window-maximized="1"
inkscape:current-layer="svg8" />
<path
d="M19.333.667H242c10.31 0 18.667 8.357 18.667 18.666V40c0 10.31-8.358 18.667-18.667 18.667H19.333C9.024 58.667.667 50.309.667 40V19.333C.667 9.024 9.024.667 19.333.667z"
id="path2" />
<path
d="M19.333.667H242c10.31 0 18.667 8.357 18.667 18.666V40c0 10.31-8.358 18.667-18.667 18.667H19.333C9.024 58.667.667 50.309.667 40V19.333C.667 9.024 9.024.667 19.333.667z"
fill="none"
stroke="#000"
stroke-width="1.333"
stroke-linecap="round"
stroke-linejoin="round"
stroke-miterlimit="10"
id="path4" />
<path
id="path866"
style="fill:#ffffff"
d="m 245.01812,13.6665 v 32.667 h -11.014 v -24.36 h -5.6 v -8.307 z M 34.51588,47.08 c -3.453333,0 -6.564333,-0.715667 -9.333,-2.147 -2.769333,-1.462 -4.947333,-3.484 -6.534,-6.066 -1.555333,-2.613333 -2.333,-5.569 -2.333,-8.867 0,-3.298 0.777667,-6.238 2.333,-8.82 1.586667,-2.613333 3.764667,-4.635667 6.534,-6.067 2.768667,-1.462 5.879667,-2.193 9.333,-2.193 3.173333,0 6.004333,0.56 8.493,1.68 2.489333,1.12 4.542667,2.737667 6.16,4.853 l -6.953,6.207 c -2.022,-2.551333 -4.402,-3.827 -7.14,-3.827 -2.302,0 -4.153,0.746667 -5.553,2.24 -1.4,1.462667 -2.1,3.438333 -2.1,5.927 0,2.488667 0.7,4.479667 2.1,5.973 1.4,1.462667 3.251,2.194 5.553,2.194 2.738,0 5.118,-1.275667 7.14,-3.827 l 6.953,6.207 c -1.617333,2.115333 -3.670667,3.733 -6.16,4.853 -2.488667,1.12 -5.319667,1.68 -8.493,1.68 z m 33.54,0 c -2.706667,0 -5.351,-0.295667 -7.933,-0.887 -2.551333,-0.622 -4.651333,-1.446333 -6.3,-2.473 l 3.546,-8.027 c 1.556,0.902667 3.298333,1.634 5.227,2.194 1.928667,0.528667 3.779667,0.793 5.553,0.793 1.524667,0 2.613667,-0.14 3.267,-0.42 0.653333,-0.311333 0.98,-0.762333 0.98,-1.353 0,-0.684667 -0.435667,-1.198 -1.307,-1.54 -0.84,-0.342667 -2.24,-0.716 -4.2,-1.12 -2.52,-0.529333 -4.62,-1.089333 -6.3,-1.68 -1.68,-0.622667 -3.142,-1.618333 -4.386,-2.987 -1.244667,-1.4 -1.867,-3.282333 -1.867,-5.647 0,-2.053333 0.575667,-3.92 1.727,-5.6 1.150667,-1.68 2.861667,-3.002 5.133,-3.966 2.302,-0.964667 5.086333,-1.447 8.353,-1.447 2.24,0 4.433333,0.249 6.58,0.747 2.178,0.466667 4.091333,1.166667 5.74,2.1 l -3.313,7.98 c -3.204667,-1.618 -6.238,-2.427 -9.1,-2.427 -2.831333,0 -4.247,0.684333 -4.247,2.053 0,0.653333 0.42,1.151333 1.26,1.494 0.84,0.310667 2.224667,0.652667 4.154,1.026 2.488667,0.466667 4.588667,1.011333 6.3,1.634 1.710667,0.590667 3.188333,1.570667 4.433,2.94 1.275333,1.368667 1.913,3.235333 1.913,5.6 0,2.053333 -0.575333,3.92 -1.726,5.6 -1.151333,1.648667 -2.878,2.970667 -5.18,3.966 -2.271333,0.964667 -5.040333,1.447 -8.307,1.447 z m 49.64,-9.053 v 8.306 h -27.16 V 13.667 h 26.553 v 8.306 h -15.726 V 25.8 h 13.813 v 7.933 h -13.813 v 4.294 z m 34.52,-24.36 v 6.766 l -10.873,25.9 h -12.04 l 10.36,-24.126 h -6.3 v 4.76 h -9.1 v -13.3 z m 34.1,0 v 6.766 l -10.873,25.9 h -12.04 l 10.36,-24.126 h -6.3 v 4.76 h -9.1 v -13.3 z m 23.32,11.526 c 1.99133,0 3.84233,0.435667 5.553,1.307 1.71133,0.871333 3.08033,2.100333 4.107,3.687 1.02667,1.586667 1.54,3.406667 1.54,5.46 0,2.270667 -0.591,4.277333 -1.773,6.02 -1.15133,1.742 -2.738,3.079667 -4.76,4.013 -2.02267,0.933333 -4.26267,1.4 -6.72,1.4 -3.14267,0 -5.896,-0.606667 -8.26,-1.82 -2.33333,-1.213333 -4.15333,-3.017667 -5.46,-5.413 -1.30667,-2.396 -1.96,-5.336 -1.96,-8.82 0,-3.733333 0.74667,-6.969 2.24,-9.707 1.524,-2.738 3.63933,-4.822333 6.346,-6.253 2.738,-1.431333 5.91133,-2.147 9.52,-2.147 1.96,0 3.82667,0.233333 5.6,0.7 1.77333,0.435333 3.28233,1.057667 4.527,1.867 l -3.967,7.7 c -1.61733,-1.151333 -3.59267,-1.727 -5.926,-1.727 -1.898,0 -3.46933,0.482333 -4.714,1.447 -1.21333,0.933333 -2.00667,2.302 -2.38,4.106 1.71133,-1.213333 3.87367,-1.82 6.487,-1.82 z m -2.8,14.28 c 0.99533,0 1.80433,-0.295333 2.427,-0.886 0.622,-0.591333 0.933,-1.400333 0.933,-2.427 0,-1.026667 -0.311,-1.835667 -0.933,-2.427 -0.62267,-0.622 -1.43167,-0.933 -2.427,-0.933 -0.99533,0 -1.80433,0.311 -2.427,0.933 -0.622,0.591333 -0.933,1.400333 -0.933,2.427 0,1.026667 0.311,1.835667 0.933,2.427 0.62267,0.590667 1.43167,0.886 2.427,0.886 z" />
</svg>

After

Width:  |  Height:  |  Size: 4.9 KiB

View File

@ -238,6 +238,7 @@ Electricity
ADE7953, components/sensor/ade7953, ade7953.svg, Power
ATM90E32, components/sensor/atm90e32, atm90e32.jpg, Voltage & Current & Power
CS5460A, components/sensor/cs5460a, cs5460a.png, Voltage & Current & Power
CSE7761, components/sensor/cse7761, cse7761.svg, Voltage & Current & Power
CSE7766, components/sensor/cse7766, cse7766.svg, Voltage & Current & Power
CT Clamp, components/sensor/ct_clamp, ct_clamp.jpg, AC current
Daly BMS, components/sensor/daly_bms, daly_bms.png, Voltage & Current & Power
@ -382,6 +383,7 @@ Binary Sensor Components
Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png
Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png
XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg
CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg
Custom Binary Sensor, components/binary_sensor/custom, language-cpp.svg
Output Components
@ -577,6 +579,7 @@ Misc Components
ESP32 Ethernet, components/ethernet, ethernet.svg
ESP32 Camera, components/esp32_camera, camera.svg
ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg
Stepper, components/stepper/index, stepper.svg
Servo, components/servo, servo.svg
@ -589,7 +592,8 @@ Misc Components
SIM800L, components/sim800l, sim800l.jpg
DFPlayer, components/dfplayer, dfplayer.svg
Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg
Improv, components/esp32_improv, improv.svg
Improv via BLE, components/esp32_improv, improv.svg
Improv via Serial, components/improv_serial, improv.svg
Debug Component, components/debug, bug-report.svg
TM1651 Battery Display, components/tm1651, tm1651_battery_display.jpg
RF Bridge, components/rf_bridge, rf_bridge.jpg

BIN
svg2png/cse7761.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB