diff --git a/Doxygen b/Doxygen index 4a3fd03794..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.3 +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 826fd12ae1..ed0590e92e 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2024.7.3 +ESPHOME_REF = 2024.8.0 PAGEFIND_VERSION=1.1.0 PAGEFIND=pagefind NET_PAGEFIND=../pagefindbin/pagefind 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 dc87a07fb8..620b3657cd 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.7.3 \ No newline at end of file +2024.9.0-dev \ No newline at end of file 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 a6600f9381..0d8b249826 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2024.7.0.html + :url: /changelog/2024.8.0.html .. toctree:: :glob: 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/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index 57ab72b4f2..76703b8740 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -50,6 +50,7 @@ Configuration variables: - **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. 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/api.rst b/components/api.rst index 96d819ee6e..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: @@ -91,7 +91,7 @@ Then: #. 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/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/ble_client.rst b/components/ble_client.rst index 4198f3b549..06f08c193c 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -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: 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/ili9xxx.rst b/components/display/ili9xxx.rst index 1e9f4024f3..493e49f9e6 100644 --- a/components/display/ili9xxx.rst +++ b/components/display/ili9xxx.rst @@ -61,9 +61,8 @@ beyond the basic SPI connections, and a reasonable amount of RAM, it is not well model: ili9341 dc_pin: GPIOXX reset_pin: GPIOXX - lambda: |- - it.fill(COLOR_BLACK); - it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!"); + invert_colors: false + show_test_card: true Configuration variables: ************************ @@ -101,7 +100,7 @@ Configuration variables: - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0 - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0. -- **invert_colors** (*Optional*): With this boolean option you can invert the display colors. +- **invert_colors** (**Required**): Specifies whether the display colors should be inverted. Options are ``true`` or ``false`` - if you are unsure, use ``false`` and change if the colors are not as expected. - **pixel_mode** (*Optional*): Allows forcing the display into 18 or 16 bit mode. Options are ``18bit`` or ``16bit``. If unspecified, the pixel mode will be determined by the model choice. Not all displays will work in both modes. - **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. This option cannot be used with ``transform``. - **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``. @@ -265,6 +264,7 @@ This config rotates the display into landscape mode using the driver chip. mirror_x: false mirror_y: true color_order: bgr + invert_colors: true data_rate: 80MHz cs_pin: GPIOXX dc_pin: GPIO13 diff --git a/components/display/index.rst b/components/display/index.rst index dc305ca4f0..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. @@ -605,11 +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/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/fingerprint_grow.rst b/components/fingerprint_grow.rst index 9f1357bd85..e7b9b60512 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -473,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 @@ -525,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 @@ -534,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/font.rst b/components/font.rst index 47ab89461f..8f215822c1 100644 --- a/components/font.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/http_request.rst b/components/http_request.rst index 18fa0fe835..54e1dc803e 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -36,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 diff --git a/components/image.rst b/components/image.rst index c9962db99e..2a27138ae5 100644 --- a/components/image.rst +++ b/components/image.rst @@ -9,6 +9,8 @@ Images 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: @@ -121,4 +123,3 @@ be supplied to modify the color used to represent the on and off bits respective 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/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 f937b80a23..df4c68c255 100644 --- a/components/index.rst +++ b/components/index.rst @@ -26,6 +26,7 @@ Components touchscreen/index lock/index display_menu/index + lvgl/index media_player/index microphone/index speaker/index 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/esp32_rmt_led_strip.rst b/components/light/esp32_rmt_led_strip.rst index cb19142449..f46e05716a 100644 --- a/components/light/esp32_rmt_led_strip.rst +++ b/components/light/esp32_rmt_led_strip.rst @@ -67,6 +67,10 @@ please consider adding support to the codebase and add it to the list above. - **bit0_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``0`` bit. - **bit1_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``1`` bit. - **bit1_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``1`` bit. +- **reset_high** (*Optional*, :ref:`config-time`): The time to hold the data line high after writing + the state. Defaults to ``0 us``. +- **reset_low** (*Optional*, :ref:`config-time`): The time to hold the data line low after writing + the state. Defaults to ``0 us``. See Also -------- diff --git a/components/light/index.rst b/components/light/index.rst index aaee494891..3e31ad3cf3 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -319,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:: @@ -339,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/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/modbus_controller.rst b/components/modbus_controller.rst index f2975f2ac8..264f078379 100644 --- a/components/modbus_controller.rst +++ b/components/modbus_controller.rst @@ -89,6 +89,9 @@ Configuration variables: - **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 -------------- @@ -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/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/tuya.rst b/components/number/tuya.rst index bf05ac960f..3b87b76520 100644 --- a/components/number/tuya.rst +++ b/components/number/tuya.rst @@ -61,6 +61,23 @@ 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: ------------------------ @@ -69,6 +86,10 @@ Configuration variables: - **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/packages.rst b/components/packages.rst index 1a23253c0d..6acc58a3e4 100644 --- a/components/packages.rst +++ b/components/packages.rst @@ -28,7 +28,7 @@ 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 services +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 @@ -39,8 +39,8 @@ definitions from main configuration file. device_base: !include common/device_base.yaml api: - services: - - service: start_laundry + actions: + - action: start_laundry then: - switch.turn_on: relay diff --git a/components/pipsolar.rst b/components/pipsolar.rst index 466be5ab39..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 diff --git a/components/rf_bridge.rst b/components/rf_bridge.rst index a9db79269b..da6b51dc2d 100644 --- a/components/rf_bridge.rst +++ b/components/rf_bridge.rst @@ -347,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 @@ -360,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 @@ -393,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/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/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst index 697dd7bad6..56267a672b 100644 --- a/components/sensor/airthings_ble.rst +++ b/components/sensor/airthings_ble.rst @@ -71,6 +71,8 @@ Configuration example: name: "WavePlus CO2" tvoc: name: "WavePlus VOC" + illuminance: + name: "WavePlus ambient light" battery_voltage: name: "WavePlus Battery Voltage" 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/bl0942.rst b/components/sensor/bl0942.rst index b2757725ee..e75d66aca9 100644 --- a/components/sensor/bl0942.rst +++ b/components/sensor/bl0942.rst @@ -59,6 +59,8 @@ Configuration variables: sensor. Defaults to ``60s``. - **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want to use multiple UART buses. +- **line_frequency** (*Optional*, string): The nominal AC line frequency of the supply voltage. One of ``50Hz``, ``60Hz``. Defaults to ``50Hz``. +- **address** (*Optional*, int): The address of the BL0942 from its strapping pins. Defaults to ``0``. See Also -------- diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst index 95d73f04cf..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. 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/esp32_hall.rst b/components/sensor/esp32_hall.rst index 7cbcc5e5e0..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. 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/jsn_sr04t.rst b/components/sensor/jsn_sr04t.rst index c8f3bcb9f1..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,6 +18,12 @@ 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% @@ -54,6 +60,7 @@ Configuration variables: 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/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/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/pulse_counter.rst b/components/sensor/pulse_counter.rst index 2bf6b07c2b..df54d8ca37 100644 --- a/components/sensor/pulse_counter.rst +++ b/components/sensor/pulse_counter.rst @@ -104,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 2e999846be..53bbb02a82 100644 --- a/components/sensor/pulse_meter.rst +++ b/components/sensor/pulse_meter.rst @@ -90,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/scd4x.rst b/components/sensor/scd4x.rst index 892e5dea00..086121d5f7 100644 --- a/components/sensor/scd4x.rst +++ b/components/sensor/scd4x.rst @@ -99,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: @@ -160,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/total_daily_energy.rst b/components/sensor/total_daily_energy.rst index 16013bf411..cd1b0bff67 100644 --- a/components/sensor/total_daily_energy.rst +++ b/components/sensor/total_daily_energy.rst @@ -69,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/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index 6a750dfe09..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. @@ -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 **** diff --git a/components/sim800l.rst b/components/sim800l.rst index 73b8ea88c2..7d7af7f0a1 100644 --- a/components/sim800l.rst +++ b/components/sim800l.rst @@ -245,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 @@ -254,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: @@ -320,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" 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/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/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/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/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/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 2e4bcb8be5..bfbb2c48da 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -298,6 +298,9 @@ Configuration variables: - **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/update/index.rst b/components/update/index.rst index e1eb18454e..db15a876f5 100644 --- a/components/update/index.rst +++ b/components/update/index.rst @@ -39,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/conf.py b/conf.py index c901e2bd04..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.3" +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/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 0411666e2c..9e9205d47f 100644 --- a/cookbook/power_meter.rst +++ b/cookbook/power_meter.rst @@ -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/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/supporters.rst b/guides/supporters.rst index 92c41703f3..45e36e3976 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -224,6 +224,7 @@ Contributors - `bleeisme (@bleeisme) `__ - `Jim Ekman (@blejdfist) `__ - `blindguynar (@blindguynar) `__ +- `BlueSkyB (@BlueSkyB) `__ - `Scott Smith (@blurfl) `__ - `Bruno Medici (@bmedici) `__ - `Bob (@Bmooij) `__ @@ -428,6 +429,7 @@ Contributors - `DeadEnd (@DeadEnded) `__ - `Debashish Sahu (@debsahu) `__ - `declanshanaghy (@declanshanaghy) `__ +- `Ali Jafri (@deCodeIt) `__ - `Maximilian (@DeerMaximum) `__ - `definitio (@definitio) `__ - `deftdawg (@deftdawg) `__ @@ -512,6 +514,7 @@ Contributors - `Jannick (@DutchDeffy) `__ - `David van der Leij (@dvanderleij) `__ - `dwildstr (@dwildstr) `__ +- `David Woodhouse (@dwmw2) `__ - `dxta1986 (@dxta1986) `__ - `dyarkovoy (@dyarkovoy) `__ - `Janez Troha (@dz0ny) `__ @@ -619,6 +622,7 @@ Contributors - `Fabio Pugliese Ornellas (@fornellas) `__ - `SmartShackMaster (@fototakas) `__ - `foxsam21 (@foxsam21) `__ +- `ESP32andmore (@fpovoski) `__ - `Fractal147 (@Fractal147) `__ - `Francis-labo (@Francis-labo) `__ - `Francisk0 (@Francisk0) `__ @@ -640,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) `__ @@ -914,6 +919,7 @@ Contributors - `jsuanet (@jsuanet) `__ - `James Szalay (@jtszalay) `__ - `Jules-R (@Jules-R) `__ +- `Julian Stremel (@JulianStremel) `__ - `Julie Koubová (@juliekoubova) `__ - `junkie1969 (@junkie1969) `__ - `junnikokuki (@junnikokuki) `__ @@ -1218,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) `__ @@ -1335,6 +1342,7 @@ Contributors - `ogatatsu (@ogatatsu) `__ - `Oğuzhan Başer (@oguzhanbaser) `__ - `Larry (@ojaksch) `__ +- `ojwc (@ojwc) `__ - `OkhammahkO (@OkhammahkO) `__ - `Oleg Tarasov (@olegtarasov) `__ - `Oliver Hihn (@oliverhihn) `__ @@ -1591,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) `__ @@ -1730,6 +1739,7 @@ Contributors - `Alan Lord (@theopensourcerer) `__ - `Simon (@theOzzieRat) `__ - `Brian Levinsen (@therealeldaria) `__ +- `thevogoncoder (@thevogoncoder) `__ - `Steve Scott (@thewishy) `__ - `Zachery Notz (@TheZackCodec) `__ - `Florian Gareis (@TheZoker) `__ @@ -1924,4 +1934,4 @@ Contributors - `Christian Zufferey (@zuzu59) `__ - `Zynth-dev (@Zynth-dev) `__ -*This page was last updated August 1, 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/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/index.rst b/index.rst index 4f5f26e0a8..b1dc97a308 100644 --- a/index.rst +++ b/index.rst @@ -442,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 @@ -499,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 @@ -546,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 @@ -660,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 ****************** @@ -739,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 @@ -767,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 @@ -774,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 ----------------- @@ -821,9 +829,13 @@ Display Components 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 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 -------------------------- @@ -903,6 +915,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 ---------------- @@ -923,6 +936,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 @@ -956,6 +970,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 @@ -966,6 +981,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 @@ -1027,6 +1043,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