diff --git a/Doxygen b/Doxygen index 51eb7461d..aabf3a3f3 100644 --- a/Doxygen +++ b/Doxygen @@ -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 diff --git a/Makefile b/Makefile index dfb79bfd5..a3947eab0 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/_static/version b/_static/version index b7d352674..f69ab25f7 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2021.10.3 \ No newline at end of file +2021.12.0-dev \ No newline at end of file diff --git a/components/binary_sensor/cap1188.rst b/components/binary_sensor/cap1188.rst new file mode 100644 index 000000000..6d3cdfc84 --- /dev/null +++ b/components/binary_sensor/cap1188.rst @@ -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 `__, +`Adafruit`_) Capacitive Touch Sensor with ESPHome. The :ref:`I²C ` 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 `. + +.. 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 `__ by `Adafruit `__ +- :ghedit:`Edit` diff --git a/components/binary_sensor/images/cap1188-full.jpg b/components/binary_sensor/images/cap1188-full.jpg new file mode 100644 index 000000000..68c392885 Binary files /dev/null and b/components/binary_sensor/images/cap1188-full.jpg differ diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index 3cf2a1802..30a6cec8b 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -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 `. .. _binary_sensor-filters: diff --git a/components/captive_portal.rst b/components/captive_portal.rst index a40884f01..cefd84933 100644 --- a/components/captive_portal.rst +++ b/components/captive_portal.rst @@ -42,5 +42,7 @@ See Also -------- - :doc:`wifi` +- :doc:`improv_serial` +- :doc:`esp32_improv` - :apiref:`captive_portal/captive_portal.h` - :ghedit:`Edit` diff --git a/components/climate/index.rst b/components/climate/index.rst index 21101b84c..3a130a4da 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -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 -------- diff --git a/components/climate/ir_climate.rst b/components/climate/ir_climate.rst index 4152dfa6e..62db46695 100755 --- a/components/climate/ir_climate.rst +++ b/components/climate/ir_climate.rst @@ -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: diff --git a/components/cover/index.rst b/components/cover/index.rst index a96f45c4a..33d5471b4 100644 --- a/components/cover/index.rst +++ b/components/cover/index.rst @@ -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: diff --git a/components/display/ili9341.rst b/components/display/ili9341.rst index 78f8366dc..e48bf31f4 100644 --- a/components/display/ili9341.rst +++ b/components/display/ili9341.rst @@ -56,6 +56,8 @@ Configuration variables: - **lambda** (*Optional*, :ref:`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. diff --git a/components/display/index.rst b/components/display/index.rst index b6d50e9f5..b312ba18c 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -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 ` 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 ` in ESPHome. Display lambdas are additionally passed a variable called ``it`` which represents the rendering engine object. .. code-block:: yaml diff --git a/components/display/max7219digit.rst b/components/display/max7219digit.rst index 9707d8b57..32436a884 100644 --- a/components/display/max7219digit.rst +++ b/components/display/max7219digit.rst @@ -66,6 +66,8 @@ Configuration variables: - **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` 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: diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 6eab5c8b2..abf273817 100644 --- a/components/esp32_camera.rst +++ b/components/esp32_camera.rst @@ -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 ---------------------------------- diff --git a/components/esp32_camera_web_server.rst b/components/esp32_camera_web_server.rst new file mode 100644 index 000000000..48e345e08 --- /dev/null +++ b/components/esp32_camera_web_server.rst @@ -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://:/`. + +.. 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` diff --git a/components/esp32_improv.rst b/components/esp32_improv.rst index f9a2589c2..2eea322a9 100644 --- a/components/esp32_improv.rst +++ b/components/esp32_improv.rst @@ -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 `__ @@ -35,6 +35,7 @@ See Also -------- - :doc:`wifi` +- :doc:`improv_serial` - :doc:`captive_portal` - `Improv Wi-Fi `__ - :apiref:`esp32_improv/esp32_improv_component.h` diff --git a/components/external_components.rst b/components/external_components.rst index 2d49f29f3..852459333 100644 --- a/components/external_components.rst +++ b/components/external_components.rst @@ -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:///[@] +The source field also accepts a short hand **github://** pull request from the ESPHome repository: + +.. code-block:: yaml + + external_components: + # shorthand + source: github://pr# + 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 diff --git a/components/fan/index.rst b/components/fan/index.rst index 67035f60b..33e2df0e4 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -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: diff --git a/components/improv_serial.rst b/components/improv_serial.rst new file mode 100644 index 000000000..5ba3ae0bd --- /dev/null +++ b/components/improv_serial.rst @@ -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 `__ +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 `__ +- :apiref:`improv_serial/improv_serial_component.h` +- :ghedit:`Edit` diff --git a/components/light/index.rst b/components/light/index.rst index f092a2cf8..6c8e8af7a 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -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 `. .. _light-toggle_action: diff --git a/components/mqtt.rst b/components/mqtt.rst index 0f2399c99..03df201c5 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -43,6 +43,9 @@ Configuration variables: - **discovery_prefix** (*Optional*, string): The prefix to use for Home Assistant’s MQTT discovery. Should not contain trailing slash. Defaults to ``homeassistant``. +- **use_abbreviations** (*Optional*, boolean): Whether to use + `Abbreviations `__ + in discovery messages. Defaults to ``true``. - **topic_prefix** (*Optional*, string): The prefix used for all MQTT messages. Should not contain trailing slash. Defaults to ````. diff --git a/components/number/index.rst b/components/number/index.rst index 90d3110a3..c386efb32 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -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: diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index c2a9cb88a..47837be50 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -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 ` 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 ****************************************** diff --git a/components/select/index.rst b/components/select/index.rst index ec0bb3c5a..8ef140408 100644 --- a/components/select/index.rst +++ b/components/select/index.rst @@ -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: diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst index 43d5ac570..d50736681 100644 --- a/components/sensor/adc.rst +++ b/components/sensor/adc.rst @@ -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 `__. -To measure voltages higher than 1.1V, set ``attenuation`` to one of the `following values -`__: +To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation +`__ 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: diff --git a/components/sensor/cse7761.rst b/components/sensor/cse7761.rst new file mode 100644 index 000000000..999047aa8 --- /dev/null +++ b/components/sensor/cse7761.rst @@ -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 ` 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 `. +- **current_1** (*Optional*): Use the current value of the channel 1 in amperes. All options from + :ref:`Sensor `. +- **current_2** (*Optional*): Use the current value of the channel 2 in amperes. All options from + :ref:`Sensor `. +- **active_power_1** (*Optional*): Use the (active) power value of the channel 1 in watts. All options from + :ref:`Sensor `. +- **active_power_2** (*Optional*): Use the (active) power value of the channel 2 in watts. All options from + :ref:`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 ` if you want + to use multiple UART buses. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`cse7761/cse7761.h` +- :ghedit:`Edit` diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 28fe2b1b6..8e1f7a681 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -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: diff --git a/components/sensor/pmsx003.rst b/components/sensor/pmsx003.rst index f04b294f2..741362297 100644 --- a/components/sensor/pmsx003.rst +++ b/components/sensor/pmsx003.rst @@ -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 `. - **humidity** (*Optional*): Use the humidity value in % for the ``PMS5003T`` and ``PMS5003ST``. All options from :ref:`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 `. - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want to use multiple UART buses. diff --git a/components/sensor/rotary_encoder.rst b/components/sensor/rotary_encoder.rst index 33ac447ed..d2a4f96ee 100644 --- a/components/sensor/rotary_encoder.rst +++ b/components/sensor/rotary_encoder.rst @@ -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 `. + + - ``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 `): Actions to be performed when the knob is turned clockwise. See :ref:`sensor-rotary_encoder-triggers`. - **on_anticlockwise** (*Optional*, :ref:`Automation `): Actions to be performed when diff --git a/components/sensor/ruuvitag.rst b/components/sensor/ruuvitag.rst index 999262ec0..8c2a7be2e 100644 --- a/components/sensor/ruuvitag.rst +++ b/components/sensor/ruuvitag.rst @@ -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: diff --git a/components/sensor/tcs34725.rst b/components/sensor/tcs34725.rst index 983adfc6b..f3bedde2d 100644 --- a/components/sensor/tcs34725.rst +++ b/components/sensor/tcs34725.rst @@ -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``. diff --git a/components/sensor/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index f64940b17..0666c3950 100644 --- a/components/sensor/xiaomi_ble.rst +++ b/components/sensor/xiaomi_ble.rst @@ -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:: diff --git a/components/switch/index.rst b/components/switch/index.rst index 35daf5834..9d7d36215 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -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 `. .. _switch-toggle_action: diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst index dc354e67f..5a23856b5 100644 --- a/components/text_sensor/index.rst +++ b/components/text_sensor/index.rst @@ -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 `. Automations: diff --git a/components/uart.rst b/components/uart.rst index 3c30a1129..beb68c4da 100644 --- a/components/uart.rst +++ b/components/uart.rst @@ -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 ` 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`` 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 `` ()`` 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 -------- diff --git a/components/web_server.rst b/components/web_server.rst index 2355b0935..ebe569eef 100644 --- a/components/web_server.rst +++ b/components/web_server.rst @@ -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" diff --git a/conf.py b/conf.py index 565549670..d26a45b71 100644 --- a/conf.py +++ b/conf.py @@ -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. diff --git a/devices/sonoff.rst b/devices/sonoff.rst index 0c4004c49..9bb2eca46 100644 --- a/devices/sonoff.rst +++ b/devices/sonoff.rst @@ -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 ------------- diff --git a/guides/automations.rst b/guides/automations.rst index d81dbc715..9f88b36a0 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -561,6 +561,30 @@ Configuration variables: - **condition** (**Required**): The condition to check whether to execute. See :ref:`Conditions `. - **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 diff --git a/guides/creators.rst b/guides/creators.rst index 6c3027be3..12be14703 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -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 -------- diff --git a/images/cap1188.jpg b/images/cap1188.jpg new file mode 100644 index 000000000..d0009139f Binary files /dev/null and b/images/cap1188.jpg differ diff --git a/images/cse7761.svg b/images/cse7761.svg new file mode 100644 index 000000000..697d4d0fb --- /dev/null +++ b/images/cse7761.svg @@ -0,0 +1,49 @@ + + + + + + + + diff --git a/index.rst b/index.rst index 330bff03b..636519e82 100644 --- a/index.rst +++ b/index.rst @@ -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 diff --git a/svg2png/cse7761.png b/svg2png/cse7761.png new file mode 100644 index 000000000..60190d126 Binary files /dev/null and b/svg2png/cse7761.png differ