diff --git a/Doxygen b/Doxygen index 51eb7461d..8e52d50a3 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.11.0 # 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..b546480e1 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2021.10.3 +ESPHOME_REF = 2021.11.0 .PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/changelog-2021.11.0.png b/_static/changelog-2021.11.0.png new file mode 100644 index 000000000..466af830a Binary files /dev/null and b/_static/changelog-2021.11.0.png differ diff --git a/_static/version b/_static/version index b7d352674..c8039a3b6 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2021.10.3 \ No newline at end of file +2021.11.0 \ No newline at end of file diff --git a/changelog/2021.11.0.rst b/changelog/2021.11.0.rst new file mode 100644 index 000000000..b83debf53 --- /dev/null +++ b/changelog/2021.11.0.rst @@ -0,0 +1,289 @@ +ESPHome 2021.11.0 - 17th November 2021 +====================================== + +.. seo:: + :description: Changelog for ESPHome 2021.11.0. + :image: /_static/changelog-2021.11.0.png + :author: ESPHome + :author_twitter: @esphome_ + +.. imgtable:: + :columns: 4 + + CSE7761, components/sensor/cse7761, cse7761.svg + CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg + ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg + Improv via Serial, components/improv_serial, improv.svg + + +State of the Open Smart Home +---------------------------- + +Mark your calendar for the `State of the Open Smart Home `__ hosted by Nabu Casa, Home Assistant & ESPHome +and we’ll be joined by our friends from WLED and Z-Wave JS to talk about our work on making this vision a reality. + +Where: YouTube + +When: Saturday, December 11, at 11am PST / 8pm CET + +.. raw:: html + + + + +Improv via Serial +----------------- + +.. raw:: html + + + + + The demo does not work in your browser. Use Google Chrome or Microsoft Edge. + + +After we created :doc:`/components/esp32_improv`, we thought it might be a good idea to implement the same for serial connections. +See the docs here for :doc:`Improv via Serial ` and the +`website documentation `__ for implementing a client or implementing improv in other firmware. + +Entity Categories for Home Assistant +------------------------------------ + +Home Assistant 2021.11 added support for `Entity Categories `__ +and with this release certain ESPHome entites such as the restart switch and uptime sensors will have the config and diagnostic categories set respectively. +The category can be overridden by the user in the yaml configuration. + +Configuration URL +----------------- + +Another feature added to Home Assistant 2021.11 is the configuration URL. This allows for ESPHome devices to notify Home Assistant when the ``web_server`` is +enabled and there will be a button in the Home Assistant device page to link directly to the ``web_server`` UI for your ESPHome device. + +.. figure:: images/configuration-url.png + :align: center + :width: 50.0% + +Repeat Action +------------- + +:ghuser:`oxan` has implemented a ``repeat`` action for those that want to execute a list of actions x number of times without just copying and pasting them. + +Device name length +------------------ + +The maximum length of the device name has been limited to 31 characters to fall in line with standards and you will get +an error if you try to set a device name longer than that. + +BLE Sensor UUID changes +----------------------- + +A bug was introduced in 2021.9 with the UUIDs for the ``ble_client`` sensors being reversed incorrectly. This release flips them to be the correct way around +and you will need to reverse them in your YAML configuration. + +BH1750 +------ + +When using the default resolution of 0.5 for the BH17850, the result is now divided by 2 as per the finidings of the community. + + +Binary sensor device classes +---------------------------- + +:esphomepr:`2703` brings the binary sensor device classes up to date with Home Assistant, but this means that +the ``update`` ``device_class`` for binary sensors has been removed, you will get an error in your configuration if +you are using this device class. + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- Make per-loop display clearing optional :esphomepr:`2626` by :ghuser:`timn` (new-feature) +- Add Entity categories for Home Assistant :esphomepr:`2636` by :ghuser:`jesserockz` (new-feature) +- Add repeat action for automations :esphomepr:`2538` by :ghuser:`oxan` (new-feature) +- Neopixelbus redo method definitions :esphomepr:`2616` by :ghuser:`OttoWinter` (new-feature) (breaking-change) + +New Components +^^^^^^^^^^^^^^ + +- Feature/sensor cse7761 :esphomepr:`2546` by :ghuser:`berfenger` (new-integration) +- Add `esp32_camera_web_server:` to expose mjpg/jpg images :esphomepr:`2237` by :ghuser:`ayufan` (new-integration) +- CAP1188 Capacitive Touch Sensor Support :esphomepr:`2653` by :ghuser:`MrEditor97` (new-integration) +- Implement Improv via Serial component :esphomepr:`2423` by :ghuser:`jesserockz` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- TCS34725 BugFix and GA factor :esphomepr:`2445` by :ghuser:`razorback16` (breaking-change) +- Limit hostnames to 31 characters :esphomepr:`2531` by :ghuser:`oxan` (breaking-change) +- Move default build path to .esphome directory :esphomepr:`2586` by :ghuser:`OttoWinter` (breaking-change) +- ESP8266 disable PIO LDF :esphomepr:`2608` by :ghuser:`OttoWinter` (breaking-change) +- Remove autoload of xiaomi_ble and ruuvi_ble :esphomepr:`2617` by :ghuser:`spbrogan` (breaking-change) +- BH1750: Fix a too high default H-res2 mode value :esphomepr:`2536` by :ghuser:`kixtarter` (breaking-change) +- Add option to use MQTT abbreviations :esphomepr:`2641` by :ghuser:`paulmonigatti` (breaking-change) +- Add restore_mode to rotary_encoder :esphomepr:`2643` by :ghuser:`niklasweber` (breaking-change) +- Neopixelbus redo method definitions :esphomepr:`2616` by :ghuser:`OttoWinter` (new-feature) (breaking-change) +- Update device classes for binary sensors :esphomepr:`2703` by :ghuser:`lcavalli` (breaking-change) +- BLE_Sensor: Use as_reversed_hex_array to properly parse UUIDs after #1627 :esphomepr:`2737` by :ghuser:`tekmaven` (breaking-change) + +Beta Fixes +^^^^^^^^^^ + +- Fix template number initial value being NaN :esphomepr:`2692` by :ghuser:`jesserockz` +- [remote_transmitter] accurate pulse timing for ESP8266 :esphomepr:`2476` by :ghuser:`CarlosGS` +- Uart debugging support :esphomepr:`2478` by :ghuser:`mmakaay` +- Enable addressable light power supply based on raw values :esphomepr:`2690` by :ghuser:`oxan` +- Remove my.ha links from improv :esphomepr:`2695` by :ghuser:`jesserockz` +- Only allow prometheus when using arduino :esphomepr:`2697` by :ghuser:`jesserockz` +- Update device classes for binary sensors :esphomepr:`2703` by :ghuser:`lcavalli` (breaking-change) +- Bump ESPAsyncWebServer to 2.1.0 :esphomepr:`2686` by :ghuser:`jesserockz` +- Allow setting custom command_topic for Select and Number components :esphomepr:`2714` by :ghuser:`kbialek` +- Restore InterruptLock on wifi-less ESP8266 :esphomepr:`2712` by :ghuser:`oxan` +- Feed WDT between doing ESP32 touchpad measurements :esphomepr:`2720` by :ghuser:`oxan` +- RemoteTransmitter fix. Bug from version 2021.10. Some changes. :esphomepr:`2706` by :ghuser:`dudanov` +- Fix indentation of write_lambda for modbus_controller number :esphomepr:`2722` by :ghuser:`jesserockz` +- Remove unnecessary duplicate touch_pad_filter_start :esphomepr:`2724` by :ghuser:`Maelstrom96` +- Add zeroconf as a direct dependency and lock the version :esphomepr:`2729` by :ghuser:`jesserockz` +- Improv serial/checksum changes :esphomepr:`2731` by :ghuser:`jesserockz` +- Fix zeroconf time comparisons :esphomepr:`2733` by :ghuser:`jesserockz` +- BLE_Sensor: Use as_reversed_hex_array to properly parse UUIDs after #1627 :esphomepr:`2737` by :ghuser:`tekmaven` (breaking-change) +- Fix senseair component uart read timeout :esphomepr:`2658` by :ghuser:`rotarykite` + +All changes +^^^^^^^^^^^ + +- TCS34725 BugFix and GA factor :esphomepr:`2445` by :ghuser:`razorback16` (breaking-change) +- Change millis() to faster micros() for 3ms check in feed_wdt :esphomepr:`2492` by :ghuser:`CarlosGS` +- Add ESP32 IDF as a test env for PRs :esphomepr:`2494` by :ghuser:`mmakaay` +- use no hold master mode for si7021/htu21d :esphomepr:`2528` by :ghuser:`dmitriy5181` +- Bump pyyaml from 5.4.1 to 6.0 :esphomepr:`2521` by :ghuser:`dependabot[bot]` +- Clarify statement at the cmd wizard tool, for new users :esphomepr:`2519` by :ghuser:`CarlosGS` +- Continue ethernet setup if hostname fails :esphomepr:`2430` by :ghuser:`Tommatheussen` +- Bump aioesphomeapi from 9.1.5 to 10.0.0 :esphomepr:`2508` by :ghuser:`dependabot[bot]` +- Move TemplatableValue helper class to automation.h :esphomepr:`2511` by :ghuser:`oxan` +- [esp-idf fix] increase FreeRTOS ticker loop from 100Hz to 1kHz :esphomepr:`2527` by :ghuser:`CarlosGS` +- Bump pytest-asyncio from 0.15.1 to 0.16.0 :esphomepr:`2547` by :ghuser:`dependabot[bot]` +- [ESP32] ADC auto-range setting :esphomepr:`2541` by :ghuser:`CarlosGS` +- Bump paho-mqtt from 1.5.1 to 1.6.0 :esphomepr:`2568` by :ghuser:`dependabot[bot]` +- Fix ESP8266 dallas GPIO16 INPUT_PULLUP :esphomepr:`2581` by :ghuser:`OttoWinter` +- Fix platformio version in Dockerfile doesn't match requirements :esphomepr:`2582` by :ghuser:`OttoWinter` +- Fix platformio_install_deps no longer installing all lib_deps :esphomepr:`2584` by :ghuser:`OttoWinter` +- ESP32 ADC use factory calibration data :esphomepr:`2574` by :ghuser:`OttoWinter` +- Add mDNS config dump :esphomepr:`2576` by :ghuser:`mmakaay` +- Fix mDNS ESP8266 log not included :esphomepr:`2589` by :ghuser:`OttoWinter` +- Bump platformio from 5.2.1 to 5.2.2 :esphomepr:`2569` by :ghuser:`dependabot[bot]` +- Update docker base images :esphomepr:`2583` by :ghuser:`OttoWinter` +- Bump paho-mqtt from 1.6.0 to 1.6.1 :esphomepr:`2596` by :ghuser:`dependabot[bot]` +- Logging a proper url allows terminals to make it clickable :esphomepr:`2554` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 10.0.0 to 10.0.3 :esphomepr:`2595` by :ghuser:`dependabot[bot]` +- Bump tzlocal from 3.0 to 4.0.1 :esphomepr:`2553` by :ghuser:`dependabot[bot]` +- Add IDF support to dallas :esphomepr:`2578` by :ghuser:`OttoWinter` +- Limit hostnames to 31 characters :esphomepr:`2531` by :ghuser:`oxan` (breaking-change) +- Add EntityBase properties to ESP32 Camera :esphomepr:`2600` by :ghuser:`paulmonigatti` +- Move default build path to .esphome directory :esphomepr:`2586` by :ghuser:`OttoWinter` (breaking-change) +- ESP8266 disable PIO LDF :esphomepr:`2608` by :ghuser:`OttoWinter` (breaking-change) +- Switch issue-close-app to GH Actions and workflow cleanup :esphomepr:`2624` by :ghuser:`OttoWinter` +- relax max entities checking :esphomepr:`2629` by :ghuser:`martgras` +- Allow setting URL as platform_version :esphomepr:`2598` by :ghuser:`oxan` +- Constrain GH Actions workflows permissions :esphomepr:`2625` by :ghuser:`OttoWinter` +- Bump tzlocal from 4.0.1 to 4.0.2 :esphomepr:`2631` by :ghuser:`dependabot[bot]` +- Bump esptool from 3.1 to 3.2 :esphomepr:`2632` by :ghuser:`dependabot[bot]` +- Add publish_initial_value option to rotary encoder :esphomepr:`2503` by :ghuser:`niklasweber` +- Remove autoload of xiaomi_ble and ruuvi_ble :esphomepr:`2617` by :ghuser:`spbrogan` (breaking-change) +- Bump aioesphomeapi from 10.0.3 to 10.1.0 :esphomepr:`2638` by :ghuser:`dependabot[bot]` +- Expose web_server port via the API :esphomepr:`2467` by :ghuser:`alexiri` +- Allow cloning/fetching Github PR branches in external_components :esphomepr:`2639` by :ghuser:`jesserockz` +- use update_interval for sntp synchronization :esphomepr:`2563` by :ghuser:`martgras` +- Feature/sensor cse7761 :esphomepr:`2546` by :ghuser:`berfenger` (new-integration) +- Bump aioesphomeapi from 10.1.0 to 10.2.0 :esphomepr:`2642` by :ghuser:`dependabot[bot]` +- BH1750: Fix a too high default H-res2 mode value :esphomepr:`2536` by :ghuser:`kixtarter` (breaking-change) +- Bump tzlocal from 4.0.2 to 4.1 :esphomepr:`2645` by :ghuser:`dependabot[bot]` +- convert SCD30 into Component, polls dataready register :esphomepr:`2308` by :ghuser:`geoffrey-vl` +- Add option to use MQTT abbreviations :esphomepr:`2641` by :ghuser:`paulmonigatti` (breaking-change) +- Fix deep sleep invert_wakeup mode :esphomepr:`2644` by :ghuser:`OttoWinter` +- Expose webserver_port to the native API :esphomepr:`2640` by :ghuser:`jesserockz` +- Fix for noise in pulse_counter and duty_cycle components :esphomepr:`2646` by :ghuser:`CarlosGS` +- Bump black from 21.9b0 to 21.10b0 :esphomepr:`2650` by :ghuser:`dependabot[bot]` +- Add restore_mode to rotary_encoder :esphomepr:`2643` by :ghuser:`niklasweber` (breaking-change) +- Make per-loop display clearing optional :esphomepr:`2626` by :ghuser:`timn` (new-feature) +- Allow esp8266 to compile with no wifi :esphomepr:`2664` by :ghuser:`glmnet` +- Fix CRC error during DSMR chunked message reading :esphomepr:`2622` by :ghuser:`mmakaay` +- Add Entity categories for Home Assistant :esphomepr:`2636` by :ghuser:`jesserockz` (new-feature) +- Add SPI lib for ESP8266 and only add lib for ESP32 when using Arduino :esphomepr:`2677` by :ghuser:`mmakaay` +- Hotfix for encrypted DSMR regression :esphomepr:`2679` by :ghuser:`mmakaay` +- Add HA Entity Category support to MQTT :esphomepr:`2678` by :ghuser:`paulmonigatti` +- Fix gpio validation for esp32 variants :esphomepr:`2609` by :ghuser:`martgras` +- Fix when package url has no branch/ref :esphomepr:`2683` by :ghuser:`jesserockz` +- SSD1306_base -> Add support for 64x32 size and fix typo for flip functions :esphomepr:`2682` by :ghuser:`ychieux` +- Fix dashboard imports for adoption :esphomepr:`2684` by :ghuser:`jesserockz` +- Add `esp32_camera_web_server:` to expose mjpg/jpg images :esphomepr:`2237` by :ghuser:`ayufan` (new-integration) +- fix esp32 rmt receiver item array length :esphomepr:`2671` by :ghuser:`glmnet` +- Remote base add pronto protocol :esphomepr:`2619` by :ghuser:`cvwillegen` +- Set up output_switch at priority DATA instead of HARDWARE. :esphomepr:`2648` by :ghuser:`duncf` +- fix rc switch protocol 6 :esphomepr:`2672` by :ghuser:`glmnet` +- Remove "delay_microseconds_accurate()" and improve systemwide delayMicroseconds() :esphomepr:`2497` by :ghuser:`CarlosGS` +- modbus_controller: remove hard coded register size :esphomepr:`2654` by :ghuser:`martgras` +- CAP1188 Capacitive Touch Sensor Support :esphomepr:`2653` by :ghuser:`MrEditor97` (new-integration) +- Add missing hal.h include in esp32_camera_web_server :esphomepr:`2689` by :ghuser:`oxan` +- [ESP32 ADC] Add option for raw uncalibrated output :esphomepr:`2663` by :ghuser:`CarlosGS` +- Introduce parse_number() helper function :esphomepr:`2659` by :ghuser:`oxan` +- Add repeat action for automations :esphomepr:`2538` by :ghuser:`oxan` (new-feature) +- Neopixelbus redo method definitions :esphomepr:`2616` by :ghuser:`OttoWinter` (new-feature) (breaking-change) +- Introduce byteswap helpers :esphomepr:`2661` by :ghuser:`oxan` +- Max7219digit multiline :esphomepr:`1622` by :ghuser:`TVDLoewe` +- Clean-up string sanitization helpers :esphomepr:`2660` by :ghuser:`oxan` +- Introduce encode_value/decode_value() template functions :esphomepr:`2662` by :ghuser:`oxan` +- Make OTA function switchable in web_server component :esphomepr:`2685` by :ghuser:`lazlyhu` +- Implement Improv via Serial component :esphomepr:`2423` by :ghuser:`jesserockz` (new-integration) +- [ms5611]: Re-implement conversion from ADC readings to sensor values :esphomepr:`2665` by :ghuser:`anatoly-savchenkov` +- Fix template number initial value being NaN :esphomepr:`2692` by :ghuser:`jesserockz` +- [remote_transmitter] accurate pulse timing for ESP8266 :esphomepr:`2476` by :ghuser:`CarlosGS` +- Uart debugging support :esphomepr:`2478` by :ghuser:`mmakaay` +- Enable addressable light power supply based on raw values :esphomepr:`2690` by :ghuser:`oxan` +- Remove my.ha links from improv :esphomepr:`2695` by :ghuser:`jesserockz` +- Only allow prometheus when using arduino :esphomepr:`2697` by :ghuser:`jesserockz` +- Update device classes for binary sensors :esphomepr:`2703` by :ghuser:`lcavalli` (breaking-change) +- Bump ESPAsyncWebServer to 2.1.0 :esphomepr:`2686` by :ghuser:`jesserockz` +- Allow setting custom command_topic for Select and Number components :esphomepr:`2714` by :ghuser:`kbialek` +- Restore InterruptLock on wifi-less ESP8266 :esphomepr:`2712` by :ghuser:`oxan` +- Feed WDT between doing ESP32 touchpad measurements :esphomepr:`2720` by :ghuser:`oxan` +- RemoteTransmitter fix. Bug from version 2021.10. Some changes. :esphomepr:`2706` by :ghuser:`dudanov` +- Fix indentation of write_lambda for modbus_controller number :esphomepr:`2722` by :ghuser:`jesserockz` +- Remove unnecessary duplicate touch_pad_filter_start :esphomepr:`2724` by :ghuser:`Maelstrom96` +- Add zeroconf as a direct dependency and lock the version :esphomepr:`2729` by :ghuser:`jesserockz` +- Improv serial/checksum changes :esphomepr:`2731` by :ghuser:`jesserockz` +- Fix zeroconf time comparisons :esphomepr:`2733` by :ghuser:`jesserockz` +- BLE_Sensor: Use as_reversed_hex_array to properly parse UUIDs after #1627 :esphomepr:`2737` by :ghuser:`tekmaven` (breaking-change) +- Fix senseair component uart read timeout :esphomepr:`2658` by :ghuser:`rotarykite` + +Past Changelogs +--------------- + +.. toctree:: + :maxdepth: 1 + + 2021.10.0 + 2021.9.0 + 2021.8.0 + v1.20.0 + v1.19.0 + v1.18.0 + v1.17.0 + v1.16.0 + v1.15.0 + v1.14.0 + v1.13.0 + v1.12.0 + v1.11.0 + v1.10.0 + v1.9.0 + v1.8.0 + v1.7.0 diff --git a/changelog/images/configuration-url.png b/changelog/images/configuration-url.png new file mode 100644 index 000000000..61399d676 Binary files /dev/null and b/changelog/images/configuration-url.png differ diff --git a/changelog/index.rst b/changelog/index.rst index f8ffc1e7d..c3815151c 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2021.10.0.html + :url: /changelog/2021.11.0.html .. toctree:: :glob: 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..7c1f3e75b 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: 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/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..d22972b02 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.11" # The full version, including alpha/beta/rc tags. -release = "2021.10.3" +release = "2021.11.0" # 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/guides/supporters.rst b/guides/supporters.rst index 940438e72..32c745e37 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -55,6 +55,7 @@ Contributors - `aliktb (@aliktb) `__ - `Amish Vishwakarma (@amishv) `__ - `Jason Nader (@ammgws) `__ +- `anatoly-savchenkov (@anatoly-savchenkov) `__ - `andig (@andig) `__ - `András Bíró (@andrasbiro) `__ - `Andreas Hergert (@andreashergert1984) `__ @@ -87,6 +88,7 @@ Contributors - `Viktr (@BbIKTOP) `__ - `J. Nick Koston (@bdraco) `__ - `Ben Suffolk (@bensuffolk) `__ +- `Arturo Casal (@berfenger) `__ - `Ivan Bessarabov (@bessarabov) `__ - `besteru (@besteru) `__ - `Bierchermuesli (@Bierchermuesli) `__ @@ -106,6 +108,7 @@ Contributors - `Brian Hanifin (@brianhanifin) `__ - `brianrjones69 (@brianrjones69) `__ - `buddydvd (@buddydvd) `__ +- `bulburDE (@bulburDE) `__ - `buxtronix (@buxtronix) `__ - `bvansambeek (@bvansambeek) `__ - `bwente (@bwente) `__ @@ -123,6 +126,7 @@ Contributors - `John (@CircuitSetup) `__ - `Colby Rome (@cisasteelersfan) `__ - `Chris Debenham (@cjd) `__ +- `Clifford Roche (@cmroche) `__ - `CODeRUS (@CODeRUS) `__ - `Cody James (@codyjamestechnical) `__ - `John Coggeshall (@coogle) `__ @@ -193,6 +197,7 @@ Contributors - `Daniel Müller (@dtmuller) `__ - `dubit0 (@dubit0) `__ - `Sergey V. DUDANOV (@dudanov) `__ +- `Duncan Findlay (@duncf) `__ - `dyarkovoy (@dyarkovoy) `__ - `Dimitris Zervas (@dzervas) `__ - `dziobson (@dziobson) `__ @@ -246,6 +251,7 @@ Contributors - `frippe75 (@frippe75) `__ - `Fritz Mueller (@fritzm) `__ - `Marc Egli (@frog32) `__ +- `frspp (@frspp) `__ - `mr G1K (@G1K) `__ - `Aljaž Srebrnič (@g5pw) `__ - `Gabe Cook (@gabe565) `__ @@ -254,6 +260,7 @@ Contributors - `GeekVisit (@GeekVisit) `__ - `R Huish (@genestealer) `__ - `Geoff Davis (@geoffdavis) `__ +- `Geoffrey Van Landeghem (@geoffrey-vl) `__ - `Gérald Guiony (@gerald-guiony) `__ - `Gerard (@gerard33) `__ - `Giovanni (@Gio-dot) `__ @@ -290,6 +297,7 @@ Contributors - `MoA (@honomoa) `__ - `Hopperpop (@Hopperpop) `__ - `Yang Hau (@HowJMay) `__ +- `Antonio Vanegas (@hpsaturn) `__ - `hreintke (@hreintke) `__ - `Huub Eikens (@huubeikens) `__ - `Petr Urbánek (@HyperReap) `__ @@ -307,6 +315,7 @@ Contributors - `Ivan Shvedunov (@ivan4th) `__ - `Ivan Kravets (@ivankravets) `__ - `Ivo-tje (@Ivo-tje) `__ +- `Jan Harkes (@jaharkes) `__ - `Jakob Reiter (@jakommo) `__ - `James Braid (@jamesbraid) `__ - `James Gao (@jamesgao) `__ @@ -354,11 +363,13 @@ Contributors - `kalebzettl (@kalebzettl) `__ - `Karol Zlot (@karolzlot) `__ - `Krasimir Nedelchev (@kaykayehnn) `__ +- `Krzysztof Białek (@kbialek) `__ - `kbouchard111 (@kbouchard111) `__ - `Keith Burzinski (@kbx81) `__ - `Robert Kiss (@kepten) `__ - `Kevin O'Rourke (@kevinior) `__ - `kimonm (@kimonm) `__ +- `Ed (@kixtarter) `__ - `Kurt Kellner (@kkellner) `__ - `Klaas Schoute (@klaasnicolaas) `__ - `Klarstein (@Klarstein) `__ @@ -386,6 +397,8 @@ Contributors - `Steffen Weinreich (@lairsdragon) `__ - `Fredrik Lindqvist (@Landrash) `__ - `larsonmpdx (@larsonmpdx) `__ +- `Laszlo Gazdag (@lazlyhu) `__ +- `lcavalli (@lcavalli) `__ - `lein1013 (@lein1013) `__ - `Riku Lindblad (@lepinkainen) `__ - `Luca Gugelmann (@lgugelmann) `__ @@ -403,6 +416,7 @@ Contributors - `M95D (@M95D) `__ - `Marc-Antoine Courteau (@macourteau) `__ - `Massimiliano Ravelli (@madron) `__ +- `Alexandre-Jacques St-Jacques (@Maelstrom96) `__ - `magnus (@magnusja) `__ - `Magnus Øverli (@magnusoverli) `__ - `Major Péter (@majorpeter) `__ @@ -433,6 +447,7 @@ Contributors - `Me No Dev (@me-no-dev) `__ - `Alexandr Zarubkin (@me21) `__ - `Joseph Mearman (@Mearman) `__ +- `Bas (@Mechazawa) `__ - `Mechotronic (@Mechotronic) `__ - `MeIchthys (@meichthys) `__ - `meijerwynand (@meijerwynand) `__ @@ -460,6 +475,7 @@ Contributors - `monkeyclass (@monkeyclass) `__ - `Moritz Glöckl (@moritzgloeckl) `__ - `Matthew Pettitt (@mpettitt) `__ +- `Sam Hughes (@MrEditor97) `__ - `Mariusz Kryński (@mrk-its) `__ - `Ryan Matthews (@mrrsm) `__ - `MrZetor (@MrZetor) `__ @@ -472,6 +488,7 @@ Contributors - `Kevin Uhlir (@n0bel) `__ - `n8detar (@n8detar) `__ - `Erik Näsström (@Naesstrom) `__ +- `H. Árkosi Róbert (@nagyrobi) `__ - `Oskar Napieraj (@napieraj) `__ - `Nate Lust (@natelust) `__ - `ueno (@nayuta-ueno) `__ @@ -480,6 +497,7 @@ Contributors - `NMC (@ncareau) `__ - `Nebula (@nebula-it) `__ - `needspeed (@needspeed) `__ +- `NeoAcheron (@NeoAcheron) `__ - `nepozs (@nepozs) `__ - `Mike Meessen (@netmikey) `__ - `nickrout (@nickrout) `__ @@ -491,6 +509,7 @@ Contributors - `Zvonimir Haramustek (@nitko12) `__ - `Nikolay Kitanov (@nkitanov) `__ - `nldroid (@nldroid) `__ +- `Nicolas Liaudat (@nliaudat) `__ - `Niccolò Maggioni (@nmaggioni) `__ - `Alex (@nnmalex) `__ - `Jan Sandbrink (@NobodysNightmare) `__ @@ -591,18 +610,17 @@ Contributors - `romerod (@romerod) `__ - `Jérôme W. (@RomRider) `__ - `Robbie Page (@rorpage) `__ +- `rotarykite (@rotarykite) `__ - `rradar (@rradar) `__ - `rspaargaren (@rspaargaren) `__ - `Rubén G. (@rubengargar) `__ - `RubyBailey (@RubyBailey) `__ -- `rudgr (@rudgr) `__ - `Roberto Wagner (@rwagnervm) `__ - `rweather (@rweather) `__ - `ryanalden (@ryanalden) `__ - `Ryan Nazaretian (@ryannazaretian) `__ - `Silvio (@s1lvi0) `__ - `Jan Čermák (@sairon) `__ -- `samnewman86 (@samnewman86) `__ - `sascha lammers (@sascha432) `__ - `Sascha (@Scarbous) `__ - `Nils Schulte (@Schnilz) `__ @@ -615,13 +633,11 @@ Contributors - `sethcohn (@sethcohn) `__ - `Emanuele Tessore (@setola) `__ - `Abdelkader Boudih (@seuros) `__ -- `shaeed (@shaeed) `__ - `SharkSharp (@SharkSharp) `__ - `shbatm (@shbatm) `__ - `sherbang (@sherbang) `__ - `Shish (@shish) `__ - `SiliconAvatar (@SiliconAvatar) `__ -- `sillyfrog (@sillyfrog) `__ - `Derek Hageman (@Sizurka) `__ - `Stephen Tierney (@sjtrny) `__ - `Niklas Wagner (@Skaronator) `__ @@ -629,6 +645,7 @@ Contributors - `Luca Zimmermann (@soundstorm) `__ - `Sourabh Jaiswal (@sourabhjaiswal) `__ - `Philip Allgaier (@spacegaier) `__ +- `Sean Brogan (@spbrogan) `__ - `Stephan Peijnik-Steinwender (@speijnik) `__ - `spilin (@spilin) `__ - `square99 (@square99) `__ @@ -650,6 +667,7 @@ Contributors - `tantive (@tantive) `__ - `TBobsin (@TBobsin) `__ - `Team Super Panda (@teamsuperpanda) `__ +- `Ryan Hoffman (@tekmaven) `__ - `Tempura San (@tempura-san) `__ - `testbughub (@testbughub) `__ - `Greg Lincoln (@tetious) `__ @@ -666,11 +684,13 @@ Contributors - `Dominik Bruhn (@theomega) `__ - `Simon (@theOzzieRat) `__ - `Florian Gareis (@TheZoker) `__ +- `Thomas Hollstegge (@Tho85) `__ - `Thomas Klingbeil (@thomasklingbeil) `__ - `Thomas Dietrich (@ThomDietrich) `__ - `Andrew Thompson (@thompsa) `__ - `Tijs-B (@Tijs-B) `__ - `Aidan Timson (@timmo001) `__ +- `Tim Niemueller (@timn) `__ - `Tim P (@timpur) `__ - `Tim Savage (@timsavage) `__ - `Max Efremov (@Tmin10) `__ @@ -694,6 +714,7 @@ Contributors - `Tuckie (@Tuckie) `__ - `Alexey Vlasov (@turbulator) `__ - `Seppel Hardt (@tuxBurner) `__ +- `TVDLoewe (@TVDLoewe) `__ - `Thorsten von Eicken (@tve) `__ - `Tyler Menezes (@tylermenezes) `__ - `ukewea (@ukewea) `__ @@ -711,6 +732,7 @@ Contributors - `Ian Wells (@wellsi) `__ - `Werner Beroux (@wernight) `__ - `wifwucite (@wifwucite) `__ +- `wilberforce (@wilberforce) `__ - `Wilmar den Ouden (@wilmardo) `__ - `Emil Hesslow (@WizKid) `__ - `WJCarpenter (@wjcarpenter) `__ @@ -721,6 +743,7 @@ Contributors - `Mike (@xsnoopy) `__ - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ +- `ychieux (@ychieux) `__ - `Pavel (@yekm) `__ - `Atsuko Ito (@yottatsa) `__ - `Nico B (@youknow0) `__ @@ -734,4 +757,4 @@ Contributors - `ZTX18 (@ZTX18) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated October 27, 2021.* +*This page was last updated November 17, 2021.* 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