diff --git a/.github/workflows/component-image.yml b/.github/workflows/component-image.yml index 609a8aa315..6c46330277 100644 --- a/.github/workflows/component-image.yml +++ b/.github/workflows/component-image.yml @@ -48,7 +48,7 @@ jobs: component: ${{ needs.prepare.outputs.name }} - name: Upload - uses: actions/upload-artifact@v4.3.3 + uses: actions/upload-artifact@v4.3.4 id: upload-artifact with: name: ${{ needs.prepare.outputs.name }} diff --git a/Doxygen b/Doxygen index a840b136d9..da27607a96 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 = 2024.7.0-dev +PROJECT_NUMBER = 2024.9.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 40b3485065..ed0590e92e 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2024.6.4 +ESPHOME_REF = 2024.8.0 PAGEFIND_VERSION=1.1.0 PAGEFIND=pagefind NET_PAGEFIND=../pagefindbin/pagefind diff --git a/_redirects b/_redirects index 6964b22428..0b7f37536a 100644 --- a/_redirects +++ b/_redirects @@ -41,3 +41,4 @@ /cookbook/dual-r2-cover.html /cookbook/lambda_magic.html#one-button-cover-control 301 /ready-made/projects /projects/ 301 +/components/images /components/image 301 diff --git a/_static/changelog-2024.8.0.png b/_static/changelog-2024.8.0.png new file mode 100644 index 0000000000..cf40f46b68 Binary files /dev/null and b/_static/changelog-2024.8.0.png differ diff --git a/_static/version b/_static/version index 45336c3761..620b3657cd 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.7.0-dev \ No newline at end of file +2024.9.0-dev \ No newline at end of file diff --git a/automations/actions.rst b/automations/actions.rst index 1db6d04360..57f635f163 100644 --- a/automations/actions.rst +++ b/automations/actions.rst @@ -258,7 +258,7 @@ For example, the automation below will flash the light five times. Configuration variables: -- **count** (**Required**, int): The number of times the action should be repeated. +- **count** (**Required**, int): The number of times the action should be repeated. The counter is available to lambdas using the reserved word "iteration". - **then** (**Required**, :ref:`Action `): The action to repeat. .. _wait_until_action: diff --git a/changelog/2024.6.0.rst b/changelog/2024.6.0.rst index 39d0856374..16b92cba73 100644 --- a/changelog/2024.6.0.rst +++ b/changelog/2024.6.0.rst @@ -219,6 +219,20 @@ Release 2024.6.4 - June 27 - [ota-esphome] Merge configurations by port :esphomepr:`7001` by :ghuser:`kbx81` - Fix LEDC 100% is not 100% duty with ESP32 IDF :esphomepr:`6997` by :ghuser:`Links2004` +Release 2024.6.5 - July 3 +------------------------- + +- [mpr121] await register parented :esphomepr:`7014` by :ghuser:`jesserockz` +- Move some consts for #4585 :esphomepr:`7023` by :ghuser:`kbx81` +- [wifi] Only set default ttls phase 2 on esp-idf :esphomepr:`7033` by :ghuser:`jesserockz` + +Release 2024.6.6 - July 3 +------------------------- + +- Bump dockerfile dependencies :esphomepr:`7017` by :ghuser:`jesserockz` +- [docker] Bump versions inside armv7 block :esphomepr:`7022` by :ghuser:`jesserockz` +- [docker] Fix docker build error fall through :esphomepr:`7021` by :ghuser:`jesserockz` + Full list of changes -------------------- diff --git a/changelog/2024.7.0.rst b/changelog/2024.7.0.rst new file mode 100644 index 0000000000..fbb645854a --- /dev/null +++ b/changelog/2024.7.0.rst @@ -0,0 +1,226 @@ +ESPHome 2024.7.0 - 17th July 2024 +================================= + +.. seo:: + :description: Changelog for ESPHome 2024.7.0. + :author: Jesse Hills + :author_twitter: @jesserockz + + +microWakeWord +------------- + +The `micro_wake_word` component has been updated to "version 2". +This brings the capability to configure multiple models per device and has a ``vad`` model for +voice activity detection. + +The configuration has a breaking change to support these new features. + +.. code-block:: yaml + + micro_wake_word: + model: okay_nabu + +needs to be changed to the following: + +.. code-block:: yaml + + micro_wake_word: + models: + - okay_nabu + +Please see the :doc:`Documentation ` for the full configuration. + +Release 2024.7.1 - July 22 +-------------------------- + +- Prevent rename from deleting new config :esphomepr:`7104` by :ghuser:`acortelyou` +- [i2s_microphone] Partially revert #7092 so microphone volume doesn't change :esphomepr:`7109` by :ghuser:`kahrendt` +- [heatpumpir] Fix BK72XX Compile error with IRremoteESP8266 :esphomepr:`6955` by :ghuser:`dianlight` +- [http_request] allow basic auth for idf :esphomepr:`7086` by :ghuser:`oarcher` +- Fixes sml parser to process extended length lists with a number of items that is dividable by 16 :esphomepr:`6148` by :ghuser:`irgendwienet` + +Release 2024.7.2 - July 25 +-------------------------- + +- [http_request] Change default timeout to 4.5s :esphomepr:`7123` by :ghuser:`jesserockz` +- [http_request] Fix ESP-IDF follow redirect :esphomepr:`7101` by :ghuser:`dentra` + +Release 2024.7.3 - August 1 +--------------------------- + +- [pmwcs3] Add delay after sending REG_READ_START :esphomepr:`7130` by :ghuser:`thevogoncoder` +- Fix for Mitsubishi units that only support cooling :esphomepr:`7143` by :ghuser:`RubyBailey` +- [micro_wake_word] Fix VAD detection and modify detection computation :esphomepr:`7164` by :ghuser:`kahrendt` + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- [uptime] Add new timestamp type for uptime sensor :esphomepr:`7029` by :ghuser:`jesserockz` (new-feature) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- [dooya] Flip bit timings :esphomepr:`6947` by :ghuser:`jesserockz` (breaking-change) +- [modbus_text_sensor] new default ANSI encoding type :esphomepr:`6975` by :ghuser:`dudanov` (breaking-change) +- [micro_wake_word] Version 2 :esphomepr:`7032` by :ghuser:`kahrendt` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- helpers.cpp: Fix GLIBCXX_RELEASE check < 8 :esphomepr:`7062` by :ghuser:`ferbar` +- Fix pmsa003i cold boot marked as failed on ESP32 et al :esphomepr:`7064` by :ghuser:`z3liff` +- [http_request] Fix follow_redirects on arduino :esphomepr:`7054` by :ghuser:`guillempages` +- [ethernet] Fix compile warning for IPv6 :esphomepr:`7048` by :ghuser:`HeMan` +- Update webserver local assets to 20240704-081526 :esphomepr:`7041` by :ghuser:`esphomebot` +- Add braces to if statement to avoid compiler warning. :esphomepr:`7036` by :ghuser:`colmbuckley` +- [mitsubishi] Fix current temperature :esphomepr:`6909` by :ghuser:`ttaborda` +- [climate] fix dump output of unsupported features :esphomepr:`7005` by :ghuser:`dudanov` +- [climate-traits] improved performance :esphomepr:`7006` by :ghuser:`dudanov` +- Add default icon to restart button :esphomepr:`7076` by :ghuser:`leejoow` +- Add support for the Gree YAC1FB9 in climate_ir :esphomepr:`7056` by :ghuser:`topeju` +- add ESP32-C6 support to esp32_can :esphomepr:`7063` by :ghuser:`Adminius` +- Fix voice assistant crash when no speaker configured :esphomepr:`7075` by :ghuser:`kevdliu` +- Bump HeatpumpIR, add protocols, remove IRremoteESP8266 :esphomepr:`6996` by :ghuser:`nagyrobi` +- LTR390 separate ALS and UV gain and resolution :esphomepr:`7026` by :ghuser:`latonita` +- [improv_serial] Fix linker error created in #6998 :esphomepr:`7082` by :ghuser:`kbx81` +- [i2s_audio] Allow config for primary/secondary i2s mode :esphomepr:`7092` by :ghuser:`jesserockz` +- [micro_wake_word] Allow simpler model config :esphomepr:`7094` by :ghuser:`jesserockz` +- [ota] Print Arduino update errors :esphomepr:`7096` by :ghuser:`jesserockz` + +All changes +^^^^^^^^^^^ + +- [CI] Update device class sync script for update entities :esphomepr:`6895` by :ghuser:`jesserockz` +- X9c operation speed :esphomepr:`6898` by :ghuser:`oliverhihn` +- Bump actions/checkout from 4.1.6 to 4.1.7 :esphomepr:`6900` by :ghuser:`dependabot[bot]` +- [CI] Allow clang-tidy to see IDF components :esphomepr:`6903` by :ghuser:`kbx81` +- [esp32_camera] Use newer library version (for #6802) :esphomepr:`6809` by :ghuser:`kbx81` +- [micro_wake_word] Pin to esp-tflite-micro v1.3.1 :esphomepr:`6906` by :ghuser:`kbx81` +- VEML7700 Fix GCC build warnings :esphomepr:`6881` by :ghuser:`latonita` +- IDF 5 fixes for #6802 :esphomepr:`6911` by :ghuser:`kbx81` +- [CI-ethernet] Add/fix/organize/clean up ethernet component tests :esphomepr:`6916` by :ghuser:`kbx81` +- [CI-a01nyub] Consolidate test files :esphomepr:`6917` by :ghuser:`kbx81` +- [CI-api] Test fix for IDF 5+ :esphomepr:`6918` by :ghuser:`kbx81` +- [CI-http_request] Test fix for IDF 5+ :esphomepr:`6919` by :ghuser:`kbx81` +- [CI-wireguard] Test file consolidation :esphomepr:`6920` by :ghuser:`kbx81` +- [CI-esp32_hall] Remove IDF test :esphomepr:`6921` by :ghuser:`kbx81` +- [CI] Introduce testing for IDF 5 (and other arbitrary framework versions) :esphomepr:`6802` by :ghuser:`kbx81` +- uart: allow setting the UART id in final_validate_device_schema :esphomepr:`6923` by :ghuser:`paravoid` +- Bump peter-evans/create-pull-request from 6.0.5 to 6.1.0 :esphomepr:`6935` by :ghuser:`dependabot[bot]` +- Fix garbled graphics on LILYGO T4-S3 display :esphomepr:`6910` by :ghuser:`manuelkasper` +- Update cover.h for open() and close() compiler warnings :esphomepr:`6936` by :ghuser:`peter--s` +- [CI] Add debug component test for LibreTiny :esphomepr:`6945` by :ghuser:`kbx81` +- [dooya] Flip bit timings :esphomepr:`6947` by :ghuser:`jesserockz` (breaking-change) +- [qspi_amoled] Fix display remaining blank after update() before setup completion :esphomepr:`6958` by :ghuser:`manuelkasper` +- Bump docker/build-push-action from 6.0.1 to 6.1.0 in /.github/actions/build-image :esphomepr:`6962` by :ghuser:`dependabot[bot]` +- Synchronise Device Classes from Home Assistant :esphomepr:`6966` by :ghuser:`esphomebot` +- [qspi_amoled] Fix clear/fill with rotation :esphomepr:`6960` by :ghuser:`manuelkasper` +- [script] allow template parameters :esphomepr:`6972` by :ghuser:`ssieb` +- [haier] climate ID auto generation :esphomepr:`6949` by :ghuser:`dudanov` +- [core] Add script to extract actions, conditions, and pin_providers :esphomepr:`6929` by :ghuser:`jesserockz` +- [external_files] Move common ``download_content`` function to ``external_files.py`` :esphomepr:`6982` by :ghuser:`jesserockz` +- Do not build mDNS when mDNS is disabled via yaml :esphomepr:`6979` by :ghuser:`Links2004` +- Bump HeatpumpIR and IRremoteESP8266 :esphomepr:`6948` by :ghuser:`nagyrobi` +- [CI] Add more mdns and safe_mode tests :esphomepr:`6990` by :ghuser:`kbx81` +- [CI] Remove old test yamls from CI runs :esphomepr:`6991` by :ghuser:`kbx81` +- [CI] Update tests to run against IDF 5.1 :esphomepr:`6992` by :ghuser:`kbx81` +- Bump docker/build-push-action from 6.1.0 to 6.2.0 in /.github/actions/build-image :esphomepr:`6999` by :ghuser:`dependabot[bot]` +- [tuya] implement command 0x22 - datapoint-async :esphomepr:`6980` by :ghuser:`christiaanderidder` +- Allow wireguard to bind to PPP interface :esphomepr:`6989` by :ghuser:`droscy` +- [modbus_text_sensor] new default ANSI encoding type :esphomepr:`6975` by :ghuser:`dudanov` (breaking-change) +- [CI] Remove old test yaml files :esphomepr:`7002` by :ghuser:`kbx81` +- Revert "[CI] Update tests to run against IDF 5.1" :esphomepr:`7003` by :ghuser:`jesserockz` +- Enable devcontainer linters :esphomepr:`7019` by :ghuser:`orland0m` +- 'uart' and 'improv_serial' need to understand non-UART logger configurations :esphomepr:`6998` by :ghuser:`kpfleming` +- Make crc8 const-correct :esphomepr:`7027` by :ghuser:`nattgris` +- [CI] Run all tests when a base test changes :esphomepr:`7010` by :ghuser:`kbx81` +- [CI] Update tests to run against IDF 5.1 :esphomepr:`7011` by :ghuser:`kbx81` +- [uptime] Add new timestamp type for uptime sensor :esphomepr:`7029` by :ghuser:`jesserockz` (new-feature) +- Fix compile errors on ESP32-C6 with W5500 SPI ethernet :esphomepr:`7030` by :ghuser:`LeeHanYeong` +- Bump docker/setup-buildx-action from 3.3.0 to 3.4.0 :esphomepr:`7043` by :ghuser:`dependabot[bot]` +- Bump docker/build-push-action from 6.2.0 to 6.3.0 in /.github/actions/build-image :esphomepr:`7038` by :ghuser:`dependabot[bot]` +- Bump docker/setup-qemu-action from 3.0.0 to 3.1.0 :esphomepr:`7039` by :ghuser:`dependabot[bot]` +- Bump actions/upload-artifact from 4.3.3 to 4.3.4 :esphomepr:`7047` by :ghuser:`dependabot[bot]` +- Bump actions/download-artifact from 4.1.7 to 4.1.8 :esphomepr:`7046` by :ghuser:`dependabot[bot]` +- Fix display of update state in webinterfae :esphomepr:`7045` by :ghuser:`leejoow` +- Haier component update to support more protocol variations :esphomepr:`7040` by :ghuser:`paveldn` +- Don't test for IPv6 addresses when min_ipv6_addr_count is 0 :esphomepr:`7037` by :ghuser:`colmbuckley` +- [CI] Allow running specific target test(s) only :esphomepr:`7051` by :ghuser:`tomaszduda23` +- Bump actions/setup-python from 5.1.0 to 5.1.1 in /.github/actions/restore-python :esphomepr:`7071` by :ghuser:`dependabot[bot]` +- Fix RC Switch protocol not transmitting correctly via IR :esphomepr:`5411` by :ghuser:`michd` +- [micro_wake_word] Version 2 :esphomepr:`7032` by :ghuser:`kahrendt` (breaking-change) +- UART component support added for host platform :esphomepr:`6912` by :ghuser:`paveldn` +- Configure ap ip for RP2040 :esphomepr:`7065` by :ghuser:`HeMan` +- helpers.cpp: Fix GLIBCXX_RELEASE check < 8 :esphomepr:`7062` by :ghuser:`ferbar` +- Fix pmsa003i cold boot marked as failed on ESP32 et al :esphomepr:`7064` by :ghuser:`z3liff` +- [http_request] Fix follow_redirects on arduino :esphomepr:`7054` by :ghuser:`guillempages` +- [ethernet] Fix compile warning for IPv6 :esphomepr:`7048` by :ghuser:`HeMan` +- Update webserver local assets to 20240704-081526 :esphomepr:`7041` by :ghuser:`esphomebot` +- Add braces to if statement to avoid compiler warning. :esphomepr:`7036` by :ghuser:`colmbuckley` +- [mitsubishi] Fix current temperature :esphomepr:`6909` by :ghuser:`ttaborda` +- [climate] fix dump output of unsupported features :esphomepr:`7005` by :ghuser:`dudanov` +- [climate-traits] improved performance :esphomepr:`7006` by :ghuser:`dudanov` +- Add default icon to restart button :esphomepr:`7076` by :ghuser:`leejoow` +- Add support for the Gree YAC1FB9 in climate_ir :esphomepr:`7056` by :ghuser:`topeju` +- add ESP32-C6 support to esp32_can :esphomepr:`7063` by :ghuser:`Adminius` +- Fix voice assistant crash when no speaker configured :esphomepr:`7075` by :ghuser:`kevdliu` +- Bump HeatpumpIR, add protocols, remove IRremoteESP8266 :esphomepr:`6996` by :ghuser:`nagyrobi` +- LTR390 separate ALS and UV gain and resolution :esphomepr:`7026` by :ghuser:`latonita` +- [improv_serial] Fix linker error created in #6998 :esphomepr:`7082` by :ghuser:`kbx81` +- [i2s_audio] Allow config for primary/secondary i2s mode :esphomepr:`7092` by :ghuser:`jesserockz` +- [micro_wake_word] Allow simpler model config :esphomepr:`7094` by :ghuser:`jesserockz` +- [ota] Print Arduino update errors :esphomepr:`7096` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :doc:`2024.6.0` +- :doc:`2024.5.0` +- :doc:`2024.4.0` +- :doc:`2024.3.0` +- :doc:`2024.2.0` +- :doc:`2023.12.0` +- :doc:`2023.11.0` +- :doc:`2023.10.0` +- :doc:`2023.9.0` +- :doc:`2023.8.0` +- :doc:`2023.7.0` +- :doc:`2023.6.0` +- :doc:`2023.5.0` +- :doc:`2023.4.0` +- :doc:`2023.3.0` +- :doc:`2023.2.0` +- :doc:`2022.12.0` +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/changelog/2024.8.0.rst b/changelog/2024.8.0.rst new file mode 100644 index 0000000000..93aef64109 --- /dev/null +++ b/changelog/2024.8.0.rst @@ -0,0 +1,301 @@ +ESPHome 2024.8.0 - 21st August 2024 +=================================== + +.. seo:: + :description: Changelog for ESPHome 2024.8.0. + :image: /_static/changelog-2024.8.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + LVGL Graphics, components/lvgl/index, lvgl.png + Online Image, components/online_image, image-sync-outline.svg, dark-invert + APDS9306, components/sensor/apds9306, apds9306.png + + Home Assistant Number, components/number/homeassistant, home-assistant.svg, dark-invert + Home Assistant Switch, components/switch/homeassistant, home-assistant.svg, dark-invert + BME68x via BSEC2, components/sensor/bme68x_bsec2, bme680.jpg + + M5Stack Unit 8 Angle, components/sensor/m5stack_8angle, m5stack_8angle.png + LYWSD02MMC, components/sensor/xiaomi_ble.html#lywsd02mmc, xiaomi_mijia_logo.jpg + +Light and Versatile Embedded Graphics Library +--------------------------------------------- + +Or LVGL for short, has been worked on by :ghuser:`clydebarrow` (and multiple other users doing testing and documentation etc) +for quite some time now and is finally ready for releasing this month. It is a very powerful graphics library that +is able to be configured almost completely in YAML (There are some places that will require lambdas/c++). +The :doc:`documentation ` is very extensive and hopefully we see +some awesome dashboards being made with it. + +Online Image +------------ + +:ghuser:`guillempages` created a new :doc:`online_image ` component that allows your ESPHome device to download +images from the internet while it is running and show them on your display. This can also be combined with the new LVGL +component to show dynamic images for your dashboard. + +Home Assistant Switch & Number +------------------------------ + +New platforms have been added for ``switch`` and ``number`` to allow importing of state and controlling +of switches and numbers that exist in Home Assistant (or another device via Home Assistant). +This greatly simplifies controlling remote entities and will hopefully be extended to other platforms. + +Thank you for your support +-------------------------- + +We would like to thank all Home Assistant Cloud subscribers for their support. It allows `Nabu Casa `__ to +employ two developers to maintain and further develop the ESPHome project. + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- [update] Implement ``update.perform`` action and ``update.is_available`` condition :esphomepr:`7165` by :ghuser:`jesserockz` (new-feature) + +New Components +^^^^^^^^^^^^^^ + +- Feature/m5angle8: Add support for m5angle8 input device :esphomepr:`6799` by :ghuser:`rnauber` (new-integration) +- APDS9306 Ambient Light Sensor :esphomepr:`6709` by :ghuser:`aodrenah` (new-integration) +- [lvgl] base implementation :esphomepr:`7116` by :ghuser:`clydebarrow` (new-integration) +- Add runtime online image support :esphomepr:`4710` by :ghuser:`guillempages` (new-integration) +- [bme68x_bsec2_i2c] BME68X Temperature+Pressure+Humidity+Gas Sensor via BSEC2 :esphomepr:`4585` by :ghuser:`neffs` (new-integration) +- Add support for LYWSD02MMC Xiaomi device :esphomepr:`7080` by :ghuser:`juanluss31` (new-integration) + +New Platforms +^^^^^^^^^^^^^ + +- [homeassistant] Native switch entity import and control :esphomepr:`7018` by :ghuser:`Links2004` (new-platform) +- [homeassistant] Native number entity import and control :esphomepr:`6455` by :ghuser:`landonr` (new-platform) +- Correct offset calibration :esphomepr:`7228` by :ghuser:`descipher` (new-platform) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Remove deprecated argument parser :esphomepr:`7151` by :ghuser:`jesserockz` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- remove extra number from pronto :esphomepr:`7263` by :ghuser:`ssieb` +- [api] Bump noise-c library version :esphomepr:`7288` by :ghuser:`clydebarrow` +- fix some small rtttl issues :esphomepr:`6817` by :ghuser:`nielsnl68` +- Fix overflow in ESPColorCorrection object :esphomepr:`7268` by :ghuser:`g-kiss` +- [validation] Allow ``maybe_simple_value`` to not have default key in complex value :esphomepr:`7294` by :ghuser:`jesserockz` +- [network] Always allow ``enable_ipv6: false`` :esphomepr:`7291` by :ghuser:`dwmw2` +- Revert "[validation] Allow ``maybe_simple_value`` to not have default key in complex value" :esphomepr:`7305` by :ghuser:`jesserockz` +- [lvgl] Bug fixes :esphomepr:`7300` by :ghuser:`clydebarrow` +- [speaker] Fix header includes :esphomepr:`7304` by :ghuser:`nielsnl68` +- [microphone] Fix header includes :esphomepr:`7310` by :ghuser:`jesserockz` +- Fix RP2040 Neopixel flickering issue :esphomepr:`7307` by :ghuser:`deCodeIt` +- add the ability to add more idf components to an existing setup :esphomepr:`7302` by :ghuser:`nielsnl68` +- Fix waveshare 2.13" epaper stride calculation error :esphomepr:`7303` by :ghuser:`serialx` +- [rtttl] fix STOPPED state :esphomepr:`7323` by :ghuser:`NewoPL` + +All changes +^^^^^^^^^^^ + +- [wifi] Fix EAP for IDF 5.1+, add test :esphomepr:`7061` by :ghuser:`kbx81` +- jsn_sr04t component: AJ_SR04M compatibility mode in checksum calculation :esphomepr:`7044` by :ghuser:`soeffi` +- [CI] compile entire web_server during tests :esphomepr:`7084` by :ghuser:`tomaszduda23` +- [CI] Add more ``improv_serial`` tests :esphomepr:`7081` by :ghuser:`kbx81` +- Bump docker/build-push-action from 6.3.0 to 6.4.0 in /.github/actions/build-image :esphomepr:`7089` by :ghuser:`dependabot[bot]` +- [CI] add web_server v1 test :esphomepr:`7090` by :ghuser:`tomaszduda23` +- [wifi] Hostname may not be set as expected on Arduino platform :esphomepr:`7050` by :ghuser:`NewoPL` +- Add host uart support for MacOS :esphomepr:`7095` by :ghuser:`clydebarrow` +- Bump docker/build-push-action from 6.4.0 to 6.4.1 in /.github/actions/build-image :esphomepr:`7102` by :ghuser:`dependabot[bot]` +- [code-quality] Add some ruff configuration :esphomepr:`7103` by :ghuser:`jesserockz` +- [web_server] move v1 code to separate file :esphomepr:`7091` by :ghuser:`tomaszduda23` +- [validation] Add ``host`` to ``require_framework_version`` :esphomepr:`7107` by :ghuser:`jesserockz` +- [code-quality] Tidy up some duplicate CONFIG_SCHEMA assignments :esphomepr:`7106` by :ghuser:`jesserockz` +- Move MQTT ip discovery to deticated config option. :esphomepr:`6673` by :ghuser:`Links2004` +- Feature/m5angle8: Add support for m5angle8 input device :esphomepr:`6799` by :ghuser:`rnauber` (new-integration) +- use cache to build tests for compoenents :esphomepr:`7059` by :ghuser:`tomaszduda23` +- [modbus_controller] Add on_command_sent trigger :esphomepr:`7078` by :ghuser:`leejoow` +- [ili9xxx] Rework delay handling :esphomepr:`7115` by :ghuser:`clydebarrow` +- Inherit `esp32_ble_beacon` from `esp32_ble` :esphomepr:`6908` by :ghuser:`jpbede` +- APDS9306 Ambient Light Sensor :esphomepr:`6709` by :ghuser:`aodrenah` (new-integration) +- Bump docker/build-push-action from 6.4.1 to 6.5.0 in /.github/actions/build-image :esphomepr:`7119` by :ghuser:`dependabot[bot]` +- Bump docker/setup-qemu-action from 3.1.0 to 3.2.0 :esphomepr:`7120` by :ghuser:`dependabot[bot]` +- Bump docker/login-action from 3.2.0 to 3.3.0 :esphomepr:`7121` by :ghuser:`dependabot[bot]` +- Bump docker/setup-buildx-action from 3.4.0 to 3.5.0 :esphomepr:`7122` by :ghuser:`dependabot[bot]` +- [fan] fix initial FanCall to properly set speed :esphomepr:`7113` by :ghuser:`kr0ner` +- Added ruff to pre-commit hooks :esphomepr:`7124` by :ghuser:`clydebarrow` +- Update webserver local assets to 20240724-013115 :esphomepr:`7126` by :ghuser:`esphomebot` +- [http_request] Allow configure buffer size on ESP-IDF :esphomepr:`7125` by :ghuser:`dentra` +- Give more info on import errors. :esphomepr:`7128` by :ghuser:`clydebarrow` +- [lvgl] base implementation :esphomepr:`7116` by :ghuser:`clydebarrow` (new-integration) +- Bump aioesphomeapi to 24.6.2 and cryptography to 43.0.0 :esphomepr:`7131` by :ghuser:`bdraco` +- [dependabot] Group docker action bumps into single PR :esphomepr:`7133` by :ghuser:`jesserockz` +- Add ``--version`` handler to cli :esphomepr:`7150` by :ghuser:`jesserockz` +- [code-quality] Organise ethernet related imports :esphomepr:`7152` by :ghuser:`jesserockz` +- [code-quality] Organise wifi related imports :esphomepr:`7153` by :ghuser:`jesserockz` +- [code-quality] Organise core imports :esphomepr:`7149` by :ghuser:`jesserockz` +- Remove deprecated argument parser :esphomepr:`7151` by :ghuser:`jesserockz` (breaking-change) +- Move ``CONF_ON_ERROR`` to const.py :esphomepr:`7156` by :ghuser:`jesserockz` +- [code-quality] Organise esp32 imports :esphomepr:`7154` by :ghuser:`jesserockz` +- Add microAmp and milliAmp to defined units :esphomepr:`7157` by :ghuser:`FreeBear-nc` +- Bump docker/setup-buildx-action from 3.5.0 to 3.6.1 in the docker-actions group :esphomepr:`7159` by :ghuser:`dependabot[bot]` +- LVGL stage 2 :esphomepr:`7129` by :ghuser:`clydebarrow` +- [pid] Add get_min_integral() and get_max_integral() :esphomepr:`7162` by :ghuser:`FreeBear-nc` +- [code-quality] Organise bluetooth related imports :esphomepr:`7155` by :ghuser:`jesserockz` +- http_request watchdog as a component :esphomepr:`7161` by :ghuser:`oarcher` +- [touchscreen] Allow binary sensor to have multiple pages in config :esphomepr:`7112` by :ghuser:`jesserockz` +- [matrix_keypad] Add `pin->setup()` to rows and cols :esphomepr:`7163` by :ghuser:`AAllport` +- [update] Implement ``update.perform`` action and ``update.is_available`` condition :esphomepr:`7165` by :ghuser:`jesserockz` (new-feature) +- [lvgl] PR stage 3 :esphomepr:`7160` by :ghuser:`clydebarrow` +- [api] ``homeassistant.action`` replaces ``homeassistant.service`` :esphomepr:`7171` by :ghuser:`jesserockz` +- ade7953_spi wrong size specified in read_array call :esphomepr:`7172` by :ghuser:`SimoPk` +- Bump improv library to 1.2.4 :esphomepr:`7174` by :ghuser:`jesserockz` +- Implement 'round to nearest multiple' filter :esphomepr:`7142` by :ghuser:`MrEbbinghaus` +- git ignore managed_components :esphomepr:`7180` by :ghuser:`oarcher` +- [core] Eliminate nuisance messages from `build_codeowners` :esphomepr:`7185` by :ghuser:`clydebarrow` +- [code-quality] More portable shebangs :esphomepr:`7189` by :ghuser:`jesserockz` +- Add support for doing update entity refresh/check via API. :esphomepr:`7190` by :ghuser:`jesserockz` +- [lvgl] Stage 4 :esphomepr:`7166` by :ghuser:`clydebarrow` +- [esp32_improv] Update Improv library to reference new repo/version :esphomepr:`7195` by :ghuser:`kahrendt` +- hydreon_rgxx: Fix parsing of data line :esphomepr:`7192` by :ghuser:`domob1812` +- Remove outdated version block :esphomepr:`7177` by :ghuser:`tomaszduda23` +- [lvgl] Stage 5 :esphomepr:`7191` by :ghuser:`clydebarrow` +- socket: socket::set_sockaddr() for IPv4 addresses in IPv6 builds :esphomepr:`7196` by :ghuser:`dwmw2` +- Adds MQTT component to Alarm Control panel component :esphomepr:`7188` by :ghuser:`heythisisnate` +- [lvgl] Final stage :esphomepr:`7184` by :ghuser:`clydebarrow` +- Move ``CONF_BACKGROUND_COLOR`` and ``CONF_FOREGROUND_COLOR`` to const.py :esphomepr:`7202` by :ghuser:`jesserockz` +- [helpers] Set default flags of ExternalRAMAllocator to ALLOW_FAILURE :esphomepr:`7201` by :ghuser:`jesserockz` +- Add runtime online image support :esphomepr:`4710` by :ghuser:`guillempages` (new-integration) +- Update i2s_audio_speaker.cppi2s_audio/speaker: Fix fallthrough compiler warning :esphomepr:`7167` by :ghuser:`Mimoja` +- Move CONF_ITEMS/CONF_FONT/CONF_TEXT to const.py :esphomepr:`7204` by :ghuser:`jesserockz` +- [lvgl] Fix compile error when using encoder with buttons only. :esphomepr:`7203` by :ghuser:`clydebarrow` +- Revert "Add null GPIO pin " :esphomepr:`6621` by :ghuser:`jesserockz` +- [remote_transmitter] Change default carrier_frequency to valid value :esphomepr:`7176` by :ghuser:`iannisimo` +- [code-quality] Organise script imports :esphomepr:`7198` by :ghuser:`jesserockz` +- [max31856] Use cv.frequency as validator :esphomepr:`7212` by :ghuser:`jesserockz` +- [code-quality] Organise base entities imports :esphomepr:`7208` by :ghuser:`tomaszduda23` +- [spi] Remove ``SPIDelegateDummy`` :esphomepr:`7215` by :ghuser:`jesserockz` +- [code-quality] Apply ruff linting suggestions :esphomepr:`7206` by :ghuser:`tomaszduda23` +- [code-quality] Organise logger imports :esphomepr:`7205` by :ghuser:`tomaszduda23` +- [code-quality] Apply ruff linting suggestions to core :esphomepr:`7207` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy sprinkler :esphomepr:`7222` by :ghuser:`tomaszduda23` +- [code-quality] __attribute__((packed)) :esphomepr:`7221` by :ghuser:`tomaszduda23` +- hx711: Check for DOUT going high after a reading :esphomepr:`7214` by :ghuser:`dwmw2` +- [mqtt] Add extended device info :esphomepr:`7194` by :ghuser:`dentra` +- [code-quality] NOLINT readability-identifier-naming :esphomepr:`7220` by :ghuser:`tomaszduda23` +- [code-quality] Organise time imports :esphomepr:`7219` by :ghuser:`tomaszduda23` +- [lvgl] Fix set state on updates :esphomepr:`7227` by :ghuser:`clydebarrow` +- add missing override :esphomepr:`7231` by :ghuser:`tomaszduda23` +- Add text_align_to_string :esphomepr:`7243` by :ghuser:`MrMDavidson` +- [sml] Fixed crashing sml parser :esphomepr:`7235` by :ghuser:`eNBeWe` +- Allow project name and version as improv_serial identity :esphomepr:`7248` by :ghuser:`AzonInc` +- [lvgl] Implement default group for encoders :esphomepr:`7242` by :ghuser:`clydebarrow` +- [bme68x_bsec2_i2c] BME68X Temperature+Pressure+Humidity+Gas Sensor via BSEC2 :esphomepr:`4585` by :ghuser:`neffs` (new-integration) +- [code-quality] clang-tidy media_player :esphomepr:`7238` by :ghuser:`tomaszduda23` +- Bump docker/build-push-action from 6.5.0 to 6.6.1 in /.github/actions/build-image :esphomepr:`7232` by :ghuser:`dependabot[bot]` +- fix build error :esphomepr:`7229` by :ghuser:`tomaszduda23` +- adjust to new python pre-commit hooks :esphomepr:`7178` by :ghuser:`tomaszduda23` +- add windows script/setup.bat :esphomepr:`7140` by :ghuser:`nielsnl68` +- [code-quality] add NOLINT haier_base :esphomepr:`7236` by :ghuser:`tomaszduda23` +- [code-quality] clang-tidy bedjet :esphomepr:`7251` by :ghuser:`tomaszduda23` +- fix name conflict with zephyr macro :esphomepr:`7252` by :ghuser:`tomaszduda23` +- [code-quality] Apply ruff linting suggestions :esphomepr:`7239` by :ghuser:`tomaszduda23` +- Add support for LYWSD02MMC Xiaomi device :esphomepr:`7080` by :ghuser:`juanluss31` (new-integration) +- [code-quality] fix clang-tidy web server :esphomepr:`7230` by :ghuser:`tomaszduda23` +- [test][web_server] Rejig test for v3 :esphomepr:`7110` by :ghuser:`RFDarter` +- [api] Error log when NONE Update command is sent :esphomepr:`7247` by :ghuser:`oarcher` +- [api] Add new flag to request state/attribute once from HA only :esphomepr:`7258` by :ghuser:`jesserockz` +- [homeassistant] Add ``HOME_ASSISTANT_IMPORT_CONTROL_SCHEMA`` :esphomepr:`7259` by :ghuser:`jesserockz` +- [const] Add some units for future use and adjust case :esphomepr:`7260` by :ghuser:`nkinnan` +- [online_image] add option to show placeholder while downloading :esphomepr:`7083` by :ghuser:`guillempages` +- [lvgl] Add initial_focus for encoders :esphomepr:`7256` by :ghuser:`clydebarrow` +- [code-quality] fix order in esphome/const.py :esphomepr:`7267` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy network :esphomepr:`7266` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy core optional :esphomepr:`7265` by :ghuser:`tomaszduda23` +- [code-quality] Fix variable naming in base_light_effects :esphomepr:`7237` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy mqtt :esphomepr:`7253` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy wifi related :esphomepr:`7254` by :ghuser:`tomaszduda23` +- Bump docker/build-push-action from 6.6.1 to 6.7.0 in /.github/actions/build-image :esphomepr:`7269` by :ghuser:`dependabot[bot]` +- [CI] Dont run full CI on ``build-image`` action changes :esphomepr:`7270` by :ghuser:`jesserockz` +- Implement ByteBuffer :esphomepr:`6878` by :ghuser:`clydebarrow` +- Add min and max brightness parameters for Light dim_relative Action :esphomepr:`6971` by :ghuser:`PaoloTK` +- [homeassistant] Native switch entity import and control :esphomepr:`7018` by :ghuser:`Links2004` (new-platform) +- [homeassistant] Native number entity import and control :esphomepr:`6455` by :ghuser:`landonr` (new-platform) +- [lvgl] Rework events to avoid feedback loops :esphomepr:`7262` by :ghuser:`clydebarrow` +- Add `color_filter_opa` style property :esphomepr:`7276` by :ghuser:`clydebarrow` +- [code-quality] fix clang-tidy wake_on_lan :esphomepr:`7275` by :ghuser:`tomaszduda23` +- [code-quality] fix readability-braces-around-statements :esphomepr:`7273` by :ghuser:`tomaszduda23` +- [mqtt] fix missing initializer in MQTTClientComponent::disable_discovery :esphomepr:`7271` by :ghuser:`oarcher` +- [code-quality] fix readability-named-parameter :esphomepr:`7272` by :ghuser:`tomaszduda23` +- support illuminance for airthings wave plus device :esphomepr:`5203` by :ghuser:`MadMonkey87` +- [micro_wake_word] Bump ESPMicroSpeechFeatures version to 1.1.0 :esphomepr:`7249` by :ghuser:`kahrendt` +- Implement the finish() method and action. implement the is_stopped condition :esphomepr:`7255` by :ghuser:`nielsnl68` +- Correct offset calibration :esphomepr:`7228` by :ghuser:`descipher` (new-platform) +- remove extra number from pronto :esphomepr:`7263` by :ghuser:`ssieb` +- [api] Bump noise-c library version :esphomepr:`7288` by :ghuser:`clydebarrow` +- fix some small rtttl issues :esphomepr:`6817` by :ghuser:`nielsnl68` +- Fix overflow in ESPColorCorrection object :esphomepr:`7268` by :ghuser:`g-kiss` +- [validation] Allow ``maybe_simple_value`` to not have default key in complex value :esphomepr:`7294` by :ghuser:`jesserockz` +- [network] Always allow ``enable_ipv6: false`` :esphomepr:`7291` by :ghuser:`dwmw2` +- Revert "[validation] Allow ``maybe_simple_value`` to not have default key in complex value" :esphomepr:`7305` by :ghuser:`jesserockz` +- [lvgl] Bug fixes :esphomepr:`7300` by :ghuser:`clydebarrow` +- [speaker] Fix header includes :esphomepr:`7304` by :ghuser:`nielsnl68` +- [microphone] Fix header includes :esphomepr:`7310` by :ghuser:`jesserockz` +- Fix RP2040 Neopixel flickering issue :esphomepr:`7307` by :ghuser:`deCodeIt` +- add the ability to add more idf components to an existing setup :esphomepr:`7302` by :ghuser:`nielsnl68` +- Fix waveshare 2.13" epaper stride calculation error :esphomepr:`7303` by :ghuser:`serialx` +- [rtttl] fix STOPPED state :esphomepr:`7323` by :ghuser:`NewoPL` + +Past Changelogs +--------------- + +- :doc:`2024.7.0` +- :doc:`2024.6.0` +- :doc:`2024.5.0` +- :doc:`2024.4.0` +- :doc:`2024.3.0` +- :doc:`2024.2.0` +- :doc:`2023.12.0` +- :doc:`2023.11.0` +- :doc:`2023.10.0` +- :doc:`2023.9.0` +- :doc:`2023.8.0` +- :doc:`2023.7.0` +- :doc:`2023.6.0` +- :doc:`2023.5.0` +- :doc:`2023.4.0` +- :doc:`2023.3.0` +- :doc:`2023.2.0` +- :doc:`2022.12.0` +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/changelog/index.rst b/changelog/index.rst index 4696979742..0d8b249826 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2024.6.0.html + :url: /changelog/2024.8.0.html .. toctree:: :glob: diff --git a/changelog/v1.10.0.rst b/changelog/v1.10.0.rst index 66bdd66904..95cf07b88c 100644 --- a/changelog/v1.10.0.rst +++ b/changelog/v1.10.0.rst @@ -134,7 +134,7 @@ Other notable changes: (:ref:`wifi-networks`) - GPIO Switches have a new option ``restore_mode`` to configure how their values should be restored on boot. (:doc:`/components/switch/gpio`) -- Added :ref:`substitutions ` to reduce repeating across configs. +- Added :doc:`/components/substitutions` to reduce repeating across configs. - Validation error messages are now displayed even better. Now all errors are shown with the exact context where the error appeared. Try it, it's so much better. Next step will be to upgrade to a better YAML reader to provide better error messages when the YAML syntax is invalid. diff --git a/changelog/v1.12.0.rst b/changelog/v1.12.0.rst index 67a2059dea..5ebdc124a5 100644 --- a/changelog/v1.12.0.rst +++ b/changelog/v1.12.0.rst @@ -23,7 +23,7 @@ It's release day! 🎉 Today I'm happy to release ESPHome 1.12.0. What's new? A stuff got added! Let me walk you through it: Before 1.12, it was only possible to transfer data from ESPHome to Home Assistant (with the -``homeassistant.service`` call). With 1.12 you get :ref:`User-defined services `, +``homeassistant.service`` call). With 1.12 you get :ref:`User-defined services `, just define a service in your ESPHome file and call it like any other service from HA. All the rest (like variables, data validation, etc) are handled automatically! diff --git a/changelog/v1.9.0.rst b/changelog/v1.9.0.rst index ff519918c7..900ef04b7c 100644 --- a/changelog/v1.9.0.rst +++ b/changelog/v1.9.0.rst @@ -137,7 +137,7 @@ New Features - You can now upload OTA firmware files with the :doc:`web server component ` -- Added the ability to define global variables in esphomeyaml: :ref:`config-globals`. +- Added the ability to define global variables in esphomeyaml: :doc:`/components/globals`. - Added a ``frequency`` option to the :doc:`/components/output/esp8266_pwm`. diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index da0e8d8a86..76703b8740 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -19,7 +19,8 @@ Base Alarm Control Panel Configuration Configuration variables: -- **name** (**Required**, string): The name of the alarm control panel. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the alarm control panel. At least one of **id** and **name** must be specified. .. note:: @@ -47,8 +48,9 @@ Configuration variables: - **on_ready** (*Optional*, :ref:`Action `): An automation to perform when the logical 'and' of all the zone sensors change state. See :ref:`alarm_control_panel_on_ready_trigger`. - **on_chime** (*Optional*, :ref:`Action `): An automation to perform - when a zone has been marked as chime in the configuration, and it changes from closed to open. + when a zone has been marked as chime in the configuration, and it changes from closed to open. See :ref:`alarm_control_panel_on_chime_trigger`. +- If MQTT enabled, all other options from :ref:`MQTT Component `. - If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. diff --git a/components/animation.rst b/components/animation.rst new file mode 100644 index 0000000000..1a8d282fe0 --- /dev/null +++ b/components/animation.rst @@ -0,0 +1,86 @@ +.. _display-animation: + +Animation +========= + +Allows to use animated images on displays. Animation inherits all options from the image component. +It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_frame()`` to change the shown picture of a gif. + +.. code-block:: yaml + + animation: + - file: "animation.gif" + id: my_animation + resize: 100x100 + +The animation can be rendered just like the image component with the ``image()`` function of the display component. + +To show the next frame of the animation call ``id(my_animation).next_frame()``, to show the previous picture use ``id(my_animation).prev_frame()``. To show a specific picture use ``id(my_animation).set_frame(int frame)``. +This can be combined with all Lambdas: + +.. code-block:: yaml + + display: + - platform: ... + # ... + lambda: |- + //Ingress shown animation Frame. + id(my_animation).next_frame(); + // Draw the animation my_animation at position [x=0,y=0] + it.image(0, 0, id(my_animation), COLOR_ON, COLOR_OFF); + +Additionally, you can use the ``animation.next_frame``, ``animation.prev_frame`` or ``animation.set_frame`` actions. + +.. note:: + + To draw the next animation independent of Display draw cycle use an interval: + + .. code-block:: yaml + + interval: + - interval: 5s + then: + animation.next_frame: my_animation + +Configuration variables: +------------------------ + +- **file** (**Required**, string): The path (relative to where the .yaml file is) of the gif file. +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the animation later + in your display code. +- **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT`` + and preserve the aspect ratio. +- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``. + + - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit + per pixel, 8 pixels per byte. + - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel + will be the on color. Uses 1 bit per pixel, 8 pixels per byte. + - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. + - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. + - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. + +- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. +- **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over. + + - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation. + - **end_frame** (*Optional*, int): The last frame to show in the loop; when this frame is reached it will loop back to ``start_frame``. Defaults to the last frame in the animation. + - **repeat** (*Optional*, int): Specifies how many times the loop will run. When the count is reached, the animation will continue with the next frame after ``end_frame``, or restart from the beginning if ``end_frame`` was the last frame. Defaults to "loop forever". + +Actions: +-------- + +- **animation.next_frame**: Moves the animation to the next frame. This is equivalent to the ``id(my_animation).next_frame();`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + +- **animation.prev_frame**: Moves the animation to the previous frame. This is equivalent to the ``id(my_animation).prev_frame();`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + +- **animation.set_frame**: Moves the animation to a specific frame. This is equivalent to the ``id(my_animation).set_frame(frame);`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + - **frame** (**Required**, int): The frame index to show next. + diff --git a/components/api.rst b/components/api.rst index a6386a845c..398c46b146 100644 --- a/components/api.rst +++ b/components/api.rst @@ -60,7 +60,7 @@ Configuration variables: document.getElementById("api-key").value = bytesArrToBase64(array); -- **services** (*Optional*, list): A list of user-defined services. See :ref:`api-services`. +- **actions** (*Optional*, list): A list of user-defined actions. See :ref:`api-device-actions`. - **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when no client connects to the API. This is needed because sometimes the low level ESP functions report that the ESP is connected to the network, when in fact it is not - only a full reboot fixes it. @@ -79,7 +79,7 @@ Actions ------- Before using any of the actions below, you'll need to tell Home Assistant to allow your device to -make service calls. +perform actions. Open the ESPHome integration page on your Home Assistant instance: @@ -89,9 +89,9 @@ Open the ESPHome integration page on your Home Assistant instance: Then: -#. Fnd your device in the device list +#. Find your device in the device list #. Click the "configure" button next to it -#. Check the "Allow the device to make Home Assistant service calls" box +#. Check the "Allow the device to perform Home Assistant actions" box #. Then click "submit". .. _api-homeassistant_event_action: @@ -102,7 +102,7 @@ Then: .. note:: Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow - your device to make service calls. + your device to perform actions. When using the native API with Home Assistant, you can create events in the Home Assistant event bus straight from ESPHome :ref:`Automations `. @@ -127,31 +127,30 @@ Configuration variables: - **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``. Values are :ref:`lambdas ` and will be evaluated before sending the request. -.. _api-homeassistant_service_action: +.. _api-homeassistant_action-action: -``homeassistant.service`` Action +``homeassistant.action`` Action ******************************** .. note:: Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow - your device to make service calls. + your device to perform actions. -When using the native API with Home Assistant, you can create Home Assistant service -calls straight from ESPHome :ref:`Automations `. +When using the native API with Home Assistant, you can perform Home Assistant actions straight from ESPHome :ref:`Automations `. .. code-block:: yaml # In some trigger on_...: # Simple - - homeassistant.service: - service: notify.html5 + - homeassistant.action: + action: notify.html5 data: message: Button was pressed # With templates and variables - - homeassistant.service: - service: notify.html5 + - homeassistant.action: + action: notify.html5 data: title: New Humidity data_template: @@ -163,10 +162,10 @@ calls straight from ESPHome :ref:`Automations `. Configuration variables: ```````````````````````` -- **service** (**Required**, string): The Home Assistant `Service `__ - to call. -- **data** (*Optional*, mapping): Optional *static* data to pass along with the service call. -- **data_template** (*Optional*, mapping): Optional template data to pass along with the service call. +- **action** (**Required**, string): The Home Assistant `Action `__ + to perform. +- **data** (*Optional*, mapping): Optional *static* data to perform the action with. +- **data_template** (*Optional*, mapping): Optional template data to perform the action with. This is evaluated on the Home Assistant side with Home Assistant's templating engine. - **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``. Values are :ref:`lambdas ` and will be evaluated before sending the request. @@ -182,7 +181,7 @@ the parameters in plain format. set_light_rgb: alias: 'ESPHome RGB light set' sequence: - - service: light.turn_on + - action: light.turn_on data_template: entity_id: '{{ light_name }}' rgb_color: @@ -196,8 +195,8 @@ Then, in ESPHome: # In some trigger on_...: - - homeassistant.service: - service: script.set_light_rgb + - homeassistant.action: + action: script.set_light_rgb data: light_name: 'my_light' red: '255' @@ -212,7 +211,7 @@ Then, in ESPHome: .. note:: Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow - your device to make service calls. + your device to make action calls. When using the native API with Home Assistant, you can push tag_scanned to Home Assistant straight from ESPHome :ref:`Automations `. @@ -289,27 +288,27 @@ if logs are shown remotely. then: - logger.log: API is connected! -.. _api-services: +.. _api-device-actions: -User-defined Services ---------------------- +User-defined Actions +-------------------- -It is also possible to get data from Home Assistant to ESPHome with user-defined services. -When you declare services in your ESPHome YAML file, they will automatically show up in +It is also possible to get data from Home Assistant to ESPHome with user-defined actions. +When you declare actions in your ESPHome YAML file, they will automatically show up in Home Assistant and you can call them directly. .. code-block:: yaml # Example configuration entry api: - services: - - service: start_laundry + actions: + - action: start_laundry then: - switch.turn_on: relay - delay: 3h - switch.turn_off: relay -For example with the configuration seen above, after uploading you will see a service +For example with the configuration seen above, after uploading you will see an action called ``esphome.livingroom_start_laundry`` (livingroom is the node name) which you can then call. @@ -319,8 +318,8 @@ Additionally, you can also transmit data from Home Assistant to ESPHome with thi # Example configuration entry api: - services: - - service: start_effect + actions: + - action: start_effect variables: my_brightness: int my_effect: string @@ -331,18 +330,18 @@ Additionally, you can also transmit data from Home Assistant to ESPHome with thi effect: !lambda 'return my_effect;' Using the ``variables`` key you can tell ESPHome which variables to expect from Home Assistant. -For example the service seen above would be executed with something like this: +For example the action seen above would be executed with something like this: .. code-block:: yaml - # Example Home Assistant Service Call - service: esphome.livingroom_start_effect + # Example Home Assistant Action + action: esphome.livingroom_start_effect data_template: my_brightness: "{{ states.brightness.state }}" my_effect: "Rainbow" Then each variable you define in the ``variables`` section is accessible in the automation -triggered by the user-defined service through the name you gave it in the variables section +triggered by the user-defined action through the name you gave it in the variables section (note: this is a local variable, so do not wrap it in ``id(...)`` to access it). There are currently 4 types of variables: diff --git a/components/binary_sensor/analog_threshold.rst b/components/binary_sensor/analog_threshold.rst index 236eed00f2..f006afdfc1 100644 --- a/components/binary_sensor/analog_threshold.rst +++ b/components/binary_sensor/analog_threshold.rst @@ -36,8 +36,6 @@ a binary sensor. Configuration variables ----------------------- -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **sensor_id** (**Required**, :ref:`config-id`): The ID of the source sensor. - **threshold** (**Required**, float or mapping): Configures the reference for comparison. Accepts either a shorthand float number that will be used as both upper/lower threshold, or a mapping to define different values for each (to diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst index b9fdd1f007..c8a5c6565d 100644 --- a/components/binary_sensor/ble_presence.rst +++ b/components/binary_sensor/ble_presence.rst @@ -10,7 +10,7 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -27,7 +27,7 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu binary_sensor: # Presence based on MAC address - platform: ble_presence - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "ESP32 BLE Tracker Google Home Mini" min_rssi: -80dB # Presence based on Identity Resolving Key (IRK) @@ -54,7 +54,6 @@ The ``ble_presence`` binary sensor platform lets you track the presence of a Blu Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the binary sensor. - **mac_address** (*Optional*, MAC Address): The MAC address to track for this binary sensor. Note that exactly one of ``mac_address``, ``irk``, ``service_uuid`` or ``ibeacon_uuid`` must be present. @@ -72,8 +71,6 @@ Configuration variables: same building. - **ibeacon_minor** (*Optional*, int): The iBeacon minor identifier of the beacon that needs to be tracked. Usually used to identify beacons within an iBeacon group. -- **id** (*Optional*, :ref:`config-id`): Manually specify - the ID used for code generation. - **min_rssi** (*Optional*, int): at which minimum RSSI level would the component report the device be present. - **timeout** (*Optional*, :ref:`config-time`): The delay after last detecting the device before publishing not present state. The default is 5 minutes. @@ -96,7 +93,7 @@ the logs to see discovered Bluetooth Low Energy devices. Using the configuration above, first you should see a ``Starting scan...`` debug message at boot-up. Then, when a BLE device is discovered, you should see messages like -``Found device AC:37:43:77:5F:4C`` together with some information about their +``Found device XX:XX:XX:XX:XX:XX`` together with some information about their address type and advertised name. If you don't see these messages, your device is unfortunately currently not supported. diff --git a/components/binary_sensor/cap1188.rst b/components/binary_sensor/cap1188.rst index 016720311f..65f0608cc9 100644 --- a/components/binary_sensor/cap1188.rst +++ b/components/binary_sensor/cap1188.rst @@ -68,9 +68,7 @@ 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**, int): The channel number the CAP1188 the touchkey is connected to. - All other options from :ref:`Binary Sensor `. diff --git a/components/binary_sensor/esp32_touch.rst b/components/binary_sensor/esp32_touch.rst index 7c6bc25f3d..72153999a5 100644 --- a/components/binary_sensor/esp32_touch.rst +++ b/components/binary_sensor/esp32_touch.rst @@ -141,8 +141,6 @@ Configuration variables: events on. - **threshold** (**Required**, ``int``): The threshold to use to detect touch events. See :ref:`esp32-finding-thresholds` below for help determining this value. -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **wakeup_threshold** (*Optional*, ``int``): The threshold to use to detect touch events to wake-up from deep sleep. See :ref:`esp32-finding-thresholds` below for help determining this value. Touch pad sensors that should trigger a wake-up from deep sleep must specify this value. The :ref:`deep_sleep-component` must also be configured to enable diff --git a/components/binary_sensor/gpio.rst b/components/binary_sensor/gpio.rst index 65aefcb127..465cddd28e 100644 --- a/components/binary_sensor/gpio.rst +++ b/components/binary_sensor/gpio.rst @@ -27,8 +27,6 @@ Configuration variables: ------------------------ - **pin** (**Required**, :ref:`Pin Schema `): The pin to periodically check. -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. Activating internal pullups diff --git a/components/binary_sensor/homeassistant.rst b/components/binary_sensor/homeassistant.rst index 2628c5d582..b822a075bd 100644 --- a/components/binary_sensor/homeassistant.rst +++ b/components/binary_sensor/homeassistant.rst @@ -30,11 +30,9 @@ With Home Assistant 2021.6 or newer, entity state attributes can also be importe Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the binary sensor. - **entity_id** (**Required**, string): The entity ID to import from Home Assistant. - **attribute** (*Optional*, string): The name of the state attribute to import from the specified entity. The entity state is used when this option is omitted. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. See Also diff --git a/components/binary_sensor/hydreon_rgxx.rst b/components/binary_sensor/hydreon_rgxx.rst index 47a5b7dba4..d49864221f 100644 --- a/components/binary_sensor/hydreon_rgxx.rst +++ b/components/binary_sensor/hydreon_rgxx.rst @@ -34,27 +34,15 @@ Configuration variables: - **too_cold** (*Optional*): ``true`` if the sensor reports being too cold. Hydreon only mentions this feature for the RG-9. - - **name** (**Required**, string): The name for the sensor. - - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - - All other options from :ref:`Binary Sensor `. + - All options from :ref:`Binary Sensor `. - **lens_bad** (*Optional*): ``true`` if the sensor reports the lens being bad. - - **name** (**Required**, string): The name for the sensor. - - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - - All other options from :ref:`Binary Sensor `. + - All options from :ref:`Binary Sensor `. - **em_sat** (*Optional*): ``true`` if the sensor reports the Emitter being saturated. - - **name** (**Required**, string): The name for the sensor. - - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - - All other options from :ref:`Binary Sensor `. + - All options from :ref:`Binary Sensor `. See Also diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index fba4b9da68..949a2bf154 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -27,7 +27,8 @@ you can always override it. Configuration variables: -- **name** (**Required**, string): The name for the binary sensor. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the binary sensor. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/binary_sensor/lvgl.rst b/components/binary_sensor/lvgl.rst new file mode 100644 index 0000000000..e56b9c196c --- /dev/null +++ b/components/binary_sensor/lvgl.rst @@ -0,0 +1,39 @@ +LVGL Binary Sensor +================== + +.. seo:: + :description: Instructions for setting up an LVGL widget binary sensor. + :image: ../images/lvgl_c_bns.png + +The ``lvgl`` binary sensor platform creates a binary sensor from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widget is :ref:`lvgl-widget-button`. A single binary sensor supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome binary sensor component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the binary sensor. +- All other variables from :ref:`Binary Sensor `. + +Example: + +.. code-block:: yaml + + binary_sensor: + - platform: lvgl + widget: btn_id + name: LVGL push button + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Button widget ` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/binary_sensor/modbus_controller.rst b/components/binary_sensor/modbus_controller.rst index 8e8ecea77a..1ff315fe3c 100644 --- a/components/binary_sensor/modbus_controller.rst +++ b/components/binary_sensor/modbus_controller.rst @@ -12,8 +12,6 @@ and requires :doc:`/components/modbus_controller` to be configured. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **register_type** (**Required**): type of the modbus register. - ``coil``: Coils are 1-bit registers (ON/OFF values) that are used to control discrete outputs. Read and Write access. Modbus *Function Code 1 (Read Coil Status)* will be used. diff --git a/components/binary_sensor/mpr121.rst b/components/binary_sensor/mpr121.rst index 73fcd743be..4d41a21376 100644 --- a/components/binary_sensor/mpr121.rst +++ b/components/binary_sensor/mpr121.rst @@ -69,9 +69,7 @@ binary sensors for each touch sensor. Configuration variables: -- **name** (*Optional*, string): The name for the binary sensor. - **mpr121_id** (*Optional*, :ref:`config-id`): The ID of the MPR121 defined above. Useful for multiple MPR121's on the I²C bus -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **channel** (**Required**, int): The channel number at the MPR121 the touchkey is connected to. - **touch_threshold** (*Optional*, int): A per-channel override of the global touch_threshold value. If not specified, uses the global value. - **release_threshold** (*Optional*, int): A per-channel override of the global release_threshold value. If not specified, uses the global value. diff --git a/components/binary_sensor/nextion.rst b/components/binary_sensor/nextion.rst index 9825c216f5..2260ddb024 100644 --- a/components/binary_sensor/nextion.rst +++ b/components/binary_sensor/nextion.rst @@ -39,7 +39,6 @@ See :doc:`/components/display/nextion` for setting up the display Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. - **component_name** (*Optional*, string): The name of the Nextion component. - **variable_name** (*Optional*, string): The name of the Nextion variable. Any value over ``0`` is considered to be **on** diff --git a/components/binary_sensor/pn532.rst b/components/binary_sensor/pn532.rst index fe161c46df..c2db142a97 100644 --- a/components/binary_sensor/pn532.rst +++ b/components/binary_sensor/pn532.rst @@ -208,8 +208,6 @@ Configuration variables: - **uid** (**Required**, string): The unique ID of the NFC/RFID tag. This is a hyphen-separated list of hexadecimal values. For example ``74-10-37-94``. -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. .. _pn532-setting_up_tags: diff --git a/components/binary_sensor/rc522.rst b/components/binary_sensor/rc522.rst index 1c89732b1f..837e797ca7 100644 --- a/components/binary_sensor/rc522.rst +++ b/components/binary_sensor/rc522.rst @@ -189,8 +189,6 @@ Configuration variables: - **uid** (**Required**, string): The unique ID of the NFC/RFID tag. This is a hyphen-separated list of hexadecimal values. For example ``74-10-37-94``. -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. .. _rc522-setting_up_tags: diff --git a/components/binary_sensor/rdm6300.rst b/components/binary_sensor/rdm6300.rst index 11b102e6fc..901a5db17c 100644 --- a/components/binary_sensor/rdm6300.rst +++ b/components/binary_sensor/rdm6300.rst @@ -107,8 +107,6 @@ Configuration variables: ************************ - **uid** (**Required**, int): The unique ID of the NFC/RFID tag. -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. .. _rdm6300-setting_up_tags: diff --git a/components/binary_sensor/status.rst b/components/binary_sensor/status.rst index cdaac910a5..b426031a12 100644 --- a/components/binary_sensor/status.rst +++ b/components/binary_sensor/status.rst @@ -22,9 +22,7 @@ for Home Assistant. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Binary Sensor `. (Inverted mode is not supported) +- All options from :ref:`Binary Sensor `. (Inverted mode is not supported) See Also -------- diff --git a/components/binary_sensor/template.rst b/components/binary_sensor/template.rst index 85b70513d8..c1c8e645b1 100644 --- a/components/binary_sensor/template.rst +++ b/components/binary_sensor/template.rst @@ -36,12 +36,8 @@ Possible return values of the lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the binary sensor. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated repeatedly to get the current state of the binary sensor. -- **id** (*Optional*, - :ref:`config-id`): Manually specify - the ID used for code generation. - All other options from :ref:`Binary Sensor `. .. _binary_sensor-template-publish_action: diff --git a/components/binary_sensor/ttp229.rst b/components/binary_sensor/ttp229.rst index 6910db3b2e..8fbf712fc3 100644 --- a/components/binary_sensor/ttp229.rst +++ b/components/binary_sensor/ttp229.rst @@ -47,9 +47,7 @@ The configuration is made up of two parts: The central component, and individual Configuration variables: -- **name** (**Required**, string): The name of the binary sensor. - **channel** (**Required**, int): The channel number at the TTP229 the touchkey is connected to. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. ``ttp229_bsf`` Component @@ -85,9 +83,7 @@ Base Configuration: Configuration variables: -- **name** (**Required**, string): The name of the binary sensor. - **channel** (**Required**, int): The channel number at the TTP229 the touchkey is connected to. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. See Also diff --git a/components/binary_sensor/tuya.rst b/components/binary_sensor/tuya.rst index ab6489af27..30c362e692 100644 --- a/components/binary_sensor/tuya.rst +++ b/components/binary_sensor/tuya.rst @@ -20,8 +20,6 @@ You can create the binary sensor as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the binary sensor. - **sensor_datapoint** (**Required**, int): The datapoint id number of the binary sensor. - All other options from :ref:`Binary Sensor `. diff --git a/components/ble_client.rst b/components/ble_client.rst index 98697f8407..06f08c193c 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -12,7 +12,7 @@ connections to them for use by other components. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -36,7 +36,7 @@ to discover available client devices. esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black auto_connect: true @@ -73,7 +73,7 @@ This automation is triggered when the client connects to the BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_connect: then: @@ -90,7 +90,7 @@ This automation is triggered when the client disconnects from a BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_disconnect: then: @@ -108,7 +108,7 @@ This automation is triggered when the BLE device requests a passkey for authenti .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_passkey_request: then: @@ -126,7 +126,7 @@ This automation is triggered when a passkey is received from the BLE device. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_passkey_notification: then: @@ -144,7 +144,7 @@ This automation is triggered when a numeric comparison is requested by the BLE d .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: ble_itag on_numeric_comparison_request: then: @@ -174,10 +174,10 @@ on, hence the stop and start of the scan during connect. ble_client: - id: ble_clock - mac_address: 17:75:BC:F2:94:4D + mac_address: XX:XX:XX:XX:XX:XX auto_connect: false - id: other_device - mac_address: 0D:33:12:66:00:D4 + mac_address: XX:XX:XX:XX:XX:XX interval: - interval: 60min @@ -222,7 +222,7 @@ Example usage: .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client switch: @@ -308,7 +308,7 @@ Example usage: .. code-block:: yaml ble_client: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client on_connect: then: @@ -391,9 +391,9 @@ display them in the log: .. code-block:: text - [18:24:56][D][ble_client:043]: Found device at MAC address [FC:58:FA:B1:F8:93] - [18:24:56][I][ble_client:072]: Attempting BLE connection to fc:58:fa:b1:f8:93 - [18:24:56][I][ble_client:097]: [fc:58:fa:b1:f8:93] ESP_GATTC_OPEN_EVT + [18:24:56][D][ble_client:043]: Found device at MAC address [XX:XX:XX:XX:XX:XX] + [18:24:56][I][ble_client:072]: Attempting BLE connection to XX:XX:XX:XX:XX:XX + [18:24:56][I][ble_client:097]: [XX:XX:XX:XX:XX:XX] ESP_GATTC_OPEN_EVT [18:24:57][I][ble_client:143]: Service UUID: 0x1800 [18:24:57][I][ble_client:144]: start_handle: 0x1 end_handle: 0x5 [18:24:57][I][ble_client:305]: characteristic 0x2A00, handle 0x3, properties 0x2 @@ -445,7 +445,7 @@ Secure connection with a fixed passkey: esp32_ble_tracker: ble_client: - - mac_address: A4:C1:38:B1:CD:7F + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display on_passkey_request: then: @@ -459,8 +459,8 @@ Secure connection with a dynamically generated passkey: .. code-block:: yaml api: - services: - - service: passkey_reply + actions: + - action: passkey_reply variables: passkey: int then: @@ -468,7 +468,7 @@ Secure connection with a dynamically generated passkey: - ble_client.passkey_reply: id: my_ble_client passkey: !lambda return passkey; - - service: numeric_comparison_reply + - action: numeric_comparison_reply variables: accept: bool then: @@ -483,7 +483,7 @@ Secure connection with a dynamically generated passkey: esp32_ble_tracker: ble_client: - - mac_address: AA:BB:CC:DD:EE:FF + - mac_address: XX:XX:XX:XX:XX:XX id: my_ble_client on_passkey_request: then: diff --git a/components/button/factory_reset.rst b/components/button/factory_reset.rst index 03e1bfe097..f8ed5a97a7 100644 --- a/components/button/factory_reset.rst +++ b/components/button/factory_reset.rst @@ -35,9 +35,7 @@ After reboot all states, parameters and variables will be reinitialized with the Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the button. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Button `. +- All options from :ref:`Button `. See Also -------- diff --git a/components/button/index.rst b/components/button/index.rst index 0151b7c690..921d37848e 100644 --- a/components/button/index.rst +++ b/components/button/index.rst @@ -40,7 +40,8 @@ All buttons in ESPHome have a name and an optional icon. Configuration variables: -- **name** (**Required**, string): The name for the button. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the button. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/button/output.rst b/components/button/output.rst index d037730fca..e54d704622 100644 --- a/components/button/output.rst +++ b/components/button/output.rst @@ -29,8 +29,6 @@ momentarily set a GPIO pin using a button. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the button. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **output** (**Required**, :ref:`config-id`): The ID of the output component to use. - **duration** (**Required**, :ref:`config-time`): How long the output should be set when the button is pressed. - All other options from :ref:`Button `. diff --git a/components/button/restart.rst b/components/button/restart.rst index 03be784b78..0f6d445191 100644 --- a/components/button/restart.rst +++ b/components/button/restart.rst @@ -18,9 +18,7 @@ through Home Assistant. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the button. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Button `. +- All options from :ref:`Button `. See Also -------- diff --git a/components/button/safe_mode.rst b/components/button/safe_mode.rst index 45fe8534ab..7342d08e2f 100644 --- a/components/button/safe_mode.rst +++ b/components/button/safe_mode.rst @@ -24,9 +24,7 @@ This component requires :doc:`/components/safe_mode` to be configured. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the button. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Button `. +- All options from :ref:`Button `. See Also -------- diff --git a/components/button/shutdown.rst b/components/button/shutdown.rst index 68dadc518c..c6d363b505 100644 --- a/components/button/shutdown.rst +++ b/components/button/shutdown.rst @@ -24,9 +24,7 @@ pressing the reset button or restarting the power supply. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the button. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Button `. +- All options from :ref:`Button `. See Also -------- diff --git a/components/button/template.rst b/components/button/template.rst index 11095ab827..cc8d3965a1 100644 --- a/components/button/template.rst +++ b/components/button/template.rst @@ -20,9 +20,7 @@ it will automatically appear in Home Assistant as a button and can be controlled Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Button `. +- All options from :ref:`Button `. See Also -------- diff --git a/components/button/uart.rst b/components/button/uart.rst index 565e42af20..174d7b827f 100644 --- a/components/button/uart.rst +++ b/components/button/uart.rst @@ -22,8 +22,6 @@ The ``uart`` button platform allows you to send a pre-defined sequence of bytes Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (*Optional*, string): The name for the button. - **data** (**Required**, string or list of bytes): The data to send via UART. Either an ASCII string or a list of bytes. - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub. diff --git a/components/button/wake_on_lan.rst b/components/button/wake_on_lan.rst index 3d702036ac..b91e5f3ba4 100644 --- a/components/button/wake_on_lan.rst +++ b/components/button/wake_on_lan.rst @@ -14,14 +14,12 @@ by specifying its MAC address. button: - platform: wake_on_lan name: "Start the Server" - target_mac_address: E9:48:B8:CA:58:A1 + target_mac_address: XX:XX:XX:XX:XX:XX Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the button. - **target_mac_address** (**Required**, MAC Address): The MAC Address of the target computer. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Button `. See Also diff --git a/components/canbus.rst b/components/canbus.rst deleted file mode 100644 index 8c562f6263..0000000000 --- a/components/canbus.rst +++ /dev/null @@ -1,498 +0,0 @@ -.. _canbus: - -CAN bus -======= - -.. seo:: - :description: Instructions for setting up an CAN bus in ESPHome - :image: canbus.svg - :keywords: CAN - -Controller Area Network (CAN bus) is a serial bus protocol to connect individual systems and sensors -as an alternative to conventional multi-wire looms. -It allows automotive components to communicate on a single or dual-wire networked data bus up to 1Mbps. -CAN is an International Standardization Organization (ISO) defined serial communications bus originally -developed for the automotive industry to replace the complex wiring harness with a two-wire bus. The -specification calls for high immunity to electrical interference and the ability to self-diagnose and repair -data errors. These features have led to CAN’s popularity in a variety of industries including building -automation, medical, and manufacturing. - -The current ESPHome implementation supports single frame data transfer. In this way you may send and -receive data frames up to 8 bytes. -With this you can transmit the press of a button or the feedback from a sensor on the bus. -All other devices on the bus will be able to get this data to switch on/off a light or display the -transmitted data. - -The CAN bus itself has only two wires named Can High and Can Low or CanH and CanL. For the ESPHome -CAN bus to work you need to select the device that has the physical CAN bus implemented. -You can configure multiple buses. - -Any can bus node can transmit data at any time, and any node can send any ``can_id`` value and any -node can receive any can_id too. Is up to you how to organize the can_id values. You can setup a can -bus network where each node has a can id which will use to broadcast data about itself, if a node -should, e.g. turn on a light, it can listen for can messages with the can id assigned to it. -So you can have several nodes being able to control a light in e.g. node 20. - -Base CAN Bus Configuration --------------------------- - -Each canbus platform extends this configuration schema. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: ... - can_id: 4 - on_frame: - - can_id: 500 - use_extended_id: false - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can id 500", "%s", &b[0] ); - -.. _config-canbus: - -Configuration variables: -************************ - -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **can_id** (**Required**, int): default *can id* used for transmitting frames. -- **use_extended_id** (*Optional*, boolean): default *false* identifies the type of *can_id*: - *false*: Standard 11 bits IDs, *true*: Extended 29 bits ID -- **bit_rate** (*Optional*, enum): One of the supported bitrates. Defaults to ``125KBPS``. - - - ``1KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``5KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``10KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``12K5BPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``16KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``20KBPS`` - Support by ``esp32_can`` depends on ESP32 variant - - ``25KBPS`` - - ``31K25BPS`` - Not supported by ``esp32_can`` - - ``33KBPS`` - Not supported by ``esp32_can`` - - ``40KBPS`` - Not supported by ``esp32_can`` - - ``50KBPS`` - - ``80KBPS`` - Not supported by ``esp32_can`` - - ``83K3BPS`` - Not supported by ``esp32_can`` - - ``95KBPS`` - Not supported by ``esp32_can`` - - ``100KBPS`` - - ``125KBPS`` - (Default) - - ``200KBPS`` - Not supported by ``esp32_can`` - - ``250KBPS`` - - ``500KBPS`` - - ``1000KBPS`` - - See :ref:`this table ` for a list of supported bit rates by the internal CAN (TWAI) controllers of different ESP32 variants. - - -Automations: ------------- - -- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when a - CAN frame is received. See :ref:`canbus-on-frame`. - -.. _canbus-on-frame: - -``on_frame`` Trigger -******************** - -This automation will be triggered when a CAN frame is received. The variables ``x`` (of type -``std::vector``) containing the frame data, ``can_id`` (of type ``uint32_t``) containing the actual -received CAN id and ``remote_transmission_request`` (of type ``bool``) containing the corresponding field -from the CAN frame are passed to the automation for use in lambdas. - -.. note:: - - Messages this node sends to the same ID will not show up as received messages. - -.. code-block:: yaml - - canbus: - - platform: ... - on_frame: - - can_id: 43 # the received can_id - then: - - if: - condition: - lambda: 'return (x.size() > 0) ? x[0] == 0x11 : false;' - then: - light.toggle: light1 - - can_id: 0b00000000000000000000001000000 - can_id_mask: 0b11111000000000011111111000000 - use_extended_id: true - remote_transmission_request: false - then: - - lambda: |- - auto pdo_id = can_id >> 14; - switch (pdo_id) - { - case 117: - ESP_LOGD("canbus", "exhaust_fan_duty"); - break; - case 118: - ESP_LOGD("canbus", "supply_fan_duty"); - break; - case 119: - ESP_LOGD("canbus", "supply_fan_flow"); - break; - // to be continued... - } - - -Configuration variables: -************************ - -- **can_id** (**Required**, int): The received CAN id to trigger this automation on. -- **can_id_mask** (*Optional*, int): The bit mask to apply to the received CAN id before trying to match it - with *can_id*, defaults to ``0x1fffffff`` (all bits of received CAN id are compared with *can_id*). -- **use_extended_id** (*Optional*, boolean): Identifies the type of *can_id* to match on, defaults to *false*. -- **remote_transmission_request** (*Optional*, boolean): Whether to run for CAN frames with the "remote - transmission request" bit set or not set, defaults to not checking, i.e. to run for both cases. - -``canbus.send`` Action -********************** - -The can bus can transmit frames by means of the ``canbus.send`` action. -There are several forms to use it: - -.. code-block:: yaml - - on_...: - - canbus.send: - data: [ 0x10, 0x20, 0x30 ] - canbus_id: my_mcp2515 # optional if you only have 1 canbus device - can_id: 23 # override the can_id configured in the can bus - - on_...: - - canbus.send: [ 0x11, 0x22, 0x33 ] - - - canbus.send: 'hello' - - # Templated, return type is std::vector - - canbus.send: !lambda return {0x00, 0x20, 0x42}; - -Configuration variables: - -- **data** (**Required**, binary data, :ref:`templatable `): Data to transmit, up to 8 bytes or - characters are supported by can bus per frame. -- **canbus_id** (*Optional*): Optionally set the can bus id to use for transmitting - the frame. Not needed if you are using only 1 can bus. -- **can_id** (*Optional*, int): Allows to override the can id configured in - the can bus device. -- **use_extended_id** (*Optional*, boolean): default *false* identifies the type of *can_id*: - *false*: Standard 11 Bit IDs, *true*: Extended 29Bit ID -- **remote_transmission_request** (*Optional*, boolean): Set to send CAN bus frame to request data from another node - (defaults to *false*). If a certain data length code needs to be sent, provide as many (dummy) bytes in *data*. - -ESP32 CAN Component -------------------- - -The ESP32 has an integrated CAN controller and therefore doesn't need an external controller necessarily. -You only need to specify the RX and TX pins. Any GPIO will work. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: esp32_can - tx_pin: GPIOXX - rx_pin: GPIOXX - can_id: 4 - bit_rate: 50kbps - on_frame: - ... - - -.. _esp32-can-bit-rate: - -The table lists the specific bit rates supported by the component for ESP32 variants: - =================== ======= ========== ========== ========== ========== ========== - bit_rate ESP32 ESP32-S2 ESP32-S3 ESP32-C3 ESP32-C6 ESP32-H2 - =================== ======= ========== ========== ========== ========== ========== - 1KBPS x x x x x - 5KBPS x x x x x - 10KBPS x x x x x - 12K5BPS x x x x x - 16KBPS x x x x x - 20KBPS x x x x x - 25KBPS x x x x x x - 31K25BPS - 33KBPS - 40KBPS - 50KBPS x x x x x x - 80KBPS - 83K38BPS - 95KBPS - 100KBPS x x x x x x - 125KBPS (Default) x x x x x x - 250KBPS x x x x x x - 500KBPS x x x x x x - 800KBPS x x x x x x - 1000KBPS x x x x x x - =================== ======= ========== ========== ========== ========== ========== - - -Wiring options -************** - -5V CAN transceivers are cheap and generate compliant levels. If you power your -board with 5V this is the preferred option. R501 is important to reduce the 5V -logic level down to 3.3V, to avoid damaging the ESP32. You can alternatively -use a voltage divider here instead. - -.. figure:: images/canbus_esp32_5v.png - :align: center - :target: ../_images/canbus_esp32_5v.png - -If you prefer to only have a 3.3V power supply, special 3.3V CAN transceivers are available. - -.. figure:: images/canbus_esp32_3v3.png - :align: center - :target: ../_images/canbus_esp32_3v3.png - - -Configuration variables: -************************ - -- **rx_pin** (**Required**, :ref:`Pin `): Receive pin. -- **tx_pin** (**Required**, :ref:`Pin `): Transmit pin. -- All other options from :ref:`Canbus `. - -MCP2515 Component ------------------ - -The MCP2515 is a spi device and therefore you must first add the configuration for the spi bus to your file. -You need to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** and **miso_pin** set. - -For wiring up the MSP2515 please refer to the section below. - -.. code-block:: yaml - - # Example configuration entry - canbus: - - platform: mcp2515 - cs_pin: GPIOXX - can_id: 4 - bit_rate: 50kbps - on_frame: - - can_id: 500 - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("canid 500", "%s", &b[0] ); - - light.turn_off: light_1 - - can_id: 501 - then: - - light.turn_on: - id: light_1 - brightness: !lambda "return (x.size() > 0) ? (float) x[0]/255 : 0;" - -Configuration variables: -************************ - -- **cs_pin** (**Required**, :ref:`Pin Schema `): Is used to tell the receiving SPI device - when it should listen for data on the SPI bus. Each device has an individual ``CS`` line. - Sometimes also called ``SS``. -- **clock** (*Optional*): One of ``8MHZ``, ``12MHz``, ``16MHZ`` or ``20MHZ``. Clock crystal used on the MCP2515 device. - Defaults to ``8MHZ``. -- **mode** (*Optional*): Operation mode. Default to ``NORMAL`` - - - ``NORMAL``: Normal operation - - ``LOOPBACK``: Loopback mode can be used to just test you spi connections to the device - - ``LISTENONLY``: only receive data - -- All other options from :ref:`Canbus `. - -Note that not all combinations of clock and bitrate are supported. An unsupported -combination will not be flagged at compile time, check the runtime log for a message like -``Invalid frequency/bitrate combination`` if you suspect this is an issue. - -Wiring options -************** - -Easiest approach is to just use fully assembled boards and just add one resistor in the MISO line. -This runs MOSI, SCK and CS out of specification which is nearly never a problem. - -.. figure:: images/canbus_mcp2515_resistor.png - :align: center - :target: ../_images/canbus_mcp2515_resistor.png - -A more advanced option is to fully convert the 5V and 3.3V logic levels with a level shifter. - -.. figure:: images/canbus_mcp2515_txs0108e.png - :align: center - :target: ../_images/canbus_mcp2515_txs0108e.png - -Extended ID ------------ -Standard IDs and Extended IDs can coexist on the same segment. - -.. note:: - - It is important to know that for example Standard 0x123 and Extended 0x123 are different addresses. - This example shows how the different ID types are used in the configuration for transmission and receiving. - For the IDs decimal or hexadecimal notation is possible: - 0x000 - 0x7ff / 0-2047 for Standard IDs only. - 0x00000000 - 0x1fffffff / 0-536870911 for Extended IDs. - -.. code-block:: yaml - - # Transmission of extended and standard ID 0x100 every second - time: - - platform: sntp - on_time: - - seconds: /1 - then: - - canbus.send: - # Extended ID explicit - use_extended_id: true - can_id: 0x100 - data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] - - canbus.send: - # Standard ID by default - can_id: 0x100 - data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 0x1fff - use_extended_id: true - bit_rate: 125kbps - on_frame: - - can_id: 0x123 - use_extended_id: true - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can extended id 0x123", "%s", &b[0] ); - - can_id: 0x123 - then: - - lambda: |- - std::string b(x.begin(), x.end()); - ESP_LOGD("can standard id 0x123", "%s", &b[0] ); - -Binary Sensor Example ---------------------- -Example for the following application: -Button is connected on a can node which sends an A message on ID 0x100 with payload 0x01 for contact closed and 0x00 for contact open. - -.. code-block:: yaml - - spi: - id: McpSpi - clk_pin: GPIOXX - mosi_pin: GPIOXX - miso_pin: GPIOXX - - binary_sensor: - - platform: template - name: "CAN Bus Button" - id: "can_bus_button" - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 4 - bit_rate: 125kbps - on_frame: - - can_id: ${0x100} - then: - - lambda: |- - if(x.size() > 0) { - switch(x[0]) { - case 0x0: id(can_bus_button).publish_state(false); break; // button release - case 0x1: id(can_bus_button).publish_state(true); break; // button down - } - } - -Cover Example -------------- -Example for following application: -Buttons are connected on the CAN-Node and also the motor is connected via CAN. - -.. epigraph:: - - | **Button 1:** ID 0x50B - 1 byte payload - | (0: Button release, 1: Button down, 2: long down, 3: long release, 4 double click) - | **Button 2:** ID 0x50C - 1 byte payload - | (0: Button release, 1: Button down, 2: long down, 3: long release, 4 double click) - | **Motor:** ID 0x51A - 1 byte payload - | (0: off, 1: open, 2: close) - -.. code-block:: yaml - - spi: - id: McpSpi - clk_pin: GPIOXX - mosi_pin: GPIOXX - miso_pin: GPIOXX - - canbus: - - platform: mcp2515 - id: my_mcp2515 - spi_id: McpSpi - cs_pin: GPIOXX - can_id: 4 - bit_rate: 125kbps - on_frame: - - can_id: 0x50c - then: - - lambda: |- - if(x.size() > 0) { - auto call = id(TestCover).make_call(); - switch(x[0]) { - case 0x2: call.set_command_open(); call.perform(); break; // long pressed - case 0x1: // button down - case 0x3: call.set_command_stop(); call.perform(); break; // long released - case 0x4: call.set_position(1.0); call.perform(); break; // double click - } - } - - can_id: 0x50b - then: - - lambda: |- - if(x.size() > 0) { - auto call = id(TestCover).make_call(); - switch(x[0]) { - case 0x2: call.set_command_close(); call.perform(); break; // long pressed - case 0x1: // button down - case 0x3: call.set_command_stop(); call.perform(); break; // long released - case 0x4: call.set_position(0.0); call.perform(); break; // double click - } - } - - cover: - - platform: time_based - name: "MyCanbusTestCover" - id: TestCover - device_class: shutter - has_built_in_endstop: true - open_action: - - canbus.send: - data: [ 0x01 ] - canbus_id: my_mcp2515 - can_id: 0x51A - open_duration: 2min - close_action: - - canbus.send: - data: [ 0x02 ] - canbus_id: my_mcp2515 - can_id: 0x51A - close_duration: 2min - stop_action: - - canbus.send: - data: [ 0x00 ] - canbus_id: my_mcp2515 - can_id: 0x51A - -See Also --------- - -- :apiref:`spi/spi.h` -- :ghedit:`Edit` diff --git a/components/canbus/esp32_can.rst b/components/canbus/esp32_can.rst new file mode 100644 index 0000000000..bc973f08e2 --- /dev/null +++ b/components/canbus/esp32_can.rst @@ -0,0 +1,83 @@ +ESP32 CAN +========= + +.. seo:: + :description: Instructions for setting up the ESP32 CAN bus platform in ESPHome + :image: canbus.svg + :keywords: CAN, ESP32 + +The ESP32 has an integrated CAN controller and therefore doesn't necessarily need an external controller. +You only need to specify the RX and TX pins. Any GPIO will work. + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: esp32_can + tx_pin: GPIOXX + rx_pin: GPIOXX + can_id: 4 + bit_rate: 50kbps + on_frame: + ... + +Configuration variables: +------------------------ + +- **rx_pin** (**Required**, :ref:`Pin `): Receive pin. +- **tx_pin** (**Required**, :ref:`Pin `): Transmit pin. +- All other options from :ref:`Canbus `. + +.. _esp32-can-bit-rate: + +The following table lists the bit rates supported by the component for ESP32 variants: + +=================== ======= ========== ========== ========== ========== ========== +bit_rate ESP32 ESP32-S2 ESP32-S3 ESP32-C3 ESP32-C6 ESP32-H2 +=================== ======= ========== ========== ========== ========== ========== +1KBPS x x x x x +5KBPS x x x x x +10KBPS x x x x x +12K5BPS x x x x x +16KBPS x x x x x +20KBPS x x x x x +25KBPS x x x x x x +31K25BPS +33KBPS +40KBPS +50KBPS x x x x x x +80KBPS +83K38BPS +95KBPS +100KBPS x x x x x x +125KBPS (Default) x x x x x x +250KBPS x x x x x x +500KBPS x x x x x x +800KBPS x x x x x x +1000KBPS x x x x x x +=================== ======= ========== ========== ========== ========== ========== + +Wiring options +-------------- + +5V CAN transceivers are cheap and generate compliant levels. If you power your +board with 5V this is the preferred option. R501 is important to reduce the 5V +logic level down to 3.3V, to avoid damaging the ESP32. You can alternatively +use a voltage divider here instead. + +.. figure:: images/canbus_esp32_5v.png + :align: center + :target: ../_images/canbus_esp32_5v.png + +If you prefer to only have a 3.3V power supply, special 3.3V CAN transceivers are available. + +.. figure:: images/canbus_esp32_3v3.png + :align: center + :target: ../_images/canbus_esp32_3v3.png + +See Also +-------- + +- :doc:`index` +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/images/canbus_esp32_3v3.png b/components/canbus/images/canbus_esp32_3v3.png similarity index 100% rename from components/images/canbus_esp32_3v3.png rename to components/canbus/images/canbus_esp32_3v3.png diff --git a/components/images/canbus_esp32_5v.png b/components/canbus/images/canbus_esp32_5v.png similarity index 100% rename from components/images/canbus_esp32_5v.png rename to components/canbus/images/canbus_esp32_5v.png diff --git a/components/images/canbus_mcp2515_resistor.png b/components/canbus/images/canbus_mcp2515_resistor.png similarity index 100% rename from components/images/canbus_mcp2515_resistor.png rename to components/canbus/images/canbus_mcp2515_resistor.png diff --git a/components/images/canbus_mcp2515_txs0108e.png b/components/canbus/images/canbus_mcp2515_txs0108e.png similarity index 100% rename from components/images/canbus_mcp2515_txs0108e.png rename to components/canbus/images/canbus_mcp2515_txs0108e.png diff --git a/components/canbus/index.rst b/components/canbus/index.rst new file mode 100644 index 0000000000..a16a727085 --- /dev/null +++ b/components/canbus/index.rst @@ -0,0 +1,369 @@ +CAN Bus +======= + +.. seo:: + :description: Instructions for setting up an CAN bus in ESPHome + :image: canbus.svg + :keywords: CAN + +The Controller Area Network (CAN) bus is a serial bus protocol to connect individual systems and sensors +as an alternative to conventional multi-wire looms. It allows automotive components to communicate on a +single or dual-wire data bus at speeds up to 1Mbps. + +CAN is an International Standardization Organization (ISO) defined serial communications bus originally +developed for the automotive industry to replace the complex wiring harness with a two-wire bus. The +specification calls for high immunity to electrical interference and the ability to self-diagnose and repair +data errors. These features have led to CAN’s popularity in a variety of industries including building +automation, medical, and manufacturing. + +The current ESPHome implementation supports single frame data transfer. In this way you may send and +receive data frames up to 8 bytes. +With this you can transmit the press of a button or the feedback from a sensor on the bus. +All other devices on the bus will be able to get this data to switch on/off a light or display the +transmitted data. + +The CAN bus itself has only two wires named Can High and Can Low or CanH and CanL. For the ESPHome +CAN bus to work, you need to select the device that has the physical CAN bus implemented. +You can configure multiple buses. + +Any CAN bus node can transmit data at any time; any node can both send and/or receive any ``can_id`` value. +You must determine how to organize the ``can_id`` values; for example, you can set up a CAN bus network where +each node has a ``can_id`` it will use to broadcast data about itself. If a given node should (for example) turn +on a light, it can listen to the CAN bus for messages containing its specific ``can_id`` and react accodingly. +With this architecture, you can have multiple nodes able to control a light connected to a single, specific node. + +Base CAN Bus Configuration +-------------------------- + +Each ``canbus`` platform extends the following configuration schema: + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: ... + can_id: 4 + on_frame: + - can_id: 500 + use_extended_id: false + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("can id 500", "%s", &b[0] ); + +.. _config-canbus: + +**Configuration variables:** + +- **platform** (**Required**, :ref:`platform`): One of the supported CAN bus :ref:`platforms-canbus`. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **can_id** (**Required**, int): default *CAN ID* used for transmitting frames. +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id``: + + - ``false``: Standard 11-bit IDs *(default)* + - ``true``: Extended 29-bit IDs + +- **bit_rate** (*Optional*, enum): One of the supported bit rates. See :ref:`this table ` for a + list of supported bit rates by the internal CAN (TWAI) controllers of different ESP32 variants. Defaults to ``125KBPS``. + + - ``1KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``5KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``10KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``12K5BPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``16KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``20KBPS`` - Support by ``esp32_can`` depends on ESP32 variant + - ``25KBPS`` + - ``31K25BPS`` - Not supported by ``esp32_can`` + - ``33KBPS`` - Not supported by ``esp32_can`` + - ``40KBPS`` - Not supported by ``esp32_can`` + - ``50KBPS`` + - ``80KBPS`` - Not supported by ``esp32_can`` + - ``83K3BPS`` - Not supported by ``esp32_can`` + - ``95KBPS`` - Not supported by ``esp32_can`` + - ``100KBPS`` + - ``125KBPS`` - *Default* + - ``200KBPS`` - Not supported by ``esp32_can`` + - ``250KBPS`` + - ``500KBPS`` + - ``1000KBPS`` + +- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when a + CAN frame is received. See :ref:`canbus-on-frame`. + +.. _platforms-canbus: + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +Automations +----------- + +.. _canbus-on-frame: + +``on_frame`` Trigger +******************** + +This automation will be triggered when a CAN frame is received. The variables ``x`` (of type +``std::vector``) containing the frame data, ``can_id`` (of type ``uint32_t``) containing the actual +received CAN ID and ``remote_transmission_request`` (of type ``bool``) containing the corresponding field +from the CAN frame are passed to the automation for use in lambdas. + +.. note:: + + Messages this node sends to the same ID will not show up as received messages. + +.. code-block:: yaml + + canbus: + - platform: ... + on_frame: + - can_id: 43 # the received can_id + then: + - if: + condition: + lambda: 'return (x.size() > 0) ? x[0] == 0x11 : false;' + then: + light.toggle: light1 + - can_id: 0b00000000000000000000001000000 + can_id_mask: 0b11111000000000011111111000000 + use_extended_id: true + remote_transmission_request: false + then: + - lambda: |- + auto pdo_id = can_id >> 14; + switch (pdo_id) + { + case 117: + ESP_LOGD("canbus", "exhaust_fan_duty"); + break; + case 118: + ESP_LOGD("canbus", "supply_fan_duty"); + break; + case 119: + ESP_LOGD("canbus", "supply_fan_flow"); + break; + // to be continued... + } + + +**Configuration variables:** + +- **can_id** (**Required**, int): The CAN ID which, when received, will trigger this automation. +- **can_id_mask** (*Optional*, int): The bit mask to apply to the received CAN ID before trying to match it + with *can_id*. Defaults to ``0x1fffffff`` (all bits of received CAN ID are compared with *can_id*). +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id`` to match on. Defaults to ``false``. +- **remote_transmission_request** (*Optional*, boolean): Whether to run for CAN frames with the "remote + transmission request" bit set or not set. Defaults to not checking (the automation will run for both cases). + +``canbus.send`` Action +********************** + +The CAN bus can transmit frames by means of the ``canbus.send`` action. There are several ways to use it: + +.. code-block:: yaml + + on_...: + - canbus.send: + data: [ 0x10, 0x20, 0x30 ] + canbus_id: my_mcp2515 # optional if you only have 1 canbus device + can_id: 23 # override the can_id configured in the can bus + + on_...: + - canbus.send: [ 0x11, 0x22, 0x33 ] + + - canbus.send: 'hello' + + # Templated; return type must be std::vector + - canbus.send: !lambda return {0x00, 0x20, 0x42}; + +**Configuration variables:** + +- **data** (**Required**, binary data, :ref:`templatable `): Data to transmit, up to eight + bytes/characters are supported by CAN bus per frame. +- **canbus_id** (*Optional*): Sets the CAN bus ID to use for transmitting the frame. Required if you are have multiple + CAN bus platforms defined in your configuration. +- **can_id** (*Optional*, int): Allows overriding the ``can_id`` configured for the CAN bus device. +- **use_extended_id** (*Optional*, boolean): Identifies the type of ``can_id``: + + - ``false``: Standard 11-bit IDs *(default)* + - ``true``: Extended 29-bit IDs + +- **remote_transmission_request** (*Optional*, boolean): Set to send CAN bus frame to request data from another node. + If a certain data length code needs to be sent, include the necessary (dummy) bytes in ``data``. Defaults to ``false``. + +Extended ID +----------- + +Standard IDs and Extended IDs can coexist on the same segment. + +.. note:: + + It is important to know that "standard" and "extended" addresses denote different addresses. For example, + Standard ``0x123`` and Extended ``0x123`` are, in fact, different addresses. + +Decimal or hexadecimal notation may be used for IDs: + +- Standard IDs use ``0x000`` to ``0x7ff`` (hexadecimal) or ``0`` to ``2047`` (decimal) +- Extended IDs use ``0x00000000`` to ``0x1fffffff`` (hexadecimal) or ``0`` to ``536870911`` (decimal) + +This example illustrates how different ID types may be used in your configuration for both transmitting and receiving. + +.. code-block:: yaml + + # Transmission of extended and standard ID 0x100 every second + time: + - platform: sntp + on_time: + - seconds: /1 + then: + - canbus.send: + # Extended ID explicit + use_extended_id: true + can_id: 0x100 + data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] + - canbus.send: + # Standard ID by default + can_id: 0x100 + data: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08] + + canbus: + - platform: ... + can_id: 0x1fff + use_extended_id: true + bit_rate: 125kbps + on_frame: + - can_id: 0x123 + use_extended_id: true + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("CAN extended ID 0x123", "%s", &b[0]); + - can_id: 0x123 + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("CAN standard ID 0x123", "%s", &b[0]); + +Binary Sensor Example +--------------------- + +Given that we have a button connected to a remote CAN node which will send a message to ID ``0x100`` with the payload +``0x1`` for contact closed and ``0x0`` for contact open, this example will look for this message and update the state +of its ``binary_sensor`` accordingly. + +.. code-block:: yaml + + binary_sensor: + - platform: template + name: CAN Bus Button + id: can_bus_button + + canbus: + - platform: ... + can_id: 4 + bit_rate: 125kbps + on_frame: + - can_id: ${0x100} + then: + - lambda: |- + if(x.size() > 0) { + switch(x[0]) { + case 0x0: // button release + id(can_bus_button).publish_state(false); + break; + case 0x1: // button press + id(can_bus_button).publish_state(true); + break; + } + } + +Cover Example +------------- + +In this example, three nodes are connected to the CAN bus: + +- Node 1 sends a one-byte payload to ID ``0x50B`` +- Node 2 sends a one-byte payload to ID ``0x50C`` + + These nodes send the following one-byte payload which is based on the state of a button connected to each of them: + + - 0: Button release + - 1: Button press + - 2: Long press + - 3: Long release + - 4: Double-click + +- Node 3 controls a motor connected to it. It expects a message to ID ``0x51A`` where the one-byte payload is: + + - 0: Off + - 1: Open + - 2: Close + +.. code-block:: yaml + + canbus: + - platform: ... + id: my_canbus + can_id: 4 + bit_rate: 125kbps + on_frame: + - can_id: 0x50c + then: + - lambda: |- + if(x.size() > 0) { + auto call = id(TestCover).make_call(); + switch(x[0]) { + case 0x2: call.set_command_open(); call.perform(); break; // long press + case 0x1: // button press + case 0x3: call.set_command_stop(); call.perform(); break; // long release + case 0x4: call.set_position(1.0); call.perform(); break; // double-click + } + } + - can_id: 0x50b + then: + - lambda: |- + if(x.size() > 0) { + auto call = id(TestCover).make_call(); + switch(x[0]) { + case 0x2: call.set_command_close(); call.perform(); break; // long press + case 0x1: // button press + case 0x3: call.set_command_stop(); call.perform(); break; // long release + case 0x4: call.set_position(0.0); call.perform(); break; // double-click + } + } + + cover: + - platform: time_based + name: Canbus Test Cover + id: TestCover + device_class: shutter + has_built_in_endstop: true + open_action: + - canbus.send: + data: [ 0x01 ] + canbus_id: my_canbus + can_id: 0x51A + open_duration: 2min + close_action: + - canbus.send: + data: [ 0x02 ] + canbus_id: my_canbus + can_id: 0x51A + close_duration: 2min + stop_action: + - canbus.send: + data: [ 0x00 ] + canbus_id: my_canbus + can_id: 0x51A + +See Also +-------- + +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/canbus/mcp2515.rst b/components/canbus/mcp2515.rst new file mode 100644 index 0000000000..eab97d2ebe --- /dev/null +++ b/components/canbus/mcp2515.rst @@ -0,0 +1,79 @@ +MCP2515 +======= + +.. seo:: + :description: Instructions for setting up the MCP2515 CAN bus platform in ESPHome + :image: canbus.svg + :keywords: CAN, MCP2515 + +The MCP2515 communicates with ESPHome via the :ref:`SPI bus `; to use it, you must have at least one +:ref:`SPI bus ` with both the ``mosi_pin`` and ``miso_pin`` defined in your ESPHome configuration. + +The :ref:`mcp2515-wiring` section below illustrates how to wire up your MCP2515. + +.. code-block:: yaml + + # Example configuration entry + canbus: + - platform: mcp2515 + cs_pin: GPIOXX + can_id: 4 + bit_rate: 50kbps + on_frame: + - can_id: 500 + then: + - lambda: |- + std::string b(x.begin(), x.end()); + ESP_LOGD("canid 500", "%s", &b[0] ); + - light.turn_off: light_1 + - can_id: 501 + then: + - light.turn_on: + id: light_1 + brightness: !lambda "return (x.size() > 0) ? (float) x[0]/255 : 0;" + +Configuration variables: +------------------------ + +- **cs_pin** (**Required**, :ref:`Pin Schema `): Is used to signal to a SPI device when it should + listen for data on the SPI bus. Each SPI device has its own ``CS`` line. Sometimes also called ``SS``. +- **clock** (*Optional*, frequency): The frequency of the clock crystal used on the MCP2515 device. One of ``8MHZ``, + ``12MHz``, ``16MHZ`` or ``20MHZ``. Defaults to ``8MHZ``. +- **mode** (*Optional*, enum): Operating mode. One of: + + - ``NORMAL``: Normal operation. *(default)* + - ``LOOPBACK``: Loopback mode is useful for testing your connections to/from the device. + - ``LISTENONLY``: Receive data only. + +- All other options from :ref:`Canbus `. + +.. note:: + + Not all combinations of clock and bitrate are supported. An unsupported combination will not be flagged at + compile time. Check your ESPHome device's logs for a message like ``Invalid frequency/bitrate combination`` + if you suspect this is an issue. + +.. _mcp2515-wiring: + +Wiring options +-------------- + +The easiest approach is to use fully assembled boards and just add one resistor on the MISO line. This runs MOSI, SCK +and CS out of specification which is rarely a problem. + +.. figure:: images/canbus_mcp2515_resistor.png + :align: center + :target: ../_images/canbus_mcp2515_resistor.png + +A more complex option is to properly convert the 3.3V and 5V logic levels with a level shifter. + +.. figure:: images/canbus_mcp2515_txs0108e.png + :align: center + :target: ../_images/canbus_mcp2515_txs0108e.png + +See Also +-------- + +- :doc:`index` +- :apiref:`canbus/canbus.h` +- :ghedit:`Edit` diff --git a/components/climate/anova.rst b/components/climate/anova.rst index 0cfa3eac71..2962f8a671 100644 --- a/components/climate/anova.rst +++ b/components/climate/anova.rst @@ -36,7 +36,7 @@ need to do conversion again within the frontend if you use Fahrenheit. .. code-block:: yaml ble_client: - - mac_address: 11:22:33:aa:bb:cc + - mac_address: XX:XX:XX:XX:XX:XX id: my_anova climate: @@ -48,8 +48,6 @@ need to do conversion again within the frontend if you use Fahrenheit. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the climate device. - **ble_client_id** (**Required**, :ref:`config-id`): The ID of the BLE Client. - **unit_of_measurement** (**Required**, string): Units to use on the device display. 'c' or 'f'. - All other options from :ref:`Climate `. diff --git a/components/climate/bedjet.rst b/components/climate/bedjet.rst index e9cf9d5347..31b7e442cf 100644 --- a/components/climate/bedjet.rst +++ b/components/climate/bedjet.rst @@ -31,7 +31,7 @@ and delegates status updates to individual platform components. esp32_ble_tracker: ble_client: - - mac_address: C4:4F:33:00:00:01 + - mac_address: XX:XX:XX:XX:XX:XX id: bedjet_ble_id1 bedjet: @@ -109,8 +109,6 @@ setting the mode and target temperature. Configuration variables: ************************ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the climate device. - **bedjet_id** (**Required**, :ref:`config-id`): The ID of the Bedjet component. - **heat_mode** (*Optional*, string): The primary heating mode to use for ``HVACMode.HEAT``: @@ -148,8 +146,6 @@ When the BedJet is already on, turning the Fan component off will set the BedJet Configuration variables: ************************ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the fan device. - **bedjet_id** (**Required**, :ref:`config-id`): The ID of the Bedjet component. - Other options from :ref:`Fan `. diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst index 6f67f8f9c5..aaf3cc23fc 100644 --- a/components/climate/climate_ir.rst +++ b/components/climate/climate_ir.rst @@ -10,17 +10,15 @@ control signal, just as the unit's handheld remote controller would. .. figure:: images/climate-ui.png :align: center - :width: 60.0% + :width: 40.0% There is a growing list of compatible units. If your unit is not listed below you should submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ -| Name | Platform name | Supports receiver | +| Supported units | Platform name | Supports receiver | | | | | +=======================================+=====================+======================+ -| :ref:`Arduino-HeatpumpIR` | ``heatpumpir`` | | -+---------------------------------------+---------------------+----------------------+ | Ballu | ``ballu`` | yes | +---------------------------------------+---------------------+----------------------+ | Coolix | ``coolix`` | yes | @@ -39,7 +37,7 @@ submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ | :ref:`GREE` | ``gree`` | | +---------------------------------------+---------------------+----------------------+ -| Hitachi | ``hitachi_ac344`` | yes | +| Hitachi | ``hitachi_ac344``, | yes | | | ``hitachi_ac424`` | | +---------------------------------------+---------------------+----------------------+ | :ref:`LG` | ``climate_ir_lg`` | yes | @@ -50,7 +48,7 @@ submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ | Noblex | ``noblex`` | yes | +---------------------------------------+---------------------+----------------------+ -| TCL112, Fuego | ``tcl112`` | yes | +| Electrolux, TCL, Fuego | ``tcl112`` | yes | +---------------------------------------+---------------------+----------------------+ | :ref:`Toshiba` | ``toshiba`` | yes | +---------------------------------------+---------------------+----------------------+ @@ -62,11 +60,15 @@ submit a feature request (see FAQ). +---------------------------------------+---------------------+----------------------+ | :ref:`ZH/LT-01` | ``zhlt01`` | yes | +---------------------------------------+---------------------+----------------------+ +| :ref:`Arduino-HeatpumpIR` | ``heatpumpir`` | | +| library | | | ++---------------------------------------+---------------------+----------------------+ This component requires that you have configured a :doc:`/components/remote_transmitter`. Due to the unidirectional nature of IR remote controllers, this component cannot determine the actual state of the device and will assume the state of the device is the latest state requested. +The assumed state can be restored at boot. However, when receiver is supported, you can optionally add a :doc:`/components/remote_receiver` component so the climate state will be tracked when it is operated with the original remote @@ -80,13 +82,12 @@ controller unit. carrier_duty_percent: 50% climate: - - platform: coolix # adjust to match your AC unit! + - platform: REPLACEME name: "Living Room AC" Configuration Variables: ------------------------ -- **name** (**Required**, string): The name for the climate device. - **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient temperature. This is only for reporting the current temperature in the frontend. - **supports_cool** (*Optional*, boolean): Enables setting cooling mode for this climate device. Defaults to ``true``. @@ -95,98 +96,15 @@ Configuration Variables: receiver. see: :ref:`ir-receiver_id`. - All other options from :ref:`Climate `. -Advanced Options ----------------- +**Advanced Options** -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter. -.. _heatpumpir: - -Arduino-HeatpumpIR ------------------- - -The ``heatpumpir`` platform supports dozens of manufacturers and hundreds of AC units by utilising the `Arduino-HeatpumpIR library `__. - -This platform should only be used if your AC unit is not supported by any of the other (native) platforms. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. - -This platform utilises the library's generic one-size-fits-all API, which might not line up perfectly with all of the supported AC units. For example, some AC units have more fan speed options than what the generic API supports. - -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``, ``carrier_qlima_1``, ``carrier_qlima_1``, ``daikin``, ``daikin_arc417``, - ``daikin_arc480``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeyaa``, ``greeyac``, ``greeyan``, ``greeyap``, - ``greeyt``, ``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_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``nibe``, ``panasonic_ckp``, ``panasonic_dke``, - ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_aqv12msan``, - ``samsung_fjm``, ``sharp``, ``toshiba``, ``toshiba_daiseikai``, ``zhjg01``, ``zhlt01``. - - -- **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. - - - The ``zhlt01`` protocol supports multiple AC brands: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc. - -.. _ir-receiver_id: - -Using a Receiver ----------------- - -.. note:: - - This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page. - -Optionally, some platforms can listen to data the climate device sends over infrared to update their state ( -for example what mode the device is in). By setting up a :doc:`remote_receiver ` -and passing its ID to the climate platform you can enable this mode. - -When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's -IR receiver. - -.. code-block:: yaml - - # Example configuration entry - remote_receiver: - id: rcvr - pin: - number: GPIOXX - inverted: true - mode: - input: true - pullup: true - # high 55% tolerance is recommended for some remote control units - tolerance: 55% - - climate: - - platform: coolix - name: "Living Room AC" - receiver_id: rcvr +**Specific configuration variables:** .. _climate_ir_lg: -``climate_ir_lg`` Climate -------------------------- - -Additional configuration is available for this platform - - -Configuration variables: +``climate_ir_lg`` **Climate**: - **header_high** (*Optional*, :ref:`config-time`): time for the high part of the header for the LG protocol. Defaults to ``8000us`` - **header_low** (*Optional*, :ref:`config-time`): time for the low part of the header for the LG protocol. Defaults to ``4000us`` @@ -204,31 +122,12 @@ Configuration variables: header_high: 3265us # AC Units from LG in Brazil, for example use these timings header_low: 9856us -.. _daikin_arc: - -``daikin_arc`` Climate -------------------------- - -The Daikin ARC remotes are used by the japanese model of Daikin. - -.. code-block:: yaml - - # Example configuration entry - climate: - - platform: daikin_arc - name: "AC" - sensor: room_temperature - .. _daikin_brc: -``daikin_brc`` Climate -------------------------- +``daikin_brc`` **Climate**: The Daikin BRC remotes are used by the ceiling cassette model of Daikin heatpumps. - -Configuration variables: - - **use_fahrenheit** (*Optional*, boolean): U.S. models of the Daikin BRC remote send the temperature in Fahrenheit, if your remote shows Fahrenheit and can not be changed to Celsius then set this to true. Defaults to ``false``. .. code-block:: yaml @@ -240,29 +139,44 @@ Configuration variables: sensor: room_temperature use_fahrenheit: true - .. _delonghi_ir: -``delonghi`` Climate -------------------------- +``delonghi`` **Climate**: -Currently supports the protocol used by some Delonghi portable units +The ``delonghi`` climate currently supports the protocol used by some Delonghi portable units, known working with Delonghi PAC WE 120HP. -Known working with: +.. _daikin_arc: -- Delonghi PAC WE 120HP +``daikin_arc`` **Climate**: -.. _midea_ir: +The Daikin ARC remotes (``daikin_arc`` climate, ``daikin_arc417``, ``daikin_arc480`` protocols of :ref:`Arduino-HeatpumpIR`) are used by the japanese model of Daikin. -``midea_ir`` Climate -------------------------- +.. _gree_ir: -These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states. +``gree`` **Climate**: -Additional configuration is available for this platform +- **model** (*Required*, string): GREE has a few different protocols depending on model. One of these will work for you. + - ``generic`` + - ``yan`` + - ``yaa`` + - ``yac`` + - ``yac1fb9`` + +.. code-block:: yaml + + # Example configuration entry + climate: + - platform: gree + name: "AC" + sensor: room_temperature + model: yan + +.. _midea_ir: + +``midea_ir`` **Climate**: -Configuration variables: +These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states. - **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``. @@ -282,12 +196,11 @@ Configuration variables: .. _mitsubishi: -``mitsubishi`` Climate ------------------------- +``mitsubishi`` **Climate**: -Additonal configurations available for this platform. +.. note:: -Configuration variables: + - When using this component with Mitsubishi units that only support cooling mode, the Off command may not work. Set **supports_heat** to ``false`` to resolve that issue. - **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to ``3levels`` @@ -325,13 +238,7 @@ Configuration variables: .. _toshiba: -``toshiba`` Climate -------------------- - -Additional configuration is available for this model. - - -Configuration variables: +``toshiba`` **Climate**: - **model** (*Optional*, string): There are two valid models @@ -357,32 +264,18 @@ Configuration variables: - This climate IR component is also known to work with Midea model MAP14HS1TBL and may work with other similar models, as well. (Midea acquired Toshiba's product line and re-branded it.) - .. _whirlpool: +``whirlpool`` **Climate**: -``whirlpool`` Climate ---------------------- - -Additional configuration is available for this model. - - -Configuration variables: - -- **model** (*Optional*, string): There are two valid models +- **model** (*Optional*, string): There are two valid models to choose from: - ``DG11J1-3A``: Temperature range is from 18 to 32 (default) - ``DG11J1-91``: Temperature range is from 16 to 30 .. _whynter: -``whynter`` Climate -------------------------- - -Additional configuration is available for this platform - - -Configuration variables: +``whynter`` **Climate**: - **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``. @@ -396,63 +289,84 @@ Configuration variables: use_fahrenheit: true supports_heat: true +.. _zhlt01: -.. _gree_ir: - +``zhlt01`` **Climate**: -``gree`` Climate ---------------------- +The ``zhlt01`` climate and protocol, based on the ZH/LT-01 remote controller, is used with many locally branded airconditioners, like: Eurom, Chigo, Tristar, Tecnomaster, Elgin, Geant, Tekno, Topair, Proma, Sumikura, JBS, Turbo Air, Nakatomy, Celestial Air, Ager, Blueway, Airlux, etc. -Additional configuration is available for this model. +.. _ir-receiver_id: +Using a Receiver +---------------- -Configuration variables: +.. note:: -- **model** (*Required*, string): GREE has a few different protocols depending on model. One of these will work for you. + This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page. - - ``generic`` - - ``yan`` - - ``yaa`` - - ``yac`` +Optionally, some platforms can listen to data the climate device sends over infrared to update their state ( +for example what mode the device is in). By setting up a :doc:`remote_receiver ` +and passing its ID to the climate platform you can enable this mode. +When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's +IR receiver. .. code-block:: yaml # Example configuration entry + remote_receiver: + id: rcvr + pin: + number: GPIOXX + inverted: true + mode: + input: true + pullup: true + # high 55% tolerance is recommended for some remote control units + tolerance: 55% + climate: - - platform: gree - name: "AC" - sensor: room_temperature - model: yan + - platform: REPLACEME + name: "Living Room AC" + receiver_id: rcvr -.. _zhlt01: +.. _heatpumpir: +Arduino-HeatpumpIR +------------------ -``zhlt01`` Climate ---------------------- - -ZH/LT-01 is a remote control that is used with many locally branded split airconditioners. -Supported brands include: - -- Eurom -- Chigo -- Tristar -- Tecnomaster -- Elgin -- Geant -- Tekno -- Topair -- Proma -- Sumikura -- JBS -- Turbo Air -- Nakatomy -- Celestial Air -- Ager -- Blueway -- Airlux - -No additional configuration is required for this model. +The ``heatpumpir`` platform supports dozens of manufacturers and hundreds of AC units by utilising the `Arduino-HeatpumpIR library `__. + +This platform compiles only under ``arduino`` framework or LibreTiny, and should only be used if your AC unit is not supported by any of the other (native) platforms from above. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. + +This platform utilises the library's generic one-size-fits-all API, which might not line up perfectly with all of the supported AC units. For example, some AC units have more fan speed options than what the generic API supports. + +Additional configuration must be specified for this platform: + +- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: + ``airway``, ``aux``, ``ballu``, ``bgh_aud``, ``carrier_mca``, ``carrier_nqv``, ``carrier_qlima_1``, ``carrier_qlima_1``, ``daikin``, + ``daikin_arc417``, ``daikin_arc480``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeyaa``, ``greeyac``, ``greeyan``, + ``greeyap``, ``greeyt``, ``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_kj``, + ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``nibe``, ``panasonic_altdke``, ``panasonic_ckp``, ``panasonic_dke``, + ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``r51m``, ``samsung_aqv``, ``samsung_aqv12msan``, ``samsung_fjm``, ``sharp``, + ``toshiba``, ``toshiba_daiseikai``, ``vaillantvai8``, ``zhjg01``, ``zhlt01`` +- **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 in ``heatpumpir`` 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. See Also -------- @@ -462,14 +376,15 @@ See Also - :doc:`/components/remote_transmitter` - :doc:`/components/sensor/index` - :apiref:`ballu.h `, -- :apiref:`coolix.h `, + :apiref:`climate_ir_lg.h ` + :apiref:`coolix.h `, :apiref:`daikin.h ` :apiref:`fujitsu_general.h `, + :apiref:`gree.h `, :apiref:`hitachi_ac344.h `, :apiref:`midea_ir.h `, :apiref:`mitsubishi.h `, :apiref:`tcl112.h `, :apiref:`yashima.h ` :apiref:`whirlpool.h ` - :apiref:`climate_ir_lg.h ` - :ghedit:`Edit` diff --git a/components/climate/haier.rst b/components/climate/haier.rst index 7b7e81ed88..9369f191fd 100644 --- a/components/climate/haier.rst +++ b/components/climate/haier.rst @@ -61,7 +61,7 @@ This component requires a :ref:`uart` to be setup. climate: - platform: haier id: haier_ac - protocol: hOn + protocol: hon name: Haier AC uart_id: ac_port wifi_signal: true @@ -100,27 +100,34 @@ This component requires a :ref:`uart` to be setup. level: INFO format: "Alarm deactivated. Code: %d. Message: \"%s\"" args: [ code, message] + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **uart_id** (*Optional*, :ref:`config-id`): ID of the UART port to communicate with AC. -- **protocol** (*Optional*, string): Defines communication protocol with AC. Possible values: hon or smartair2. The default value is smartair2. -- **name** (**Required**, string): The name of the climate device. -- **wifi_signal** (*Optional*, boolean): If true - send wifi signal level to AC. -- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. The default value is 200ms. -- **alternative_swing_control** (*Optional*, boolean): (supported by smartAir2 only) If true - use alternative values to control swing mode. Use only if the original control method is not working for your AC. -- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. The default value: 10. -- **control_method** (*Optional*, list): (supported only by hOn) Defines control method (should be supported by AC). Supported values: MONITOR_ONLY - no control, just monitor status, SET_GROUP_PARAMETERS - set all AC parameters with one command (default method), SET_SINGLE_PARAMETER - set each parameter individually (this method is supported by some new ceiling ACs like AD71S2SM3FA) +- **protocol** (*Optional*, string): Defines communication protocol with AC. Possible values: ``hon`` or ``smartair2``. The default value is ``smartair2``. +- **wifi_signal** (*Optional*, boolean): If ``true`` - send wifi signal level to AC. +- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. The default value is ``200ms``. +- **alternative_swing_control** (*Optional*, boolean): (supported by smartAir2 only) If ``true`` - use alternative values to control swing mode. Use only if the original control method is not working for your AC. +- **status_message_header_size** (*Optional*, int): (supported only by hOn) Define the header size of the status message. Can be used to handle some protocol variations. Use only if you are sure what you are doing. The default value: ``0``. +- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. The default value: ``10``. +- **sensors_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the sensor packet of the status message. Can help with some models of ACs that have bigger sensor packet. The default value: ``22``, minimum value: ``18``. +- **control_method** (*Optional*, list): (supported only by hOn) Defines control method (should be supported by AC). Supported values: ``MONITOR_ONLY`` - no control, just monitor status, ``SET_GROUP_PARAMETERS`` - set all AC parameters with one command (default method), ``SET_SINGLE_PARAMETER`` - set each parameter individually (this method is supported by some new ceiling ACs like AD71S2SM3FA) - **display** (*Optional*, boolean): Can be used to set the AC display off. - **beeper** (*Optional*, boolean): Can be used to disable beeping on commands from AC. Supported only by hOn protocol. -- **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: 'OFF', HEAT_COOL, COOL, HEAT, DRY, FAN_ONLY -- **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: 'OFF', VERTICAL, HORIZONTAL, BOTH -- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: AWAY, BOOST, COMFORT. Possible values for hOn are: AWAY, ECO, BOOST, SLEEP. AWAY preset can be enabled only in HEAT mode, it is disabled by default -- **on_alarm_start** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start` -- **on_alarm_end** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end` +- **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: ``'OFF'``, ``HEAT_COOL``, ``COOL``, ``HEAT``, ``DRY``, ``FAN_ONLY``. +- **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: ``'OFF'``, ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. +- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: ``AWAY``, ``BOOST``, ``COMFORT``. Possible values for hOn are: ``AWAY``, ``ECO``, ``BOOST``, ``SLEEP``. ``AWAY`` preset can be enabled only in ``HEAT`` mode, it is disabled by default. +- **on_alarm_start** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start`. +- **on_alarm_end** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end`. +- **on_status_message** (*Optional*, :ref:`Automation `): Automation to perform when status message received from AC. See :ref:`haier-on_status_message`. - All other options from :ref:`Climate `. Automations @@ -131,36 +138,55 @@ Automations ``on_alarm_start`` Trigger ************************** -This automation will be triggered when a new alarm is activated by AC. The error code of the alarm will be given in the variable "code" (type uint8_t), error message in the variable "message" (type char*). Those variables can be used in :ref:`lambdas ` +This automation will be triggered when a new alarm is activated by AC. The error code of the alarm will be given in the variable ``code`` (``uint8_t``), error message in the variable ``message`` (``const char *``). Those variables can be used in :ref:`lambdas `. .. code-block:: yaml climate: - - protocol: hOn + - protocol: hon on_alarm_start: then: - logger.log: level: WARN format: "Alarm activated. Code: %d. Message: \"%s\"" - args: [ code, message] + args: [ 'code', 'message' ] .. _haier-on_alarm_end: ``on_alarm_end`` Trigger ************************ -This automation will be triggered when a previously activated alarm is deactivated by AC. The error code of the alarm will be given in the variable "code" (type uint8_t), error message in the variable "message" (type char*). Those variables can be used in :ref:`lambdas ` +This automation will be triggered when a previously activated alarm is deactivated by AC. The error code of the alarm will be given in the variable ``code`` (``uint8_t``), error message in the variable ``message`` (``const char *``). Those variables can be used in :ref:`lambdas `. .. code-block:: yaml climate: - - protocol: hOn + - protocol: hon on_alarm_end: then: - logger.log: level: INFO format: "Alarm deactivated. Code: %d. Message: \"%s\"" - args: [ code, message] + args: [ 'code', 'message' ] + +.. _haier-on_status_message: + +``on_status_message`` Trigger +***************************** + +This automation will be triggered when component receives new status packet from AC. Raw message binary (without header and checksum) will be provided in the variable ``data`` (``const char *``), message length in the variable ``data_size`` (``uint8_t``). Those variables can be used in :ref:`lambdas `. +This trigger can be used to support some features that unique for the model and not supported by others. + +.. code-block:: yaml + + climate: + - protocol: hon + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] ``climate.haier.power_on`` Action ********************************* @@ -198,7 +224,7 @@ This action toggles AC power ``climate.haier.display_on`` Action *********************************** -This action turns the AC display on +This action turns the AC display on. .. code-block:: yaml @@ -209,7 +235,7 @@ This action turns the AC display on ``climate.haier.display_off`` Action ************************************ -This action turns the AC display off +This action turns the AC display off. .. code-block:: yaml @@ -220,7 +246,7 @@ This action turns the AC display off ``climate.haier.health_on`` Action ********************************** -Turn on health mode (`UV light sterilization `__) +Turn on health mode (`UV light sterilization `__). .. code-block:: yaml @@ -231,7 +257,7 @@ Turn on health mode (`UV light sterilization `__ +(supported only by hOn) Start `self-cleaning `__. .. code-block:: yaml @@ -301,7 +327,7 @@ Turn off health mode ``climate.haier.start_steri_cleaning`` Action ********************************************* -(supported only by hOn) Start 56°C steri-cleaning +(supported only by hOn) Start 56°C steri-cleaning. .. code-block:: yaml diff --git a/components/climate/images/climate-ui.png b/components/climate/images/climate-ui.png index 10a49b62a3..3ecabbd87e 100644 Binary files a/components/climate/images/climate-ui.png and b/components/climate/images/climate-ui.png differ diff --git a/components/climate/index.rst b/components/climate/index.rst index 5385bfa3e6..8badd6d9bb 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -46,7 +46,8 @@ All climate platforms in ESPHome inherit from the climate configuration schema. Configuration variables: -- **name** (**Required**, string): The name of the climate device. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the climate device. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/climate/midea.rst b/components/climate/midea.rst index cec59359cb..659fddca9a 100644 --- a/components/climate/midea.rst +++ b/components/climate/midea.rst @@ -67,10 +67,8 @@ The ``midea`` component creates a Midea air conditioner climate device. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`../uart` if you want to use multiple UART buses. -- **name** (**Required**, string): The name of the climate device. - **transmitter_id** (*Optional*, :ref:`config-id`): Defined and used automatically when using :doc:`../remote_transmitter` component for IR commands transmit. - **period** (*Optional*, :ref:`config-time`): Minimal period between requests to the appliance. Defaults to ``1s``. - **timeout** (*Optional*, :ref:`config-time`): Request response timeout until next request attempt. Defaults to ``2s``. @@ -86,21 +84,15 @@ Configuration variables: - **outdoor_temperature** (*Optional*): The information for the outdoor temperature sensor. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_usage** (*Optional*): The information for the current power consumption sensor. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity_setpoint** (*Optional*): The information for the humidity indoor sensor (experimental). - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - All other options from :ref:`Climate `. Automations diff --git a/components/climate/pid.rst b/components/climate/pid.rst index c8bdad802c..ec256623e8 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -409,7 +409,6 @@ the calculated PID parameters to help finding good PID values. Configuration variables: -- **name** (**Required**, string): The name of the sensor - **type** (**Required**, string): The value to monitor. One of - ``RESULT`` - The resulting value (sum of P, I, and D terms). @@ -423,6 +422,8 @@ Configuration variables: - ``KI`` - The current factor for the integral term of the PID controller. - ``KD`` - The current factor for the differential term of the PID controller. +- All other options from :ref:`Sensor `. + Advanced options: - **climate_id** (*Optional*, :ref:`config-id`): The ID of the pid climate to get the values from. diff --git a/components/climate/tuya.rst b/components/climate/tuya.rst index c0bf5f8559..707d27f43a 100644 --- a/components/climate/tuya.rst +++ b/components/climate/tuya.rst @@ -60,14 +60,12 @@ Based on this, you can create the climate device as follows: eco: datapoint: 5 temperature: 28 - + Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the climate device. - **supports_heat** (*Optional*, boolean): Specifies if the device has a heating mode. Defaults to ``true``. - **supports_cool** (*Optional*, boolean): Specifies if the device has a cooling mode. Defaults to ``false``. - **switch_datapoint** (**Required**, int): The datapoint id number of the climate switch (device on/off). diff --git a/components/copy.rst b/components/copy.rst index 5cc7191c8a..a2c212d933 100644 --- a/components/copy.rst +++ b/components/copy.rst @@ -26,7 +26,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The binary sensor that should be mirrored. -- **name** (**Required**, string): The name of the binary sensor. - All other options from :ref:`Binary Sensor `. Copy Button @@ -44,7 +43,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The button that should be mirrored. -- **name** (**Required**, string): The name of the button. - All other options from :ref:`Button `. Copy Cover @@ -62,7 +60,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The cover that should be mirrored. -- **name** (**Required**, string): The name of the cover. - All other options from :ref:`Cover `. Copy Fan @@ -80,7 +77,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The fan that should be mirrored. -- **name** (**Required**, string): The name of the fan. - All other options from :ref:`Fan `. Copy Lock @@ -98,7 +94,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The lock that should be mirrored. -- **name** (**Required**, string): The name of the lock. - All other options from :ref:`Lock `. Copy Number @@ -116,7 +111,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The number that should be mirrored. -- **name** (**Required**, string): The name of the number. - All other options from :ref:`Number `. Copy Select @@ -134,7 +128,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The select that should be mirrored. -- **name** (**Required**, string): The name of the select. - All other options from :ref:`Select `. .. _copy-sensor: @@ -154,7 +147,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The sensor that should be mirrored. -- **name** (**Required**, string): The name of the sensor. - All other options from :ref:`Sensor `. Copy Switch @@ -172,7 +164,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The switch that should be mirrored. -- **name** (**Required**, string): The name of the switch. - All other options from :ref:`Switch `. Copy Text Sensor @@ -190,7 +181,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The text sensor that should be mirrored. -- **name** (**Required**, string): The name of the text sensor. - All other options from :ref:`Text Sensor `. Copy Text @@ -208,7 +198,6 @@ Configuration variables: ************************ - **source_id** (**Required**, :ref:`config-id`): The text that should be mirrored. -- **name** (**Required**, string): The name of the number. - All other options from :ref:`Text `. See Also diff --git a/components/cover/am43.rst b/components/cover/am43.rst index c1f05f5056..efef4b14b2 100644 --- a/components/cover/am43.rst +++ b/components/cover/am43.rst @@ -27,7 +27,7 @@ and state of the motor. esp32_ble_tracker: ble_client: - - mac_address: AA:BB:CC:DD:EE:FF + - mac_address: XX:XX:XX:XX:XX:XX id: am43_kitchen cover: @@ -53,13 +53,11 @@ To make use of the battery and light level sensors, see the Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the cover. - **ble_client_id** (**Required**, :ref:`config-id`): The id of the ``ble_client`` entry associated with the device. - **pin** (*Optional*, int): The pin for the device, as set in the app. The default is usually printed on the device. Defaults to ``8888``. - **invert_position** (*Optional*, boolean): Inverts the position value to and from the device. Set if ESPHome is swapping around the open/close state of the cover. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Cover `. diff --git a/components/cover/current_based.rst b/components/cover/current_based.rst index 48408fe03d..440f82f00d 100644 --- a/components/cover/current_based.rst +++ b/components/cover/current_based.rst @@ -62,7 +62,6 @@ operation circuit (typically caused by welded relays). Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the cover. - **open_sensor** (**Required**, :ref:`config-id`): The open current sensor. - **open_action** (**Required**, :ref:`Action `): The action that should be performed when the remote requests the cover to be opened. @@ -95,7 +94,6 @@ Configuration variables: - **malfunction_action** (*Optional*, :ref:`Action `): The action that should be performed when relay malfunction is detected. Malfunction may require device servicing. You can use this action to notify other systems about this situation -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Cover `. Use with Shelly 2.5 diff --git a/components/cover/endstop.rst b/components/cover/endstop.rst index 1637f8d72a..a116f2f08d 100644 --- a/components/cover/endstop.rst +++ b/components/cover/endstop.rst @@ -47,7 +47,6 @@ current position of the cover. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the cover. - **open_action** (**Required**, :ref:`Action `): The action that should be performed when the remote requests the cover to be opened. - **open_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover @@ -66,7 +65,6 @@ Configuration variables: be performed when the remote requests the cover to be closed or an endstop is reached. - **max_duration** (*Optional*, :ref:`config-time`): The maximum duration the cover should be opening or closing. Useful for protecting from dysfunctional endstops. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Cover `. See Also diff --git a/components/cover/feedback.rst b/components/cover/feedback.rst index 2f087be286..0c759eae94 100644 --- a/components/cover/feedback.rst +++ b/components/cover/feedback.rst @@ -4,8 +4,8 @@ Feedback Cover .. seo:: :description: Instructions for setting up feedback covers in ESPHome. -The ``feedback`` cover platform allows you to create covers with position control that -can optionally have feedback from sensors to detect the fully-open and fully-closed states (endstops), +The ``feedback`` cover platform allows you to create covers with position control that +can optionally have feedback from sensors to detect the fully-open and fully-closed states (endstops), and from sensors to detect actual movement (opening/closing). In all the cases the current position is approximated with the time the cover has been moving in a direction. @@ -54,11 +54,11 @@ Endstop Sensors *************** For cases where there are endstops at one or both ends of the cover to detect the fully-open and fully-closed states. -When any of these endstops are reached, an actual state is read and updated and the cover optionally +When any of these endstops are reached, an actual state is read and updated and the cover optionally stopped (via ``stop_action``). The state is not assumed. The extension also handles the case where the cover has builtin endstops, which stops the movement, independently to -the component's logic. In this case, when the cover is fully closed (either if timed based or sensor based) the +the component's logic. In this case, when the cover is fully closed (either if timed based or sensor based) the ``stop_action`` is not triggered. It is a drop-in replacement of :doc:`/components/cover/endstop`. @@ -71,9 +71,9 @@ as soon as an action is triggered) and can also react to commands issued to cove keep states in sync (useful for "smartization" of an existing cover). When there are no specific endstop sensors, and if the cover has builtin endstops and no external control logic, -these movement sensors can optionally be use to infer the endstop state. +these movement sensors can optionally be use to infer the endstop state. When the movement stops (with no stop action being requested) it is assumed that it was caused by -the builtin endstops, and so the close/open state (according to current direction) was reached. +the builtin endstops, and so the close/open state (according to current direction) was reached. This function is activated setting ``infer_endstop`` to True. It can be used to replace a :doc:`/components/cover/current_based`, with some modifications in the yaml. See :ref:`migrating_current_based` @@ -85,16 +85,13 @@ To protect the cover hardware from damage, some safety options are available: - *Max duration*, to protect from faulty endstops - *Direction change wait time*, like an interlock wait time, to protect motors from sudden direction changes -- *Obstacle sensors* and *rollback*, possibility to stop and optionally rollback the cover when some external sensors detects an obstacle +- *Obstacle sensors* and *rollback*, possibility to stop and optionally rollback the cover when some external sensors detects an obstacle (it might be a sensor for high current consumption or an infrared light detecting an obstruction in the path). Configuration variables ----------------------- -- **name** (**Required**, string): The name of the cover. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - **stop_action** (**Required**, :ref:`Action `): The action that should be performed when the remote requests the cover to be closed or an endstop is reached. @@ -132,23 +129,23 @@ Additional options: detectors. In this configuration the ``stop_action`` is not performed when the open or close time is completed and if the cover is commanded to open or close the corresponding actions will be performed without checking current state. Defaults to ``false``. -- **infer_endstop_from_movement** (*Optional*, boolean): Whether to infer endstop state from the movement sensor. +- **infer_endstop_from_movement** (*Optional*, boolean): Whether to infer endstop state from the movement sensor. Requires movement sensors to be set, no endstop sensors and to have builtin endstops. Defaults to ``false``. - **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known. This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead of hiding or disabling one of them. Defaults to ``true`` if no sensor is available to known the actual state of the cover. - **max_duration** (*Optional*, :ref:`config-time`): The maximum duration the cover should be opening - or closing. Useful for protecting from dysfunctional endstops. + or closing. Useful for protecting from dysfunctional endstops. Requires internal, builtin or inferred endstops. - **direction_change_wait_time** (*Optional*, :ref:`config-time`): Stops cover and forces a wait time between changes in direction, - and takes it into account when computing cover position (useful to protect motors). + and takes it into account when computing cover position (useful to protect motors). When this option is set (even at 0s) if an open/close action is invoked while the cover is moving in the opposite direction, - then and intermediate stop action will be invoked to generate the delay. -- **acceleration_wait_time** (*Optional*, :ref:`config-time`): Considers a wait time needed by the cover to actually - start moving after command is issued and takes it into account when computing cover position - (useful for heavy covers with large inertia). - Intended to not accumulate error when doing multiple partial open/close actions). + then and intermediate stop action will be invoked to generate the delay. +- **acceleration_wait_time** (*Optional*, :ref:`config-time`): Considers a wait time needed by the cover to actually + start moving after command is issued and takes it into account when computing cover position + (useful for heavy covers with large inertia). + Intended to not accumulate error when doing multiple partial open/close actions). The open/close duration includes one instance of this delay, as it is the total amount of time from issuing a command to reaching endstop. Defaults to ``0s``. @@ -175,13 +172,13 @@ Most options can be left untouched, but some modifications are needed: If there where any open/close obstacle current threshold defined, a separate binary sensor with that threshold should be defined. The option ``start_sensing_delay`` should be directly replaced by a ``delayed_off`` filter in the movement sensors, or alternatively - hysteresis options could be used to reduce the noise. + hysteresis options could be used to reduce the noise. 2. To have the very same behavior implicit in current based cover, you must always set ``has_built_in_endstop`` and ``infer_endstop_from_movement`` to True. .. code-block:: yaml - # Example original sensor configuration + # Example original sensor configuration cover: - platform: current_based name: "Current Based Cover" @@ -192,7 +189,7 @@ Most options can be left untouched, but some modifications are needed: start_sensing_delay: 0.8s # ...rest of options - # Example converted sensor configuration + # Example converted sensor configuration binary_sensor: - platform: analog_threshold id: open_binary_sensor @@ -216,43 +213,43 @@ Most options can be left untouched, but some modifications are needed: open_obstacle_sensor: open_obstacle_binary_sensor #... rest of options -3. Malfunction detection is not directly supported by Feedback Cover, as the malfunction was very narrowly defined to a specific use case - (while in other hardware configurations, the same situation is perfectly valid). +3. Malfunction detection is not directly supported by Feedback Cover, as the malfunction was very narrowly defined to a specific use case + (while in other hardware configurations, the same situation is perfectly valid). The malfunction alerted specifically when there was current in the opposite direction of the requested operation (possibly due to a relay welded). This detection can still be achieved by putting the logic directly in the switch, (or whatever needed according to your specific use case). .. code-block:: yaml - # Example original malfunction configuration + # Example original malfunction configuration cover: - platform: current_based - close_sensor: close_current + close_sensor: close_current close_action: - switch.turn_on: open_relay - open_sensor: open_current + open_sensor: open_current open_action: - - switch.turn_on: open_relay - + - switch.turn_on: open_relay + malfunction_detection: true malfunction_action: - - logger.log: "Malfunction detected. Relay welded." - #... rest of options + - logger.log: "Malfunction detected. Relay welded." + #... rest of options - # Example converted malfunction configuration + # Example converted malfunction configuration switch: - platform: gpio id: open_relay - #... rest of options + #... rest of options on_turn_off: - delay: 200ms #allow for switching time and any discharge - if: - condition: + condition: binary_sensor.is_on: open_binary_sensor - # alternative can check directly + # alternative can check directly # on sensor.in_range open_current then: - - logger.log: "Malfunction detected. Relay welded." + - logger.log: "Malfunction detected. Relay welded." diff --git a/components/cover/index.rst b/components/cover/index.rst index 28a5efc7f8..3ac2e9b667 100644 --- a/components/cover/index.rst +++ b/components/cover/index.rst @@ -28,7 +28,8 @@ All cover config schemas inherit from this schema - you can set these keys for c Configuration variables: -- **name** (**Required**, string): The name for the cover. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the cover. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/cover/template.rst b/components/cover/template.rst index 9d6b82692f..908f860aca 100644 --- a/components/cover/template.rst +++ b/components/cover/template.rst @@ -43,7 +43,6 @@ Possible return values for the optional lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the cover. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated repeatedly to get the current state of the cover. - **open_action** (*Optional*, :ref:`Action `): The action that should @@ -71,7 +70,6 @@ Configuration variables: be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific position. The desired position is available in the lambda in the ``pos`` variable. Useless if `has_position` is not set to ``true``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Cover `. .. _cover-template-publish_action: diff --git a/components/cover/time_based.rst b/components/cover/time_based.rst index d879948227..41c84c84c1 100644 --- a/components/cover/time_based.rst +++ b/components/cover/time_based.rst @@ -7,7 +7,8 @@ Time Based Cover The ``time_based`` cover platform allows you to create covers with position control that do not have any position feedback. The state of the cover is thus always an assumed one, the current -position is approximated with the time the cover has been moving in a direction. +position is approximated with the time the cover has been moving in a direction. The state +of the cover can be restored at node reboot. .. figure:: images/more-info-ui.png :align: center @@ -36,7 +37,6 @@ position is approximated with the time the cover has been moving in a direction. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the cover. - **open_action** (**Required**, :ref:`Action `): The action that should be performed when the remote requests the cover to be opened. - **open_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover @@ -52,17 +52,16 @@ Configuration variables: detectors. In this configuration the ``stop_action`` is not performed when the open or close time is completed and if the cover is commanded to open or close the corresponding actions will be performed without checking current state. Defaults to ``false``. -- **manual_control** (*Optional*, boolean): For covers with manual external controls. With this - configuration if the cover is commanded to open or close the corresponding actions will be - performed even if the current state fully open or fully closed matches desired state, then - ``stop_action`` will be called after the full duration of the action elapses. +- **manual_control** (*Optional*, boolean): For covers with manual external controls. With this + configuration if the cover is commanded to open or close the corresponding actions will be + performed even if the current state fully open or fully closed matches desired state, then + ``stop_action`` will be called after the full duration of the action elapses. The current state will then be relearned upon completion. - It's recommended to set ``assumed_state`` to true so the cover control button aren't disabled - in the interface. Defaults to ``false``. + It's recommended to set ``assumed_state`` to true so the cover control button aren't disabled + in the interface. Defaults to ``false``. - **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known. This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead of hiding or disabling one of them. Defaults to ``true``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Cover `. @@ -71,12 +70,6 @@ Configuration variables: The stop button on the UI is always enabled even when the cover is stopped and each press on the button will cause the ``stop_action`` to be performed. -.. note:: - - The state of the cover can be restored from flash after a node reboot, with - ``esp8266_restore_from_flash: true`` option set. - See :doc:`esp8266_restore_from_flash ` for details. - Handle stop_action: ------------------------ For some cover controllers, separate switches for UP and DOWN action are used while a stop is issued when sending a counter command. @@ -84,7 +77,7 @@ This can be handled at the **stop_action** by using the following lambda functio .. code-block:: yaml - stop_action: + stop_action: - lambda: !lambda |- if (id(cover).get_last_operation() == CoverOperation::COVER_OPERATION_OPENING) { // Cover is currently opening @@ -94,7 +87,7 @@ This can be handled at the **stop_action** by using the following lambda functio id(cover_button_up).press(); } -Be aware that ``get_last_operation`` will only return the last opening or closing operation, but not the last idle operation. +Be aware that ``get_last_operation`` will only return the last opening or closing operation, but not the last idle operation. This issue is tracked `here `_. See Also diff --git a/components/cover/tuya.rst b/components/cover/tuya.rst index 33f1fa4793..2cb13faa83 100644 --- a/components/cover/tuya.rst +++ b/components/cover/tuya.rst @@ -31,8 +31,6 @@ Now you can create the cover. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the cover. - **control_datapoint** (*Optional*, int): The datapoint id number for sending control commands. - **position_datapoint** (**Required**, int): The datapoint id number of the cover position value. - **position_report_datapoint** (*Optional*, int): The datapoint id number of the cover position report value, if separate from position_datapoint. diff --git a/components/datetime/index.rst b/components/datetime/index.rst index 0580442d76..60ec0001b2 100644 --- a/components/datetime/index.rst +++ b/components/datetime/index.rst @@ -29,7 +29,8 @@ All datetime in ESPHome have a name and an optional icon. Configuration variables: -- **name** (**Required**, string): The name for the datetime. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the datetime. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/dfplayer.rst b/components/dfplayer.rst index 672cc46157..512559c1e7 100644 --- a/components/dfplayer.rst +++ b/components/dfplayer.rst @@ -345,19 +345,19 @@ Sample code logger.log: 'Playback finished event' api: - services: - - service: dfplayer_next + actions: + - action: dfplayer_next then: - dfplayer.play_next: - - service: dfplayer_previous + - action: dfplayer_previous then: - dfplayer.play_previous: - - service: dfplayer_play + - action: dfplayer_play variables: file: int then: - dfplayer.play: !lambda 'return file;' - - service: dfplayer_play_loop + - action: dfplayer_play_loop variables: file: int loop_: bool @@ -365,7 +365,7 @@ Sample code - dfplayer.play: file: !lambda 'return file;' loop: !lambda 'return loop_;' - - service: dfplayer_play_folder + - action: dfplayer_play_folder variables: folder: int file: int @@ -374,7 +374,7 @@ Sample code folder: !lambda 'return folder;' file: !lambda 'return file;' - - service: dfplayer_play_loop_folder + - action: dfplayer_play_loop_folder variables: folder: int then: @@ -382,54 +382,54 @@ Sample code folder: !lambda 'return folder;' loop: true - - service: dfplayer_set_device_tf + - action: dfplayer_set_device_tf then: - dfplayer.set_device: TF_CARD - - service: dfplayer_set_device_usb + - action: dfplayer_set_device_usb then: - dfplayer.set_device: USB - - service: dfplayer_set_volume + - action: dfplayer_set_volume variables: volume: int then: - dfplayer.set_volume: !lambda 'return volume;' - - service: dfplayer_set_eq + - action: dfplayer_set_eq variables: preset: int then: - dfplayer.set_eq: !lambda 'return static_cast(preset);' - - service: dfplayer_sleep + - action: dfplayer_sleep then: - dfplayer.sleep - - service: dfplayer_reset + - action: dfplayer_reset then: - dfplayer.reset - - service: dfplayer_start + - action: dfplayer_start then: - dfplayer.start - - service: dfplayer_pause + - action: dfplayer_pause then: - dfplayer.pause - - service: dfplayer_stop + - action: dfplayer_stop then: - dfplayer.stop - - service: dfplayer_random + - action: dfplayer_random then: - dfplayer.random - - service: dfplayer_volume_up + - action: dfplayer_volume_up then: - dfplayer.volume_up - - service: dfplayer_volume_down + - action: dfplayer_volume_down then: - dfplayer.volume_down diff --git a/components/display/index.rst b/components/display/index.rst index 4db857c2c1..5d5c02af12 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -8,14 +8,25 @@ Display Component The ``display`` component houses ESPHome's powerful rendering and display engine. Fundamentally, there are these types of displays: -- Text based displays like :doc:`7-Segment displays ` or +- Character displays like :doc:`7-Segment displays ` or :doc:`LCD displays `. -- Graphical serial displays like :doc:`nextion` that have their own processors for rendering. +- Serial displays like :doc:`nextion` that have their own processors for graphics rendering. - Graphical binary displays which can toggle ON/OFF any pixel, like :doc:`E-Paper `, + :doc:`OLED ` or :doc:`TFT ` displays. -For the last type, ESPHome has a powerful rendering engine that can do -many things like draw some basic shapes, print text with any font you want, or even show images. +For graphical displays, which offer the greatest flexibility, there are two options: + +- ESPHome's :ref:`own rendering engine ` +- :doc:`LVGL ` - Light and Versatile Graphics Library + +.. _display-engine: + +Display Rendering Engine +------------------------ + +ESPHome's own powerful rendering engine can handle many common tasks such as drawing basic shapes, +printing text with fonts of your choice, or even rendering images. To achieve all this flexibility displays tie in directly into ESPHome's :ref:`lambda system `. So when you want to write some text or sensor values to the screen you will be writing in C++ code @@ -24,11 +35,6 @@ using an API that is designed to - be simple and to be used without programming experience - but also be flexible enough to work with more complex tasks like displaying an analog clock. -.. _display-engine: - -Display Rendering Engine ------------------------- - In this section we will be discussing how to use ESPHome's display rendering engine from ESPHome and some basic commands. Please note that this only applies to displays that can control each pixel individually. @@ -459,364 +465,6 @@ Configuration variables: RGB displays use red, green, and blue, while grayscale displays may use white. -.. _display-graphs: - -Graph Component ---------------- - -You can display a graph of a sensor value(s) using this component. The states used for the graph are stored in -memory at the time the sensor updates and will be lost when the device reboots. - -Examples: - -.. figure:: images/display_rendering_graph.png - :align: center - -Graph component with options for grids, border and line-types. - -.. code-block:: yaml - - graph: - # Show bare-minimum auto-ranged graph - - id: single_temperature_graph - sensor: my_temperature - duration: 1h - width: 151 - height: 51 - # Show multi-trace graph - - id: multi_temperature_graph - duration: 1h - x_grid: 10min - y_grid: 1.0 # degC/div - width: 151 - height: 51 - traces: - - sensor: my_inside_temperature - line_type: DASHED - line_thickness: 2 - color: my_red - - sensor: my_outside_temperature - line_type: SOLID - continuous: true - line_thickness: 3 - color: my_blue - - sensor: my_beer_temperature - line_type: DOTTED - line_thickness: 2 - color: my_green - -Configuration variables: - -- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the graph later - in your display code. -- **width** (**Required**, int): The graph width in pixels -- **height** (**Required**, int): The graph height in pixels -- **duration** (**Required**, :ref:`config-time`): The total graph history duration. -- **border** (*Optional*, boolean): Specifies if a border will be drawn around the graph. Default is True. -- **x_grid** (*Optional*): Specifies the time per division. If not specified, no vertical grid will be drawn. -- **y_grid** (*Optional*, float): Specifies the number of units per division. If not specified, no horizontal grid will be drawn. -- **max_range** (*Optional*): Specifies the maximum Y-axis range. -- **min_range** (*Optional*): Specifies the minimum Y-axis range. -- **max_value** (*Optional*): Specifies the maximum Y-axis value. -- **min_value** (*Optional*): Specifies the minimum Y-axis value. -- **traces** (*Optional*): Use this to specify more than a single trace. - -Trace specific fields: - -- **sensor** (*Optional*, :ref:`config-id`): The sensor value to plot -- **line_thickness** (*Optional*): Defaults to 3 -- **line_type** (*Optional*): Specifies the plot line-type. Can be one of the following: ``SOLID``, ``DOTTED``, ``DASHED``. Defaults to ``SOLID``. -- **continuous** (*Optional*): connects the individual points to make a continuous line. Defaults to ``false``. -- **color** (*Optional*): Sets the color of the sensor trace. - -And then later in code: - -.. code-block:: yaml - - display: - - platform: ... - # ... - pages: - - id: page1 - lambda: |- - // Draw the graph at position [x=10,y=20] - it.graph(10, 20, id(single_temperature_graph)); - - id: page2 - lambda: |- - // Draw the graph at position [x=10,y=20] - it.graph(10, 20, id(multi_temperature_graph), my_yellow); - - color: - - id: my_red - red: 100% - green: 0% - blue: 0% - - id: my_green - red: 0% - green: 100% - blue: 0% - - id: my_blue - red: 0% - green: 0% - blue: 100% - - id: my_yellow - red: 100% - green: 100% - blue: 0% -.. note:: - - Here are some things to note: - - Setting ``y_grid`` will expand any specified range to the nearest multiple of grid spacings. - - Axis labels are currently not possible without manually placing them. - - The grid and border color is set with it.graph(), while the traces are defined separately. - - -.. _display-qrcode: - -QR Code Component ------------------ - -Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays. - -.. code-block:: yaml - - qr_code: - - id: homepage_qr - value: esphome.io - -Configuration variables: - -- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the QR-code later - in your display code. -- **value** (**Required**, string): The string which you want to encode in the QR-code. -- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values: - - - ``LOW``: The QR Code can tolerate about 7% erroneous codewords - - ``MEDIUM``: The QR Code can tolerate about 15% erroneous codewords - - ``QUARTILE``: The QR Code can tolerate about 25% erroneous codewords - - ``HIGH``: The QR Code can tolerate about 30% erroneous codewords - -To draw the QR-code, call the ``it.qr_code`` function from your render lambda: - -.. code-block:: yaml - - display: - - platform: ... - # ... - pages: - - id: page1 - lambda: |- - // Draw the QR-code at position [x=50,y=0] with white color and a 2x scale - it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2); - - // Draw the QR-code in the center of the screen with white color and a 2x scale - auto size = id(homepage_qr).get_size() * 2; // Multiply by scale - auto x = (it.get_width() / 2) - (size / 2); - auto y = (it.get_height() / 2) - (size / 2); - it.qr_code(x, y, id(homepage_qr), Color(255,255,255), 2); - - -.. _display-image: - -Images ------- - -Use this component to store graphical images on the device, you can then draw the images on compatible displays. - -.. code-block:: yaml - - image: - - file: "image.png" - id: my_image - resize: 100x100 - -.. code-block:: yaml - - image: - - file: mdi:alert-outline - id: alert - resize: 80x80 - -.. code-block:: yaml - - image: - - file: https://esphome.io/_images/logo.png - id: esphome_logo - resize: 200x162 - -Configuration variables: - -- **file** (**Required**, string): - - - **Local files**: The path (relative to where the .yaml file is) of the image file. - - **Material Design Icons**: Specify the `Material Design Icon `_ - id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration. - - **Remote files**: The URL of the image file. - -- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later - in your display code. -- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT`` - and preserve the aspect ratio. -- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local images and ``TRANSPARENT_BINARY`` for MDIs. - - - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit - per pixel, 8 pixels per byte. - - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel - will be the on color. Uses 1 bit per pixel, 8 pixels per byte. - - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. - - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. - - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. - - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. - -- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. - -- **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here `__ and `here `__. - - - ``NONE``: Every pixel convert to its nearest color. - - ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels. - -.. note:: - - To use images you will need to have the python ``pillow`` package installed. - If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be - installed. Otherwise you need to install it using ``pip install pillow``. - Additionally, if you want to use SVG images (including MDI images), you will additionally need to have the python ``cairosvg`` package installed. - If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should also already be - installed. Otherwise you need to install it using ``pip install cairosvg``. - -And then later in code: - -.. code-block:: yaml - - display: - - platform: ... - # ... - lambda: |- - // Draw the image my_image at position [x=0,y=0] - it.image(0, 0, id(my_image)); - -By default, ESPHome will *align* the image at the top left. That means if you enter the coordinates -``[0,10]`` for your image, the top left of the image will be at ``[0,10]``. If you want to draw some -image at the right side of the display, it is however sometimes useful to choose a different **image alignment**. -When you enter ``[0,10]`` you're really telling ESPHome that it should position the **anchor point** of the image -at ``[0,10]``. When using a different alignment, like ``TOP_RIGHT``, the image will be positioned left of the anchor -pointed, so that, as the name implies, the anchor point is a the *top right* corner of the image. - -.. code-block:: yaml - - display: - - platform: ... - # ... - lambda: |- - // Aligned on left by default - it.image(0, 0, id(my_image)); - - // Aligned on right edge - it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT); - -For binary images the ``image`` method accepts two additional color parameters which can -be supplied to modify the color used to represent the on and off bits respectively. e.g. - -.. code-block:: yaml - - display: - - platform: ... - # ... - lambda: |- - // Draw the image my_image at position [x=0,y=0] - // with front color red and back color blue - it.image(0, 0, id(my_image), id(red), id(blue)); - - // Aligned on right edge - it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue)); - -You can also use this to invert images in two colors display, use ``COLOR_OFF`` then ``COLOR_ON`` -as the additional parameters. - -Animation ---------- - -Allows to use animated images on displays. Animation inherits all options from the image component. -It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_frame()`` to change the shown picture of a gif. - -.. code-block:: yaml - - animation: - - file: "animation.gif" - id: my_animation - resize: 100x100 - -The animation can be rendered just like the image component with the ``image()`` function of the display component. - -To show the next frame of the animation call ``id(my_animation).next_frame()``, to show the previous picture use ``id(my_animation).prev_frame()``. To show a specific picture use ``id(my_animation).set_frame(int frame)``. -This can be combined with all Lambdas: - -.. code-block:: yaml - - display: - - platform: ... - # ... - lambda: |- - //Ingress shown animation Frame. - id(my_animation).next_frame(); - // Draw the animation my_animation at position [x=0,y=0] - it.image(0, 0, id(my_animation), COLOR_ON, COLOR_OFF); - -Additionally, you can use the ``animation.next_frame``, ``animation.prev_frame`` or ``animation.set_frame`` actions. - -.. note:: - - To draw the next animation independent of Display draw cycle use an interval: - - .. code-block:: yaml - - interval: - - interval: 5s - then: - animation.next_frame: my_animation - - -Configuration variables: -^^^^^^^^^^^^^^^^^^^^^^^^ - -- **file** (**Required**, string): The path (relative to where the .yaml file is) of the gif file. -- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the animation later - in your display code. -- **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT`` - and preserve the aspect ratio. -- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``. - - - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit - per pixel, 8 pixels per byte. - - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel - will be the on color. Uses 1 bit per pixel, 8 pixels per byte. - - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. - - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. - - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. - - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. - -- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. -- **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over. - - - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation. - - **end_frame** (*Optional*, int): The last frame to show in the loop; when this frame is reached it will loop back to ``start_frame``. Defaults to the last frame in the animation. - - **repeat** (*Optional*, int): Specifies how many times the loop will run. When the count is reached, the animation will continue with the next frame after ``end_frame``, or restart from the beginning if ``end_frame`` was the last frame. Defaults to "loop forever". - -Actions: -^^^^^^^^ - -- **animation.next_frame**: Moves the animation to the next frame. This is equivalent to the ``id(my_animation).next_frame();`` lambda call. - - - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. - -- **animation.prev_frame**: Moves the animation to the previous frame. This is equivalent to the ``id(my_animation).prev_frame();`` lambda call. - - - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. - -- **animation.set_frame**: Moves the animation to a specific frame. This is equivalent to the ``id(my_animation).set_frame(frame);`` lambda call. - - - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. - - **frame** (**Required**, int): The frame index to show next. .. _display-pages: @@ -963,7 +611,13 @@ See Also -------- - :apiref:`display/display_buffer.h` +- :doc:`LVGL ` - :ref:`Fonts ` +- :ref:`Graph Component ` +- :ref:`QR Code Component ` +- :ref:`Image Component ` +- :ref:`Animation Component ` +- :ref:`Online Image ` - :ghedit:`Edit` .. toctree:: diff --git a/components/display/inkplate6.rst b/components/display/inkplate6.rst index 0ef6d520d2..5d1b7741ab 100644 --- a/components/display/inkplate6.rst +++ b/components/display/inkplate6.rst @@ -180,7 +180,7 @@ Wi-Fi, API, and OTA configuration. - platform: adc id: battery_voltage update_interval: never - attenuation: 11db + attenuation: 12db pin: 35 - platform: template name: "Inkplate Battery Voltage" diff --git a/components/display/nextion.rst b/components/display/nextion.rst index 09d8a85f92..d551f6c9f5 100644 --- a/components/display/nextion.rst +++ b/components/display/nextion.rst @@ -115,8 +115,8 @@ The developer tools in Home Assistant can be used to trigger the update. The bel .. code-block:: yaml api: - services: - - service: update_nextion + actions: + - action: update_nextion then: - lambda: 'id(nextion1)->upload_tft();' @@ -151,8 +151,8 @@ The developer tools in Home Assistant can be used to trigger the update. The bel # Enable Home Assistant API api: - services: - - service: set_nextion_sensor + actions: + - action: set_nextion_sensor variables: nextion_type: int name: string @@ -160,7 +160,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel then: - lambda: |- id(nextion1).set_nextion_sensor_state(nextion_type,name,state); - - service: set_nextion_text + - action: set_nextion_text variables: name: string state: string diff --git a/components/display/pvvx_mithermometer.rst b/components/display/pvvx_mithermometer.rst index 799b25333c..05cc787231 100644 --- a/components/display/pvvx_mithermometer.rst +++ b/components/display/pvvx_mithermometer.rst @@ -29,7 +29,7 @@ The firmware configuration can be changed via browser using `TelinkMiFlasher.htm esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display display: @@ -139,12 +139,12 @@ The following example display the sensor states of a MiFlora sensor on a pvvx di esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -154,7 +154,7 @@ The following example display the sensor states of a MiFlora sensor on a pvvx di battery_voltage: name: "PVVX Battery-Voltage" - platform: xiaomi_hhccjcy01 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY01 Temperature" id: miflora_temperature @@ -199,12 +199,12 @@ The following example will synchronized the time of the pvvx device once a day. esp32_ble_tracker: ble_client: - - mac_address: "A4:C1:38:B1:CD:7F" + - mac_address: XX:XX:XX:XX:XX:XX id: pvvx_ble_display sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: diff --git a/components/display/sdl.rst b/components/display/sdl.rst index c075dfc773..3e30ad60c8 100644 --- a/components/display/sdl.rst +++ b/components/display/sdl.rst @@ -17,14 +17,13 @@ than compiling for and flashing a microcontroller target system. .. code-block:: yaml # Example configuration entry + esphome: + name: sdl + host: - mac_address: "62:23:45:AF:B3:DD" display: - platform: sdl - id: sdl_display - update_interval: 1s - auto_clear_enabled: false show_test_card: true dimensions: width: 450 @@ -95,13 +94,7 @@ Linux instructions above. See https://learn.microsoft.com/en-us/windows/wsl/inst Build and run ------------- -The ``esphome`` command will not automatically run the build file on the ``host`` platform. Instead use ``esphome compile yourfile.yaml`` -then locate the executable file called ``program`` within the ``.esphome`` build tree: - -.. code-block:: sh - - `find .esphome -name program` - +The ``esphome run yourfile.yaml`` command will compile and automatically run the build file on the ``host`` platform. See Also -------- diff --git a/components/esp32.rst b/components/esp32.rst index 5fae8a97af..e714b21de8 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -18,7 +18,7 @@ Configuration variables: - **board** (**Required**, string): The PlatformIO board ID that should be used. Choose the appropriate board from - `this list `__ (the icon next to the name + `this list `__ (the icon next to the name can be used to copy the board ID). *This only affects pin aliases, flash size and some internal settings*, if unsure choose a generic board from Espressif such as ``esp32dev``. - **framework** (*Optional*): Options for the underlying framework used by ESPHome. @@ -32,10 +32,6 @@ Configuration variables: ``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. Defaults to the variant that is detected from the board; if a board that's unknown to ESPHome is used, this option is mandatory. -.. note:: - - Support for ESP32 variants such as the S2, S3 and C3 is still in development and there could be issues. - GPIO Pin Numbering ------------------ diff --git a/components/esp32_ble_tracker.rst b/components/esp32_ble_tracker.rst index 818f8d513c..1474e429a0 100644 --- a/components/esp32_ble_tracker.rst +++ b/components/esp32_ble_tracker.rst @@ -14,7 +14,7 @@ the MAC address of a device and track it using ESPHome. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -26,15 +26,15 @@ the MAC address of a device and track it using ESPHome. binary_sensor: - platform: ble_presence - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "ESP32 BLE Presence Google Home Mini" sensor: - platform: ble_rssi - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "BLE Google Home Mini RSSI value" - platform: xiaomi_hhccjcy01 - mac_address: 94:2B:FF:5C:91:61 + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi MiFlora Temperature" moisture: @@ -46,7 +46,7 @@ the MAC address of a device and track it using ESPHome. battery_level: name: "Xiaomi MiFlora Battery Level" - platform: xiaomi_lywsdcgq - mac_address: 7A:80:8E:19:36:BA + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi MiJia Temperature" humidity: @@ -116,9 +116,9 @@ This automation will be triggered when a Bluetooth advertising is received. A va esp32_ble_tracker: on_ble_advertise: - - mac_address: - - 11:11:11:11:11:11 - - 22:22:22:22:22:22 + - mac_address: + - XX:XX:XX:XX:XX:XX + - XX:XX:XX:XX:XX:XX then: - lambda: |- ESP_LOGD("ble_adv", "New BLE device"); @@ -159,7 +159,7 @@ variable ``x`` of type ``std::vector`` is passed to the automation for esp32_ble_tracker: on_ble_manufacturer_data_advertise: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX manufacturer_id: 0590 then: - lambda: |- @@ -190,7 +190,7 @@ variable ``x`` of type ``std::vector`` is passed to the automation for esp32_ble_tracker: on_ble_service_data_advertise: - - mac_address: 11:22:33:44:55:66 + - mac_address: XX:XX:XX:XX:XX:XX service_uuid: 181A then: - lambda: 'id(ble_sensor).publish_state(x[0]);' diff --git a/components/esphome.rst b/components/esphome.rst index ec0217c502..21837971a3 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -239,12 +239,12 @@ custom components. - Wire # use the git version of a library used by a component - - esphome/Improv=https://github.com/improv-wifi/sdk-cpp.git#v1.0.0 + - Improv=https://github.com/improv-wifi/sdk-cpp.git#v1.0.0 The most common usage of this option is to include third-party libraries that are available in the `PlatformIO registry `__. They can be added by listing their name under this option. It is also possible to use specific versions, or to fetch libraries from a file or git repository. ESPHome accepts the same syntax as the -`pio lib install `__ command. +`lib_deps `__ option. Using ``=`` syntax, it is possible to override the version used for libraries that are automatically added by one of ESPHome's components. This can be useful during development to make ESPHome use a custom fork of a library. diff --git a/components/event/index.rst b/components/event/index.rst index 3d5d222aa8..b1cc7e4f25 100644 --- a/components/event/index.rst +++ b/components/event/index.rst @@ -48,8 +48,8 @@ Configuration variables: One of ``id`` or ``name`` is required. -- **id** (**Required**, :ref:`config-id`): Manually specify the ID used for code generation, allowing for further customization or interaction with this event within ESPHome scripts or lambda functions. -- **name** (**Required**, string): The name for the event. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the event. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/fan/binary.rst b/components/fan/binary.rst index c7328c5e7b..69414e3518 100644 --- a/components/fan/binary.rst +++ b/components/fan/binary.rst @@ -27,13 +27,10 @@ Configuration variables: - **output** (**Required**, :ref:`config-id`): The id of the binary output component to use for this fan. -- **name** (**Required**, string): The name for this fan. - **oscillation_output** (*Optional*, :ref:`config-id`): The id of the :ref:`output ` to use for the oscillation state of this fan. Default is empty. - **direction_output** (*Optional*, :ref:`config-id`): The id of the :ref:`output ` to use for the direction state of the fan. Default is empty. -- **id** (*Optional*, :ref:`config-id`): Manually specify - the ID used for code generation. - All other options from :ref:`Fan Component `. See Also diff --git a/components/fan/hbridge.rst b/components/fan/hbridge.rst index 7e4295f8c0..120fcb1733 100644 --- a/components/fan/hbridge.rst +++ b/components/fan/hbridge.rst @@ -46,8 +46,6 @@ Configuration variables: - **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. The value is used to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100`` will allow 1% increments in the output. Defaults to ``100``. -- **name** (**Required**, string): The name for this fan. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`). - All other options from :ref:`Fan Component `. diff --git a/components/fan/index.rst b/components/fan/index.rst index 9e68a0d171..c0e34ef058 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -26,7 +26,8 @@ Base Fan Configuration Configuration variables: -- **name** (**Required**, string): The name of the fan. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the fan. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/fan/speed.rst b/components/fan/speed.rst index e23f0b009b..28af893b8a 100644 --- a/components/fan/speed.rst +++ b/components/fan/speed.rst @@ -23,7 +23,6 @@ supports speed settings. Configuration variables: ------------------------ -- **name** (*Optional*, string): The name for this fan. - **output** (**Required**, :ref:`config-id`): The id of the :ref:`float output ` to use for this fan. - **oscillation_output** (*Optional*, :ref:`config-id`): The id of the :ref:`output ` to use for the oscillation state of this fan. Default is empty. @@ -32,7 +31,6 @@ Configuration variables: - **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. The value is used to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100`` will allow 1% increments in the output. Defaults to ``100``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`). - All other options from :ref:`Fan Component `. diff --git a/components/fan/template.rst b/components/fan/template.rst index 75c36ce8ed..19a9e04a59 100644 --- a/components/fan/template.rst +++ b/components/fan/template.rst @@ -25,8 +25,6 @@ The ``template`` fan platform lets you create a fan interface using only trigger Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (*Optional*, string): The name for this fan. - **has_direction** (*Optional*, boolean): Indicates if there should be a control for direction. Default is ``false``. - **has_oscillating** (*Optional*, boolean): Indicates if there should be a control for oscillating. Default is ``false``. - **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. Default is only on/off. diff --git a/components/fan/tuya.rst b/components/fan/tuya.rst index 8eb3136f4c..7bfe09cbc6 100644 --- a/components/fan/tuya.rst +++ b/components/fan/tuya.rst @@ -49,8 +49,6 @@ Based on this, you can create the fan as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the fan. - **speed_datapoint** (**Required**, int): The datapoint id number of the fan speed. - **switch_datapoint** (**Required**, int): The datapoint id number of the fan switch. - **oscillation_datapoint** (*Optional*, int): The datapoint id number of the oscillation diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst index cdba660740..e7b9b60512 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -83,9 +83,7 @@ Binary Sensor Configuration variables: -- **name** (**Required**, string): The name for the enrolling binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Binary Sensor `. +- All options from :ref:`Binary Sensor `. Sensor @@ -475,8 +473,8 @@ All actions Test setup ---------- -With the following code you can quickly setup a node and use Home Assistant's service in the developer tools. -E.g. for calling ``fingerprint_grow.enroll`` select the service ``esphome.test_node_enroll`` and in service data enter +With the following code you can quickly setup a node and use Home Assistant's action in the developer tools. +E.g. for calling ``fingerprint_grow.enroll`` select the action ``esphome.test_node_enroll`` and in action data enter .. code-block:: json @@ -527,8 +525,8 @@ Sample code finger_id: !lambda 'return finger_id;' api: - services: - - service: enroll + actions: + - action: enroll variables: finger_id: int num_scans: int @@ -536,16 +534,16 @@ Sample code - fingerprint_grow.enroll: finger_id: !lambda 'return finger_id;' num_scans: !lambda 'return num_scans;' - - service: cancel_enroll + - action: cancel_enroll then: - fingerprint_grow.cancel_enroll: - - service: delete + - action: delete variables: finger_id: int then: - fingerprint_grow.delete: finger_id: !lambda 'return finger_id;' - - service: delete_all + - action: delete_all then: - fingerprint_grow.delete_all: diff --git a/components/display/fonts.rst b/components/font.rst similarity index 98% rename from components/display/fonts.rst rename to components/font.rst index 47ab89461f..8f215822c1 100644 --- a/components/display/fonts.rst +++ b/components/font.rst @@ -9,7 +9,7 @@ Font Renderer Component ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts. -These fonts can be used in ESPHome's :ref:`own rendering engine `. +These fonts can be used in ESPHome's :ref:`own rendering engine ` or in the :doc:`LVGL Graphics ` component. To use fonts you can either - Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file. @@ -83,6 +83,7 @@ Next, create a ``font:`` section in your configuration: display: # ... + Configuration variables: ------------------------ @@ -155,6 +156,7 @@ See Also - :apiref:`display/display_buffer.h` - :ref:`display-engine` +- :doc:`/components/lvgl/index` - `MDI cheatsheet `_ - `MDI font repository `_ - :ghedit:`Edit` diff --git a/components/globals.rst b/components/globals.rst index 614254efa5..6097d95fe7 100644 --- a/components/globals.rst +++ b/components/globals.rst @@ -1,5 +1,3 @@ -.. _config-globals: - Global Variables ---------------- @@ -42,7 +40,6 @@ Configuration variables: ``int`` (for integers), ``float`` (for decimal numbers), ``int[50]`` for an array of 50 integers, etc. - **restore_value** (*Optional*, boolean): Whether to try to restore the state on boot up. Be careful: on the ESP8266, you only have a total of 96 bytes available for this! Defaults to ``no``. - This will use storage in "RTC memory", so it won't survive a power-cycle unless you use the ``esp8266_restore_from_flash`` option to save to flash. See :doc:`esp8266_restore_from_flash ` for details. - **max_restore_data_length** (*Optional*, integer): Only applies to variables of type ``std::string``. ESPHome will allocate enough space for this many characters, plus single character of overhead. Strings longer than this will not be saved. The max value of this variable is 254 characters, and the default is 63 characters. - **initial_value** (*Optional*, string): The value with which to initialize this variable if the state @@ -54,7 +51,7 @@ Configuration variables: ``globals.set`` Action ---------------------- -This :ref:`Action ` allows you to change the value of a :ref:`global ` +This :ref:`Action ` allows you to change the value of a ``global`` variable without having to use the lambda syntax. .. code-block:: yaml @@ -70,6 +67,14 @@ Configuration variables: - **value** (**Required**, :ref:`templatable `): The value to set the global variable to. +.. note:: + + This action can also be written in lambdas: + + .. code-block:: cpp + + id(my_global_var) = 10; + See Also -------- diff --git a/components/gps.rst b/components/gps.rst index 94a4efbc0e..4a40483f79 100644 --- a/components/gps.rst +++ b/components/gps.rst @@ -49,39 +49,27 @@ Configuration variables: ------------------------ - **latitude** (*Optional*): Include the Latitude as a sensor - - **name** (**Required**, string): The name to give the latitude sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **longitude** (*Optional*): Include the Longitude as a sensor - - **name** (**Required**, string): The name to give the longitude sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **speed** (*Optional*): Include the measured speed as a sensor - - **name** (**Required**, string): The name to give the speed sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **course** (*Optional*): Include the measured course as a sensor - - **name** (**Required**, string): The name to give the course sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **altitude** (*Optional*): Include the measured altitude as a sensor - - **name** (**Required**, string): The name to give the altitude sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **satellites** (*Optional*): Include the number of tracking satellites being used as a sensor - - **name** (**Required**, string): The name to give the tracking satellites sensor - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. See Also -------- diff --git a/components/graph.rst b/components/graph.rst new file mode 100644 index 0000000000..a2df8b6b68 --- /dev/null +++ b/components/graph.rst @@ -0,0 +1,119 @@ +.. _display-graphs: + +Graph Component +=============== + +.. seo:: + :description: Instructions for displaying graphs in ESPHome. + :image: chart-line.svg + +You can display a graph of a sensor value(s) using this component. The states used for the graph are stored in +memory at the time the sensor updates and will be lost when the device reboots. + +Examples: + +.. figure:: images/display_rendering_graph.png + :align: center + +Graph component with options for grids, border and line-types. + +.. code-block:: yaml + + graph: + # Show bare-minimum auto-ranged graph + - id: single_temperature_graph + sensor: my_temperature + duration: 1h + width: 151 + height: 51 + # Show multi-trace graph + - id: multi_temperature_graph + duration: 1h + x_grid: 10min + y_grid: 1.0 # degC/div + width: 151 + height: 51 + traces: + - sensor: my_inside_temperature + line_type: DASHED + line_thickness: 2 + color: my_red + - sensor: my_outside_temperature + line_type: SOLID + continuous: true + line_thickness: 3 + color: my_blue + - sensor: my_beer_temperature + line_type: DOTTED + line_thickness: 2 + color: my_green + +Configuration variables: +------------------------ + +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the graph later + in your display code. +- **width** (**Required**, int): The graph width in pixels +- **height** (**Required**, int): The graph height in pixels +- **duration** (**Required**, :ref:`config-time`): The total graph history duration. +- **border** (*Optional*, boolean): Specifies if a border will be drawn around the graph. Default is True. +- **x_grid** (*Optional*): Specifies the time per division. If not specified, no vertical grid will be drawn. +- **y_grid** (*Optional*, float): Specifies the number of units per division. If not specified, no horizontal grid will be drawn. +- **max_range** (*Optional*): Specifies the maximum Y-axis range. +- **min_range** (*Optional*): Specifies the minimum Y-axis range. +- **max_value** (*Optional*): Specifies the maximum Y-axis value. +- **min_value** (*Optional*): Specifies the minimum Y-axis value. +- **traces** (*Optional*): Use this to specify more than a single trace. + +Trace specific fields: + +- **sensor** (*Optional*, :ref:`config-id`): The sensor value to plot +- **line_thickness** (*Optional*): Defaults to 3 +- **line_type** (*Optional*): Specifies the plot line-type. Can be one of the following: ``SOLID``, ``DOTTED``, ``DASHED``. Defaults to ``SOLID``. +- **continuous** (*Optional*): connects the individual points to make a continuous line. Defaults to ``false``. +- **color** (*Optional*): Sets the color of the sensor trace. + +And then later in code: + +.. code-block:: yaml + + display: + - platform: ... + # ... + pages: + - id: page1 + lambda: |- + pages: + - id: page1 + lambda: |- + // Draw the graph at position [x=10,y=20] + it.graph(10, 20, id(single_temperature_graph)); + - id: page2 + lambda: |- + // Draw the graph at position [x=10,y=20] + it.graph(10, 20, id(multi_temperature_graph), my_yellow); + + color: + - id: my_red + red: 100% + green: 0% + blue: 0% + - id: my_green + red: 0% + green: 100% + blue: 0% + - id: my_blue + red: 0% + green: 0% + blue: 100% + - id: my_yellow + red: 100% + green: 100% + blue: 0% +.. note:: + + Here are some things to note: + - Setting ``y_grid`` will expand any specified range to the nearest multiple of grid spacings. + - Axis labels are currently not possible without manually placing them. + - The grid and border color is set with it.graph(), while the traces are defined separately. + diff --git a/components/host.rst b/components/host.rst index 38897cd87f..1013bdd30a 100644 --- a/components/host.rst +++ b/components/host.rst @@ -23,17 +23,23 @@ configure wifi - network will automatically be available using the host computer # Example configuration entry host: - mac_address: "98:35:69:ab:f6:79" + mac_address: "06:35:69:ab:f6:79" Configuration variables: ------------------------ - **mac_address** (**Optional**, MAC address): A dummy MAC address to use when communicating with HA. +Build and run +------------- + +The ``esphome run yourfile.yaml`` command will compile and automatically run the build file on the ``host`` platform. + See Also -------- +- :ref:`SDL display ` - :doc:`esphome` - :doc:`/components/time/host` - :ghedit:`Edit` diff --git a/components/http_request.rst b/components/http_request.rst index c483275dea..54e1dc803e 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -13,8 +13,6 @@ The ``http_request`` component lets you make HTTP/HTTPS requests. To do so, you # Example configuration entry http_request: - useragent: esphome/device - timeout: 10s .. _http_request-configuration_variables: @@ -24,7 +22,7 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **follow_redirects** (*Optional*, boolean): Enable following HTTP redirects. Defaults to ``true``. - **redirect_limit** (*Optional*, integer): Maximum amount of redirects to follow when enabled. Defaults to ``3``. -- **timeout** (*Optional*, :ref:`config-time`): Timeout for request. Defaults to ``5s``. +- **timeout** (*Optional*, :ref:`config-time`): Timeout for request. Defaults to ``4.5s``. - **useragent** (*Optional*, string): User-Agent header for requests. Defaults to ``ESPHome/ (https://esphome.io)`` where ```` is the version of ESPHome the device is running. For example: ``ESPHome/2024.6.0 (https://esphome.io)`` @@ -38,6 +36,11 @@ Configuration variables: experiencing device reboots due to watchdog timeouts;** doing so may prevent the device from rebooting due to a legitimate problem. **Only available on ESP32 and RP2040**. +**For the ESP32 when using ESP-IDF:** + +- **buffer_size_rx** (*Optional*, integer): Change HTTP receive buffer size. Defaults to ``512``. +- **buffer_size_tx** (*Optional*, integer): Change HTTP transmit buffer size. Defaults to ``512``. + **For the ESP8266:** - **esp8266_disable_ssl_support** (*Optional*, boolean): Determines whether to include HTTPS/SSL support in the @@ -88,8 +91,8 @@ This :ref:`action ` sends a GET request. - logger.log: format: 'Response status: %d, Duration: %u ms' args: - - status_code - - duration_ms + - response->status_code + - response->duration_ms # Short form - http_request.get: https://esphome.io @@ -159,7 +162,7 @@ This :ref:`action ` sends a request. This automation will be triggered when the HTTP request is complete. The following variables are available for use in :ref:`lambdas `: -- ``response`` as a ``HttpContainer`` object which contains ``content_length``, ``status_code`` and ``duration_ms``. +- ``response`` as a pointer to ``HttpContainer`` object which contains ``content_length``, ``status_code`` and ``duration_ms``. - ``body`` as ``std::string`` which contains the response body when ``capture_response`` (see :ref:`http_request-get_action`) is set to ``true``. @@ -174,8 +177,10 @@ The following variables are available for use in :ref:`lambdas `: - logger.log: format: "Response status: %d, Duration: %u ms" args: - - response.status_code - - response.duration_ms + - response->status_code + - response->duration_ms + - lambda: |- + ESP_LOGD(TAG, "Response status: %d, Duration: %u ms", response->status_code, response->duration_ms); .. _http_request-examples: diff --git a/components/image.rst b/components/image.rst new file mode 100644 index 0000000000..2a27138ae5 --- /dev/null +++ b/components/image.rst @@ -0,0 +1,125 @@ +.. _display-image: + +Images +====== + +.. seo:: + :description: Instructions to display static images on ESPHome + :image: image-outline.svg + +Use this component to store graphical images on the device, you can then draw the images on compatible displays. + +For showing images downloaded at runtime, take a look at the :ref:`Online Image ` component. + +.. code-block:: yaml + + image: + - file: "image.png" + id: my_image + resize: 100x100 + +.. code-block:: yaml + + image: + - file: mdi:alert-outline + id: alert + resize: 80x80 + +.. code-block:: yaml + + image: + - file: https://esphome.io/_images/logo.png + id: esphome_logo + resize: 200x162 + +Configuration variables: +------------------------ + +- **file** (**Required**, string): + + - **Local files**: The path (relative to where the .yaml file is) of the image file. + - **Material Design Icons**: Specify the `Material Design Icon `_ + id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration. + - **Remote files**: The URL of the image file. + +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later + in your display code. +- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT`` + and preserve the aspect ratio. +- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local and remote images and ``TRANSPARENT_BINARY`` for MDIs. + + - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit + per pixel, 8 pixels per byte. + - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel + will be the on color. Uses 1 bit per pixel, 8 pixels per byte. + - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. + - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. + - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. + +- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. + +- **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here `__ and `here `__. + + - ``NONE``: Every pixel convert to its nearest color. + - ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels. + +.. note:: + + To use images you will need to have the python ``pillow`` package installed. + Additionally, if you want to use SVG images (including MDI images), you will + additionally need to have the python ``cairosvg`` package installed. + + If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. + + Use ``pip install "esphome[displays]"`` to install these optional dependencies with + the versions that ESPHome requires. + +And then later in code: + +.. code-block:: yaml + + display: + - platform: ... + # ... + lambda: |- + // Draw the image my_image at position [x=0,y=0] + it.image(0, 0, id(my_image)); + +By default, ESPHome will *align* the image at the top left. That means if you enter the coordinates +``[0,10]`` for your image, the top left of the image will be at ``[0,10]``. If you want to draw some +image at the right side of the display, it is however sometimes useful to choose a different **image alignment**. +When you enter ``[0,10]`` you're really telling ESPHome that it should position the **anchor point** of the image +at ``[0,10]``. When using a different alignment, like ``TOP_RIGHT``, the image will be positioned left of the anchor +pointed, so that, as the name implies, the anchor point is a the *top right* corner of the image. + +.. code-block:: yaml + + display: + - platform: ... + # ... + lambda: |- + // Aligned on left by default + it.image(0, 0, id(my_image)); + + // Aligned on right edge + it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT); + +For binary images the ``image`` method accepts two additional color parameters which can +be supplied to modify the color used to represent the on and off bits respectively. e.g. + +.. code-block:: yaml + + display: + - platform: ... + # ... + lambda: |- + // Draw the image my_image at position [x=0,y=0] + // with front color red and back color blue + it.image(0, 0, id(my_image), id(red), id(blue)); + + // Aligned on right edge + it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue)); + +You can also use this to invert images in two color displays, use ``COLOR_OFF`` then ``COLOR_ON`` +as the additional parameters. diff --git a/components/images/apds9306.png b/components/images/apds9306.png new file mode 100644 index 0000000000..07fbc1d37a Binary files /dev/null and b/components/images/apds9306.png differ diff --git a/components/display/images/display_rendering_graph.png b/components/images/display_rendering_graph.png similarity index 100% rename from components/display/images/display_rendering_graph.png rename to components/images/display_rendering_graph.png diff --git a/components/images/web_server/number-slider-popup-input-field.png b/components/images/web_server/number-slider-popup-input-field.png new file mode 100644 index 0000000000..8f3d939b0e Binary files /dev/null and b/components/images/web_server/number-slider-popup-input-field.png differ diff --git a/components/images/web_server/number-slider-popup.png b/components/images/web_server/number-slider-popup.png new file mode 100644 index 0000000000..825a794dda Binary files /dev/null and b/components/images/web_server/number-slider-popup.png differ diff --git a/components/images/web_server/sensor-history-graph.png b/components/images/web_server/sensor-history-graph.png new file mode 100644 index 0000000000..501b9079c0 Binary files /dev/null and b/components/images/web_server/sensor-history-graph.png differ diff --git a/components/images/web_server/tab-header-expand-cloapsed.png b/components/images/web_server/tab-header-expand-cloapsed.png new file mode 100644 index 0000000000..746ea287fd Binary files /dev/null and b/components/images/web_server/tab-header-expand-cloapsed.png differ diff --git a/components/images/web_server/tab-header-expand-controls-expanded.png b/components/images/web_server/tab-header-expand-controls-expanded.png new file mode 100644 index 0000000000..f16b267d36 Binary files /dev/null and b/components/images/web_server/tab-header-expand-controls-expanded.png differ diff --git a/components/images/web_server/tab-header-expand-logs-expanded.png b/components/images/web_server/tab-header-expand-logs-expanded.png new file mode 100644 index 0000000000..807f1d8956 Binary files /dev/null and b/components/images/web_server/tab-header-expand-logs-expanded.png differ diff --git a/components/improv_serial.rst b/components/improv_serial.rst index 206df451a6..6d76b1c40f 100644 --- a/components/improv_serial.rst +++ b/components/improv_serial.rst @@ -10,6 +10,8 @@ for configuring Wi-Fi on an ESPHome device by using a serial connection to the d The ``improv_serial`` component requires the serial ``logger`` to be configured. +The ``improv_serial`` component will use the project name and version instead of ESPHomes version whenever it's available. + .. code-block:: yaml diff --git a/components/index.rst b/components/index.rst index 5ccbbb4b1a..df4c68c255 100644 --- a/components/index.rst +++ b/components/index.rst @@ -6,6 +6,7 @@ Components :glob: binary_sensor/index + canbus/index climate/index cover/index fan/index @@ -25,6 +26,7 @@ Components touchscreen/index lock/index display_menu/index + lvgl/index media_player/index microphone/index speaker/index diff --git a/components/interval.rst b/components/interval.rst index c5edfe0bb7..84243420da 100644 --- a/components/interval.rst +++ b/components/interval.rst @@ -1,7 +1,5 @@ -.. _interval: - -``interval`` Component ----------------------- +Interval Component +------------------ This component allows you to run actions at fixed time intervals. For example, if you want to toggle a switch every minute, you can use this component. Please note that it's possible to achieve the same thing with the diff --git a/components/key_collector.rst b/components/key_collector.rst index 552522b5bf..0976caf060 100644 --- a/components/key_collector.rst +++ b/components/key_collector.rst @@ -6,12 +6,12 @@ Key collector component .. seo:: :description: Key collector component -The ``key_collector`` component collects key presses from -components like :ref:`matrix_keypad` or ``wiegand``. It allows you to process -key sequences and treat them as one, for example to allow inputting of -a PIN code or a passkey. The component outputs the result of the keypress -sequence as a variable usable in automations. - +The ``key_collector`` component collects key presses from components +like :ref:`matrix_keypad`, :doc:`Wiegand keypad ` +or LVGL :ref:`Button Matrix `, :ref:`Keyboard ` +widgets. It allows you to process key sequences and treat them as one, for +example to allow inputting of a PIN code or a passkey. The component outputs +the result of the keypress sequence as a variable usable in automations. Component --------- @@ -92,7 +92,7 @@ See Also -------- - :doc:`/components/matrix_keypad` - -.. - :doc:`/components/wiegand` - +- :doc:`/components/wiegand` +- :ref:`LVGL Button Matrix widget ` +- :ref:`LVGL Keyboard widget ` - :ghedit:`Edit` diff --git a/components/light/binary.rst b/components/light/binary.rst index 4a3bf44e5e..08fe2f6c92 100644 --- a/components/light/binary.rst +++ b/components/light/binary.rst @@ -24,12 +24,7 @@ The ``binary`` light platform creates a simple ON/OFF-only light from a Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. -- **output** (**Required**, :ref:`config-id`): The id of the - binary :ref:`output` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light, though binary lights - only support very few of them. +- **output** (**Required**, :ref:`config-id`): The id of the binary :ref:`output` to use for this light. - All other options from :ref:`Light `. See Also diff --git a/components/light/color_temperature.rst b/components/light/color_temperature.rst index b66a942488..1f674d5513 100644 --- a/components/light/color_temperature.rst +++ b/components/light/color_temperature.rst @@ -23,7 +23,6 @@ and the other channel controls the brightness. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **color_temperature** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the color temperature. - **brightness** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the brightness. - **cold_white_color_temperature** (**Required**, float): The coldest color temperature supported by this light. This @@ -32,8 +31,6 @@ Configuration variables: - **warm_white_color_temperature** (**Required**, float): The warmest color temperature supported by this light. This is the highest value when expressed in `mireds `__, or the lowest value when expressed in Kelvin. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/cwww.rst b/components/light/cwww.rst index 43127cbc4a..467087c4b1 100644 --- a/components/light/cwww.rst +++ b/components/light/cwww.rst @@ -36,7 +36,6 @@ calculation assumes that both lights have the same illuminance, which might not Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **cold_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the cold white channel. - **warm_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the warm white channel. - **cold_white_color_temperature** (*Optional*, float): The color temperature (in `mireds `__ or Kelvin) @@ -44,8 +43,6 @@ Configuration variables: - **warm_white_color_temperature** (*Optional*, float): The color temperature (in `mireds `__ or Kelvin) of the warm white channel. Note that this option is required to control the mixing from Home Assistant. - **constant_brightness** (*Optional*, boolean): When enabled, this will keep the overall brightness of the cold and warm white channels constant by limiting the combined output to 100% of a single channel. This reduces the possible overall brightness but is necessary for some power supplies that are not able to run both channels at full brightness at once. Defaults to ``false``. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/fastled.rst b/components/light/fastled.rst index f1799fca06..cc68da4e8d 100644 --- a/components/light/fastled.rst +++ b/components/light/fastled.rst @@ -55,7 +55,6 @@ Clockless FastLED lights differ from the Configuration variables: ************************ -- **name** (**Required**, string): The name of the light. - **chipset** (**Required**, string): Set a chipset to use. See :ref:`fastled_clockless-chipsets` for options. - **pin** (**Required**, :ref:`config-pin`): The pin for the data line of the FastLED light. @@ -67,8 +66,6 @@ Configuration variables: - **max_refresh_rate** (*Optional*, :ref:`config-time`): A time interval used to limit the number of commands a light can handle per second. For example 16ms will limit the light to a refresh rate of about 60Hz. Defaults to the default value for the used chipset. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. .. _fastled_clockless-chipsets: @@ -135,7 +132,6 @@ whereas the clockless lights only need a single pin. Configuration variables: ************************ -- **name** (**Required**, string): The name of the light. - **chipset** (**Required**, string): Set a chipset to use. See :ref:`fastled_spi-chipsets` for options. - **data_pin** (**Required**, :ref:`config-pin`): The pin for the data line of the FastLED light. - **clock_pin** (**Required**, :ref:`config-pin`): The pin for the clock line of the FastLED light. @@ -150,7 +146,6 @@ Configuration variables: - **data_rate** (*Optional*, frequency): The data rate to use for shifting data to the light. Can help if you have long cables or slow level-shifters. - **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. .. _fastled_spi-chipsets: diff --git a/components/light/hbridge.rst b/components/light/hbridge.rst index 07b8c23cc8..5560c007ce 100644 --- a/components/light/hbridge.rst +++ b/components/light/hbridge.rst @@ -34,8 +34,6 @@ control the colors in the :ref:`light control actions `, y Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the light. - **pin_a** (**Required**, :ref:`config-id`): The id of the first float :ref:`output` to use for this light. - **pin_b** (**Required**, :ref:`config-id`): The id of the second float :ref:`output` to use for this light. - All other options from :ref:`Light `. diff --git a/components/light/index.rst b/components/light/index.rst index 5ccae3afb5..3e31ad3cf3 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -26,7 +26,8 @@ All light configuration schemas inherit these options. Configuration variables: -- **name** (**Required**, string): The name of the light. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the light. At least one of **id** and **name** must be specified. .. note:: @@ -43,8 +44,6 @@ Configuration variables: - **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash is called. Defaults to ``0s``. - **restore_mode** (*Optional*): Control how the light attempts to restore state on bootup. - For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the - :doc:`esphome section `. - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. @@ -320,6 +319,15 @@ Configuration variables: - **relative_brightness** (**Required**, :ref:`templatable `, percentage): The relative brightness to dim the light by. - **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the transition. +- **brightness_limits** (*Optional*): Limits in the brightness range. + - **min_brightness** (*Optional*, percentage): The minimum brightness to dim the light to. Defaults to ``0%``. + - **max_brightness** (*Optional*, percentage): The maximum brightness to dim the light to. Defaults to ``100%``. + - **limit_mode** (*Optional*): What to do when the current brightness is outside of the limit range. Defaults to ``CLAMP``. + Valid limit modes are: + + - ``CLAMP``: Clamp the brightness to the limit range. + - ``DO_NOTHING``: No dimming if the brightness is outside the limit range. + .. note:: @@ -340,6 +348,8 @@ Configuration variables: id: light_1 relative_brightness: 5% transition_length: 0.1s + brightness_limits: + max_brightness: 90% - delay: 0.1s .. _light-addressable_set_action: diff --git a/components/light/lvgl.rst b/components/light/lvgl.rst new file mode 100644 index 0000000000..a4e1d1d3bf --- /dev/null +++ b/components/light/lvgl.rst @@ -0,0 +1,44 @@ +LVGL Light +========== + +.. seo:: + :description: Instructions for setting up an LVGL widget light. + :image: ../images/lvgl_c_lig.png + +The ``lvgl`` light platform creates a light from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widget is :ref:`lvgl-widget-led`. A single light supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome light component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a ``led`` widget configured in LVGL, which will reflect the state of the light. +- All other options from :ref:`light `. + + +Example: + +.. code-block:: yaml + + light: + - platform: lvgl + widget: led_id + name: LVGL light + +.. note:: + + To have linear brightness control, ``gamma_correct`` of the light is set by default to ``0``. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`LED widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/light/monochromatic.rst b/components/light/monochromatic.rst index c24a9787a2..164ff7f421 100644 --- a/components/light/monochromatic.rst +++ b/components/light/monochromatic.rst @@ -30,10 +30,7 @@ The ``monochromatic`` light platform creates a simple brightness-only light from Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **output** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for this light. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/neopixelbus.rst b/components/light/neopixelbus.rst index 852978677b..69cf514654 100644 --- a/components/light/neopixelbus.rst +++ b/components/light/neopixelbus.rst @@ -37,10 +37,7 @@ Configuration variables: **Base Options:** -- **name** (**Required**, string): The name of the light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **num_leds** (**Required**, int): The number of LEDs attached. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. **Type Options:** @@ -87,8 +84,6 @@ If you have one line, only specify ``pin``, otherwise specify both ``clock_pin`` - **clock_pin** (**Required**, :ref:`config-pin`): The pin for the clock line of the light, for two-wire lights. - **data_pin** (**Required**, :ref:`config-pin`): The pin for the data line of the light, for two-wire lights. -**Advanced Options:** - - All other options from :ref:`Light `. .. warning:: diff --git a/components/light/partition.rst b/components/light/partition.rst index a5544cb45b..50778b13af 100644 --- a/components/light/partition.rst +++ b/components/light/partition.rst @@ -90,9 +90,8 @@ Joining multiple LED lights into one Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **segments** (**Required**, list): A list of segments included in this partition. - + *For addressable segments:* - **id** (**Required**, :ref:`config-id`): The ID of the addressable light to be controlled by this segment. @@ -106,9 +105,6 @@ Configuration variables: - **single_light_id** (**Required**, :ref:`config-id`): The ID of a single addressable or non-addressable light. If an addressable light is specified, it will be treated as a single light in the partition. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. - - All other options from :ref:`Light `. .. note:: diff --git a/components/light/rgb.rst b/components/light/rgb.rst index 2c1f4f8374..bfa1b2b327 100644 --- a/components/light/rgb.rst +++ b/components/light/rgb.rst @@ -60,12 +60,9 @@ perceived intensity of different colors will generally vary. This can be done by Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **red** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the red channel. - **green** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the green channel. - **blue** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the blue channel. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/rgbct.rst b/components/light/rgbct.rst index 7e198bbb2a..3447758ea8 100644 --- a/components/light/rgbct.rst +++ b/components/light/rgbct.rst @@ -25,7 +25,6 @@ light from 5 :ref:`float output components ` (one for each channel). Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **red** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the red channel. - **green** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the green channel. - **blue** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the blue channel. @@ -41,8 +40,6 @@ Configuration variables: expressed in Kelvin. - **color_interlock** (*Optional*, boolean): When enabled, this will prevent white leds being on at the same time as RGB leds. See :ref:`rgbw_color_interlock` for more information. Defaults to ``false``. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/rgbw.rst b/components/light/rgbw.rst index ca089b07d0..3cf45f8309 100644 --- a/components/light/rgbw.rst +++ b/components/light/rgbw.rst @@ -64,15 +64,12 @@ the ``color_mode`` option of the :ref:`light control actions ` to use for this light. - **color_interlock** (*Optional*, boolean): When enabled, this will prevent white leds being on at the same time as RGB leds. See :ref:`rgbw_color_interlock` for more information. Defaults to ``false``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/rgbww.rst b/components/light/rgbww.rst index 426e45f1b7..c308860e29 100644 --- a/components/light/rgbww.rst +++ b/components/light/rgbww.rst @@ -69,7 +69,6 @@ the ``color_mode`` option of the :ref:`light control actions ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Light `. See Also diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst index d6f9b8c124..7b5899067a 100644 --- a/components/light/shelly_dimmer.rst +++ b/components/light/shelly_dimmer.rst @@ -10,7 +10,6 @@ A detailed analysis of the Shelly Dimmer 2 hardware is given `here `_: ``true`` means leading edge, ``false`` is trailing edge. Defaults to ``false``. - **min_brightness** (*Optional*, int): Minimum brightness value on a scale from 0..1000, the default is 0. - **max_brightness** (*Optional*, int): Maximum brightness value on a scale from 0..1000, the default is 1000. @@ -91,7 +88,7 @@ Configuration variables: firmware: version: "51.6" #<-- set version here update: true - + There is no action required by the user to flash the STM32. There is no way to revert to stock firmware on the STM32 at the time of writing. - All other options from :ref:`Light `. diff --git a/components/light/sonoff_d1.rst b/components/light/sonoff_d1.rst index b2a17cba86..4882f69516 100644 --- a/components/light/sonoff_d1.rst +++ b/components/light/sonoff_d1.rst @@ -94,8 +94,6 @@ This component is useless for devices other than Sonoff D1 dimmer. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the light. - **use_rm433_remote** (*Optional*, boolean): Set to ``True`` if your setup uses Sonoff RM433 or any other radio remote control. Properly setting this parameter allows the platform to identify what to do with incoming UART commands. RF chip is known to catch random commands diff --git a/components/light/spi_led_strip.rst b/components/light/spi_led_strip.rst index 31b226e093..5626d18c3d 100644 --- a/components/light/spi_led_strip.rst +++ b/components/light/spi_led_strip.rst @@ -35,10 +35,7 @@ perceived intensity of different colors will generally vary. This can be done by Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. - **num_leds** (*Optional*, int): The number of LEDs attached. The default is 1. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz``, ``5MHz``, ``2MHz``, ``1MHz`` (default), ``200kHz``, ``75kHz`` or ``1kHz``. - All other options from :ref:`Light `. diff --git a/components/light/status_led.rst b/components/light/status_led.rst index 69b315b5f0..1aa2b91c1d 100644 --- a/components/light/status_led.rst +++ b/components/light/status_led.rst @@ -34,12 +34,8 @@ When the device is in OK state, the LED will be restored to the state of the ``b Configuration variables: ------------------------ -- **name** (*Optional*, string): The name of the light. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **pin** (*Optional*, :ref:`Pin Schema `): The GPIO pin to operate the LED on. - **output** (*Optional*, :ref:`config-id`): The id of the binary :ref:`output` to use for this light. -- **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light, though binary lights - only support very few of them. - All other options from :ref:`Light `. .. note:: diff --git a/components/light/tuya.rst b/components/light/tuya.rst index e0b74872a3..e866828f8b 100644 --- a/components/light/tuya.rst +++ b/components/light/tuya.rst @@ -42,8 +42,6 @@ Now you can create the light. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the light. - **dimmer_datapoint** (*Optional*, int): The datapoint id number of the dimmer value. - **min_value_datapoint** (*Optional*, int): The datapoint id number of the MCU minimum value setting. If this is set then ESPHome will sync the **min_value** to the MCU on startup. diff --git a/components/lock/index.rst b/components/lock/index.rst index a42f88be48..f88c939780 100644 --- a/components/lock/index.rst +++ b/components/lock/index.rst @@ -21,7 +21,8 @@ Base Lock Configuration Configuration variables: -- **name** (**Required**, string): The name of the lock. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the lock. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/lock/output.rst b/components/lock/output.rst index ef07f45181..127ad9a017 100644 --- a/components/lock/output.rst +++ b/components/lock/output.rst @@ -27,8 +27,6 @@ Configuration variables: ------------------------ - **output** (**Required**, :ref:`config-id`): The ID of the output component to use. -- **name** (**Required**, string): The name for the lock. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Lock `. See Also diff --git a/components/lock/template.rst b/components/lock/template.rst index e94a42ffd0..feeff7fde6 100644 --- a/components/lock/template.rst +++ b/components/lock/template.rst @@ -45,7 +45,6 @@ Possible return values for the optional lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the lock. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated repeatedly to get the current state of the lock. - **lock_action** (*Optional*, :ref:`Action `): The action that should @@ -58,7 +57,6 @@ Configuration variables: - **assumed_state** (*Optional*, boolean): Whether the true state of the lock is not known. This will make the Home Assistant frontend show buttons for both LOCK and UNLOCK actions, instead of hiding one of them when the lock is LOCKED/UNLOCKED. Defaults to ``false``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Lock `. .. _lock-template-publish_action: diff --git a/components/lvgl/images/lvgl_align.png b/components/lvgl/images/lvgl_align.png new file mode 100644 index 0000000000..e7a1381ca6 Binary files /dev/null and b/components/lvgl/images/lvgl_align.png differ diff --git a/components/lvgl/images/lvgl_animimg.gif b/components/lvgl/images/lvgl_animimg.gif new file mode 100644 index 0000000000..9f6bce8bee Binary files /dev/null and b/components/lvgl/images/lvgl_animimg.gif differ diff --git a/components/lvgl/images/lvgl_arc.png b/components/lvgl/images/lvgl_arc.png new file mode 100644 index 0000000000..d2114ce262 Binary files /dev/null and b/components/lvgl/images/lvgl_arc.png differ diff --git a/components/lvgl/images/lvgl_bar.png b/components/lvgl/images/lvgl_bar.png new file mode 100644 index 0000000000..b48a56f891 Binary files /dev/null and b/components/lvgl/images/lvgl_bar.png differ diff --git a/components/lvgl/images/lvgl_baseobj.png b/components/lvgl/images/lvgl_baseobj.png new file mode 100644 index 0000000000..5fe7294ce6 Binary files /dev/null and b/components/lvgl/images/lvgl_baseobj.png differ diff --git a/components/lvgl/images/lvgl_boxmodel.png b/components/lvgl/images/lvgl_boxmodel.png new file mode 100644 index 0000000000..98251f4169 Binary files /dev/null and b/components/lvgl/images/lvgl_boxmodel.png differ diff --git a/components/lvgl/images/lvgl_button.png b/components/lvgl/images/lvgl_button.png new file mode 100644 index 0000000000..c80d07f2d1 Binary files /dev/null and b/components/lvgl/images/lvgl_button.png differ diff --git a/components/lvgl/images/lvgl_buttonmatrix.png b/components/lvgl/images/lvgl_buttonmatrix.png new file mode 100644 index 0000000000..4842d58f3a Binary files /dev/null and b/components/lvgl/images/lvgl_buttonmatrix.png differ diff --git a/components/lvgl/images/lvgl_checkbox.png b/components/lvgl/images/lvgl_checkbox.png new file mode 100644 index 0000000000..31b63cc7f5 Binary files /dev/null and b/components/lvgl/images/lvgl_checkbox.png differ diff --git a/components/lvgl/images/lvgl_dropdown.png b/components/lvgl/images/lvgl_dropdown.png new file mode 100644 index 0000000000..191f0bdb53 Binary files /dev/null and b/components/lvgl/images/lvgl_dropdown.png differ diff --git a/components/lvgl/images/lvgl_image.png b/components/lvgl/images/lvgl_image.png new file mode 100644 index 0000000000..014d8aecb2 Binary files /dev/null and b/components/lvgl/images/lvgl_image.png differ diff --git a/components/lvgl/images/lvgl_keyboard.png b/components/lvgl/images/lvgl_keyboard.png new file mode 100644 index 0000000000..a9b009d310 Binary files /dev/null and b/components/lvgl/images/lvgl_keyboard.png differ diff --git a/components/lvgl/images/lvgl_label.png b/components/lvgl/images/lvgl_label.png new file mode 100644 index 0000000000..9a31c4ef3e Binary files /dev/null and b/components/lvgl/images/lvgl_label.png differ diff --git a/components/lvgl/images/lvgl_led.png b/components/lvgl/images/lvgl_led.png new file mode 100644 index 0000000000..0349f1b9cd Binary files /dev/null and b/components/lvgl/images/lvgl_led.png differ diff --git a/components/lvgl/images/lvgl_line.png b/components/lvgl/images/lvgl_line.png new file mode 100644 index 0000000000..6d85c445b4 Binary files /dev/null and b/components/lvgl/images/lvgl_line.png differ diff --git a/components/lvgl/images/lvgl_main_screenshot.png b/components/lvgl/images/lvgl_main_screenshot.png new file mode 100644 index 0000000000..a8c971a901 Binary files /dev/null and b/components/lvgl/images/lvgl_main_screenshot.png differ diff --git a/components/lvgl/images/lvgl_meter.png b/components/lvgl/images/lvgl_meter.png new file mode 100644 index 0000000000..1283126ccc Binary files /dev/null and b/components/lvgl/images/lvgl_meter.png differ diff --git a/components/lvgl/images/lvgl_msgbox.png b/components/lvgl/images/lvgl_msgbox.png new file mode 100644 index 0000000000..101a40c8b4 Binary files /dev/null and b/components/lvgl/images/lvgl_msgbox.png differ diff --git a/components/lvgl/images/lvgl_roller.png b/components/lvgl/images/lvgl_roller.png new file mode 100644 index 0000000000..3eab1039c0 Binary files /dev/null and b/components/lvgl/images/lvgl_roller.png differ diff --git a/components/lvgl/images/lvgl_slider.png b/components/lvgl/images/lvgl_slider.png new file mode 100644 index 0000000000..d2de4030d2 Binary files /dev/null and b/components/lvgl/images/lvgl_slider.png differ diff --git a/components/lvgl/images/lvgl_spinbox.png b/components/lvgl/images/lvgl_spinbox.png new file mode 100644 index 0000000000..72ebee3c89 Binary files /dev/null and b/components/lvgl/images/lvgl_spinbox.png differ diff --git a/components/lvgl/images/lvgl_spinner.gif b/components/lvgl/images/lvgl_spinner.gif new file mode 100644 index 0000000000..cf4b1640f3 Binary files /dev/null and b/components/lvgl/images/lvgl_spinner.gif differ diff --git a/components/lvgl/images/lvgl_switch.png b/components/lvgl/images/lvgl_switch.png new file mode 100644 index 0000000000..9864b2b79b Binary files /dev/null and b/components/lvgl/images/lvgl_switch.png differ diff --git a/components/lvgl/images/lvgl_symbols.png b/components/lvgl/images/lvgl_symbols.png new file mode 100644 index 0000000000..65320bd91d Binary files /dev/null and b/components/lvgl/images/lvgl_symbols.png differ diff --git a/components/lvgl/images/lvgl_tabview.png b/components/lvgl/images/lvgl_tabview.png new file mode 100644 index 0000000000..ae18acf31a Binary files /dev/null and b/components/lvgl/images/lvgl_tabview.png differ diff --git a/components/lvgl/images/lvgl_textarea.png b/components/lvgl/images/lvgl_textarea.png new file mode 100644 index 0000000000..1382f7e100 Binary files /dev/null and b/components/lvgl/images/lvgl_textarea.png differ diff --git a/components/lvgl/index.rst b/components/lvgl/index.rst new file mode 100644 index 0000000000..16b903a309 --- /dev/null +++ b/components/lvgl/index.rst @@ -0,0 +1,725 @@ +LVGL Graphics +============= + +.. seo:: + :description: LVGL - ESPHome Displays showing contents created with Light and Versatile Graphics Library + :image: /images/lvgl.png + +`LVGL `__ (Light and Versatile Graphics Library) is a free and open-source +embedded graphics library to create beautiful UIs for any MCU, MPU and display type. ESPHome supports `LVGL version 8 `__. + +.. figure:: /components/lvgl/images/lvgl_main_screenshot.png + +To use LVGL with a :ref:`display ` in ESPHome, you'll need an ESP32 or supported ESP32 variant. PSRAM is not a strict requirement but it is generally recommended, especially for color displays with resolutions larger than approximately 240x240 pixels. + +The graphic display should be configured with ``auto_clear_enabled: false`` and ``update_interval: never``, and should not have any ``lambda`` set. + +For interactivity, a :doc:`Touchscreen ` (capacitive highly preferred), a :doc:`/components/sensor/rotary_encoder` or a custom keypad made up from discrete :doc:`Binary Sensors ` can be used. + + +Basics +------ + +In LVGL, graphical elements like buttons, labels, sliders, etc. are called widgets or objects. See :doc:`/components/lvgl/widgets` for a complete list of widgets supported within ESPHome. Not all LVGL widgets are implemented, just those commonly used to support home automation needs/tasks. + +Every widget has a parent object where it is created. For example, if a label is created on a button, the button is the parent of the label. Complex widgets internally consist of several smaller/simpler widgets; these are known as parts, each of which can have separate properties from the main widget. + +Pages in ESPHome are implemented as LVGL screens, which are special objects which have no parent. There is always one active page on a display. + +Widgets can be assigned with an :ref:`config-id` so that they can be referenced in :ref:`automations `. + +Some widgets integrate also as native ESPHome components: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 + + * - LVGL Widget + - ESPHome component + + * - ``button`` + - :doc:`Switch `, :doc:`Binary Sensor ` + + * - ``switch``, ``checkbox`` + - :doc:`Switch ` + + * - ``slider``, ``arc``, ``spinbox`` + - :doc:`Number `, :doc:`Sensor ` + + * - ``dropdown``, ``roller`` + - :doc:`Select ` + + * - ``label``, ``textarea`` + - :doc:`Text `, :doc:`Text Sensor ` + + * - ``led`` + - :doc:`Light ` + +These are useful with `Home Assistant automations `__ interacting directly with the widgets. + +Main Configuration +------------------ + +Although LVGL is a complex matrix of objects-parts-states-styles, ESPHome simplifies this into a hierarchy. + +At the highest level of the LVGL object hierarchy is the display (represented by the hardware driver). A display can have one or more pages associated with it. Each page contains a hierarchy of objects for graphical widgets representing a layout to be presented on the display. + +The following configuration variables apply to the main ``lvgl`` component, in order to establish the principal operating conditions. Some :ref:`styling options ` can be set at this level too, but only for inheritance purposes. + +**Configuration variables:** + +- **displays** (*Optional*, list, :ref:`config-id`): A list of display IDs where LVGL should perform rendering based on its configuration. This may be omitted if there is a single display configured, which will be used automatically. +- **touchscreens** (*Optional*, list): A list of touchscreens interacting with the LVGL widgets on the display. + - **touchscreen_id** (**Required**, :ref:`config-id`): ID of a touchscreen configuration related to a display. + - **long_press_time** (*Optional*, :ref:`Time `): For the touchscreen, delay after which the ``on_long_pressed`` :ref:`interaction trigger ` will be called. Defaults to ``400ms``. + - **long_press_repeat_time** (*Optional*, :ref:`Time `): For the touchscreen, repeated interval after ``long_press_time``, when ``on_long_pressed_repeat`` :ref:`interaction trigger ` will be called. Defaults to ``100ms``. +- **encoders** (*Optional*, list): A list of rotary encoders interacting with the LVGL widgets on the display. + - **group** (*Optional*, string): A name for a group of widgets which will interact with the the input device. See the :doc:`common properties ` of the widgets for more information on groups. + - **initial_focus** (*Optional*, :ref:`config-id`): An optional ID for a widget to be given focus on startup (especially useful if there is only one focusable widget.) + - **enter_button** (**Required**, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``ENTER`` key. + - **sensor** (*Optional*, :ref:`config-id`): The ID of a :doc:`/components/sensor/rotary_encoder`; or a list with buttons for left/right interaction with the widgets: + - **left_button** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``LEFT`` key. + - **right_button** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``RIGHT`` key. + - **long_press_time** (*Optional*, :ref:`Time `): For the rotary encoder, delay after which the ``on_long_pressed`` :ref:`interaction trigger ` will be called. Defaults to ``400ms``. Can be disabled with ``never``. + - **long_press_repeat_time** (*Optional*, :ref:`Time `): For the rotary encoder, repeated interval after ``long_press_time``, when ``on_long_pressed_repeat`` :ref:`interaction trigger ` will be called. Defaults to ``100ms``. Can be disabled with ``never``. +- **keypads** (*Optional*, list): A list of keypads interacting with the LVGL widgets on the display. + - **group** (*Optional*, string): A name for a group of widgets which will interact with the the input device. See the :doc:`common properties ` of the widgets for more information on groups. + - **up** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``UP`` key. + - **down** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``DOWN`` key. + - **right** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``RIGHT`` key. + - **left** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``LEFT`` key. + - **esc** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``ESC`` key. + - **del** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``DEL`` key. + - **backspace** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``BACKSPACE`` key. + - **enter** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``ENTER`` key. + - **next** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``NEXT`` key. + - **prev** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``PREV`` key. + - **home** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``HOME`` key. + - **end** (*Optional*, :ref:`config-id`): The ID of a :doc:`Binary Sensor `, to be used as ``END`` key. + - **long_press_time** (*Optional*, :ref:`Time `): For the keypad, delay after which the ``on_long_pressed`` :ref:`interaction trigger ` will be called. Defaults to ``400ms``. Can be disabled with ``never``. + - **long_press_repeat_time** (*Optional*, :ref:`Time `): For the keypad, repeated interval after ``long_press_time``, when ``on_long_pressed_repeat`` :ref:`interaction trigger ` will be called. Defaults to ``100ms``. Can be disabled with ``never``. + + .. tip:: + + When using binary sensors (from physical keys) to interact with LVGL, if there are only three keys available, they are best used when configured as a rotary encoder, where ``LEFT`` and ``RIGHT`` act like the rotary wheel, and ``ENTER`` generates an ``on_press`` :ref:`trigger `. With four or more keys, a keypad configuration is generally more appropriate. For example, a keypad consisting of five keys might use ``PREV``, ``NEXT``, ``UP``, ``DOWN`` and ``ENTER``; ``PREV``/``NEXT`` are used to select a widget within the group, ``UP``/``DOWN`` changes the selected value and ``ENTER`` generates an ``on_press`` :ref:`trigger `. + + The ``long_press_time`` and ``long_press_repeat_time`` can be fine-tuned also by setting them to ``never`` and using the ``autorepeat`` filter on each binary sensor separately. + +- **color_depth** (*Optional*, string): The color deph at which the contents are generated. Currently only ``16`` is supported (RGB565, 2 bytes/pixel), which is the default value. +- **buffer_size** (*Optional*, percentage): The percentage of screen size to allocate buffer memory. Default is ``100%`` (or ``1.0``). For devices without PSRAM, the recommended value is ``25%``. +- **log_level** (*Optional*, string): Set the logger level specifically for the messages of the LVGL library: ``TRACE``, ``INFO``, ``WARN``, ``ERROR``, ``USER``, ``NONE``. Defaults to ``WARN``. +- **byte_order** (*Optional*, int16): The byte order of the data LVGL outputs; either ``big_endian`` or ``little_endian``. Defaults to ``big_endian``. +- **disp_bg_color** (*Optional*, :ref:`color `): Solid color used to fill the background. Can be changed at runtime with the ``lvgl.update`` action. +- **disp_bg_image** (*Optional*, :ref:`image `): The ID of an existing image configuration, to be used as background wallpaper. To change the image at runtime use the ``lvgl.update`` action. Also see :ref:`lvgl-widget-image` for a note regarding supported image formats. +- **default_font** (*Optional*, ID): The ID of the :ref:`font ` used by default to render the text or symbols. Defaults to LVGL's internal ``montserrat_14`` if not specified. +- **style_definitions** (*Optional*, list): A batch of style definitions to use in LVGL widget's ``styles`` configuration. See :ref:`below ` for more details. +- **theme** (*Optional*, list): A list of styles to be applied to all widgets. See :ref:`below ` for more details. +- **widgets** (*Optional*, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the root display. May not be used if ``pages`` (below) is configured. +- **pages** (*Optional*, list): A list of page IDs. Each page acts as a parent for widgets placed on it. May not be used with ``widgets`` (above). Options for each page: + - **skip** (*Optional*, boolean): Option to skip this page when navigating between them with :ref:`lvgl-page-next-previous-action`. + - **layout** (*Optional*): See :ref:`lvgl-layouts` for details. Defaults to ``NONE``. + - **widgets** (*Optional*, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the page. + - All other options from :ref:`lvgl-styling` to be applied to this page. +- **page_wrap** (*Optional*, boolean): Wrap from the last to the first page when navigating between them with :ref:`lvgl-page-next-previous-action`. Defaults to ``true``. +- **top_layer** (*Optional*, list): A special kind of *Always on Top* page, which acts as a parent for widgets placed on it. It's shown above all the pages, which may be useful for widgets which always need to be visible. + - **layout** (*Optional*): See :ref:`lvgl-layouts` for details. Defaults to ``NONE``. + - **widgets** (*Optional*, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the page. + - All other options from :ref:`lvgl-styling` to be applied to this page. +- **layout** (*Optional*): See :ref:`lvgl-layouts` for details. Defaults to ``NONE``. +- All other options from :ref:`lvgl-styling` to be applied to all widgets directly. + +**Example:** + +.. code-block:: yaml + + # Example configuration entry + lvgl: + displays: + - my_display + touchscreens: + - my_touch + pages: + - id: main_page + widgets: + - label: + align: CENTER + text: 'Hello World!' + + +.. _lvgl-color: + +Colors +****** + +Colors can be specified anywhere in the LVGL configuration either by referencing a preconfigured :ref:`ESPHome color ` ID or by representing the color in the common hexadecimal notation. For example, ``0xFF0000`` would be red. + +.. _lvgl-opacity: + +Opacity +******* + +Various parts of the widgets (like background, borders etc.) support opacity. It can be overridden with a string: ``TRANSP`` for fully transparent, ``COVER`` for fully opaque, or percentage between ``0%`` and ``100%``. Actual default values depend on widget specifics. + +.. _lvgl-fonts: + +Fonts +***** + +Two font choices are available: + +**ESPHome fonts** + +You can use :ref:`fonts configured normally`, the glyphs will be rendered while building the binary. This has the advantage that you can define custom sets of glyphs of any size, with icons or diacritic characters of your choice, for any language, from any TrueType/OpenType font, allowing a more optimal flash space usage because you don't need to include all glyphs for all sizes you wish to use. + +.. tip:: + + For best results, set ``bpp: 4`` to get the glyphs rendered with proper anti-aliasing. + + +**Library fonts** + +The LVGL library offers by default prerendered sets with ASCII characters (``0x20-0x7F``), the degree symbol (``0xB0``), the bullet symbol (``0x2022``) from `Montserrat Medium `__, and 60 symbols from `FontAwesome `__ (see below). You can use the IDs below when specifying the ``text_font`` parameter: + +- ``montserrat_8``: 8px font +- ``montserrat_10``: 10px font +- ``montserrat_12``: 12px font +- ``montserrat_14``: 14px font (**default**, included if ``default_font`` option is missing) +- ``montserrat_16``: 16px font +- ``montserrat_18``: 18px font +- ``montserrat_20``: 20px font +- ``montserrat_22``: 22px font +- ``montserrat_24``: 24px font +- ``montserrat_26``: 26px font +- ``montserrat_28``: 28px font +- ``montserrat_30``: 30px font +- ``montserrat_32``: 32px font +- ``montserrat_34``: 34px font +- ``montserrat_36``: 36px font +- ``montserrat_38``: 38px font +- ``montserrat_40``: 40px font +- ``montserrat_42``: 42px font +- ``montserrat_44``: 44px font +- ``montserrat_46``: 46px font +- ``montserrat_48``: 48px font + +The binary will only include any of the above if used in the configuration. + +You can display the embedded symbols among the text by their codepoint address preceded by ``\u``. For example: ``\uF00C``: + +.. figure:: /components/lvgl/images/lvgl_symbols.png + :align: center + +.. note:: + + The ``text_font`` parameter affects the size of symbols, since all the built-in font arrays based on Montserrat include these symbols at the respective sizes. If you set ``text_font`` on a widget to a custom ESPHome font, these symbols will likely not display, unless you include them manually from a FontAwesome OpenType file. + + For escape sequences to work, you have to put them in strings enclosed in double quotes. + +In addition to the above, the following special fonts are available from LVGL as built-in: + +- ``unscii_8``: 8 px pixel perfect font with only ASCII characters. +- ``unscii_16``: 16 px pixel perfect font with only ASCII characters. +- ``simsun_16_cjk``: 16 px font with normal range + 1000 most common `CJK Radicals `__. +- ``dejavu_16_persian_hebrew``: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms. + +.. _lvgl-styling: + +Style properties +**************** + +LVGL follows CSS's `border-box model `__. A widget's *box* is built from the following parts: + +.. figure:: /components/lvgl/images/lvgl_boxmodel.png + :align: center + +- *bounding box*: the box defined with ``width`` and ``height`` of the widgets (pixels or parent content area percentage; not drawn, just for calculations). +- *border*: the border line, drawn on the inner side of the bounding box (pixels). +- *outline*: the outline, drawn on the outer side of the bounding box (pixels). +- *padding*: space to keep between the border of the widget and its content or children (*I don't want my children too close to my sides, so keep this space*). +- *content*: the content area which is the size of the bounding box reduced by the border width and padding (it's what's referenced as the ``SIZE_CONTENT`` option of certain widgets). + +You can adjust the appearance of widgets by changing their foreground, background, border color and/or font. Some widgets allow for more complex styling, effectively changing all or part of their appearance. + +**Styling variables:** + +- **bg_color** (*Optional*, :ref:`color `): Color for the background of the widget. Defaults to ``0xFFFFFF`` (white). +- **bg_grad_color** (*Optional*, :ref:`color `): Color to make the background gradually fade to. Defaults to ``0`` (black). +- **bg_dither_mode** (*Optional*, dict): Set dithering of the background gradient. One of ``NONE``, ``ORDERED``, ``ERR_DIFF``. Defaults to ``NONE``. +- **bg_grad_dir** (*Optional*, dict): Choose the direction of the background gradient: ``NONE``, ``HOR``, ``VER``. Defaults to ``NONE``. +- **bg_main_stop** (*Optional*, 0-255): Specify where the gradient should start: ``0`` = upper left, ``128`` = in the center, ``255`` = lower right. Defaults to ``0``. +- **bg_grad_stop** (*Optional*, 0-255): Specify where the gradient should stop: ``0`` = upper left, ``128`` = in the center, ``255`` = lower right. Defaults to ``255``. +- **opa** (*Optional*, :ref:`opacity `): Opacity of the entire widget. Inherited from parent. Defaults to ``COVER``. +- **bg_opa** (*Optional*, :ref:`opacity `): Opacity of the widget background. +- **opa_layered** (*Optional*, :ref:`opacity `): Opacity of the entire layer the widget is on. Inherited from parent. Defaults to ``COVER``. +- **bg_image_src** (*Optional*, :ref:`image `): The ID of an existing image configuration, to show as the background of the widget. +- **bg_image_opa** (*Optional*, :ref:`opacity `): Opacity of the background image of the widget. +- **bg_image_recolor** (*Optional*, :ref:`color `): Color to mix with every pixel of the background image of the widget. +- **bg_image_recolor_opa** (*Optional*, :ref:`opacity `): Opacity of the recoloring of the background image of the widget. +- **border_width** (*Optional*, int16): Set the width of the border in pixels. Defaults to ``0``. +- **border_color** (*Optional*, :ref:`color `): Color to draw borders of the widget. Defaults to ``0`` (black). +- **border_opa** (*Optional*, :ref:`opacity `): Opacity of the borders of the widget. Defaults to ``COVER``. +- **border_post** (*Optional*, boolean): If ``true`` the border will be drawn after all children of the widget have been drawn. Defaults to ``false``. +- **border_side** (*Optional*, list): Select which borders of the widgets to show (multiple can be specified as a YAML list, defaults to ``NONE``): + - ``NONE`` + - ``TOP`` + - ``BOTTOM`` + - ``LEFT`` + - ``RIGHT`` + - ``INTERNAL`` +- **clip_corner** (*Optional*, boolean): If set to ``true``, overflowing content will be clipped off by the widget's rounded corners (``radius`` > ``0``). +- **color_filter_opa** (*Optional*, :ref:`opacity `): Opacity of the color filter. Currently color filters are applied only by the default LVGL theme, this option allows the effect of those to be disabled by setting to ``TRANSP``. +- **outline_width** (*Optional*, int16): Set the width of the outline in pixels. Defaults to ``0``. +- **outline_color** (*Optional*, :ref:`color `): Color used to draw an outline around the widget. Defaults to ``0`` (black). +- **outline_opa** (*Optional*, :ref:`opacity `): Opacity of the outline of the widget. Defaults to ``COVER``. +- **outline_pad** (*Optional*, int16): Distance between the outline and the widget itself. Defaults to ``0``. +- **pad_all** (*Optional*, int16): Set the padding in all directions, in pixels. +- **pad_top** (*Optional*, int16): Set the padding on the top, in pixels. +- **pad_bottom** (*Optional*, int16): Set the padding on the bottom, in pixels. +- **pad_left** (*Optional*, int16): Set the padding on the left, in pixels. +- **pad_right** (*Optional*, int16): Set the padding on the right, in pixels. +- **pad_row** (*Optional*, int16): Set the padding between the rows of the children elements, in pixels. +- **pad_column** (*Optional*, int16): Set the padding between the columns of the children elements, in pixels. +- **radius** (*Optional*, uint16): The radius to be used to form the widget's rounded corners. 0 = no radius (square corners); 65535 = pill shaped widget (true circle if it has same width and height). +- **shadow_color** (*Optional*, :ref:`color `): Color used to create a drop shadow under the widget. Defaults to ``0`` (black). +- **shadow_ofs_x** (*Optional*, int16): Horizontal offset of the shadow, in pixels. Defaults to ``0``. +- **shadow_ofs_y** (*Optional*, int16): Vertical offset of the shadow, in pixels. Defaults to ``0``. +- **shadow_opa** (*Optional*, :ref:`opacity `): Opacity of the shadow. Defaults to ``COVER``. +- **shadow_spread** (*Optional*, int16): Spread of the shadow, in pixels. Defaults to ``0``. +- **shadow_width** (*Optional*, int16): Width of the shadow, in pixels. Defaults to ``0``. +- **transform_angle** (*Optional*, 0-360): Transformation angle of the widget (eg. rotation) +- **transform_height** (*Optional*, int16 or percentage): Transformation height of the widget (eg. stretching) +- **transform_pivot_x** (*Optional*, int16): Horizontal anchor point of the transformation. Relative to the widget's top left corner. +- **transform_pivot_y** (*Optional*, int16): Vertical anchor point of the transformation. Relative to the widget's top left corner. +- **transform_zoom** (*Optional*, 0.1-10): Transformation zoom of the widget (eg. resizing) +- **translate_x** (*Optional*, int16 or percentage): Movement of the widget with this value in horizontal direction. +- **translate_y** (*Optional*, int16 or percentage): Movement of the widget with this value in vertical direction. + +.. _lvgl-theme: + +Themes +****** + +The widgets support lots of :ref:`lvgl-styling` to customize their appearance and behavior. + +You can configure a global theme for all widgets at the top level with the ``theme`` configuration variable. In the example below, all the ``arc``, ``slider`` and ``button`` widgets will, by default, use the styles and properties defined here. A combination of styles and :ref:`states ` can be chosen for every widget. + +.. code-block:: yaml + + lvgl: + theme: + arc: + scroll_on_focus: true + group: general + slider: + scroll_on_focus: true + group: general + button: + scroll_on_focus: true + group: general + border_width: 2 + outline_pad: 6 + pressed: + border_color: 0xFF0000 + checked: + border_color: 0xFFFF00 + focused: + border_color: 0x00FF00 + +Naturally, you can override these at the individual configuration level of each widget. This can be done in batches, using the ``style_definitions`` configuration variable of the main component. +In the example below, you defined ``date_style``: + +.. code-block:: yaml + + lvgl: + style_definitions: + - id: date_style # choose an ID for your definition + text_font: unscii_8 + align: center + text_color: 0x000000 + bg_opa: cover + radius: 4 + pad_all: 2 + +And then you apply these selected styles to two labels, and only change very specific style ``y`` locally: + +.. code-block:: yaml + + widgets: + - label: + id: day_label + styles: date_style # apply the definition here by the ID chosen above + y: -20 + - label: + id: date_label + styles: date_style + y: +20 + +Additionally, you can change the styles based on the :ref:`state ` property of the widgets or their parts. If you want to set a property for all states (e.g. red background color) just set it for the default state at the root of the widget. If the widget can't find a property for its current state it will fall back to this. + +In the example below, you have an ``arc`` with some styles set here. Note how you change the ``arc_color`` of the ``indicator`` part, based on state changes: + +.. code-block:: yaml + + - arc: + id: my_arc + value: 75 + min_value: 1 + max_value: 100 + indicator: + arc_color: 0xF000FF + pressed: + arc_color: 0xFFFF00 + focused: + arc_color: 0x808080 + +So the precedence happens like this: state based styles override the locally specified styles, which override the style definitions, which override the theme, which overrides the top level styles. The value precedence of states is quite intuitive and it's something the user would expect naturally. For example, if a widget is focused the user will still want to see if it's pressed, therefore the pressed state has a higher precedence. (If the focused state had a higher precedence it would override the *pressed* color, defeating its purpose.) + +Feel free to experiment to discover inheritance and precedence of the styles based on states between the nested widgets. + + +.. _lvgl-layouts: + +Layouts +******* + +Layouts aim to position widgets automatically, eliminating the need to specify ``x`` and ``y`` coordinates to position each widget. This is a great way to simplify your configuration as it allows you to omit alignment options. + +The layout configuration options are applied to any parent widget or page, influencing the appearance of the children. The position and size calculated by the layout overwrites the *normal* ``x``, ``y``, ``width``, and ``height`` settings of the children. + + +The ``hidden``, ``ignore_layout`` and ``floating`` :ref:`flags ` can be used on widgets to ignore them in layout calculations. + +**Configuration variables:** + +- **layout** (*Optional*, dict): A dictionary describing the layout configuration: + - **type** (*Optional*, string): ``FLEX``, ``GRID`` or ``NONE``. Defaults to ``NONE``. + - Further options from below depending on the chosen type. + +**Flex** + +The Flex layout in LVGL is a subset implementation of `CSS Flexbox `__. + +It can arrange items into rows or columns (tracks), handle wrapping, adjust spacing between items and tracks and even handle growing the layout to make the item(s) fill the remaining space with respect to minimum/maximum width and height. + +**Terms used:** + +- *track*: the rows or columns *main* direction flow: row or column in the direction in which the items are placed one after the other. +- *cross direction*: perpendicular to the main direction. +- *wrap*: if there is no more space in the track a new track is started. +- *gap*: the space between the rows and columns or the items on a track. +- *grow*: if set on an item it will grow to fill the remaining space on the track. The available space will be distributed among items respective to their grow value (larger value means more space). It dictates what amount of the available space the widget should take up. For example if all items on the track have a ``grow`` set to ``1``, the space in the track will be distributed equally to all of them. If one of the items has a value of 2, that one would take up twice as much of the space as either one of the others. + +**Configuration variables:** + + - **flex_flow** (*Optional*, string): Select the arrangement of the children widgets: + - ``ROW``: place the children in a row without wrapping. + - ``COLUMN``: place the children in a column without wrapping. + - ``ROW_WRAP``: place the children in a row with wrapping (default). + - ``COLUMN_WRAP``: place the children in a column with wrapping. + - ``ROW_REVERSE``: place the children in a row without wrapping but in reversed order. + - ``COLUMN_REVERSE``: place the children in a column without wrapping but in reversed order. + - ``ROW_WRAP_REVERSE``: place the children in a row with wrapping but in reversed order. + - ``COLUMN_WRAP_REVERSE``: place the children in a column with wrapping but in reversed order. + + - **flex_align_main** (*Optional*, string): Determines how to distribute the items in their track on the *main* axis. For example, flush the items to the right on with ``flex_flow: ROW_WRAP`` (known as *justify-content* in CSS). Possible options below. + - **flex_align_cross** (*Optional*, string): Determines how to distribute the items in their track on the *cross* axis. For example, if the items have different height place them to the bottom of the track (known as *align-items* in CSS). Possible options below. + - **flex_align_track** (*Optional*, string): Determines how to distribute the tracks (known as *align-content* in CSS). Possible options below. + + Values for use with ``flex_align_main``, ``flex_align_cross``, ``flex_align_track``: + + - ``START``: means left horizontally and top vertically (default). + - ``END``: means right horizontally and bottom vertically. + - ``CENTER``: simply center. + - ``SPACE_EVENLY``: items are distributed so that the spacing between any two items (and the space to the edges) is equal. Does not apply to ``flex_align_track``. + - ``SPACE_AROUND``: items are evenly distributed in the track with equal space around them. Note that visually the spaces aren’t equal, since all the items have equal space on both sides. The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Does not apply to ``flex_align_track``. + - ``SPACE_BETWEEN``: items are evenly distributed in the track: first item is on the start line, last item on the end line. Does not apply to ``flex_align_track``. + + - **pad_row** (*Optional*, int16): Set the padding between the rows, in pixels. + - **pad_column** (*Optional*, int16): Set the padding between the columns, in pixels. + - **flex_grow** (*Optional*, int16): Can be used to make one or more children fill the available space on the track. When one or more children have ``flex_grow`` set, the available space will be distributed proportionally to the grow values. Defaults to ``0``, which disables growing. + +.. code-block:: yaml + + # Example flex layout + + - obj: + layout: + type: flex + pad_row: 4 + pad_column: 4px + flex_align_main: center + flex_align_cross: start + flex_align_track: end + widgets: + - animimg: + flex_grow: 1 + +**Grid** + +The Grid layout in LVGL is a subset implementation of `CSS Grid `__. + +It can arrange items into a 2D "table" that has rows or columns (tracks). The item(s) can span through multiple columns or rows. The track's size can be set in pixels, to the largest item of the track (``CONTENT``) or in "free units" to distribute the free space proportionally. + +**Terms used:** + +- *tracks*: the rows or the columns. +- *gap*: the space between the rows and columns or the items on a track. +- *free unit (FR)*: a proportional distribution unit for the space available on the track. It accepts a unitless integer value that serves as a proportion. It dictates what amount of the available space the widget should take up. For example if all items on the track have a ``FR`` set to ``1``, the space in the track will be distributed equally to all of them. If one of the items has a value of 2, that one would take up twice as much of the space as either one of the others. + +**Configuration variables:** + + - **grid_rows** (**Required**): The number of rows in the grid, expressed a list of values in pixels, ``CONTENT`` or ``FR(n)`` (free units, where ``n`` is a proportional integer value). + - **grid_columns** (**Required**): The number of columns in the grid, expressed a list of values in pixels, ``CONTENT`` or ``FR(n)`` (free units, where ``n`` is a proportional integer value). + - **grid_row_align** (*Optional*, string): How to align the row. Works only when ``grid_rows`` is given in pixels. Possible options below. + - **grid_column_align** (*Optional*, string): How to align the column. Works only when ``grid_columns`` is given in pixels. Possible options below. + - **pad_row** (*Optional*, int16): Set the padding between the rows, in pixels. + - **pad_column** (*Optional*, int16): Set the padding between the columns, in pixels. + +In a grid layout, *all the widgets placed on the grid* will get some additional configuration variables to help with placement: + + - **grid_cell_row_pos** (**Required**, int16): Position of the widget, in which row to appear (0 based count). + - **grid_cell_column_pos** (**Required**, int16): Position of the widget, in which column to appear (0 based count). + - **grid_cell_x_align** (*Optional*, string): How to align the widget horizontally within the cell. Can also be applied through :ref:`lvgl-styling`. Possible options below. + - **grid_cell_y_align** (*Optional*, string): How to align the widget vertically within the cell. Can also be applied through :ref:`lvgl-styling`. Possible options below. + - **grid_cell_row_span** (*Optional*, int16): How many rows to span across the widget. Defaults to ``1``. + - **grid_cell_column_span** (*Optional*, int16): How many columns to span across the widget. . Defaults to ``1``. + + .. note:: + + These ``grid_cell_`` variables apply to widget configuations! + +Values for use with ``grid_column_align``, ``grid_row_align``, ``grid_cell_x_align``, ``grid_cell_y_align``: + + - ``START``: means left horizontally and top vertically (default). + - ``END``: means right horizontally and bottom vertically. + - ``CENTER``: simply center. + - ``STRETCH``: stretch the widget to the cell in the respective direction. Does not apply to ``grid_column_align``, ``grid_row_align``. + - ``SPACE_EVENLY``: items are distributed so that the spacing between any two items (and the space to the edges) is equal. + - ``SPACE_AROUND``: items are evenly distributed in the track with equal space around them. Note that visually the spaces aren’t equal, since all the items have equal space on both sides. The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. + - ``SPACE_BETWEEN``: items are evenly distributed in the track: first item is on the start line, last item on the end line. + +.. code-block:: yaml + + # Example grid layout + + - obj: + layout: + type: grid + grid_row_align: end + grid_rows: [25px, fr(1), content] + grid_columns: [40, fr(1), fr(1)] + pad_row: 6px + pad_column: 0 + widgets: + - image: + grid_cell_row_pos: 0 + grid_cell_column_pos: 0 + +.. tip:: + + To visualize real, calculated sizes of transparent widgets you can temporarily set ``outline_width: 1`` on them. + +Widgets +******* + +LVGL supports a list of :doc:`/components/lvgl/widgets` which can be used to draw interactive objects on the screen. + +Actions +------- + +Widgets support :ref:`general or specific ` actions. +Several actions are available for LVGL, these are outlined below. + +.. _lvgl-redraw-action: + +``lvgl.widget.redraw`` +********************** + +This :ref:`action ` redraws the entire screen, or optionally only a widget on it. + +- **id** (*Optional*): The ID of a widget configured in LVGL which you want to redraw; if omitted, the entire screen will be redrawn. + +.. code-block:: yaml + + on_...: + then: + - lvgl.widget.redraw: + +.. _lvgl-pause-action: + +``lvgl.pause`` +************** + +This :ref:`action ` pauses the activity of LVGL, including rendering. + +- **show_snow** (*Optional*, boolean): When paused, display random colored pixels across the entire screen in order to minimize screen burn-in, to relief the tension put on each individual pixel. + +.. code-block:: yaml + + on_...: + then: + - lvgl.pause: + show_snow: true + +.. _lvgl-resume-action: + +``lvgl.resume`` +*************** + +This :ref:`action ` resumes the activity of LVGL, including rendering. + +.. code-block:: yaml + + on_...: + then: + - lvgl.resume: + +``lvgl.update`` +*************** + +This :ref:`action ` allows changing/updating the ``disp_bg_color`` or ``disp_bg_image`` configuration variables of the main component, making it possible to change the background color or wallpaper at any time. + +.. code-block:: yaml + + # Examples: + on_...: + then: + - lvgl.update: + disp_bg_color: 0x0000FF + - lvgl.update: + disp_bg_image: cat_image + +.. _lvgl-page-next-previous-action: + +``lvgl.page.next``, ``lvgl.page.previous`` +****************************************** + +This :ref:`action ` changes the page to the next/previous based on the configuration (pages with their ``skip`` option enabled are...skipped). Page changes will wrap around at the end. + +- **animation** (*Optional*): Animate page changes as specified. One of: ``NONE``, ``OVER_LEFT``, ``OVER_RIGHT``, ``OVER_TOP``, ``OVER_BOTTOM``, ``MOVE_LEFT``, ``MOVE_RIGHT``, ``MOVE_TOP``, ``MOVE_BOTTOM``, ``FADE_IN``, ``FADE_OUT``, ``OUT_LEFT``, ``OUT_RIGHT``, ``OUT_TOP``, ``OUT_BOTTOM``. Defaults to ``NONE``. +- **time** (*Optional*, :ref:`Time `): Duration of the page change animation. Defaults to ``50ms``. + +.. code-block:: yaml + + on_...: + then: + - lvgl.page.next: + animation: OUT_LEFT + time: 300ms + + on_...: + then: + - lvgl.page.previous: + animation: OUT_RIGHT + time: 300ms + +.. _lvgl-page-show-action: + +``lvgl.page.show`` +****************** + +This :ref:`action ` shows a specific page (including pages with their ``skip`` option enabled). + +- **id** (**Required**): The ID of the page to be shown. +- **animation** (*Optional*): Animate page changes as specified. One of: ``NONE``, ``OVER_LEFT``, ``OVER_RIGHT``, ``OVER_TOP``, ``OVER_BOTTOM``, ``MOVE_LEFT``, ``MOVE_RIGHT``, ``MOVE_TOP``, ``MOVE_BOTTOM``, ``FADE_IN``, ``FADE_OUT``, ``OUT_LEFT``, ``OUT_RIGHT``, ``OUT_TOP``, ``OUT_BOTTOM``. Defaults to ``NONE``. +- **time** (*Optional*, :ref:`Time `): Duration of the page change animation. Defaults to ``50ms``. + +.. code-block:: yaml + + on_...: + then: + - lvgl.page.show: + id: secret_page + + on_...: + then: + - lvgl.page.show: secret_page # shorthand version + +.. _lvgl-conditions: + +Conditions +---------- + +.. _lvgl-is-idle-condition: + +``lvgl.is_idle`` +**************** + +This :ref:`condition ` checks if the amount of time specified has passed since the last touch event. + +- **timeout** (**Required**, :ref:`templatable `, int): Amount of :ref:`time ` expected since the last touch event. + +.. code-block:: yaml + + # In some trigger: + on_...: + then: + - if: + condition: lvgl.is_idle + timeout: 5s + then: + - light.turn_off: + id: display_backlight + transition_length: 3s + +.. _lvgl-is-paused-condition: + +``lvgl.is_paused`` +****************** + +This :ref:`condition ` checks if LVGL is in the paused state or not. + +.. code-block:: yaml + + # In some trigger: + on_...: + then: + - if: + condition: lvgl.is_paused + then: + - lvgl.resume: + +Triggers +-------- + +Widget level :ref:`interaction triggers ` can be configured universally, or depending on the widtget functionality. + +.. _lvgl-on-idle-trigger: + +``lvgl.on_idle`` +**************** + +LVGL has a notion of screen inactivity -- in other words, the time since the last user interaction with the screen is tracked. This can be used to dim the display backlight or turn it off after a moment of inactivity (like a screen saver). Every use of an input device (touchscreen, rotary encoder) counts as an activity and resets the inactivity counter. + +The ``on_idle`` :ref:`triggers ` are activated when inactivity time becomes longer than the specified ``timeout``. You can configure any desired number of timeouts with different actions. + +- **timeout** (**Required**, :ref:`templatable `, int): :ref:`Time ` that has elapsed since the last touch event, after which you want your actions to be performed. + +.. code-block:: yaml + + lvgl: + ... + on_idle: + - timeout: 30s + then: + - lvgl.page.show: main_page + - timeout: 60s + then: + - light.turn_off: display_backlight + - lvgl.pause: + + +See Also +-------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +- :doc:`/components/display/index` +- :doc:`/components/touchscreen/index` +- :doc:`/components/sensor/rotary_encoder` +- `LVGL docs `__ +- :ghedit:`Edit` diff --git a/components/lvgl/widgets.rst b/components/lvgl/widgets.rst new file mode 100644 index 0000000000..ea9ac7ee88 --- /dev/null +++ b/components/lvgl/widgets.rst @@ -0,0 +1,1847 @@ +LVGL Widgets +============ + +At the next level of the LVGL object hierarchy are the widgets, which support styling directly. They can have sub-parts, which may be styled separately. Usually styles are inherited, but this depends on widget specifics or functionality. The widget and its parts have states, and different styling can be set for different states. + +Widgets can have children, which can be any other widgets. Think of this as a nested structure. The child widgets move with the parent and, if the parent is hidden, its children will also be hidden. + +By default, LVGL draws new widgets on top of old widgets, including their children. When widgets have children, property inheritance takes place. Some properties (typically those related to text and opacity) can be inherited from the parent widgets's styles. When the property is inheritable, the parent will be searched for an object which specifies a value for the property. The parents will use their own :ref:`state ` to determine the value. For example, if a button is pressed and the text color is defined by the "pressed" state, this "pressed" text color will be used. + +Common properties +----------------- + +The properties below are common to all widgets. + +**Configuration variables:** + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **x** (*Optional*, int16 or percentage): Horizontal position of the widget. +- **y** (*Optional*, int16 or percentage): Vertical position of the widget. + +.. note:: + + By default, the ``x`` and ``y`` coordinates are measured from the *top left corner* of the parent's content area. :ref:`Important `: content area starts *after the padding* thus if the parent has a non-zero padding value, position will be shifted with that. Percentage values are calculated from the parent's content area size. + + If specifying ``align``, ``x`` and ``y`` can be used as an offset to the calculated position (can also be negative). They are ignored if :ref:`lvgl-layouts` are used on the parent. + +- **height** (*Optional*): Height of the widget in pixels or a percentage, or ``SIZE_CONTENT``. +- **width** (*Optional*): Width of the widget in pixels or a percentage, or ``SIZE_CONTENT``. + +.. note:: + + The size settings support a special value: ``SIZE_CONTENT``. It means the widget's size in the respective direction will be set to the size of its children. Note that only children on the right and bottom sides will be considered and children on the top and left remain cropped. This limitation makes the behavior more predictable. Widgets with ``hidden`` or ``floating`` flags will be ignored by the ``SIZE_CONTENT`` calculation. + + Similarly to CSS, LVGL also supports ``min_width``, ``max_width``, ``min_height`` and ``max_height``. These are limits preventing a widget's size from becoming smaller/larger than these values. They are especially useful if the size is set by percentage or ``SIZE_CONTENT``. + +- **min_width**, **max_width**, **min_height**, **max_height** (*Optional*, int16 or percentage): Sets a minimal/maximal width or a minimal/maximal height. Pixel and percentage values can be used. Percentage values are relative to the dimensions of the parent's content area. Defaults to ``0%``. +- **scrollbar_mode** (*Optional*, string): If a child widget is outside its parent content area (the size without padding), the parent can become scrollable (see the ``scrollable`` :ref:`flag `). The widget can either be scrolled horizontally or vertically in one stroke. Scroll bars can appear depending on the setting: + - ``"OFF"``: Never show the scroll bars (use the double quotes!). + - ``"ON"``: Always show the scroll bars (use the double quotes!). + - ``"ACTIVE"``: Show scroll bars while a widget is being scrolled. + - ``"AUTO"``: Show scroll bars when the content is large enough to be scrolled (default). + +- **align** (*Optional*, dict): Alignment of the of the widget relative to the parent. A child widget is clipped to its parent boundaries. One of the values *not* starting with ``OUT_`` (see picture below). +- **align_to** (*Optional*, list): Alignment of the of the widget relative to another widget on the same level: + - **id** (**Required**): The ID of a widget *to* which you want to align. + - **align** (**Required**, string): Desired alignment (one of the values starting with ``OUT_``). + - **x** (*Optional*, int16 or percentage): Horizontal offset position. Default ``0``. + - **y** (*Optional*, int16 or percentage): Vertical offset position. Default ``0``. + +.. figure:: /components/lvgl/images/lvgl_align.png + :align: center + +- **group** (*Optional*, string): The name of the group of widgets which will interact with a :doc:`/components/sensor/rotary_encoder`. In every group there is always one focused widget which receives the encoder actions. You need to associate an input device with a group. An input device can send key events to only one group but a group can receive data from more than one input device. If no group is specified for a widget or an encoder, an unnamed default group will be assigned, so in most cases where only one encoder is used it will not be necessary to explicitly specify a group. +- **layout** (*Optional*): See :ref:`lvgl-layouts` for details. Defaults to ``NONE``. +- **styles** (*Optional*, :ref:`config-id`): The ID of a *style definition* from the main component configuration to override the theme styles. +- **theme** (*Optional*, list): A list of styles to apply to the widget and children. Same configuration option as at the main component. +- **widgets** (*Optional*, list): A list of LVGL widgets to be drawn as children of this widget. Same configuration option as at the main component. + +.. _lvgl-widgetproperty-state: + +- **state** (*Optional*, dict): Widgets or their (sub)parts can have have states, which support separate styling. These state styles inherit from the theme, but can be locally set or overridden within style definitions. Can be one of: + - **checked** (*Optional*, boolean): Toggled or checked state. + - **default** (*Optional*, boolean): Normal, released state. + - **disabled** (*Optional*, boolean): Disabled state (also usable with :ref:`shorthand ` actions ``lvgl.widget.enable`` and ``lvgl.widget.disable``). + - **edited** (*Optional*, boolean): Edit by an encoder. + - **focus_key** (*Optional*, boolean): Focused via keypad or encoder but *not* via touch screen. + - **focused** (*Optional*, boolean): Focused via keypad or encoder or clicked via touch screen. + - **pressed** (*Optional*, boolean): Being pressed. + - **scrolled** (*Optional*, boolean): Being scrolled. + - **user_1**, **user_2**, **user_3**, **user_4** (*Optional*, boolean): Custom states. + +By default, states are all ``false``, and they are templatable. +To apply styles to the states, you need to specify them one level above, for example: + +.. code-block:: yaml + + - button: + checkable: true + state: + checked: true # here you activate the state to be used at boot + checked: + bg_color: 0x00FF00 # here you apply styles to be used when in the respective state + +The state itself can be can be changed by interacting with the widget, or through :ref:`actions ` with ``lvgl.widget.update``. + +.. _lvgl-widget-flags: + +In addition to visual styling, each widget supports some boolean **flags** to influence the behavior: + +- **adv_hittest** (*Optional*, boolean): allow performing more accurate hit (click) test. For example, may help by accounting for rounded corners. +- **checkable** (*Optional*, boolean): toggle checked state when the widget is clicked. +- **click_focusable** (*Optional*, boolean): add focused state to the widget when clicked. +- **clickable** (*Optional*, boolean): make the widget clickable by input devices. Defaults to ``true``. If ``false``, it will pass the click to the widgets behind it (clicking through). +- **event_bubble** (*Optional*, boolean): propagate the events to the parent. +- **floating** (*Optional*, boolean): do not scroll the widget when the parent scrolls and ignore layout. +- **gesture_bubble** (*Optional*, boolean): propagate the gestures to the parent. +- **hidden** (*Optional*, boolean): make the widget hidden (like it wasn't there at all), also usable with :ref:`shorthand ` actions ``lvgl.widget.show`` and ``lvgl.widget.hide``. Hidden objects are ignored in layout calculations. Defaults to ``false``. +- **ignore_layout** (*Optional*, boolean): the widget is simply ignored by the layouts. Its coordinates can be set as usual. +- **layout_1**, **layout_2** (*Optional*, boolean): custom flags, free to use by layouts. +- **overflow_visible** (*Optional*, boolean): do not clip the children's content to the parent's boundary. +- **press_lock** (*Optional*, boolean): keep the widget pressed even if the press slid from the widget. +- **scroll_chain simple** (*Optional*, boolean): packaging for (``scroll_chain_hor | scroll_chain_ver``). +- **scroll_chain_hor** (*Optional*, boolean): allow propagating the horizontal scroll to a parent. +- **scroll_chain_ver** (*Optional*, boolean): allow propagating the vertical scroll to a parent. +- **scroll_elastic** (*Optional*, boolean): allow scrolling inside but with slower speed. +- **scroll_momentum** (*Optional*, boolean): make the widget scroll further when "thrown". +- **scroll_on_focus** (*Optional*, boolean): automatically scroll widget to make it visible when focused. +- **scroll_one** (*Optional*, boolean): allow scrolling only on ``snappable`` children. +- **scroll_with_arrow** (*Optional*, boolean): allow scrolling the focused widget with arrow keys. +- **scrollable** (*Optional*, boolean): the widget can become scrollable. Defaults to ``true`` (also see the ``scrollbar_mode`` property). +- **snappable** (*Optional*, boolean): if scroll snap is enabled on the parent it can snap to this widget. +- **user_1**, **user_2**, **user_3**, **user_4** (*Optional*, boolean): custom flags, free to use by user. +- **widget_1**, **widget_2** (*Optional*, boolean): custom flags, free to use by widget. + +.. note:: + + LVGL only supports **integers** for numeric ``value``. Visualizer widgets can't display floats directly, but they allow scaling by 10s. + +Widget-specific properties +-------------------------- + +Some widgets have properties that are specific to that widget. For example ``label`` has a ``text`` property. The properties +specific to a widget are described in each section below. Some of these properties may also be updated with a corresponding +``lvgl..update`` action, e.g. ``lvgl.label.update`` allows updating not only the common style properties, +but also the ``text`` property of a label. + + +.. _text-property: + +Text property +------------- + +Several widgets have a ``text`` property, and the possible ways this can be specified are common to all ``text`` properties. +The text may be a Unicode string or other constant convertible to a string; if the string is enclosed in double quotes ``""`` then +standard escape sequences sucn as newline ``\n`` and Unicode codepoints will be translated. +The text value may also be a lambda returning a ``std::string`` or may be +specified with a ``format`` property utilising ``printf`` style formatting. There is also a ``time_format`` option +which allows use of `strftime `_ formats. + + +**Examples:** + +.. code-block:: yaml + + # Example label + - label: + id: label_id + text: "Text string" + - checkbox: + id: checkbox_id + text: "\uF00C" # Unicode check-mark + + + on_...: + - lvgl.label.update: + id: label_id + text: + format: "%d bells, %d things" + args: [x, 10] # x is a value from the enclosing trigger. + - lvgl.label.update: + id: label_id + text: !lambda return id(text_sensor).state; + - lvgl.label.update: + id: label_id + text: + time_format: "%c" # uses default time component + - lvgl.checkbox.update: + id: checkbox_id + text: + time_format: "%c" + time: sntp_id + - lvgl.label.update: + id: label_id + text: + time_format: "%c" + time: !lambda return id(sntp_id).utcnow(); + + + +.. _lvgl-widget-animimg: + +``animimg`` +----------- + +The animation image is similar to the normal ``image`` widget. The main difference is that instead of one source image, you set a list of multiple source images. You can also specify a duration and a repeat count. + +.. figure:: /components/lvgl/images/lvgl_animimg.gif + :align: center + +**Configuration variables:** + +- **src** (**Required**, list of :ref:`images `): A list of IDs of existing image configurations to be loaded as frames of the animation. +- **auto_start** (*Optional*, boolean): Start the animation playback automatically at boot and when updating the widget. Defaults to ``true``. +- **duration** (**Required**, :ref:`Time `): Total duration of a playback cycle (each frame is displayed for an equal amount of time). +- **repeat_count** (*Optional*, int16 or *forever*): The number of times playback should be repeated. Defaults to ``forever``. +- Some style options from :ref:`lvgl-styling` for the background rectangle that uses the typical background style properties and the image itself using the image style properties. + +**Actions:** + +- ``lvgl.animimg.start`` :ref:`action ` starts the animation playback if it was displayed with ``auto_start`` false or after ``repeat_count`` expired. + - **id** (**Required**): The ID or a list of IDs of animimg widgets which you want start. + +- ``lvgl.animimg.stop`` :ref:`action ` stops the animation playback. + - **id** (**Required**): The ID or a list of IDs of animimg widgets which you want stop. + +- ``lvgl.animimg.update`` :ref:`action ` can be used to change ``repeat_count`` and ``duration``, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. ``src`` and ``auto_start`` cannot be updated at runtime. + - **id** (**Required**): The ID or a list of IDs of animimg widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - animimg: + align: CENTER + id: anim_id + src: [ cat_image, cat_image_bowtie ] + duration: 1000ms + + # Example actions: + on_...: + then: + - lvgl.animimg.update: + id: anim_id + repeat_count: 100 + duration: 300ms + +.. _lvgl-widget-arc: + +``arc`` +------- + +The arc consists of a background and a foreground arc. The indicator foreground can be touch-adjusted with a knob. + +.. figure:: /components/lvgl/images/lvgl_arc.png + :align: center + +**Configuration variables:** + +- **adjustable** (*Optional*, boolean): Add a knob that the user can move to change the value. Defaults to ``false``. +- **arc_color** (*Optional*, :ref:`color `): Color used to draw the arc. +- **arc_opa** (*Optional*, :ref:`opacity `): Opacity of the arc. +- **arc_rounded** (*Optional*, boolean): Make the end points of the arcs rounded. ``true`` rounded, ``false`` perpendicular line ending. +- **arc_width** (*Optional*, int16): Set the width of the arcs in pixels. +- **change_rate** (*Optional*, int8): If the arc is pressed the current value will set with a limited speed according to the set change rate. The change rate is defined in degree/second. Defaults to ``720``. +- **end_angle** (*Optional*, 0-360): end angle of the arc background (see note). Defaults to ``45``. +- **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. Draws *another arc using the arc style* properties. Its padding values are interpreted relative to the background arc. +- **knob** (*Optional*, list): Settings for the knob *part* to control the value. Supports a list of :ref:`styles ` and state-based styles to customize. Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width. Larger padding makes it larger, smaller padding makes it smaller. +- **max_value** (*Optional*, int8): Maximum value of the indicator. Defaults to ``100``. +- **min_value** (*Optional*, int8): Minimum value of the indicator. Defaults to ``0``. +- **mode** (*Optional*, string): ``NORMAL``: the indicator is drawn from the minimum value to the current. ``REVERSE``: the indicator is drawn counter-clockwise from the maximum value to the current. ``SYMMETRICAL``: the indicator is drawn from the middle point to the current value. Defaults to ``NORMAL``. +- **rotation** (*Optional*, 0-360): Offset to the 0 degree position. Defaults to ``0.0``. +- **start_angle** (*Optional*, 0-360): start angle of the arc background (see note). Defaults to ``135``. +- **value** (**Required**, int8): Actual value of the indicator at start, in ``0``-``100`` range. Defaults to ``0``. +- Any :ref:`Styling ` and state-based option to override styles inherited from parent. The arc's size and position will respect the padding style properties. + +If the ``adv_hittest`` :ref:`flag ` is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. + +.. note:: + + The zero degree position is at the middle right (3 o'clock) of the widget and the degrees increase in a clockwise direction from there. Angles are specified in the ``0``-``360`` range. + +**Actions:** + +- ``lvgl.arc.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of arc widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when the knob changes the value of the arc. The new value is returned in the variable ``x``. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - arc: + x: 10 + y: 10 + id: arc_id + value: 75 + min_value: 0 + max_value: 100 + adjustable: true + + # Example action: + on_...: + then: + - lvgl.arc.update: + id: arc_id + knob: + bg_color: 0x00FF00 + value: 55 + + # Example trigger: + - arc: + ... + on_value: + - logger.log: + format: "Arc value is: %.0f" + args: [ 'x' ] + +.. note:: + + The ``on_value`` trigger is sent as the arc knob is dragged or changed with keys. The event is sent *continuously* while the arc knob is being dragged; this generally has a negative effect on performance. To mitigate this, consider using a :ref:`universal interaction trigger ` like ``on_release``, to get the ``x`` variable once after the interaction has completed. + +The ``arc`` can be also integrated as :doc:`Number ` or :doc:`Sensor ` component. + +.. _lvgl-widget-bar: + +``bar`` +------- + +The bar widget has a background and an indicator foreground on it. The size of the indicator is set according to the current ``value`` of the bar. + +.. figure:: /components/lvgl/images/lvgl_bar.png + :align: center + +Vertical bars can be created if the width is smaller than the height. + +Not only the end, but also the start value of the bar can be set, which changes the start position of the indicator. + +**Configuration variables:** + +- **anim_time** (*Optional*, :ref:`Time `): Sets the animation time if the value is set with ``animated: true``. +- **animated** (*Optional*, boolean): Animate the indicator when the bar changes value. Defaults to ``true``. +- **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize, all the typical background properties. +- **max_value** (*Optional*, int8): Maximum value of the indicator. Defaults to ``100``. +- **min_value** (*Optional*, int8): Minimum value of the indicator. Defaults to ``0``. +- **mode** (*Optional*, string): ``NORMAL``: the indicator is drawn from the minimum value to the current. ``REVERSE``: the indicator is drawn counter-clockwise from the maximum value to the current. ``SYMMETRICAL``: the indicator is drawn from the middle point to the current value. Defaults to ``NORMAL``. +- **value** (**Required**, int8): Actual value of the indicator at start, in ``0``-``100`` range. Defaults to ``0``. +- Style options from :ref:`lvgl-styling`. The background of the bar and it uses the typical background style properties. Adding padding will make the indicator smaller or larger. + +**Actions:** + +- ``lvgl.bar.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of bar widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - bar: + x: 10 + y: 100 + id: bar_id + value: 75 + min_value: 1 + max_value: 100 + + # Example action: + on_...: + then: + - lvgl.bar.update: + id: bar_id + value: 55 + +The ``bar`` can be also integrated as :doc:`Number ` or :doc:`Sensor ` component. + +.. _lvgl-widget-button: + +``button`` +---------- + +Simple push (momentary) or toggle (two-states) button. + +.. figure:: /components/lvgl/images/lvgl_button.png + :align: center + +**Configuration variables:** + +- **checkable** (*Optional*, boolean): A significant :ref:`flag ` to make a toggle button (which remains pressed in ``checked`` state). Defaults to ``false``. +- Style options from :ref:`lvgl-styling` for the background of the button. Uses the typical background style properties. + +A notable state is ``checked`` (boolean) which can have different styles applied. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated after clicking. If ``checkable`` is ``true``, the boolean variable ``x``, representing the checked state, may be used by lambdas within this trigger. +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - button: + x: 10 + y: 10 + width: 50 + height: 30 + id: btn_id + +To have a button with a text label on it, add a child :ref:`lvgl-widget-label` widget to it: + +.. code-block:: yaml + + # Example toggle button with text: + - button: + x: 10 + y: 10 + width: 70 + height: 30 + id: btn_id + checkable: true + widgets: + - label: + align: center + text: "Light" + + # Example trigger: + - button: + ... + on_value: + then: + - logger.log: + format: "Button checked state: %d" + args: [ x ] + +The ``button`` can be also integrated as a :doc:`Binary Sensor ` or as a :doc:`Switch ` component. + +.. _lvgl-widget-buttonmatrix: + +``buttonmatrix`` +---------------- + +The button matrix widget is a lightweight way to display multiple buttons in rows and columns. It's lightweight because the buttons are not actually created but instead simply drawn on the fly. This reduces the memory footprint of each button from approximately 200 bytes (for both the button and its label widget) down to only eight bytes. + +.. figure:: /components/lvgl/images/lvgl_buttonmatrix.png + :align: center + +**Configuration variables:** + +- **rows** (**Required**, list): A list for the button rows: + - **buttons** (**Required**, list): A list of buttons in a row: + - **id** (*Optional*): An ID for the button in the matrix. + - **key_code** (*Optional*, string): One character be sent as the key code to a :ref:`key_collector` instead of ``text`` when the button is pressed. + - **selected** (*Optional*, boolean): Set the button as the most recently released or focused. Defaults to ``false``. + - **text** (*Optional*, :ref:`text-property`): Text to display on the button. + - **width** (*Optional*): Width relative to the other buttons in the same row. Must be a value between ``1`` and ``15``; the default is ``1`` (for example, given a line with two buttons, one with ``width: 1`` and another one with ``width: 2``, the first will be ``33%`` wide while the second will be ``66%`` wide). + - **control** (*Optional*): Binary flags to control behavior of the buttons (all ``false`` by default): + - **checkable** (*Optional*, boolean): Enable toggling of a button, ``checked`` state will be added/removed as the button is clicked. + - **checked** (*Optional*, boolean): Make the button checked. Apply ``checked`` styles to the button. + - **click_trig** (*Optional*, boolean): Control how to :ref:`trigger ` ``on_value`` : if ``true`` on *click*, if ``false`` on *press*. + - **custom_1** and **custom_2** (*Optional*, boolean): Custom, free to use flags. + - **disabled** (*Optional*, boolean): Apply ``disabled`` styles to the button. + - **hidden** (*Optional*, boolean): Make a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable). + - **no_repeat** (*Optional*, boolean): Disable repeating when the button is long pressed. + - **popover** (*Optional*, boolean): Show the button label in a popover when pressing this button. + - **recolor** (*Optional*, boolean): Enable recoloring of button text with ``#``. For example: ``It's #FF0000 red#`` + +- **items** (*Optional*, list): Settings for the items *part*, the buttons all use the text and typical background style properties except translations and transformations. +- **one_checked** (*Optional*, boolean): Allow only one button to be checked at a time (aka. radio buttons). Defaults to ``false``. +- Style options from :ref:`lvgl-styling` for the background of the button matrix, uses the typical background style properties. ``pad_row`` and ``pad_column`` set the space between the buttons. + +**Actions:** + +- ``lvgl.buttonmatrix.update`` :ref:`action ` updates the item styles and properties specified in the specific ``state``, ``items`` options. + - **id** (**Required**): The ID or a list of IDs of buttonmatrix widgets which you want update. + - Widget styles or properties from ``state``, ``items`` options above, which you want update. + +- ``lvgl.matrix.button.update`` :ref:`action ` updates the button styles and properties specified in the specific ``control``, ``width`` and ``selected`` options. + - **id** (**Required**): The ID or a list of IDs of matrix buttons which you want update. + - Widget styles or properties from ``control``, ``width`` and ``selected`` options above, which you want update. + +**Triggers:** + +- ``on_value`` and :ref:`interaction ` triggers can be configured for each button, is activated after clicking. If ``checkable`` is ``true``, the boolean variable ``x``, representing the checked state, may be used by lambdas within this trigger. +- The :ref:`interaction ` LVGL event triggers can be configured for the main widget, they pass the ID of the pressed button (or null if nothing pressed) as variable ``x`` (a pointer to a ``uint16_t`` which holds the index number of the button). + +**Example:** + +.. code-block:: yaml + + # Example widget: + - buttonmatrix: + x: 10 + y: 40 + width: 220 + items: + pressed: + bg_color: 0xFFFF00 + id: matrix_id + rows: + - buttons: + - id: button_1 + text: "\uF04B" + control: + checkable: true + - id: button_2 + text: "\uF04C" + control: + checkable: true + - buttons: + - id: button_3 + text: "A" + control: + popover: true + - id: button_4 + text: "B" + control: + disabled: true + - buttons: + - id: button_5 + text: "It's #ff0000 red#" + width: 2 + control: + recolor: true + + # Example action: + on_...: + then: + - lvgl.matrix.button.update: + id: button_1 + width: 1 + selected: true + control: + checkable: false + - lvgl.buttonmatrix.update: + id: matrix_id + state: + disabled: true + items: + bg_color: 0xf0f0f0 + + # Example trigger: + - buttonmatrix: + ... + rows: + - buttons: + ... + - id: button_2 + ... + control: + checkable: true + on_value: # Trigger for the individual button, returning the checked state + then: + - logger.log: + format: "Button 2 checked: %d" + args: [ x ] + on_press: # Triggers for the matrix, to determine which button was pressed. + logger.log: + format: "Matrix button pressed: %d" + args: ["x"] # If x is 65535, it was the container, (or through a disabled button). + on_click: + logger.log: + format: "Matrix button clicked: %d, is button_2 = %u" + args: ["x", "id(button_2) == x"] + +.. tip:: + + The Button Matrix widget supports the :ref:`key_collector` to collect the button presses as key press sequences for further automations. + +.. _lvgl-widget-checkbox: + +``checkbox`` +------------ + +The checkbox widget is made internally from a *tick box* and a label. When the checkbox is clicked the tick box's ``checked`` state will be toggled. + +.. figure:: /components/lvgl/images/lvgl_checkbox.png + :align: center + +**Configuration variables:** + +- **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. The "tick box" is a square that uses all the typical background style properties. By default, its size is equal to the height of the main part's font. Padding properties make the tick box larger in the respective directions. +- Style options from :ref:`lvgl-styling` for the background of the widget and it uses the text and all the typical background style properties. ``pad_column`` adjusts the spacing between the tick box and the label. + +**Actions:** + +- ``lvgl.checkbox.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of checkbox widgets which you want update. + - **text** (*Optional*, :ref:`text-property`): Text to display beside the checkbox. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +``on_value`` :ref:`trigger ` is activated when toggling the checkbox. The boolean variable ``x``, representing the checkbox's state, may be used by lambdas within this trigger. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - checkbox: + x: 10 + y: 10 + id: checkbox_id + text: Checkbox + + # Example action: + on_...: + then: + - lvgl.checkbox.update: + id: checkbox_id + state: + checked: true + text: Checked + + # Example trigger: + - checkbox: + ... + on_value: + then: + - logger.log: + format: "Checkbox state: %d" + args: [ x ] + +.. note:: + + In case you configure ``default_font`` in the main section to a custom font, the checkmark will not be shown correctly when the checkbox is in the checked state. + +The ``checkbox`` can be also integrated as a :doc:`Switch ` component. + +.. _lvgl-widget-dropdown: + +``dropdown`` +------------ + +The dropdown widget allows the user to select one value from a list. + +The dropdown list is closed by default and displays a single value. When activated (by clicking on the drop-down list), a list is drawn from which the user may select one option. When the user selects a new value, the list is deleted from the screen. + +.. figure:: /components/lvgl/images/lvgl_dropdown.png + :align: center + +The Dropdown widget is built internally from a *button* part and a *list* part (both not related to the actual widgets with the same name). + +**Configuration variables:** + +- **dir** (*Optional*, dict): Where the list part of the dropdown gets created relative to the button part. ``LEFT``, ``RIGHT``, ``BOTTOM``, ``TOP``, defaults to ``BOTTOM``. +- **dropdown_list** (*Optional*, list): Settings for the dropdown_list *part*, the list with items. Supports a list of :ref:`styles ` to customize. Notable are ``text_line_space`` and ``pad_all`` for spacing of list items, and ``text_font`` to separately change the font in the list. +- **indicator** (*Optional*, list): Settings for the the parent of ``symbol``. Supports a list of :ref:`styles ` to customize. +- **options** (**Required**, list): The list of available options in the drop-down. +- **scrollbar** (*Optional*, list): Settings for the scrollbar *part*. Supports a list of :ref:`styles ` to customize. The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right. +- **selected_index** (*Optional*, int8): The index of the item you wish to be selected. +- **selected** (*Optional*, list): Settings for the selected item in the list. Supports a list of :ref:`styles ` to customize. +- **symbol** (*Optional*, dict): A symbol (typically an chevron) is shown in dropdown list. If ``dir`` of the drop-down list is ``LEFT`` the symbol will be shown on the left, otherwise on the right. Choose a different :ref:`symbol ` from those built-in or from your own customized font. +- Style options from :ref:`lvgl-styling` for the background of the button and the list. Uses the typical background properties and :ref:`lvgl-widget-label` text properties for the text on it. ``max_height`` can be used to limit the height of the list. ``text_font`` can be used to set the font of the button part, including the symbol. + +**Actions:** + +- ``lvgl.dropdown.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of dropdown widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated only when you select an item from the list. The new selected index is returned in the variable ``x``. The :ref:`interaction ` LVGL event triggers also apply, and they also return the selected index in ``x``. +- ``on_cancel`` :ref:`trigger ` is also activated when you close the dropdown without selecting an item from the list. The currently selected index is returned in the variable ``x``. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - dropdown: + id: dropdown_id + width: 90 + align: CENTER + options: + - Violin + - Piano + - Bassoon + - Chello + - Drums + selected_index: 2 + + # Example action: + on_...: + then: + - lvgl.dropdown.update: + id: dropdown_id + selected_index: 4 + + # Example trigger: + - dropdown: + ... + on_value: + - logger.log: + format: "Selected index is: %d" + args: [ x ] + on_cancel: + - logger.log: + format: "Dropdown closed. Selected index is: %d" + args: [ x ] + +The ``dropdown`` can be also integrated as :doc:`Select ` component. + +.. _lvgl-widget-image: + +``image`` +--------- + +Images are the basic widgets used to display images. + +.. figure:: /components/lvgl/images/lvgl_image.png + :align: center + +**Configuration variables:** + +- **angle** (*Optional*, 0-360): Rotation of the image. Defaults to ``0.0``. Needs ``pivot_x`` and ``pivot_y`` to be specified. +- **antialias** (*Optional*): The quality of the angle or scale transformation. When anti-aliasing is enabled, the transformations are higher quality but slower. Defaults to ``false``. +- **mode** (*Optional*): Either ``REAL`` or ``VIRTUAL``. With ``VIRTUAL``, when the image is scaled or rotated, the real coordinates of the image object are not changed. The larger content simply overflows the object's boundaries. It also means the layouts are not affected the by the transformations. With ``REAL``, if the width/height of the object is set to ``SIZE_CONTENT``, the object's size will be set to the scaled and rotated size. If an explicit size is set, the overflowing content will be cropped. Defaults to ``VIRTUAL``. +- **offset_x** (*Optional*): Add a horrizontal offset to the image position. +- **offset_y** (*Optional*): Add a vertical offset to the image position. +- **pivot_x** (*Optional*): Horizontal position of the pivot point of rotation, in pixels, relative to the top left corner of the image. +- **pivot_y** (*Optional*): Vertical position of the pivot point of rotation, in pixels, relative to the top left corner of the image. +- **scale** (*Optional*, 0.1-10): Zoom of the image. +- **src** (**Required**, :ref:`image `): The ID of an existing image configuration. +- Some style options from :ref:`lvgl-styling` for the background rectangle that uses the typical background style properties and the image itself using the image style properties. + +**Actions:** + +- ``lvgl.image.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. Updating the ``src`` option changes the image at runtime. + - **id** (**Required**): The ID or a list of IDs of image widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - image: + align: CENTER + src: cat_image + id: img_id + radius: 11 + clip_corner: true + + # Example action: + on_...: + then: + - lvgl.image.update: + id: img_id + src: cat_image_bowtie + +.. note:: + + Currently ``RGB565`` type images are supported, with transparency using the optional parameter ``use_transparency`` set to ``true``. See :ref:`display-image` for how to load an image for rendering in ESPHome. + +.. tip:: + + ``offset_x`` and ``offset_y`` can be useful when the widget size is set to be smaller than the image source size. A "running image" effect can be created by animating these values. + +.. _lvgl-widget-keyboard: + +``keyboard`` +------------ + +The keyboard widget is a special Button matrix with predefined keymaps and other features to show an on-screen keyboard usable to type text into a :ref:`lvgl-widget-textarea`. + +.. figure:: /components/lvgl/images/lvgl_keyboard.png + :align: center + +For styling, the ``keyboard`` widget uses the same settings as :ref:`lvgl-widget-buttonmatrix`. + +**Configuration variables:** + +- **textarea** (*Optional*): The ID of the ``textarea`` from which to receive the keystrokes. +- **mode** (*Optional*, dict): Keyboard layout to use. Each ``TEXT_`` layout contains a button to allow the user to iterate through the ``TEXT_`` layouts. + - ``TEXT_LOWER``: Display lower case letters (default). + - ``TEXT_UPPER``: Display upper case letters. + - ``TEXT_SPECIAL``: Display special characters. + - ``NUMBER``: Display numbers, +/- sign, and decimal dot. + +**Actions:** + +- ``lvgl.keyboard.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of keyboard widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- ``on_ready`` :ref:`trigger ` is activated when the checkmark key is pressed. +- ``on_cancel`` :ref:`trigger ` is activated when the key containing the keyboard icon is pressed. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - keyboard: + id: keyboard_id + textarea: textarea_1 + mode: TEXT_UPPER + + # Example actions: + on_focus: + then: + - lvgl.keyboard.update: + id: keyboard_id + mode: number + textarea: textarea_2 + + # Example trigger: + - keyboard: + ... + on_ready: + then: + - logger.log: Keyboard is ready + on_cancel: + then: + - logger.log: Keyboard cancelled + +.. tip:: + + The Keyboard widget supports the :ref:`key_collector` to collect the button presses as key press sequences for further automations. + +.. note:: + + The Keyboard widget in ESPHome doesn't support popovers or custom layouts. + +.. _lvgl-widget-label: + +``label`` +--------- + +A label is the basic widget type that is used to display text. + +.. figure:: /components/lvgl/images/lvgl_label.png + :align: center + +**Configuration variables:** + +- **long_mode** (*Optional*, list): By default, the width and height of the label is set to ``SIZE_CONTENT``. Therefore, the size of the label is automatically expanded to the text size. Otherwise, if the ``width`` or ``height`` are explicitly set (or set by :ref:`lvgl-layouts`), the lines wider than the label's width can be manipulated according to the long mode policies below. These policies can be applied if the height of the text is greater than the height of the label. + - ``WRAP``: Wrap lines which are too long. If the height is ``SIZE_CONTENT``, the label's height will be expanded, otherwise the text will be clipped (default). + - ``DOT``: Replaces the last 3 characters from bottom right corner of the label with dots. + - ``SCROLL``: If the text is wider than the label, scroll the text horizontally back and forth. If it's higher, scroll vertically. Text will scroll in only one direction; horizontal scrolling has higher precedence. + - ``SCROLL_CIRCULAR``: If the text is wider than the label, continuously scroll the text horizontally. If it's higher, scroll vertically. Text will scroll in only one direction; horizontal scrolling has higher precedence. + - ``CLIP``: Simply clip the parts of the text outside the label. +- **recolor** (*Optional*, boolean): Enable recoloring of button text with ``#``. This makes it possible to set the color of characters in the text individually by prefixing the text to be re-colored with a ``#RRGGBB`` hexadecimal color code followed by a *space*, and finally closed with a single hash ``#`` tag. For example: ``Write a #FF0000 red# word``. +- **scrollbar** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. The scroll bar that is shown when the text is larger than the widget's size. +- **selected** (*Optional*, list): Settings for the the style of the selected text. Only ``text_color`` and ``bg_color`` style properties can be used. +- **text_align** (*Optional*, dict): Alignment of the text in the widget - it doesn't align the object itself, only the lines inside the object. One of ``LEFT``, ``CENTER``, ``RIGHT``, ``AUTO``. Inherited from parent. Defaults to ``AUTO``, which detects the text base direction and uses left or right alignment accordingly. +- **text_color** (*Optional*, :ref:`color `): Color to render the text in. Inherited from parent. Defaults to ``0`` (black). +- **text_decor** (*Optional*, list): Choose decorations for the text: ``NONE``, ``UNDERLINE``, ``STRIKETHROUGH`` (multiple can be specified as YAML list). Inherited from parent. Defaults to ``NONE``. +- **text_font**: (*Optional*, :ref:`font `): The ID of the font used to render the text or symbol. Inherited from parent. +- **text_letter_space** (*Optional*, int16): Extra character spacing of the text. Inherited from parent. Defaults to ``0``. +- **text_line_space** (*Optional*, int16): Line spacing of the text. Inherited from parent. Defaults to ``0``. +- **text_opa** (*Optional*, :ref:`opacity `): Opacity of the text. Inherited from parent. Defaults to ``COVER``. +- **text** (*Optional*, :ref:`text-property`): Text to display on the label. +- Style options from :ref:`lvgl-styling`. Uses all the typical background properties and the text properties. The padding values can be used to add space between the text and the background. + +.. note:: + + Newline escape sequences are handled automatically by the label widget. You can use ``\n`` to make a line break. For example: ``"line1\nline2\n\nline4"``. For escape sequences like newline to be translated, *enclose the string in double quotes*. + +**Actions:** + +- ``lvgl.label.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of label widgets which you want update. + - **text** (*Optional*, :ref:`text-property`): Text to display on the button. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - label: + align: CENTER + id: lbl_id + recolor: true + text: "#FF0000 write# #00FF00 colored# #0000FF text#" + + - label: + align: TOP_MID + id: lbl_symbol + text_font: montserrat_28 + text: "\uF013" + + # Example action (update label with a value from a sensor): + on_...: + then: + - lvgl.label.update: + id: lbl_id + text: + format: "%.0fdBm" + args: [ 'id(wifi_signal_db).get_state()' ] + +The ``label`` can be also integrated as :doc:`Text ` or :doc:`Text Sensor ` component. + +.. _lvgl-widget-led: + +``led`` +------- + +The LED widgets are either circular or rectangular widgets whose brightness can be adjusted. As their brightness decreases, the colors become darker. + +.. figure:: /components/lvgl/images/lvgl_led.png + :align: center + +**Configuration variables:** + +- **brightness** (*Optional*, percentage): The brightness of the LED color, where ``0%`` corresponds to black, and ``100%`` corresponds to the full brightness of the color specified above. +- **color** (*Optional*, :ref:`color `): Color for the background, border, and shadow of the widget. +- Style options from :ref:`lvgl-styling`, using all the typical background style properties. + +**Actions:** + +- ``lvgl.led.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of led widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - led: + id: led_id + align: CENTER + color: 0xFF0000 + brightness: 70% + + # Example action: + on_...: + then: + - lvgl.led.update: + id: led_id + color: 0x00FF00 + +The ``led`` can be also integrated as :doc:`Light ` component. + +.. note:: + + If configured as a light component, ``color`` and ``brightness`` are overridden by the light at startup, according to its ``restore_mode`` setting. + +.. _lvgl-widget-line: + +``line`` +-------- + +The line widget is capable of drawing straight lines between a set of points. + +.. figure:: /components/lvgl/images/lvgl_line.png + :align: center + +**Configuration variables:** + +- **line_color** (*Optional*, :ref:`color `): Color for the line. +- **line_dash_gap** (*Optional*, int16): Set the width of the gap between the dashes in the line (in pixels). +- **line_dash_width** (*Optional*, int16): Set the width of the dashes in the line (in pixels). +- **line_rounded** (*Optional*, boolean): Make the end points of the line rounded. ``true`` rounded, ``false`` perpendicular line ending. +- **line_width** (*Optional*, int16): Set the width of the line in pixels. +- **points** (**Required**, list): A list of ``x, y`` integer pairs for point coordinates (origin from top left of parent) +- Style options from :ref:`lvgl-styling`, all the typical background properties and line style properties. + +By default, the Line widget width and height dimensions are set to ``SIZE_CONTENT``. This means it will automatically set its size to fit all the points. If the size is set explicitly, parts of the line may not be visible. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - line: + points: + - 5, 5 + - 70, 70 + - 120, 10 + - 180, 60 + - 230, 15 + line_width: 8 + line_color: 0x0000FF + line_rounded: true + +.. _lvgl-widget-meter: + +``meter`` +--------- + +The meter widget can visualize data in very flexible ways. It can use arcs, needles, ticks, lines and/or labels. + +.. figure:: /components/lvgl/images/lvgl_meter.png + :align: center + +**Configuration variables:** + +- **scales** (**Required**, list): A list with (any number of) scales to be added to the meter. + - **angle_range** (**Required**): The angle between start and end of the tick scale. Defaults to ``270``. + - **indicators** (**Required**, list): A list with indicators to be added to the scale. Multiple of each can be added. Their values are interpreted in the range of the scale: + - **arc** (*Optional*): Add a background arc the scale: + - **color**: :ref:`Color ` to draw the arc. Defaults to ``0`` (black). + - **end_value**: The value in the scale range to end drawing the arc to. + - **r_mod**: Adjust the position of the arc from the scale radius with this amount (can be negative). Defaults to ``0``. + - **start_value**: The value in the scale range to start drawing the arc from. + - **width**: Arc width in pixels. Defaults to ``4``. + - Style options for the *arc* using the :ref:`lvgl-widget-arc` style properties. + - **image** (*Optional*): Add a rotating needle image to the scale: + - **id**: Manually specify the :ref:`config-id` used for updating the indicator value at runtime. + - **pivot_x**: Horizontal position of the pivot point of rotation, in pixels, relative to the top left corner of the image. + - **pivot_y**: Vertical position of the pivot point of rotation, in pixels, relative to the top left corner of the image. + - **src**: The ID of an existing image configuration, representing a needle pointing to the right like ``-o--->``. + - **value**: The value in the scale range to show at start. + - **line** (*Optional*): Add a needle line to the scale. By default, the length of the line is the same as the scale's radius: + - **color**: :ref:`Color ` for the needle line. Defaults to ``0`` (black). + - **id**: Manually specify the :ref:`config-id` used for updating the indicator value at runtime. + - **r_mod**: Adjust the length of the needle from the scale radius with this amount (can be negative). Defaults to ``0``. + - **value**: The value in the scale range to show at start. + - **width**: Needle line width in pixels. Defaults to ``4``. + - Style options for the *needle line* using the :ref:`lvgl-widget-line` style properties, as well as the background properties from :ref:`lvgl-styling` to draw a square (or circle) on the pivot of the needles. Padding makes the square larger. + - **tick_style** (**Optional**): Add tick style modifications: + - **color_end**: :ref:`Color ` for the gradient end of the ticks. + - **color_start**: :ref:`Color ` for the gradient start of the ticks. + - **end_value**: The value in the scale range to modify the ticks to. + - **local**: If ``true`` the ticks' color will be faded from ``color_start`` to ``color_end`` in the start and end values specified above. If ``false``, ``color_start`` and ``color_end`` will be mapped to the entire scale range (and only a *slice* of that color gradient will be visible in the indicator's start and end value range). Defaults to ``false``. + - **start_value**: The value in the scale range to modify the ticks from. + - **width**: Modifies the ``width`` of the tick lines. + - **range_from** (**Required**): The minimum value of the tick scale. Defaults to ``0``. + - **range_to** (**Required**): The maximum value of the tick scale. Defaults to ``100``. + - **rotation** (*Optional*): The rotation angle offset of the tick scale. + - **ticks** (**Required**, list): A scale can have minor and major ticks and labels on the major ticks. To add the minor ticks: + - **color** (*Optional*, :ref:`color `): Color to draw the ticks. Required if ``count`` is greater than ``0``. Defaults to ``0x808080``. + - **count** (**Required**): How many ticks to be on the scale. Defaults to ``12``. + - **length** (*Optional*): Tick line length in pixels. Required if ``count`` is greater than ``0``. Defaults to ``10``. + - **width** (*Optional*): Tick line width in pixels. Required if ``count`` is greater than ``0``. Defaults to ``2``. + - **major** (*Optional*, list): If you want major ticks and value labels displayed: + - **color**: :ref:`Color ` to draw the major ticks. Defaults to ``0`` (black). + - **label_gap**: Label distance from the ticks with text proportional to the values of the tick line. Defaults to ``4``. + - **length**: Tick line length in pixels or percentage. Defaults to ``15%``. + - **stride**: How many minor ticks to skip when adding major ticks. Defaults to ``3``. + - **width**: Tick line width in pixels. Defaults to ``5``. + - Style options from :ref:`lvgl-styling` for the tick *lines* and *labels* using the :ref:`lvgl-widget-line` and :ref:`lvgl-widget-label` text style properties. +- Style options from :ref:`lvgl-styling` for the background of the meter, using the typical background properties. + +.. note:: + + The zero degree position is at the middle right (3 o'clock) of the widget and the degrees increase in a clockwise direction from there. Angles are specified in the ``0``-``360`` range. + +**Actions:** + +- ``lvgl.indicator.update`` :ref:`action ` updates indicator options except ``src``, which cannot be updated at runtime. :ref:`lvgl.widget.update ` action can be used for the common styles, states or flags of the meter widget (not the indicators). + - **id** (**Required**): The ID or a list of IDs of line or image indicators which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - meter: + align: center + scales: + range_from: -10 + range_to: 40 + angle_range: 240 + rotation: 150 + ticks: + count: 51 + length: 3 + major: + stride: 5 + length: 13 + label_gap: 13 + indicators: + - line: + id: temperature_needle + width: 2 + color: 0xFF0000 + r_mod: -4 + - tick_style: + start_value: -10 + end_value: 40 + color_start: 0x0000bd #FF0000 + color_end: 0xbd0000 #0000FF + + # Example action: + on_...: + then: + - lvgl.indicator.update: + id: temperature_needle + value: 3 + +.. _lvgl-widget-msgbox: + +``msgboxes`` +------------ + +The message boxes act as pop-ups. They are built from a background container, a title, an optional close button, a text and optional buttons. + +.. figure:: /components/lvgl/images/lvgl_msgbox.png + :align: center + +The text will be broken into multiple lines automatically and the height will be set automatically to include the text and the buttons. The message box is modal (blocks clicks on the rest of the screen until closed). + +**Configuration variables:** + +- **msgboxes** (*Optional*, dict): A list of message boxes to use. This option has to be added to the top level of the LVGL component configuration. + - **title** (**Required**, string): A string to display at the top of the message box. + - **body** (*Optional*, dict): The content of the body of the message box: + - **text** (*Optional*, :ref:`text-property`): The text to display in the body of the message box. + - Style options from :ref:`lvgl-styling`. Uses all the typical background properties and the text properties. + - **buttons** (*Optional*, list): A list of buttons to show at the bottom of the message box: + - **text** (*Optional*, :ref:`text-property`): Text to display on the button. + - See :ref:`lvgl-widget-buttonmatrix` for other options for the buttons. + - **close_button** (*Optional*, boolean): Controls the appearance of the close button to the top right of the message box. + +**Actions:** + +The configured message boxes are hidden by default. One can show them with ``lvgl.widget.show`` and ``lvgl.widget.hide`` :ref:`actions `. + +**Example:** + +.. code-block:: yaml + + # Example widget: + lvgl: + ... + msgboxes: + - id: message_box + close_button: true + title: Message box + body: + text: "This is a sample message box." + bg_color: 0x808080 + buttons: + - id: msgbox_apply + text: "Apply" + - id: msgbox_close + text: "\uF00D" + on_click: + then: + - lvgl.widget.hide: message_box + +.. tip:: + + You can create your own more complex dialogs with a full-screen sized, half-opaque ``obj`` with any child widgets on it, and the ``hidden`` flag set to ``true`` by default. For non-modal dialogs, simply set the ``clickable`` flag to ``false`` on it. + +.. _lvgl-widget-obj: + +``obj`` +------- + +The base object is just a simple, empty widget. By default, it's nothing more than a rounded rectangle: + +.. figure:: /components/lvgl/images/lvgl_baseobj.png + :align: center + +You can use it as a parent container for other widgets. By default, it catches touches. + +**Configuration variables:** + +- Style options from :ref:`lvgl-styling`. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - obj: + x: 10 + y: 10 + width: 220 + height: 300 + widgets: + - ... + +.. _lvgl-widget-roller: + +``roller`` +---------- + +Roller allows you to simply select one option from a list by scrolling. + +.. figure:: /components/lvgl/images/lvgl_roller.png + :align: center + +**Configuration variables:** + +- **anim_time** (*Optional*, :ref:`Time `): When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically in this amount of time. +- **mode** (*Optional*, dict): Option to make the roller circular. ``NORMAL`` or ``INFINITE``, defaults to ``NORMAL``. +- **options** (**Required**, list): The list of available options in the roller. +- **selected_index** (*Optional*, int8): The index of the item you wish to be selected. +- **selected** (*Optional*, list): Settings for the selected *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. The selected option in the middle. Besides the typical background properties it uses the :ref:`lvgl-widget-label` text style properties to change the appearance of the text in the selected area. +- **visible_row_count** (*Optional*, int8): The number of visible rows. +- Style options from :ref:`lvgl-styling`. The background of the roller uses all the typical background properties and :ref:`lvgl-widget-label` style properties. ``text_line_space`` adjusts the space between the options. + +**Actions:** + +- ``lvgl.roller.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of roller widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when you select an item from the list. The new selected index is returned in the variable ``x``. +- :ref:`interaction ` LVGL event triggers which also return the selected index in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - roller: + align: CENTER + id: roller_id + options: + - Violin + - Piano + - Bassoon + - Chello + - Drums + + # Example action: + on_...: + then: + - lvgl.roller.update: + id: roller_id + selected_index: 4 + + # Example trigger: + - roller: + ... + on_value: + - logger.log: + format: "Selected index is: %d" + args: [ x ] + +The ``roller`` can be also integrated as :doc:`Select ` component. + +.. _lvgl-widget-slider: + +``slider`` +---------- + +The slider widget looks like a bar supplemented with a knob. The user can drag the knob to set a value. Just like bar, slider can be vertical or horizontal. The size of the indicator foreground and the knob position is set according to the current ``value`` of the slider. + +.. figure:: /components/lvgl/images/lvgl_slider.png + :align: center + +**Configuration variables:** + +- **anim_time** (*Optional*, :ref:`Time `): Sets the animation time if the value is set with ``animated: true``. +- **animated** (*Optional*, boolean): Animate the indicator when the bar changes value. Defaults to ``true``. +- **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. The indicator shows the current state of the slider. Also uses all the typical background style properties. +- **knob** (*Optional*, list): Settings for the knob *part* to control the value. Supports a list of :ref:`styles ` and state-based styles to customize. A rectangle (or circle) is drawn at the current value. Also uses all the typical background properties to describe the knob. By default, the knob is square (with an optional corner radius) with side length equal to the smaller side of the slider. The knob can be made larger with the padding values. Padding values can be asymmetric. +- **max_value** (*Optional*, int8): Maximum value of the indicator. Defaults to ``100``. +- **min_value** (*Optional*, int8): Minimum value of the indicator. Defaults to ``0``. +- **value** (**Required**, int8): Actual value of the indicator at start, in ``0``-``100`` range. Defaults to ``0``. +- Any :ref:`Styling ` and state-based option for the background of the slider. Uses all the typical background style properties. Padding makes the indicator smaller in the respective direction. + +Normally, the slider can be adjusted either by dragging the knob, or by clicking on the slider bar. In the latter case the knob moves to the point clicked and slider value changes accordingly. In some cases it is desirable to set the slider to react on dragging the knob only. This feature is enabled by enabling the ``adv_hittest`` flag. + +**Actions:** + +- ``lvgl.slider.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of slider widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when the knob changes the value of the slider. The new value is returned in the variable ``x``. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - slider: + x: 10 + y: 10 + width: 220 + id: slider_id + value: 75 + min_value: 0 + max_value: 100 + + # Example action: + on_...: + then: + - lvgl.slider.update: + id: slider_id + knob: + bg_color: 0x00FF00 + value: 55 + + # Example trigger: + - slider: + ... + on_value: + - logger.log: + format: "Slider value is: %.0f" + args: [ 'x' ] + +.. note:: + + The ``on_value`` trigger is sent as the slider is dragged or changed with keys. The event is sent *continuously* while the slider is being dragged; this generally has a negative effect on performance. To mitigate this, consider using a :ref:`universal interaction trigger ` like ``on_release``, to get the ``x`` variable once after the interaction has completed. + +The ``slider`` can be also integrated as :doc:`Number ` or :doc:`Sensor ` component. + +.. _lvgl-widget-spinbox: + +``spinbox`` +----------- + +The spinbox contains a numeric value (as text) which can be increased or decreased through actions. You can, for example, use buttons labeled with plus and minus to call actions which increase or decrease the value as required. + +.. figure:: /components/lvgl/images/lvgl_spinbox.png + :align: center + +**Configuration variables:** + +- **anim_time** (*Optional*, :ref:`Time `): Sets the cursor's blink time. +- **decimal_places** (*Optional*, 0..6): The number of digits after the decimal point. If ``0``, no decimal point is displayed. Defaults to ``0``. +- **digits** (*Optional*, 1..10): The number of digits (excluding the decimal separator and the sign characters). Defaults to ``4``. +- **range_from** (*Optional*, float): The minimum value allowed to set the spinbox to. Defaults to ``0``. +- **range_to** (*Optional*, float): The maximum value allowed to set the spinbox to. Defaults to ``100``. +- **rollover** (*Optional*, boolean): While increasing or decreasing the value, if either the minimum or maximum value is reached with this option enabled, the value will change to the other limit. If disabled, the value will remain at the minimum or maximum value. Defaults to ``false``. +- **step** (*Optional*, float): The granularity with which the value can be set. Defaults to ``1.0``. +- **value** (**Required**, float): Actual value to be shown by the spinbox at start. + +.. note:: + + The sign character will only be shown if the set range contains negatives. + +**Actions:** + +- ``lvgl.spinbox.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of spinbox widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +- ``lvgl.spinbox.increment`` :ref:`action ` increases the value by one ``step`` configured above. + - **id** (**Required**): The ID of the spinbox widget which you want to increment. + +- ``lvgl.spinbox.decrement`` :ref:`action ` decreases the value by one ``step`` configured above. + - **id** (**Required**): The ID of the spinbox widget which you want to decrement. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when the knob changes the value of the arc. The new value is returned in the variable ``x``. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - spinbox: + id: spinbox_id + text_align: center + range_from: -10 + range_to: 40 + step: 0.5 + digits: 3 + decimal_places: 1 + + # Example actions: + on_...: + then: + - lvgl.spinbox.decrement: spinbox_id + on_...: + then: + - lvgl.spinbox.update: + id: spinbox_id + value: 25.5 + + # Example trigger: + - spinbox: + ... + on_value: + then: + - logger.log: + format: "Spinbox value is %f" + args: [ x ] + +The ``spinbox`` can be also integrated as :doc:`Number ` or :doc:`Sensor ` component. + +.. _lvgl-widget-spinner: + +``spinner`` +----------- + +The Spinner widget is a spinning arc over a ring. + +.. figure:: /components/lvgl/images/lvgl_spinner.gif + :align: center + +**Configuration variables:** + +- **arc_color** (*Optional*, :ref:`color `): Color to draw the arcs. +- **arc_length** (**Required**, 0-360): Length of the spinning arc in degrees. +- **arc_opa** (*Optional*, :ref:`opacity `): Opacity of the arc. +- **arc_rounded** (*Optional*, boolean): Make the end points of the arcs rounded. ``true`` rounded, ``false`` perpendicular line ending. +- **arc_width** (*Optional*, int16): Set the width of the arcs in pixels. +- **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles ` and state-based styles to customize. Draws *another arc using the arc style* properties. Its padding values are interpreted relative to the background arc. +- **spin_time** (**Required**, :ref:`Time `): Duration of one cycle of the spin. + +**Actions:** + +- ``lvgl.spinner.update`` :ref:`action ` updates the widget styles and properties for the *indicator* part (anything other than the properties that apply commonly to all widgets), just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. + - **id** (**Required**): The ID or a list of IDs of spinner widgets which you want update. + - Widget styles or properties from the specific options above, which you want update. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - spinner: + align: center + spin_time: 2s + arc_length: 60deg + id: spinner_id + indicator: + arc_color: 0xd4d4d4 + + # Example action: + on_...: + then: + - lvgl.spinner.update: + id: spinner_id + arc_color: 0x31de70 + +.. _lvgl-widget-switch: + +``switch`` +---------- + +The switch looks like a little slider and can be used to turn something on and off. + +.. figure:: /components/lvgl/images/lvgl_switch.png + :align: center + +**Configuration variables:** + +- **indicator** (*Optional*, list): Settings for the indicator *part*, the foreground area underneath the knob shown when the switch is in ``checked`` state. Supports a list of :ref:`styles ` and state-based styles to customize. +- **knob** (*Optional*, list): Settings for the knob *part* to control the value. Supports a list of :ref:`styles ` and state-based styles to customize. +- Style options from :ref:`lvgl-styling`. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when toggling the switch. The boolean variable ``x``, representing the switch's state, may be used by lambdas within this trigger. +- :ref:`interaction ` LVGL event triggers which also return the value in ``x``. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - switch: + x: 10 + y: 10 + id: switch_id + + # Example trigger: + - switch: + ... + on_value: + then: + - logger.log: + format: "Switch state: %d" + args: [ x ] + +The ``switch`` can be also integrated as a :doc:`Switch ` component. + +.. _lvgl-widget-tabview: + +``tabview`` +----------- + +The tab view object can be used to organize content in tabs. The tab buttons are internally generated with a :ref:`lvgl-widget-buttonmatrix`. + +.. figure:: /components/lvgl/images/lvgl_tabview.png + :align: center + +The tabs are indexed (zero-based) in the order they appear in the configuration file. A new tab can be selected either by clicking on a tab button, by sliding horizontally on the content or via the ``lvgl.tabview.select`` :ref:`action `, specifying the tab's index. + +**Configuration variables:** + +- **position** (*Optional*, string): Position of the tab selector buttons. One of ``TOP``, ``BOTTOM``, ``LEFT``, ``RIGHT``. Defaults to ``TOP``. +- **size** (*Optional*, percentage): The height (in case of ``TOP``, ``BOTTOM``) or width (in case of ``LEFT``, ``RIGHT``) tab buttons. Defaults to ``10%``. +- **tabs** (**Required**, list): A list with (any number of) tabs to be added to tabview. + - **name** (**Required**): The text to be shown on the button corresponding to the tab. + - **id** (*Optional*): An ID for the tab itself. + - **widgets** (**Required**, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the tab, as children. +- **tab_style** (*Optional*): Style settings for the tabs. + - **items** (*Optional*, list): Settings for the items *part*, the buttons all use the text and typical background style properties except translations and transformations. + +**Actions:** + +- ``lvgl.tabview.select`` :ref:`action ` jumps the view to the desired tab: + - **id** (**Required**): The ID of the tabview which receives this action. + - **index** (**Required**): The (zero-based) index of the tab to which to jump. + - **animated** (*Optional*, boolean): To animate the movement. Defaults to ``false``. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when displayed tab changes. The new value is returned in the variable ``tab`` as the ID of the now-visible tab. +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - tabview: + id: tabview_id + position: top + tab_style: + border_color: 0x00FF00 + border_width: 6 + items: + text_color: 0x0000FF + tabs: + - name: Dog + id: tabview_tab_1 + widgets: + - image: + src: dog_img + ... + ... + + # Example action: + on_...: + then: + - lvgl.tabview.select: + id: tabview_id + index: 1 + animated: true + + # Example trigger: + - tabview: + ... + on_value: + then: + - if: + condition: + lambda: return tab == id(tabview_tab_1); + then: + - logger.log: "Dog tab is now showing" + +.. _lvgl-widget-textarea: + +``textarea`` +------------ + +The textarea is an extended label widget which displays a cursor and allows the user to input text. Long lines are wrapped and when the text becomes long enough the text area can be scrolled. It supports one line mode and password mode, where typed characters are replaced visually with bullets or asterisks. + +.. figure:: /components/lvgl/images/lvgl_textarea.png + :align: center + +**Configuration variables:** + +- **accepted_chars** (*Optional*, string): You can set a list of accepted characters, so other characters will be ignored. +- **max_length** (*Optional*, int): Limit the maximum number of characters to this value. +- **one_line** (*Optional*, boolean): The text area can be limited to only allow a single line of text. In this case the height will set automatically to fit only one line, line break characters will be ignored, and word wrap will be disabled. +- **password_mode** (*Optional*, boolean): The text area supports password mode. By default, if the ``•`` (bullet, ``0x2022``) glyph exists in the font, the entered characters are converted to it after some time or when a new character is entered. If ``•`` is missing from the font, ``*`` (asterisk) will be used. +- **text** (*Optional*, :ref:`text-property`): Initial contents of the textarea. +- **placeholder_text** (*Optional*, :ref:`text-property`): A placeholder text can be specified, which is displayed when the Text area is empty. +- any :ref:`Styling ` and state-based option for the background of the textarea. Uses all the typical background style properties and the text/label related style properties for the text. + +**Actions:** + +- ``lvgl.textarea.update`` :ref:`action ` updates the widget's ``text`` property, to replace the entire text content. + - **id** (**Required**): The ID or a list of IDs of textarea widgets which you want update. + - **text** (*Optional*, :ref:`text-property`): The text to replace the textarea content. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated on every keystroke. +- ``on_ready`` :ref:`trigger ` is activated when ``one_line`` is configured as ``true`` and the newline character is received (Enter/Ready key on the keyboard). +- :ref:`interaction ` LVGL event triggers. + +For both triggers above, when triggered, the variable ``text`` (``std::string`` type) is available for use in lambdas within these triggers and it will contain the entire contents of the textarea. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - textarea: + id: textarea_id + one_line: true + placeholder_text: "Enter text here" + + # Example action: + on_...: + then: + - lvgl.textarea.update: + id: textarea_id + text: "Hello World!" + + # Example trigger: + - textarea: + ... + on_value: + then: + - logger.log: + format: "Textarea changed to: %s" + args: [ text.c_str() ] + on_ready: + then: + - logger.log: + format: "Textarea ready: %s" + args: [ text.c_str() ] + +The ``textarea`` can be also integrated as :doc:`Text ` or :doc:`Text Sensor ` component. + +.. _lvgl-widget-tileview: + +``tileview`` +------------ + +The tileview is a container object whose elements, called tiles, can be arranged in grid form. A user can navigate between the tiles by dragging or swiping. Any direction can be disabled on the tiles individually to not allow moving from one tile to another. + +If the Tile view is screen sized, the user interface resembles what you may have seen on smartwatches. + +**Configuration variables:** + +- **tiles** (**Required**, list): A list with (any number of) tiles to be added to tileview. + - **column** (**Required**): Vertical position of the tile in the tileview grid. + - **row** (**Required**): Horizontal position of the tile in the tileview grid. + - **dir** (*Optional*): Enable moving to adjacent tiles in the given direction by swiping/dragging. One (or multiple as YAML list) of ``LEFT``, ``RIGHT``, ``TOP``, ``BOTTOM``, ``HOR``, ``VER``, ``ALL``. Defaults to ``ALL``. + - **id** (*Optional*): A tile ID to be used with the ``lvgl.tileview.select`` action. + - **widgets** (*Optional*, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the tile, as children. + +**Actions:** + +- ``lvgl.tileview.select`` :ref:`action ` jumps the ``tileview`` to the desired tile: + - **animated** (*Optional*, boolean): To animate the movement. Defaults to ``false``. + - **column** (*Optional*): Vertical position of the tile to which to jump. Required if not specifying ``tile_id``. + - **row** (*Optional*): Horizontal position of the tile to which to jump. Required if not specifying ``tile_id``. + - **id** (**Required**): The ID of the tileview which receives this action. + - **tile_id** (*Optional*): The ID of the tile (from within the tileview) to which to jump. Required if not specifying ``row`` and ``column``. + +**Triggers:** + +- ``on_value`` :ref:`trigger ` is activated when displayed tile changes. The new value is returned in the variable ``tile`` as the ID of the now-visible tile. +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - tileview: + id: tiv_id + tiles: + - id: cat_tile + row: 0 + column: 0 + dir: VER + widgets: + - image: + src: cat_image + - ... + - ... + + # Example action: + on_...: + then: + - lvgl.tileview.select: + id: tiv_id + tile_id: cat_tile + animated: true + + # Example trigger: + - tileview: + ... + on_value: + - if: + condition: + lambda: return tile == id(cat_tile); + then: + - logger.log: "Cat tile is now showing" + +.. _lvgl-automations: + +Automations +----------- + +.. _lvgl-automation-actions: + +Actions +******* + +As outlined in the sections above, each widget type supports several of its own, unique actions. +Several universal actions are also available for all widgets, these are outlined below. + +``lvgl.widget.update`` +^^^^^^^^^^^^^^^^^^^^^^ + +This powerful :ref:`action ` allows changing/updating any widget's common :ref:`style property `, state (templatable) or :ref:`flag ` on the fly. + +- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL which you want update. +- The widget's common :ref:`style property `, state (templatable) or :ref:`flag `. + +.. code-block:: yaml + + # Example for updating styles (in states): + on_...: + then: + - lvgl.widget.update: + id: my_button_id + bg_color: 0xFF0000 + state: + disabled: true + + # Example for updating flag: + on_...: + then: + - lvgl.widget.update: + id: my_label_id + hidden: true + + +.. _lvgl-automation-shorthands: + +``lvgl.widget.hide``, ``lvgl.widget.show`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These :ref:`actions ` are shorthands for toggling the ``hidden`` :ref:`flag ` of any widget. + +- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL which you want to hide or show. + +.. code-block:: yaml + + on_...: + then: + - lvgl.widget.hide: my_label_id # a single widget + - lvgl.widget.show: [my_button_1, my_button_2] # a list of widgets + - delay: 0.5s + - lvgl.widget.show: + -id: my_label_id + - lvgl.widget.hide: + - id: [my_button_1, my_button_2] + +``lvgl.widget.disable``, ``lvgl.widget.enable`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These :ref:`actions ` are shorthands for toggling the ``disabled`` state of any widget (which controls the appearance of the corresponding *disabled* style set of the theme): + +- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL which you want to disable or enable. + +.. code-block:: yaml + + - on_...: + then: + - lvgl.widget.disable: + - my_button_1 + - my_button_2 + + - on_...: + then: + - lvgl.widget.enable: + - id: my_button_1 + - id: my_button_2 + +.. _lvgl-automation-triggers: + +Triggers +******** + +Specific triggers like ``on_value`` are available for certain widgets; they are described above in their respective section. +Some universal triggers are also available for all of the widgets: + +ESPHome implements as universal triggers the following interaction events generated by LVGL: + +- ``on_press``: The widget has been pressed. +- ``on_long_press``: The widget has been pressed for at least the ``long_press_time`` specified in the input device configuration. Not called if scrolled. +- ``on_long_press_repeat``: Called after ``long_press_time`` in every ``long_press_repeat_time`` ms. Not called if scrolled. +- ``on_short_click``: The widget was pressed for a short period of time, then released. Not called if scrolled or long pressed. +- ``on_click``: Called on release if a widget did not scroll (regardless of long press). +- ``on_release``: Called in every case when a widget has been released. +- ``on_scroll_begin``: Scrolling of the widget begins. +- ``on_scroll_end``: Scrolling of the widget ends. +- ``on_scroll``: The widget was scrolled. +- ``on_focus``: The widget is focused. +- ``on_defocus``: The widget is unfocused. + +These triggers can be applied directly to any widget in the LVGL configuration, *given that the widget itself supports generating such events*. For the widgets having a value, the triggers return the current value in variable ``x``; this variable may be used in lambdas defined within those triggers. + +.. code-block:: yaml + + # Example triggers: + - button: + ... + on_short_click: + then: + lvgl.page.show: main_page + on_long_press: + then: + light.toggle: display_backlight + + - slider: + ... + on_release: + then: + - light.turn_on: + id: display_backlight + transition_length: 0ms + brightness: !lambda return x / 100; + +See Also +-------- + +- :doc:`LVGL Main component ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- `LVGL docs `__ +- :ghedit:`Edit` diff --git a/components/media_player/index.rst b/components/media_player/index.rst index 01a33e595b..f71f32be91 100644 --- a/components/media_player/index.rst +++ b/components/media_player/index.rst @@ -25,7 +25,8 @@ Base Media Player Configuration Configuration variables: -- **name** (**Required**, string): The name of the media player. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the media player. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/micro_wake_word.rst b/components/micro_wake_word.rst index 5726025ff9..be541b796f 100644 --- a/components/micro_wake_word.rst +++ b/components/micro_wake_word.rst @@ -10,72 +10,55 @@ This repository/library allows you to create a custom wake word for your ESPHome The training process is described on the `microWakeWord GitHub repository `__. -The ``micro_wake_word`` component requires an **ESP32-S3 with PSRAM** to function. .. code-block:: yaml # Shorthand name micro_wake_word: - model: okay_nabu + models: + - model: okay_nabu # Github shorthand URL micro_wake_word: - model: github://esphome/micro-wake-word-models/models/okay_nabu.json + models: + - model: github://esphome/micro-wake-word-models/models/v2/okay_nabu.json Configuration variables: ------------------------ -- **model** (**Required**, string): The model to use. This can be one of: +- **models** (**Required**, list): The models to use. - - A simple name of a model that exists in the official `ESPHome Models repository `__. - e.g. ``okay_nabu``. - - A github shorthand URL to a model JSON file. - e.g. ``github://esphome/micro-wake-word-models/models/okay_nabu.json@main``. - - A full URL to a model JSON file. - e.g. ``https://github.com/esphome/micro-wake-word-models/raw/main/models/okay_nabu.json``. + - **model** (**Required**, string): This can be one of: + - A simple name of a model that exists in the official `ESPHome Models repository `__. + e.g. ``okay_nabu``. + - A github shorthand URL to a model JSON file. + e.g. ``github://esphome/micro-wake-word-models/models/okay_nabu.json@main``. + - A full URL to a model JSON file. + e.g. ``https://github.com/esphome/micro-wake-word-models/raw/main/models/okay_nabu.json``. + + - **probability_cutoff** (*Optional*, percentage): The probability cutoff for the wake word detection. + If the probability of the wake word is below this value, the wake word is not detected. + A larger value reduces the number of false accepts but increases the number of false rejections. + - **sliding_window_size** (*Optional*, int): The size of the sliding window average for the wake word detection. A small value lowers latency but may increase the number of false accepts. - **on_wake_word_detected** (*Optional*, Automation): An automation to perform when the wake word is detected. The ``wake_word`` phrase from the model manifest is provided as a ``std::string`` to any actions in this automation. +- **vad** (*Optional*, model): Enable a Voice Activity Detection model to reduce false accepts from non-speech sounds. -The below two options are provided by the JSON file, but can be overridden in YAML. + - **model** (*Optional*, string): This can be one of: -- **probability_cutoff** (*Optional*, percentage): The probability cutoff for the wake word detection. - If the probability of the wake word is below this value, the wake word is not detected. - A larger value reduces the number of false accepts but increases the number of false rejections. -- **sliding_window_average_size** (*Optional*, int): The size of the sliding window average for the wake word detection. A small value lowers latency but may increase the number of false accepts. + - A github shorthand URL to a model JSON file. + e.g. ``github://esphome/micro-wake-word-models/models/v2/vad.json@main``. + - A full URL to a model JSON file. + e.g. ``https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/vad.json``. -Model JSON ----------- + - **probability_cutoff** (*Optional*, percentage): The probability cutoff for voice activity detection. + If the probability is below this value, then no wake word will be accepted. + A larger value reduces the number of false accepts but increases the number of false rejections. + - **sliding_window_size** (*Optional*, int): The size of the sliding window average for voice activity detection. The average probability is compared to ``probability_cutoff`` to determine if voice activity is detected. -.. code-block:: json - { - "type": "micro", - "wake_word": "okay nabu", - "author": "Kevin Ahrendt", - "website": "https://www.kevinahrendt.com/", - "model": "./okay_nabu.tflite", - "version": 1, - "micro": { - "probability_cutoff": 0.5, - "sliding_window_average_size": 10 - } - } - -The model JSON file contains the following fields that are all **required** unless otherwise specified: - -- **type** (string): The type of the model. This should always be ``micro``. -- **wake_word** (string): The wake word that the model is trained to detect. -- **author** (string): The name of the author that trained the model. -- **website** (string): The website of the author. -- **model** (string): The relative or absolute path or URL to the TFLite trained model file. -- **version** (int): The version of the JSON schema. Currently only version ``1`` exists. -- **micro** (object): The microWakeWord specific configuration. - - - **probability_cutoff** (float): The probability cutoff for the wake word detection. - If the probability of the wake word is below this value, the wake word is not detected. - - **sliding_window_average_size** (int): The size of the sliding window average for the wake word detection. - - **minimum_esphome_version** (*Optional* version): The minimum ESPHome version required to use this model. +The ``probability_cutoff`` and ``sliding_window_size`` are provided by the JSON file but can be overridden in YAML. A default VAD model is provided with the ``vad`` configuration variables, but a different model can be overridden in YAML. Automations @@ -97,13 +80,56 @@ Example usage .. code-block:: yaml micro_wake_word: - model: okay_nabu + vad: + models: + - model: okay_nabu + - model: hey_mycroft on_wake_word_detected: then: - voice_assistant.start: wake_word: !lambda return wake_word; +Model JSON +---------- + +.. code-block:: json + + { + "type": "micro", + "wake_word": "okay nabu", + "author": "Kevin Ahrendt", + "website": "https://www.kevinahrendt.com/", + "model": "stream_state_internal_quant.tflite", + "version": 2, + "micro": { + "probability_cutoff": 0.97, + "sliding_window_size": 5, + "feature_step_size": 10, + "tensor_arena_size": 22860, + "minimum_esphome_version": "2024.7" + } + } + +The model JSON file contains the following fields that are all **required** unless otherwise specified: + +- **type** (string): The type of the model. This should always be ``micro``. +- **wake_word** (string): The wake word that the model is trained to detect. +- **author** (string): The name of the author that trained the model. +- **website** (*optional* string): The website of the author. +- **model** (string): The relative or absolute path or URL to the TFLite trained model file. +- **trained_languages** (list of strings): A list of the wake word samples' primary languages/pronunciations used when training. +- **version** (int): The version of the JSON schema. The current version is ``2``. +- **micro** (object): The microWakeWord specific configuration. + + - **probability_cutoff** (float): The probability cutoff for the wake word detection. + If the probability of the wake word is below this value, the wake word is not detected. + - **sliding_window_size** (int): The size of the sliding window for the wake word detection. Wake words average all probabilities in the sliding window and VAD models use the maximum of all probabilities in the sliding window. + - **feature_step_size** (int): The step size for the spectrogram feature generation in milliseconds. + - **tensor_arena_size** (int): The minimum size of the tensor arena in bytes. + - **minimum_esphome_version** (version): The minimum ESPHome version required to use this model. + + See Also -------- diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst index 7e84843f9b..42aa8f3898 100644 --- a/components/microphone/i2s_audio.rst +++ b/components/microphone/i2s_audio.rst @@ -44,8 +44,9 @@ Configuration variables: - **sample_rate** (*Optional*, positive integer): I2S sample rate. Defaults to ``16000``. - **bits_per_sample** (*Optional*, enum): The bit depth of the audio samples. Note that while set to ``32bit``, the samples will be scaled down to 16bit before being forwarded. - One of ``16bit`` or ``32bit``. Defaults to ``16bit``. + One of ``16bit`` or ``32bit``. Defaults to ``32bit``. - **use_apll** (*Optional*, boolean): I2S using APLL as main I2S clock, enable it to get accurate clock. Defaults to ``false``. +- **i2s_mode** (*Optional*, enum): The I²S mode to use. One of ``primary`` or ``secondary``. Defaults to ``primary``. - **i2s_audio_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`I²S Audio ` you wish to use for this microphone. - All other options from :ref:`Microphone ` diff --git a/components/modbus_controller.rst b/components/modbus_controller.rst index 82601c6f9a..264f078379 100644 --- a/components/modbus_controller.rst +++ b/components/modbus_controller.rst @@ -68,7 +68,7 @@ Configuration variables: responds to a command, it'll be marked online again. - **server_registers** (*Optional*): A list of registers that are responded to when acting as a server. - - **start_address** (**Required**, integer): start address of the first register in a range + - **address** (**Required**, integer): start address of the first register in a range - **value_type** (*Optional*): datatype of the mod_bus register data. The default data type for ModBUS is a 16 bit integer in big endian format (MSB first) - ``U_WORD``: unsigned 16 bit integer from 1 register = 16bit @@ -86,9 +86,12 @@ Configuration variables: Defaults to ``U_WORD``. - - **lambda** (**Required**, :ref:`lambda `): + - **read_lambda** (**Required**, :ref:`lambda `): Lambda that returns the value of this register. +Automations: + +- **on_command_sent** (*Optional*, :ref:`Automation `): An automation to perform when a modbus command has been sent. See :ref:`modbus_controller-on_command_sent` Example Client -------------- @@ -175,9 +178,9 @@ The following code allows a ModBUS client to read a sensor value from your ESPHo - modbus_id: modbus_server address: 0x4 server_registers: - - start_address: 0x0002 + - address: 0x0002 value_type: S_DWORD_R - lambda: |- + read_lambda: |- return id(evse_voltage_l1).state; sensor: @@ -721,6 +724,28 @@ The response is mapped to the sensor based on ``register_count`` and offset in b .. _modbusseealso: +.. _modbus_controller-automations: + +Automation +---------- + +.. _modbus_controller-on_command_sent: + +``on_command_sent`` +******************* + +This automation will be triggered when a command has been sent by the `modbus_controller`. In :ref:`Lambdas ` +you can get the function code in ``function_code`` and the register address in ``address``. + +.. code-block:: yaml + + modbus_controller: + - id: modbus_con + # ... + on_command_sent: + then: + - number.increment: modbus_commands + See Also -------- diff --git a/components/mqtt.rst b/components/mqtt.rst index c255d8ef27..6ec0cd291c 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -41,7 +41,9 @@ Configuration variables: authentication. Empty (the default) means no authentication. - **client_id** (*Optional*, string): The client id to use for opening connections. See :ref:`mqtt-defaults` for more information. -- **discovery** (*Optional*, boolean): If Home Assistant automatic +- **discover_ip** (*Optional*, boolean): If Home Assistant automatic device + discovery should be enabled. Defaults to ``true``. +- **discovery** (*Optional*, boolean): If Home Assistant automatic entity discovery should be enabled. Defaults to ``true``. - **discovery_retain** (*Optional*, boolean): Whether to retain MQTT discovery messages so that entities are added automatically on Home @@ -137,10 +139,93 @@ Configuration options: - **retain** (*Optional*, boolean): If the published message should have a retain flag on or not. Defaults to ``true``. -.. _mqtt-using_with_home_assistant: -Using with Home Assistant -------------------------- +.. _mqtt-device_discovery: + +MQTT device discovery +--------------------- + +The ESPHome device will respond to the following MQTT topics if ``mqtt.discover_ip`` is enabled. + +- ``esphome/discover`` (All ESPHome device will answer) +- ``esphome/ping/`` + +The response will be sent to ``esphome/discover/`` and is a JSON encoded message. + +The MQTT device discovery is currently used for: + +- ESPHome dashboard (online / offline status) +- ESPHome CLI (IP discovery; used to view logs and perform OTA uploads) +- Home Assistant device discovery + +Example Payload: + +.. code-block:: json + + { + "ip": "192.168.0.122", + "name": "esp32-test", + "friendly_name": "Test Device", + "port": 6053, + "version": "2024.4.1", + "mac": "84fce6123456", + "platform": "ESP32", + "board": "esp32-c3-devkitm-1", + "network": "wifi", + "api_encryption": "Noise_NNpsk0_25519_ChaChaPoly_SHA256" + } + + +JSON keys: + +- **ip** (**Required**, ip): The IP address of the ESPHome device. +- **name** (**Required**, string): Name of the device (``esphome.name``). +- **mac** (**Required**, string): MAC address of the device. +- **board** (**Required**, string): Board used for the device. +- **version** (**Required**, string): ESPHome version. +- **port** (*Optional*, port): Port of the ESPHome API (if enabled). +- **ipX** (*Optional*, ip): Additional IP addresses (X is a number starting at 1). +- **friendly_name** (*Optional*, string): Friendly name of the device (``esphome.friendly_name``). +- **platform** (*Optional*, string): Platform of the device (e.g. ESP32 or ESP8266) +- **network** (*Optional*, string): Network type. +- **project_name** (*Optional*, string): ``esphome.project.name``. +- **project_version** (*Optional*, string): ``esphome.project.version``. +- **project_version** (*Optional*, string): ``dashboard_import.package_import_url``. +- **api_encryption** (*Optional*, string): API encryption type. + +.. _mqtt-using_device_discovery_with_home_assistant: + +Using device discovery with Home Assistant +------------------------------------------ + +MQTT can be used to automatically discover the ESPHome devices in Home Assistant. +This allows Home Assistant to find the ESPHome device and connect +to it via the ESPHome API which allows the usage +of more features then MQTT entity discovery alone (e.g. Bluetooth Proxy, Voice Assistant). + +This can be achieved by enabling ``api`` and ``mqtt`` with ``mqtt.discover_ip`` enabled. +It may makes sense to disable ``mqtt.discovery`` since there will be no need to use the +MQTT entity discovery if Home Assistant will connect to the ESPHome API. + +Example configuration: + +.. code-block:: yaml + + api: + encryption: + key: "" + + mqtt: + broker: 10.0.0.2 + username: livingroom + password: !secret mqtt_password + discovery: False # disable entity discovery + discover_ip: True # enable device discovery + +.. _mqtt-using_with_home_assistant_entities: + +Using with Home Assistant MQTT entities +--------------------------------------- Using ESPHome with Home Assistant is easy, simply setup an MQTT broker (like `mosquitto `__) and point both your @@ -377,16 +462,16 @@ Configuration variables: - **state_topic** (*Optional*, string): The topic to publish state updates to. Defaults to ``///state``. - - ESPHome will always publish a manually configured state topic, even if - the component is internal. Use ``null`` to disable publishing the + + ESPHome will always publish a manually configured state topic, even if + the component is internal. Use ``null`` to disable publishing the component's state. - **command_topic** (*Optional*, string): The topic to subscribe to for commands from the remote. Defaults to ``///command``. - - ESPHome will always subscribe to a manually configured command topic, - even if the component is internal. Use ``null`` to disable subscribing + + ESPHome will always subscribe to a manually configured command topic, + even if the component is internal. Use ``null`` to disable subscribing to the component's command topic. - **command_retain** (*Optional*, boolean): Whether MQTT command messages sent to the device should be retained or not. Default to ``false``. diff --git a/components/number/home_assistant.rst b/components/number/home_assistant.rst new file mode 100644 index 0000000000..3a657c5133 --- /dev/null +++ b/components/number/home_assistant.rst @@ -0,0 +1,36 @@ +Home Assistant Number +===================== + +.. seo:: + :description: Instructions for setting up Home Assistant numbers with ESPHome. + :image: description.svg + +The ``homeassistant`` number platform allows you to create a number that is synchronized +with Home Assistant. Min, Max and Step are not configurable for this platform because they are taken from the Home Assistant entity. + +.. code-block:: yaml + + # Example configuration entry + number: + - platform: homeassistant + id: my_ha_number + entity_id: number.my_number + +Configuration variables: +------------------------ + +- **entity_id** (**Required**, string): The Home Assistant entity ID of the number to synchronize with. +- All other options from :ref:`Number `. + +``number.set`` Action +--------------------- + +You can also set the number for the Home Assistant number from elsewhere in your YAML file +with the :ref:`number-set_action`. + +See Also +-------- + +- :ref:`automation` +- :apiref:`homeassistant/number/homeassistant_number.h` +- :ghedit:`Edit` diff --git a/components/number/index.rst b/components/number/index.rst index 82ba8e3361..117c170e25 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -30,7 +30,8 @@ All numbers in ESPHome have a name and an optional icon. Configuration variables: -- **name** (**Required**, string): The name for the number. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the number. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/number/lvgl.rst b/components/number/lvgl.rst new file mode 100644 index 0000000000..29b2e5cfd3 --- /dev/null +++ b/components/number/lvgl.rst @@ -0,0 +1,48 @@ +LVGL Number +=========== + +.. seo:: + :description: Instructions for setting up an LVGL widget number component. + :image: ../images/lvgl_c_num.png + +The ``lvgl`` number platform creates a number component from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-arc`, :ref:`lvgl-widget-bar`, :ref:`lvgl-widget-slider` and :ref:`lvgl-widget-spinbox`. A single number supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome number component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the number. +- **animated** (*Optional*, boolean): Whether to set the value of the widget with an animation (if supported by the widget). Defaults to ``true``. +- **update_on_release** (*Optional*, boolean): By default the number will publish a new value each time the value of the associated widget changes. If this option is ``true`` then the value will only be published when touch is released. +- All other variables from :ref:`Number `. + +Example: + +.. code-block:: yaml + + number: + - platform: lvgl + widget: slider_id + name: LVGL Slider + +.. note:: + + Widget-specific actions (``lvgl.arc.update``, ``lvgl.bar.update``, ``lvgl.slider.update``, ``lvgl.spinbox.update``, ``lvgl.spinbox.decrement``, ``lvgl.spinbox.increment``) will trigger correspponding component updates to be sent to Home Assistant. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Arc widget ` +- :ref:`Bar widget ` +- :ref:`Slider widget ` +- :ref:`Spinbox widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/number/modbus_controller.rst b/components/number/modbus_controller.rst index 3c5e2042ba..f43b9c883d 100644 --- a/components/number/modbus_controller.rst +++ b/components/number/modbus_controller.rst @@ -10,8 +10,6 @@ When the Number is updated a modbus write command is created sent to the device. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **address** (**Required**, int): start address of the first register in a range (can be decimal or hexadecimal). - **value_type** (**Required**): datatype of the modbus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first): diff --git a/components/number/template.rst b/components/number/template.rst index 13cbef2f79..62b52799e3 100644 --- a/components/number/template.rst +++ b/components/number/template.rst @@ -22,7 +22,6 @@ using :ref:`lambdas `. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the number. - **min_value** (**Required**, float): The minimum value this number can be. - **max_value** (**Required**, float): The maximum value this number can be. - **step** (**Required**, float): The granularity with which the number can be set. @@ -41,7 +40,6 @@ Configuration variables: - **initial_value** (*Optional*, float): The value to set the state to on setup if not restored with ``restore_value``. Cannot be used with ``lambda``. Defaults to ``min_value``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Number `. ``number.set`` Action diff --git a/components/number/tuya.rst b/components/number/tuya.rst index 8db9bdf5cf..3b87b76520 100644 --- a/components/number/tuya.rst +++ b/components/number/tuya.rst @@ -61,16 +61,35 @@ For instance, assume we have a pH sensor that reads from 0.00 to 15.00 with a sc max_value: 15.00 multiply: 100 +Hidden datapoints: +------------------ +The above configurations will work fine as long as Tuya device publishes the datapoint value (along with its type) at initialization. +However this is not always the case. To be able to use such "hidden" datapoints as Number, you need to specify additional ``datapoint_hidden`` configuration block. +This block allows to specify the missing datapoint type and, optionally, the value that should be written to the datapoint at initialization. + +.. code-block:: yaml + + - platform: "tuya" + name: "Alarm at maximum" + number_datapoint: 116 + min_value: 0 + max_value: 100 + datapoint_hidden: + datapoint_type: int + initial_value: 85 + Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the switch. - **number_datapoint** (**Required**, int): The datapoint id number of the number. - **min_value** (**Required**, float): The minimum value this number can be. - **max_value** (**Required**, float): The maximum value this number can be. - **step** (*Optional*, float): The granularity with which the number can be set. Defaults to 1. - **multiply** (*Optional*, float): multiply the new value with this factor before sending the requests. +- **datapoint_hidden** (*Optional*): Specify information required for hidden datapoints. + + - **datapoint_type** (**Required**, string): The datapoint type, one of *int*, *uint*, *enum*. + - **initial_value** (*Optional*, float): The value to be written at initialization. Must be between ``min_value`` and ``max_value``. - All other options from :ref:`Number `. diff --git a/components/online_image.rst b/components/online_image.rst new file mode 100644 index 0000000000..a69fcb68dd --- /dev/null +++ b/components/online_image.rst @@ -0,0 +1,154 @@ +.. _online_image: + +Online Image Component +====================== + +.. seo:: + :description: Instructions for displaying images downloaded at runtime in ESPHome. + :image: image-sync-outline.svg + +With this component you can define images that will be downloaded, decoded and drawn at runtime. + +.. note:: + + Currently only images in PNG format are supported. + +.. warning:: + + This component requires a fair amount of RAM; both for downloading the image, and for storing the decoded image. It might work on devices without PSRAM, but there is no guarantee. + +This component has a dependency to :doc:`/components/http_request`; the configuration options you set to the ``http_request`` component will also apply here. + +.. code-block:: yaml + + online_image: + - url: "https://example.com/example.png" + format: png + id: my_online_image + +Configuration variables +----------------------- + +- **url** (**Required**, url): The URL where the image will be downloaded from. +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later + in your display code. +- **format** (**Required**): The format that the image is encoded with. + + - ``PNG``: The image on the server is encoded in PNG format. +- **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT`` + and preserve the aspect ratio. +- **placeholder** (**Optional**, :ref:`config-id`): ID of an :doc:`Image ` to display while the downloaded image is not yet ready. + This placeholder image will **not** be resized; regardless of the ``resize`` option value for the ``online_image``. +- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY``. + + - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit + per pixel, 8 pixels per byte. + - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel + will be the on color. Uses 1 bit per pixel, 8 pixels per byte. + - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. + - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. + - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. +- **use_transparency** (*Optional*, boolean): If set the alpha channel of the input image will be taken into account, + and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, + the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information + within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``true`` and cannot be set to ``false``; other types default to ``false``. +- **update_interval** (*Optional*, int): Redownload the image when the specified time has elapsed. Defaults to ``never`` (i.e. the update component action needs to be called manually). + +Automations +----------- + +- **on_download_finished** (*Optional*, :ref:`Automation `): An automation to perform when the image has been successfully downloaded. + +A good example for that is to update the display component after the download succeeded. + +- **on_error** (*Optional*, :ref:`Automation `): An automation to perform when an error happened during download or decode. + +Actions +------- + +**online_image.set_url**: Change the URL where the image is downloaded from. The image needs to be manually updated afterwards. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The image to update the URL for. +- **url** (**Required**, url): The new URL to download the image from. + +.. code-block:: yaml + + on_...: + - online_image.set_url: + id: my_online_image + url: "https://www.example.com/new_image.png" + - component.update: my_online_image + +**online_image.release**: Release the memory currently used by an image. Can be used if different display pages need different images, to avoid wasting memory on an image that is currently not being displayed. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The image to update the URL for. + +.. code-block:: yaml + + on_...: + - online_image.release: my_online_image + +Examples +-------- + +.. code-block:: yaml + + online_image: + - url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png" + format: png + id: my_online_image + on_download_finished: + component.update: my_display + +And then later in code: + +.. code-block:: yaml + + display: + - platform: ... + id: my_display + # ... + lambda: |- + // Draw the image my_online_image at position [x=0,y=0] + it.image(0, 0, id(my_online_image)); + +For monochrome displays the ``image`` method accepts two additional color parameters which can +be supplied to specify the color used to draw bright and dark pixels respectively. +In this case the image will be internally converted to a grayscale image and then to monochrome +based on an internally defined threshold. + +.. code-block:: yaml + + display: + - platform: ... + id: my_display + # ... + lambda: |- + // Draw the image my_image at position [x=0,y=0] + // with front color "OFF" and back color "ON" + it.image(0, 0, id(my_online_image), COLOR_OFF, COLOR_ON); + +By default ``online_image`` is configured to not automatically update/download the image; in order to do the initial download, you can either: + - Add a ``component.update `` in the ``on_connect:`` action on the :doc:`/components/wifi` component. + - Explicitly set an ``update_interval``. + - Call ``component.update `` in an :doc:`/components/interval` block. + - Call ``component.update `` where you need the image to be downloaded/updated. + +.. code-block:: yaml + + wifi: + on_connect: + - component.update: my_online_image + +See Also +-------- + +- :apiref:`online_image/online_image.h` +- :doc:`Image Component ` +- :doc:`Animation Component ` +- :ghedit:`Edit` diff --git a/components/ota/esphome.rst b/components/ota/esphome.rst index 1c735daadc..ed97c343e7 100644 --- a/components/ota/esphome.rst +++ b/components/ota/esphome.rst @@ -22,7 +22,6 @@ expected. This is automatically enabled by this component, but it may be disable # Example configuration entry ota: - platform: esphome - safe_mode: true password: !secret ota_password Configuration variables: @@ -67,6 +66,7 @@ won't work. This issue can be worked around by executing the operations separate id: my_ota password: "Old password" +The "id: my_ota" in the OTA block is important. This is referenced in the lambda. After this trick has been used to change the password, the ``on_boot`` trigger may be removed and the old password replaced with the new password in the ``ota:`` section. @@ -75,6 +75,16 @@ Adding a Password If OTA is already enabled without a password, simply add a ``password:`` line to the existing ``ota:`` config block. +Removing a Password +******************* + +- If you know your password but want to remove it, enter an empty string: ``id(my_ota).set_auth_password("");`` instead of changing. +- If you no longer know your password and the web server has been activated: + + - Remove the OTA password from the configuration + - Build a new image locally. + - Execute the OTA update directly via the ESP web server. + See Also -------- diff --git a/components/output/ble_client.rst b/components/output/ble_client.rst index 3aed40ed78..53c1f4452c 100644 --- a/components/output/ble_client.rst +++ b/components/output/ble_client.rst @@ -12,7 +12,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -22,7 +22,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black output: @@ -39,7 +39,7 @@ Configuration variables: - **service_uuid** (**Required**, UUID): UUID of the service on the device. - **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to write to. - **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. -- **require_response** (*Optional*, boolean): Control whether to require a remote response from the device when writing. +- **require_response** (*Optional*, boolean): Control whether to require a remote response from the device when writing. Whether or not this is required will vary by device. Defaults to ``false`` - All other options from :ref:`Output `. diff --git a/components/packages.rst b/components/packages.rst new file mode 100644 index 0000000000..6acc58a3e4 --- /dev/null +++ b/components/packages.rst @@ -0,0 +1,203 @@ +Packages +======== + +.. seo:: + :description: How to use packages in ESPHome + :image: settings.svg + +When you have many ESPHome devices (or are producing and distributing them at scale), a common need tends to surface: +configuration modularization. You'll likely want to break your configuration into common (groups of) elements, building +it into reusable pieces which can subsequently be used by many/all devices. Only unique pieces of your configuration +remain in any given device's YAML configuration file. + +This can be accomplished with ESPHome's ``packages`` feature. + +All definitions from packages will be merged with your device's main configuration in a non-destructive way. This +allows overriding (parts of) configuration contained in the package(s). Substitutions in your main configuration will +override substitutions with the same name in a package. + +Dictionaries are merged key-by-key. Lists of components are merged by component ID (if specified). Other lists are +merged by concatenation. All other configuration values are replaced with the later value. + +ESPHome uses ``!include`` to "bring in" packages; this is a syntax brought over from +`Home Assistant's YAML configuration directives `__. + +Local Packages +-------------- + +Consider the following example where the author put common pieces of configuration (like Wi-Fi and API) into base files +and then extends it with some device-specific configuration in the main configuration. + +Note how the piece of configuration describing ``api`` component in ``device_base.yaml`` gets merged with the actions +definitions from main configuration file. + +.. code-block:: yaml + + # In config.yaml + packages: + wifi: !include common/wifi.yaml + device_base: !include common/device_base.yaml + + api: + actions: + - action: start_laundry + then: + - switch.turn_on: relay + + # any additional configuration... + +.. code-block:: yaml + + # In wifi.yaml + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + +.. code-block:: yaml + + # In device_base.yaml + esphome: + name: ${node_name} + + esp32: + board: wemos_d1_mini32 + + logger: + + api: + encryption: + key: !secret api_encryption_key + +.. _config-git_packages: + +Remote/Git Packages +------------------- + +Packages can also be loaded from a Git repository by utilizing the correct configuration syntax. +:doc:`/components/substitutions` can be used inside the remote packages which allows users to override +them locally with their own substitution value. + +.. note:: + + Remote packages cannot have ``secret`` lookups in them. They should instead make use of substitutions with an + optional default in the packaged YAML, which the local device YAML can set using values from the local secrets. + +.. code-block:: yaml + + # Git repo examples + packages: + # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] + remote_package_shorthand: github://esphome/non-existant-repo/file1.yml@main + + remote_package_files: + url: https://github.com/esphome/non-existant-repo + files: [file1.yml, file2.yml] # optional; if not specified, all files will be included + ref: main # optional + refresh: 1d # optional + +Configuration variables: +------------------------ + +For each package: + +- **url** (**Required**, string): The URL for the repository. +- **username** (*Optional*, string): Username to be used for authentication, if required. +- **password** (*Optional*, string): Password to be used for authentication, if required. +- **files** (**Required**, list of strings): List of files to include. +- **ref** (*Optional*, string): The Git ref(erence) to be used when pulling content from the repository. +- **refresh** (*Optional*, :ref:`config-time`): The interval at which the content from the repository should be refreshed. + +Packages as Templates +--------------------- + +Since packages are incorporated using the ``!include`` system, variables can be provided to them. This means that +packages can be used as *templates*, allowing complex or repetitive configurations to be stored in a package file +and then incorporated into the configuration more than once. + +Packages may also contain a ``defaults`` block which provides subsitutions for variables not provided by the +``!include`` block. + +As an example, if the configuration needed to support three garage doors using the ``gpio`` switch platform and the +``time_based`` cover platform, it could be constructed like this: + +.. code-block:: yaml + + # In config.yaml + packages: + left_garage_door: !include + file: garage-door.yaml + vars: + door_name: Left + vars: + door_name: Middle + vars: + door_name: Right + + +.. code-block:: yaml + + # In garage-door.yaml + switch: + - name: ${door_name} Garage Door Switch + platform: gpio + # ... + +Extend +------ + +To make changes or add additional configuration to included configurations, ``!extend config_id`` can be used, where +``config_id`` is the ID of the configuration to modify. + +For example, to set a specific update interval on a common uptime sensor that is shared between configurations: + +.. code-block:: yaml + + # In common.yaml + captive_portal: + + sensor: + - platform: uptime + id: uptime_sensor + update_interval: 1min + +.. code-block:: yaml + + packages: + common: !include common.yaml + + sensor: + - id: !extend uptime_sensor + update_interval: 10s + +Remove +------ + +To remove existing entries from included configurations, ``!remove [config_id]`` can be used, where ``config_id`` is +the ID of the entry to modify. + +For example, to remove a common uptime sensor that is shared between configurations: + +.. code-block:: yaml + + packages: + common: !include common.yaml # see above + + sensor: + - id: !remove uptime_sensor + +To remove captive portal for a specific device: + +.. code-block:: yaml + + packages: + common: !include common.yaml # see above + + captive_portal: !remove + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`/guides/getting_started_command_line` +- :doc:`/guides/faq` +- :ghedit:`Edit` diff --git a/components/pipsolar.rst b/components/pipsolar.rst index 89b63d2f68..b6cb09678b 100644 --- a/components/pipsolar.rst +++ b/components/pipsolar.rst @@ -242,6 +242,8 @@ Not all possible switches are exposed as they lead to the possibility to make se name: inverter0_output_source_priority_solar output_source_priority_battery: name: inverter0_output_source_priority_battery + output_source_priority_hybrid: + name: inverter0_output_source_priority_hybrid input_voltage_range: name: inverter0_input_voltage_range pv_ok_condition_for_parallel: @@ -256,6 +258,7 @@ All sensors are normal text sensors... so all text sensor variables are working - **output_source_priority_utility** (*Optional*): output source priority utility - **output_source_priority_solar** (*Optional*): output source priority solar - **output_source_priority_battery** (*Optional*): output source priority battery +- **output_source_priority_hybrid** (*Optional*): output source priority hybrid - **input_voltage_range** (*Optional*): input voltage range - **pv_ok_condition_for_parallel** (*Optional*): pv ok condition for parallel - **pv_power_balance** (*Optional*): pv power balance @@ -320,7 +323,7 @@ target level of the output. then: - output.pipsolar.set_level: id: my_pipsolar_output - level: 48.0 + value: 48.0 Configuration options: diff --git a/components/qr_code.rst b/components/qr_code.rst new file mode 100644 index 0000000000..fb178b0339 --- /dev/null +++ b/components/qr_code.rst @@ -0,0 +1,50 @@ +.. _display-qrcode: + +QR Code Component +================= + +.. seo:: + :description: Instructions for displaying a QR Code in ESPHome + :image: qr-code.svg + +Use this component to generate a QR-code containing a string on the device, which can then be drawn on compatible displays. + +.. code-block:: yaml + + qr_code: + - id: homepage_qr + value: esphome.io + +Configuration variables: +------------------------ + +- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the QR-code later + in your display code. +- **value** (**Required**, string): The string which you want to encode in the QR-code. +- **ecc** (*Optional*, string): The error correction code level you want to use. Defaults to ``LOW``. You can use one of the following values: + + - ``LOW``: The QR Code can tolerate about 7% erroneous codewords + - ``MEDIUM``: The QR Code can tolerate about 15% erroneous codewords + - ``QUARTILE``: The QR Code can tolerate about 25% erroneous codewords + - ``HIGH``: The QR Code can tolerate about 30% erroneous codewords + +To draw the QR-code, call the ``it.qr_code`` function from your render lambda: + +.. code-block:: yaml + + display: + - platform: ... + # ... + pages: + - id: page1 + lambda: |- + // Draw the QR-code at position [x=50,y=0] with white color and a 2x scale + it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2); + + // Draw the QR-code in the center of the screen with white color and a 2x scale + auto size = id(homepage_qr).get_size() * 2; // Multiply by scale + auto x = (it.get_width() / 2) - (size / 2); + auto y = (it.get_height() / 2) - (size / 2); + it.qr_code(x, y, id(homepage_qr), Color(255,255,255), 2); + + diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index a994d8c51e..d2374f7c0b 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -23,6 +23,8 @@ which will trigger when they hear their own configured signal. pin: GPIOXX dump: all +Multiple remote receivers can be configured as a list of dict definitions in remote_receiver. + Configuration variables: ------------------------ @@ -30,7 +32,7 @@ Configuration variables: - **dump** (*Optional*, list): Decode and dump these remote codes in the logs (at log.level=DEBUG). Set to ``all`` to dump all available codecs: - - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`remote_transmitter-transmit_abbwelcome` + - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`transmitter description ` for more details. - **aeha**: Decode and dump AEHA infrared codes. - **byronsx**: Decode and dump Byron SX doorbell RF codes. - **canalsat**: Decode and dump CanalSat infrared codes. @@ -232,23 +234,20 @@ then immediately OFF. Configuration variables: ************************ -- **name** (**Required**, string): The name for the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **receiver_id** (*Optional*, :ref:`config-id`): The remote receiver to receive the + remote code with. Required if multiple receivers configured. - All other options from :ref:`Binary Sensor `. Remote code selection (exactly one of these has to be included): -- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data. +- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data, see the :ref:`transmitter description ` for more info. - - **source_address** (**Required**, int): The source address to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome` - for more info. - - **destination_address** (**Required**, int): The destination address to trigger on, see - :ref:`remote_transmitter-transmit_abbwelcome` for more info. + - **source_address** (**Required**, int): The source address to trigger on. + - **destination_address** (**Required**, int): The destination address to trigger on. - **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false`` means two bytes and ``true`` means three bytes. Defaults to ``false``. - **retransmission** (**Optional**, boolean): ``true`` if the message was re-transmitted. Defaults to ``false``. - - **message_type** (**Required**, int): The message type to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome` - for more info. + - **message_type** (**Required**, int): The message type to trigger on. - **message_id** (**Optional**, int): The random message ID to trigger on, see dumper output for more info. Defaults to any ID. - **data** (**Optional**, 0-7 bytes list): The code to listen for. Usually you only need to copy this directly from the dumper output. Defaults to ``[]`` @@ -256,7 +255,7 @@ Remote code selection (exactly one of these has to be included): - **aeha**: Trigger on a decoded AEHA remote code with the given data. - **address** (**Required**, int): The address to trigger on, see dumper output for more info. - - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_aeha` + - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **byronsx**: Trigger on a decoded Byron SX Doorbell RF remote code with the given data. @@ -313,7 +312,7 @@ Remote code selection (exactly one of these has to be included): - **haier**: Trigger on a Haier remote code with the given code. - - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_haier` + - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **lg**: Trigger on a decoded LG remote code with the given data. @@ -328,7 +327,7 @@ Remote code selection (exactly one of these has to be included): - **midea**: Trigger on a Midea remote code with the given code. - - **code** (**Required**, 5-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_midea` + - **code** (**Required**, 5-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy first 5 bytes directly from the dumper output. - **nec**: Trigger on a decoded NEC remote code with the given data. @@ -355,14 +354,14 @@ Remote code selection (exactly one of these has to be included): - **pronto**: Trigger on a Pronto remote code with the given code. - - **data** (**Required**, string): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + - **data** (**Required**, string): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **delta** (**Optional**, integer): This parameter allows you to manually specify the allowed difference between what Pronto code is specified, and what IR signal has been sent by the remote control. - **raw**: Trigger on a raw remote code with the given code. - - **code** (**Required**, list): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + - **code** (**Required**, list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. - **rc5**: Trigger on a decoded RC5 remote code with the given data. @@ -436,7 +435,7 @@ Remote code selection (exactly one of these has to be included): - **mirage**: Trigger on a Mirage remote code with the given code. - - **code** (**Required**, 14-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_mirage` + - **code** (**Required**, 14-bytes list): The code to listen for, see :ref:`transmitter description ` for more info. Usually you only need to copy this directly from the dumper output. .. note:: @@ -491,8 +490,9 @@ See Also - :doc:`index` - :doc:`/components/remote_transmitter` +- :ref:`remote-setting-up-infrared` +- :ref:`remote-setting-up-rf` - :doc:`/components/rf_bridge` - `RCSwitch `__ by `Suat Özgür `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote/remote_receiver.h` - :ghedit:`Edit` diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 1774a35d01..8f47bd2230 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -2,9 +2,9 @@ Remote Transmitter ================== .. seo:: - :description: Instructions for setting up switches that send out pre-defined sequences of IR or RF signals + :description: Instructions for setting up configurations that send out pre-defined sequences of IR or RF signals :image: remote.svg - :keywords: Infrared, IR, RF, Remote, TX + :keywords: Infrared, IR, RF, Remote, TX, 433, Blaster The ``remote_transmitter`` component lets you send digital packets to control devices in your home. For example this includes infrared data or 433MHz RF signals. @@ -71,8 +71,8 @@ Configuration variables: - **repeat** (*Optional*): Optionally set the code to be repeated a number of times. Defaults to sending the code only once. - - **times** (int): The number of times to repeat the code. - - **wait_time** (:ref:`config-time`): The time to wait between repeats. + - **times** (:ref:`templatable `, int): The number of times to repeat the code. + - **wait_time** (:ref:`templatable `, :ref:`config-time`): The time to wait between repeats (in µs as a result of a :ref:`lambda `). - **transmitter_id** (*Optional*, :ref:`config-id`): The remote transmitter to send the remote code with. Defaults to the first one defined in the configuration. @@ -82,8 +82,7 @@ Home Assistant, you'll want to set the **times** to 10 and the **wait_time** to .. _remote_transmitter-transmit_abbwelcome: -``remote_transmitter.transmit_abbwelcome`` Action -************************************************* +``remote_transmitter.transmit_abbwelcome`` **Action** This :ref:`action ` sends a ABB-Welcome message to the intercom bus. The message type, addresses, address length and data can vary a lot between ABB-Welcome @@ -123,6 +122,7 @@ Configuration variables: Defaults to a randomly generated ID if this message is not a reply or retransmission. - **data** (**Optional**, 0-7 bytes list): The code to send. Usually you only need to copy this directly from the dumper output. Defaults to ``[]`` +- All other options from :ref:`remote_transmitter-transmit_action`. .. note:: @@ -132,8 +132,7 @@ Configuration variables: .. _remote_transmitter-transmit_aeha: -``remote_transmitter.transmit_aeha`` Action -********************************************* +``remote_transmitter.transmit_aeha`` **Action** This :ref:`action ` sends a AEHA code to a remote transmitter. @@ -150,13 +149,13 @@ Configuration variables: - **data** (**Required**, list): The command to send, A length of 2-35 bytes can be specified for one packet. - **carrier_frequency** (*Optional*, float): Set a frequency to send the signal with for infrared signals. Defaults to ``38000Hz``. +- All other options from :ref:`remote_transmitter-transmit_action`. AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other companies. .. _remote_transmitter-transmit_byronsx: -``remote_transmitter.transmit_byronsx`` Action -********************************************** +``remote_transmitter.transmit_byronsx`` **Action** This :ref:`action ` sends a Byron Doorbell RF protocol code to a remote transmitter. @@ -171,10 +170,11 @@ Configuration variables: - **address** (**Required**, int): The 8-bit ID to send, see dumper output for more info. - **command** (**Required**, int): The command to send, see dumper output for more info. -- All other options from :ref:`remote_transmitter-transmit_action`... _remote_transmitter-transmit_canalsat: +- All other options from :ref:`remote_transmitter-transmit_action`. + +.. _remote_transmitter-transmit_canalsat: -``remote_transmitter.transmit_canalsat`` Action -*********************************************** +``remote_transmitter.transmit_canalsat`` **Action** This :ref:`action ` sends a CanalSat infrared remote code to a remote transmitter. @@ -200,8 +200,7 @@ Configuration variables: .. _remote_transmitter-transmit_canalsatld: -``remote_transmitter.transmit_canalsatld`` Action -************************************************* +``remote_transmitter.transmit_canalsatld`` **Action** This :ref:`action ` sends a CanalSatLD infrared remote code to a remote transmitter. @@ -227,8 +226,7 @@ Configuration variables: .. _remote_transmitter-transmit_coolix: -``remote_transmitter.transmit_coolix`` Action -********************************************* +``remote_transmitter.transmit_coolix`` **Action** This :ref:`action ` sends one or two (stricted or not) 24-bit Coolix infrared remote codes to a remote transmitter. @@ -243,11 +241,11 @@ Configuration variables: - **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send, see dumper output for more info. - **second** (*Optional*, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. +- All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_dish: -``remote_transmitter.transmit_dish`` Action -******************************************* +``remote_transmitter.transmit_dish`` **Action** This :ref:`action ` sends a Dish Network infrared remote code to a remote transmitter. @@ -268,8 +266,7 @@ You can find a list of commands in the `LIRC project ` sends a Dooya RF remote code to a remote transmitter. @@ -292,8 +289,7 @@ Configuration variables: .. _remote_transmitter-transmit_drayton: -``remote_transmitter.transmit_drayton`` Action -********************************************** +``remote_transmitter.transmit_drayton`` **Action** This :ref:`action ` sends a Draton Digistat RF remote code to a remote transmitter. @@ -314,8 +310,7 @@ Configuration variables: .. _remote_transmitter-transmit_jvc: -``remote_transmitter.transmit_jvc`` Action -****************************************** +``remote_transmitter.transmit_jvc`` **Action** This :ref:`action ` sends a JVC infrared remote code to a remote transmitter. @@ -328,11 +323,11 @@ This :ref:`action ` sends a JVC infrared remote code to a remote Configuration variables: - **data** (**Required**, int): The JVC code to send, see dumper output for more info. +- All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_keeloq: -``remote_transmitter.transmit_keeloq`` Action -********************************************** +``remote_transmitter.transmit_keeloq`` **Action** This :ref:`action ` sends KeeLoq RF remote code to a remote transmitter. @@ -358,8 +353,7 @@ Configuration variables: .. _remote_transmitter-transmit_haier: -``remote_transmitter.transmit_haier`` Action -******************************************** +``remote_transmitter.transmit_haier`` **Action** This :ref:`action ` sends a 104-bit Haier code to a remote transmitter. 8-bits of checksum added automatically. @@ -376,8 +370,7 @@ Configuration variables: .. _remote_transmitter-transmit_lg: -``remote_transmitter.transmit_lg`` Action -***************************************** +``remote_transmitter.transmit_lg`` **Action** This :ref:`action ` sends an LG infrared remote code to a remote transmitter. @@ -396,8 +389,7 @@ Configuration variables: .. _remote_transmitter-transmit_magiquest: -``remote_transmitter.transmit_magiquest`` Action -************************************************ +``remote_transmitter.transmit_magiquest`` **Action** This :ref:`action ` sends a MagiQuest wand code to a remote transmitter. @@ -416,8 +408,7 @@ Configuration variables: .. _remote_transmitter-transmit_midea: -``remote_transmitter.transmit_midea`` Action -******************************************** +``remote_transmitter.transmit_midea`` **Action** This :ref:`action ` sends a 40-bit Midea code to a remote transmitter. 8-bits of checksum added automatically. @@ -438,8 +429,7 @@ Configuration variables: - **code** (**Required**, list, :ref:`templatable `): The 40-bit Midea code to send as a list of hex or integers. - All other options from :ref:`remote_transmitter-transmit_action`. -``remote_transmitter.transmit_nec`` Action -****************************************** +``remote_transmitter.transmit_nec`` **Action** This :ref:`action ` sends an NEC infrared remote code to a remote transmitter. @@ -466,8 +456,7 @@ Configuration variables: - **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. Defaults to `1`. - All other options from :ref:`remote_transmitter-transmit_action`. -``remote_transmitter.transmit_nexa`` Action -******************************************* +``remote_transmitter.transmit_nexa`` **Action** This :ref:`action ` a Nexa RF remote code to a remote transmitter. @@ -492,8 +481,7 @@ Configuration variables: .. _remote_transmitter-transmit_panasonic: -``remote_transmitter.transmit_panasonic`` Action -************************************************ +``remote_transmitter.transmit_panasonic`` **Action** This :ref:`action ` sends a Panasonic infrared remote code to a remote transmitter. @@ -512,8 +500,7 @@ Configuration variables: .. _remote_transmitter-transmit_pioneer: -``remote_transmitter.transmit_pioneer`` Action -********************************************** +``remote_transmitter.transmit_pioneer`` **Action** This :ref:`action ` sends a Pioneer infrared remote code to a remote transmitter. @@ -543,8 +530,7 @@ are largely shared among devices within a given class. .. _remote_transmitter-transmit_pronto: -``remote_transmitter.transmit_pronto`` Action -********************************************* +``remote_transmitter.transmit_pronto`` **Action** This :ref:`action ` sends a raw code to a remote transmitter specified in Pronto format. @@ -562,8 +548,7 @@ Configuration variables: .. _remote_transmitter-transmit_raw: -``remote_transmitter.transmit_raw`` Action -****************************************** +``remote_transmitter.transmit_raw`` **Action** This :ref:`action ` sends a raw code to a remote transmitter. @@ -590,8 +575,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc5: -``remote_transmitter.transmit_rc5`` Action -****************************************** +``remote_transmitter.transmit_rc5`` **Action** This :ref:`action ` sends an RC5 infrared remote code to a remote transmitter. @@ -610,8 +594,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc6: -``remote_transmitter.transmit_rc6`` Action -****************************************** +``remote_transmitter.transmit_rc6`` **Action** This :ref:`action ` sends an RC6 infrared remote code to a remote transmitter. @@ -630,8 +613,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_raw: -``remote_transmitter.transmit_rc_switch_raw`` Action -**************************************************** +``remote_transmitter.transmit_rc_switch_raw`` **Action** This :ref:`action ` sends a raw RC-Switch code to a remote transmitter. @@ -650,28 +632,9 @@ Configuration variables: for more information. - All other options from :ref:`remote_transmitter-transmit_action`. -.. _remote_transmitter-rc_switch-protocol: - -RC Switch Protocol -^^^^^^^^^^^^^^^^^^ - -All RC Switch ``protocol`` settings have these settings: - -- Either the value is an integer, then the inbuilt protocol definition with the given number - is used. -- Or a key-value mapping is given, then there are these settings: - - - **pulse_length** (**Required**, int): The pulse length of the protocol - how many microseconds - one pulse should last for. - - **sync** (*Optional*): The number of high/low pulses for the sync header, defaults to ``[1, 31]`` - - **zero** (*Optional*): The number of high/low pulses for a zero bit, defaults to ``[1, 3]`` - - **one** (*Optional*): The number of high/low pulses for a one bit, defaults to ``[3, 1]`` - - **inverted** (*Optional*, boolean): If this protocol is inverted. Defaults to ``false``. - .. _remote_transmitter-transmit_rc_switch_type_a: -``remote_transmitter.transmit_rc_switch_type_a`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_a`` **Action** This :ref:`action ` sends a type A RC-Switch code to a remote transmitter. @@ -696,8 +659,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_b: -``remote_transmitter.transmit_rc_switch_type_b`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_b`` **Action** This :ref:`action ` sends a type B RC-Switch code to a remote transmitter. @@ -722,8 +684,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_c: -``remote_transmitter.transmit_rc_switch_type_c`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_c`` **Action** This :ref:`action ` sends a type C RC-Switch code to a remote transmitter. @@ -750,8 +711,7 @@ Configuration variables: .. _remote_transmitter-transmit_rc_switch_type_d: -``remote_transmitter.transmit_rc_switch_type_d`` Action -******************************************************* +``remote_transmitter.transmit_rc_switch_type_d`` **Action** This :ref:`action ` sends a type D RC-Switch code to a remote transmitter. @@ -776,8 +736,7 @@ Configuration variables: .. _remote_transmitter-transmit_roomba: -``remote_transmitter.transmit_roomba`` Action -********************************************* +``remote_transmitter.transmit_roomba`` **Action** This :ref:`action ` sends a Roomba infrared remote code to a remote transmitter. @@ -799,8 +758,7 @@ Configuration variables: .. _remote_transmitter-transmit_samsung: -``remote_transmitter.transmit_samsung`` Action -********************************************** +``remote_transmitter.transmit_samsung`` **Action** This :ref:`action ` sends a Samsung infrared remote code to a remote transmitter. It transmits codes up to 64 bits in length in a single packet. @@ -823,8 +781,7 @@ Configuration variables: .. _remote_transmitter-transmit_samsung36: -``remote_transmitter.transmit_samsung36`` Action -************************************************ +``remote_transmitter.transmit_samsung36`` **Action** This :ref:`action ` sends a Samsung36 infrared remote code to a remote transmitter. It transmits the ``address`` and ``command`` in two packets separated by a "space". @@ -844,8 +801,7 @@ Configuration variables: .. _remote_transmitter-transmit_sony: -``remote_transmitter.transmit_sony`` Action -******************************************* +``remote_transmitter.transmit_sony`` **Action** This :ref:`action ` a Sony infrared remote code to a remote transmitter. @@ -864,8 +820,7 @@ Configuration variables: .. _remote_transmitter-transmit_toshiba_ac: -``remote_transmitter.transmit_toshiba_ac`` Action -************************************************* +``remote_transmitter.transmit_toshiba_ac`` **Action** This :ref:`action ` sends a Toshiba AC infrared remote code to a remote transmitter. @@ -885,13 +840,11 @@ Configuration variables: - **rc_code_1** (**Required**, int): The remote control code to send, see dumper output for more details. - **rc_code_2** (*Optional*, int): The secondary remote control code to send; some codes are sent in two parts. - - All other options from :ref:`remote_transmitter-transmit_action`. .. _remote_transmitter-transmit_mirage: -``remote_transmitter.transmit_mirage`` Action -********************************************* +``remote_transmitter.transmit_mirage`` **Action** This :ref:`action ` sends a 112-bit Mirage code to a remote transmitter. 8-bits of checksum added automatically. @@ -906,6 +859,24 @@ Configuration variables: - **code** (**Required**, list): The 14 byte Mirage code to send. - All other options from :ref:`remote_transmitter-transmit_action`. +.. _remote_transmitter-rc_switch-protocol: + +RC Switch Protocol +****************** + +All RC Switch ``protocol`` settings have these settings: + +- Either the value is an integer, then the inbuilt protocol definition with the given number + is used. +- Or a key-value mapping is given, then there are these settings: + + - **pulse_length** (**Required**, int): The pulse length of the protocol - how many microseconds + one pulse should last for. + - **sync** (*Optional*): The number of high/low pulses for the sync header, defaults to ``[1, 31]`` + - **zero** (*Optional*): The number of high/low pulses for a zero bit, defaults to ``[1, 3]`` + - **one** (*Optional*): The number of high/low pulses for a one bit, defaults to ``[3, 1]`` + - **inverted** (*Optional*, boolean): If this protocol is inverted. Defaults to ``false``. + Lambda calls ************ @@ -924,202 +895,15 @@ See the full API Reference for more info. call.set_send_times(2); call.perform(); - -.. _remote-setting-up-infrared: - -Setting up Infrared Devices ---------------------------- - -In this guide an infrared device will be set up with ESPHome. First, the remote code -will be captured with an IR receiver module (like `this one `__). -We will use ESPHome's dumping ability to output the decoded remote code directly. - -Then we will set up a new remote transmitter with an infrared LED (like -`this one `__) to transmit the -code when a switch is triggered. - -First, connect the infrared receiver module to a pin on your board and set up a -remote_receiver instance: - -.. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: all - -Compile and upload the code. While viewing the log output from the ESP, -press a button on an infrared remote you want to capture (one at a time). - -You should see log output like below: - -.. code-block:: text - - # If the codec is known: - [D][remote.panasonic] Received Panasonic: address=0x4004 command=0x8140DFA2 - - # Or raw output if it's not known yet - # The values may fluctuate a bit, but as long as they're similar it's ok - [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 - -If the codec is already implemented in ESPHome, you will see the decoded value directly - -otherwise you will see the raw data dump (which you can use just as well). You have -just successfully captured your first infrared code. - -Now let's use this information to emulate a button press from the ESP. First, wire up the -IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` instance: - -.. code-block:: yaml - - remote_transmitter: - pin: GPIOXX - # Infrared remotes use a 50% carrier signal - carrier_duty_percent: 50% - -This will allow us to send any data we want via the IR LED. To replicate the codes we decoded -earlier, create a new template switch that sends the infrared code when triggered: - -.. code-block:: yaml - - switch: - - platform: template - name: Panasonic Power Button - turn_on_action: - - remote_transmitter.transmit_panasonic: - address: 0x4004 - command: 0x8140DFA2 - - # Or for raw code - switch: - - platform: template - name: Raw Code Power Button - turn_on_action: - - remote_transmitter.transmit_raw: - carrier_frequency: 38kHz - code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] - -Recompile again, when you power up the device the next time you will see a new switch -in the frontend. Click on it and you should see the remote signal being transmitted. Done! - -.. _remote-setting-up-rf: - -Setting Up RF Devices ---------------------- - -The ``remote_transmitter`` and ``remote_receiver`` components can also be used to send -and receive 433MHz RF signals. This guide will discuss setting up a 433MHz receiver to -capture a device's remote codes. After that we will set up a 433MHz transmitter to replicate -the remote code with the press of a switch in the frontend. - -First, connect the RF module to a pin on the ESP and set up a remote_receiver instance: - -.. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: all - # Settings to optimize recognition of RF devices - tolerance: 50% - filter: 250us - idle: 4ms - buffer_size: 2kb - -Compile and upload the code. While viewing the log output from the ESP, -press a button on an RF remote you want to capture (one at a time). - -You should see log output like below: - -.. code-block:: text - - # If the codec is known: - [D][remote.rc_switch] Received RCSwitch: protocol=2 data='100010000000000010111110' - - # Or raw output if it's not known yet - # The values may fluctuate a bit, but as long as they're similar it's ok - [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 - -.. note:: - - If the log output is flooded with "Received Raw" messages, you can also disable raw - remote code reporting and rely on rc_switch to decode the values. - - .. code-block:: yaml - - remote_receiver: - pin: GPIOXX - dump: - - rc_switch - tolerance: 50% - filter: 250us - idle: 4ms - buffer_size: 2kb - -If the codec is already implemented in ESPHome, you will see the decoded value directly - -otherwise you will see the raw data dump (which you can use just as well). You have -just successfully captured your first RF code. - -Now let's use this information to emulate a button press from the ESP. First, wire up the -RF transmitter to a new pin on the ESP and configure a global ``remote_transmitter`` instance: - -.. code-block:: yaml - - remote_transmitter: - pin: GPIOXX - # RF uses a 100% carrier signal - carrier_duty_percent: 100% - -This will allow us to send any data we want via the RF transmitter. To replicate the codes we decoded -earlier, create a new template switch that sends the RF code when triggered: - -.. code-block:: yaml - - switch: - - platform: template - name: RF Power Button - optimistic: true - turn_on_action: - - remote_transmitter.transmit_rc_switch_raw: - code: '100010000000000010111110' - protocol: 2 - repeat: - times: 10 - wait_time: 0s - - - # Or for raw code - switch: - - platform: template - name: Raw Code Power Button - turn_on_action: - - remote_transmitter.transmit_raw: - code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] - -Recompile again, when you power up the device the next time you will see a new switch -in the frontend. Click on it and you should see the remote signal being transmitted. Done! - -.. note:: - - Some devices require that the transmitted code be repeated for the signal to be picked up - as valid. Also the interval between repetitions can be important. Check that the pace of - repetition logs are consistent between the remote controller and the transmitter node. - You can adjust the ``repeat:`` settings accordingly. - - - See Also -------- - :doc:`index` - :doc:`/components/remote_receiver` +- :ref:`remote-setting-up-infrared` +- :ref:`remote-setting-up-rf` +- :doc:`/components/rf_bridge` - :ref:`lambda_magic_rf_queues` - `RCSwitch `__ by `Suat Özgür `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote_transmitter/remote_transmitter.h` - :ghedit:`Edit` diff --git a/components/rf_bridge.rst b/components/rf_bridge.rst index 0ab8e3b73a..da6b51dc2d 100644 --- a/components/rf_bridge.rst +++ b/components/rf_bridge.rst @@ -21,6 +21,8 @@ which is 19200bps. :align: center :width: 60.0% + Sonoff RF Bridge 433, version R1 or R2 V1.0 + .. code-block:: yaml # Example configuration entry @@ -345,8 +347,8 @@ Home Assistant as events and will also setup a service so you can send codes wit .. code-block:: yaml api: - services: - - service: send_rf_code + actions: + - action: send_rf_code variables: sync: int low: int @@ -358,7 +360,7 @@ Home Assistant as events and will also setup a service so you can send codes wit low: !lambda 'return low;' high: !lambda 'return high;' code: !lambda 'return code;' - - service: learn + - action: learn then: - rf_bridge.learn @@ -391,7 +393,7 @@ To trigger the automation from Home Assistant you can invoke the service with th automation: # ... action: - - service: esphome.rf_bridge_send_rf_code + - action: esphome.rf_bridge_send_rf_code data: sync: 0x700 low: 0x800 diff --git a/components/rtttl.rst b/components/rtttl.rst index b502a649e0..dd0872e17e 100644 --- a/components/rtttl.rst +++ b/components/rtttl.rst @@ -174,8 +174,8 @@ Sample code - logger.log: 'Song ended!' api: - services: - - service: play_rtttl + actions: + - action: play_rtttl variables: song_str: string then: diff --git a/components/script.rst b/components/script.rst index 1b400fd110..7112626e04 100644 --- a/components/script.rst +++ b/components/script.rst @@ -1,7 +1,5 @@ -.. _scripts: - -``script`` Component --------------------- +Script Component +---------------- ESPHome's ``script`` component allows you to define a list of steps (actions) in a central place. You can then execute the script from nearly anywhere in your device's configuration with a single call. diff --git a/components/select/index.rst b/components/select/index.rst index 5c05a65b0e..688f4132bc 100644 --- a/components/select/index.rst +++ b/components/select/index.rst @@ -30,7 +30,8 @@ All selects in ESPHome have a name and an optional icon. Configuration variables: -- **name** (**Required**, string): The name for the select. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the select. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/select/lvgl.rst b/components/select/lvgl.rst new file mode 100644 index 0000000000..711c2509da --- /dev/null +++ b/components/select/lvgl.rst @@ -0,0 +1,44 @@ +LVGL Select +=========== + +.. seo:: + :description: Instructions for setting up an LVGL widget select. + :image: ../images/lvgl_c_sel.png + +The ``lvgl`` select platform creates a select from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-dropdown` and :ref:`lvgl-widget-roller`. A single select supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome select component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the select. +- All other variables from :ref:`Select `. + +Example: + +.. code-block:: yaml + + select: + - platform: lvgl + widget: dropdown_id + name: LVGL Dropdown + +.. note:: + + Widget-specific actions (``lvgl.dropdown.update``, ``lvgl.roller.update``) will trigger correspponding component updates to be sent to Home Assistant. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Roller widget ` +- :ref:`Dropdown widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/select/modbus_controller.rst b/components/select/modbus_controller.rst index 1c90d85266..76cfa56e86 100644 --- a/components/select/modbus_controller.rst +++ b/components/select/modbus_controller.rst @@ -10,7 +10,6 @@ registers. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the Select. - **address** (**Required**, int): The start address of the first or only register of the Select (can be decimal or hexadecimal). - **optionsmap** (**Required**, Map[str, int]): Provide a mapping from options (str) of @@ -38,7 +37,6 @@ Configuration variables: - **force_new_range** (*Optional*, boolean): If possible sensors with sequential addresses are grouped together and requested in one range. Setting this to ``true`` enforces the start of a new range at that address. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the current option of the select. @@ -57,7 +55,7 @@ Configuration variables: - **write_lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated on every update of the Sensor, before the new value is written to the modbus registers. -- **use_write_multiple** (*Optional*, boolean): By default the modbus command *Function Code 6 (Preset Single Registers)* +- **use_write_multiple** (*Optional*, boolean): By default the modbus command *Function Code 6 (Preset Single Registers)* is used for setting the holding register if only one register is set. If your device only supports *Function Code 16 (Preset Multiple Registers)* set this option to ``true``. - **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, any command sent to the Modbus Select will immediately update the reported state. Defaults diff --git a/components/select/template.rst b/components/select/template.rst index 39f544a43e..a349358f21 100644 --- a/components/select/template.rst +++ b/components/select/template.rst @@ -25,7 +25,6 @@ using :ref:`lambdas `. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the Select. - **options** (**Required**, list): The list of options this Select has. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the current option of the select. @@ -42,7 +41,6 @@ Configuration variables: - **initial_option** (*Optional*, string): The option to set the option to on setup if not restored with ``restore_value``. Cannot be used with ``lambda``. Defaults to the first option in the ``options`` list. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Select `. .. note:: diff --git a/components/select/tuya.rst b/components/select/tuya.rst index 1b0b9d5e3b..456d70b191 100644 --- a/components/select/tuya.rst +++ b/components/select/tuya.rst @@ -49,8 +49,6 @@ Based on this, you can create the select as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the switch. - **enum_datapoint** (**Required**, int): The enum datapoint id number for the select. - **options** (**Required**, Map[int, str]): Provide a mapping from values (int) of this Select to options (str) of the *enum_datapoint* and vice versa. All options and diff --git a/components/sensor/a01nyub.rst b/components/sensor/a01nyub.rst index 04371bd0a5..be57d228d4 100644 --- a/components/sensor/a01nyub.rst +++ b/components/sensor/a01nyub.rst @@ -6,7 +6,7 @@ A01NYUB Waterproof Ultrasonic Sensor :image: a01nyub.jpg :keywords: ultrasonic, DFRobot, A01NYUB -This sensor allows you to use A01NYUB waterproof ultrasonic sensor by DFRobot +This sensor allows you to use A01NYUB waterproof ultrasonic sensor by DFRobot (`datasheet `__) with ESPHome to measure distances. This sensor can measure ranges between 28 centimeters and 750 centimeters with a resolution of 1 milimeter. @@ -27,12 +27,11 @@ To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and conn sensor: - platform: "a01nyub" name: "Distance" - + Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus ` you wish to use for this sensor. Use this if you want to use multiple UART buses at once. - All other options from :ref:`Sensor `. diff --git a/components/sensor/a02yyuw.rst b/components/sensor/a02yyuw.rst index 2fc928380d..d090d0a8e4 100644 --- a/components/sensor/a02yyuw.rst +++ b/components/sensor/a02yyuw.rst @@ -6,7 +6,7 @@ A02YYUW Waterproof Ultrasonic Sensor :image: a02yyuw.jpg :keywords: ultrasonic, DFRobot, A02YYUW -This sensor allows you to use A02YYUW waterproof ultrasonic sensor by DFRobot +This sensor allows you to use A02YYUW waterproof ultrasonic sensor by DFRobot (`datasheet `__) with ESPHome to measure distances. This sensor can measure ranges between 3 centimeters and 450 centimeters with a resolution of 1 milimeter. @@ -27,12 +27,11 @@ To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and conn sensor: - platform: "a02yyuw" name: "Distance" - + Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus ` you wish to use for this sensor. Use this if you want to use multiple UART buses at once. - All other options from :ref:`Sensor `. diff --git a/components/sensor/absolute_humidity.rst b/components/sensor/absolute_humidity.rst index 3ba963a81a..b4a27de868 100644 --- a/components/sensor/absolute_humidity.rst +++ b/components/sensor/absolute_humidity.rst @@ -30,7 +30,6 @@ See the links at the bottom of the page for details on absolute humidity and the Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the absolute humidity sensor. - **temperature** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature, in °C. - **humidity** (**Required**, :ref:`config-id`): The sensor that is used to measure the current relative humidity, in %. - **equation** (*Optional*): The saturated vapor pressure equation to use (see below). diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst index a95c690e16..364ba80b71 100644 --- a/components/sensor/adc.rst +++ b/components/sensor/adc.rst @@ -31,14 +31,12 @@ Configuration variables: - **pin** (**Required**, :ref:`config-pin`): The pin to measure the voltage on. Or on the ESP8266 or Raspberry Pi Pico it could alternatively be set to ``VCC``, see :ref:`adc-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`. Defaults to ``0db``. - **raw** (*Optional*): Allows to read the raw ADC output without any conversion or calibration. See :ref:`adc-raw`. Defaults to ``false``. - **samples** (*Optional*): The amount of ADC readings to take per sensor update. On the ESP32 this value is ignored if ``attenuation`` is set to ``auto``. Defaults to ``1``. - **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. - All other options from :ref:`Sensor `. .. note:: @@ -63,7 +61,7 @@ ESP32 Attenuation ----------------- 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``. +Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``12db``. There's more information `at the manufacturer's website `__. To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index 3e2eb83c4e..eae66c79f9 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -88,17 +88,16 @@ Configuration variables: - **multiplexer** (**Required**): The multiplexer channel of this sensor. Effectively means between which pins you want to measure voltage. - **gain** (**Required**, float): The gain of this sensor. -- **name** (**Required**, string): The name for this sensor. - **ads1115_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`ADS1115 Hub ` you want to use this sensor. - **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. - **resolution** (*Optional*, string): the resolution of this sensor. Defaults to ``16 bits``. - ``16 bits`` - ``12 bits`` +- All other options from :ref:`Sensor `. Multiplexer and Gain -------------------- diff --git a/components/sensor/aht10.rst b/components/sensor/aht10.rst index e3550ce51b..d41fec0cb4 100644 --- a/components/sensor/aht10.rst +++ b/components/sensor/aht10.rst @@ -47,15 +47,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst index e6fad15e7d..56267a672b 100644 --- a/components/sensor/airthings_ble.rst +++ b/components/sensor/airthings_ble.rst @@ -29,7 +29,7 @@ The device will then listen for nearby devices, and display a message like this .. code-block:: text [D][airthings_ble:019]: - Found AirThings device Serial: 123456789 (MAC: 01:02:03:04:05:06) + Found AirThings device Serial: 123456789 (MAC: XX:XX:XX:XX:XX:XX) Once the device is found, remove the ``airthings_ble`` device tracker from your configuration and take note of the device MAC address, and use it when configuring a sensor below. @@ -71,11 +71,13 @@ Configuration example: name: "WavePlus CO2" tvoc: name: "WavePlus VOC" + illuminance: + name: "WavePlus ambient light" battery_voltage: name: "WavePlus Battery Voltage" ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: airthings01 esp32_ble_tracker: @@ -110,7 +112,7 @@ Configuration example: name: "WaveMini Battery Voltage" ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: airthingsmini esp32_ble_tracker: diff --git a/components/sensor/am2320.rst b/components/sensor/am2320.rst index 9ed04dde96..6670626b24 100644 --- a/components/sensor/am2320.rst +++ b/components/sensor/am2320.rst @@ -40,15 +40,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/am43.rst b/components/sensor/am43.rst index 108c75f5e2..c057d8d4bf 100644 --- a/components/sensor/am43.rst +++ b/components/sensor/am43.rst @@ -25,7 +25,7 @@ to the device over the ESP32's BLE peripheral. esp32_ble_tracker: ble_client: - - mac: AA:BB:CC:DD:EE:FF + - mac: XX:XX:XX:XX:XX:XX id: am43_device sensor: @@ -45,14 +45,11 @@ Configuration variables: - **ble_client_id** (**Required**, :ref:`config-id`): The id of the ``ble_client`` entry associated with the device. - **battery_level** (*Optional*): The information for the battery level sensor. - - **name** (**Required**, string): The name for the battery level sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. + - **illuminance** (*Optional*): The information for the light level sensor. - - **name** (**Required**, string): The name for the light level sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/apds9306.rst b/components/sensor/apds9306.rst new file mode 100644 index 0000000000..a86bbbb12d --- /dev/null +++ b/components/sensor/apds9306.rst @@ -0,0 +1,70 @@ +APDS9306 Sensor +=============== + +.. seo:: + :description: Instructions for setting up APDS9306 sensors. + :image: apds9306.png + + +.. _apds9306-component: + +Component +--------- + +The ``apds9306`` sensor component allows you to use APDS9306 ambient light sensors (`datasheet `__, `Broadcom`_) with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. figure:: images/apds9306.png + :align: center + :width: 80.0% + + Image by `Broadcom`_ + + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: apds9306 + name: "APDS9306 Light Level" # below are optional + gain: 1 + bit_width: 18 + measurement_rate: 100ms + update_interval: 60s + +.. _Broadcom: https://www.broadcom.com/products/optical-sensors/ambient-light-photo-sensors/apds-9306-065 + +Configuration variables: +------------------------ + +The ``apds9306`` sensor allows you to use your :doc:`apds9306` to perform ambient light measurements. + +- **address** (*Optional*, int): The I²C address of the sensor. Should be ``0x52`` according to datasheet ("Contact factory for other addressing options"). +- **gain** (*Optional*, int): The gain of the ambient light sensor. One of 1, 3, 6, 9, 18. Defaults to ``1``. +- **bit\_width** (*Optional*, int): The bit width/resolution of the ambient light sensor. One of: + + - 20 - takes 400ms + - 19 - takes 200ms + - 18 - takes 100ms (``default``) + - 17 - takes 50ms + - 16 - takes 25ms + - 13 - takes 3.125ms + +- **measurement\_rate** (*Optional*, int): The measurement rate of the ambient light sensor in milliseconds. One of: + + - 25 + - 50 + - 100 (``default``); + - 200 + - 500 + - 1000 + +- **update\_interval** (*Optional*, :ref:`config-time`): The interval at which the sensor reading will be updated. Defaults to ``60s``. +- All opther options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`apds9306/apds9306.h` +- :ghedit:`Edit` diff --git a/components/sensor/apds9960.rst b/components/sensor/apds9960.rst index 0838841cf1..60883aec6f 100644 --- a/components/sensor/apds9960.rst +++ b/components/sensor/apds9960.rst @@ -69,7 +69,6 @@ measurements. Configuration variables: -- **name** (**Required**, string): The name for the sensor. - **type** (**Required**, string): The type of sensor measurement. One of - ``CLEAR`` @@ -78,7 +77,6 @@ Configuration variables: - ``BLUE`` - ``PROXIMITY`` -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. Binary Sensor @@ -89,7 +87,6 @@ measurements. Configuration variables: -- **name** (**Required**, string): The name for the binary sensor. - **direction** (**Required**, string): The direction to measure. One of: - ``UP`` @@ -97,7 +94,6 @@ Configuration variables: - ``LEFT`` - ``RIGHT`` -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Binary Sensor `. Troubleshooting: diff --git a/components/sensor/b_parasite.rst b/components/sensor/b_parasite.rst index ce738a98a4..6617670933 100644 --- a/components/sensor/b_parasite.rst +++ b/components/sensor/b_parasite.rst @@ -24,7 +24,7 @@ The ``b_parasite`` sensor platform tracks b-parasite's Bluetooth Low Energy (BLE sensor: - platform: b_parasite - mac_address: F0:CA:F0:CA:01:01 + mac_address: XX:XX:XX:XX:XX:XX humidity: name: 'b-parasite Air Humidity' temperature: @@ -42,24 +42,23 @@ Configuration variables - **mac_address** (**Required**): The MAC address of the device. - **temperature** (*Optional*): Air temperature in Celsius. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. + - **humidity** (*Optional*): Relative air humidity in %. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. + - **moisture** (*Optional*): Soil moisture in %. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. + - **battery_voltage** (*Optional*): Battery voltage in volts. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. + - **illuminance** (*Optional*): Illuminance in lux. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. See Also -------- diff --git a/components/sensor/bh1750.rst b/components/sensor/bh1750.rst index b571bef6ed..ab2eb8399e 100644 --- a/components/sensor/bh1750.rst +++ b/components/sensor/bh1750.rst @@ -35,14 +35,11 @@ your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the sensor. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x23`` (address if address pin is pulled low). If the address pin is pulled high, the address is ``0x5C``. - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/binary_sensor_map.rst b/components/sensor/binary_sensor_map.rst index e23d0a0144..132800a45f 100644 --- a/components/sensor/binary_sensor_map.rst +++ b/components/sensor/binary_sensor_map.rst @@ -121,7 +121,6 @@ The maximum amount of observations/channels supported is 64. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **type** (**Required**, string): The sensor type. Should be one of: ``BAYESIAN``, ``GROUP``, or ``SUM``. - **channels** (**Required for GROUP or SUM types**): A list of channels that are mapped to certain values. diff --git a/components/sensor/ble_client.rst b/components/sensor/ble_client.rst index 469c810992..963cfefd35 100644 --- a/components/sensor/ble_client.rst +++ b/components/sensor/ble_client.rst @@ -13,7 +13,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -23,7 +23,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black sensor: diff --git a/components/sensor/ble_rssi.rst b/components/sensor/ble_rssi.rst index d169f49f5c..56ebe944b2 100644 --- a/components/sensor/ble_rssi.rst +++ b/components/sensor/ble_rssi.rst @@ -13,7 +13,7 @@ instructions for setting up this platform. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -26,7 +26,7 @@ instructions for setting up this platform. sensor: # RSSI based on MAC address - platform: ble_rssi - mac_address: AC:37:43:77:5F:4C + mac_address: XX:XX:XX:XX:XX:XX name: "BLE Google Home Mini RSSI value" # RSSI based on Identity Resolving Key (IRK) - platform: ble_rssi @@ -49,7 +49,6 @@ instructions for setting up this platform. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **mac_address** (*Optional*, MAC Address): The MAC address to track for this sensor. Note that exactly one of ``mac_address``, ``irk``, ``service_uuid`` or ``ibeacon_uuid`` must be present. @@ -67,7 +66,6 @@ Configuration variables: same building. - **ibeacon_minor** (*Optional*, int): The iBeacon minor identifier of the beacon that needs to be tracked. Usually used to identify beacons within an iBeacon group. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/bme680.rst b/components/sensor/bme680.rst index b8e5815146..5aaf05a1f2 100644 --- a/components/sensor/bme680.rst +++ b/components/sensor/bme680.rst @@ -41,33 +41,25 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`bme680-oversampling`. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`bme680-oversampling`. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`bme680-oversampling`. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **gas_resistance** (*Optional*): The information for the gas sensor. - - **name** (**Required**, string): The name for the gas resistance sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x76``. Another address can be ``0x77``. @@ -132,7 +124,7 @@ Add indoor air quality (IAQ) calculation and IAQ label, based on the values in t name: "BME680 Indoor Air Quality" id: iaq icon: "mdi:gauge" - # calculation: comp_gas = log(R_gas[ohm]) + 0.04 log(Ohm)/%rh * hum[%rh] + # calculation: comp_gas = log(R_gas[ohm]) + 0.04 log(Ohm)/%rh * hum[%rh] lambda: |- return log(id(gas_resistance).state) + 0.04 * id(humidity).state; state_class: "measurement" diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst index 2b3e0780b5..7dec310141 100644 --- a/components/sensor/bme680_bsec.rst +++ b/components/sensor/bme680_bsec.rst @@ -18,9 +18,11 @@ for CO₂ and Breath Volatile Organic Compounds (b-VOC) using a correlation betw .. note:: - The BSEC library is only available for use after accepting its software license agreement. By enabling this component, - you are explicitly agreeing to the terms of the `BSEC license agreement`_. You must not distribute any compiled firmware - binaries that include this component. + - The BSEC library is only available for use after accepting its software license agreement. By enabling this component, + you are explicitly agreeing to the terms of the `BSEC license agreement`_. You must not distribute any compiled firmware + binaries that include this component. + + - We recommend using the newer :doc:`bme68x_bsec2 ` component whenever possible. The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. @@ -125,54 +127,38 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **gas_resistance** (*Optional*): The information for the gas sensor. - - **name** (**Required**, string): The name for the gas resistance sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **iaq** (*Optional*): The information for the IAQ sensor. - - **name** (**Required**, string): The name for the IAQ sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **iaq_accuracy** (*Optional*): The information for the numeric IAQ accuracy sensor. - - **name** (**Required**, string): The name for the IAQ accuracy sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **co2_equivalent** (*Optional*): The information for the CO₂ equivalent sensor. - - **name** (**Required**, string): The name for the CO₂ equivalent sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **breath_voc_equivalent** (*Optional*): The information for the Breath VOC equivalent humidity sensor. - - **name** (**Required**, string): The name for the Breath VOC equivalent sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Text Sensor ----------- @@ -186,9 +172,7 @@ Configuration variables: - **iaq_accuracy** (*Optional*): The information for the IAQ accuracy sensor. Shows: Stabilizing, Uncertain, Calibrating, Calibrated. - - **name** (**Required**, string): The name for the IAQ accuracy sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`TextSensor `. + - All options from :ref:`TextSensor `. .. figure:: images/bme680-bsec-ui.png :align: center diff --git a/components/sensor/bme68x_bsec2.rst b/components/sensor/bme68x_bsec2.rst new file mode 100644 index 0000000000..6b51359142 --- /dev/null +++ b/components/sensor/bme68x_bsec2.rst @@ -0,0 +1,285 @@ +BME68x Temperature, Humidity, Pressure & Gas Sensor via BSEC2 +============================================================= + +.. seo:: + :description: Instructions for setting up BME68x temperature, humidity, pressure, and gas sensors via BSEC2. + :image: bme680.jpg + :keywords: BME680, BME688, BME68X, BSEC2 + +Component/Hub +------------- + +The ``bme68x_bsec2_i2c`` sensor platform allows you to use your +`BME680 `__ and +`BME688 `__ +(`Adafruit`_, `Pimoroni`_) temperature, humidity, pressure and gas sensors with ESPHome via the Bosch Sensortec +Environmental Cluster 2 (BSEC2) software library. The use of Bosch's proprietary algorithms provide an Index for Air +Quality (IAQ) measurement derived from the gas resistance sensor's response to specific Volatile Organic Compounds +(VOCs). The BSEC software also provides estimated values for CO₂ and Breath Volatile Organic Compounds (b-VOC) using +a correlation between VOC and CO₂ in a human's exhaled breath. + +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. _BSEC license agreement: https://www.bosch-sensortec.com/media/boschsensortec/downloads/software/bme688_development_software/2023_04/license_terms_bme688_bme680_bsec.pdf + +.. _Adafruit: https://www.adafruit.com/product/3660 + +.. _Pimoroni: https://shop.pimoroni.com/products/bme680-breakout + +.. note:: + + The BSEC2 library is only available for use after accepting its software license agreement. By enabling this + component in your configuration, you are explicitly agreeing to the terms of the `BSEC license agreement`_. Note + that the license forbids distribution of any compiled firmware binaries that include this component. + +.. figure:: images/bme680-full.jpg + :align: center + :width: 50.0% + + BME680 Temperature, Pressure, Humidity & Gas Sensor. + +.. figure:: images/bme680-bsec-ui.png + :align: center + :width: 80.0% + + Example UI + +.. code-block:: yaml + + # Minimal example configuration with common sensors + bme68x_bsec2_i2c: + address: 0x76 + model: bme680 + operating_age: 28d + sample_rate: LP + voltage: 3.3V + + + +Configuration variables: +^^^^^^^^^^^^^^^^^^^^^^^^ + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x76``. The sensor can + also be configured to use ``0x77``. +- **model** (*Optional*, string): The model of the connected sensor; either ``BME680`` or ``BME688``. +- **algorithm_output** (*Optional*, string): The output of the BSEC2 algorithm. Either ``classification`` (default) or + ``regression``. *Only valid when model is BME688.* +- **operating_age** (*Optional*, string): The history BSEC2 considers for the automatic background calibration of the + IAQ in days. That means changes in this time period will influence the IAQ value. Either ``4d`` or ``28d``. +- **sample_rate** (*Optional*, string): Sample rate. Default is ``LP`` for low power consumption, sampling every 3 + seconds. Can be ``ULP`` for ultra-low power, sampling every 5 minutes. This controls the sampling rate for + gas-dependent sensors and will govern the interval at which the sensor heater is operated. By default, this rate will + also be used for temperature, humidity and pressure sensors but can be overridden per-sensor if required. +- **supply_voltage** (*Optional*, string): Supply voltage of the sensor. Default is ``3.3V``. Can be set to ``1.8V`` if + your sensor is powerd with 1.8 volts (for example, the Pimoroni PIM357 BME680 breakout module). +- **temperature_offset** (*Optional*, float): Temperature offset if device is in enclosure and reads too high. This + value is subtracted from the reading (for example, if the sensor reads 5°C higher than expected, set this to ``5``) + and also corrects the relative humidity readings. Defaults to ``0``. +- **state_save_interval** (*Optional*, :ref:`config-time`): The minimum interval at which to save the calibrated BSEC2 + algorithm state to flash so that calibration doesn't have to start from scratch on device restart. Defaults to ``6h``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this ID in the sensor + section to refer to the correct BME68x sensor if you have more than one device. This will also be used to refer to + the calibrated BSEC2 algorithm state saved to flash. + +Sensor +------ + +.. code-block:: yaml + + sensor: + - platform: bme68x_bsec2 + temperature: + name: "BME68x Temperature" + pressure: + name: "BME68x Pressure" + humidity: + name: "BME68x Humidity" + iaq: + name: "BME68x IAQ" + id: iaq + co2_equivalent: + name: "BME68x CO2 Equivalent" + breath_voc_equivalent: + name: "BME68x Breath VOC Equivalent" + +Configuration variables: +^^^^^^^^^^^^^^^^^^^^^^^^ + +- **bme68x_bsec2_id** (*Optional*, :ref:`config-id`): The ID of the ``bme68x_bsec2_i2c`` component sensors will refer + to. Useful when multiple devices are present in your configuration. + +- **temperature** (*Optional*): Configuration for the temperature sensor. + + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``LP`` for low power + consumption, sampling every 3 seconds or ``ULP`` for ultra-low power, sampling every 5 minutes. + - All other options from :ref:`Sensor `. + +- **pressure** (*Optional*): Configuration for the pressure sensor. + + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``LP`` for low power + consumption, sampling every 3 seconds or ``ULP`` for ultra-low power, sampling every 5 minutes. + - All other options from :ref:`Sensor `. + +- **humidity** (*Optional*): Configuration for the humidity sensor. + + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``LP`` for low power + consumption, sampling every 3 seconds or ``ULP`` for ultra-low power, sampling every 5 minutes. + - All other options from :ref:`Sensor `. + +- **gas_resistance** (*Optional*): Configuration for the gas sensor. + + - All options from :ref:`Sensor `. + +- **iaq** (*Optional*): Configuration for the IAQ sensor. + + - All options from :ref:`Sensor `. + +- **iaq_static** (*Optional*): Configuration for the IAQ static sensor. + + - All options from :ref:`Sensor `. + +- **iaq_accuracy** (*Optional*): Configuration for the numeric IAQ accuracy sensor. + + - All options from :ref:`Sensor `. + +- **co2_equivalent** (*Optional*): Configuration for the CO₂ equivalent sensor. + + - All options from :ref:`Sensor `. + +- **breath_voc_equivalent** (*Optional*): Configuration for the Breath VOC equivalent humidity sensor. + + - All options from :ref:`Sensor `. + +Text Sensor +----------- + +The sensor's accuracy can be reported in text format. + +.. code-block:: yaml + + text_sensor: + - platform: bme68x_bsec2 + iaq_accuracy: + name: "BME68x IAQ Accuracy" + +Configuration variables: +^^^^^^^^^^^^^^^^^^^^^^^^ + +- **bme68x_bsec2_id** (*Optional*, :ref:`config-id`): The ID of the ``bme68x_bsec2_i2c`` component the text sensor + will refer to. Useful when multiple devices are present in your configuration. +- **iaq_accuracy** (*Optional*): Configuration for the IAQ accuracy sensor. Shows: ``Stabilizing``, ``Uncertain``, + ``Calibrating``, ``Calibrated``. + + - All other options from :ref:`Text Sensor `. + +Index for Air Quality (IAQ) Measurement +--------------------------------------- + +The measurements are expressed with an index scale ranging from 0 to 500. The index itself is deduced from tests using +ethanol gas, as well as important VOC in the exhaled breath of healthy humans. The VOC values themselves are derived +from several publications on breath analysis studies. The BSEC2 software library defines the levels as follows: + ++-----------+---------------------+ +| IAQ Index | Air Quality | ++===========+=====================+ +| 0 - 50 | Excellent | ++-----------+---------------------+ +| 51 - 100 | Good | ++-----------+---------------------+ +| 101 - 150 | Lightly polluted | ++-----------+---------------------+ +| 151 - 200 | Moderately polluted | ++-----------+---------------------+ +| 201 - 250 | Heavily polluted | ++-----------+---------------------+ +| 251 - 350 | Severely polluted | ++-----------+---------------------+ +| > 351 | Extremely polluted | ++-----------+---------------------+ + +This can be represented by a template text sensor such as below + +.. code-block:: yaml + + text_sensor: + - platform: template + name: "BME68x IAQ Classification" + lambda: |- + if ( int(id(iaq).state) <= 50) { + return {"Excellent"}; + } + else if (int(id(iaq).state) >= 51 && int(id(iaq).state) <= 100) { + return {"Good"}; + } + else if (int(id(iaq).state) >= 101 && int(id(iaq).state) <= 150) { + return {"Lightly polluted"}; + } + else if (int(id(iaq).state) >= 151 && int(id(iaq).state) <= 200) { + return {"Moderately polluted"}; + } + else if (int(id(iaq).state) >= 201 && int(id(iaq).state) <= 250) { + return {"Heavily polluted"}; + } + else if (int(id(iaq).state) >= 251 && int(id(iaq).state) <= 350) { + return {"Severely polluted"}; + } + else if (int(id(iaq).state) >= 351) { + return {"Extremely polluted"}; + } + else { + return {"error"}; + } + +The selected b-VOC gasses are as follows: + ++--------------------+----------------+ +| Compound | Molar fraction | ++====================+================+ +| `Ethane`_ | 5 ppm | ++--------------------+----------------+ +| `Isoprene`_ | 10 ppm | ++--------------------+----------------+ +| `Ethanol`_ | 10 ppm | ++--------------------+----------------+ +| `Acetone`_ | 50 ppm | ++--------------------+----------------+ +| `Carbon Monoxide`_ | 15 ppm | ++--------------------+----------------+ + +.. _Ethane: https://en.wikipedia.org/wiki/Ethane +.. _Isoprene: https://en.wikipedia.org/wiki/Isoprene +.. _Ethanol: https://en.wikipedia.org/wiki/Ethanol +.. _Acetone: https://en.wikipedia.org/wiki/Acetone +.. _Carbon Monoxide: https://en.wikipedia.org/wiki/Carbon_monoxide + +.. _bsec2-calibration: + +IAQ Accuracy and Calibration +---------------------------- + +The BSEC2 software automatically calibrates in the background to provide consistent IAQ performance. The calibration +process considers the recent measurement history so that a value of 50 corresponds to a “typical good” level and a +value of 200 to a “typical polluted” level. The IAQ Accuracy sensor will indicate one of the following values: + +- ``Stabilizing``: The device has just started, and the sensor is stabilizing (this typically lasts 5 minutes) +- ``Uncertain``: The background history of BSEC2 is uncertain. This typically means the gas sensor data was too stable + for BSEC2 to clearly define its reference. +- ``Calibrating``: BSEC2 found new calibration data and is currently calibrating. +- ``Calibrated``: BSEC2 calibrated successfully. + +Every ``state_save_interval``, or as soon thereafter when full calibration is reached, the current algorithm state is +saved to flash so that the process does not have to start from scratch on device restart. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`absolute_humidity` +- :doc:`bme680` +- :apiref:`bme68x_bsec2_i2c/bme68x_bsec2_i2c.h` +- `BME680 datasheet `__ +- `BME688 datasheet `__ +- `BME680 VOC classification `__ +- `Bosch BSEC2 Library `__ by `Bosch Sensortec `__ +- `Bosch Sensortec Community `__ +- :ghedit:`Edit` diff --git a/components/sensor/bmp085.rst b/components/sensor/bmp085.rst index 3f3c6d82a3..f8402f7370 100644 --- a/components/sensor/bmp085.rst +++ b/components/sensor/bmp085.rst @@ -40,16 +40,11 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature - sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x77``. diff --git a/components/sensor/bmp280.rst b/components/sensor/bmp280.rst index 87337481c0..ff0c6abbc5 100644 --- a/components/sensor/bmp280.rst +++ b/components/sensor/bmp280.rst @@ -38,19 +38,14 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature. sensor - - **name** (**Required**, string): The name for the temperature - sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`Oversampling Options `. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. + - **oversampling** (*Optional*): The oversampling parameter for the pressure sensor. See :ref:`Oversampling Options `. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of diff --git a/components/sensor/ccs811.rst b/components/sensor/ccs811.rst index 95b4bde42b..2eb08eab9e 100644 --- a/components/sensor/ccs811.rst +++ b/components/sensor/ccs811.rst @@ -10,10 +10,10 @@ The ``ccs811`` sensor platform allows you to use CCS811 eCO_2 and volatile organ .. note:: - Most CCS811 modules require the WAK pin to be pulled low to wake up the sensor, as outlined in the data sheets. - Outside low-power scenarios, connecting WAK to ground is the recommended configuration. For low power installations, + Most CCS811 modules require the WAK pin to be pulled low to wake up the sensor, as outlined in the data sheets. + Outside low-power scenarios, connecting WAK to ground is the recommended configuration. For low power installations, pulling WAK low should happen in software prior to taking the measures. - + .. figure:: images/ccs811-full.jpg :align: center :width: 50.0% @@ -46,23 +46,19 @@ Configuration variables: - **eco2** (**Required**): The eCO_2 data from the sensor in parts per million (ppm). - - **name** (**Required**, string): The name for the CO_2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **tvoc** (**Required**): The information for the total volatile organic compound sensor in parts per billion (ppb). - - **name** (**Required**, string): The name for the tvoc sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **version** (*Optional*): This sensor reports the firmware ('application') version in text, with the internal hex representation of the version number behind it, so version 1.0.0 will be reported as '1.0.0 (0x1000)'. - - **name** (**Required**, string): The name for the version sensor. + - All options from :ref:`Text Sensor `. Advanced: diff --git a/components/sensor/ct_clamp.rst b/components/sensor/ct_clamp.rst index 27f9e5eb19..c21a3921c9 100644 --- a/components/sensor/ct_clamp.rst +++ b/components/sensor/ct_clamp.rst @@ -35,13 +35,11 @@ as an introduction to the working principle of CT clamp sensors and how to hook Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **sensor** (**Required**, :ref:`config-id`): The source sensor to measure voltage values from. - **sample_duration** (*Optional*, :ref:`config-time`): The time duration to sample the current clamp with. Higher values can increase accuracy. Defaults to ``200ms`` which would be 10 whole cycles on a 50Hz system. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. The **update_interval** for ``ct_clamp`` has to be greater than **sample_duration**. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. Calibration diff --git a/components/sensor/dallas_temp.rst b/components/sensor/dallas_temp.rst index 00337cfdd4..19e8f3b2ed 100644 --- a/components/sensor/dallas_temp.rst +++ b/components/sensor/dallas_temp.rst @@ -19,6 +19,7 @@ required to be set up in your configuration for this sensor to work. - platform: dallas_temp address: 0x1234567812345628 name: temperature + update_interval: 120s Configuration variables: ************************ diff --git a/components/sensor/dht.rst b/components/sensor/dht.rst index f8943d6c08..2b16241ebd 100644 --- a/components/sensor/dht.rst +++ b/components/sensor/dht.rst @@ -51,15 +51,11 @@ Configuration variables: - **pin** (**Required**, :ref:`config-pin`): The pin where the DHT bus is connected. - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **model** (*Optional*, int): Manually specify the DHT model, can be diff --git a/components/sensor/dht12.rst b/components/sensor/dht12.rst index 0588bbcf29..53afa28cff 100644 --- a/components/sensor/dht12.rst +++ b/components/sensor/dht12.rst @@ -38,15 +38,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/dps310.rst b/components/sensor/dps310.rst index 4cd5f5baaf..8130925faf 100644 --- a/components/sensor/dps310.rst +++ b/components/sensor/dps310.rst @@ -33,17 +33,12 @@ Configuration variables: - **pressure** (**Required**): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (**Required**): The information for the temperature. sensor - - **name** (**Required**, string): The name for the temperature - sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x77``. diff --git a/components/sensor/dsmr.rst b/components/sensor/dsmr.rst index 0181270e07..4d5fb1fc2f 100644 --- a/components/sensor/dsmr.rst +++ b/components/sensor/dsmr.rst @@ -71,205 +71,139 @@ Configuration variables: - **energy_delivered_tariff1** (*Optional*): Energy Consumed Tariff 1. - - **name** (**Required**, string): The name for the energy_delivered_tariff1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **energy_delivered_tariff2** (*Optional*): Energy Consumed Tariff 2. - - **name** (**Required**, string): The name for the energy_delivered_tariff2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **energy_returned_tariff1** (*Optional*): Energy Produced Tariff 1. - - **name** (**Required**, string): The name for the energy_returned_tariff1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **energy_returned_tariff2** (*Optional*): Energy Produced Tariff 2. - - **name** (**Required**, string): The name for the energy_returned_tariff2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_delivered** (*Optional*): Power Consumed. - - **name** (**Required**, string): The name for the power_delivered sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_returned** (*Optional*): Power Produced. - - **name** (**Required**, string): The name for the power_returned sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_failures** (*Optional*): Electricity Failures. - - **name** (**Required**, string): The name for the electricity_failures sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_long_failures** (*Optional*): Long Electricity Failures. - - **name** (**Required**, string): The name for the electricity_long_failures sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_sags_l1** (*Optional*): Number of voltage sags in phase L1. - - **name** (**Required**, string): The name for the electricity_sags_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_sags_l2** (*Optional*): Number of voltage sags in phase L2. - - **name** (**Required**, string): The name for the electricity_sags_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_sags_l3** (*Optional*): Number of voltage sags in phase L3. - - **name** (**Required**, string): The name for the electricity_sags_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_swells_l1** (*Optional*): Number of voltage swells in phase L1. - - **name** (**Required**, string): The name for the electricity_swells_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_swells_l2** (*Optional*): Number of voltage swells in phase L2. - - **name** (**Required**, string): The name for the electricity_swells_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **electricity_swells_l3** (*Optional*): Number of voltage swells in phase L3. - - **name** (**Required**, string): The name for the electricity_swells_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **voltage_l1** (*Optional*): Voltage Phase 1. - - **name** (**Required**, string): The name for the voltage_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **voltage_l2** (*Optional*): Voltage Phase 2. - - **name** (**Required**, string): The name for the voltage_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **voltage_l3** (*Optional*): Voltage Phase 3. - - **name** (**Required**, string): The name for the voltage_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **current_l1** (*Optional*): Current Phase 1. - - **name** (**Required**, string): The name for the current_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **current_l2** (*Optional*): Current Phase 2. - - **name** (**Required**, string): The name for the current_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **current_l3** (*Optional*): Current Phase 3. - - **name** (**Required**, string): The name for the current_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_delivered_l1** (*Optional*): Power Consumed Phase 1. - - **name** (**Required**, string): The name for the power_delivered_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_delivered_l2** (*Optional*): Power Consumed Phase 2. - - **name** (**Required**, string): The name for the power_delivered_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_delivered_l3** (*Optional*): Power Consumed Phase 3. - - **name** (**Required**, string): The name for the power_delivered_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_returned_l1** (*Optional*): Power Produced Phase 1. - - **name** (**Required**, string): The name for the power_returned_l1 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_returned_l2** (*Optional*): Power Produced Phase 2. - - **name** (**Required**, string): The name for the power_returned_l2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power_returned_l3** (*Optional*): Power Produced Phase 3. - - **name** (**Required**, string): The name for the power_returned_l3 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **gas_delivered** (*Optional*): Gas Consumed. - - **name** (**Required**, string): The name for the gas_delivered sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Belgium - **gas_delivered_be** (*Optional*): Gas Consumed Belgium. - - **name** (**Required**, string): The name for the gas_delivered_be sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **active_energy_import_current_average_demand** (*Optional*): Current Average Quarterly Demand for Peak Tarrif Belgium. - - **name** (**Required**, string): The name for the active_energy_import_current_average_demand sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **active_energy_import_maximum_demand_running_month** (*Optional*): Current Month's Maximum Quarterly Demand for Peak Tarrif Belgium. - - **name** (**Required**, string): The name for the active_energy_import_maximum_demand_running_month sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **active_energy_import_maximum_demand_last_13_months** (*Optional*): 13 Month Maximum Quarterly Demand for Peak Tarrif Belgium. - - **name** (**Required**, string): The name for the active_energy_import_maximum_demand_last_13_months sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Luxembourg - **energy_delivered_lux** (*Optional*): Energy Consumed Luxembourg - - **name** (**Required**, string): The name for the energy_delivered_lux sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **energy_returned_lux** (*Optional*): Energy Produced Luxembourg - - **name** (**Required**, string): The name for the energy_returned_lux sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Text Sensor ----------- @@ -278,79 +212,55 @@ Configuration variables: - **identification** (*Optional*): DSMR Identification - - **name** (**Required**, string): The name for the identification text sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **p1_version** (*Optional*): DSMR Version - - **name** (**Required**, string): The name for the p1_version text sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **timestamp** (*Optional*): Timestamp - - **name** (**Required**, string): The name for the timestamp sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **electricity_tariff** (*Optional*): The current tariff. According to the specs value '0001' means 'normal tariff' and value '0002' means 'low tariff'. Your meter may report differently. - - **name** (**Required**, string): The name for the electricity_tariff sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **electricity_failure_log** (*Optional*): Electricity Failure Log - - **name** (**Required**, string): The name for the electricity_failure_log sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **message_short** (*Optional*): Message Short - - **name** (**Required**, string): The name for the message_short sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **message_long** (*Optional*): Message Long - - **name** (**Required**, string): The name for the message_long sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **gas_equipment_id** (*Optional*): Gas Equipment ID. - - **name** (**Required**, string): The name for the gas_equipment_id sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **water_equipment_id** (*Optional*): Water Equipment ID - - **name** (**Required**, string): The name for the water_equipment_id sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **sub_equipment_id** (*Optional*): Sub Equipment ID - - **name** (**Required**, string): The name for the sub_equipment_id sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. - **gas_delivered_text** (*Optional*): A text sensor which unformatted gas data. You need to apply a custom parsing of this value depending on your meter format. - - **name** (**Required**, string): The name for the p1_version text sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. Belgium - **p1_version_be** (*Optional*): DSMR Version Belgium - - **name** (**Required**, string): The name for the p1_version_be text sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Text Sensor `. + - All options from :ref:`Text Sensor `. Older DSMR meters support ------------------------- diff --git a/components/sensor/duty_time.rst b/components/sensor/duty_time.rst index 6273c87df0..0efa5ba52e 100644 --- a/components/sensor/duty_time.rst +++ b/components/sensor/duty_time.rst @@ -2,13 +2,13 @@ Duty Time ========= .. seo:: - :description: Instructions for setting up a sensor that tracks the duty time of the some object. + :description: Instructions for setting up a sensor that tracks the duty time of some object. :image: timer-play-outline.svg -The ``duty_time`` sensor allows you to track the total duty time of the some object, for example, a light bulb, in seconds. +The ``duty_time`` sensor allows you to track the total duty time of some object, for example, a light bulb, in seconds. Able to calculate the last turn-on time when an optional sensor ``last_time`` is included in the configuration. -Supports boolean signal sources: ``binary_sensor`` or ``lambda`` that returns a boolean state of tracked object. +Supports boolean signal sources: ``binary_sensor`` or ``lambda`` that returns a boolean state of the tracked object. As an alternative to controlling a component in automations, may be used the ``sensor.duty_time.start`` and ``sensor.duty_time.stop`` actions. diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst index dfb5f2b7dd..ebad7741d5 100644 --- a/components/sensor/ee895.rst +++ b/components/sensor/ee895.rst @@ -38,21 +38,15 @@ Configuration variables: - **temperature** (**Required**): The information for the Temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **co2** (**Required**): The information for the CO₂ sensor. - - **name** (**Required**, string): The name for the CO₂eq sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pressure** (**Required**): The information for the Pressure sensor. - - **name** (**Required**, string): The name for the Pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x5F``. diff --git a/components/sensor/ens160.rst b/components/sensor/ens160.rst index bbc5ac08fb..4693123cdf 100644 --- a/components/sensor/ens160.rst +++ b/components/sensor/ens160.rst @@ -6,15 +6,15 @@ ENS160 Sensor :keywords: ENS160 The ``ens160`` sensor platform allows you to use your ENS160 -(`datasheet `__) air-quality sensors with ESPHome. +(`datasheet `__) air-quality sensors with ESPHome. The :ref:`I²C ` or :ref:`SPI ` is required to be set up in your configuration for this sensor to work. .. note:: On first power-up of the ENS160 sensor, there is a 1 hour initial startup delay before readings will be available. - For subsequent starts or reboots, there is a 3 minute warm up period before readings are available. Also, be aware that the + For subsequent starts or reboots, there is a 3 minute warm up period before readings are available. Also, be aware that the ENS160 can take up to 1 second for sucessive data measurements to be ready. - + .. figure:: images/ens160.jpg :align: center :width: 80.0% @@ -33,7 +33,7 @@ The :ref:`I²C ` or :ref:`SPI ` is required to be set up in your confi aqi: id: ens160_air_quality_index name: "ENS160 Air Quality Index" - update_interval: 60s + update_interval: 60s address: 0x53 compensation: temperature: id_temperature_sensor @@ -48,7 +48,7 @@ The :ref:`I²C ` or :ref:`SPI ` is required to be set up in your confi name: "ENS160 Total Volatile Organic Compounds" aqi: name: "ENS160 Air Quality Index" - update_interval: 60s + update_interval: 60s cs_pin: GPIO5 compensation: temperature: id_temperature_sensor @@ -60,48 +60,42 @@ Configuration variables: - **eco2** (**Required**): Configuration for the eCO2 sensor. - - **name** (**Required**, string): The name for the eCO2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **tvoc** (**Required**): Configuration for the TVOC sensor. - - **name** (**Required**, string): The name for the TVOC sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **aqi** (*Optional*): Configuration for the air quality index sensor. - - **name** (**Required**, string): The name for the AQI sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. The update interval should be greater than the measurement frequency of the ENS160 which is up to 1 second. - **address** (*Optional*, int): *I²C only.* Manually specify the I²C address of - the sensor. Defaults to ``0x53``. Another address can be ``0x52``. + the sensor. Defaults to ``0x52``. Another address can be ``0x53``. - **cs_pin** (*Required*, :ref:`Pin Schema `): *SPI only.* The Chip Select pin. Advanced: -- **compensation** (*Optional*): The block containing sensors used for compensation. +- **compensation** (*Optional*): The block containing sensors used for compensation. Temperature and humidity compensation improves the accuracy of sensor readings. Without compensation, the ENS160 internally assumes 25°C temperature and 50% humidity, with readings noticeably diverting from real changes without compensation in temperature and humidity. - + - **temperature** (**Required**, :ref:`config-id`): The ID of an external temperature sensor. - **humidity** (**Required**, :ref:`config-id`): The ID of an external humidity sensor. - + Example Text Sensor configuration --------------------------------- The Air Quality Index(AQI) from this sensor is a number between 1 and 5. The ENS160 (`datasheet `__) states that "The AQI-UBA air quality index is derived from a guideline by the German Federal Environmental -Agency based on a TVOC sum signal". The following is an example configuration to convert the numeric ENS160 AQI to the rating text. +Agency based on a TVOC sum signal". The following is an example configuration to convert the numeric ENS160 AQI to the rating text. .. code-block:: yaml @@ -114,7 +108,7 @@ Agency based on a TVOC sum signal". The following is an example configuration to case 2: return {"Good"}; case 3: return {"Moderate"}; case 4: return {"Poor"}; - case 5: return {"Unhealthy"}; + case 5: return {"Unhealthy"}; default: return {"Not Available"}; } diff --git a/components/sensor/ens210.rst b/components/sensor/ens210.rst index 782af1510b..3503a56510 100644 --- a/components/sensor/ens210.rst +++ b/components/sensor/ens210.rst @@ -35,15 +35,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/esp32_hall.rst b/components/sensor/esp32_hall.rst index 436b8610a0..5d2168c6ec 100644 --- a/components/sensor/esp32_hall.rst +++ b/components/sensor/esp32_hall.rst @@ -11,6 +11,12 @@ The ``esp32_hall`` sensor platform allows you to use the integrated ESP32 chip to measure the magnitude and direction of magnetic field around the chip (with quite poor accuracy). +.. warning:: + + Espressif has `removed support `__ + for the ESP32's Hall sensor in IDF 5; for this reason, support for this component is + likely to be removed in a future release. + Please make sure that nothing is connected to pins ``GPIO36`` and ``GPIO39`` if this component is enabled, as those pins are used for the internal low-noise amplifier used by the hall sensor. @@ -30,10 +36,8 @@ by the hall sensor. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the hall effect sensor. - **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. - All other options from :ref:`Sensor `. .. warning:: diff --git a/components/sensor/ezo.rst b/components/sensor/ezo.rst index 515bb8c961..41508e2fa2 100644 --- a/components/sensor/ezo.rst +++ b/components/sensor/ezo.rst @@ -42,7 +42,6 @@ Configuration variables: - **address** (**Required**, int): Specify the I²C address of the sensor. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. Automation triggers: diff --git a/components/sensor/hdc1080.rst b/components/sensor/hdc1080.rst index 19bc5a7fdf..b4cd76b652 100644 --- a/components/sensor/hdc1080.rst +++ b/components/sensor/hdc1080.rst @@ -41,15 +41,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/hm3301.rst b/components/sensor/hm3301.rst index d6f71e7f59..ac73b956b7 100644 --- a/components/sensor/hm3301.rst +++ b/components/sensor/hm3301.rst @@ -33,27 +33,19 @@ Configuration variables: - **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **aqi** (*Optional*): AQI sensor. Requires the ``pm_2_5`` and ``pm_10_0`` sensors defined. See below. - **calculation_type** (**Required**): One of: ``AQI`` or ``CAQI``. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. Air Quality Sensor: diff --git a/components/sensor/homeassistant.rst b/components/sensor/homeassistant.rst index b8d0ea0e94..631615702b 100644 --- a/components/sensor/homeassistant.rst +++ b/components/sensor/homeassistant.rst @@ -39,11 +39,9 @@ Entity state attributes can also be imported: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **entity_id** (**Required**, string): The entity ID to import from Home Assistant. - **attribute** (*Optional*, string): The name of the state attribute to import from the specified entity. The entity state is used when this option is omitted. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. diff --git a/components/sensor/honeywellabp.rst b/components/sensor/honeywellabp.rst index d85582e9a8..5da92211a7 100644 --- a/components/sensor/honeywellabp.rst +++ b/components/sensor/honeywellabp.rst @@ -49,9 +49,7 @@ datasheet indicates that the sensor does not measure temperature. - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **cs_pin** (**Required**, :ref:`SPI `): Chip select pin. diff --git a/components/sensor/hte501.rst b/components/sensor/hte501.rst index 4e052de0ea..27c16778cd 100644 --- a/components/sensor/hte501.rst +++ b/components/sensor/hte501.rst @@ -33,15 +33,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x40``. diff --git a/components/sensor/hx711.rst b/components/sensor/hx711.rst index 8855113a65..8555b7545f 100644 --- a/components/sensor/hx711.rst +++ b/components/sensor/hx711.rst @@ -36,7 +36,6 @@ and ``CLK`` (or ``SCK``) to free GPIO pins. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the load cell sensor. - **dout_pin** (**Required**, :ref:`Pin Schema `): The DOUT (or DAT) pin. - **clk_pin** (**Required**, :ref:`Pin Schema `): The CLK pin. - **gain** (*Optional*, enum): The gain. Implicitly selects the channel. Defaults to ``128``. @@ -47,7 +46,6 @@ Configuration variables: - **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. - All other options from :ref:`Sensor `. diff --git a/components/sensor/hydreon_rgxx.rst b/components/sensor/hydreon_rgxx.rst index 04e08c06d9..04a919b803 100644 --- a/components/sensor/hydreon_rgxx.rst +++ b/components/sensor/hydreon_rgxx.rst @@ -74,42 +74,30 @@ Configuration variables: - **moisture** (*Optional*): Rain intensity level from 0-7 (`more detail `__). Only on RG-9. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): Device internal temperature in Celsius. Accuracy is ±5°C. Only on RG-9 firmware version 1.100-onwards. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **resolution** (*Optional*, string): Specify rain sensor resolution. Must be either ``low`` or ``high``. Default resolution is ``high``. Only applies to RG-15. - **acc** (*Optional*): Amount of rain since last message (see ``update_interval``), in ``mm``. Only on RG-15. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **event_acc** (*Optional*): Amount of rain for this event (i.e. since it last stopped raining), in ``mm``. Only on RG-15. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **total_acc** (*Optional*): Total amount of rain this sensor has ever measured, in ``mm``. Only on RG-15. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **r_int** (*Optional*): Current rain intensity in ``mm/h``. Only on RG-15. - - **name** (**Required**, string): The name for the sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/hyt271.rst b/components/sensor/hyt271.rst index 658b66f830..84693eeefc 100644 --- a/components/sensor/hyt271.rst +++ b/components/sensor/hyt271.rst @@ -6,7 +6,7 @@ HYT271 Temperature & Humidity Sensor :image: hyt271.jpg :keywords: HYT271 -The HYT271 Temperature & Humidity sensors with ESPHome. +The HYT271 Temperature & Humidity sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. Example sensors: @@ -27,15 +27,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/images/apds9306.png b/components/sensor/images/apds9306.png new file mode 100644 index 0000000000..521acbfc8b Binary files /dev/null and b/components/sensor/images/apds9306.png differ diff --git a/components/sensor/images/m5stack_8angle.jpg b/components/sensor/images/m5stack_8angle.jpg new file mode 100644 index 0000000000..20b444cb49 Binary files /dev/null and b/components/sensor/images/m5stack_8angle.jpg differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 4d5ca3b605..177b952852 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -296,6 +296,27 @@ Rounds the value to the given decimal places. - round: 1 # will round to 1 decimal place + +``round_to_multiple_of`` +************************ + +Rounds the value to the nearest multiple. Takes a float greater than zero. + +.. code-block:: yaml + + - platform: ... + filters: + - round_to_multiple_of: 10 + # 123 -> 120 + # 126 -> 130 + + - platform: ... + filters: + - round_to_multiple_of: 0.25 + # 3.1415 -> 3.25 + # 1.6180 -> 1.5 + + ``quantile`` ************ diff --git a/components/sensor/inkbird_ibsth1_mini.rst b/components/sensor/inkbird_ibsth1_mini.rst index 530fc4e5a3..ac18f2e859 100644 --- a/components/sensor/inkbird_ibsth1_mini.rst +++ b/components/sensor/inkbird_ibsth1_mini.rst @@ -38,7 +38,7 @@ many IBS-TH1/TH2 devices at once as you want. sensor: - platform: inkbird_ibsth1_mini - mac_address: 38:81:D7:0A:9C:11 + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Inkbird IBS-TH1 Temperature" external_temperature: @@ -54,27 +54,19 @@ Configuration variables: - **mac_address** (**Required**, MAC Address): The MAC address of the Inkbird IBS-TH1 device. - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **external_temperature** (*Optional*): The information for the external temperature sensor. - - **name** (**Required**, string): The name for the external temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **battery_level** (*Optional*): The information for the battery level sensor - - **name** (**Required**, string): The name for the battery level sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Setting Up Devices @@ -88,21 +80,21 @@ like so: esp32_ble_tracker: -After uploading the ESP32 will immediately try to scan for BLE devices such as the Inkbird IBS-TH1/TH2. +After uploading the ESP32 will immediately try to scan for BLE devices such as the Inkbird IBS-TH1/TH2. When it detects these sensors, it will automatically parse the BLE message print a message like this one: .. code:: - [13:36:43][D][esp32_ble_tracker:544]: Found device 38:81:D7:0A:9C:11 RSSI=-53 + [13:36:43][D][esp32_ble_tracker:544]: Found device XX:XX:XX:XX:XX:XX RSSI=-53 [13:36:43][D][esp32_ble_tracker:565]: Address Type: PUBLIC [13:36:43][D][esp32_ble_tracker:567]: Name: 'sps' Note that it can sometimes take some time for the first BLE broadcast to be received. Please note that address type -should say 'PUBLIC' and the device name should be 'sps', this is how you find the Inkbird IBS-TH1/TH2 among all the +should say 'PUBLIC' and the device name should be 'sps', this is how you find the Inkbird IBS-TH1/TH2 among all the other devices. -Then just copy the address (``38:81:D7:0A:9C:11``) into a new ``sensor.inkbird_ibsth1_mini`` platform +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.inkbird_ibsth1_mini`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/integration.rst b/components/sensor/integration.rst index de9dc7f447..d2a2534bf3 100644 --- a/components/sensor/integration.rst +++ b/components/sensor/integration.rst @@ -29,7 +29,6 @@ Configuration variables: ------------------------ - **sensor** (**Required**, :ref:`config-id`): The ID of the sensor to integrate over time. -- **name** (**Required**, string): The name of the integration sensor. - **time_unit** (**Required**, string): The time unit to integrate with, one of ``ms``, ``s``, ``min``, ``h`` or ``d``. - **integration_method** (*Optional*, string): The integration method to use. One of @@ -37,7 +36,6 @@ Configuration variables: - **restore** (*Optional*, boolean): Whether to store the intermediate result on the device so that the value can be restored upon power cycle or reboot. Warning: this option can wear out your flash. Defaults to ``false``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. .. _sensor-integration-reset_action: diff --git a/components/sensor/internal_temperature.rst b/components/sensor/internal_temperature.rst index 066aafecf1..38d8679fd0 100644 --- a/components/sensor/internal_temperature.rst +++ b/components/sensor/internal_temperature.rst @@ -28,10 +28,8 @@ temperature sensor of the ESP32, RP2040 and BK72XX chip. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the temperature sensor. - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/jsn_sr04t.rst b/components/sensor/jsn_sr04t.rst index 700701255a..7e78484e13 100644 --- a/components/sensor/jsn_sr04t.rst +++ b/components/sensor/jsn_sr04t.rst @@ -6,7 +6,7 @@ JSN-SR04T Waterproof Ultrasonic Range Finder :image: jsn-sr04t-v3.jpg :keywords: JSN-SR04T -This sensor allows you to use the JSN-SR04T Waterproof Ultrasonic Range Finder **in Mode 1 and 2** +This sensor allows you to use the JSN-SR04T and AJ_SR04M Waterproof Ultrasonic Range Finder **in Mode 1 and 2** with ESPHome to measure distances. This sensor can measure ranges between 25 centimeters and 600 centimeters with a resolution of 1 millimeter. @@ -18,16 +18,22 @@ Configure the JSN-SR04T for mode 2: - **V1.0 and V2.0**: Add a 120k resistor to pad R27. - **V3.0**: Short pad M2 or add 120k resistor to pad mode. +Configure the AJ_SR04M for mode 1: + - Add a 120k resistor to pad R19. + +Configure the AJ_SR04M for mode 2: + - Add a 47k resistor to pad R19. + .. figure:: images/jsn-sr04t-v3-mode-select-pads.jpg :align: center :width: 50.0% JSN-SR04T Waterproof Ultrasonic Range Finder Mode Select Pads. -In mode 1 the module continuously takes measurements approximately every 100mS and outputs the distance on the TX pin at 9600 baud. +In mode 1 the module continuously takes measurements approximately every 100mS and outputs the distance on the TX pin at 9600 baud. In this mode :ref:`sensor-filters` are highly recommended. -In mode 2 the module takes a measurement only when a trigger command of 0x55 is sent to the RX pin on the module. +In mode 2 the module takes a measurement only when a trigger command of 0x55 is sent to the RX pin on the module. The module then outputs the distance on its TX pin. The frequency of the measurements can be set with the **update_interval** option. To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and connect the sensor to the specified pin. @@ -45,16 +51,16 @@ To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and conn - platform: "jsn_sr04t" name: "Distance" update_interval: 1s - + Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. Not applicable in mode 1. - **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus ` you wish to use for this sensor. Use this if you want to use multiple UART buses at once. +- **model** (*Optional*): Sensor model. Available options: ``jsn_sr04t`` (default) and ``aj_sr04t``. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index acc4b48231..1f897b69e6 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -156,7 +156,7 @@ Configuration variables: - **detection_distance** (*Optional*, int): Distance in cm of target. All options from :ref:`Sensor `. - **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8). - + - **move_energy** (*Optional*, int): When in :ref:`engineering mode`, the move energy of the gate, otherwise ``unknown``. Value between ``0`` and ``100`` inclusive. All options from :ref:`Sensor `. @@ -276,7 +276,7 @@ Configuration variables: Value between ``2`` and ``8`` inclusive. Defaults to ``8``. All options from :ref:`Number `. - **gX** (*Optional*): Thresholds for the Xth gate (X => 0 to 8). - + - **move_threshold** (**Required**, int): Threshold for the gate for motion detection. Above this level for the considered gate (distance), movement detection will be triggered. Value between ``0`` and ``100`` inclusive. See default values below. @@ -435,8 +435,8 @@ To change the password from HA you can use the following example config: id: my_ld2410 api: - services: - - service: set_ld2410_bluetooth_password + actions: + - action: set_ld2410_bluetooth_password variables: password: string then: diff --git a/components/sensor/ltr390.rst b/components/sensor/ltr390.rst index 4b6933d75e..d80ed21177 100644 --- a/components/sensor/ltr390.rst +++ b/components/sensor/ltr390.rst @@ -44,6 +44,28 @@ Configuration variables: - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. It is recommended that the update interval is at least 1 second since updates can take up to 800ms when using a high resolution value. +Granular control over gain and resolution +......................................... +By default, the ``gain`` and ``resolution`` parameters set same values for both ALS and UV measurements. In real life scenarios there might be significant +differences in the light intensity and UV index, so it is recommended to use different gain and resolution values for ALS and for UV sensor to avoid saturation. +See the example below, where the gain and resolution are set to different values for ALS and UV sensors.: + +.. code-block:: yaml + + sensor: + - platform: ltr390 + uv: + name: "UV Sensor Counts" + ambient_light: + name: "Light Sensor Counts" + gain: + ambient_light: X9 + uv: X3 + resolution: + ambient_light: 18 + uv: 13 + + Lux and UVI Formulas -------------------- diff --git a/components/sensor/lvgl.rst b/components/sensor/lvgl.rst new file mode 100644 index 0000000000..b7c13e252b --- /dev/null +++ b/components/sensor/lvgl.rst @@ -0,0 +1,46 @@ +LVGL Sensor +=========== + +.. seo:: + :description: Instructions for setting up an LVGL widget sensor component. + :image: ../images/lvgl_c_num.png + +The ``lvgl`` sensor platform creates a semsor component from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-arc`, :ref:`lvgl-widget-bar`, :ref:`lvgl-widget-slider` and :ref:`lvgl-widget-spinbox`. A single sensor supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome sensor. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the sensor. +- All other variables from :ref:`Sensor `. + +Example: + +.. code-block:: yaml + + sensor: + - platform: lvgl + widget: slider_id + name: LVGL Slider + +.. note:: + + Widget-specific actions (``lvgl.arc.update``, ``lvgl.bar.update``, ``lvgl.slider.update``, ``lvgl.spinbox.update``, ``lvgl.spinbox.decrement``, ``lvgl.spinbox.increment``) will trigger correspponding component updates to be sent to Home Assistant. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Arc widget ` +- :ref:`Bar widget ` +- :ref:`Slider widget ` +- :ref:`Spinbox widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/sensor/m5stack_8angle.rst b/components/sensor/m5stack_8angle.rst new file mode 100644 index 0000000000..659d05458b --- /dev/null +++ b/components/sensor/m5stack_8angle.rst @@ -0,0 +1,145 @@ +M5Stack Unit 8 Angle +==================== + +.. seo:: + :description: Setting up the M5Stack Unit 8 Angle input device with 8 knobs. + :image: m5stack_8angle.png + +Component/Hub +------------- + +The ``m5stack_8angle`` platform allows to use the [m5angle](https://docs.m5stack.com/en/unit/UNIT%208Angle) input device with ESPHome. +It has 8 knobs, a switch and can individually drive 9 RGB LEDs. + +.. figure:: images/m5stack_8angle.jpg + :align: center + :width: 75.0% + + The m5stack_8angle unit. + +The ``m5stack_8angle`` component communicates through an :ref:`I²C ` bus and uses a default address of 0x43. + +.. code-block:: yaml + + # Example configuration entry + m5stack_8angle: + id: m5stack_8angle_base + +Configuration variables: +************************ + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you need +- **address** (*Optional*, int): Manually specify the I²C address of the device. Defaults to ``0x43``. + + +Knob's position sensor +---------------------- + +The position of the 8 knobs can be made available as sensors with values between 0-1 (with 0 being the leftmost position). + +.. code-block:: yaml + + sensor: + - platform: m5stack_8angle + m5stack_8angle_id: m5stack_8angle_base + channel: 1 + name: "Knob 1" + bit_depth: 12 bit + - platform: m5stack_8angle + m5stack_8angle_id: m5stack_8angle_base + channel: 2 + name: "Knob 2" + +Configuration variables: +************************ + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``10s``. +- **bit_depth** (*Optional*, one of ``12 bit`` or ``8 bit``) determines the precision of the analog readout, defaults to ``8bit``. +- **raw** (*Optional*, boolean) if true, the sensor returns the raw readout value of the knob. +- All other options from :ref:`Sensor `. + + +Input switch binary sensor +-------------------------- + + A binary sensor indicating the state of the switch on the device. + +.. code-block:: yaml + + binary_sensor: + - platform: m5stack_8angle + m5stack_8angle_id: m5stack_8angle_base + name: "Switch" + +Configuration variables: +************************ + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``10s``. +- All other options from :ref:`Binary Sensor `. + + +Lights +------ +The 9 LEDs can be used a addressable light output. + +.. code-block:: yaml + + light: + - platform: m5stack_8angle + m5stack_8angle_id: m5stack_8angle_base + id: m8_angle_leds + name: "Lights" + effects: + - addressable_rainbow: + +Configuration variables: +************************ +- All options from :ref:`Light `. + + +Read knob's positions and switch state in Lambdas +------------------------------------------------- + +You can trigger the readout of the position of an individual knob through ``float value = id(...)->read_knob_pos(index);`` and of the switch through ``int value = id(...)->read_switch();``. +A negative return value indicates a failure to read the state. + +.. code-block:: yaml + + # Example configuration entry for having the LEDs indicate the knobs' position + light: + - platform: m5stack_8angle + m5stack_8angle_id: m5stack_8angle_base + id: m8_angle_leds + name: "Lights" + effects: + - addressable_lambda: + name: "Indicate Values" + update_interval: 200ms + lambda: |- + ESPHSVColor hsv; + hsv.value = 255; + hsv.saturation = 240; + auto parent = id(m5stack_8angle_base); + for (int i=0; i < 8; i++) { + auto kpos = parent->read_knob_pos(i); + if (kpos >= 0){ + hsv.hue = kpos * 200; + it[i] = hsv; + } + } + if (parent->read_switch() > 0) + hsv.hue = 200; + else + hsv.hue = 0; + it[8] = hsv; + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`/components/binary_sensor/index` +- :doc:`/components/light/index` +- :doc:`template` +- :apiref:`m5stack_8angle/m5stack_8angle.h` +- :ghedit:`Edit` diff --git a/components/sensor/max31855.rst b/components/sensor/max31855.rst index fea7c71bc0..f7749d9af0 100644 --- a/components/sensor/max31855.rst +++ b/components/sensor/max31855.rst @@ -34,12 +34,13 @@ Connect ``GND`` to ``GND``, ``VCC`` to ``3.3V`` and the other three ``MISO`` (or Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **cs_pin** (**Required**, :ref:`Pin Schema `): The Chip Select pin of the SPI interface. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. -- **reference_temperature** (*Optional*, :ref:`config-id`): Access the internal temperature sensor of the MAX31855. Requires a **name** and/or **id**. +- **reference_temperature** (*Optional*, :ref:`config-id`): Access the internal temperature sensor of the MAX31855. + + - All options from :ref:`Sensor `. + - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/max31865.rst b/components/sensor/max31865.rst index 1282ec1b75..343892d602 100644 --- a/components/sensor/max31865.rst +++ b/components/sensor/max31865.rst @@ -46,7 +46,6 @@ to have an :ref:`spi bus ` in your configuration with both **miso_pin** and Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **cs_pin** (**Required**, :ref:`Pin Schema `): The Chip Select pin of the SPI interface. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **reference_resistance** (**Required**, float): Reference resistor on the PCB. Adafruit's PT100 (#3328) uses 430 Ω, their PT1000 (#3648) uses 4300 Ω. @@ -54,7 +53,6 @@ Configuration variables: - **mains_filter** (*Optional*, string): The mains power frequency to reject (``50 Hz`` or ``60 Hz``). Defaults to ``60 Hz``. - **rtd_wires** (*Optional*, int): The number of RTD wires. Be sure to solder board jumpers to match! Defaults to ``4``. - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/max44009.rst b/components/sensor/max44009.rst index b1c41cb7f1..31e04e1487 100644 --- a/components/sensor/max44009.rst +++ b/components/sensor/max44009.rst @@ -8,8 +8,8 @@ MAX44009 Ambient Light Sensor The ``max44009`` sensor platform allows you to use your MAX44009 (`datasheet `__) -ambient light sensor with ESPHome. This sensor features an ultra-wide 22-bit dynamic range -from 0.045 lux to 188,000 lux. The :ref:`I²C bus ` is required to be set up in your +ambient light sensor with ESPHome. This sensor features an ultra-wide 22-bit dynamic range +from 0.045 lux to 188,000 lux. The :ref:`I²C bus ` is required to be set up in your configuration for this sensor to work. The ``max44009`` sensor can operate in two modes: ``low_power`` (default) and ``continuous``: @@ -28,12 +28,10 @@ The ``max44009`` sensor can operate in two modes: ``low_power`` (default) and `` Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the sensor. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x4A``. - **mode** (*Optional*, string): Measurement mode. One of ``auto``, ``low_power``, ``continuous``. - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/max6675.rst b/components/sensor/max6675.rst index 1eef166200..a965ad8b6a 100644 --- a/components/sensor/max6675.rst +++ b/components/sensor/max6675.rst @@ -42,13 +42,11 @@ Connect ``GND`` to ``GND``, ``VCC`` to ``3.3V`` and the other three ``MISO`` (or Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **cs_pin** (**Required**, :ref:`Pin Schema `): The Chip Select pin of the SPI interface. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/max9611.rst b/components/sensor/max9611.rst index 5cfbd5ff5f..dd9e2cca67 100644 --- a/components/sensor/max9611.rst +++ b/components/sensor/max9611.rst @@ -47,23 +47,19 @@ Configuration variables: - **voltage** (*Optional*): The information for the voltage sensor - - **name** (**Required**, string): The name for the voltage sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **current** (*Optional*): The information for the current sensor, scaled by the gain factor and multiplied by voltage - - **name** (**Required**, string): The name for the current sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **power** (*Optional*): The information for the power sensor - - **name** (**Required**, string): The name for the power sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the temperature sensor - - **name** (**Required**, string): The name for the temperature sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of diff --git a/components/sensor/mcp9600.rst b/components/sensor/mcp9600.rst index 5d5a6a809b..5294470ac6 100644 --- a/components/sensor/mcp9600.rst +++ b/components/sensor/mcp9600.rst @@ -41,16 +41,11 @@ Configuration variables: - **hot_junction** (*Optional*): The information for the Hot Junction temperature sensor. - - **name** (**Required**, string): The name for the temperature - sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **cold_junction** (*Optional*): The information for the Cold Junction temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **thermocouple_type** (*Optional*): Set the thermocouple type. Options are: K, J, T, N, S, E, B and R type thermocouple. Defaults to ``K``. diff --git a/components/sensor/mcp9808.rst b/components/sensor/mcp9808.rst index 6bd23f9405..9162f4addc 100644 --- a/components/sensor/mcp9808.rst +++ b/components/sensor/mcp9808.rst @@ -32,8 +32,6 @@ required to be set up in your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x18``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - All other options from :ref:`Sensor `. diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 0d3c8f3138..a62065672c 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -82,13 +82,13 @@ for over 20 minutes and you execute this function. then: - mhz19.calibrate_zero: my_mhz19_id -You can provide :ref:`service ` to call it from Home Assistant +You can provide an :ref:`action ` to perform from Home Assistant .. code-block:: yaml api: - services: - - service: mhz19_calibrate_zero + actions: + - action: mhz19_calibrate_zero then: - mhz19.calibrate_zero: my_mhz19_id diff --git a/components/sensor/mlx90393.rst b/components/sensor/mlx90393.rst index fb4700e247..643456ab19 100644 --- a/components/sensor/mlx90393.rst +++ b/components/sensor/mlx90393.rst @@ -37,8 +37,6 @@ Configuration variables: - **x_axis** (*Optional*): The information for the x-axis. - - **name** (**Required**, string): The name for the x-axis sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of: - ``16BIT`` @@ -50,8 +48,6 @@ Configuration variables: - **y_axis** (*Optional*): The information for the y-axis. - - **name** (**Required**, string): The name for the y-axis sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **resolution** (*Optional*, int): Set resolution. Defaults to ``19BIT``. Must be one of: - ``16BIT`` @@ -63,8 +59,6 @@ Configuration variables: - **z_axis** (*Optional*): The information for the z-axis. - - **name** (**Required**, string): The name for the z-axis sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **resolution** (*Optional*, int): Set resolution. Defaults to ``16BIT``. Must be one of: - ``16BIT`` @@ -76,8 +70,6 @@ Configuration variables: - **temperature** (*Optional*): Built-in temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - **oversampling** (*Optional*, int): On-chip oversampling for the temperature sensor. Defaults to ``0``. Must be between ``0`` and ``3``. - All other options from :ref:`Sensor `. diff --git a/components/sensor/modbus_controller.rst b/components/sensor/modbus_controller.rst index a0ae94dae8..4d9d7c1835 100644 --- a/components/sensor/modbus_controller.rst +++ b/components/sensor/modbus_controller.rst @@ -11,8 +11,6 @@ and requires :doc:`/components/modbus_controller` to be configured. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **register_type** (**Required**): type of the modbus register. - ``coil``: Coils are 1-bit registers (ON/OFF values) that are used to control discrete outputs. They may be read and/or written. Modbus *Function Code 1 (Read Coil Status)* will be used. diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index ec003a832a..6647cb0c2c 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -9,7 +9,7 @@ Mopeka Pro Check BLE Sensor The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka Pro Check LP, Mopeka Pro Plus, Mopeka Pro Universal or Lippert Propane Tank Sensors, Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component -will track the tank level, distance, temperature, and battery percentage of a +will track the tank level, distance, temperature, and battery percentage of a device every time the sensor sends out a BLE broadcast. .. warning:: @@ -21,7 +21,7 @@ device every time the sensor sends out a BLE broadcast. + Lippert Propane Tank Sensor, part number 2021130655 Sensors are calibrated for propane only. - + See :doc:`/components/sensor/mopeka_std_check` for original Mopeka Check sensors support. .. figure:: images/mopeka_pro_check.jpg @@ -32,7 +32,7 @@ device every time the sensor sends out a BLE broadcast. .. figure:: images/mopeka_pro_check_lippert.jpg :align: center - Lippert™ Propane Tank Sensor + Lippert™ Propane Tank Sensor The original Mopeka Check sensors are not supported. @@ -46,7 +46,7 @@ Mopeka Pro Check LP over BLE: sensor: # Example using 20lb vertical propane tank. - platform: mopeka_pro_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: 20LB_V temperature: name: "Propane test temp" @@ -59,7 +59,7 @@ Mopeka Pro Check LP over BLE: # Custom example - user defined empty / full points - platform: mopeka_pro_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: CUSTOM custom_distance_full: 40cm custom_distance_empty: 10mm @@ -137,9 +137,9 @@ For all sensors found the ``mopeka_ble`` component will print a message like thi .. code:: - [20:43:26][I][mopeka_ble:074]: MOPEKA PRO (NRF52) SENSOR FOUND: D3:75:F2:DC:16:91 + [20:43:26][I][mopeka_ble:074]: MOPEKA PRO (NRF52) SENSOR FOUND: XX:XX:XX:XX:XX:XX -Then just copy the address (``D3:75:F2:DC:16:91``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.mopeka_pro_check`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/mopeka_std_check.rst b/components/sensor/mopeka_std_check.rst index e9f7f6f6de..84c6c594e4 100644 --- a/components/sensor/mopeka_std_check.rst +++ b/components/sensor/mopeka_std_check.rst @@ -7,9 +7,9 @@ Mopeka Standard Check BLE Sensor :keywords: Mopeka, Mopeka Standard Check, Mopeka Std Check, BLE, Bluetooth The ``mopeka_std_check`` sensor platform lets you track the output of Mopeka -Standard Check LP Bluetooth Low Energy devices using the -:doc:`/components/esp32_ble_tracker`. This component will track the tank level, -distance, temperature, and battery percentage of a Mopeka Standard Check LP BLE +Standard Check LP Bluetooth Low Energy devices using the +:doc:`/components/esp32_ble_tracker`. This component will track the tank level, +distance, temperature, and battery percentage of a Mopeka Standard Check LP BLE device every time the sensor sends out a BLE broadcast. .. warning:: @@ -29,7 +29,7 @@ device every time the sensor sends out a BLE broadcast. sensor: # Example using 11kg 100% propane tank. - platform: mopeka_std_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: Europe_11kg temperature: name: "Propane test temp" @@ -42,7 +42,7 @@ device every time the sensor sends out a BLE broadcast. # Custom example - user defined empty / full points and 80% butane and 20% propane. - platform: mopeka_std_check - mac_address: D3:75:F2:DC:16:91 + mac_address: XX:XX:XX:XX:XX:XX tank_type: CUSTOM custom_distance_full: 40cm custom_distance_empty: 32mm @@ -125,15 +125,15 @@ and the ``mopeka_ble`` component like so: mopeka_ble: -After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Standard devices you must press and hold the green sync button for it to be identified. +After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Standard devices you must press and hold the green sync button for it to be identified. Or alternativly set the configuration flag ``show_sensors_without_sync: true`` to see all devices. For all sensors found the ``mopeka_ble`` component will print a message like this one: .. code:: - [20:43:26][I][mopeka_ble:056]: MOPEKA STD (CC2540) SENSOR FOUND: D3:75:F2:DC:16:91 + [20:43:26][I][mopeka_ble:056]: MOPEKA STD (CC2540) SENSOR FOUND: XX:XX:XX:XX:XX:XX -Then just copy the address (``D3:75:F2:DC:16:91``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.mopeka_std_check`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/mpl3115a2.rst b/components/sensor/mpl3115a2.rst index 4333ed9c7c..77dcaa1357 100644 --- a/components/sensor/mpl3115a2.rst +++ b/components/sensor/mpl3115a2.rst @@ -37,21 +37,15 @@ sensor is configured. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **altitude** (*Optional*): The information for the altitude sensor. - - **name** (**Required**, string): The name for the altitude sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x60``. diff --git a/components/sensor/mqtt_subscribe.rst b/components/sensor/mqtt_subscribe.rst index ae8e723e01..0db66d45e1 100644 --- a/components/sensor/mqtt_subscribe.rst +++ b/components/sensor/mqtt_subscribe.rst @@ -26,10 +26,8 @@ text sensor for importing arbitrary text into the ESPHome ecosystem. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **topic** (**Required**, string): The MQTT topic to listen for numeric messages. - **qos** (*Optional*, int): The MQTT QoS to subscribe with. Defaults to ``0``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/ms5611.rst b/components/sensor/ms5611.rst index 4ef9c05a15..9474bb1efa 100644 --- a/components/sensor/ms5611.rst +++ b/components/sensor/ms5611.rst @@ -39,17 +39,12 @@ Configuration variables: - **pressure** (**Required**): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (**Required**): The information for the temperature. sensor - - **name** (**Required**, string): The name for the temperature - sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x77``. diff --git a/components/sensor/nextion.rst b/components/sensor/nextion.rst index b5d23af9ba..ff8389c3d1 100644 --- a/components/sensor/nextion.rst +++ b/components/sensor/nextion.rst @@ -54,7 +54,6 @@ See :doc:`/components/display/nextion` for setting up the display Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **nextion_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the Nextion display. - **component_name** (*Optional*, string): Manually specify the name of the Nextion component. - **variable_name** (*Optional*, string): Manually specify the name of the Nextion variable. diff --git a/components/sensor/ntc.rst b/components/sensor/ntc.rst index 5977da1d88..c7b90c78b0 100644 --- a/components/sensor/ntc.rst +++ b/components/sensor/ntc.rst @@ -73,12 +73,10 @@ calibration parameter: Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the sensor. - **sensor** (**Required**, :ref:`config-id`): The sensor to read the resistance values from to convert to temperature readings. - **calibration** (**Required**, float): The calibration parameters of the sensor - see above for more details. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. Self-Heating diff --git a/components/sensor/pulse_counter.rst b/components/sensor/pulse_counter.rst index 9486bd4dee..df54d8ca37 100644 --- a/components/sensor/pulse_counter.rst +++ b/components/sensor/pulse_counter.rst @@ -28,7 +28,6 @@ Configuration variables ------------------------ - **pin** (**Required**, :ref:`config-pin`): The pin to count pulses on. -- **name** (**Required**, string): The name of the sensor. - **count_mode** (*Optional*): Configure how the counter should behave on a detected rising edge/falling edge. @@ -40,18 +39,12 @@ Configuration variables Defaults to ``DISABLE``. - **use_pcnt** (*Optional*, boolean): Use hardware ``PCNT`` pulse counter. Only supported on ESP32. Defaults to ``true``. - - **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this time is detected, it’s discarded and no pulse is counted. Defaults to ``13us``. On the ESP32, when using the hardware pulse counter this value can not be higher than ``13us``, for the ESP8266 or with ``use_pcnt: false`` you can use larger intervals too. If you enable this, set up the ``count_mode`` to increase on the falling edge, not leading edge. For S0 pulse meters that are used to meter power consumption 50-100 ms is a reasonable value. - - **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. - - **total** (*Optional*): Report the total number of pulses. - - All other options from :ref:`Sensor `. .. note:: @@ -111,10 +104,10 @@ trying to match. .. code-block:: yaml - # Set pulse counter total from home assistant using this service call: + # Set pulse counter total from home assistant using this action: api: - services: - - service: set_pulse_total + actions: + - action: set_pulse_total variables: new_pulse_total: int then: diff --git a/components/sensor/pulse_meter.rst b/components/sensor/pulse_meter.rst index 785f299c54..53bbb02a82 100644 --- a/components/sensor/pulse_meter.rst +++ b/components/sensor/pulse_meter.rst @@ -29,7 +29,6 @@ Configuration variables ------------------------ - **pin** (**Required**, :ref:`config-pin`): The pin to count pulses on. -- **name** (**Required**, string): The name of the sensor. - **internal_filter** (*Optional*, :ref:`config-time`): If a pulse shorter than this time is detected, it is discarded. Defaults to ``13us``. @@ -91,8 +90,8 @@ trying to match. .. code-block:: yaml api: - services: - - service: set_total + actions: + - action: set_total variables: new_total: int then: diff --git a/components/sensor/qmc5883l.rst b/components/sensor/qmc5883l.rst index 5157490aef..803d4d2d28 100644 --- a/components/sensor/qmc5883l.rst +++ b/components/sensor/qmc5883l.rst @@ -44,7 +44,7 @@ configuration for this sensor to work. Configuration variables: ------------------------ -- **address** (*Optional*, int): Manually specify the I²c address of the sensor. Defaults to ``0x1E``. +- **address** (*Optional*, int): Manually specify the I²c address of the sensor. Defaults to ``0x0D``. - **field_strength_x** (*Optional*): The field strength in microtesla along the X-Axis. All options from :ref:`Sensor `. - **field_strength_y** (*Optional*): The field strength in microtesla along the Y-Axis. All options from diff --git a/components/sensor/qmp6988.rst b/components/sensor/qmp6988.rst index 8d777dfb4d..de6f54ff5f 100644 --- a/components/sensor/qmp6988.rst +++ b/components/sensor/qmp6988.rst @@ -38,19 +38,14 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature sensor - - **name** (**Required**, string): The name for the temperature - sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`Oversampling Options `. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. See :ref:`Oversampling Options `. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of @@ -73,9 +68,9 @@ configure this amount. Possible oversampling values: - ``2x`` - ``4x`` - ``8x`` (default) -- ``16x`` -- ``32x`` -- ``64x`` +- ``16x`` +- ``32x`` +- ``64x`` See Also -------- diff --git a/components/sensor/radon_eye_ble.rst b/components/sensor/radon_eye_ble.rst index cbf7356661..eea0374b84 100644 --- a/components/sensor/radon_eye_ble.rst +++ b/components/sensor/radon_eye_ble.rst @@ -29,7 +29,7 @@ The device will then listen for nearby devices, and display a message like this .. code-block:: text [D][radon_eye_ble:017]: - Found Radon Eye RD200 device Name: FR:R20:SN1234 (MAC: 01:02:03:04:05:06) + Found Radon Eye RD200 device Name: FR:R20:SN1234 (MAC: XX:XX:XX:XX:XX:XX) Once the device is found, remove the ``radon_eye_ble`` device tracker from your configuration and take note of the device MAC address, and use it when configuring a sensor below. @@ -61,7 +61,7 @@ Configuration example: esp32_ble_tracker: ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: radon_eye_ble_id sensor: @@ -80,7 +80,7 @@ Here is an example to use pCi/L (to match the value on the device display): esp32_ble_tracker: ble_client: - - mac_address: 01:02:03:04:05:06 + - mac_address: XX:XX:XX:XX:XX:XX id: radon_eye_ble_id sensor: @@ -99,4 +99,3 @@ Here is an example to use pCi/L (to match the value on the device display): accuracy_decimals: 2 filters: - lambda: return x / 37; - diff --git a/components/sensor/resistance.rst b/components/sensor/resistance.rst index cc6ce039ef..85934b41d2 100644 --- a/components/sensor/resistance.rst +++ b/components/sensor/resistance.rst @@ -60,7 +60,6 @@ Some boards like NodeMCUv2 needs to multiply ADC reading by 3.3 to provide accur Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the sensor. - **sensor** (**Required**, :ref:`config-id`): The sensor to read the voltage values from to convert to resistance readings. - **configuration** (**Required**, string): The type of circuit, one of ``DOWNSTREAM`` or @@ -68,7 +67,6 @@ Configuration variables: - **resistor** (**Required**, float): The value of the resistor with a constant value. - **reference_voltage** (*Optional*, float): The reference voltage. Defaults to ``3.3V``. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/rotary_encoder.rst b/components/sensor/rotary_encoder.rst index 476b4319c6..c29310843a 100644 --- a/components/sensor/rotary_encoder.rst +++ b/components/sensor/rotary_encoder.rst @@ -55,7 +55,6 @@ Configuration variables: The first pin for determining the step value. Must not be a pin from an external I/O expander. - **pin_b** (**Required**, :ref:`Pin Schema `): The second pin for determining the step value. Must not be a pin from an external I/O expander. -- **name** (**Required**, string): The name of the rotary encoder sensor. - **pin_reset** (*Optional*, :ref:`Pin Schema `): An optional pin that resets the step value. This is useful with rotary encoders that have a third pin. Defaults to no reset pin. @@ -66,7 +65,6 @@ Configuration variables: - ``2`` - ``4`` -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **min_value** (*Optional*, int): The minimum value this rotary encoder will go to, turning 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 @@ -76,8 +74,6 @@ Configuration variables: "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). diff --git a/components/sensor/ruuvitag.rst b/components/sensor/ruuvitag.rst index b38f807408..ee6df690ef 100644 --- a/components/sensor/ruuvitag.rst +++ b/components/sensor/ruuvitag.rst @@ -30,7 +30,7 @@ movement count and measurement sequence number are also tracked. sensor: - platform: ruuvitag - mac_address: FF:56:D3:2F:7D:E8 + mac_address: XX:XX:XX:XX:XX:XX humidity: name: "RuuviTag Humidity" temperature: @@ -61,91 +61,57 @@ Configuration variables: device. - **humidity** (*Optional*): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - - **name** (**Required**, string): The name for the pressure sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **acceleration** (*Optional*): The information for the acceleration sensor. - - **name** (**Required**, string): The name for the acceleration sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **acceleration_x** (*Optional*): The information for the acceleration x sensor. - - **name** (**Required**, string): The name for the acceleration x sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **acceleration_y** (*Optional*): The information for the acceleration y sensor. - - **name** (**Required**, string): The name for the acceleration y sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **acceleration_z** (*Optional*): The information for the acceleration z sensor. - - **name** (**Required**, string): The name for the acceleration z sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **battery_voltage** (*Optional*): The information for the battery voltage sensor. - - **name** (**Required**, string): The name for the battery voltage sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **tx_power** (*Optional*): The information for the transmit power sensor - - **name** (**Required**, string): The name for the transmit power sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - Only available if RAWv2 protocol is used. - **movement_counter** (*Optional*): The information for the movement count sensor - - **name** (**Required**, string): The name for the movement count sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - Only available if RAWv2 protocol is used. - **measurement_sequence_number** (*Optional*): The information for the measurement sequence number sensor - - **name** (**Required**, string): The name for the measurement sequence - number sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use - in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - Only available if RAWv2 protocol is used. Setting Up Devices @@ -167,11 +133,11 @@ print a message like this one: .. code:: - Got ruuvi RuuviTag (FF:56:D3:2F:7D:E8): Humidity: 67.5%, Temperature: 22.97°C, + Got ruuvi RuuviTag (XX:XX:XX:XX:XX:XX): Humidity: 67.5%, Temperature: 22.97°C, Pressure: 977.09hPa, Acceleration X: 0.005G, Acceleration Y: 0.017G, Acceleration Z: 1.066G, Battery Voltage: 3.223V -Then just copy the address (``FF:56:D3:2F:7D:E8``) into a new +Then just copy the address (``XX:XX:XX:XX:XX:XX``) into a new ``sensor.ruuvitag`` platform entry like in the configuration example at the top. .. note:: diff --git a/components/sensor/scd30.rst b/components/sensor/scd30.rst index 4081d8a140..3f52b07272 100644 --- a/components/sensor/scd30.rst +++ b/components/sensor/scd30.rst @@ -36,21 +36,15 @@ Configuration variables: - **co2** (*Optional*): The information for the CO₂ sensor. - - **name** (**Required**, string): The name for the CO₂eq sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the Temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the Humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature_offset** (*Optional*, float): Temperature and humidity offsets may occur when operating the sensor in end-customer @@ -90,7 +84,7 @@ Manual calibration: then: - scd30.force_recalibration_with_reference: value: !lambda 'return id(co2_cal).state;' - + number: - platform: template name: "CO2 calibration value" diff --git a/components/sensor/scd4x.rst b/components/sensor/scd4x.rst index ff52756a72..086121d5f7 100644 --- a/components/sensor/scd4x.rst +++ b/components/sensor/scd4x.rst @@ -6,7 +6,7 @@ SCD4X CO₂, Temperature and Relative Humidity Sensor :image: scd4x.jpg The ``scd4x`` sensor platform allows you to use your Sensirion SCD4X CO₂ -(`datasheet `__) sensors with ESPHome. +(`datasheet `__) sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. .. figure:: images/scd4x.jpg @@ -31,22 +31,16 @@ Configuration variables: - **co2** (*Optional*): The information for the CO₂ sensor. - - **name** (**Required**, string): The name for the CO₂eq sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the Temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the Humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature_offset** (*Optional*, float): The temperature offset can depend on various factors such as the SCD4x measurement mode, self-heating of close @@ -105,13 +99,13 @@ As of April 2022 the average fresh air Co² concentration is 419 ppm. value: 419 # outside average April 2022 id: my_scd41 -value can also be a template, for example to define a Home Assistant calibration service: +value can also be a template, for example to define a Home Assistant calibration action: .. code-block:: yaml api: - services: - - service: calibrate_co2_value + actions: + - action: calibrate_co2_value variables: co2_ppm: int then: @@ -166,8 +160,8 @@ This example creates a service `set_ambient_pressure` that can be called from Ho .. code-block:: yaml api: - services: - - service: set_ambient_pressure + actions: + - action: set_ambient_pressure variables: pressure_mbar: int then: diff --git a/components/sensor/sdp3x.rst b/components/sensor/sdp3x.rst index 8944c1b1b2..27f610ee6b 100644 --- a/components/sensor/sdp3x.rst +++ b/components/sensor/sdp3x.rst @@ -32,8 +32,6 @@ To use the sensor, set up an :ref:`I²C Bus ` and connect the sensor to the Configuration variables: ------------------------ -- **name** (**Required**, string): The name for this sensor. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for lambdas/multiple sensors. - **address** (*Optional*, int): The I²C address of the sensor. Defaults to ``0x21``. - **measurement_mode** (*Optional*): The measurement mode of the sensor. Valid options are ``differential_pressure`` and ``mass_flow``. Defaults to ``differential_pressure``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/sen5x.rst b/components/sensor/sen5x.rst index 560943b415..f8385e079c 100644 --- a/components/sensor/sen5x.rst +++ b/components/sensor/sen5x.rst @@ -66,42 +66,31 @@ Configuration variables: - **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **auto_cleaning_interval** (*Optional*): Reads/Writes the interval in seconds of the periodic fan-cleaning. - **temperature** (*Optional*): Temperature.Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): Relative Humidity. Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. -- **voc** (*Optional*): VOC Index. Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. + - All options from :ref:`Sensor `. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **voc** (*Optional*): VOC Index. Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. - **algorithm_tuning** (*Optional*): The VOC algorithm can be customized by tuning 6 different parameters. For more details see `Engineering Guidelines for SEN5x `__ @@ -116,9 +105,6 @@ Configuration variables: - **nox** (*Optional*): NOx Index. Note: Only available with Sen55. The sensor will be ignored on unsupported models. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - **algorithm_tuning** (*Optional*): The NOx algorithm can be customized by tuning 5 different parameters.For more details see `Engineering Guidelines for SEN5x `__ - **index_offset** (*Optional*): NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100. diff --git a/components/sensor/senseair.rst b/components/sensor/senseair.rst index 11540f1f4a..087cb200ec 100644 --- a/components/sensor/senseair.rst +++ b/components/sensor/senseair.rst @@ -42,9 +42,7 @@ Configuration variables: - **co2** (**Required**): The CO_2 data from the sensor in parts per million (ppm). - - **name** (**Required**, string): The name for the CO_2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sensor/sgp30.rst b/components/sensor/sgp30.rst index e54b4021ec..6651236835 100644 --- a/components/sensor/sgp30.rst +++ b/components/sensor/sgp30.rst @@ -33,15 +33,11 @@ Configuration variables: - **eco2** (**Required**): The information for the CO₂eq. sensor. - - **name** (**Required**, string): The name for the CO₂eq sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **tvoc** (**Required**): The information for the total Volatile Organic Compounds sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **store_baseline** (*Optional*, boolean): Store the sensor baselines persistently when calculated or updated. Defaults to yes. @@ -60,17 +56,13 @@ Advanced: - **tvoc_baseline** (**Required**, int): The TVOC baseline for calibration purposes. After OTA, this value is used to calibrate the sensor. -- **eco2_baseline** (*Optional*): The information for the CO₂eq. sensor baseline value. Baseline value is published in decimals. +- **eco2_baseline** (*Optional*): The information for the CO₂eq. baseline value sensor. Baseline value is published in decimals. - - **name** (**Required**, string): The name for the CO₂eq baseline value sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. -- **tvoc_baseline** (*Optional*): The information for the TVOC baseline value sensor. Baseline value is published in in decimals. +- **tvoc_baseline** (*Optional*): The information for the TVOC baseline value sensor. Baseline value is published in decimals. - - **name** (**Required**, string): The name for the TVOC baseline value sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **compensation** (*Optional*): The block containing sensors used for compensation. Both values must be supplied in order to be able to generate the absolute humidity to be reported to the sensor. diff --git a/components/sensor/sgp4x.rst b/components/sensor/sgp4x.rst index 726d0f40e8..f73612c652 100644 --- a/components/sensor/sgp4x.rst +++ b/components/sensor/sgp4x.rst @@ -39,8 +39,6 @@ Configuration variables: - **voc** (*Optional*): VOC Index - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **algorithm_tuning** (*Optional*): The VOC algorithm can be customized by tuning 6 different parameters. For more details see `Engineering Guidelines for SEN5x `__ - **index_offset** (*Optional*): VOC index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100. @@ -55,8 +53,6 @@ Configuration variables: - **nox** (*Optional*): NOx Index. Only available with SGP41. If a SGP40 sensor is detected this sensor will be ignored - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **algorithm_tuning** (*Optional*): The NOx algorithm can be customized by tuning 5 different parameters.For more details see `Engineering Guidelines for SEN5x `__ - **index_offset** (*Optional*): NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100. diff --git a/components/sensor/sht3xd.rst b/components/sensor/sht3xd.rst index 73a968f495..beffd66925 100644 --- a/components/sensor/sht3xd.rst +++ b/components/sensor/sht3xd.rst @@ -35,15 +35,11 @@ Configuration variables: - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x44``. For SHT3x, an alternate address can be ``0x45`` while SHT85 supports only address ``0x44`` diff --git a/components/sensor/sht4x.rst b/components/sensor/sht4x.rst index 4cb37c1b29..350fde2315 100644 --- a/components/sensor/sht4x.rst +++ b/components/sensor/sht4x.rst @@ -30,15 +30,11 @@ Configuration variables: - **temperature** (*Optional*): Temperature. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): Relative Humidity. - - **name** (**Required**, string): The name of the sensor. - - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **precision** (*Optional*, string): The measurement precision, either ``High``, ``Med`` or ``Low``. Default is ``High``. - **heater_max_duty** (*Optional*, float): The maximum duty cycle of the heater (limited to ``0.05``). Default is ``0.0``, i.e. heater off. diff --git a/components/sensor/shtcx.rst b/components/sensor/shtcx.rst index a5fce79eb1..d029d19ad9 100644 --- a/components/sensor/shtcx.rst +++ b/components/sensor/shtcx.rst @@ -37,15 +37,11 @@ Configuration variables: - **temperature** (**Required**): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the humidity sensor. - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x70``. diff --git a/components/sensor/sm300d2.rst b/components/sensor/sm300d2.rst index 1e0ac5adef..ab88174618 100644 --- a/components/sensor/sm300d2.rst +++ b/components/sensor/sm300d2.rst @@ -64,45 +64,31 @@ Configuration variables: - **co2** (**Required**): The information for the CO₂ sensor. Readings in parts per million (ppm). - - **name** (**Required**, string): The name of the CO₂ sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **formaldehyde** (**Required**): The information for the formaldehyde sensor. Readings in µg/m³. - - **name** (**Required**, string): The name of the formaldehyde sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **tvoc** (**Required**): The information for the total volatile organic compounds (TVOC) sensor. Readings in µg/m³. - - **name** (**Required**, string): The name of the TVOC sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_2_5** (**Required**): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³. - - **name** (**Required**, string): The name of the PM2.5 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_10_0** (**Required**): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³. - - **name** (**Required**, string): The name of the PM10 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (**Required**): The information for the temperature sensor. Readings in degrees celsius (°C). - - **name** (**Required**, string): The name of the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (**Required**): The information for the relative humidity sensor. Readings in %. - - **name** (**Required**, string): The name of the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. @@ -129,7 +115,7 @@ Configuration variables: to connect the UART ``5V`` pin to the ESP's ``VIN`` and then power everything through either the LCD module or the ESP module, with a single power cable. If you choose to power the ESP separately from the sensor board, leave the UART ``5V`` pin unconnected. - + See Also -------- diff --git a/components/sensor/smt100.rst b/components/sensor/smt100.rst index cfabbd7577..4856a38290 100644 --- a/components/sensor/smt100.rst +++ b/components/sensor/smt100.rst @@ -46,28 +46,23 @@ Configuration variables: - **counts** (*Optional*): Raw measurement data from the sensor electronics (dimensionless quantity). Higher counts mean less moisture. May be used for material specific calibrations. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **dielectric_constant** (*Optional*): Dielectric coefficient or permittivity of the material to be measured (dimensionless quantity). Higher permittivity means higher water content. May be used for material specific calibration. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): Soil temperature in degrees Celsius. Please note that the temperature sensor is inside the black sensor enclosure and requires some time to equilibrate with the soil temperature. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **moisture** (*Optional*): Soil moisture (volumetric water content in %). - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **voltage** (*Optional*): Supply voltage of the sensor in Volt. - - **name** (**Required**): Sensor name. - - All other options from :ref:`Sensor `. + - 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/sps30.rst b/components/sensor/sps30.rst index bfb0e96409..18d4148a7c 100644 --- a/components/sensor/sps30.rst +++ b/components/sensor/sps30.rst @@ -59,63 +59,43 @@ Configuration variables: - **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pmc_0_5** (*Optional*): The information for the **Number Concentration** sensor for ultrafine particles up to 0.5μm. Readings in particles/cm³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pmc_1_0** (*Optional*): The information for the **Number Concentration** sensor for fine particles up to 1μm. Readings in particles/cm³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pmc_2_5** (*Optional*): The information for the **Number Concentration** sensor for fine particles up to 2.5μm. Readings in particles/cm³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pmc_4_0** (*Optional*): The information for the **Number Concentration** sensor for coarse particles up to 4μm. Readings in particles/cm³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pmc_10_0** (*Optional*): The information for the **Number Concentration** sensor for coarse particles up to 10μm. Readings in particles/cm³. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **pm_size** (*Optional*): Typical particle size in μm. - - **name** (**Required**, string): The name for this sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in automation and lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **auto_cleaning_interval** (*Optional*): The interval in seconds of the periodic fan-cleaning. diff --git a/components/sensor/sts3x.rst b/components/sensor/sts3x.rst index b3f1b84be3..0dad70e74d 100644 --- a/components/sensor/sts3x.rst +++ b/components/sensor/sts3x.rst @@ -27,12 +27,10 @@ required to be set up in your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x4A``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/tee501.rst b/components/sensor/tee501.rst index 6901247f32..94a974b2f3 100644 --- a/components/sensor/tee501.rst +++ b/components/sensor/tee501.rst @@ -27,12 +27,10 @@ required to be set up in your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x48``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/template.rst b/components/sensor/template.rst index 8c971a0661..60ca1a3901 100644 --- a/components/sensor/template.rst +++ b/components/sensor/template.rst @@ -32,12 +32,10 @@ Possible return values for the lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the new value of the sensor - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Set to ``never`` to disable updates. Defaults to ``60s``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. .. _sensor-template-publish_action: diff --git a/components/sensor/tmp102.rst b/components/sensor/tmp102.rst index 96f0e1ac5d..c8c9f4a0d4 100644 --- a/components/sensor/tmp102.rst +++ b/components/sensor/tmp102.rst @@ -32,11 +32,9 @@ configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **address** (*Optional*, int): The I²C address of the sensor. Defaults to ``0x48``. See :ref:`I²C Addresses ` for more information. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/tmp1075.rst b/components/sensor/tmp1075.rst index d44c482df5..6702a81ff3 100644 --- a/components/sensor/tmp1075.rst +++ b/components/sensor/tmp1075.rst @@ -45,8 +45,6 @@ to the specified pins. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the temperature sensor. -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for lambdas/multiple sensors. - **address** (*Optional*, int): The I²C address of the sensor. See :ref:`I²C Addresses ` for more information. Defaults to ``0x48``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check @@ -57,12 +55,13 @@ Configuration variables: checks the sensor. Possible values are ``27.5ms``, ``55ms``, ``110ms``, and ``220ms``. Defaults to ``27.5ms``. - **alert** (*Optional*): Configure the alert pin behaviour. - + - **function** (*Optional*, enum): Function of the alert pin, either ``comparator`` or ``interrupt``. Defaults to ``comparator``. - **polarity** (*Optional*, enum): Polarity of the alert pin, either ``active_high`` or ``active_low``. Defaults to ``active_high``. - **limit_low** (*Optional*, int): Lower temperature limit, in °C. Defaults to ``-128`` (the lowest possible limit value). - **limit_high** (*Optional*, int): Higher temperature limit, in °C. Defaults to ``127.9375`` (the highest possible limit value). - **fault_count** (*Optional*, int): Number of measurements. required for the alert pin to act. Must be between ``1`` and ``4``, inclusive. Defaults to ``1``. +- All other options from :ref:`Sensor `. .. _tmp1075_i2c_addresses: diff --git a/components/sensor/tmp117.rst b/components/sensor/tmp117.rst index 749df70a4e..42c78ad092 100644 --- a/components/sensor/tmp117.rst +++ b/components/sensor/tmp117.rst @@ -37,11 +37,10 @@ If accuracy is a must, see section 8.2.2.2 of the `datasheet ` for more information. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. The sensor component sets the maximum possible averaging in the sensor based on this. +- All other options from :ref:`Sensor `. .. _tmp117_i2c_addresses: diff --git a/components/sensor/tof10120.rst b/components/sensor/tof10120.rst index 8badc342b9..50bb564cba 100644 --- a/components/sensor/tof10120.rst +++ b/components/sensor/tof10120.rst @@ -6,7 +6,7 @@ TOF10120 Time Of Flight Distance Sensor :image: tof10120.jpg :keywords: TOF10120 -The ``tof10120`` sensor platform allows you to use TOF10120 optical time of flight sensor (`datasheet `__) +The ``tof10120`` sensor platform allows you to use TOF10120 optical time of flight sensor (`datasheet `__) with ESPHome to measure distances. The sensor works optically by emitting short infrared pulses and measuring the time it takes the light to be reflected back. @@ -37,11 +37,9 @@ required to be set up in your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **address** (*Optional*, int): Manually specify the I^2C address of the sensor. Defaults to ``0x52``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/total_daily_energy.rst b/components/sensor/total_daily_energy.rst index 3fcd895817..cd1b0bff67 100644 --- a/components/sensor/total_daily_energy.rst +++ b/components/sensor/total_daily_energy.rst @@ -43,8 +43,6 @@ Configuration variables: - **power_id** (**Required**, :ref:`config-id`): The ID of the power sensor to integrate over time. -- **name** (**Required**, string): The name of the sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **restore** (*Optional*, boolean): Whether to store the intermediate result on the device so that the value can be restored upon power cycle or reboot. Defaults to ``true``. @@ -71,12 +69,30 @@ Some sensors such as the :doc:`HLW8012 ` expose their power sensor with - multiply: 0.001 unit_of_measurement: kW +Lifetime instead of Daily +------------------------- + +For a more-generic version of this component which does not reset every midnight, see :doc:`integration`, which can provide device-lifetime values instead of daily values with the following example settings: + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: integration + name: 'Total Energy' + sensor: my_power + time_unit: h + restore: true + state_class: total_increasing + device_class: energy + See Also -------- - :ref:`sensor-filters` - :doc:`hlw8012` - :doc:`cse7766` +- :doc:`integration` - :doc:`/components/sensor/pulse_counter` - :doc:`/components/sensor/pulse_meter` - :doc:`/components/time/homeassistant` diff --git a/components/sensor/tsl2561.rst b/components/sensor/tsl2561.rst index 9e88a8ae0c..1c0afbaf94 100644 --- a/components/sensor/tsl2561.rst +++ b/components/sensor/tsl2561.rst @@ -36,7 +36,6 @@ your configuration for this sensor to work. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the sensor. - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x39``. - **integration_time** (*Optional*, :ref:`config-time`): The time the sensor will take for each measurement. Longer means more accurate values. One of @@ -48,7 +47,6 @@ Configuration variables: package. 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. - All other options from :ref:`Sensor `. See Also diff --git a/components/sensor/tsl2591.rst b/components/sensor/tsl2591.rst index a7df0e95e6..e5f97f1ee6 100644 --- a/components/sensor/tsl2591.rst +++ b/components/sensor/tsl2591.rst @@ -154,28 +154,23 @@ Each configured sensor is reported separately on each ``update_interval``. - **full_spectrum** (*Optional*): The reading for the full spectrum sensor. - - **name** (**Required**, string): The name for the sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **infrared** (*Optional*): The reading for the infrared sensor. - - **name** (**Required**, string): The name for the sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **visible** (*Optional*): The reading for visible light. - - **name** (**Required**, string): The name for the sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **calculated_lux** (*Optional*): The value of the calculated lux. - - **name** (**Required**, string): The name for the sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **actual_gain** (*Optional*): The value of gain used for reported values. Particularly useful when gain is set to "auto". - - **name** (**Required**, string): The name for the sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Power save mode ............... diff --git a/components/sensor/tuya.rst b/components/sensor/tuya.rst index da036ae6be..470db3c64f 100644 --- a/components/sensor/tuya.rst +++ b/components/sensor/tuya.rst @@ -35,8 +35,6 @@ Based on this, you can create the sensor as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **sensor_datapoint** (**Required**, int): The datapoint id number of the sensor. - All other options from :ref:`Sensor `. diff --git a/components/sensor/tx20.rst b/components/sensor/tx20.rst index b4414262f0..d6944c8569 100644 --- a/components/sensor/tx20.rst +++ b/components/sensor/tx20.rst @@ -7,8 +7,6 @@ TX20/TX23 Wind Speed/Direction Sensor :keywords: TX20 The ``tx20`` sensor platform allows you to use your TX20/TX23 -(`Amazon`_, -`lacrosse_tx23`_) wind direction and speed sensors with ESPHome. The only required pin is the black or brown cable (which is used to transmit data.) The red cable should be connected to VCC (3.3V), green initiates the data transfer when connected to GND @@ -23,9 +21,6 @@ connected to GND in the TX20. TX20 / TX23 Wind Speed / Direction. -.. _Amazon: https://www.amazon.de/Technoline-Tx-20/dp/B01HXZ3KLA -.. _lacrosse_tx23: https://www.lacrossetechnology.com/tx23-wind-sensor - .. code-block:: yaml # Example configuration entry @@ -66,14 +61,20 @@ Configuration variables: return {id(tx20_id).get_wind_cardinal_direction()}; update_interval: 2s +.. note:: + + It appears that the manufacturer discontinued production of this sensor, as it doesn't seem to be available anymore for purchase. + There are various alternatives though, and since ESPHome has a :doc:`/components/modbus`, any model supporting RS485 connection + can be easily integrated. + + Check out in the ESPHome Devices database example configurations for + `RS-FSJT-N01 Wind Speed `__ and + `RS-FXJT-N01 Wind Direction `__ sensors. See Also -------- - :ref:`sensor-filters` - :apiref:`tx20/tx20.h` -- `Amazon Tx20 `__ -- `La Crosse Tx23 `__ - `Datagram Tx20 `__ -- `Datagram Tx23 `__- - :ghedit:`Edit` diff --git a/components/sensor/ultrasonic.rst b/components/sensor/ultrasonic.rst index 0fc25fa343..bf36bf2e15 100644 --- a/components/sensor/ultrasonic.rst +++ b/components/sensor/ultrasonic.rst @@ -46,7 +46,6 @@ Configuration variables: periodically send the trigger pulse to. - **echo_pin** (**Required**, :ref:`Pin Schema `): The input pin on which to wait for the echo. -- **name** (**Required**, string): The name of the sensor. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - All other options from :ref:`Sensor `. diff --git a/components/sensor/uptime.rst b/components/sensor/uptime.rst index c1f6db763f..7f1103d21c 100644 --- a/components/sensor/uptime.rst +++ b/components/sensor/uptime.rst @@ -13,16 +13,20 @@ Time rollovers are automatically handled. # Example configuration entry sensor: - platform: uptime + type: seconds name: Uptime Sensor Configuration variables: ------------------------ -- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +- **type** (*Optional*): Either: -- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. -- All other options from :ref:`Sensor `. + - ``seconds`` (*default*): A simple counter. + - ``timestamp``: presents the time ESPHome last booted up. Requires a :doc:`/components/time/index`. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + Valid only with ``type: seconds``. +- All other options from :ref:`Sensor `. See Also -------- diff --git a/components/sensor/veml7700.rst b/components/sensor/veml7700.rst index cacb844ffa..fe92a0099f 100644 --- a/components/sensor/veml7700.rst +++ b/components/sensor/veml7700.rst @@ -7,11 +7,11 @@ VEML7700 and VEML6030 Ambient Light Sensors :keywords: VEML7700, VEML6300 The ``veml7700`` sensor platform allows you to use the Vishay VEML7700 and VEML6030 ambient light sensors with ESPHome. -Communication with the device is over :ref:`I²C `, which must be present in your configuration. VEML7700 and VEML6030 -are basically the same but in different packages. The VEML7700 uses a fixed address of ``0x10``, while the smaller VEML6030 +Communication with the device is over :ref:`I²C `, which must be present in your configuration. VEML7700 and VEML6030 +are basically the same but in different packages. The VEML7700 uses a fixed address of ``0x10``, while the smaller VEML6030 can be configured to use either ``0x10`` or ``0x48``. -The VEML 7700/6030 devices are available on breakout boards from a number of vendors including `Adafruit`_, `SparkFun`_, +The VEML 7700/6030 devices are available on breakout boards from a number of vendors including `Adafruit`_, `SparkFun`_, `DFRobot`_, and others. .. _Adafruit: http://www.adafruit.com/products/4162 @@ -20,7 +20,7 @@ The VEML 7700/6030 devices are available on breakout boards from a number of ven .. figure:: images/veml7700-full.jpg - :align: center + :align: center :width: 70.0% VEML7700 Ambient Light Sensor on a board and standalone sensors. @@ -33,7 +33,7 @@ The VEML 7700/6030 devices are available on breakout boards from a number of ven The sensor is a high accuracy ambient light digital 16-bit resolution sensor with dynamic range from 0 lux to about 120,000 lux. Its wide range of measurements is enabled by four configurable *gain* levels and six different *integration time* options. -Higher gain values are typically used for lower light conditions. +Higher gain values are typically used for lower light conditions. The sensor has two photodiodes with different spectral response represented by two channels: an *ALS* channel and a *WHITE* channel. The *ALS*, or *Ambient light* channel follows a so-called human eye curve very closely. The *WHITE* channel covers a much wider wavelength/spectrum, capturing quite a lot of near-infrared radiance. @@ -50,12 +50,12 @@ taking several measurements. To do so, it follows a process recommended by the Should you desire to manually control those parameters - please note that: -- Gain levels of 1/8 and 1/4 shall be used in most cases. +- Gain levels of 1/8 and 1/4 shall be used in most cases. - Gain levels of 1 an 2 are only intended to be used in low light conditions < 100 lux. For very high illuminations it shows high non-linearity. -- In the range of 0 lux - 1000 lux the sensor measurements are stricly linear for Gain 1/4 and 1/8, after 1000 lux it shows non-linearity. +- In the range of 0 lux - 1000 lux the sensor measurements are stricly linear for Gain 1/4 and 1/8, after 1000 lux it shows non-linearity. -A lux compensation formula is used to get better readings in bright conditions. +A lux compensation formula is used to get better readings in bright conditions. However, it gives quite high error in very bright direct sunlight (instead of 100-120 kilolux it might give 150-200k+). This Wikipedia `article `__ has a table of some lux values for comparison. @@ -63,9 +63,9 @@ This Wikipedia `article `__ has a table of so Automatic measurement mode -------------------------- -In automatic measurement mode the component starts from Gain 1/8 and 100 ms (*default*). +In automatic measurement mode the component starts from Gain 1/8 and 100 ms (*default*). -- If illuminance is higher than 46 lx (100 counts) it gradually reduces integration time to get good reading (best in range 100 - 10,000 counts). +- If illuminance is higher than 46 lx (100 counts) it gradually reduces integration time to get good reading (best in range 100 - 10,000 counts). - In case of low illuminance (less than 46 lx) it tries to gradually increase gain and only then increase integration time. Please note, that in low light conditions measurement process might take several seconds due to long exposure periods and sensor reconfigurations. @@ -119,11 +119,11 @@ Example configuration - platform: veml7700 address: 0x10 update_interval: 60s - + # short variant of sensor definition: ambient_light: "Ambient light" # longer variant of sensor definition: - actual_gain: + actual_gain: name: "Actual gain" @@ -134,24 +134,24 @@ Configuration variables: - **integration_time** (*Optional*, :ref:`config-time`): The amount of time the sensor is exposed. Valid values are ``25ms``, ``50ms``, ``100ms`` *(default)*, ``200ms``, ``400ms``, ``800ms``. *In automatic mode it sets starting value*. -- **gain** (*Optional*, string): The gain the device will use for the internal ADC. Valid values are +- **gain** (*Optional*, string): The gain the device will use for the internal ADC. Valid values are ``1/8x`` *(default)*, ``1/4x``, ``1x``, ``2x``. Higher values are better in low-light conditions. *In automatic mode it sets starting gain value*. - **lux_compensation** (*Optional*, boolean): Lux compensation formula is used as per manufacturer. Defaults to ``True``. -- **glass_attenuation_factor** (*Optional*): The attenuation factor of glass if it's behind some glass +- **glass_attenuation_factor** (*Optional*): The attenuation factor of glass if it's behind some glass or plastic facia. Default is ``1.0`` means ``100%`` transmissivity. ``2`` means ``50%`` transmissivity etc. - **update_interval** (*Optional*, :ref:`config-time`): The interval for checking the sensors. Defaults to ``60s``. -- All other options for I²C devices described at :ref:`I²C Bus `. +- All other options for I²C devices described at :ref:`I²C Bus `. The sensor supports bus modes "standard" and "fast": 10 kHz to 400 kHz. Sensors ....... You can configure all or any subset of the sensors described earlier. -Each configured sensor is reported separately on each ``update_interval``. **name** (**Required**, string) is required for -every sensor. All other options from :ref:`Sensor `. +Each configured sensor is reported separately on each ``update_interval``. +All options from :ref:`Sensor ` are supported. However, if you don't need any other options, you can just use shorthands like this: ``ambient_light: Ambient light``. diff --git a/components/sensor/wifi_signal.rst b/components/sensor/wifi_signal.rst index 63b8ff905a..54933f64a2 100644 --- a/components/sensor/wifi_signal.rst +++ b/components/sensor/wifi_signal.rst @@ -34,7 +34,7 @@ To additionally display signal strength in percentage use the :ref:`copy-sensor` id: wifi_signal_db update_interval: 60s entity_category: "diagnostic" - + - platform: copy # Reports the WiFi signal strength in % source_id: wifi_signal_db name: "WiFi Signal Percent" @@ -47,10 +47,8 @@ To additionally display signal strength in percentage use the :ref:`copy-sensor` Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the WiFi signal sensor. - **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. - All other options from :ref:`Sensor `. .. warning:: diff --git a/components/sensor/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index cee4a1a6af..74d35e06a5 100644 --- a/components/sensor/xiaomi_ble.rst +++ b/components/sensor/xiaomi_ble.rst @@ -4,7 +4,7 @@ Xiaomi Mijia BLE Sensors .. seo:: :description: Instructions for setting up Xiaomi Mi Home (Mijia) bluetooth-based sensors in ESPHome. :image: xiaomi_mijia_logo.jpg - :keywords: Xiaomi, Mi Home, Mijia, BLE, Bluetooth, HHCCJCY01, GCLS002, HHCCPOT002, LYWSDCGQ, LYWSD02, CGG1, LYWSD03MMC, CGD1, JQJCY01YM, MUE4094RT, WX08ZM, MHO, C401, MHOC401 + :keywords: Xiaomi, Mi Home, Mijia, BLE, Bluetooth, HHCCJCY01, GCLS002, HHCCPOT002, LYWSDCGQ, LYWSD02, LYWSD02MMC, CGG1, LYWSD03MMC, CGD1, JQJCY01YM, MUE4094RT, WX08ZM, MHO, C401, MHOC401 The ``xiaomi_ble`` sensor platform lets you track the output of Xiaomi Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component will track, for example, the temperature, humidity, moisture, conductivity, illuminance, formaldehyde, mosquito tablet and battery level of the device every time the sensor sends out a BLE broadcast. Contrary to other implementations, ``xiaomi_ble`` listens passively to advertisement packets and does not pair with the device. Hence ESPHome has no impact on battery life. Thus, if you only use such sensors, you can safely set ``scan_parameters.active: false`` in ``esp32_ble_tracker`` configuration, to save from spamming your RF environment with useless scan requests. @@ -32,7 +32,7 @@ Configuration example: sensor: - platform: xiaomi_hhccjcy01 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY01 Temperature" moisture: @@ -64,7 +64,7 @@ Configuration example: sensor: - platform: xiaomi_gcls002 - mac_address: "94:2B:FF:5C:91:61" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "GCLS02 Temperature" moisture: @@ -89,7 +89,7 @@ Configuration example: sensor: - platform: xiaomi_hhccpot002 - mac_address: "94:2B:FF:5C:91:61" + mac_address: XX:XX:XX:XX:XX:XX moisture: name: "HHCCPOT002 Moisture" conductivity: @@ -110,7 +110,7 @@ Configuration example: sensor: - platform: xiaomi_lywsdcgq - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "LYWSDCGQ Temperature" humidity: @@ -135,7 +135,7 @@ Configuration example: sensor: - platform: xiaomi_lywsd02 - mac_address: "3F:5B:7D:82:58:4E" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "LYWSD02 Temperature" humidity: @@ -143,6 +143,26 @@ Configuration example: battery_level: name: "LYWSD02 Battery Level" +LYWSD02MMC +********** + +Hygro thermometer, rectangular body, e-ink display, broadcasts temperature, humidity and battery level. Encrypted. + +Configuration example: + +.. code-block:: yaml + + sensor: + - platform: xiaomi_lywsd02mmc + mac_address: "A4:C1:38:54:5E:18" + bindkey: "2529d8e0d23150a588675cc54ad48400" + temperature: + name: "LYWSD02MMC Temperature" + humidity: + name: "LYWSD02MMC Humidity" + battery_level: + name: "LYWSD02MMC Battery Level" + CGG1 **** @@ -160,7 +180,7 @@ Configuration example: sensor: - platform: xiaomi_cgg1 - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "CGG1 Temperature" humidity: @@ -168,7 +188,7 @@ Configuration example: battery_level: name: "CGG1 Battery Level" - platform: xiaomi_cgg1 - mac_address: "7A:80:8E:28:39:CD" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "00112233445566778899aabbccddeeff" temperature: name: "CGG1 (New) Temperature" @@ -200,7 +220,7 @@ Configuration example for Xiaomi stock firmware or ATC MiThermometer firmware se sensor: - platform: xiaomi_lywsd03mmc - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "eef418daf699a0c188f3bfd17e4565d9" temperature: name: "LYWSD03MMC Temperature" @@ -215,7 +235,7 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -233,7 +253,7 @@ Configuration example for ATC MiThermometer firmware set to "Custom" advertiseme sensor: - platform: atc_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "ATC Temperature" humidity: @@ -263,7 +283,7 @@ Configuration example: sensor: - platform: xiaomi_mhoc303 - mac_address: "E7:50:59:32:A0:1C" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "MHO-C303 Climate Temperature" humidity: @@ -296,7 +316,7 @@ Configuration example for Xiaomi stock firmware: sensor: - platform: xiaomi_mhoc401 - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "eef418daf699a0c188f3bfd17e4565d9" temperature: name: "MHOC401 Temperature" @@ -311,7 +331,7 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem sensor: - platform: pvvx_mithermometer - mac_address: "A4:C1:38:B1:CD:7F" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "PVVX Temperature" humidity: @@ -337,7 +357,7 @@ Configuration example: sensor: - platform: xiaomi_cgd1 - mac_address: "A4:C1:38:8C:34:B7" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "fe39106baeedb7c801e3d63c4396f97e" temperature: name: "CGD1 Temperature" @@ -362,7 +382,7 @@ Configuration example: sensor: - platform: xiaomi_cgdk2 - mac_address: "58:2D:34:11:34:B7" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "fe39106baeedb7c801e3d63c4396f97e" temperature: name: "CGDK2 Temperature" @@ -386,7 +406,7 @@ Configuration example: sensor: - platform: xiaomi_jqjcy01ym - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "JQJCY01YM Temperature" humidity: @@ -413,7 +433,7 @@ Configuration example: binary_sensor: - platform: xiaomi_wx08zm - mac_address: "74:a3:4a:b5:07:34" + mac_address: XX:XX:XX:XX:XX:XX tablet: name: "WX08ZM Mosquito Tablet" battery_level: @@ -437,7 +457,7 @@ Configuration example: binary_sensor: - platform: xiaomi_mue4094rt name: "MUE4094RT Night Light" - mac_address: "7A:80:8E:19:36:BA" + mac_address: XX:XX:XX:XX:XX:XX timeout: "5s" MJYD02YL-A @@ -458,7 +478,7 @@ Configuration example: binary_sensor: - platform: xiaomi_mjyd02yla name: "MJYD02YL-A Night Light" - mac_address: "50:EC:50:CD:32:02" + mac_address: XX:XX:XX:XX:XX:XX bindkey: "48403ebe2d385db8d0c187f81e62cb64" idle_time: name: "MJYD02YL-A Idle Time" @@ -485,7 +505,7 @@ Configuration example: binary_sensor: - platform: xiaomi_cgpr1 name: "CGPR1 Motion detector" - mac_address: 58:2D:34:60:32:A2 + mac_address: XX:XX:XX:XX:XX:XX bindkey: "ff1ae526b23b4aebeadcaaad86f59055" idle_time: name: "CGPR1 Idle Time" @@ -510,7 +530,7 @@ Configuration example: xiaomi_rtcgq02lm: - id: motion_one - mac_address: 01:23:45:67:89:AB + mac_address: XX:XX:XX:XX:XX:XX bindkey: fe39106baeedb7c801e3d63c4396f97e binary_sensor: @@ -539,7 +559,7 @@ Required: - **mac_address** (MAC Address): The MAC address of the device. - **bindkey** (string, 32 characters, case insensitive): The key to decrypt the BLE advertisements for encrypted sensor types -Optional with **name**, **id** (:ref:`config-id`) and all other options from :ref:`Sensor `: +All options from :ref:`Sensor ` are supported for: - **temperature** - **humidity** @@ -567,11 +587,11 @@ After uploading, the ESP32 will immediately try to scan for BLE devices. When it .. code:: - Found device A4:C1:38:4E:16:78 RSSI=-78 + Found device XX:XX:XX:XX:XX:XX RSSI=-78 Address Type: PUBLIC Name: 'LYWSD03MMC' -It can sometimes take some time for the first BLE broadcast to be received. Once the device has been found, copy the address ``A4:C1:38:4E:16:78`` into a new platform entry like shown in the example configurations. +It can sometimes take some time for the first BLE broadcast to be received. Once the device has been found, copy the address ``XX:XX:XX:XX:XX:XX`` into a new platform entry like shown in the example configurations. .. _obtaining_the_bindkey: @@ -621,7 +641,7 @@ Another option is to use a SSL packet sniffer. It can be setup on either an Andr packet: POST /app/device/bltbind - "data" = "{"did":"blt.3.129q4nasgeg00","token":"20c665a7ff82a5bfb5eefc36","props":[{"type":"prop","key":"bind_key","value":"cfc7cc892f4e32f7a733086cf3443cb0"}, {"type":"prop","key":"smac","value":"A4:C1:38:8C:34:B7"}]}" + "data" = "{"did":"blt.3.129q4nasgeg00","token":"20c665a7ff82a5bfb5eefc36","props":[{"type":"prop","key":"bind_key","value":"cfc7cc892f4e32f7a733086cf3443cb0"}, {"type":"prop","key":"smac","value":XX:XX:XX:XX:XX:XX}]}" The ``bind_key`` is the 32 digits "value" item in the above output which needs to be inserted into the config file. diff --git a/components/sensor/xiaomi_hhccjcy10.rst b/components/sensor/xiaomi_hhccjcy10.rst index d70aad5e8f..54328bc17f 100644 --- a/components/sensor/xiaomi_hhccjcy10.rst +++ b/components/sensor/xiaomi_hhccjcy10.rst @@ -16,7 +16,7 @@ MiFlora, tuya (pink) version, measures temperature, moisture, ambient light and sensor: - platform: xiaomi_hhccjcy10 - mac_address: '94:2B:FF:5C:91:61' + mac_address: XX:XX:XX:XX:XX:XX temperature: name: "Xiaomi HHCCJCY10 Temperature" moisture: diff --git a/components/sensor/xiaomi_miscale.rst b/components/sensor/xiaomi_miscale.rst index c054788d98..4860035b0c 100644 --- a/components/sensor/xiaomi_miscale.rst +++ b/components/sensor/xiaomi_miscale.rst @@ -26,7 +26,7 @@ Miscale (left) measures weight only. Miscale2 (right) measures weight and impeda sensor: - platform: xiaomi_miscale - mac_address: '5C:CA:D3:70:D4:A2' + mac_address: XX:XX:XX:XX:XX:XX weight: name: "Xiaomi Mi Scale Weight" impedance: @@ -38,13 +38,11 @@ Configuration variables: - **mac_address** (**Required**, MAC Address): The MAC address of the scale. - **weight** (*Optional*): The information for the weight sensor. - - **name** (**Required**, string): The name for the weight sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **impedance** (*Optional*): The information for the impedance sensor. **Only available on MiScale2** - - **name** (**Required**, string): The name for the impedance sensor. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **clear_impedance** (*Optional*): Clear the impedance information if a weight reading without impedance is received. Defaults to ``false``. **Only available on MiScale2** @@ -59,7 +57,7 @@ You have to replace the numbers in the lambdas to determine your weight which is sensor: - platform: xiaomi_miscale - mac_address: '5C:CA:D3:70:D4:A2' + mac_address: XX:XX:XX:XX:XX:XX weight: name: "Xiaomi Mi Scale Weight" id: weight_miscale diff --git a/components/sensor/zyaura.rst b/components/sensor/zyaura.rst index 1f7f81619f..ee6d9441fc 100644 --- a/components/sensor/zyaura.rst +++ b/components/sensor/zyaura.rst @@ -46,21 +46,15 @@ Configuration variables: - **data_pin** (**Required**, :ref:`config-pin`): The pin where the data bus is connected. - **co2** (*Optional*): The information for the CO2 sensor. - - **name** (**Required**, string): The name for the CO2 sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **temperature** (*Optional*): The information for the temperature sensor. - - **name** (**Required**, string): The name for the temperature sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor - - **name** (**Required**, string): The name for the humidity sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. diff --git a/components/sim800l.rst b/components/sim800l.rst index 4babcb9e61..7d7af7f0a1 100644 --- a/components/sim800l.rst +++ b/components/sim800l.rst @@ -76,9 +76,7 @@ Configuration variables: - **rssi** (*Optional*): The informed Received signal strength indication (RSSI) in dBm. - - **name** (**Required**, string): The name for the rssi sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Sensor `. + - All options from :ref:`Sensor `. Binary Sensor @@ -95,9 +93,7 @@ Configuration variables: - **registered** (*Optional*): Indicates if the SIM800L has successfully registered in the cellular network. - - **name** (**Required**, string): The name for the registered binary sensor. - - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - All other options from :ref:`Binary Sensor `. + - All options from :ref:`Binary Sensor `. .. _sim800l-on_sms_received: @@ -249,8 +245,8 @@ on Home Assistant and will also setup a service so you can send messages and dia .. code-block:: yaml api: - services: - - service: send_sms + actions: + - action: send_sms variables: recipient: string message: string @@ -258,19 +254,19 @@ on Home Assistant and will also setup a service so you can send messages and dia - sim800l.send_sms: recipient: !lambda 'return recipient;' message: !lambda 'return message;' - - service: dial + - action: dial variables: recipient: string then: - sim800l.dial: recipient: !lambda 'return recipient;' - - service: connect + - action: connect then: - sim800l.connect - - service: disconnect + - action: disconnect then: - sim800l.disconnect - - service: send_ussd + - action: send_ussd variables: ussdCode: string then: @@ -324,11 +320,11 @@ To trigger the automation from Home Assistant you can invoke the service with th automation: # ... action: - - service: esphome.livingroom_send_sms + - action: esphome.livingroom_send_sms data: recipient: "+15551234567" message: "Hello World!" - - service: esphome.livingroom_dial + - action: esphome.livingroom_dial data: recipient: "+15551234567" @@ -340,7 +336,7 @@ Relay management commands received from an authorized sender: sim800l: on_sms_received: - lambda: |- - if ( (id(sms_sender).state == "+79991234567") && ( (id(sms_message).state == "relay_1_on") OR (id(sms_message).state == "Relay_1_on") ) ) { + if ( (id(sms_sender).state == "+79991234567") && ( (id(sms_message).state == "relay_1_on") || (id(sms_message).state == "Relay_1_on") ) ) { id(relay_1).turn_on(); } switch: diff --git a/components/speaker/index.rst b/components/speaker/index.rst index 045d3bab07..aa9279ad9a 100644 --- a/components/speaker/index.rst +++ b/components/speaker/index.rst @@ -60,6 +60,17 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. +.. _speaker-finish: + +``speaker.finish`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will stop playing audio data from the speaker after all data **is** played. + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. + .. _speaker-conditions: Speaker Conditions @@ -79,6 +90,21 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): The speaker to check. Defaults to the only one in YAML. +.. _speaker-is_stopped: + +``speaker.is_stopped`` Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This condition will check if the speaker is fully stopped audio data and is in idle mode. + +.. note: + +Between the time ``speaker.is_playing`` is false and ``speaker.is_stopped`` is true the 'speaker' component is closing down structures that where used to play the data correctly. *It better to check if the speaker is stopped then that if it plays.* + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): The speaker to check. Defaults to the only one in YAML. + Platforms --------- diff --git a/components/sprinkler.rst b/components/sprinkler.rst index 0221411f93..7e9d1706da 100644 --- a/components/sprinkler.rst +++ b/components/sprinkler.rst @@ -1087,38 +1087,38 @@ memory use. Expose Sprinkler Controller Actions via user-API ************************************************ -This configuration snippet illustrates how user-defined ESPHome API services may be used to expose +This configuration snippet illustrates how user-defined ESPHome API actions may be used to expose various sprinkler controller actions to the front end. This could be useful to change settings and/or trigger sprinkler controller actions using automations. .. code-block:: yaml api: - services: - - service: set_multiplier + actions: + - action: set_multiplier variables: multiplier: float then: - sprinkler.set_multiplier: id: lawn_sprinkler_ctrlr multiplier: !lambda 'return multiplier;' - - service: start_full_cycle + - action: start_full_cycle then: - sprinkler.start_full_cycle: lawn_sprinkler_ctrlr - - service: start_single_valve + - action: start_single_valve variables: valve: int then: - sprinkler.start_single_valve: id: lawn_sprinkler_ctrlr valve_number: !lambda 'return valve;' - - service: next_valve + - action: next_valve then: - sprinkler.next_valve: lawn_sprinkler_ctrlr - - service: previous_valve + - action: previous_valve then: - sprinkler.previous_valve: lawn_sprinkler_ctrlr - - service: shutdown + - action: shutdown then: - sprinkler.shutdown: lawn_sprinkler_ctrlr diff --git a/components/stepper/index.rst b/components/stepper/index.rst index ea3225b3c1..7c513cc401 100644 --- a/components/stepper/index.rst +++ b/components/stepper/index.rst @@ -153,7 +153,7 @@ Configuration options: .. warning:: - This turns the stepper to an absolute position! To have the servo move *relative* to the current + This turns the stepper to an absolute position! To have the stepper motor move *relative* to the current position, first reset the current position and then set the target to the relative value. .. code-block:: yaml diff --git a/components/substitutions.rst b/components/substitutions.rst new file mode 100644 index 0000000000..ab83615eef --- /dev/null +++ b/components/substitutions.rst @@ -0,0 +1,162 @@ +Substitutions +============= + +.. seo:: + :description: How to use substitutions in ESPHome + :image: settings.svg + +ESPHome has a powerful way to reduce repetition in configuration files: substitutions. +With substitutions, you can have a single generic source file for all nodes of one kind and +substitute expressions in as required. + +.. code-block:: yaml + + substitutions: + bme280_temperature_offset: "-1.0" + + sensor: + - platform: bme280_i2c + temperature: + name: BME280 Temperature + filters: + - offset: ${bme280_temperature_offset} + + +In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before +validating your configuration, ESPHome will automatically replace all occurrences of substitutions +by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or +``${substitution_key}`` (same). + +Two substitution passes are performed allowing compound replacements. + +.. code-block:: yaml + + substitutions: + foo: yellow + bar_yellow_value: !secret yellow_secret + bar_green_value: !secret green_secret + + something: + test: ${bar_${foo}_value} + +.. _substitute-include-variables: + +Substitute !include variables +----------------------------- + +ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file. + +.. code-block:: yaml + + binary_sensor: + - platform: gpio + id: button1 + pin: GPIOXX + on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax + - platform: gpio + id: button2 + pin: GPIOXX + on_multi_click: !include + # multi-line syntax + file: on-multi-click.yaml + vars: + id: 2 + +``on-multi-click.yaml``: + +.. code-block:: yaml + + - timing: !include click-single.yaml + then: + - mqtt.publish: + topic: ${device_name}/button${id}/status + payload: single + - timing: !include click-double.yaml + then: + - mqtt.publish: + topic: ${device_name}/button${id}/status + payload: double + +.. _command-line-substitutions: + +Command line substitutions +-------------------------- + +You can define or override substitutions from the command line by adding the ``-s`` switch with arguments ``KEY`` and +``VALUE``. This will override the substitution ``KEY`` and assign it the value ``VALUE``. This switch can be included +multiple times. Consider the following ``example.yaml`` file: + +.. code-block:: yaml + + substitutions: + name: my_default_name + + esphome: + name: $name + +...and the following command: + +.. code-block:: bash + + esphome -s name my_device01 config example.yaml + +You will get something like the following output: + +.. code-block:: yaml + + substitutions: + name: my_device01 + + esphome: + name: my_device01 + # ... + +Command line substitutions take precedence over those in your configuration file. This can be used to create generic +"template" configuration files (like ``example.yaml`` above) which can be used by multiple devices, leveraging +substitutions which are provided on the command line. + +.. _YAML-insertion-operator: + +Bonus: YAML insertion operator +------------------------------ + +Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number +of nodes inherit: + +.. code-block:: yaml + + # In common.yaml + esphome: + name: $devicename + # ... + + sensor: + - platform: dht + # ... + temperature: + name: Temperature + humidity: + name: Humidity + +.. code-block:: yaml + + # In nodemcu1.yaml + substitutions: + devicename: nodemcu1 + + <<: !include common.yaml + +.. tip:: + + To hide these base files from the dashboard, you can + + - Place them in a subdirectory (dashboard only shows files in top-level directory) + - Prepend a dot to the filename, like ``.base.yaml`` + +See Also +-------- + +- :doc:`ESPHome index ` +- :doc:`/guides/getting_started_command_line` +- :doc:`/guides/faq` +- :ghedit:`Edit` diff --git a/components/sun.rst b/components/sun.rst index 0e0b7d936b..656621a14b 100644 --- a/components/sun.rst +++ b/components/sun.rst @@ -81,8 +81,6 @@ Configuration variables: - **type** (**Required**, string): The type of value to track. One of ``elevation`` and ``azimuth``. -- **name** (**Required**, string): The name of the sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. ``sun`` Text Sensor @@ -109,13 +107,10 @@ Configuration variables: - **type** (**Required**, string): The type of value to track. One of ``sunrise`` and ``sunset``. -- **name** (**Required**, string): The name of the text sensor. - **elevation** (*Optional*, float): The elevation to calculate the next sunrise/sunset event for. Defaults to -0.833° (the horizon, slightly less than 0° to compensate for atmospheric refraction). - **format** (*Optional*, string): The format to format the time value with, see :ref:`strftime` for more information. Defaults to ``%X``. - -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Text Sensor `. .. _sun-is_above_below_horizon-condition: diff --git a/components/switch/ble_client.rst b/components/switch/ble_client.rst index 96b3599b9c..4e5d05e4f4 100644 --- a/components/switch/ble_client.rst +++ b/components/switch/ble_client.rst @@ -13,7 +13,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -23,7 +23,7 @@ For more information on BLE services and characteristics, see :doc:`/components/ esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black switch: @@ -35,7 +35,6 @@ Configuration variables: ------------------------ - **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client. -- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. - All other options from :ref:`Switch `. See Also diff --git a/components/switch/factory_reset.rst b/components/switch/factory_reset.rst index 8c9eb5b001..71c870448a 100644 --- a/components/switch/factory_reset.rst +++ b/components/switch/factory_reset.rst @@ -35,9 +35,7 @@ After reboot all states, parameters and variables will be reinitialized with the Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Switch `. +- All options from :ref:`Switch `. See Also -------- diff --git a/components/switch/homeassistant.rst b/components/switch/homeassistant.rst new file mode 100644 index 0000000000..177adb3af6 --- /dev/null +++ b/components/switch/homeassistant.rst @@ -0,0 +1,30 @@ +Home Assistant Switch +===================== + +.. seo:: + :description: Instructions for setting up Home Assistant Switch with ESPHome that import states and allows control via your Home Assistant instance. + :image: home-assistant.svg + +The ``homeassistant`` Switch platform allows you to create Switch that **import** +states and allow **control** via your Home Assistant instance using the :doc:`native API `. + +.. code-block:: yaml + + # Example configuration entry + switch: + - platform: homeassistant + id: my_cool_switch_from_ha + entity_id: switch.my_cool_switch + +Configuration variables: +------------------------ + +- **entity_id** (**Required**, string): The entity ID to import / control from Home Assistant. +- All other options from :ref:`Switch `. + +See Also +-------- + +- :ref:`automation` +- :apiref:`homeassistant/switch/homeassistant_switch.h` +- :ghedit:`Edit` diff --git a/components/switch/index.rst b/components/switch/index.rst index a9c8be4ca7..4cbca2778f 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -22,7 +22,8 @@ Base Switch Configuration Configuration variables: -- **name** (**Required**, string): The name of the switch. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the switch. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/switch/lvgl.rst b/components/switch/lvgl.rst new file mode 100644 index 0000000000..37a0478c27 --- /dev/null +++ b/components/switch/lvgl.rst @@ -0,0 +1,42 @@ +LVGL Switch +=========== + +.. seo:: + :description: Instructions for setting up an LVGL widget switch. + :image: ../images/lvgl_c_swi.png + +The ``lvgl`` switch platform creates a switch from an LVGL widget +and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-button` (with ``checkable`` option enabled), :ref:`lvgl-widget-switch` and :ref:`lvgl-widget-checkbox`. A single switch supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome switch component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the switch. +- All other variables from :ref:`Switch `. + +Example: + +.. code-block:: yaml + + switch: + - platform: lvgl + widget: checkbox_id + name: LVGL switch + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Button widget ` +- :ref:`Switch widget ` +- :ref:`Checkbox widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/text/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :doc:`/components/output/index` +- :ghedit:`Edit` diff --git a/components/switch/modbus_controller.rst b/components/switch/modbus_controller.rst index 5114fd47e5..bdbd0f8447 100644 --- a/components/switch/modbus_controller.rst +++ b/components/switch/modbus_controller.rst @@ -11,8 +11,6 @@ and requires :doc:`/components/modbus_controller` to be configured. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **register_type** (**Required**): type of the modbus register. - ``coil``: Coils are 1-bit registers (on/off values) that are used to control discrete outputs. They may be read and/or written. Modbus *Function Code 1 (Read Coil Status)* will be used. @@ -48,7 +46,7 @@ Configuration variables: See :ref:`modbus_custom_command` how to use ``custom_command`` - **offset** (*Optional*, int): Offset from start address in bytes (only required for uncommon response encodings). If more than one register is written in a command, this value is used to find the start of this datapoint relative to the start address. The component calculates the size of the range based on offset and size of the value type. The value for offset depends on the register type. For holding input registers, the offset is in bytes. For coil and discrete input resisters, the LSB of the first data byte contains the coil addressed in the request. The other coils follow toward the high-order end of this byte and from low order to high order in subsequent bytes. For registers, the offset is the position of the relevant bit. To get the value of the coil register, 2 can be retrieved using ``address: 2`` / ``offset: 0`` or ``address: 0`` / ``offset 2``. - **restore_mode** (*Optional*): See :ref:`Switch `, since this configuration variable is inherited. The default value for this setting is ``DISABLED`` (recommended). - ``DISABLED`` leaves the initial state up to the hardware: usually the state lives in the device and ESPHome does not need to remember it. The switch frontend will show an undetermined + ``DISABLED`` leaves the initial state up to the hardware: usually the state lives in the device and ESPHome does not need to remember it. The switch frontend will show an undetermined state until the real state is retrieved from the device on the next refresh. Use any other setting if a reboot of your ESPHome device is tied to a reboot of the modbus device. diff --git a/components/switch/nextion.rst b/components/switch/nextion.rst index b8055bd364..c7824a702d 100644 --- a/components/switch/nextion.rst +++ b/components/switch/nextion.rst @@ -34,7 +34,6 @@ See :doc:`/components/display/nextion` for setting up the display Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. - **component_name** (*Optional*, string): The name of the Nextion component. - **variable_name** (*Optional*, string): The name of the Nextion variable. Any value over ``0`` is considered to be **on** diff --git a/components/switch/output.rst b/components/switch/output.rst index 5282f35645..8d0a4a4934 100644 --- a/components/switch/output.rst +++ b/components/switch/output.rst @@ -27,9 +27,6 @@ Configuration variables: ------------------------ - **output** (**Required**, :ref:`config-id`): The ID of the output component to use. -- **name** (**Required**, string): The name for the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - - All other options from :ref:`Switch `. See Also diff --git a/components/switch/restart.rst b/components/switch/restart.rst index e66be7c1e5..b21f60e9b7 100644 --- a/components/switch/restart.rst +++ b/components/switch/restart.rst @@ -22,9 +22,7 @@ through Home Assistant. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Switch `. +- All options from :ref:`Switch `. See Also -------- diff --git a/components/switch/safe_mode.rst b/components/switch/safe_mode.rst index 9274eeb0e3..e53a627412 100644 --- a/components/switch/safe_mode.rst +++ b/components/switch/safe_mode.rst @@ -5,7 +5,7 @@ Safe Mode Switch :description: Instructions for setting up switches that can remotely reboot the ESP in ESPHome into safe mode. :image: restart.svg -The ``safe_mode`` switch allows you to remotely reboot your node into :doc:`/components/safe_mode`. This is useful in certain situations where a misbehaving component, or low memory state is preventing Over-The-Air updates from completing successfully. +The ``safe_mode`` switch allows you to remotely reboot your node into :doc:`/components/safe_mode`. This is useful in certain situations where a misbehaving component, or low memory state is preventing Over-The-Air updates from completing successfully. This component requires :doc:`/components/safe_mode` to be configured. @@ -23,9 +23,7 @@ This component requires :doc:`/components/safe_mode` to be configured. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Switch `. +- All options from :ref:`Switch `. See Also -------- diff --git a/components/switch/shutdown.rst b/components/switch/shutdown.rst index f2d331a865..7f1559e804 100644 --- a/components/switch/shutdown.rst +++ b/components/switch/shutdown.rst @@ -24,9 +24,7 @@ pressing the reset button or restarting the power supply. Configuration variables: ------------------------ -- **name** (**Required**, string): The name for the switch. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Switch `. +- All options from :ref:`Switch `. See Also -------- diff --git a/components/switch/template.rst b/components/switch/template.rst index 6164bbd58b..74aec5b79a 100644 --- a/components/switch/template.rst +++ b/components/switch/template.rst @@ -36,7 +36,6 @@ Possible return values for the optional lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the switch. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated repeatedly to get the current state of the switch. - **turn_on_action** (*Optional*, :ref:`Action `): The action that should @@ -49,7 +48,6 @@ Configuration variables: - **assumed_state** (*Optional*, boolean): Whether the true state of the switch is not known. This will make the Home Assistant frontend show buttons for both ON and OFF actions, instead of hiding one of them when the switch is ON/OFF. Defaults to ``false``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Switch `. .. _switch-template-publish_action: diff --git a/components/switch/tuya.rst b/components/switch/tuya.rst index 8f1136668b..0afff5a007 100644 --- a/components/switch/tuya.rst +++ b/components/switch/tuya.rst @@ -35,8 +35,6 @@ Based on this, you can create the switch as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the switch. - **switch_datapoint** (**Required**, int): The datapoint id number of the switch. - All other options from :ref:`Switch `. diff --git a/components/switch/uart.rst b/components/switch/uart.rst index 98957a318a..fc8d53c2a4 100644 --- a/components/switch/uart.rst +++ b/components/switch/uart.rst @@ -31,8 +31,6 @@ The ``uart`` switch platform allows you to send a pre-defined sequence of bytes Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (*Optional*, string): The name for the switch. - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub. - **data** (*Optional*, string or list of bytes): The data to send via UART. Either an ASCII string or a list of bytes or one or both of the following nested options (see example above). diff --git a/components/text/lvgl.rst b/components/text/lvgl.rst new file mode 100644 index 0000000000..78b16e11e3 --- /dev/null +++ b/components/text/lvgl.rst @@ -0,0 +1,43 @@ +LVGL Text +========= + +.. seo:: + :description: Instructions for setting up an LVGL Text component. + :image: ../images/lvgl_c_txt.png + +The ``lvgl`` text platform creates an editable text component from an LVGL textual widget and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-label` and :ref:`lvgl-widget-textarea`. A single text supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome text component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a ``textarea`` widget configured in LVGL, which will reflect the state of the text component. +- All other variables from :ref:`Text `. + +Example: + +.. code-block:: yaml + + text: + - platform: lvgl + widget: textarea_id + name: "Textarea 1 text" + +.. note:: + + Widget-specific actions (``lvgl.label.update``, ``lvgl.textarea.update``) will trigger correspponding component updates to be sent to Home Assistant. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Label widget ` +- :ref:`Textarea widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/text_sensor/lvgl` +- :ghedit:`Edit` diff --git a/components/text_sensor/ble_client.rst b/components/text_sensor/ble_client.rst index f3ba0cd37e..2f45e799a6 100644 --- a/components/text_sensor/ble_client.rst +++ b/components/text_sensor/ble_client.rst @@ -16,7 +16,7 @@ For more information on BLE services and characteristics, see esp32_ble_tracker: ble_client: - - mac_address: FF:FF:20:00:0F:15 + - mac_address: XX:XX:XX:XX:XX:XX id: itag_black text_sensor: @@ -33,7 +33,6 @@ Configuration variables: - **service_uuid** (**Required**, UUID): UUID of the service on the device. - **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query. - **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query. -- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. - **notify** (*Optional*, boolean): Instruct the server to send notifications for this characteristic. Defaults to ``false``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device. Defaults to ``60s``. diff --git a/components/text_sensor/ble_scanner.rst b/components/text_sensor/ble_scanner.rst index 6b4c0873e4..142c3cf294 100644 --- a/components/text_sensor/ble_scanner.rst +++ b/components/text_sensor/ble_scanner.rst @@ -19,7 +19,7 @@ the data in JSON format. .. warning:: The BLE software stack on the ESP32 consumes a significant amount of RAM on the device. - + **Crashes are likely to occur** if you include too many additional components in your device's configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other audio components are most likely to cause issues. @@ -39,7 +39,7 @@ Example json log: { "timestamp":1578254525, - "address":"D7:E7:E7:66:DD:33", + "address": "XX:XX:XX:XX:XX:XX", "rssi":"-80", "name":"MI Band 2" } @@ -47,8 +47,7 @@ Example json log: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. -- All other options from :ref:`Text Sensor `. +- All options from :ref:`Text Sensor `. See Also -------- diff --git a/components/text_sensor/homeassistant.rst b/components/text_sensor/homeassistant.rst index 31f332f8ef..f012ced2d2 100644 --- a/components/text_sensor/homeassistant.rst +++ b/components/text_sensor/homeassistant.rst @@ -13,7 +13,7 @@ states from your Home Assistant instance using the :doc:`native API `. See Also diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst index e6709e5070..e94f1a1bea 100644 --- a/components/text_sensor/index.rst +++ b/components/text_sensor/index.rst @@ -24,7 +24,8 @@ Base Text Sensor Configuration Configuration variables: -- **name** (**Required**, string): The name for the sensor. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the sensor. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/text_sensor/lvgl.rst b/components/text_sensor/lvgl.rst new file mode 100644 index 0000000000..61610f4230 --- /dev/null +++ b/components/text_sensor/lvgl.rst @@ -0,0 +1,44 @@ +LVGL Text Sensor +================ + +.. seo:: + :description: Instructions for setting up an LVGL Text Sensor. + :image: ../images/lvgl_c_txt.png + +The ``lvgl`` text sensor platform creates a Text Sensor from an LVGL textual widget +and requires :doc:`LVGL ` to be configured. + +Supported widgets are :ref:`lvgl-widget-label` and :ref:`lvgl-widget-textarea`. A single text sensor supports only a single widget; in other words, it's not possible to have multiple widgets associated with a single ESPHome text sensor component. + +Configuration variables: +------------------------ + +- **widget** (**Required**): The ID of a ``textarea`` widget configured in LVGL, which will reflect the state of the text sensor. +- All other variables from :ref:`Text Sensor `. + +Example: + +.. code-block:: yaml + + text_sensor: + - platform: lvgl + widget: textarea_id + name: "Textarea 1 text" + +.. note:: + + Widget-specific actions (``lvgl.label.update``, ``lvgl.textarea.update``) will trigger correspponding component updates to be sent to Home Assistant. + +See Also +-------- +- :doc:`LVGL Main component ` +- :ref:`Label widget ` +- :ref:`Textarea widget ` +- :doc:`/components/binary_sensor/lvgl` +- :doc:`/components/sensor/lvgl` +- :doc:`/components/number/lvgl` +- :doc:`/components/switch/lvgl` +- :doc:`/components/light/lvgl` +- :doc:`/components/select/lvgl` +- :doc:`/components/text/lvgl` +- :ghedit:`Edit` diff --git a/components/text_sensor/modbus_controller.rst b/components/text_sensor/modbus_controller.rst index f949ac7f22..6e8685808f 100644 --- a/components/text_sensor/modbus_controller.rst +++ b/components/text_sensor/modbus_controller.rst @@ -10,8 +10,6 @@ and requires :doc:`/components/modbus_controller` to be configured. Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **register_type** (**Required**): type of the modbus register. - ``coil``: Coils are 1-bit registers (on/off values) that are used to control discrete outputs. They may be read and/or written. Modbus *Function Code 1 (Read Coil Status)* will be used. @@ -53,7 +51,7 @@ Configuration variables: - ``return ;`` the new value for the sensor. - ``return {};`` uses the parsed value for the state (same as ``return x;``). -- **offset** (*Optional*, int): Offset from start address in bytes (only required for uncommon response encodings). If more than one register is written in a command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type. The value for offset depends on the register type. +- **offset** (*Optional*, int): Offset from start address in bytes (only required for uncommon response encodings). If more than one register is written in a command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type. The value for offset depends on the register type. - All options from :ref:`Text Sensor `. Example: diff --git a/components/text_sensor/mqtt_subscribe.rst b/components/text_sensor/mqtt_subscribe.rst index 17a6d59666..d0a96574f1 100644 --- a/components/text_sensor/mqtt_subscribe.rst +++ b/components/text_sensor/mqtt_subscribe.rst @@ -22,10 +22,8 @@ in its ``id(mysensor).state``. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the text sensor. - **topic** (**Required**, string): The MQTT topic to listen for string data. - **qos** (*Optional*, int): The MQTT QoS to subscribe with. Defaults to ``0``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Text Sensor `. Example Usage for Displays diff --git a/components/text_sensor/nextion.rst b/components/text_sensor/nextion.rst index 619ccb2e36..b50be7c734 100644 --- a/components/text_sensor/nextion.rst +++ b/components/text_sensor/nextion.rst @@ -32,7 +32,6 @@ See :doc:`/components/display/nextion` for setting up the display Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the sensor. - **nextion_id** (*Optional*, :ref:`config-id`): The ID of the Nextion display. - **component_name** (*Optional*, string): The name of the Nextion component. - **update_interval** (*Optional*, :ref:`config-time`): The duration to update the sensor. If using a :ref:`nextion_custom_text_sensor_protocol` this should not be used diff --git a/components/text_sensor/template.rst b/components/text_sensor/template.rst index 5886e5dcf3..abe085a80f 100644 --- a/components/text_sensor/template.rst +++ b/components/text_sensor/template.rst @@ -28,12 +28,10 @@ Possible return values for the lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the text sensor. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the new value of the text sensor - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the text sensor. Set to ``never`` to disable updates. Defaults to ``60s``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Text Sensor `. .. _text_sensor-template-publish_action: diff --git a/components/text_sensor/tuya.rst b/components/text_sensor/tuya.rst index 49c1a32ad3..deed0760a2 100644 --- a/components/text_sensor/tuya.rst +++ b/components/text_sensor/tuya.rst @@ -21,8 +21,6 @@ You can create the text sensor as follows: Configuration variables: ------------------------ -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the sensor. - **sensor_datapoint** (**Required**, int): The datapoint id number of the sensor. - All other options from :ref:`Text Sensor `. diff --git a/components/text_sensor/version.rst b/components/text_sensor/version.rst index dcb78dfd19..6e6a7923ae 100644 --- a/components/text_sensor/version.rst +++ b/components/text_sensor/version.rst @@ -21,15 +21,13 @@ was compiled against as a text sensor. Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the text sensor. - **hide_timestamp** (*Optional*, boolean): Allows you to hide the compilation timestamp from the version string. Defaults to ``false``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Text Sensor `. Disabling the compilation timestamp: ------------------------------------ -.. code-block:: yaml +.. code-block:: yaml # Example configuration entry text_sensor: diff --git a/components/tm1651.rst b/components/tm1651.rst index 51dc85144c..c439e348e3 100644 --- a/components/tm1651.rst +++ b/components/tm1651.rst @@ -133,14 +133,14 @@ You also can control this component with lambda expressions .. code-block:: yaml api: - services: - - service: battery_level + actions: + - action: battery_level variables: level: int then: - lambda: |- id(tm1651_battery).set_level(level); - - service: battery_brightness + - action: battery_brightness variables: brightness: int then: diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index b1c2d0e6fe..bfbb2c48da 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -292,14 +292,15 @@ buttons. Configuration variables: ************************ -- **name** (*Optional*, string): The name for the binary sensor. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **touchscreen_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the touchscreen. - **x_min** (**Required**, int): Left coordinate of the screen area to be detected as the virtual button. - **x_max** (**Required**, int): Right coordinate of the screen area to be detected as the virtual button. - **y_min** (**Required**, int): Top coordinate of the screen area to be detected as the virtual button. - **y_max** (**Required**, int): Bottom coordinate of the screen area to be detected as the virtual button. - **page_id** (*Optional*, :ref:`config-id`): Only trigger this binary sensor if the display is showing this page. + Cannot be used with ``pages``. +- **pages** (*Optional*, list of :ref:`config-id`): Only trigger this binary sensor if the display is showing one of these pages. + Cannot be used with ``page_id``. - All other options from :ref:`Binary Sensor `. diff --git a/components/tuya.rst b/components/tuya.rst index d941b8cf6c..57596d6dd2 100644 --- a/components/tuya.rst +++ b/components/tuya.rst @@ -140,5 +140,6 @@ See Also - :doc:`/components/binary_sensor/tuya` - :doc:`/components/sensor/tuya` - :doc:`/components/text_sensor/tuya` +- :doc:`/components/number/tuya` - :apiref:`tuya/tuya.h` - :ghedit:`Edit` diff --git a/components/uart.rst b/components/uart.rst index 9632381667..731273cdb8 100644 --- a/components/uart.rst +++ b/components/uart.rst @@ -38,6 +38,9 @@ In some cases only **TX** or **RX** exists as the device at the other end only a for the data being sent. This could cause unexpected issues if you are using the Software UART and have devices that explicity check the parity. Most likely you will need to flip the ``parity`` flag in YAML. +.. note:: + + UART implementation for the host platform does not use TX and RX pins but port names. .. code-block:: yaml @@ -51,8 +54,9 @@ Configuration variables: ------------------------ - **baud_rate** (**Required**, int): The baud rate of the UART bus. -- **tx_pin** (*Optional*, :ref:`config-pin`): The pin to send data to from the ESP's perspective. Use the full pin schema and set ``inverted: true`` to invert logic levels. -- **rx_pin** (*Optional*, :ref:`config-pin`): The pin to receive data on from the ESP's perspective. Use the full pin schema and set ``inverted: true`` to invert logic levels. +- **tx_pin** (*Optional*, :ref:`config-pin`): The pin to send data to from the ESP's perspective. Use the full pin schema and set ``inverted: true`` to invert logic levels. Not supported by host platform. +- **rx_pin** (*Optional*, :ref:`config-pin`): The pin to receive data on from the ESP's perspective. Use the full pin schema and set ``inverted: true`` to invert logic levels. Not supported by host platform. +- **port** (*Optional*, string): Host platform only. Unix style name of the port to use. - **rx_buffer_size** (*Optional*, int): The size of the buffer used for receiving UART messages. Increase if you use an integration that needs to read big payloads from UART. Defaults to ``256``. - **data_bits** (*Optional*, int): The number of data bits used on the UART bus. Options: 5 to 8. Defaults to 8. - **parity** (*Optional*): The parity used on the UART bus. Options: ``NONE``, ``EVEN``, ``ODD``. Defaults to ``NONE``. @@ -258,6 +262,20 @@ Below are the methods to read current settings and modify them dynamically: This flexibility allows for dynamic adaptation to different communication requirements, enhancing the versatility of your ESPHome setup. +UART component with the host platform +------------------------------------- + +Since the host platform does not have physical UART pins, the UART component is implemented using Unix-style ports. Instead of using pins, +you can specify the port name to use. This implementation also supports components that have ``require_tx`` and ``require_rx`` options such as +smt100 etc. + +.. code-block:: yaml + + # Example configuration entry for host platform + uart: + baud_rate: 9600 + port: "/dev/ttyUSB0" + See Also -------- diff --git a/components/update/index.rst b/components/update/index.rst index d4ac6a4c02..db15a876f5 100644 --- a/components/update/index.rst +++ b/components/update/index.rst @@ -21,8 +21,14 @@ install it on its own. Configuration variables: ------------------------ -- **name** (*Optional*, string): The name to use for the update component. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name of the update entity. At least one of **id** and **name** must be specified. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the light to use that name, you can set ``name: None``. + - **device_class** (*Optional*, string): The device class for the update entity. See https://www.home-assistant.io/integrations/binary_sensor/#device-class for a list of available options. - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend @@ -33,6 +39,31 @@ Configuration variables: - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Specifying an ``id`` without a ``name`` will implicitly set this to true. +- **on_update_available** (*Optional*, :ref:`Action `): An automation to perform when an update is available. + +Automations +----------- + +``update.perform`` Action +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This action allows you to trigger the update entity to start the update process. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the update entity. +- **force_update** (*Optional*, boolean): Perform the update even if the device is already running the same version. + Defaults to ``false``. + +``update.is_available`` Condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This condition checks if an update is available for the device. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the update entity. + See Also -------- diff --git a/components/valve/index.rst b/components/valve/index.rst index c6f196ac1e..912bc676cc 100644 --- a/components/valve/index.rst +++ b/components/valve/index.rst @@ -30,7 +30,8 @@ All valve config schemas inherit from this schema - you can set these keys for v Configuration variables: -- **name** (**Required**, string): The name for the valve. +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **name** (*Optional*, string): The name for the valve. At least one of **id** and **name** must be specified. .. note:: diff --git a/components/valve/template.rst b/components/valve/template.rst index f3d3ffb5c2..d295920e35 100644 --- a/components/valve/template.rst +++ b/components/valve/template.rst @@ -41,7 +41,6 @@ Possible return values for the optional lambda: Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the valve. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated repeatedly to get the current state of the valve. - **open_action** (*Optional*, :ref:`Action `): The action that should be performed when the remote @@ -52,6 +51,12 @@ Configuration variables: requests the valve to be stopped. - **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, any command sent to the template valve will immediately update the reported state and no lambda needs to be used. Defaults to ``false``. +- **restore_mode** (*Optional*, enum): Control how the valve attempts to restore state on bootup. + + - ``NO_RESTORE`` (Default): Do not save or restore state. + - ``RESTORE``: Attempts to restore the state on startup, but doesn't instruct the valve to return to that state. + - ``RESTORE_AND_CALL``: Attempts to restore the state on startup and instructs the valve to return to the restored state. + - **assumed_state** (*Optional*, boolean): Whether the true state of the valve is not known. This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead of hiding one of them. Defaults to ``false``. - **has_position** (*Optional*, boolean): Whether this valve will publish its position as a floating point number. @@ -59,7 +64,6 @@ Configuration variables: - **position_action** (*Optional*, :ref:`Action `): The action that should be performed when the remote (like Home Assistant's frontend) requests the valve be set to a specific position. The desired position is available in the lambda in the ``pos`` variable. Requires ``has_position`` (above) to be set to ``true``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Valve `. .. _valve-template-publish_action: diff --git a/components/web_server.rst b/components/web_server.rst index 2017ca752b..198d49c81a 100644 --- a/components/web_server.rst +++ b/components/web_server.rst @@ -140,8 +140,62 @@ V2 embeds the css within the js file so is not required, however you could inclu js_url: "" version: 2 + Copy https://oi.esphome.io/v2/www.js to a V2 folder in your yaml folder. + +.. _config-webserver-version-3-options: + +Version 3 features +--------------------------- + +Number in slider mode +********************* +.. figure:: /components/images/web_server/number-slider-popup.png + :align: left + :width: 100.0% + + +You can change the value by moving the slider. +If you wish to enter a precise number you can click and hold the current value. A popup input field will appear where you can enter a number and confirm your input by pressing the enter key. + +.. figure:: /components/images/web_server/number-slider-popup-input-field.png + :align: left + :width: 100.0% + + +Expand Controls and Logs +************************ +.. figure:: /components/images/web_server/tab-header-expand-cloapsed.png + :align: left + :width: 100.0% + + +By double-clicking on any group header you can expand the controls to fill up the whole screen. +You can do the same for the logs. + +.. figure:: /components/images/web_server/tab-header-expand-controls-expanded.png + :align: center + :width: 100.0% + + Expanded Controls + + +.. figure:: /components/images/web_server/tab-header-expand-logs-expanded.png + :align: center + :width: 100.0% + + Expanded Logs + + +Sensor value graph +****************** +.. figure:: /components/images/web_server/sensor-history-graph.png + :align: left + :width: 100.0% + +By clicking on any sensor it will expand a graph with the historical values for that sensor. + .. _config-webserver-sorting: Entity sorting diff --git a/conf.py b/conf.py index bb6562ff55..40c12c45e1 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2024.7" +version = "2024.9" # The full version, including alpha/beta/rc tags. -release = "2024.7.0-dev" +release = "2024.9.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/cookbook/http_request_sensor.rst b/cookbook/http_request_sensor.rst index 7180c0d2bf..b12e2d7e3f 100644 --- a/cookbook/http_request_sensor.rst +++ b/cookbook/http_request_sensor.rst @@ -23,8 +23,6 @@ On the client nodes we need an :doc:`/components/http_request` with an ``id`` se .. code-block:: yaml http_request: - useragent: esphome/device - id: http_request_id sensor: - platform: template @@ -35,7 +33,7 @@ On the client nodes we need an :doc:`/components/http_request` with an ``id`` se Pulling the data **************** -To automate the request for data, we use an :ref:`interval` requesting the URL pointing to the sensor id for which the state is needed. See :ref:`api-rest` on how to build up the URL for your sensors. +To automate the request for data, we use an :doc:`/components/interval` requesting the URL pointing to the sensor id for which the state is needed. See :ref:`api-rest` on how to build up the URL for your sensors. In the example below we request the value of a sensor from the server node, and after parsing the resulted JSON string we publish it to the local template sensor: @@ -118,6 +116,6 @@ See Also - :doc:`/components/web_server` - :doc:`/components/http_request` - :doc:`/components/sensor/template` -- :ref:`interval` +- :doc:`/components/interval` - :ref:`api-rest` - :ghedit:`Edit` diff --git a/cookbook/infostrip.rst b/cookbook/infostrip.rst index e20060aa8a..c0bf5e80cd 100644 --- a/cookbook/infostrip.rst +++ b/cookbook/infostrip.rst @@ -111,7 +111,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don above: 1000 condition: [] action: - - service: light.turn_on + - action: light.turn_on data: color_name: red entity_id: light.pl2 @@ -125,7 +125,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don below: 800 condition: [] action: - - service: light.turn_off + - action: light.turn_off entity_id: light.pl2 mode: single - alias: "State Light Mapping" @@ -134,7 +134,7 @@ The automation to show the CO2 warning light (e.g. red if CO2 > 1000 ppm) is don # You can also match on interval. This will match every 5 minutes minutes: "/5" action: - - service: light.turn_on + - action: light.turn_on data_template: entity_id: light.pl1 brightness_pct: 30 diff --git a/cookbook/power_meter.rst b/cookbook/power_meter.rst index c829a9d93f..9e9205d47f 100644 --- a/cookbook/power_meter.rst +++ b/cookbook/power_meter.rst @@ -46,7 +46,7 @@ Adjust ``GPIO12`` to match your set up of course. The output from the pulse coun .. note:: - The ``pulse_meter`` sensor sends an update every time a pulse is detected. This can quickly lead to sub-second updates which can be a bit much for Home Assistant to handle. To avoid this, you can use the ``average_throttle`` filter to only send updates up to a desired interval: + The ``pulse_meter`` sensor sends an update every time a pulse is detected. This can quickly lead to sub-second updates which can be a bit much for Home Assistant to handle. To avoid this, you can use the ``throttle_average`` filter to only send updates up to a desired interval: .. code-block:: yaml @@ -54,7 +54,7 @@ Adjust ``GPIO12`` to match your set up of course. The output from the pulse coun - platform: pulse_meter # ... filters: - - average_throttle: 10s + - throttle_average: 10s - filter_out: NaN .. note:: @@ -97,7 +97,7 @@ When the total sensor is configured, ``pulse_meter`` also reports the total numb accuracy_decimals: 3 filters: - multiply: 0.0001 # (1/10000 pulses per kWh) - # - average_throttle: 10s + # - throttle_average: 10s # - filter_out: NaN (Re)Setting the total energy value @@ -108,8 +108,8 @@ Using this action, you are able to reset/set the total pulse count. This can be .. code-block:: yaml api: - services: - - service: set_total + actions: + - action: set_total variables: new_total: int then: @@ -137,7 +137,7 @@ Additionally you can also calculate the total daily energy generated, for which filters: # Multiplication factor from W to kW is 0.001 - multiply: 0.001 - + time: - platform: homeassistant id: homeassistant_time diff --git a/custom/custom_component.rst b/custom/custom_component.rst index 72e23baf94..a87dcb1040 100644 --- a/custom/custom_component.rst +++ b/custom/custom_component.rst @@ -86,8 +86,8 @@ Native API Custom Component --------------------------- If you want to communicate directly with Home Assistant via the :doc:`native API ` -you can use the :apiclass:`api::CustomAPIDevice` class to declare services that can be executed from -Home Assistant, as well as starting services in Home Assistant. +you can use the :apiclass:`api::CustomAPIDevice` class to declare actions that can be performed from +Home Assistant, as well as performing actions in Home Assistant. .. code-block:: cpp diff --git a/guides/cli.rst b/guides/cli.rst index 68e600eb22..7dc145a681 100644 --- a/guides/cli.rst +++ b/guides/cli.rst @@ -39,6 +39,7 @@ ESPHome's command line interface always has the following format .. option:: -v|--verbose Enable verbose esphome logs. + Can also be enabled via environment variable ``ESPHOME_VERBOSE=true``. ``--quiet`` Option ------------------ @@ -140,7 +141,7 @@ The ``esphome upload `` validates the configuration and uploads the most .. program:: esphome clean-mqtt The ``esphome clean-mqtt `` cleans retained MQTT discovery messages from the MQTT broker. -See :ref:`mqtt-using_with_home_assistant`. +See :ref:`mqtt-using_with_home_assistant_entities`. .. option:: --topic TOPIC diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index c50fef15d3..23a9436681 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -163,423 +163,6 @@ There are several ways of doing this. See below examples to see how you can spec update_interval: never # never update update_interval: 0ms # update in every loop() iteration -.. _config-substitutions: - -Substitutions -------------- - -ESPHome has a powerful new way to reduce repetition in configuration files: Substitutions. -With substitutions, you can have a single generic source file for all nodes of one kind and -substitute expressions in. - -.. code-block:: yaml - - substitutions: - devicename: livingroom - upper_devicename: Livingroom - - esphome: - name: $devicename - # ... - - sensor: - - platform: dht - # ... - temperature: - name: ${upper_devicename} Temperature - humidity: - name: ${upper_devicename} Humidity - -In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before -validating your configuration, ESPHome will automatically replace all occurrences of substitutions -by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or -``${substitution_key}`` (same). - -Two substitution passes are performed allowing compound replacements. - -.. code-block:: yaml - - substitutions: - foo: yellow - bar_yellow_value: !secret yellow_secret - bar_green_value: !secret green_secret - - something: - test: ${bar_${foo}_value} - -.. _YAML-insertion-operator: - -YAML insertion operator -*********************** - -Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number -of nodes inherit: - -.. code-block:: yaml - - # In common.yaml - esphome: - name: $devicename - # ... - - sensor: - - platform: dht - # ... - temperature: - name: ${upper_devicename} Temperature - humidity: - name: ${upper_devicename} Humidity - -.. code-block:: yaml - - # In nodemcu1.yaml - substitutions: - devicename: nodemcu1 - upper_devicename: NodeMCU 1 - - <<: !include common.yaml - -.. tip:: - - To hide these base files from the dashboard, you can - - - Place them in a subdirectory (dashboard only shows files in top-level directory) - - Prepend a dot to the filename, like ``.base.yaml`` - -.. _substitute-include-variables: - -Substitute !include variables -***************************** - -ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file. - -.. code-block:: yaml - - binary_sensor: - - platform: gpio - id: button1 - pin: GPIOXX - on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax - - platform: gpio - id: button2 - pin: GPIOXX - on_multi_click: !include - # multi-line syntax - file: on-multi-click.yaml - vars: - id: 2 - -``on-multi-click.yaml``: - -.. code-block:: yaml - - - timing: !include click-single.yaml - then: - - mqtt.publish: - topic: ${device_name}/button${id}/status - payload: single - - timing: !include click-double.yaml - then: - - mqtt.publish: - topic: ${device_name}/button${id}/status - payload: double - -.. _command-line-substitutions: - -Command line substitutions -************************** - -You can define or override substitutions from the command line by adding e.g. ``-s KEY VALUE`` -which overrides substitution KEY and gives it value VALUE. This can be issued multiple times, -so e.g. with the following ``example.yaml`` file: - -.. code-block:: yaml - - substitutions: - name: default - platform: ESP8266 - - esphome: - name: $name - platform: $platform - board: $board - -and the following command: - -.. code-block:: bash - - esphome -s name device01 -s board esp01_1m example.yaml config - -You will get something like the following output (please note the unchanged ``platform``, -added ``board``, and overridden ``name`` substitutions): - -.. code-block:: yaml - - substitutions: - name: device01 - platform: ESP8266 - board: esp01_1m - esphome: - name: device01 - platform: ESP8266 - board: esp01_1m - includes: [] - libraries: [] - esp8266_restore_from_flash: false - build_path: device01 - platformio_options: {} - arduino_version: espressif8266@2.2.3 - -We can observe here that command line substitutions take precedence over the ones in -your configuration file. This can be used to create generic 'template' configuration -files (like the ``example.yaml`` above) which can be used for multiple devices, -using substitutions which are provided on the command line. - -.. _config-packages: - -Packages --------- - -Another way to modularize and reuse your configuration is to use packages. This feature allows -you to put common pieces of configuration in separate files and keep only unique pieces of your -config in the main yaml file. All definitions from packages will be merged with your main -config in non-destructive way so you could always override some bits and pieces of package -configuration. Substitutions in your main config will override substitutions with the same -name in a package. - -Dictionaries are merged key-by-key. Lists of components are merged by component -ID if specified. Other lists are merged by concatenation. All other config -values are replaced with the later value. - -Local packages -************** - -Consider the following example where the author put common pieces of configuration like WiFi and -I²C into base files and extends it with some device specific configurations in the main config. - -Note how the piece of configuration describing ``api`` component in ``device_base.yaml`` gets -merged with the services definitions from main config file. - -.. code-block:: yaml - - # In config.yaml - substitutions: - node_name: mydevice - device_verbose_name: "My Device" - - packages: - wifi: !include common/wifi.yaml - device_base: !include common/device_base.yaml - - api: - services: - - service: start_laundry - then: - - switch.turn_on: relay - - delay: 3h - - switch.turn_off: relay - - sensor: - - platform: mhz19 - co2: - name: "CO2" - temperature: - name: "Temperature" - update_interval: 60s - automatic_baseline_calibration: false - -.. code-block:: yaml - - # In wifi.yaml - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - domain: .yourdomain.lan - fast_connect: true - -.. code-block:: yaml - - # In device_base.yaml - esphome: - name: ${node_name} - platform: ESP32 - board: wemos_d1_mini32 - build_path: ./build/${node_name} - - # I²C Bus - i2c: - sda: GPIOXX - scl: GPIOXX - scan: true - frequency: 100kHz - - # Enable logging - logger: - level: ${log_level} - - api: - encryption: - key: !secret api_encryption_key - reboot_timeout: 1h - - sensor: - - <<: !include common/sensor/uptime.config.yaml - - <<: !include common/sensor/wifi_signal.config.yaml - binary_sensor: - - <<: !include common/binary_sensor/connection_status.config.yaml - - switch: - - <<: !include common/switch/restart_switch.config.yaml - -.. _config-git_packages: - -Remote/git Packages -******************* - -Packages can also be loaded from a git repository by utilizing the correct config syntax. -:ref:`config-substitutions` can be used inside the remote packages which allows users to override -them locally with their own subsitution value. - -.. note:: - - Remote packages cannot have ``secret`` lookups in them. They should instead make use of substitutions with an - optional default in the packaged YAML, which the local device YAML can set using values from the local secrets. - -.. code-block:: yaml - - packages: - # Git repo examples - remote_package: - url: https://github.com/esphome/non-existant-repo - ref: main # optional - files: [file1.yml, file2.yml] - refresh: 1d # optional - - # A single file can be expressed using `file` or `files` as a string - remote_package_two: - url: https://github.com/esphome/non-existant-repo - file: file1.yml # cannot be combined with `files` - # files: file1.yml - - # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] - remote_package_three: github://esphome/non-existant-repo/file1.yml@main - -Packages as Templates -********************* - -Since packages are incorporated using the ``!include`` system, -variables can be provided to them. This means that packages can be -used as `templates`, allowing complex or repetitive configurations to -be stored in a package file and then incorporated into the -configuration more than once. -Additionally packages could contain a ``defaults`` block which provides -subsitutions for variables not provided by the ``!include`` block. - -As an example, if the configuration needed to support three garage -doors using the ``gpio`` switch platform and the ``time_based`` cover -platform, it could be constructed like this: - -.. code-block:: yaml - - # In config.yaml - packages: - left_garage_door: !include - file: garage-door.yaml - vars: - door_name: Left - door_location: left - open_switch_gpio: 25 - close_switch_gpio: 26 - middle_garage_door: !include - file: garage-door.yaml - vars: - door_name: Middle - door_location: middle - open_switch_gpio: 27 - close_switch_gpio: 29 - right_garage_door: !include - file: garage-door.yaml - vars: - door_name: Right - door_location: right - open_switch_gpio: 15 - close_switch_gpio: 18 - open_duration: "1min" - close_duration: "50s" - - -.. code-block:: yaml - - # In garage-door.yaml - defaults: - open_duration: "2.1min" - close_duration: "2min" - - switch: - - id: open_${door_location}_door_switch - name: ${door_name} Garage Door Open Switch - platform: gpio - pin: ${open_switch_gpio} - - - id: close_${door_location}_door_switch - name: ${door_name} Garage Door Close Switch - platform: gpio - pin: ${close_switch_gpio} - - cover: - - platform: time_based - name: ${door_name} Garage Door - - open_action: - - switch.turn_on: open_${door_location}_door_switch - open_duration: ${open_duration} - - close_action: - - switch.turn_on: close_${door_location}_door_switch - close_duration: ${close_duration} - - stop_action: - - switch.turn_off: open_${door_location}_door_switch - - switch.turn_off: close_${door_location}_door_switch - -Extend ------- - -To make changes or add additional configuration to included configurations ``!extend config_id`` can be used, where ``config_id`` is the ID of the configuration to modify. -For example to set a specific update interval on a common uptime sensor that is shared between configurations: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - sensor: - - id: !extend uptime_sensor - update_interval: 10s - -Remove ------- - -To remove existing entries from included configurations ``!remove [config_id]`` can be used, where ``config_id`` is the ID of the entry to modify. -For example to remove a common uptime sensor that is shared between configurations: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - sensor: - - id: !remove uptime_sensor - -To remove captive portal for a specific device: - -.. code-block:: yaml - - packages: - common: !include common.yaml - - captive_portal: !remove - See Also -------- diff --git a/guides/diy.rst b/guides/diy.rst index 07c1311d43..9611c994db 100644 --- a/guides/diy.rst +++ b/guides/diy.rst @@ -59,6 +59,7 @@ Blog Posts & Videos - `Automated Coffee Bean Roaster `__ by `brooksben11 `__ - `Droplet Smart Irrigation System `__ by `PricelessToolkit `__ - `Garage door opener controller for devices with optical encoder `__ by :ghuser:`serg987` +- `An IoT clock designed for children `__ by :ghuser:`chrisns` Custom Components & Code ------------------------ diff --git a/guides/faq.rst b/guides/faq.rst index 722ffdde27..105bb011ee 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -48,7 +48,7 @@ Tips for using ESPHome payload: double - For even more configuration templating, take a look at :ref:`config-substitutions`. + For even more configuration templating, take a look at :doc:`/components/substitutions`. 2. If you want to see how ESPHome interprets your configuration, run @@ -66,7 +66,7 @@ Tips for using ESPHome 5. You can view the full list of command line interface options here: :doc:`/guides/cli` -6. Use :ref:`substitutions ` to reduce repetition in your configuration files. +6. Use :doc:`/components/substitutions` to reduce repetition in your configuration files. .. |secret| replace:: ``!secret`` .. _secret: https://www.home-assistant.io/docs/configuration/secrets/ diff --git a/guides/index.rst b/guides/index.rst index 1dd6ba9d76..e51c0fd51f 100644 --- a/guides/index.rst +++ b/guides/index.rst @@ -3,5 +3,6 @@ Guides .. toctree:: :glob: + :maxdepth: 1 * diff --git a/guides/made_for_esphome.rst b/guides/made_for_esphome.rst index 4c1b92c8ff..19e4674b58 100644 --- a/guides/made_for_esphome.rst +++ b/guides/made_for_esphome.rst @@ -34,11 +34,14 @@ For all projects - Your project is powered by an ESP32 or *supported* ESP32 variant such as the S2, S3, C3, etc. - Your ESPHome configuration is open source, available for end users to modify/update - Users should be able to apply updates if your project sells ready-made devices -- Your project supports adoption via the ``dashboard_import`` feature of ESPHome (see :doc:`Sharing `). In particular: +- Your project supports adoption via the ``dashboard_import`` feature of ESPHome (see + :doc:`Sharing `). In particular: + - There are **no** references to secrets or passwords - Network configuration must assume defaults (no static IPs or DNS configured) - - It **must** compile successfully without any user changes after adopting it. - - All configuration is contained within a single YAML file. Fully remote packages are permitted if using ``import_full_config: true``. + - The configuration **must** be valid, compile and run successfully *without any user changes* after adopting it. + - Use of remote packages in the YAML is permitted only if the above criteria are met. + - Your product name cannot contain "**ESPHome**" except in the case of *ending with* "**for ESPHome**" When your project matches all requirements of the Made for ESPHome program, diff --git a/guides/setting_up_rmt_devices.rst b/guides/setting_up_rmt_devices.rst new file mode 100644 index 0000000000..9441614992 --- /dev/null +++ b/guides/setting_up_rmt_devices.rst @@ -0,0 +1,192 @@ +.. seo:: + :description: Set up guide for configuring IR and RF devices in ESPHome. + :image: remote.svg + +.. _remote-setting-up-infrared: + +Setting up IR Devices +===================== + +In this guide an infrared device will be set up with ESPHome. First, the remote code +will be captured with an IR receiver module (like `this one `__). +We will use ESPHome's dumping ability to output the decoded remote code directly. + +Then we will set up a new remote transmitter with an infrared LED (like +`this one `__) to transmit the +code when a button is pressed. + +First, connect the infrared receiver module to a pin on your board and set up a +remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: all + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an infrared remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.panasonic] Received Panasonic: address=0x4004 command=0x8140DFA2 + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first infrared code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: GPIOXX + # Infrared remotes use a 50% carrier signal + carrier_duty_percent: 50% + +This will allow us to send any data we want via the IR LED. To replicate the codes we decoded +earlier, create a new template button that sends the infrared code when triggered: + +.. code-block:: yaml + + button: + - platform: template + name: Panasonic Power Button + on_press: + - remote_transmitter.transmit_panasonic: + address: 0x4004 + command: 0x8140DFA2 + + # Or for raw code + button: + - platform: template + name: Raw Code Power Button + on_press: + - remote_transmitter.transmit_raw: + carrier_frequency: 38kHz + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new button +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +.. _remote-setting-up-rf: + +Setting up RF Devices +===================== + +The ``remote_transmitter`` and ``remote_receiver`` components can also be used to send +and receive 433MHz Radio Frequency (RF) signals. This guide will discuss setting up a 433MHz +receiver to capture a device's remote codes. After that we will set up a 433MHz transmitter +to replicate the remote code with the press of a button in the frontend. + +First, connect the RF module to a pin on the ESP and set up a remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: all + # Settings to optimize recognition of RF devices + tolerance: 50% + filter: 250us + idle: 4ms + buffer_size: 2kb # only for ESP8266 + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an RF remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.rc_switch] Received RCSwitch: protocol=2 data='100010000000000010111110' + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +.. note:: + + If the log output is flooded with "Received Raw" messages, you can also disable raw + remote code reporting and rely on rc_switch to decode the values. + + .. code-block:: yaml + + remote_receiver: + pin: GPIOXX + dump: + - rc_switch + ... + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first RF code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +RF transmitter to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: GPIOXX + # RF uses a 100% carrier signal + carrier_duty_percent: 100% + +This will allow us to send any data we want via the RF transmitter. To replicate the codes we decoded +earlier, create a new template button that sends the RF code when triggered: + +.. code-block:: yaml + + button: + - platform: template + name: RF Power Button + optimistic: true + on_press: + - remote_transmitter.transmit_rc_switch_raw: + code: '100010000000000010111110' + protocol: 2 + repeat: + times: 10 + wait_time: 0s + + + # Or for raw code + button: + - platform: template + name: Raw Code Power Button + on_press: + - remote_transmitter.transmit_raw: + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new button +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +.. note:: + + Some devices require that the transmitted code be repeated for the signal to be picked up + as valid. Also the interval between repetitions can be important. Check that the pace of + repetition logs are consistent between the remote controller and the transmitter node. + You can adjust the ``repeat:`` settings accordingly. + +See Also +-------- + +- :doc:`/components/remote_receiver` +- :doc:`/components/remote_transmitter` diff --git a/guides/supporters.rst b/guides/supporters.rst index 35f96e4caa..45e36e3976 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -40,6 +40,7 @@ Contributors - `Antonio (@acarvajalperez) `__ - `aceindy (@aceindy) `__ - `Avula Chandra Kiran Reddy (@ackr-8) `__ +- `Alex Cortelyou (@acortelyou) `__ - `acshef (@acshef) `__ - `Zhenyu Wu (@Adam5Wu) `__ - `adamgreg (@adamgreg) `__ @@ -47,6 +48,7 @@ Contributors - `Attila Darazs (@adarazs) `__ - `ADeadPixel (@ADeadPixel) `__ - `adezerega (@adezerega) `__ +- `Eugen (@Adminius) `__ - `Andrea Donno (@adonno) `__ - `Adrian Cuzman (@adriancuzman) `__ - `Adrian Fretwell (@AdrianFretwell) `__ @@ -124,6 +126,7 @@ Contributors - `Anthony (@AnthonyMaiorani) `__ - `Rémi K. (@antibill51) `__ - `Antonio Fiol (@antonio-fiol) `__ +- `Aodren Auffrédou-Heinicke (@aodrenah) `__ - `Andy Barratt (@apbarratt) `__ - `Andrey Bodrov (@apbodrov) `__ - `Adriaan Peeters (@apeeters) `__ @@ -161,6 +164,7 @@ Contributors - `Kamil Trzciński (@ayufan) `__ - `Nicholas Peters (@Azimath) `__ - `Daniel (@azrael783) `__ +- `azrdev (@azrdev) `__ - `B48D81EFCC (@B48D81EFCC) `__ - `Florian Mösch (@badbadc0ffee) `__ - `Baden (@baden03) `__ @@ -220,6 +224,7 @@ Contributors - `bleeisme (@bleeisme) `__ - `Jim Ekman (@blejdfist) `__ - `blindguynar (@blindguynar) `__ +- `BlueSkyB (@BlueSkyB) `__ - `Scott Smith (@blurfl) `__ - `Bruno Medici (@bmedici) `__ - `Bob (@Bmooij) `__ @@ -252,6 +257,7 @@ Contributors - `brtchip-tuannguyen (@brtchip-tuannguyen) `__ - `buddydvd (@buddydvd) `__ - `bulburDE (@bulburDE) `__ +- `Justin Bunton (@Bunton33) `__ - `Matt Burke (@burkemw3) `__ - `Jon Little (@burundiocibu) `__ - `buxtronix (@buxtronix) `__ @@ -302,6 +308,7 @@ Contributors - `Paweł Dembicki (@CHKDSK88) `__ - `chris-jennings (@chris-jennings) `__ - `Chris (@chrismaki) `__ +- `Chris Nesbitt-Smith (@chrisns) `__ - `Christiaan de Ridder (@christiaanderidder) `__ - `Christoph Wagner (@Christoph-Wagner) `__ - `Christian Taedcke (@chrta) `__ @@ -330,6 +337,7 @@ Contributors - `Coenie Richards (@coenier) `__ - `Ashton Lafferty (@cogneato) `__ - `Colin Leroy-Mira (@colinleroy) `__ +- `Colm (@colmbuckley) `__ - `ColoMAX (@ColoMAX) `__ - `Max (@coltoncat) `__ - `Conclusio (@Conclusio) `__ @@ -392,6 +400,7 @@ Contributors - `Aliasghar Dashkhaneh (@dashkhaneh) `__ - `Sylwester (@DatanoiseTV) `__ - `Anthony Uk (@dataway) `__ +- `Datortarps (@Datortarp5) `__ - `Dav-id (@dav-id-org) `__ - `DAVe3283 (@DAVe3283) `__ - `DaveCorder (@DaveCorder) `__ @@ -420,6 +429,7 @@ Contributors - `DeadEnd (@DeadEnded) `__ - `Debashish Sahu (@debsahu) `__ - `declanshanaghy (@declanshanaghy) `__ +- `Ali Jafri (@deCodeIt) `__ - `Maximilian (@DeerMaximum) `__ - `definitio (@definitio) `__ - `deftdawg (@deftdawg) `__ @@ -429,6 +439,7 @@ Contributors - `Mickaël Le Baillif (@demikl) `__ - `denes44 (@denes44) `__ - `Dennis (@dennisvbussel) `__ +- `Denis Prokopenko (@denproc) `__ - `dentra (@dentra) `__ - `depasseg (@depasseg) `__ - `Davide Depau (@Depau) `__ @@ -447,12 +458,14 @@ Contributors - `dgtal1 (@dgtal1) `__ - `Dan Halbert (@dhalbert) `__ - `Dustin L. Howett (@DHowett) `__ +- `Lucio Tarantino (@dianlight) `__ - `diesel437 (@diesel437) `__ - `Alain Turbide (@Dilbert66) `__ - `Mark (@Diramu) `__ - `Dirk Heinke (@DirkHeinke) `__ - `Dirk Jahnke (@dirkj) `__ - `Dennis (@dirrgang) `__ +- `Andrea Casini (@ditadipolvere08) `__ - `Johann V. (@divinitas) `__ - `dj-bauer (@dj-bauer) `__ - `Dominic Pearman (@djpearman) `__ @@ -489,6 +502,7 @@ Contributors - `DrRob (@DrRob) `__ - `drug123 (@drug123) `__ - `Drzony (@drzony) `__ +- `Dmitry Savinkin (@dsavinkin) `__ - `Dmitrii Shcherbakov (@dshcherb) `__ - `Daniel Müller (@dtmuller) `__ - `Tom Soer (@dtx3k) `__ @@ -500,6 +514,7 @@ Contributors - `Jannick (@DutchDeffy) `__ - `David van der Leij (@dvanderleij) `__ - `dwildstr (@dwildstr) `__ +- `David Woodhouse (@dwmw2) `__ - `dxta1986 (@dxta1986) `__ - `dyarkovoy (@dyarkovoy) `__ - `Janez Troha (@dz0ny) `__ @@ -516,6 +531,7 @@ Contributors - `Eduardo Pérez (@eduperez) `__ - `Edward Firmo (@edwardtfn) `__ - `Eenoo (@Eenoo) `__ +- `IDuzTheGamez (@eff3ry) `__ - `Eli Fidler (@efidler) `__ - `egandro (@egandro) `__ - `Erwin Kooi (@egeltje) `__ @@ -606,6 +622,7 @@ Contributors - `Fabio Pugliese Ornellas (@fornellas) `__ - `SmartShackMaster (@fototakas) `__ - `foxsam21 (@foxsam21) `__ +- `ESP32andmore (@fpovoski) `__ - `Fractal147 (@Fractal147) `__ - `Francis-labo (@Francis-labo) `__ - `Francisk0 (@Francisk0) `__ @@ -627,6 +644,7 @@ Contributors - `frspp (@frspp) `__ - `Florian Trück (@ftrueck) `__ - `functionpointer (@functionpointer) `__ +- `Gábor Kiss (@g-kiss) `__ - `mr G1K (@G1K) `__ - `Aljaž Srebrnič (@g5pw) `__ - `Alex Hermann (@gaaf) `__ @@ -640,6 +658,7 @@ Contributors - `Greg Cormier (@gcormier) `__ - `GeekVisit (@GeekVisit) `__ - `Ian Reinhart Geiser (@geiseri) `__ +- `Gene Hand (@genehand) `__ - `R Huish (@genestealer) `__ - `Geoff Davis (@geoffdavis) `__ - `Geoffrey Van Landeghem (@geoffrey-vl) `__ @@ -708,6 +727,7 @@ Contributors - `Alex Griffith (@halomademeapc) `__ - `Aniket (@HandyHat) `__ - `Harrison Jones (@harrisonhjones) `__ +- `HarvsG (@HarvsG) `__ - `Charles Thompson (@haryadoon) `__ - `Ha Thach (@hathach) `__ - `Cong Hoang Nguyen (@HcNguyen111) `__ @@ -773,6 +793,7 @@ Contributors - `Ingurum (@Ingurum) `__ - `Marc J (@InvncibiltyCloak) `__ - `IoT-devices LLC (@iotdevicesdev) `__ +- `irgendwienet (@irgendwienet) `__ - `Ivo Roefs (@ironirc) `__ - `irtimaled (@irtimaled) `__ - `Ingo Theiss (@itn3rd77) `__ @@ -894,9 +915,11 @@ Contributors - `joskfg (@joskfg) `__ - `Joscha Wagner (@jowgn) `__ - `Javier Peletier (@jpeletier) `__ +- `Jan Rieger (@jrieger) `__ - `jsuanet (@jsuanet) `__ - `James Szalay (@jtszalay) `__ - `Jules-R (@Jules-R) `__ +- `Julian Stremel (@JulianStremel) `__ - `Julie Koubová (@juliekoubova) `__ - `junkie1969 (@junkie1969) `__ - `junnikokuki (@junnikokuki) `__ @@ -927,11 +950,13 @@ Contributors - `kbouchard111 (@kbouchard111) `__ - `Keith Burzinski (@kbx81) `__ - `Ken Piper (@Kealper) `__ +- `kecajtop (@kecajtop) `__ - `Tom Keller (@kellertk) `__ - `Kelvie Wong (@kelvie) `__ - `Kenny Stier (@KennyStier) `__ - `Robert Kiss (@kepten) `__ - `kernelpanic85 (@kernelpanic85) `__ +- `kevdliu (@kevdliu) `__ - `Kevin O'Rourke (@kevinior) `__ - `Kevin Reilly (@kevireilly) `__ - `kevlar10 (@kevlar10) `__ @@ -979,6 +1004,7 @@ Contributors - `Kyle Manna (@kylemanna) `__ - `Kyle Hill (@kylhill) `__ - `Kalashnikov Ilya (@l1bbcsg) `__ +- `l3d00m (@l3d00m) `__ - `la7dja (@la7dja) `__ - `Limor "Ladyada" Fried (@ladyada) `__ - `Stefan Lässer (@Laess3r) `__ @@ -996,6 +1022,7 @@ Contributors - `lcavalli (@lcavalli) `__ - `Craig Fletcher (@leakypixel) `__ - `Dominik Wagenknecht (@LeDominik) `__ +- `leejoow (@leejoow) `__ - `Benny de Leeuw (@leeuwte) `__ - `Thayne (@Legot) `__ - `lein1013 (@lein1013) `__ @@ -1032,6 +1059,7 @@ Contributors - `Joakim Sørensen (@ludeeus) `__ - `ludrao (@ludrao) `__ - `Luiz Correia (@luizcorreia) `__ +- `luk1803 (@luk1803) `__ - `luka6000 (@luka6000) `__ - `Lukas Klass (@LukasK13) `__ - `Lukas Lindner (@lukasl96) `__ @@ -1196,6 +1224,7 @@ Contributors - `Chris Laplante (@mostthingsweb) `__ - `Matthew Pettitt (@mpettitt) `__ - `Michael P. Flaga (@mpflaga) `__ +- `Björn Ebbinghaus (@MrEbbinghaus) `__ - `Sam Hughes (@MrEditor97) `__ - `MrEditor97 (@mreditor97) `__ - `MRemy2 (@MRemy2) `__ @@ -1244,6 +1273,7 @@ Contributors - `NatashaLi-ESPRESSIF (@NatashaLi-ESPRESSIF) `__ - `Nate Lust (@natelust) `__ - `Nathan Marlor (@nathanmarlor) `__ +- `Andreas Fritiofson (@nattgris) `__ - `ueno (@nayuta-ueno) `__ - `Nazar Mokrynskyi (@nazar-pc) `__ - `Bergont Nicolas (@nbergont) `__ @@ -1302,6 +1332,7 @@ Contributors - `Chris Nussbaum (@nuttytree) `__ - `Michał Sochoń (@nvtkaszpir) `__ - `Nathaniel Wesley Filardo (@nwf) `__ +- `Olivier ARCHER (@oarcher) `__ - `obrain17 (@obrain17) `__ - `Ockert Marais (@OckertM) `__ - `Dave Walker (@oddsockmachine) `__ @@ -1311,6 +1342,7 @@ Contributors - `ogatatsu (@ogatatsu) `__ - `Oğuzhan Başer (@oguzhanbaser) `__ - `Larry (@ojaksch) `__ +- `ojwc (@ojwc) `__ - `OkhammahkO (@OkhammahkO) `__ - `Oleg Tarasov (@olegtarasov) `__ - `Oliver Hihn (@oliverhihn) `__ @@ -1402,6 +1434,7 @@ Contributors - `pplucky (@pplucky) `__ - `Peter Provost (@PProvost) `__ - `Q. Marchi (@preeefix) `__ +- `PricelessToolkit (@PricelessToolkit) `__ - `Francesco Ciocchetti (@primeroz) `__ - `probonopd (@probonopd) `__ - `Gary Morris (@progrmr) `__ @@ -1536,10 +1569,12 @@ Contributors - `Jan Čermák (@sairon) `__ - `samnewman86 (@samnewman86) `__ - `Sam Turner (@samturner3) `__ +- `Samuel Tardieu (@samueltardieu) `__ - `Sender (@sanderlv) `__ - `Sanjay Govind (@sanjay900) `__ - `Marcin (@Santanachia) `__ - `sascha lammers (@sascha432) `__ +- `Sašo Domadenik (@sasodoma) `__ - `Davide Perini (@sblantipodi) `__ - `sbur83 (@sbur83) `__ - `Søren Christian Aarup (@scaarup) `__ @@ -1564,6 +1599,7 @@ Contributors - `Jason Sepinsky (@Sepinsky) `__ - `Sergey Popov (@Sergey-SRG) `__ - `Sergio (@sergio303) `__ +- `Sung-jin Brian Hong (@serialx) `__ - `Sergio Mayoral Martínez (@sermayoral) `__ - `sethcohn (@sethcohn) `__ - `Seth Girvan (@sethgirvan) `__ @@ -1585,6 +1621,7 @@ Contributors - `SiliconAvatar (@SiliconAvatar) `__ - `sillyfrog (@sillyfrog) `__ - `Mark Lopez (@Silvenga) `__ +- `simonjowett (@simonjowett) `__ - `James Chaloupka (@SirGoodenough) `__ - `Maximilian Ertl (@Sirs0ri) `__ - `SirSydom (@SirSydom) `__ @@ -1694,6 +1731,7 @@ Contributors - `TheJulianJES (@TheJulianJES) `__ - `Jozef Zuzelka (@TheKuko) `__ - `Mateusz Soszyński (@TheLastGimbus) `__ +- `Daniel (@themorgantown) `__ - `Bart (@TheNameIsBart) `__ - `Andrew Quested (@thenameiwantedwastaken) `__ - `Zixuan Wang (@TheNetAdmin) `__ @@ -1701,6 +1739,7 @@ Contributors - `Alan Lord (@theopensourcerer) `__ - `Simon (@theOzzieRat) `__ - `Brian Levinsen (@therealeldaria) `__ +- `thevogoncoder (@thevogoncoder) `__ - `Steve Scott (@thewishy) `__ - `Zachery Notz (@TheZackCodec) `__ - `Florian Gareis (@TheZoker) `__ @@ -1747,12 +1786,14 @@ Contributors - `Tom Price (@tomtom5152) `__ - `Anthony Bourguignon (@Toniob) `__ - `tony (@tony-fav) `__ +- `Tomi Junnila (@topeju) `__ - `David Kiliani (@torfbolt) `__ - `Aleksandra M (@tort32) `__ - `Torwag (@torwag) `__ - `Teemu Simola (@tpssim) `__ - `tracestep (@tracestep) `__ - `Trent Houliston (@TrentHouliston) `__ +- `Trevor Schirmer (@TrevorSchirmer) `__ - `Felix Eckhofer (@tribut) `__ - `Trick van Staveren (@trickv) `__ - `TripitakaBC (@TripitakaBC) `__ @@ -1766,6 +1807,7 @@ Contributors - `Trevor North (@trvrnrth) `__ - `Trygve Laugstøl (@trygvis) `__ - `Gediminas Šaltenis (@trylika) `__ +- `ttaborda (@ttaborda) `__ - `Tuan (@tuanpmt) `__ - `tubalainen (@tubalainen) `__ - `tube0013 (@tube0013) `__ @@ -1788,6 +1830,7 @@ Contributors - `Aaron Mildenstein (@untergeek) `__ - `uPesy Electronics (@uPesy) `__ - `user897943 (@user897943) `__ +- `uSlackr (@uSlackr) `__ - `UT2UH (@UT2UH) `__ - `Vlad Yarotsky (@v-yarotsky) `__ - `Vc (@Valcob) `__ @@ -1868,6 +1911,7 @@ Contributors - `Jevgeni Kiski (@yozik04) `__ - `YuanL.Lee (@yuanl) `__ - `Yuval Aboulafia (@yuvalabou) `__ +- `Z3LIFF (@z3liff) `__ - `ZabojnikM (@ZabojnikM) `__ - `Björn Stenberg (@zagor) `__ - `zaluthar (@zaluthar) `__ @@ -1890,4 +1934,4 @@ Contributors - `Christian Zufferey (@zuzu59) `__ - `Zynth-dev (@Zynth-dev) `__ -*This page was last updated June 27, 2024.* +*This page was last updated August 21, 2024.* diff --git a/images/apds9306.png b/images/apds9306.png new file mode 100644 index 0000000000..07fbc1d37a Binary files /dev/null and b/images/apds9306.png differ diff --git a/images/chart-line.svg b/images/chart-line.svg new file mode 100644 index 0000000000..eeb7259fd0 --- /dev/null +++ b/images/chart-line.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/image-multiple-outline.svg b/images/image-multiple-outline.svg new file mode 100644 index 0000000000..d89398cb5a --- /dev/null +++ b/images/image-multiple-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/image-outline.svg b/images/image-outline.svg new file mode 100644 index 0000000000..cc75caa65d --- /dev/null +++ b/images/image-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/image-sync-outline.svg b/images/image-sync-outline.svg new file mode 100644 index 0000000000..7415eee7a2 --- /dev/null +++ b/images/image-sync-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/lvgl.png b/images/lvgl.png new file mode 100644 index 0000000000..a48dd7c4f8 Binary files /dev/null and b/images/lvgl.png differ diff --git a/images/lvgl_c_bns.png b/images/lvgl_c_bns.png new file mode 100644 index 0000000000..bcfb3e2065 Binary files /dev/null and b/images/lvgl_c_bns.png differ diff --git a/images/lvgl_c_lig.png b/images/lvgl_c_lig.png new file mode 100644 index 0000000000..48b5e3ebc4 Binary files /dev/null and b/images/lvgl_c_lig.png differ diff --git a/images/lvgl_c_num.png b/images/lvgl_c_num.png new file mode 100644 index 0000000000..8721ab99c5 Binary files /dev/null and b/images/lvgl_c_num.png differ diff --git a/images/lvgl_c_sel.png b/images/lvgl_c_sel.png new file mode 100644 index 0000000000..b0f0dab244 Binary files /dev/null and b/images/lvgl_c_sel.png differ diff --git a/images/lvgl_c_swi.png b/images/lvgl_c_swi.png new file mode 100644 index 0000000000..44f0bef2af Binary files /dev/null and b/images/lvgl_c_swi.png differ diff --git a/images/lvgl_c_txt.png b/images/lvgl_c_txt.png new file mode 100644 index 0000000000..72f1d05113 Binary files /dev/null and b/images/lvgl_c_txt.png differ diff --git a/images/m5stack_8angle.png b/images/m5stack_8angle.png new file mode 100644 index 0000000000..1a37ed3cb9 Binary files /dev/null and b/images/m5stack_8angle.png differ diff --git a/images/mcp2515.svg b/images/mcp2515.svg new file mode 100644 index 0000000000..a656b7ef19 --- /dev/null +++ b/images/mcp2515.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index ffb7e80bc1..9fd6232f46 100644 --- a/index.rst +++ b/index.rst @@ -172,7 +172,18 @@ ESPHome-specific components or components supporting ESPHome device provisioning Improv via BLE, components/esp32_improv, improv.svg, dark-invert Improv via Serial, components/improv_serial, improv.svg, dark-invert Interval, components/interval, description.svg, dark-invert - Scripts, components/scripts, description.svg, dark-invert + Script, components/script, description.svg, dark-invert + +ESPHome Configuration +--------------------- + +Streamline your ESPHome configuration and/or use components provided by other contributors. + +.. imgtable:: + + External Components, components/external_components, external_components.svg, dark-invert + Packages, components/packages, description.svg, dark-invert + Substitutions, components/substitutions, description.svg, dark-invert Network Hardware ---------------- @@ -243,7 +254,7 @@ Hardware Peripheral Interfaces/Busses .. imgtable:: - CAN Bus, components/canbus, canbus.svg + CAN Bus, components/canbus/index, canbus.svg I²C Bus, components/i2c, i2c.svg I²S Audio, components/i2s_audio, i2s_audio.svg SPI Bus, components/spi, spi.svg @@ -268,6 +279,15 @@ I/O Expanders/Multiplexers WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg XL9535, components/xl9535, xl9535.svg +CAN Bus +------- + +.. imgtable:: + + CAN Bus, components/canbus/index, canbus.svg + ESP32 CAN, components/canbus/esp32_can, esp32.svg + MCP2515, components/canbus/mcp2515, mcp2515.svg + Sensor Components ----------------- @@ -422,6 +442,7 @@ Environmental AM2320, components/sensor/am2320, am2320.jpg, Temperature & Humidity b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light BME280, components/sensor/bme280, bme280.jpg, Temperature & Humidity & Pressure + BME68x via BSEC2, components/sensor/bme68x_bsec2, bme680.jpg, Temperature & Humidity & Pressure & Gas BME680 via BSEC, components/sensor/bme680_bsec, bme680.jpg, Temperature & Humidity & Pressure & Gas BME680, components/sensor/bme680, bme680.jpg, Temperature & Humidity & Pressure & Gas BMP085, components/sensor/bmp085, bmp180.jpg, Temperature & Pressure @@ -479,6 +500,7 @@ Light .. imgtable:: AM43, components/sensor/am43, am43.jpg, Lux + APDS9306, components/sensor/apds9306, apds9306.png, Lux APDS9960, components/sensor/apds9960, apds9960.jpg, Colour & Gesture AS7341, components/sensor/as7341, as7341.jpg, Spectral Color Sensor BH1750, components/sensor/bh1750, bh1750.jpg, Lux @@ -526,6 +548,8 @@ Miscellaneous Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop Integration, components/sensor/integration, sigma.svg, dark-invert Kuntze pool sensor, components/sensor/kuntze, kuntze.jpg + LVGL widget, components/sensor/lvgl, lvgl_c_num.png + M5Stack Unit 8 Angle, components/sensor/m5stack_8angle, m5stack_8angle.png MicroNova pellet stove, components/micronova, pellet.svg Modbus Sensor, components/sensor/modbus_controller, modbus.png Nextion, components/sensor/nextion, nextion.jpg, Sensors from display @@ -640,6 +664,7 @@ Touchscreen GT911, components/touchscreen/gt911, esp32_s3_box_3.png Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png + LVGL widget, components/binary_sensor/lvgl, lvgl_c_bns.png Presence Detection ****************** @@ -664,7 +689,6 @@ Miscellaneous PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg Pylontech Batteries, components/pylontech, pylontech.jpg Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg - Remote Receiver, components/remote_receiver, remote.svg, dark-invert Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png WireGuard, components/wireguard, wireguard_custom_logo.svg @@ -720,6 +744,7 @@ Light Components H-bridge Light, components/light/hbridge, brightness-medium.svg, dark-invert Light Partition, components/light/partition, color_lens.svg, dark-invert LightWaveRF, components/lightwaverf, brightness-medium.svg + LVGL widget, components/light/lvgl, lvgl_c_lig.png Monochromatic Light, components/light/monochromatic, brightness-medium.svg, dark-invert NeoPixelBus Light, components/light/neopixelbus, color_lens.svg, dark-invert RGB Light, components/light/rgb, rgb.png @@ -748,6 +773,7 @@ Switch Components Factory Reset Switch, components/switch/factory_reset, restart-alert.svg, dark-invert Generic Output Switch, components/switch/output, upload.svg, dark-invert GPIO Switch, components/switch/gpio, pin.svg, dark-invert + LVGL Widget, components/switch/lvgl, lvgl_c_swi.png Modbus Switch, components/switch/modbus_controller, modbus.png Nextion Switch, components/switch/nextion, nextion.jpg Restart Switch, components/switch/restart, restart.svg, dark-invert @@ -755,6 +781,7 @@ Switch Components Shutdown Switch, components/switch/shutdown, power_settings.svg, dark-invert Tuya Switch, components/switch/tuya, tuya.png UART Switch, components/switch/uart, uart.svg + Home Assistant, components/switch/homeassistant, home-assistant.svg, dark-invert Button Components ----------------- @@ -797,11 +824,18 @@ Display Components .. imgtable:: Display Core, components/display/index, folder-open.svg, dark-invert + Font Renderer, components/font, format-font.svg, dark-invert + Graph, components/graph, chart-line.svg, dark-invert + QR Code, components/qr_code, qr-code.svg, dark-invert + Image, components/image, image-outline.svg, dark-invert + Animation, components/animation, image-multiple-outline.svg, dark-invert + Online Image, components/online_image, image-sync-outline.svg, dark-invert Display Menu Core, components/display_menu/index, folder-open.svg, dark-invert - Font Renderer, components/display/fonts, format-font.svg, dark-invert - Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png LCD Menu, components/display_menu/lcd_menu, lcd_menu.png + LVGL Graphics, components/lvgl/index, lvgl.png + +.. _display-hw: Display Hardware Platforms -------------------------- @@ -882,6 +916,7 @@ Text Components Text Core, components/text/index, folder-open.svg, dark-invert Template Text, components/text/template, description.svg, dark-invert + LVGL textarea Text, components/text/lvgl, lvgl_c_txt.png Valve Components ---------------- @@ -902,6 +937,7 @@ Text Sensor Components Ethernet Info, components/text_sensor/ethernet_info, ethernet.svg, dark-invert Home Assistant, components/text_sensor/homeassistant, home-assistant.svg, dark-invert LibreTiny, components/text_sensor/libretiny, libretiny.svg + LVGL textarea Text Sensor, components/text_sensor/lvgl, lvgl_c_txt.png Modbus Text Sensor, components/text_sensor/modbus_controller, modbus.png MQTT Subscribe Text, components/text_sensor/mqtt_subscribe, mqtt.png Nextion Text Sensor, components/text_sensor/nextion, nextion.jpg @@ -935,6 +971,7 @@ Number Components Number Core, components/number/index, folder-open.svg, dark-invert Template Number, components/number/template, description.svg, dark-invert + LVGL widget Number, components/number/lvgl, lvgl_c_num.png Modbus Number, components/number/modbus_controller, modbus.png Tuya Number, components/number/tuya, tuya.png @@ -945,6 +982,7 @@ Select Components Select Core, components/select/index, folder-open.svg, dark-invert Template Select, components/select/template, description.svg, dark-invert + LVGL widget Select, components/select/lvgl, lvgl_c_sel.png Modbus Select, components/select/modbus_controller, modbus.png Tuya Select, components/select/tuya, tuya.png @@ -1006,6 +1044,7 @@ Components specifically for interacting with Home Assistant. Bluetooth Proxy, components/bluetooth_proxy, bluetooth.svg, dark-invert micro Wake Word, components/micro_wake_word, voice-assistant.svg, dark-invert Sensor, components/sensor/homeassistant, home-assistant.svg, dark-invert + Switch, components/switch/homeassistant, home-assistant.svg, dark-invert Text Sensor, components/text_sensor/homeassistant, home-assistant.svg, dark-invert Voice Assistant, components/voice_assistant, voice-assistant.svg, dark-invert Cover, components/cover/homeassistant, home-assistant.svg, dark-invert diff --git a/lint.py b/lint.py index e0d3e4c3f6..106a4017aa 100644 --- a/lint.py +++ b/lint.py @@ -395,7 +395,7 @@ def lint_directive_formatting(fname, content): include=["*.rst"], exclude=[ "components/web_server.rst", - "components/display/index.rst", + "components/image.rst", ], ) def lint_esphome_io_link(fname, match):