diff --git a/Doxygen b/Doxygen index 4dca2dffe3..c9eb1b5f5f 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.10.3 +PROJECT_NUMBER = 2024.11.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index afad4da840..430cd300eb 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2024.10.3 +ESPHOME_REF = 2024.11.0 PAGEFIND_VERSION=1.1.1 PAGEFIND=pagefind NET_PAGEFIND=../pagefindbin/pagefind diff --git a/_redirects b/_redirects index 0b7f37536a..c2015d7571 100644 --- a/_redirects +++ b/_redirects @@ -42,3 +42,4 @@ /ready-made/projects /projects/ 301 /components/images /components/image 301 +/components/display/qspi_amoled.html /components/display/qspi_dbi.html 301 diff --git a/_static/changelog-2024.11.0.png b/_static/changelog-2024.11.0.png new file mode 100644 index 0000000000..92ac918c37 Binary files /dev/null and b/_static/changelog-2024.11.0.png differ diff --git a/_static/version b/_static/version index 65620ba66d..12bb95e1d0 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.10.3 \ No newline at end of file +2024.11.0 \ No newline at end of file diff --git a/automations/actions.rst b/automations/actions.rst index 57ec7e996e..ec46baf2f1 100644 --- a/automations/actions.rst +++ b/automations/actions.rst @@ -217,7 +217,11 @@ turns on a light for 5 seconds. Otherwise, the light is turned off immediately. Configuration variables: -- **condition** (**Required**, :ref:`Condition `): The condition to check to determine which branch to take. +At least one of ``condition``, ``all`` or ``any`` must be provided. + +- **condition** (*Optional*, :ref:`Condition `): The condition to check to determine which branch to take. If this is configured with a list of conditions then they must all be true for the condition to be true. +- **all** (*Optional*, :ref:`Condition `): Takes a list of conditions, all of which must be true (and is therefore equivalent to ``condition``.) +- **any** (*Optional*, :ref:`Condition `): Takes a list of conditions; if at least one is true, the condition will be true. - **then** (*Optional*, :ref:`Action `): The action to perform if the condition evaluates to true. Defaults to doing nothing. - **else** (*Optional*, :ref:`Action `): The action to perform if the condition evaluates to false. @@ -406,14 +410,17 @@ Common Conditions "Conditions" provide a way for your device to take an action only when a specific (set of) condition(s) is satisfied. .. _and_condition: +.. _all_condition: .. _or_condition: +.. _any_condition: .. _xor_condition: .. _not_condition: -``and`` / ``or`` / ``xor`` / ``not`` Condition -********************************************** +``and`` / ``all`` / ``or`` / ``any`` / ``xor`` / ``not`` Condition +****************************************************************** -Check a combination of conditions +Check a combination of conditions. ``all`` is a synonym for ``and``, and ``any`` is a synonym for ``or``. +``all`` and ``any`` may also be used directly in place of ``condition``. .. code-block:: yaml @@ -428,9 +435,10 @@ Check a combination of conditions # ... - if: - condition: - not: - binary_sensor.is_off: some_binary_sensor + any: + - not: + binary_sensor.is_off: some_binary_sensor + - binary_sensor.is_on: some_other_sensor .. _for_condition: diff --git a/automations/all_actions.rst b/automations/all_actions.rst index 0e91710832..dadff78a62 100644 --- a/automations/all_actions.rst +++ b/automations/all_actions.rst @@ -57,7 +57,7 @@ - **senseair:** ``abc_disable``, ``abc_enable``, ``abc_get_period``, ``background_calibration``, ``background_calibration_result`` - **servo:** ``detach``, ``write`` - **sim800l:** ``connect``, ``dial``, ``disconnect``, ``send_sms``, ``send_ussd`` -- **speaker:** ``play``, ``stop`` +- **speaker:** ``play``, ``stop``, ``finish``, ``volume_set`` - **sprinkler:** ``clear_queued_valves``, ``next_valve``, ``pause``, ``previous_valve``, ``queue_valve``, ``resume``, ``resume_or_start_full_cycle``, ``set_divider``, ``set_multiplier``, ``set_repeat``, ``set_valve_run_duration``, ``shutdown``, ``start_from_queue``, ``start_full_cycle``, ``start_single_valve`` - **sps30:** ``start_fan_autoclean`` - **stepper:** ``report_position``, ``set_acceleration``, ``set_deceleration``, ``set_speed``, ``set_target`` diff --git a/automations/all_conditions.rst b/automations/all_conditions.rst index 2b55ebdd6b..cf945e57f2 100644 --- a/automations/all_conditions.rst +++ b/automations/all_conditions.rst @@ -8,7 +8,7 @@ - **fan:** ``is_off``, ``is_on`` - **light:** ``is_off``, ``is_on`` - **lock:** ``is_locked``, ``is_unlocked`` -- **media_player:** ``is_idle``, ``is_playing`` +- **media_player:** ``is_announcing``, ``is_idle``, ``is_paused``, ``is_playing`` - **micro_wake_word:** ``is_running`` - **microphone:** ``is_capturing`` - **mqtt:** ``connected`` diff --git a/changelog/2024.11.0.rst b/changelog/2024.11.0.rst new file mode 100644 index 0000000000..8c4d04639e --- /dev/null +++ b/changelog/2024.11.0.rst @@ -0,0 +1,257 @@ +ESPHome 2024.11.0 - 20th November 2024 +====================================== + +.. seo:: + :description: Changelog for ESPHome 2024.11.0. + :image: /_static/changelog-2024.11.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + AXS15231, components/touchscreen/axs15231, axs15231.svg + ES8311, components/audio_dac/es8311, es8311.svg + i2c_device, components/i2c_device, i2c.svg + MAX17043, components/sensor/max17043, max17043.jpg + OpenTherm, components/opentherm, opentherm.png + TC74, components/sensor/tc74, tc74.jpg + + +ESPHome has grown over time and become more friendly for vendors to create and pre-install ESPHome onto devices +they sell / give away / provide. We are seeing more devices with ESPHome pre-installed, and we are so happy to +see how accessible it is becoming for regular Home Assistant users (not just developers or tech-savvy people) to +get their hands on a device that; A, works out of the box, B, works locally, and C can be fully customized by +the person who bought it if they choose to do so. +Because there are now more devices you can buy and do not have to install ESPHome onto yourself, we have made some +updates to allow ignoring these discovered devices from the ESPHome Dashboard as for most of these devices, you +don't actually need to **take control** and write and manage your own firmware for them. + +Further to this, we have slightly changed the identity of ESPHome as an add-on in Home Assistant. It is now called +**ESPHome Device Compiler**, because that is what it does, and most people do not need it if they are not going to +actually compile anything. + +OpenTherm +--------- + +This release brings :doc:`/components/opentherm` support to ESPHome. Please see the :doc:`documentation ` for detailed information about +it and how to use it. + + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- Support ignoring discovered devices from the dashboard :esphomepr:`7665` by :ghuser:`jesserockz` (new-feature) +- [media_player] Add new media player conditions :esphomepr:`7667` by :ghuser:`kahrendt` (new-feature) + +New Components +^^^^^^^^^^^^^^ + +- Add TC74 temperature sensor :esphomepr:`7460` by :ghuser:`sethgirvan` (new-integration) +- Add support for Analog Devices MAX17043 battery fuel gauge :esphomepr:`7522` by :ghuser:`blacknell` (new-integration) +- [speaker, i2s_audio] I2S Speaker implementation using a ring buffer :esphomepr:`7605` by :ghuser:`kahrendt` (new-integration) +- [axs15231] Touchscreen driver :esphomepr:`7592` by :ghuser:`clydebarrow` (new-integration) +- i2c_device :esphomepr:`7641` by :ghuser:`gabest11` (new-integration) +- [es8311] Add es8311 dac component :esphomepr:`7693` by :ghuser:`kahrendt` (new-integration) +- Add OpenTherm component (part 3: rest of the sensors) :esphomepr:`7676` by :ghuser:`olegtarasov` (new-integration) + +New Platforms +^^^^^^^^^^^^^ + +- [qspi_dbi] Rename from qspi_amoled, add features :esphomepr:`7594` by :ghuser:`clydebarrow` (breaking-change) (new-platform) +- Add OpenTherm component (part 2.1: sensor platform) :esphomepr:`7529` by :ghuser:`olegtarasov` (new-platform) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- [qspi_dbi] Rename from qspi_amoled, add features :esphomepr:`7594` by :ghuser:`clydebarrow` (breaking-change) (new-platform) +- [lvgl] light schema should require `widget:` not `led:` (Bugfix) :esphomepr:`7649` by :ghuser:`clydebarrow` (breaking-change) +- [http_request] Always return defined server response status :esphomepr:`7689` by :ghuser:`clydebarrow` (breaking-change) +- [touchscreen] Calibration fixes :esphomepr:`7704` by :ghuser:`clydebarrow` (breaking-change) +- [spi_device] rename mode to spi_mode :esphomepr:`7724` by :ghuser:`clydebarrow` (breaking-change) +- Update UNIT_VOLT_AMPS_REACTIVE = "var" (Currently 'VAR') :esphomepr:`7643` by :ghuser:`Roving-Ronin` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Fix temperature and humidity for bme680 with bsec2 :esphomepr:`7728` by :ghuser:`luar123` +- [i2s_audio] Bugfix: Adjust I2S speaker setup priority :esphomepr:`7759` by :ghuser:`kahrendt` +- Update UNIT_VOLT_AMPS_REACTIVE = "var" (Currently 'VAR') :esphomepr:`7643` by :ghuser:`Roving-Ronin` (breaking-change) +- Fix reactive power unit of measurement from VAR to var :esphomepr:`7757` by :ghuser:`felipecrs` +- Disable bluetooth proxy during update :esphomepr:`7695` by :ghuser:`jzucker2` +- ld2420: fix typo in log message :esphomepr:`7758` by :ghuser:`bfabio` +- TuyaFan control should use oscillation_type :esphomepr:`7776` by :ghuser:`pethans` +- Bump esphome-dashboard to 20241118.0 :esphomepr:`7782` by :ghuser:`jesserockz` +- [http_request] Feed watchdog timeout around http request functions :esphomepr:`7786` by :ghuser:`jesserockz` +- Bump esphome-dashboard to 20241120.0 :esphomepr:`7787` by :ghuser:`jesserockz` + +All changes +^^^^^^^^^^^ + +- Update `pillow` to 10.4.0 :esphomepr:`7566` by :ghuser:`hostcc` +- Bump actions/upload-artifact from 4.4.2 to 4.4.3 :esphomepr:`7575` by :ghuser:`dependabot[bot]` +- [fix] ESP32-C6 Reset Reasons :esphomepr:`7578` by :ghuser:`rvalitov` +- [light] Add ``initial_state`` configuration :esphomepr:`7577` by :ghuser:`jesserockz` +- [CI] failures when installing using apt-get. :esphomepr:`7593` by :ghuser:`clydebarrow` +- [web_server] expose event compoent to REST :esphomepr:`7587` by :ghuser:`RFDarter` +- Update test_build_components :esphomepr:`7597` by :ghuser:`tomaszduda23` +- [fix] ESP32-C6: internal temperature reporting :esphomepr:`7579` by :ghuser:`rvalitov` +- [code-quality] statsd component :esphomepr:`7603` by :ghuser:`tomaszduda23` +- [automation] Implement all and any condition shortcuts :esphomepr:`7565` by :ghuser:`clydebarrow` +- Add TC74 temperature sensor :esphomepr:`7460` by :ghuser:`sethgirvan` (new-integration) +- [display] filled_ring and filled_gauge methods added :esphomepr:`7420` by :ghuser:`artemyevav` +- [fix] deprecated functions warnings for logger component with ESP IDF version 5.3.0+ :esphomepr:`7600` by :ghuser:`rvalitov` +- [lvgl] Implement better software rotation :esphomepr:`7595` by :ghuser:`clydebarrow` +- [qspi_dbi] Rename from qspi_amoled, add features :esphomepr:`7594` by :ghuser:`clydebarrow` (breaking-change) (new-platform) +- Add support for Analog Devices MAX17043 battery fuel gauge :esphomepr:`7522` by :ghuser:`blacknell` (new-integration) +- chore: bump pyyaml to 6.0.2 to support py3.13 build :esphomepr:`7610` by :ghuser:`chenrui333` +- chore: bump platformio to 6.1.16 to support py3.13 build :esphomepr:`7590` by :ghuser:`chenrui333` +- [speaker, i2s_audio] I2S Speaker implementation using a ring buffer :esphomepr:`7605` by :ghuser:`kahrendt` (new-integration) +- Bump arduino-mlx90393 to 1.0.2 :esphomepr:`7618` by :ghuser:`functionpointer` +- [fix] ESP32-C6 BLE compile error :esphomepr:`7580` by :ghuser:`rvalitov` +- [axs15231] Touchscreen driver :esphomepr:`7592` by :ghuser:`clydebarrow` (new-integration) +- [lvgl] Roller and Dropdown enhancements; :esphomepr:`7608` by :ghuser:`clydebarrow` +- [code-quality] udp component :esphomepr:`7602` by :ghuser:`tomaszduda23` +- [lvgl] Revise code generation to allow early widget creation :esphomepr:`7611` by :ghuser:`clydebarrow` +- [lvgl] Allow esphome::Image in lambda to update image source directly :esphomepr:`7624` by :ghuser:`guillempages` +- Bump bme68x_bsec2 version to 1.8.2610 :esphomepr:`7626` by :ghuser:`shvmm` +- Update Pull request template :esphomepr:`7620` by :ghuser:`jesserockz` +- [lvgl] Defer display rotation reset until setup(). (Bugfix) :esphomepr:`7627` by :ghuser:`clydebarrow` +- [lvgl] light schema should require `widget:` not `led:` (Bugfix) :esphomepr:`7649` by :ghuser:`clydebarrow` (breaking-change) +- [image] Fix compile time problem with host image not using lvgl :esphomepr:`7654` by :ghuser:`clydebarrow` +- [lvgl] Fix rotation code for 90deg (Bugfix) :esphomepr:`7653` by :ghuser:`clydebarrow` +- [lvgl] Allow strings to be interpreted as integers (Bugfix) :esphomepr:`7652` by :ghuser:`clydebarrow` +- [rtttl] Add ``get_gain()`` :esphomepr:`7647` by :ghuser:`edwardtfn` +- feat(MQTT): Add subscribe QoS to discovery :esphomepr:`7648` by :ghuser:`Rapsssito` +- i2c_device :esphomepr:`7641` by :ghuser:`gabest11` (new-integration) +- Bump actions/cache from 4.1.1 to 4.1.2 in /.github/actions/restore-python :esphomepr:`7659` by :ghuser:`dependabot[bot]` +- Bump actions/cache from 4.1.1 to 4.1.2 :esphomepr:`7660` by :ghuser:`dependabot[bot]` +- [speaker, i2s_audio] Support audio_dac component, mute actions, and improved logging :esphomepr:`7664` by :ghuser:`kahrendt` +- unified way how all platforms handle copy_files :esphomepr:`7614` by :ghuser:`tomaszduda23` +- updating ESP32 board definitions :esphomepr:`7650` by :ghuser:`asolochek` +- Support ignoring discovered devices from the dashboard :esphomepr:`7665` by :ghuser:`jesserockz` (new-feature) +- Bump esphome-dashboard to 20241025.0 :esphomepr:`7669` by :ghuser:`jesserockz` +- unified way how all platforms handle get_download_types :esphomepr:`7617` by :ghuser:`tomaszduda23` +- [media_player] Add new media player conditions :esphomepr:`7667` by :ghuser:`kahrendt` (new-feature) +- [code-quality] weikai.h :esphomepr:`7601` by :ghuser:`tomaszduda23` +- Bump actions/setup-python from 5.2.0 to 5.3.0 in /.github/actions/restore-python :esphomepr:`7671` by :ghuser:`dependabot[bot]` +- Bump actions/setup-python from 5.2.0 to 5.3.0 :esphomepr:`7670` by :ghuser:`dependabot[bot]` +- [image][online_image][animation] Fix transparency in RGB565 :esphomepr:`7631` by :ghuser:`clydebarrow` +- Add OpenTherm component (part 2.1: sensor platform) :esphomepr:`7529` by :ghuser:`olegtarasov` (new-platform) +- gp8403 : Add the possibility to use substitution for channel selection :esphomepr:`7681` by :ghuser:`SeByDocKy` +- [lvgl] Implement qrcode :esphomepr:`7623` by :ghuser:`clydebarrow` +- [bytebuffer] Rework ByteBuffer using templates :esphomepr:`7638` by :ghuser:`clydebarrow` +- [http_request] Always return defined server response status :esphomepr:`7689` by :ghuser:`clydebarrow` (breaking-change) +- [font] Fix failure with bitmap fonts :esphomepr:`7691` by :ghuser:`clydebarrow` +- [http_request] Add enum for status codes :esphomepr:`7690` by :ghuser:`clydebarrow` +- Support W5500 SPI-Ethernet polling mode if framework is supported :esphomepr:`7503` by :ghuser:`slakichi` +- Add asdf to gitignore (and dockerignore) :esphomepr:`7686` by :ghuser:`jzucker2` +- Add more prometheus metrics :esphomepr:`7683` by :ghuser:`jzucker2` +- Mopeka Pro Check improvement to allow user to configure the sensor reporting for lower quality readings :esphomepr:`7475` by :ghuser:`spbrogan` +- fix(WiFi): Fix strncpy missing NULL terminator [-Werror=stringop-truncation] :esphomepr:`7668` by :ghuser:`Rapsssito` +- let make new platform implementation in external components :esphomepr:`7615` by :ghuser:`tomaszduda23` +- remove use of delay :esphomepr:`7680` by :ghuser:`ssieb` +- fix build error :esphomepr:`7694` by :ghuser:`tomaszduda23` +- fix: [climate] Allow substitutions in `visual.temperature_step.{target_temperature,current_temperature}` :esphomepr:`7679` by :ghuser:`hostcc` +- Add in area and device to the prometheus labels :esphomepr:`7692` by :ghuser:`jzucker2` +- [http_request] Implement `on_error` trigger for requests :esphomepr:`7696` by :ghuser:`clydebarrow` +- Bump pypa/gh-action-pypi-publish from 1.10.3 to 1.11.0 :esphomepr:`7700` by :ghuser:`dependabot[bot]` +- [es8311] Add es8311 dac component :esphomepr:`7693` by :ghuser:`kahrendt` (new-integration) +- [sdl] Allow window to be resized. :esphomepr:`7698` by :ghuser:`clydebarrow` +- Add config for current temperature precision :esphomepr:`7699` by :ghuser:`JasonN3` +- [spi] Add mosi pin checks for displays :esphomepr:`7702` by :ghuser:`clydebarrow` +- [CI] Fix webserver defines to be present based on platform, not just framework :esphomepr:`7703` by :ghuser:`jesserockz` +- [touchscreen] Calibration fixes :esphomepr:`7704` by :ghuser:`clydebarrow` (breaking-change) +- [font] Add support for "glyphsets" :esphomepr:`7429` by :ghuser:`paravoid` +- [lvlg] fix tests :esphomepr:`7708` by :ghuser:`clydebarrow` +- [esp32_ble] Add disconnect as a virtual function to ``ESPBTClient`` :esphomepr:`7705` by :ghuser:`jesserockz` +- handle bad pin schemas :esphomepr:`7711` by :ghuser:`ssieb` +- datetime fix build_language_schema :esphomepr:`7710` by :ghuser:`tomaszduda23` +- [lvgl] Don't just throw key error if someone types a bad layout type :esphomepr:`7722` by :ghuser:`jesserockz` +- [spi_device] rename mode to spi_mode :esphomepr:`7724` by :ghuser:`clydebarrow` (breaking-change) +- feat(MQTT): Add `enable`, `disable` and `enable_on_boot` :esphomepr:`7716` by :ghuser:`Rapsssito` +- [lvgl] Allow multiple LVGL instances :esphomepr:`7712` by :ghuser:`clydebarrow` +- [fix] deprecated legacy driver tsens :esphomepr:`7658` by :ghuser:`rvalitov` +- [lvgl] Fix id config for the lvgl component (Bugfix) :esphomepr:`7731` by :ghuser:`clydebarrow` +- Bump pypa/gh-action-pypi-publish from 1.11.0 to 1.12.2 :esphomepr:`7730` by :ghuser:`dependabot[bot]` +- OTA: Fix IPv6 and multiple address support :esphomepr:`7414` by :ghuser:`dwmw2` +- Fix dashboard ip resolving :esphomepr:`7747` by :ghuser:`jesserockz` +- [docker] Bump curl, iputils-ping and libssl-dev :esphomepr:`7748` by :ghuser:`jesserockz` +- Remove the choice for MQTT logging if it is disabled :esphomepr:`7723` by :ghuser:`solarkennedy` +- [sensor] Make some values templatable :esphomepr:`7735` by :ghuser:`clydebarrow` +- [lvgl] Implement keypads :esphomepr:`7719` by :ghuser:`clydebarrow` +- [midea] Add temperature validation in do_follow_me method (bugfix) :esphomepr:`7736` by :ghuser:`DjordjeMandic` +- Add OpenTherm component (part 3: rest of the sensors) :esphomepr:`7676` by :ghuser:`olegtarasov` (new-integration) +- [i2s_audio] I2S speaker improvements :esphomepr:`7749` by :ghuser:`kahrendt` +- [opentherm] Message to string extend :esphomepr:`7755` by :ghuser:`FreeBear-nc` +- [sun] Implements `is_above_horizon()` :esphomepr:`7754` by :ghuser:`edwardtfn` +- [core] Ring buffer write functions use const pointer parameter :esphomepr:`7750` by :ghuser:`kahrendt` +- [Modbus Controller] Added `on_online` and `on_offline` automation :esphomepr:`7417` by :ghuser:`0x3333` +- Updated dfplayer logging to be more user-friendly :esphomepr:`7740` by :ghuser:`solarkennedy` +- Fix temperature and humidity for bme680 with bsec2 :esphomepr:`7728` by :ghuser:`luar123` +- [i2s_audio] Bugfix: Adjust I2S speaker setup priority :esphomepr:`7759` by :ghuser:`kahrendt` +- Update UNIT_VOLT_AMPS_REACTIVE = "var" (Currently 'VAR') :esphomepr:`7643` by :ghuser:`Roving-Ronin` (breaking-change) +- Fix reactive power unit of measurement from VAR to var :esphomepr:`7757` by :ghuser:`felipecrs` +- Disable bluetooth proxy during update :esphomepr:`7695` by :ghuser:`jzucker2` +- ld2420: fix typo in log message :esphomepr:`7758` by :ghuser:`bfabio` +- TuyaFan control should use oscillation_type :esphomepr:`7776` by :ghuser:`pethans` +- Bump esphome-dashboard to 20241118.0 :esphomepr:`7782` by :ghuser:`jesserockz` +- [http_request] Feed watchdog timeout around http request functions :esphomepr:`7786` by :ghuser:`jesserockz` +- Bump esphome-dashboard to 20241120.0 :esphomepr:`7787` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :doc:`2024.10.0` +- :doc:`2024.9.0` +- :doc:`2024.8.0` +- :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 5083b6fc9f..7763244d40 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2024.10.0.html + :url: /changelog/2024.11.0.html .. toctree:: :glob: diff --git a/components/audio_dac/es8311.rst b/components/audio_dac/es8311.rst new file mode 100644 index 0000000000..c7a9d67451 --- /dev/null +++ b/components/audio_dac/es8311.rst @@ -0,0 +1,81 @@ +ES8311 +====== + +.. seo:: + :description: Instructions for using ESPHome's ES8311 audio DAC platform to play media from your devices. + :image: es8311.svg + :keywords: ES8311, Audio, DAC, I2S, ESP32 + +The ``es8311`` platform allows your ESPHome devices to use the ES8311 low power mono audio codec. +This allows the playback of audio via the microcontroller from a range of sources via :doc:`/components/speaker/index` or +:doc:`/components/media_player/index`. + +The :ref:`I²C bus ` is required in your configuration as this is used to communicate with the ES8311. + +.. code-block:: yaml + + # Example configuration entry + audio_dac: + - platform: es8311 + +.. _config-es8311: + +Configuration variables: +------------------------ +- **bits_per_sample** (*Optional*, enum): The bit depth of the audio samples. One of ``16bit``, ``24bit``, or ``32bit``. Defaults to ``16bit``. +- **sample_rate** (*Optional*, positive integer): I2S sample rate. Defaults to ``16000``. +- **use_mclk** (*Optional*, bool): Use the MCLK signal to control the clock. Defaults to ``True``. +- **use_microphone** (*Optional*, bool): Configure the codec's ADC for microphone input. Defaults to ``False``. +- **mic_gain** (*Optional*, enum): The gain applied to the ADC microphones. One of ``MIN``, ``0DB``, ``6DB``, ``12DB``, ``18DB``, ``24DB``, ``30DB``, ``36DB``, ``42DB``, or ``MAX``. Defaults to ``42DB``. +- **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x18``. +- **i2c_id** (*Optional*): The ID of the :ref:`I²C bus ` the ES8311 is connected to. +- All other options from :ref:`Audio DAC `. + +Automations +----------- + +All :ref:`Audio DAC Automations ` are supported by this platform. + +Configuration Examples +---------------------- + +**ESP32 S3 Box 3**: + +.. code-block:: yaml + + audio_dac: + - platform: es8311 + id: es8311_dac + bits_per_sample: 16bit + sample_rate: 16000 + + i2s_audio: + - id: i2s_output + i2s_lrclk_pin: GPIO45 + i2s_bclk_pin: GPIO17 + i2s_mclk_pin: GPIO23 + + speaker: + - platform: i2s_audio + i2s_audio_id: i2s_output + id: speaker_id + i2s_dout_pin: GPIO15 + dac_type: external + sample_rate: 16000 + bits_per_sample: 16bit + channel: stereo + audio_dac: es8311_dac + + switch: + - platform: gpio + name: "Speaker Enable" + pin: GPIO46 + restore_mode: RESTORE_DEFAULT_ON + +See Also +-------- + +- :doc:`index` +- :apiref:`es8311/es8311.h` +- :apiref:`audio_dac/audio_dac.h` +- :ghedit:`Edit` diff --git a/components/display/index.rst b/components/display/index.rst index 6be87e1eea..9b0006fd04 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -125,6 +125,13 @@ Now that you know a bit more about ESPHome's coordinate system, let's draw some // ... and the same thing filled again it.filled_circle(20, 75, 10); + // Ring and half-ring. First draw the circle with a hole in it + // at [75,75] with inner raduis of 20 and outer of 30 + id.filled_ring(75, 75, 30, 20); + // and a "gauge": half-ring that is partially filled. + // Same position and size but 80% filled left to right + id.filled_gauge(75, 75, 30, 20, 80) + // Triangles... Let's draw the outline of a triangle from the [x,y] coordinates of its three points // [25,5], [100,5], [80,25] it.triangle(25, 5, 100, 5, 80, 25); diff --git a/components/display/qspi_amoled.rst b/components/display/qspi_dbi.rst similarity index 74% rename from components/display/qspi_amoled.rst rename to components/display/qspi_dbi.rst index 5d65d8b467..fbd54f7c87 100644 --- a/components/display/qspi_amoled.rst +++ b/components/display/qspi_dbi.rst @@ -1,20 +1,21 @@ -Quad SPI AMOLED Displays -======================== +Quad SPI Displays +================= .. seo:: - :description: Instructions for setting up quad SPI AMOLED displays. + :description: Instructions for setting up quad SPI displays. :image: t4-s3.jpg -.. _qspi_amoled: +.. _qspi_dbi: Models ------ -This display driver supports AMOLED displays with quad SPI interfaces. +This display driver supports AMOLED and LCD displays with quad SPI interfaces, using the MIPI DBI interface. This driver has been tested with the following displays: - Lilygo T4-S3 - Lilygo T-Display S3 AMOLED + - JC4832W535 board using AXS15231 Usage ----- @@ -36,19 +37,16 @@ ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`q .. code-block:: yaml - # Example minimal configuration entry + # Example configuration entry display: - - platform: qspi_amoled + - platform: qspi_dbi model: RM690B0 data_rate: 80MHz - spi_mode: mode0 dimensions: width: 450 height: 600 offset_width: 16 - color_order: rgb - invert_colors: false brightness: 255 cs_pin: GPIOXX reset_pin: GPIOXX @@ -58,7 +56,8 @@ ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`q Configuration variables: ************************ -- **model** (**Required**): One of ``RM67162`` or ``RM690B0``. +- **model** (**Required**): One of ``CUSTOM``, ``RM67162`` or ``RM690B0``. +- **init_sequence** (*Optional*, A list of byte arrays): Specifies the init sequence for the display. This is required when using the ``CUSTOM`` model - but may be empty. If specified for other models this data will be sent after the pre-configured sequence. - **cs_pin** (**Required**, :ref:`Pin Schema `): The chip select pin. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. - **enable_pin** (*Optional*, :ref:`Pin Schema `): The display enable pin. @@ -84,6 +83,7 @@ Configuration variables: - **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz`` (default), ``5MHz``, ``2MHz`` or ``1MHz``. - **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is ``MODE0``. - **invert_colors** (*Optional*): With this boolean option you can invert the display colors. +- **draw_from_origin** (*Optional*): When set, all partial display updates will start at the origin (0,0). Defaults to false. - **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. See :ref:`display-engine` for more information. @@ -115,7 +115,7 @@ Lilygo T4-S3 reset_pin: 17 display: - - platform: qspi_amoled + - platform: qspi_dbi model: RM690B0 data_rate: 80MHz spi_mode: mode0 @@ -162,7 +162,7 @@ Lilygo T-Display S3 AMOLED number: 21 display: - - platform: qspi_amoled + - platform: qspi_dbi model: RM67162 id: main_lcd dimensions: @@ -178,9 +178,56 @@ Lilygo T-Display S3 AMOLED enable_pin: 38 +JC4832W535 3.5" LCD Board +************************* + +This rotates the display into landscape mode using software rotation. + +.. code-block:: yaml + + psram: + mode: octal + speed: 80MHz + + spi: + id: display_qspi + type: quad + clk_pin: 47 + data_pins: [21,48,40,39] + + power_supply: + id: backlight_id + pin: 1 + enable_on_boot: true + + display: + - platform: qspi_dbi + model: axs15231 + data_rate: 40MHz + dimensions: + height: 480 + width: 320 + cs_pin: + number: 45 + ignore_strapping_warning: true + auto_clear_enabled: false + update_interval: never + init_sequence: + + i2c: + sda: 4 + scl: 8 + + touchscreen: + platform: axs15231 + transform: + swap_xy: true + mirror_y: true + + See Also -------- - :doc:`index` -- :apiref:`qspi_amoled/qspi_amoled.h` +- :apiref:`qspi_dbi/qspi_dbi.h` - :ghedit:`Edit` diff --git a/components/ethernet.rst b/components/ethernet.rst index bc2a5b4def..f5e1258744 100644 --- a/components/ethernet.rst +++ b/components/ethernet.rst @@ -90,11 +90,30 @@ SPI configuration variables: - **miso_pin** (**Required**, :ref:`config-pin`): The SPI MISO pin. - **cs_pin** (**Required**, :ref:`config-pin`): The SPI chip select pin. - **interrupt_pin** (*Optional*, :ref:`config-pin`): The interrupt pin. + This variable is **required** for older frameworks. See below. - **reset_pin** (*Optional*, :ref:`config-pin`): The reset pin. - **clock_speed** (*Optional*, float): The SPI clock speed. Any frequency between `8Mhz` and `80Mhz` is allowed, but the nearest integer division of `80Mhz` is used, i.e. `16Mhz` (`80Mhz` / 5) is used when `15Mhz` is configured. Default: `26.67Mhz`. +- **polling_interval** (*Optional*, :ref:`config-time`): If ``interrupt_pin`` is not set, + set the time interval for periodic polling. Minimum is 1ms, Defaults to 10ms. + Older frameworks may not support this variable. See below for details. + +If you are using a framework with the latest version, ESPHome provides +an SPI-based Ethernet module without interrupt pin. +Support for SPI polling mode (no interrupt pin) is provided by the following frameworks: + +- ESP-IDF 5.3 or later +- ESP-IDF 5.2.1 and later 5.2.x versions +- ESP-IDF 5.1.4 +- Arduino-ESP32 3.0.0 or later (**Caution**: PlatformIO does not support these Arduino-ESP32 versions) + +When building with frameworks that support SPI polling mode, either ``interrupt_pin`` +or ``polling_interval`` can be set. If you set both, ESPHome will throw an error. + +If you are using a framework that does not support SPI-based ethernet modules without interrupt pin, +``interrupt_pin`` is **required** and you cannot set ``polling_interval``. Advanced common configuration variables: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/components/font.rst b/components/font.rst index 8f215822c1..7de652a6b5 100644 --- a/components/font.rst +++ b/components/font.rst @@ -71,6 +71,16 @@ Next, create a ``font:`` section in your configuration: "\U000F05D4", # mdi-airplane-landing ] + - file: + type: gfonts + family: Roboto + id: roboto_european_core + size: 16 + glyphsets: + - GF_Latin_Core + - GF_Greek_Core + - GF_Cyrillic_Core + - file: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf" id: web_font size: 20 @@ -124,9 +134,26 @@ Configuration variables: If you want to use the same font in different sizes, create two font objects. Note: *size* is ignored by bitmap fonts. Defaults to ``20``. - **bpp** (*Optional*, int): The bit depth of the rendered font from OpenType/TrueType, for anti-aliasing. Can be ``1``, ``2``, ``4``, ``8``. Defaults to ``1``. -- **glyphs** (*Optional*, list): A list of characters you plan to use. Only the characters you specify - here will be compiled into the binary. Adjust this if you need some special characters or want to - reduce the size of the binary if you don't plan to use some glyphs. You can also specify glyphs by their codepoint (see below). Defaults to ``!"%()+=,-_.:°/?0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz``. +- **glyphsets** (*Optional*, list): A list of glyphsets you plan to use. Defaults to + ``GF_Latin_Kernel``, which contains the basic characters and necessary punctuation and symbols for + the English language. ``GF_Latin_Core`` is a more extended set that includes glyphs for the + languages of Europe and the Americas with over 5 million speakers. Other options include + ``GF_Arabic_Core``, ``GF_Cyrillic_Core``, ``GF_Greek_Core``, their ``Plus`` variants, as well as + ``GF_Latin_African``, ``GF_Latin_PriAfrican`` and ``GF_Latin_Vietnamese``. + See the `Google Fonts Glyphset documentation `_ + for an extensive list of all possible sets, along with their names and the languages supported by + each of those sets. Note that ``GF_Latin_Kernel`` may need to be included for glyphs for basic + characters such as numbers (0-9) and whitespace to be present. +- **glyphs** (*Optional*, list): A list of characters you plan to use, in addition to the characters + defined by the **glyphsets** option above. Adjust this list if you need some special characters or + want to reduce the size of the binary if you don't plan to use certain glyphs. Both single + characters (``a, b, c``) or strings of characters (``abc, def``) are acceptable options. You can + also specify glyphs by their codepoint (see below). +- **ignore_missing_glyphs** (*Optional*, boolean): By default, warnings are generated for any glyph + that is included in the defined **glyphsets** but not present in the configured font. Use this + setting to suppress those warnings. Please note that the absence of any manually defined glyphs + (specified via the **glyphs** option) will always be treated as an error and will not be influenced + by this setting. - **extras** (*Optional*, enum): A list of font glyph configurations you'd like to include within this font, from other OpenType/TrueType files (eg. icons from other font, but at the same size as the main font): - **file** (**Required**, string): The path of the font file with the extra glyphs. @@ -149,7 +176,7 @@ Configuration variables: To use fonts you will need to have the python ``pillow`` package installed, as ESPHome uses that package to translate the OpenType/TrueType and bitmap font files into an internal format. If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need - to install it using ``pip install "pillow==10.2.0"``. + to install it using ``pip install "pillow==10.4.0"``. See Also -------- @@ -159,4 +186,5 @@ See Also - :doc:`/components/lvgl/index` - `MDI cheatsheet `_ - `MDI font repository `_ +- `Google Fonts Glyphsets `_ - :ghedit:`Edit` diff --git a/components/http_request.rst b/components/http_request.rst index 9402450767..2f42ac5b9c 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -105,6 +105,7 @@ This :ref:`action ` sends a GET request. - **max_response_buffer_size** (*Optional*, integer): The maximum buffer size to be used to store the response. Defaults to ``1 kB``. - **on_response** (*Optional*, :ref:`Automation `): An automation to perform after the request is received. +- **on_error** (*Optional*, :ref:`Automation `): An automation to perform if the request cannot be completed. .. _http_request-post_action: @@ -166,6 +167,11 @@ The following variables are available for use in :ref:`lambdas `: - ``body`` as ``std::string`` which contains the response body when ``capture_response`` (see :ref:`http_request-get_action`) is set to ``true``. + .. note:: + + The ``status_code`` should be checked before using the ``body`` variable. A successful response will usually have + a status code of ``200``. Server errors such as "not found" (404) or "internal server error" (500) will have an appropriate status code, and may contain an error message in the ``body`` variable. + .. code-block:: yaml on_... @@ -181,6 +187,20 @@ The following variables are available for use in :ref:`lambdas `: - response->duration_ms - lambda: |- ESP_LOGD(TAG, "Response status: %d, Duration: %u ms", response->status_code, response->duration_ms); + on_error: + then: + - logger.log: "Request failed!" + + +.. _http_request-on_error: + +``on_error`` Trigger +----------------------- + +This automation will be triggered when the HTTP request fails to complete. This may be e.g. when the network is not available, +or the server is not reachable. This will *not* be triggered if the request +completes, even if the response code is not 200. No information on the type of error is available and no variables +are available for use in :ref:`lambdas `. See example usage above. .. _http_request-examples: @@ -246,7 +266,7 @@ can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax as s GET values from a JSON body response ************************************ -If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is +If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is set to player_volume you can do this, but note that checking for the presence of the key will prevent difficult-to-read error messages: @@ -265,17 +285,22 @@ whose ``id`` is set to ``player_volume``: capture_response: true on_response: then: - - lambda: |- - json::parse_json(body, [](JsonObject root) -> bool { - if (root["vol"]) { - id(player_volume).publish_state(root["vol"]); - return true; - } - else { - ESP_LOGD(TAG,"No 'vol' key in this json!"); - return false; - } - }); + - if: + condition: + lambda: return response->status_code == 200; + then: + - lambda: |- + json::parse_json(body, [](JsonObject root) -> bool { + if (root["vol"]) { + id(player_volume).publish_state(root["vol"]); + } else { + ESP_LOGD(TAG,"No 'vol' key in this json!"); + } + }); + else: + - logger.log: + format: "Error: Response status: %d, message %s" + args: [response->status_code, body.c_str()]; See Also -------- diff --git a/components/i2c.rst b/components/i2c.rst index df20ab6a4d..ec05601958 100644 --- a/components/i2c.rst +++ b/components/i2c.rst @@ -65,11 +65,12 @@ Configuration variables: address: 0x76 # ... -For I2C multiplexing see :doc:`/components/tca9548a`. +For I²C multiplexing see :doc:`/components/tca9548a`. See Also -------- - :doc:`/components/tca9548a` +- :doc:`/components/i2c_device` - :apiref:`i2c/i2c.h` - :ghedit:`Edit` diff --git a/components/i2c_device.rst b/components/i2c_device.rst new file mode 100644 index 0000000000..c51c0c158e --- /dev/null +++ b/components/i2c_device.rst @@ -0,0 +1,37 @@ +Generic I²C device component: +----------------------------- +.. _i2c_device: + +General-purpose I²C device component that can be used to communicate with hardware not supported by a specific component. It allows selection of the I²C address. Reads and writes on the device can be performed with lambdas. For example: + +.. code-block:: yaml + + i2c: + sda: 4 + scl: 5 + scan: True + + i2c_device: + id: i2cdev + address: 0x2C + + on...: + then: + - lambda: !lambda |- + id(i2cdev).write_byte(0x00, 0x12); + if (auto b = id(i2cdev).read_byte(0x01)) { + // TODO + } + + +Configuration variables: +------------------------ + +- **address** (*Required*, int): I²C address of the device. + +See Also +-------- + +- :doc:`/components/i2c` +- :apiref:`i2c_device/i2c_device.h` +- :ghedit:`Edit` diff --git a/components/images/opentherm-shield.png b/components/images/opentherm-shield.png new file mode 100644 index 0000000000..7ed9af18df Binary files /dev/null and b/components/images/opentherm-shield.png differ diff --git a/components/light/index.rst b/components/light/index.rst index 9d0ac4ed3e..5ced32c281 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -5,11 +5,10 @@ Light Component :description: Instructions for setting up lights and light effects in ESPHome. :image: folder-open.svg -The ``light`` domain in ESPHome lets you create lights that will -automatically be shown in Home Assistant’s frontend and have many -features such as RGB colors, transitions, flashing and effects. +In ESPHome, ``light`` components allow you to create lights usable from Home Assistant's frontend and have many +features such as colors, transitions and even effects. -This component restores its state on reboot/reset. +This component can restore its state on reboot/reset if configured to do so. .. _config-light: @@ -24,25 +23,39 @@ All light configuration schemas inherit these options. - platform: ... -Configuration variables: +**Configuration variables:** -- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. +- **platform** (**Required**, platform): A light platform. See the following for details: + + .. toctree:: + :maxdepth: 1 + :glob: + + * + +- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be + specified. - **name** (*Optional*, string): The name of the light. At least one of **id** and **name** must be specified. .. note:: - If you have a :ref:`friendly_name ` set for your device and - you want the light to use that name, you can set ``name: None``. + If you have a :ref:`friendly_name ` set for your device and you want the light + to use that name, you can set ``name: None``. - **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend. - **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. -- **gamma_correct** (*Optional*, float): Apply a `gamma correction - factor `__ to the light channels. - Defaults to ``2.8``. -- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length - to use when no transition length is set in the light call. Defaults to ``1s``. -- **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash - is called. Defaults to ``0s``. +- **gamma_correct** (*Optional*, float): Apply a `gamma correction factor + `__ to the light channels. Defaults to ``2.8``. +- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length to use when no + transition length is set in the light call. Defaults to ``1s``. +- **flash_transition_length** (*Optional*, :ref:`config-time`): The transition length to use when flash is called. + Defaults to ``0s``. +- **initial_state** (*Optional*): The initial state the light should be set to on bootup. This state will be applied + when the state is **not** restored based on ``restore_mode`` (below). + + - **state** (*Optional*, :ref:`templatable `, boolean): The ON/OFF state for the light. + - All other options from :ref:`light state `. + - **restore_mode** (*Optional*): Control how the light attempts to restore state on bootup. - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. @@ -54,35 +67,82 @@ Configuration variables: - ``ALWAYS_OFF`` (Default) - Always initialize the light as OFF on bootup. - ``ALWAYS_ON`` - Always initialize the light as ON on bootup. -- **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform - when the light is turned on. See :ref:`light-on_turn_on_off_trigger`. -- **on_turn_off** (*Optional*, :ref:`Action `): An automation to perform - when the light is turned off. See :ref:`light-on_turn_on_off_trigger`. -- **on_state** (*Optional*, :ref:`Action `): An automation to perform - when the light's set state is changed. See :ref:`light-on_state_trigger`. +- **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform when the light is turned on. See + :ref:`light-on_turn_on_off_trigger`. +- **on_turn_off** (*Optional*, :ref:`Action `): An automation to perform when the light is turned off. + See :ref:`light-on_turn_on_off_trigger`. +- **on_state** (*Optional*, :ref:`Action `): An automation to perform when the light's set state is + changed. See :ref:`light-on_state_trigger`. -Additional configuration variables for addressable lights: +**Additional configuration variables for addressable lights:** -- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel. - This defines the maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the - green channel to be at most at 50% brightness. -- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to - this light. When the light is turned on, the power supply will automatically be switched on too. +- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel. This defines the + maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the green channel to be at most at + 50% brightness. +- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to this light. When + the light is turned on, the power supply will automatically be switched on too. -Advanced options: +**Advanced options:** -- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will - not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without - a ``name`` will implicitly set this to true. +- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the + frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true. - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, - (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). - Defaults to ``false``. -- **entity_category** (*Optional*, string): The category of the entity. - See https://developers.home-assistant.io/docs/core/entity/#generic-properties - for a list of available options. - Set to ``""`` to remove the default entity category. + (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``. +- **entity_category** (*Optional*, string): The category of the entity. See `this list + `__ for a list of available options. Set + to ``""`` to remove the default entity category. - If MQTT enabled, all other options from :ref:`MQTT Component `. -- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. +- If Webserver enabled and :ref:`version 3 ` is selected, all other options from + :doc:`/components/web_server`. + +.. _light-state_config: + +**Light state:** + +Some actions/configuration refer to **light state**. A **light state** may consist of any of the following +configuration variables: + +- **color_mode** (*Optional*, :ref:`templatable `): For lights that support more than one color + mode, the color mode that will be activated. The color mode determines which outputs of the light are active, and + which parameters can be used. For example, this can be used to switch between colored and white light. Must be a + color mode that is supported by the light. Valid color modes are: + + - ``ON_OFF``: Only on/off control. + - ``BRIGHTNESS``: Only brightness control. Accepts ``brightness`` parameter. + - ``WHITE``: Single white channel only. Accepts ``brightness`` and ``white`` parameters. + - ``COLOR_TEMPERATURE``: Color-temperature controlled white channel. Accepts ``brightness`` and ``color_temperature`` + parameters. + - ``COLD_WARM_WHITE``: Cold and warm white channels. Accepts ``brightness``, ``color_temperature``, ``cold_white`` and + ``warm_white`` parameters. + - ``RGB``: RGB color channels. Accepts ``brightness``, ``color_brightness``, ``red``, ``green`` and ``blue`` parameters. + - ``RGB_WHITE``: RGB color channels and a separate white channel. Accepts parameters from ``RGB`` and ``WHITE`` + color modes. + - ``RGB_COLOR_TEMPERATURE``: RGB color channels and a separate color-temperature controlled white channel. Accepts + parameters from ``RGB`` and ``COLOR_TEMPERATURE`` color modes. + - ``RGB_COLD_WARM_WHITE``: RGB color channels and two separate cold and warm white channels. Accepts parameters + from ``RGB`` and ``COLD_WARM_WHITE`` color modes. + +- **brightness** (*Optional*, percentage, :ref:`templatable `): The primary brightness of the light; + applies to all channels (both color and white) of the light. +- **color_brightness** (*Optional*, percentage, :ref:`templatable `): The brightness of the color + lights. Useful to control brightness of colored and white lights separately for RGBW lights. +- **red** (*Optional*, percentage, :ref:`templatable `): The red channel of the light. +- **green** (*Optional*, percentage, :ref:`templatable `): The green channel of the light. +- **blue** (*Optional*, percentage, :ref:`templatable `): The blue channel of the light. +- **white** (*Optional*, percentage, :ref:`templatable `): The brightness of the white channel. +- **color_temperature** (*Optional*, float, :ref:`templatable `): The color temperature (in `mireds + `__ or Kelvin) of the white channel. +- **cold_white** (*Optional*, percentage, :ref:`templatable `): The brightness of the cold white + channel. Cannot be used at the same time as *color_temperature*. +- **warm_white** (*Optional*, percentage, :ref:`templatable `): The brightness of the warm white + channel. Cannot be used at the same time as *color_temperature*. + +All percentage options accept values in the range ``0%`` to ``100%`` or ``0.0`` to ``1.0`` and they default to not +changing the current value (which might be the value from before the light was last turned off). To reset values, +explicitly set them to zero. + +Light Automations +----------------- .. _light-toggle_action: @@ -100,11 +160,11 @@ This action toggles a light with the given ID when executed. # Shorthand: - light.toggle: light_1 -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the light. -- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the transition - if the light supports it. +- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the + transition if the light supports it. .. note:: @@ -133,64 +193,25 @@ This action turns a light with the given ID on when executed. red: 100% green: 100% blue: 1.0 - # Templated - light.turn_on: id: light_1 brightness: !lambda |- // output value must be in range 0 - 1.0 return id(some_sensor).state / 100.0; - # Shorthand - light.turn_on: light_1 -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the light. -- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the transition - if the light supports it. -- **color_mode** (*Optional*, :ref:`templatable `): For lights that support more than one color mode, the color - mode that will be activated. The color mode determines which outputs of the light are active, and which parameters can be used. - This can for example be used to switch between colored and white light. Must be a color mode that is supported by the light. - Valid color modes are: - - - ``ON_OFF``: Only on/off control. - - ``BRIGHTNESS``: Only brightness control. Accepts *brightness* parameter. - - ``WHITE``: Single white channel only. Accepts *brightness* and *white* parameters. - - ``COLOR_TEMPERATURE``: Color-temperature controlled white channel. Accepts *brightness* and *color_temperature* - parameters. - - ``COLD_WARM_WHITE``: Cold and warm white channels. Accepts *brightness*, *color_temperature*, *cold_white* and - *warm_white* parameters. - - ``RGB``: RGB color channels. Accepts *brightness*, *color_brightness*, *red*, *green* and *blue* parameters. - - ``RGB_WHITE``: RGB color channels and a separate white channel. Accepts parameters from ``RGB`` and ``WHITE`` - color modes. - - ``RGB_COLOR_TEMPERATURE``: RGB color channels and a separate color-temperature controlled white channel. Accepts - parameters from ``RGB`` and ``COLOR_TEMPERATURE`` color modes. - - ``RGB_COLD_WARM_WHITE``: RGB color channels and two separate cold and warm white channels. Accepts parameters - from ``RGB`` and ``COLD_WARM_WHITE`` color modes. - -- **brightness** (*Optional*, percentage, :ref:`templatable `): The master brightness of the light, that - applies to all channels (both color and white) of the light. -- **color_brightness** (*Optional*, percentage, :ref:`templatable `): The brightness of the color lights. Useful - to control brightness of colored and white lights separately for RGBW lights. -- **red** (*Optional*, percentage, :ref:`templatable `): The red channel of the light. -- **green** (*Optional*, percentage, :ref:`templatable `): The green channel of the light. -- **blue** (*Optional*, percentage, :ref:`templatable `): The blue channel of the light. -- **white** (*Optional*, percentage, :ref:`templatable `): The brightness of the white channel. -- **color_temperature** (*Optional*, float, :ref:`templatable `): The color temperature - (in `mireds `__ or Kelvin) of the white channel. -- **cold_white** (*Optional*, percentage, :ref:`templatable `): The brightness of the cold white channel. - Cannot be used at the same time as *color_temperature*. -- **warm_white** (*Optional*, percentage, :ref:`templatable `): The brightness of the warm white channel. - Cannot be used at the same time as *color_temperature*. -- **flash_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): If set, will flash the given color - for this period of time and then go back to the previous state. -- **effect** (*Optional*, string, :ref:`templatable `): If set, will attempt to - start an effect with the given name. - -All percentage options accept values in the range ``0%`` to ``100%`` or ``0.0`` to ``1.0``, and default to not changing -the current value (which might be the value from before the light was last turned off). To reset values, explicitly set -them to zero. +- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the + transition if the light supports it. +- **flash_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): If set, will flash the + given color for this period of time and then go back to the previous state. +- **effect** (*Optional*, string, :ref:`templatable `): If set, will attempt to start an effect + with the given name. +- All other options from :ref:`light state `. .. note:: @@ -219,16 +240,15 @@ them to zero. .. note:: - The ``red``, ``green`` and ``blue`` values only control the color of the light, not its - brightness! If you assign ``50%`` to all RGB channels it will be interpreted as 100% on. - Only use ``brightness`` or ``color_brightness`` to control the brightness of the light. + The ``red``, ``green`` and ``blue`` values only control the color of the light, not its brightness! If you assign + ``50%`` to all RGB channels it will be interpreted as 100% on. Only use ``brightness`` or ``color_brightness`` to + control the brightness of the light. .. note:: - The master brightness (``brightness``) and separate brightness controls for the color and - white channels (``color_brightness``, ``white``, ``cold_white`` and ``warm_white``) are - multiplied together. Thus, this will result in color at 40% brightness and white at 60% - brightness: + The master brightness (``brightness``) and separate brightness controls for the color and white channels + (``color_brightness``, ``white``, ``cold_white`` and ``warm_white``) are multiplied together. Thus, this will + result in color at 40% brightness and white at 60% brightness: .. code-block:: yaml @@ -251,15 +271,14 @@ This action turns a light with the given ID off when executed. then: - light.turn_off: id: light_1 - # Shorthand - light.turn_off: light_1 -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the light. -- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the transition - if the light supports it. +- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable `): The length of the + transition if the light supports it. .. note:: @@ -278,8 +297,8 @@ Configuration variables: ``light.control`` Action ************************ -This :ref:`Action ` is a generic call to change the state of a light - it -is essentially just a combination of the turn_on and turn_off calls. +This :ref:`Action ` is a generic call to change the state of a light - it is essentially just a +combination of the turn_on and turn_off calls. .. code-block:: yaml @@ -289,20 +308,18 @@ is essentially just a combination of the turn_on and turn_off calls. id: light_1 state: on -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the light. -- **state** (*Optional*, :ref:`templatable `, boolean): Change the ON/OFF - state of the light. -- All other options from :ref:`light.turn_on `. +- **state** (*Optional*, :ref:`templatable `, boolean): Change the ON/OFF state of the light. +- All other options from :ref:`light state `. .. _light-dim_relative_action: ``light.dim_relative`` Action ***************************** -This :ref:`Action ` allows you to dim a light that supports brightness -by a relative amount. +This :ref:`Action ` allows you to dim a light that supports brightness by a relative amount. .. code-block:: yaml @@ -313,17 +330,18 @@ by a relative amount. id: light_1 relative_brightness: 5% -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the light. -- **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. +- **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: + - **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. @@ -357,8 +375,8 @@ Configuration variables: ``light.addressable_set`` Action ******************************** -This :ref:`Action ` allows you to manually set a range of LEDs on an addressable light -to a specific color. +This :ref:`Action ` allows you to manually set a range of LEDs on an addressable light to a specific +color. .. code-block:: yaml @@ -371,24 +389,20 @@ to a specific color. green: 0% blue: 0% -Configuration variables: +**Configuration variables:** - **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control. -- **range_from** (*Optional*, :ref:`templatable `, int): The beginning - of the range of LEDs to control, inclusive, using zero-based indexing. Defaults to 0 (the beginning of the strip). -- **range_to** (*Optional*, :ref:`templatable `, int): The end of the - range of LEDs to control, inclusive, using zero-based indexing. - Defaults to the end of the strip (``num_leds`` - 1). -- **color_brightness** (*Optional*, :ref:`templatable `, percentage): The brightness to - set the color channel to. -- **red** (*Optional*, :ref:`templatable `, percentage): The value to - set the red channel to. -- **green** (*Optional*, :ref:`templatable `, percentage): The value to - set the green channel to. -- **blue** (*Optional*, :ref:`templatable `, percentage): The value to - set the blue channel to. -- **white** (*Optional*, :ref:`templatable `, percentage): The brightness to - set the white channel to. +- **range_from** (*Optional*, :ref:`templatable `, int): The beginning of the range of LEDs to + control, inclusive, using zero-based indexing. Defaults to 0 (the beginning of the strip). +- **range_to** (*Optional*, :ref:`templatable `, int): The end of the range of LEDs to control, + inclusive, using zero-based indexing. Defaults to the end of the strip (``num_leds`` - 1). +- **color_brightness** (*Optional*, :ref:`templatable `, percentage): The brightness to set the + color channel to. +- **red** (*Optional*, :ref:`templatable `, percentage): The value to set the red channel to. +- **green** (*Optional*, :ref:`templatable `, percentage): The value to set the green channel to. +- **blue** (*Optional*, :ref:`templatable `, percentage): The value to set the blue channel to. +- **white** (*Optional*, :ref:`templatable `, percentage): The brightness to set the white channel + to. .. _light-is_on_condition: .. _light-is_off_condition: @@ -396,8 +410,8 @@ Configuration variables: ``light.is_on`` / ``light.is_off`` Condition ******************************************** -This :ref:`Condition ` checks if the given light is ON or OFF. OFF means -that the light is completely OFF, and ON means that the light is emitting at least a bit of light. +This :ref:`Condition ` checks if the given light is ON or OFF. OFF means that the light is completely +OFF, and ON means that the light is emitting at least a bit of light. .. code-block:: yaml @@ -414,8 +428,8 @@ that the light is completely OFF, and ON means that the light is emitting at lea ``light.on_turn_on`` / ``light.on_turn_off`` Trigger **************************************************** -This trigger is activated each time the light is turned on or off. It is consistent -with the behavior of the ``light.is_on`` and ``light.is_off`` condition above. +This trigger is activated each time the light is turned on or off. It is consistent with the behavior of the +``light.is_on`` and ``light.is_off`` condition above. .. code-block:: yaml @@ -432,10 +446,9 @@ with the behavior of the ``light.is_on`` and ``light.is_off`` condition above. ``light.on_state`` Trigger ************************** -This trigger is activated each time the set light state is changed. It is not triggered -based on current state, but rather, it triggers on the set state which can differ from -the current state due to transitions. For example, the ``light.on_state`` trigger can -be used for immediate action when the light is set to off; while ``light.on_turn_off`` +This trigger is activated each time the set light state is changed. It is not triggered based on current state, but +rather, it triggers on the set state which can differ from the current state due to transitions. For example, the +``light.on_state`` trigger can be used for immediate action when the light is set to off; while ``light.on_turn_off`` does not trigger until the light actually achieves the off state. .. code-block:: yaml @@ -451,13 +464,11 @@ does not trigger until the light actually achieves the off state. Light Effects ------------- -ESPHome also offers a bunch of light effects you can use for your lights. The defaults for the -effect parameters are made to work well on their own but of course ESPHome gives you the option to manually change -these parameters. +ESPHome has several built-in/pre-defined light effects you can use for your lights. The defaults for the effect +parameters are made to work well on their own, but ESPHome also allows you to manually change these parameters. -With ESPHome's light effects system you're basically creating a bunch of entries for the effects dropdown in -Home Assistant. If you wish to have several variants of the same effect you can of course also create multiple -entries with each having a unique name like so: +Each effect you define in ESPHome will appear as an entry in the effects dropdown for the light in Home Assistant. If +you wish to have several variants of the same effect, you can create multiple entries, each having a unique name: .. code-block:: yaml @@ -479,12 +490,16 @@ entries with each having a unique name like so: .. note:: - After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the ``effect`` to ``none`` when it is being called through Home Assistant or directly on the device. + After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the + ``effect`` to ``none`` when it is being called through Home Assistant or directly on the device. Pulse Effect ************ -This effect makes a pulsating light. The period can be defined by ``update_interval``, the transition length with ``transition_length``. ``transition_length`` should be set to less than ``update_interval``, setting ``transition_length`` to ``1s`` and ``update_interval`` to ``2s`` will result in a transition from 0% to 100% lasting 1 second, 1 second full light, a transition from 100% to 0% for 1 second and off for 1 second. +This effect makes a pulsating light. The period can be defined by ``update_interval``, the transition length with +``transition_length``. ``transition_length`` should be set to less than ``update_interval``, setting +``transition_length`` to ``1s`` and ``update_interval`` to ``2s`` will result in a transition from 0% to 100% lasting +1 second, 1 second full light, a transition from 100% to 0% for 1 second and off for 1 second. .. code-block:: yaml @@ -501,7 +516,7 @@ This effect makes a pulsating light. The period can be defined by ``update_inter max_brightness: 100% - pulse: name: "Slow Pulse" - # transition_length: 1s # defaults to 1s + transition_length: 500ms update_interval: 2s - pulse: name: "Asymmetrical Pulse" @@ -510,23 +525,24 @@ This effect makes a pulsating light. The period can be defined by ``update_inter off_length: 500ms update_interval: 1.5s -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``. -- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. - Defaults to ``1s``. Can be a single time or split for on and off using these nested options. +- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``. Can be a + single time or split for on and off using these nested options. - **on_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned on. - **off_length** (*Optional*, :ref:`config-time`): The duration of the transition when the light is turned off. -- **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to ``1s``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to + ``1s``. - **min_brightness** (*Optional*, percentage): The minimum brightness value. Defaults to ``0%`` - **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%`` - Random Effect ************* -This effect makes a transition (of length ``transition_length``) to a randomly-chosen color and/or brightness (e.g. monochromatic) every ``update_interval``. +This effect makes a transition (of length ``transition_length``) to a randomly-chosen color and/or brightness (for +monochromatic) every ``update_interval``. .. code-block:: yaml @@ -540,12 +556,12 @@ This effect makes a transition (of length ``transition_length``) to a randomly-c transition_length: 5s update_interval: 7s -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Random``. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition to start. Defaults to ``5s``. -- **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and transitioned - to. +- **update_interval** (*Optional*, :ref:`config-time`): The interval with which a new color is selected and + transitioned to. Strobe Effect ************* @@ -577,7 +593,7 @@ This effect cycles through a list of colors with specific durations. blue: 0% duration: 500ms -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Strobe``. - **colors** (*Optional*, list): A list of colors to cycle through. Defaults to a quick cycle between ON and OFF. @@ -590,13 +606,14 @@ Configuration variables: - **green** (*Optional*, percentage): The green channel of the light, if applicable. Defaults to ``100%``. - **blue** (*Optional*, percentage): The blue channel of the light, if applicable. Defaults to ``100%``. - **white** (*Optional*, percentage): The white channel of the light, if applicable. Defaults to ``100%``. - - **color_temperature** (*Optional*, float): The color temperature (in `mireds `__ or Kelvin) of the light, if applicable. + - **color_temperature** (*Optional*, float): The color temperature (in `mireds `__ + or Kelvin) of the light, if applicable. - **cold_white** (*Optional*, percentage): The cold white channel of the light, if applicable. Defaults to ``100%``. - **warm_white** (*Optional*, percentage): The warm white channel of the light, if applicable. Defaults to ``100%``. - **duration** (**Required**, :ref:`config-time`): The duration this color should be active. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``0s``. -See `light.turn_on ` for more information on the various color fields. +See :ref:`light state ` for more information on the various color fields. Flicker Effect ************** @@ -615,11 +632,11 @@ This effect "hovers" around the active color of the light and flickers each colo alpha: 95% intensity: 1.5% -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Flicker``. -- **alpha** (*Optional*, percentage): The percentage that the last color value should affect the light. More - or less the "forget-factor" of an exponential moving average. Defaults to ``95%``. +- **alpha** (*Optional*, percentage): The percentage that the last color value should affect the light. More or less + the "forget-factor" of an exponential moving average. Defaults to ``95%``. - **intensity** (*Optional*, percentage): The intensity of the flickering, basically the maximum amplitude of the random offsets. Defaults to ``1.5%``. @@ -630,7 +647,8 @@ This effect allows you to write completely custom light effects yourself using : Available variable in the lambda: -- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. +- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when + restarting an effect. .. code-block:: yaml @@ -660,20 +678,19 @@ Available variable in the lambda: if (state == 4) state = 0; -Configuration variables: +**Configuration variables:** - **name** (**Required**, string): The name of the custom effect. -- **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed. - A value of ``0ms`` means that the lambda is always executed, without a cool-down. Defaults to ``0ms``. -- **lambda** (**Required**, :ref:`lambda `): The code to execute. ``static`` variables are - especially useful. - +- **update_interval** (*Optional*, :ref:`config-time`): The interval with which the lambda code is executed. A value of + ``0ms`` means that the lambda is always executed, without a cool-down. Defaults to ``0ms``. +- **lambda** (**Required**, :ref:`lambda `): The code to execute. ``static`` variables are especially + useful. Addressable Rainbow Effect ************************** -A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using -the HSV color wheel. +A light effect for individually-addressable LEDs that creates a moving rainbow over the whole LED strip using the HSV +color wheel. .. code-block:: yaml @@ -687,18 +704,17 @@ the HSV color wheel. speed: 10 width: 50 -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Rainbow``. - **speed** (*Optional*, int): The speed of the effect, unitless. Defaults to ``10``. - **width** (*Optional*, int): The "width" of a full-scale rainbow, unitless. Defaults to ``50``. - Addressable Color Wipe Effect ***************************** -A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of -the strip and shifts them forward every ``add_led_interval``. +A light effect for individually-addressable LEDs that continuously introduces new colors at the beginning of the strip +and shifts them forward every ``add_led_interval``. .. code-block:: yaml @@ -722,7 +738,7 @@ the strip and shifts them forward every ``add_led_interval``. add_led_interval: 100ms reverse: false -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Color Wipe``. - **colors** (*Optional*, list): The colors to shift in at the beginning of the strip. Defaults to shifting in random @@ -733,18 +749,20 @@ Configuration variables: - **blue** (*Optional*, percentage): The percentage the blue color channel should be on. Defaults to ``100%``. - **random** (*Optional*, boolean): If set to ``true``, will overwrite the RGB colors by a new, randomly-chosen color each time. Defaults to ``false``. - - **num_leds** (**Required**, positive int): The number of LEDs of this type to have before transitioning to the next color. If ``gradient`` is true, this will be the number of LEDs over which the color transition will occur. - - **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds`` to the next color. Defaults to ``false``. + - **num_leds** (**Required**, positive int): The number of LEDs of this type to have before transitioning to the next + color. If ``gradient`` is true, this will be the number of LEDs over which the color transition will occur. + - **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds`` + to the next color. Defaults to ``false``. -- **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new leds at the - beginning of the strip. Defaults to ``100ms``. +- **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new LEDs at the beginning + of the strip. Defaults to ``100ms``. - **reverse** (*Optional*, boolean): Whether to reverse the direction of the color wipe. Defaults to ``false``. Addressable Scan Effect *********************** -Create a single, fast-moving dot moving back and forth an individually-addressable LED strip. The color is chosen by the -currently active light color. +Creates a single, fast-moving dot "sliding" back and forth on the LED strip. The color is chosen by the currently +active light color. .. code-block:: yaml @@ -758,20 +776,18 @@ currently active light color. move_interval: 100ms scan_width: 1 -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Scan``. - **move_interval** (*Optional*, :ref:`config-time`): The interval with which to move the dot/line one LED forward. Defaults to ``100ms``. -- **scan_width** (*Optional*, int): The number of LEDs to use. - Defaults to ``1``. +- **scan_width** (*Optional*, int): The number of LEDs to use. Defaults to ``1``. Addressable Twinkle Effect ************************** -A light effect for individually-addressable LED strips that randomly chooses some LEDs and let's them bright -up for a moment, like a stars twinkling in the night's sky. The color of the pixels will be chosen by the -currently active light color. +Randomly chooses LEDs and brightens them for a moment, mimicking stars twinkling in the night sky. The color of the +pixels is determined by the current light color. .. code-block:: yaml @@ -785,13 +801,13 @@ currently active light color. twinkle_probability: 5% progress_interval: 4ms -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Twinkle``. -- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen - LED should start its twinkle animation. -- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This - affects the duration of a twinkle animation. Defaults to ``4ms``. +- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED + should start its twinkle animation. +- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects + the duration of a twinkle animation. Defaults to ``4ms``. Addressable Random Twinkle Effect ********************************* @@ -810,14 +826,13 @@ A light effect similar to ``addressable_twinkle``, but using random colors for e twinkle_probability: 5% progress_interval: 32ms -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Random Twinkle``. -- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen - LED should start its twinkle animation. -- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This - affects the duration of a twinkle animation. Defaults to ``4ms``. - +- **twinkle_probability** (*Optional*, percentage): The percentage with which, at any time step, a randomly-chosen LED + should start its twinkle animation. +- **progress_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. This affects + the duration of a twinkle animation. Defaults to ``4ms``. Addressable Fireworks Effect **************************** @@ -839,15 +854,15 @@ and lets the sparkles cascade over the LED strip. use_random_color: false fade_out_rate: 120 -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Fireworks``. -- **update_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. - Defaults to ``32ms``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval with which to progress the effect. Defaults to + ``32ms``. - **spark_probability** (*Optional*, percentage): The probability to start a new firework spark at a randomly-chosen LED at any given time step. Defaults to ``10%``. -- **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to - using the currently active light color. +- **use_random_color** (*Optional*, boolean): Whether to use random colors for new firework sparks. Defaults to using + the currently active light color. - **fade_out_rate** (*Optional*, int): The rate with which to fade out the LED strip, unitless. Needs to be carefully chosen so that the whole strip doesn't light up forever if the fade out rate is too low or that the firework sparks do not propagate for a long time. Defaults to ``120``. @@ -855,8 +870,8 @@ Configuration variables: Addressable Flicker Effect ************************** -An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers -each LED by its own random amount around the currently active light color. +An effect similar to the ``flicker`` effect, but for individually-addressable LED strips. This effect flickers each LED +by its own random amount around the currently active light color. .. code-block:: yaml @@ -870,11 +885,11 @@ each LED by its own random amount around the currently active light color. update_interval: 16ms intensity: 5% -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. Defaults to ``Addressable Flicker``. -- **update_interval** (*Optional*, :ref:`config-time`): The time interval for updating the random offsets. - Defaults to ``16ms``. +- **update_interval** (*Optional*, :ref:`config-time`): The time interval for updating the random offsets. Defaults to + ``16ms``. - **intensity** (*Optional*, percentage): The intensity of the effect, basically how much the random values can offset the currently active light color. Defaults to ``5%``. @@ -887,7 +902,8 @@ Available variables in the lambda: - **it** - :apiclass:`AddressableLight ` instance (see API reference for more info). - **current_color** - :apistruct:`ESPColor ` instance (see API reference for more info). -- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. +- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when + restarting an effect. .. note:: @@ -946,19 +962,17 @@ Available variables in the lambda: } -Examples of this API can be found here: -https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h +Examples of this API can be found +`here `__ (the built-in addressable light effects). Automation Light Effect *********************** -Additionally to the ``lambda`` and ``addressable_lambda`` light effects, effects can also -be written through ESPHome's :ref:`Automation ` system with the ``automation`` -effect type. +In addition to the ``lambda`` and ``addressable_lambda`` light effects, effects can also be created with ESPHome's +:ref:`Automation ` system with the ``automation`` effect type. -The automation given in the ``sequence`` block will be repeatedly executed until the effect -is stopped by the user. +The automation given in the ``sequence`` block will be repeatedly executed until the effect is stopped by the user. .. code-block:: yaml @@ -983,21 +997,20 @@ is stopped by the user. green: 0% blue: 0% -Configuration variables: +**Configuration variables:** - **name** (*Optional*, string): The name of the effect. -- **sequence** (*Optional*, :ref:`Action `): The actions to perform in sequence - until the effect is stopped. +- **sequence** (*Optional*, :ref:`Action `): The actions to perform in sequence until the effect is + stopped. .. _e131-light-effect: E1.31 Effect ************ -This effect enables controlling addressable lights using UDP-based -E1.31_ protocol. +This effect enables controlling addressable lights by way of the UDP-based E1.31_ protocol. -For Example JINX_ or Hyperion.NG_ could be used to control E1.31_ enabled ESPHome. +For example, when enabled, JINX_ or Hyperion.NG_ could be used to control the LEDs connected to the ESPHome device. .. code-block:: yaml @@ -1012,11 +1025,11 @@ For Example JINX_ or Hyperion.NG_ could be used to control E1.31_ enabled ESPHom universe: 1 channels: RGB -Configuration variables: +**Configuration variables:** - **universe** (**Required**, int): The value of universe, between 1 to 512. -- **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``, - ``RGB`` or ``RGBW`` light and in which order the colors are. Defaults to ``RGB``. +- **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``, ``RGB`` or ``RGBW`` light + and in which order the colors are. Defaults to ``RGB``. There are three modes of operation: @@ -1024,23 +1037,22 @@ There are three modes of operation: - ``RGB``: this supports 3 channels per LED (RGB), up-to 170 LEDs (3*170 = 510 bytes) per universe - ``RGBW``: this supports 4 channels per LED (RGBW), up-to 128 LEDs (4*128 = 512 bytes) per universe -If there's more LEDs than allowed per-universe, additional universe will be used. -In the above example of 189 LEDs, first 170 LEDs will be assigned to 1 universe, -the rest of 19 LEDs will be automatically assigned to 2 universe. +If there are more LEDs than allowed per universe, an additional universe will be used. In the above example of 189 +LEDs, first 170 LEDs will be assigned to universe 1, while the remaining 19 LEDs will be assigned to universe 2. -It is possible to enable multiple light platforms to listen to the same universe concurrently, -allowing to replicate the behaviour on multiple strips. +It is possible to enable multiple light platforms to concurrently listen to the same universe, allowing the behavior +to be replicated on multiple strips. E1.31 Component ^^^^^^^^^^^^^^^ The :ref:`e131-light-effect` requires a component hub for the ``e131`` light effect. -Configuration variables: +**Configuration variables:** - **method** (*Optional*): Listening method, one of ``multicast`` or ``unicast``. Defaults to ``multicast``. -The udp port esphome is listening on is 5568. +ESPHome will listen on UDP port ``5568``. .. _E1.31: https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol .. _JINX: http://www.live-leds.de/jinx-v1-3-with-resizable-mainwindow-real-dmx-and-sacne1-31/ @@ -1049,11 +1061,10 @@ The udp port esphome is listening on is 5568. Adalight Effect *************** -This effect enables controlling addressable lights using UART-based -Adalight_ protocol, allowing to create realtime ambient lighting effects. +This effect enables controlling addressable lights using the serial Adalight_ protocol, allowing the creation of +realtime ambient lighting effects. -Prismatik_ can be used to control addressable lights via Adalight_ protocol -on ESPHome. +Prismatik_ can be used to control addressable lights via Adalight_ protocol on ESPHome. .. code-block:: yaml @@ -1076,10 +1087,10 @@ on ESPHome. - adalight: # uart_id: additional_uart -Configuration variables: +**Configuration variables:** -- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want - to use multiple UART buses. +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component `. Useful if + you've configured multiple UARTs. .. _Adalight: https://learn.adafruit.com/adalight-diy-ambient-tv-lighting .. _Prismatik: https://github.com/psieg/Lightpack @@ -1087,12 +1098,11 @@ Configuration variables: WLED Effect *********** -This effect enables controlling addressable lights using UDP-based -`UDP Realtime Control`_ protocol used by WLED_, allowing to create realtime ambient -lighting effects. +This effect enables controlling addressable lights using the `UDP Realtime Control`_ protocol used by WLED_, allowing +creation of realtime ambient lighting effects. -Prismatik_ can be used to control addressable lights over network on ESPHome. -It is also possible to use LedFx_ to control the lights. Please use the connection type ``udp`` on the default port and add the Data Prefix ``0201``. +Prismatik_ and/or LedFx_ can be used to control addressable lights over the network on ESPHome. Use the connection type +``udp`` on the default port and add the data prefix ``0201``. .. code-block:: yaml @@ -1107,19 +1117,25 @@ It is also possible to use LedFx_ to control the lights. Please use the connecti # blank_on_start: True # sync_group_mask: 0 -Configuration variables: +**Configuration variables:** - **port** (*Optional*, int): The port to run the UDP server on. Defaults to ``21324``. - **blank_on_start** (*Optional*, boolean): Whether or not to blank all LEDs when effect starts. Deaults to ``True``. -- **sync_group_mask** (*Optional*, int): Used with WLED Notifier. The Sync Group mask value that specifies which WLED Sync Groups to listen to. Defaults to ``0`` (All Sync Groups). Sync Groups 1, 2, 3, 4, 5, 6, 7, 8 use masks 1, 2, 4, 8, 16, 32, 64, 128. Combine mask values to listen to multiple Sync Groups. +- **sync_group_mask** (*Optional*, int): Used with WLED Notifier. The Sync Group mask value that specifies which WLED + Sync Groups to listen to. Defaults to ``0`` (All Sync Groups). Sync Groups 1, 2, 3, 4, 5, 6, 7, 8 use masks 1, 2, 4, + 8, 16, 32, 64, 128. Combine mask values to listen to multiple Sync Groups. .. note:: - You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a - UDP device with protocol 0. + You can also set the ``port`` to ``19446`` for compatibility with Hyperion Classic using a UDP device with protocol 0. -Currently the following realtime protocols are supported: -WARLS, DRGB, DRGBW, DNRGB and WLED Notifier. +The following realtime protocols are supported: + +- WARLS +- DRGB +- DRGBW +- DNRGB +- WLED Notifier .. _UDP Realtime Control: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control .. _WLED: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control @@ -1132,9 +1148,3 @@ See Also - :apiref:`light/light_state.h` - `WS2812FX library `__ by `@kitesurfer1404 `__ - :ghedit:`Edit` - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/components/lvgl/index.rst b/components/lvgl/index.rst index 797395c4d7..17019cfb27 100644 --- a/components/lvgl/index.rst +++ b/components/lvgl/index.rst @@ -77,7 +77,7 @@ The following configuration variables apply to the main ``lvgl`` component, in o **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. +- **touchscreens** (*Optional*, list): A list of touchscreens interacting with the LVGL widgets on the display. If you configure a single touchscreen it will be used automatically, and this config entry will not be required. - **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``. @@ -124,8 +124,10 @@ The following configuration variables apply to the main ``lvgl`` component, in o +- **resume_on_input** (*Optional*, boolean): If LVGL is paused and the user interacts with the screen, resume the activity of LVGL. Defaults to ``true``. "Interacts" means to release a touch or button, or rotate an encoder. - **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%``. +- **draw_rounding** (*Optional*, int): An optional value to use for rounding draw areas to a specified boundary. Defaults to 2. Useful for displays that require draw windows to be on specified boundaries (usually powers of 2.) - **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. @@ -156,8 +158,6 @@ The following configuration variables apply to the main ``lvgl`` component, in o lvgl: displays: - my_display - touchscreens: - - my_touch pages: - id: main_page widgets: @@ -167,6 +167,27 @@ The following configuration variables apply to the main ``lvgl`` component, in o See :ref:`lvgl-cookbook-navigator` in the Cookbook for an example which demonstrates how to implement a page navigation bar at the bottom of the screen. +.. _lgvgl-multi-conf: + + +Multiple LVGL configurations +**************************** + +If you have multiple displays configured, and wish to have different content displayed on each display, you can configure multiple LVGL configurations. For example: + +.. code-block:: yaml + + lvgl: + - id: lvgl_1 + displays: display_1 + widgets: + - label: + text: 'Hello World #1!' + - id: lvgl_2 + displays: display_2 + widgets: + - label: + text: 'Hello World #2!' .. _lvgl-color: Colors @@ -587,15 +608,17 @@ A gradient is a sequence of colors which can be applied to an object using the ` 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. +Widgets support :ref:`general or specific ` actions - see the :doc:`/components/lvgl/widgets` section for more information. + +Several actions are available for the LVGL component itself, these are outlined below. Note that if multiple LVGL instances are configured, an **lvgl_id** config entry will be required to specify which instance the action relates to. This is not required if there is only a single LVGL instance configured. + .. _lvgl-redraw-action: @@ -605,12 +628,14 @@ Several actions are available for LVGL, these are outlined below. 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. +- **lvgl_id** (*Optional*): The ID of the LVGL instance to redraw. .. code-block:: yaml on_...: then: - lvgl.widget.redraw: + lvgl_id: lvgl1 # optional when only one LVGL instance is configured .. _lvgl-pause-action: @@ -620,6 +645,7 @@ This :ref:`action ` redraws the entire screen, or optionally onl 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. See :ref:`lvgl-cookbook-antiburn` for an example which demonstrates how to use this. +- **lvgl_id** (*Optional*): The ID of the LVGL instance to pause. .. code-block:: yaml @@ -635,12 +661,15 @@ This :ref:`action ` pauses the activity of LVGL, including rende This :ref:`action ` resumes the activity of LVGL, including rendering. +- **lvgl_id** (*Optional*): The ID of the LVGL instance to resume. + .. code-block:: yaml on_...: then: - lvgl.resume: + ``lvgl.update`` *************** @@ -765,6 +794,7 @@ Conditions 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. +- **lvgl_id** (*Optional*): The ID of the LVGL instance to monitor. .. code-block:: yaml @@ -787,6 +817,8 @@ This :ref:`condition ` checks if the amount of time specified This :ref:`condition ` checks if LVGL is in the paused state or not. +- **lvgl_id** (*Optional*): The ID of the LVGL instance to monitor. + .. code-block:: yaml # In some trigger: @@ -800,18 +832,18 @@ This :ref:`condition ` checks if LVGL is in the paused state Triggers -------- -Widget level :ref:`interaction triggers ` can be configured universally, or depending on the widtget functionality. +Widget level :ref:`interaction triggers ` are available, plus a few for the LVGL component itself: .. _lvgl-on-idle-trigger: -``lvgl.on_idle`` -**************** +``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. +LVGL has a notion of screen inactivity -- i.e. the time since the last user interaction with the screen is tracked. This can, for example, 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. +- **timeout** (**Required**, :ref:`templatable `, int): :ref:`Time ` that has elapsed since the last touch event, after which the trigger will be invoked. .. code-block:: yaml @@ -828,6 +860,21 @@ The ``on_idle`` :ref:`triggers ` are activated when inactivity time See :ref:`lvgl-cookbook-idlescreen` for an example which demonstrates how to implement screen saving with idle settings. +.. _lvgl_on_pause_trigger: + +``on_pause`` +************ + +This :ref:`trigger ` is triggered when LVGL is paused. This can be used to perform any desired actions when the screen is locked, such as turning off the display backlight. + +.. _lvgl_on_resume_trigger: + +``on_resume`` +************* + +This :ref:`trigger ` is triggered when LVGL is resumed. This can be used to perform any desired actions when the screen is unlocked, such as turning on the display backlight. + + See Also -------- diff --git a/components/lvgl/widgets.rst b/components/lvgl/widgets.rst index 9bcb2dff7c..f58725b83b 100644 --- a/components/lvgl/widgets.rst +++ b/components/lvgl/widgets.rst @@ -240,8 +240,8 @@ The animation image is similar to the normal ``image`` widget. The main differen - **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. + - **id** (**Required**): The ID or a list of IDs of animimg widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -306,8 +306,8 @@ If the ``adv_hittest`` :ref:`flag ` is enabled the arc can be **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. + - **id** (**Required**): The ID or a list of IDs of arc widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -381,8 +381,8 @@ Not only the end, but also the start value of the bar can be set, which changes **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. + - **id** (**Required**): The ID or a list of IDs of bar widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -511,12 +511,12 @@ The button matrix widget is a lightweight way to display multiple buttons in row **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. + - **id** (**Required**): The ID or a list of IDs of buttonmatrix widgets to be updated. + - Widget styles or properties from ``state``, ``items`` options above, to be updated. - ``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. + - **id** (**Required**): The ID or a list of IDs of matrix buttons to be updated. + - Widget styles or properties from ``control``, ``width`` and ``selected`` options above, to be updated. **Triggers:** @@ -624,9 +624,9 @@ The checkbox widget is made internally from a *tick box* and a label. When the c **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. + - **id** (**Required**): The ID or a list of IDs of checkbox widgets to be updated. - **text** (*Optional*, :ref:`text-property`): Text to display beside the checkbox. - - Widget styles or properties from the specific options above, which you want update. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -689,14 +689,15 @@ The Dropdown widget is built internally from a *button* part and a *list* part ( - **indicator** (*Optional*, dict): Styles for the dropdown symbol. - **options** (**Required**, list): The list of available options in the drop-down. - **selected_index** (*Optional*, int8): The index of the item you wish to be selected. +- **selected_text** (*Optional*, string): The text of the item you wish to be selected. - **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. Uses the typical background properties and :ref:`lvgl-widget-label` text properties for the text on it. ``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. + - **id** (**Required**): The ID or a list of IDs of dropdown widgets to update. + - Widget styles or properties from the specific options above to update. **Triggers:** @@ -772,8 +773,8 @@ Images are the basic widgets used to display images. **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. + - **id** (**Required**): The ID or a list of IDs of image widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -912,9 +913,9 @@ A label is the basic widget type that is used to display text. **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. + - **id** (**Required**): The ID or a list of IDs of label widgets to be updated. - **text** (*Optional*, :ref:`text-property`): Text to display on the button. - - Widget styles or properties from the specific options above, which you want update. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -967,8 +968,8 @@ The LED widgets are either circular or rectangular widgets whose brightness can **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. + - **id** (**Required**): The ID or a list of IDs of led widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1247,6 +1248,50 @@ You can use it as a parent container for other widgets. By default, it catches t widgets: - ... +.. _lvgl-widget-qrcode: + +``qrcode`` +---------- + +Use this widget to generate and display a QR-code containing a string at run time. + +**Configuration variables:** + +- **text** (**Required**, string): The string to be encoded in the QR. +- **size** (**Required**, int16): Set the desired size of the QR-code (in pixels). QR-codes with less data are smaller, but they scaled by an integer number to best fit to the given size. +- **light_color** (*Optional*, :ref:`color `): Color for the light areas of the QR. Defaults to white. +- **dark_color** (*Optional*, :ref:`color `): Color for the dark areas of the QR. Defaults to black. +- Style options from :ref:`lvgl-styling`. + +**Actions:** + +- ``lvgl.qrcode.update`` :ref:`action ` updates the widget's ``text`` property to display a new QR-code. + - **id** (**Required**): The ID of the qrcode widget to be updated. + - **text** (**Required**): The new text to be encoded and displayed. + +**Triggers:** + +- :ref:`interaction ` LVGL event triggers. + +**Example:** + +.. code-block:: yaml + + # Example widget: + - qrcode: + id: lv_qr + size: 100 + light_color: whitesmoke + dark_color: steelblue + text: esphome.io + + # Example action: + on_...: + then: + - lvgl.qrcode.update: + id: lv_qr + text: home-assistant.io + .. _lvgl-widget-roller: ``roller`` @@ -1263,6 +1308,7 @@ Roller allows you to simply select one option from a list by scrolling. - **mode** (*Optional*, enum): 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_text** (*Optional*, string): The text 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. @@ -1270,12 +1316,13 @@ Roller allows you to simply select one option from a list by scrolling. **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. +- **id** (**Required**): The ID or a list of IDs of roller widgets to be updated. +- **animated** (*Optional*, boolean): Animate the indicator when the bar changes value. Defaults to ``true``. +- All the other roller options as listed above. **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``. +- ``on_value`` :ref:`trigger ` is activated when you select an item from the list. The new selected index is returned in the variable ``x``, and the text of the selected item is returned in the variable ``text``. - :ref:`interaction ` LVGL event triggers which also return the selected index in ``x``. **Example:** @@ -1305,8 +1352,8 @@ Roller allows you to simply select one option from a list by scrolling. ... on_value: - logger.log: - format: "Selected index is: %d" - args: [ x ] + format: "Selected index is: %d, text is: %s" + args: [x, text.c_str()] The ``roller`` can be also integrated as :doc:`Select ` component. @@ -1336,8 +1383,8 @@ Normally, the slider can be adjusted either by dragging the knob, or by clicking **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. + - **id** (**Required**): The ID or a list of IDs of slider widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1411,8 +1458,8 @@ The spinbox contains a numeric value (as text) which can be increased or decreas **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. + - **id** (**Required**): The ID or a list of IDs of spinbox widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. - ``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. @@ -1485,8 +1532,8 @@ The Spinner widget is a spinning arc over a ring. **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. + - **id** (**Required**): The ID or a list of IDs of spinner widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1655,7 +1702,7 @@ The textarea is an extended label widget which displays a cursor and allows the **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. + - **id** (**Required**): The ID or a list of IDs of textarea widgets to be updated. - **text** (*Optional*, :ref:`text-property`): The text to replace the textarea content. **Triggers:** @@ -1706,7 +1753,7 @@ The ``textarea`` can be also integrated as :doc:`Text ` o 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. +If the tileview is screen sized, the user interface resembles what you may have seen on smartwatches. The tileview has parts ``main`` and ``scrollbar``. **Configuration variables:** @@ -1785,7 +1832,7 @@ Several universal actions are also available for all widgets, these are outlined 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. +- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL to be updated. - The widget's common :ref:`style property `, state (templatable) or :ref:`flag `. .. code-block:: yaml diff --git a/components/media_player/index.rst b/components/media_player/index.rst index d88bbc0f58..0deb613b95 100644 --- a/components/media_player/index.rst +++ b/components/media_player/index.rst @@ -254,6 +254,36 @@ This condition checks if the media player is playing media. condition: media_player.is_playing: +.. _media_player-is_paused_condition: + +``media_player.is_paused`` Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This condition checks if the media player is paused. + +.. code-block:: yaml + + # In some trigger: + on_...: + if: + condition: + media_player.is_paused: + +.. _media_player-is_announcing_condition: + +``media_player.is_announcing`` Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This condition checks if the media player is playing an announcement. + +.. code-block:: yaml + + # In some trigger: + on_...: + if: + condition: + media_player.is_announcing: + Play media in order ------------------- diff --git a/components/modbus_controller.rst b/components/modbus_controller.rst index 8e2ea4e688..adf67a2cbf 100644 --- a/components/modbus_controller.rst +++ b/components/modbus_controller.rst @@ -64,6 +64,8 @@ Configuration variables: - **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked. Defaults to 60 seconds. +.. _modbus_controller-offline_skip_updates: + - **offline_skip_updates** (*Optional*, integer): When a slave doesn't respond to a command, it is marked as offline, you can specify how many updates will be skipped while it is offline. If using a bus with multiple slaves, this avoids waiting for timeouts allowing to read other slaves in the same bus. When the slave @@ -96,6 +98,8 @@ Configuration variables: 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` +- **on_online** (*Optional*, :ref:`Automation `): An automation to perform when a modbus controller goes online. See :ref:`modbus_controller-on_online` +- **on_offline** (*Optional*, :ref:`Automation `): An automation to perform when a modbus controller goes offline. See :ref:`modbus_controller-on_offline` Example Client -------------- @@ -200,7 +204,7 @@ The following code allows a ModBUS client to read a sensor value from your ESPHo unit_of_measurement: V filters: - multiply: 0.1 - + Check out the various Modbus components available at the bottom of the document in the :ref:`modbusseealso` section. They can be directly defined *(inline)* under the ``modbus_controller`` hub or as standalone components. Technically there is no difference between the *inline* and the standard definitions approach. @@ -738,7 +742,7 @@ Automation ``on_command_sent`` ******************* -This automation will be triggered when a command has been sent by the `modbus_controller`. In :ref:`Lambdas ` +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 @@ -750,6 +754,40 @@ you can get the function code in ``function_code`` and the register address in ` then: - number.increment: modbus_commands +.. _modbus_controller-on_online: + +``on_online`` +******************* + +This automation will be triggered when a `modbus_controller` goes ``online``, after been ``offline``. 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_online: + then: + - logger.log: "Controller back online!" + +.. _modbus_controller-on_offline: + +``on_offline`` +******************* + +This automation will be triggered when a `modbus_controller` goes ``offline`` (See :ref:`offline_skip_updates `). 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_offline: + then: + - logger.log: "Controller goes offline!" + See Also -------- diff --git a/components/mqtt.rst b/components/mqtt.rst index bf43085bd4..f802645101 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -34,6 +34,7 @@ Configuration variables: ------------------------ - **broker** (**Required**, string): The host of your MQTT broker. +- **enable_on_boot** (*Optional*, boolean): If enabled, MQTT will be enabled on boot. Defaults to ``true``. - **port** (*Optional*, int): The port to connect to. Defaults to 1883. - **username** (*Optional*, string): The username to use for authentication. Empty (the default) means no authentication. @@ -458,6 +459,8 @@ Configuration variables: be retained. Defaults to ``true``. - **discovery** (*Optional*, boolean): Manually enable/disable discovery for a component. Defaults to the global default. +- **subscribe_qos** (*Optional*, int): The [Quality of Service](https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/) + level advertised in discovery for subscribing (only if discovery is enabled). Defaults to 0. - **availability** (*Optional*): Manually set what should be sent to Home Assistant for showing entity availability. Default derived from :ref:`global birth/last will message `. @@ -731,6 +734,57 @@ Configuration options: root["something"] = id(my_sensor).state; }); +``mqtt.disable`` Action +----------------------- + +This action turns off the MQTT component on demand. + +.. code-block:: yaml + + on_...: + then: + - mqtt.disable: + +.. note:: + + The configuration option ``enable_on_boot`` can be set to ``false`` if you do not want MQTT to be enabled on boot. + + +``mqtt.enable`` Action +---------------------- + +This action turns on the MQTT component on demand. + +.. code-block:: yaml + + on_...: + then: + - mqtt.enable: + +.. note:: + + The configuration option ``enable_on_boot`` can be set to ``false`` if you do not want MQTT to be enabled on boot. + ``mqtt.enable`` can be useful for custom setups. For example, if the broker name is negotiated dynamically and saved in a global variable. + +.. code-block:: yaml + + mqtt: + id: mqtt_id + broker: "" + enable_on_boot: False + + globals: + - id: broker_address + type: std::string + restore_value: yes + max_restore_data_length: 24 + initial_value: '"192.168.1.2"' + + on_...: + then: + - lambda: !lambda id(mqtt_id).set_broker_address(id(broker_address)); + - mqtt.enable: + .. _mqtt-connected_condition: ``mqtt.connected`` Condition diff --git a/components/opentherm.rst b/components/opentherm.rst new file mode 100644 index 0000000000..19ac27f816 --- /dev/null +++ b/components/opentherm.rst @@ -0,0 +1,437 @@ +OpenTherm +========= + +.. seo:: + :description: Instructions for setting up OpenTherm bridge in ESPHome. + :image: ../components/images/opentherm-shield.png + :keywords: OpenTherm + +OpenTherm (OT) is a standard communications protocol used in central heating systems for the communication between +central heating appliances and a thermostatic controller. As a standard, OpenTherm is independent of any single +manufacturer. A controller from manufacturer A can in principle be used to control a boiler from manufacturer B. + +Since OpenTherm doesn't operate in a standard voltage range, special hardware is required. You can choose from several +ready-made adapters or roll your own: + +- `DIYLESS Master OpenTherm Shield `__ +- `Ihor Melnyk's OpenTherm Adapter `__ +- `Jiří Praus' OpenTherm Gateway Arduino Shield `__ + +.. figure:: images/opentherm-shield.png + :align: center + :width: 50.0% + + DIYLESS Master OpenTherm Shield. + +.. note:: + + This component acts only as an OpenTherm master (for example, a thermostat or controller) and not as a slave or + gateway. Your existing thermostat is not usable while you use ESPHome with this component to control your boiler. + +Quick glossary +-------------- + +- CH: Central Heating +- DHW: Domestic Hot Water + +Hub +--- + +First, you need to define the OpenTherm hub in your configuration. Note that most OpenTherm adapters label ``in`` and +``out`` pins relative to themselves; this component labels its ``in`` and ``out`` pins relative to the microcontroller +ESPHome runs on. As such, your bridge's ``in`` pin becomes the hub's ``out`` pin and vice-versa. + +.. code-block:: yaml + + opentherm: + in_pin: GPIOXX + out_pin: GPIOXX + +Configuration variables: +************************ + +- **in_pin** (**Required**, number): The pin of the OpenTherm hardware bridge which is usually labeled ``out`` on the + board. +- **out_pin** (**Required**, number): The pin of the OpenTherm hardware bridge which is usually labeled ``in`` on the + board. +- **sync_mode** (**Optional**, boolean, default **false**): Synchronous communication mode prevents other components + from disabling interrupts while we are talking to the boiler. Enable if you experience a lot of random intermittent + invalid response errors (very likely to happen while using Dallas temperature sensors). +- **opentherm_version** (**Optional**, float): OpenTherm version that is required for some boilers to work (message + id 124). You don't need to specify this if everything works. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have + multiple busses. + +Note abut sync mode +******************* + +The use of some components (like Dallas temperature sensors) may result in lost frames and protocol warnings from +OpenTherm. Since OpenTherm is resilient by design and transmits its messages in a constant loop, these dropped frames +don't usually cause any problems. Still, if you want to decrease the number of protocol warnings in your logs, you can +enable ``sync_mode`` which will block ESPHome's main application loop until a single conversation with the boiler is +complete. This can greatly reduce the number of dropped frames, but usually won't eliminate them entirely. With +``sync_mode`` enabled, in some cases, ESPHome's main application loop may be blocked for longer than is recommended, +resulting in warnings in the logs. If this bothers you, you can adjust ESPHome's log level by adding the following to +your configuration: + +.. code-block:: yaml + + logger: + logs: + component: ERROR + +Usage as a thermostat +--------------------- + +The most important function for a thermostat is to set the boiler temperature setpoint. This component has three ways +to provide this input: using a Home Assistant sensor from which the setpoint can be read, using a +:doc:`/components/number/index`, or defining an output to which other components can write. For most users, the last +option is the most useful one, as it can be combined with the :doc:`/components/climate/pid` component to create a +thermostat that works as you would expect a thermostat to work. See :ref:`thermostat-pid-basic` for an example. + +Numerical values +**************** + +There are three ways to set a numerical value: + +- As an input sensor, defined in the hub configuration: + + .. code-block:: yaml + + opentherm: + t_set: setpoint_sensor + + sensor: + - platform: homeassistant + id: setpoint_sensor + entity_id: sensor.boiler_setpoint + + This can be useful if you have an external thermostat-like device that provides the setpoint as a sensor. + +- As a number: + + .. code-block:: yaml + + number: + - platform: opentherm + t_set: + name: Boiler Setpoint + + This is useful if you want full control over your boiler and want to manually set all values. + +- As an output: + + .. code-block:: yaml + + output: + - platform: opentherm + t_set: + id: setpoint + + This is especially useful in combination with the PID Climate component: + + .. code-block:: yaml + + climate: + - platform: pid + heat_output: setpoint + # ... + +For the output and number variants, there are four more properties you can configure beyond those included in the +output and number components by default: + +- ``min_value`` (float): The minimum value. For a number this is the minimum value you are allowed to input. For an + output this is the number that will be sent to the boiler when the output is at 0%. +- ``max_value`` (float): The maximum value. For a number this is the maximum value you are allowed to input. For an + output this is the number that will be sent to the boiler when the output is at 100%. +- ``auto_max_value`` (boolean): Automatically configure the maximum value to a value reported by the boiler. Not + available for all inputs. +- ``auto_min_value`` (boolean): Automatically configure the minimum value to a value reported by the boiler. Not + available for all inputs. + +The following numerical values are available: + +- ``t_set``: Control setpoint: temperature setpoint for the boiler's supply water (°C) + + * Default ``min_value``: 0 + * Default ``max_value``: 100 + * Supports ``auto_max_value`` +- ``t_set_ch2``: Control setpoint 2: temperature setpoint for the boiler's supply water on the second heating circuit + (°C) + + * Default ``min_value``: 0 + * Default ``max_value``: 100 + * Supports ``auto_max_value`` +- ``cooling_control``: Cooling control signal (%) + + * Default ``min_value``: 0 + * Default ``max_value``: 100 +- ``t_dhw_set``: Domestic hot water temperature setpoint (°C) + + * Default ``min_value``: 0 + * Default ``max_value``: 127 + * Supports ``auto_min_value`` + * Supports ``auto_max_value`` +- ``max_t_set``: Maximum allowable CH water setpoint (°C) + + * Default ``min_value``: 0 + * Default ``max_value``: 127 + * Supports ``auto_min_value`` + * Supports ``auto_max_value`` +- ``t_room_set``: Current room temperature setpoint (informational) (°C) + + * Default ``min_value``: -40 + * Default ``max_value``: 127 +- ``t_room_set_ch2``: Current room temperature setpoint on CH2 (informational) (°C) + + * Default ``min_value``: -40 + * Default ``max_value``: 127 +- ``t_room``: Current sensed room temperature (informational) (°C) + + * Default ``min_value``: -40 + * Default ``max_value``: 127 +- ``max_rel_mod_level``: Maximum relative modulation level (%) + + * Default ``min_value``: 0 + * Default ``max_value``: 100 + * Supports ``auto_min_value`` +- ``otc_hc_ratio``: OTC heat curve ratio (°C) + + * Default ``min_value``: 0 + * Default ``max_value``: 127 + * Supports ``auto_min_value`` + * Supports ``auto_max_value`` + +Switch +****** + + +Switches are available to allow manual toggling of any of the following seven status codes: + +- ``ch_enable``: Central Heating enabled +- ``dhw_enable``: Domestic Hot Water enabled +- ``cooling_enable``: Cooling enabled +- ``otc_active``: Outside temperature compensation active +- ``ch2_active``: Central Heating 2 active +- ``summer_mode_active``: Summer mode active +- ``dhw_block``: Block DHW + +If you do not wish to have switches, the same values can be permanently set in the hub configuration, like so: + +.. code-block:: yaml + + opentherm: + ch_enable: true + dhw_enable: true + +This is useful when you'd never want to toggle it after the initial configuration. + +The default values for these configuration variables are listed below. + +To enable central heating and cooling, the flag is only sent to the boiler if the following conditions are met: + +- the flag is set to true in the hub configuration, +- the switch is on (if configured), +- the setpoint or cooling control value is not 0 (if configured) + +For domestic hot water and outside temperature compensation, only the first two conditions are necessary. + +The last point ensures that central heating is not enabled if no heating is requested as indicated by a setpoint of 0. +If you use a number as the setpoint input and use a minimum value higher than 0, you **must** use the ``ch_enable`` +switch to turn off your central heating. In such a case, the flag will be set to true in the hub configuration and the +setpoint is always larger than 0, so including a switch is the only way you can turn off central heating. (This also +holds for cooling and CH2.) + +Binary sensor +************* + +The component can report boiler status on several binary sensors. The *Status* sensors are updated in each message +cycle, while the others are only set during initialization, as they are unlikely to change without restarting the +boiler. + +- ``fault_indication``: Status: Fault indication +- ``ch_active``: Status: Central Heating active +- ``dhw_active``: Status: Domestic Hot Water active +- ``flame_on``: Status: Flame on +- ``cooling_active``: Status: Cooling active +- ``ch2_active``: Status: Central Heating 2 active +- ``diagnostic_indication``: Status: Diagnostic event +- ``electricity_production``: Status: Electricity production +- ``dhw_present``: Configuration: DHW present +- ``control_type_on_off``: Configuration: Control type is on/off +- ``cooling_supported``: Configuration: Cooling supported +- ``dhw_storage_tank``: Configuration: DHW storage tank +- ``controller_pump_control_allowed``: Configuration: Controller pump control allowed +- ``ch2_present``: Configuration: CH2 present +- ``water_filling``: Configuration: Remote water filling +- ``heat_mode``: Configuration: Heating or cooling +- ``dhw_setpoint_transfer_enabled``: Remote boiler parameters: DHW setpoint transfer enabled +- ``max_ch_setpoint_transfer_enabled``: Remote boiler parameters: CH maximum setpoint transfer enabled +- ``dhw_setpoint_rw``: Remote boiler parameters: DHW setpoint read/write +- ``max_ch_setpoint_rw``: Remote boiler parameters: CH maximum setpoint read/write +- ``service_request``: Service required +- ``lockout_reset``: Lockout Reset +- ``low_water_pressure``: Low water pressure fault +- ``flame_fault``: Flame fault +- ``air_pressure_fault``: Air pressure fault +- ``water_over_temp``: Water overtemperature + +Sensor +****** + +The boiler can also report several numerical values, which are available through sensors. Your boiler may not support +all of these values, in which case there won't be any value published to that sensor. The following sensors are +available: + +- ``rel_mod_level``: Relative modulation level (%) +- ``ch_pressure``: Water pressure in CH circuit (bar) +- ``dhw_flow_rate``: Water flow rate in DHW circuit (l/min) +- ``t_boiler``: Boiler water temperature (°C) +- ``t_dhw``: DHW temperature (°C) +- ``t_outside``: Outside temperature (°C) +- ``t_ret``: Return water temperature (°C) +- ``t_storage``: Solar storage temperature (°C) +- ``t_collector``: Solar collector temperature (°C) +- ``t_flow_ch2``: Flow water temperature CH2 circuit (°C) +- ``t_dhw2``: Domestic hot water temperature 2 (°C) +- ``t_exhaust``: Boiler exhaust temperature (°C) +- ``fan_speed``: Boiler fan speed (RPM) +- ``fan_speed_setpoint``: Boiler fan speed setpoint (RPM) +- ``flame_current``: Boiler flame current (µA) +- ``burner_starts``: Number of starts burner +- ``ch_pump_starts``: Number of starts CH pump +- ``dhw_pump_valve_starts``: Number of starts DHW pump/valve +- ``dhw_burner_starts``: Number of starts burner during DHW mode +- ``burner_operation_hours``: Number of hours that burner is in operation +- ``ch_pump_operation_hours``: Number of hours that CH pump has been running +- ``dhw_pump_valve_operation_hours``: Number of hours that DHW pump has been running or DHW valve has been opened +- ``dhw_burner_operation_hours``: Number of hours that burner is in operation during DHW mode +- ``t_dhw_set_ub``: Upper bound for adjustment of DHW setpoint (°C) +- ``t_dhw_set_lb``: Lower bound for adjustment of DHW setpoint (°C) +- ``max_t_set_ub``: Upper bound for adjustment of max CH setpoint (°C) +- ``max_t_set_lb``: Lower bound for adjustment of max CH setpoint (°C) +- ``t_dhw_set``: Domestic hot water temperature setpoint (°C) +- ``max_t_set``: Maximum allowable CH water setpoint (°C) +- ``opentherm_version_device``: Version of OpenTherm implemented by device +- ``device_type``: Device product type +- ``device_version``: Device product version +- ``device_id``: Device ID code +- ``otc_hc_ratio_ub``: OTC heat curve ratio upper bound +- ``otc_hc_ratio_lb``: OTC heat curve ratio lower bound + + +Examples +-------- + +Minimal example with numeric input +********************************** + +.. code-block:: yaml + + # An extremely minimal configuration which only enables you to set the boiler's + # water temperature setpoint as a number. + + opentherm: + in_pin: GPIOXX + out_pin: GPIOXX + ch_enable: true + + number: + - platform: opentherm + t_set: + name: "Boiler Control setpoint" + +.. _thermostat-pid-basic: + +Basic PID thermostat +******************** + +.. code-block:: yaml + + # A basic thremostat for a boiler with a single central heating circuit and + # domestic hot water. It reports the flame, CH and DHW status, similar to what + # you would expect to see on a thermostat and also reports the internal boiler + # temperatures and the current modulation level. The temperature is regulated + # through a PID Climate controller and the current room temperature is retrieved + # from a sensor in Home Asisstant. + + # This configuration should meet most needs and is the recommended starting + # point if you just want a thermostat with an external temperature sensor. + + opentherm: + in_pin: GPIOXX + out_pin: GPIOXX + dhw_enable: true # Note that when we specify an input in hub config with a static value, it can't be + # changed without uploading new firmware. If you want to be able to turn things on or off, + # use a switch (see the ch_enable switch below). + # Also note that when we define an input as a switch (or use other platform), we don't need + # to set it at hub level. + + output: + - platform: opentherm + t_set: + id: t_set + min_value: 20 + max_value: 65 + zero_means_zero: true + + sensor: + - platform: opentherm + rel_mod_level: + name: "Boiler Relative modulation level" + t_boiler: + name: "Boiler water temperature" + t_ret: + name: "Boiler Return water temperature" + + - platform: homeassistant + id: ch_room_temperature + entity_id: sensor.temperature + filters: + # Push room temperature every second to update PID parameters + - heartbeat: 1s + + binary_sensor: + - platform: opentherm + ch_active: + name: "Boiler Central Heating active" + dhw_active: + name: "Boiler Domestic Hot Water active" + flame_on: + name: "Boiler Flame on" + fault_indication: + name: "Boiler Fault indication" + entity_category: diagnostic + diagnostic_indication: + name: "Boiler Diagnostic event" + entity_category: diagnostic + + switch: + - platform: opentherm + ch_enable: + name: "Boiler Central Heating enabled" + restore_mode: RESTORE_DEFAULT_ON + + climate: + - platform: pid + name: "Central heating" + heat_output: t_set + default_target_temperature: 20 + sensor: ch_room_temperature + control_parameters: + kp: 0.4 + ki: 0.004 + +See Also +-------- + +- :apiref:`API Reference: OpenthermHub ` +- :apiref:`API Reference: OpenthermInput ` +- :apiref:`API Reference: OpenthermNumber ` +- :apiref:`API Reference: OpenthermOutput ` +- :apiref:`API Reference: OpenthermSwitch ` +- `OpenTherm thermostat with ESPHome and Home Assistant `__ — + real-world use case for this component. +- `Development repository `__ — new features will be tested here + before proposing them to ESPHome core. +- :ghedit:`Edit` diff --git a/components/sensor/images/max17043.jpg b/components/sensor/images/max17043.jpg new file mode 100644 index 0000000000..3567f5d020 Binary files /dev/null and b/components/sensor/images/max17043.jpg differ diff --git a/components/sensor/images/tc74-full.jpg b/components/sensor/images/tc74-full.jpg new file mode 100644 index 0000000000..f7d63ae768 Binary files /dev/null and b/components/sensor/images/tc74-full.jpg differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 255b925ef4..74802f679e 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -123,12 +123,14 @@ Filters are applied in the order they are defined in your configuration. # Example filters: filters: - offset: 2.0 - - multiply: 1.2 + - multiply: !lambda return 1.2; - calibrate_linear: - 0.0 -> 0.0 - 40.0 -> 45.0 - 100.0 -> 102.5 - - filter_out: 42.0 + - filter_out: + - 42.0 + - 43.0 - median: window_size: 5 send_every: 5 @@ -158,7 +160,7 @@ Filters are applied in the order they are defined in your configuration. ``offset`` ********** -Adds a constant value to each sensor value. +Adds a value to each sensor value. The value may be a constant or a lambda returning a float. .. code-block:: yaml @@ -168,11 +170,12 @@ Adds a constant value to each sensor value. filters: - offset: 2.0 - multiply: 1.2 + - offset: !lambda return id(some_sensor).state; ``multiply`` ************ -Multiplies each value by a constant value. +Multiplies each value by a templatable value. .. _sensor-filter-calibrate_linear: @@ -256,6 +259,20 @@ degree with a least squares solver. filters: - filter_out: 85.0 +A list of values may be supplied, and values are templatable: + + +.. code-block:: yaml + + # Example configuration entry + - platform: wifi_signal + # ... + filters: + - filter_out: + - 85.0 + - !lambda return id(some_sensor).state; + + ``clamp`` ********* @@ -538,7 +555,7 @@ of the input values. ************ After the first value has been sent, if no subsequent value is published within the -``specified time period``, send a value which defaults to ``NaN``. +``specified time period``, send a templatable value which defaults to ``NaN``. Especially useful when data is derived from some other communication channel, e.g. a serial port, which can potentially be interrupted. @@ -549,7 +566,7 @@ channel, e.g. a serial port, which can potentially be interrupted. - timeout: 10s # sent value will be NaN - timeout: timeout: 10s - value: 0 + value: !lambda return 0; ``debounce`` ************ diff --git a/components/sensor/max17043.rst b/components/sensor/max17043.rst new file mode 100644 index 0000000000..3b8af7addb --- /dev/null +++ b/components/sensor/max17043.rst @@ -0,0 +1,106 @@ +Analog Devices MAX17043 battery fuel gauge +========================================== + +.. seo:: + :description: Instructions for setting up Analog Devices MAX17043 battery fuel gauge in ESPHome. + :image: max17043.jpg + +The MAX17043 platform allows you to use a MAX17043 to more accurately monitor the remaining capacity +of a LIPO battery (`datasheet `__, +`DFRobot`_) in ESPHome. It uses the :ref:`I²C Bus ` for communication (the address is fixed at 0x36). + +Once configured, it uses a sophisticated Li+ battery-modeling scheme, called ModelGauge™ to track the +battery's relative state-of-charge continuously over a widely varying charge/discharge profile. +Unlike traditional fuel gauges, the ModelGauge algorithm eliminates the need for battery relearn cycles +and an external current-sense resistor. + +In low power applications, it's very important to report battery levels accurately. By utilising ESPHome's ``deep_sleep`` +component together with a MAX17043, projects can run for extended periods and the user can be confident of the amount of battery remaining. +This overcomes the reality that measured battery voltage does not correlate well at all with remaining battery charge. + +.. note:: + + See hardware design discussion below - it's important to leave the MAX17043 powered on during deep sleep. + +.. figure:: images/max17043.jpg + :align: center + :width: 60.0% + + DFRobot DFR0563 Gravity I2C 3.7V Li battery fuel gauge. + +.. _DFRobot: https://www.dfrobot.com/product-1734.html + +Configuration +************* + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: max17043 + id: max17043_id + i2c_id: i2c_max17043 + battery_voltage: + name: "Battery Voltage" + battery_level: + name: "Battery" + +Sensors +******* + +- **battery_voltage** (*Optional*, float): The voltage measured at the LIPO battery. + + - All other options from :ref:`Sensor `. +- **battery_level** (*Optional*, float): The percentage of battery remaining using the ModelGauge™ battery-modelling scheme. + + - All other options from :ref:`Sensor `. + +Hardware design considerations +****************************** + +It's important to realise that the relationship between battery voltage and remaining battery level +is poorly correlated as well as being non-linear. + +The MAX17043 works by continually monitoring charge and discharge to assess how much battery capacity remains. +When first powered on, it makes an assumption that the measured voltage has been in a relaxed state for +30 minutes. This best first guess does not have a lasting impact because it monitors relative state-of-charge +over time. + +Deep sleep cycles are most often designed so the device wakes up for short +periods to do its business and then sleeps for a much longer period. It's critical to allow the MAX17043 to maintain +state during the sleep phase. + +If power is removed from the MAX17043 then each time the ESP comes out of deep sleep the MAX17043 will +have to start again from a new best guess. +It will not be able to use past charge and discharge behaviour to work its magic - +significantly diminishing the point of using a MAX17043. + +Current consumption during device sleep mode is extremely low (maximum of 3µA compared to up to 75µA maximum when active). +The driver enables the user to put the device to sleep just before deep sleep commences using the `sleep_mode` action. +When the ESP comes out of deep sleep the driver clears the MAX17043 sleep bit. + +For example: + +.. code-block:: yaml + + on_...: + then: + - max17043.sleep_mode: max17043_id + - deep_sleep.enter: + id: deep_sleep_1 + sleep_duration: 20min + +.. note:: + + Once you have called the ``sleep_mode()`` action, the MAX17043 will stop recalculating the voltage and battery level. + Hence, if you leave the ESP running it will continue to publish the sensor values with the *last* measurements. + The only way to come of sleep mode is to restart the device (either as intended via deep sleep wake; or less ideally with a power cycle). + + So, only call ``sleep_mode()`` when you intend to send the ESP into deep sleep. + +See Also +-------- + +- :ref:`i2c` +- :doc:`/components/deep_sleep` +- :ghedit:`Edit` diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index 6647cb0c2c..7071d140bc 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -9,8 +9,9 @@ Mopeka Pro Check BLE Sensor The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka Pro Check LP, Mopeka Pro Plus, Mopeka Pro Universal or Lippert Propane Tank Sensors, Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`. This component -will track the tank level, distance, temperature, and battery percentage of a -device every time the sensor sends out a BLE broadcast. +will track the tank level, distance, temperature, battery percentage, and sensor reading quality of a +device every time the sensor sends out a BLE broadcast. There are additional configuration options +to control handling of poor quality readings and reporting reading quality issues. .. warning:: @@ -56,6 +57,12 @@ Mopeka Pro Check LP over BLE: name: "Propane test distance" battery_level: name: "Propane test battery level" + signal_quality: + name: "Propane test read quality" + ignored_reads: + name: "Propane test ignored reads" + # Report sensor distance/level data for all equal or greater than + minimum_signal_quality: "LOW" # Custom example - user defined empty / full points - platform: mopeka_pro_check @@ -87,11 +94,13 @@ Configuration variables: - **custom_distance_empty** (*Optional*): distance sensor will read when it should be considered empty (0%). This is only used when tank_type = CUSTOM -- **level** (*Optional*): The percentage of full for the tank sensor +- **level** (*Optional*): The percentage of full for the tank sensor. If + read is ignored due to quality this sensor will not be updated. - All options from :ref:`Sensor `. - **distance** (*Optional*): The raw distance/depth of the liquid for the sensor in mm. + If read is ignored due to quality this sensor will not be updated. - All options from :ref:`Sensor `. @@ -105,6 +114,31 @@ Configuration variables: - All options from :ref:`Sensor `. +- **signal_quality** (*Optional*): The information for the read quality + sensor. + + - All options from :ref:`Sensor `. + +- **ignored_reads** (*Optional*): A diagnostic sensor indicating the number + of consecutive ignored reads. This resets to zero each time the read is + equal or greater than the configured ignored quality. Only the distance + and level sensors are not reported. + + - All options from :ref:`Sensor `. + +- **minimum_signal_quality** (*Optional*): Each report from the sensor + indicates the quality or confidence in the distance the sensor calculated. Physical + sensor placement, tank material or quality, or other factors can influence the + sensors ability to read with confidence. As quality gets lower, the accuracy of the + distance reading may not align with expectations. This value allows configuration of + the minimum quality level that the distance should be evaluated/reported. + Acceptable Values: + + - "HIGH": High Quality + - "MEDIUM": Medium Quality (default value) + - "LOW": Low Quality + - "ZERO": Zero Quality + Tank Types ---------- @@ -132,7 +166,7 @@ and the ``mopeka_ble`` component like so: mopeka_ble: After uploading, the ESP32 will immediately try to scan for BLE devices. Press and hold the sync button for it to be identified. -Or alternativly set the configuration flag ``show_sensors_without_sync: true`` to see all devices. +Or alternatively set the configuration flag ``show_sensors_without_sync: true`` to see all devices. For all sensors found the ``mopeka_ble`` component will print a message like this one: .. code:: diff --git a/components/sensor/tc74.rst b/components/sensor/tc74.rst new file mode 100644 index 0000000000..20a4069674 --- /dev/null +++ b/components/sensor/tc74.rst @@ -0,0 +1,50 @@ +TC74 Temperature Sensor +======================= + +.. seo:: + :description: Instructions for setting up the TC74 temperature sensors. + :image: tc74.jpg + :keywords: TC74 + +The TC74 sensor platform allows you to use your TC74 (`datasheet +`__, `Adafruit +`__) temperature sensors with ESPHome. +The :ref:`I²C Bus ` is required to be set up in your configuration for this +sensor to work. + +.. figure:: images/tc74-full.jpg + :align: center + :width: 50.0% + + TC74 Temperature Sensor. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: tc74 + name: "Living Room Temperature" + +Configuration variables: +------------------------ + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check + the sensor. Defaults to ``60s``. +- **address** (*Optional*, int): The I²C address of the sensor. Defaults to + ``0x48``, the address of the TC74A0. For suffixes other than ``A0`` add the + final digit to ``0x48`` to calculate the address. For example, the TC74A5 has + I²C address ``0x4D``. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`dht` +- :doc:`dht12` +- :doc:`hdc1080` +- :doc:`sht3xd` +- :doc:`htu21d` +- :doc:`tmp102` +- :apiref:`tc74/tc74.h` +- :ghedit:`Edit` diff --git a/components/speaker/i2s_audio.rst b/components/speaker/i2s_audio.rst index 1c33f4a489..20c4f83e76 100644 --- a/components/speaker/i2s_audio.rst +++ b/components/speaker/i2s_audio.rst @@ -54,7 +54,9 @@ Configuration variables: - ``pcm`` - ``pcm_short`` - ``pcm_long`` -- **timeout** (*Optional*, :ref:`config-time`): How long to wait after finishing playback before releasing the bus. Defaults to ``100ms``. +- **buffer_duration** (*Optional*, :ref:`config-time`): The duration of the internal ring buffer. Larger values can reduce stuttering but uses more memory. Defaults to ``500ms``. +- **timeout** (*Optional*, :ref:`config-time`): How long to wait after finishing playback before releasing the bus. Set to ``never`` to never stop the speaker due to a timeout. Defaults to ``500ms``. +- All other options from :ref:`Speaker Component `. External DAC ************ diff --git a/components/speaker/index.rst b/components/speaker/index.rst index aa9279ad9a..36ab814a78 100644 --- a/components/speaker/index.rst +++ b/components/speaker/index.rst @@ -13,12 +13,20 @@ speaker platforms. Base Speaker Configuration -------------------------- -No configuration variables +.. code-block:: yaml + + speaker: + - platform: ... + + +Configuration variables: + +- **audio_dac** (*Optional*, :ref:`config-id`): The :doc:`audio DAC ` to use for volume control. .. _speaker-actions: Speaker Actions ------------------- +--------------- All ``speaker`` actions can be used without specifying an ``id`` if you have only one ``speaker`` in your configuration YAML. @@ -26,7 +34,7 @@ your configuration YAML. .. _speaker-play: ``speaker.play`` Action -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^ This action will start playing raw audio data from the speaker. @@ -52,7 +60,7 @@ Configuration variables: .. _speaker-stop: ``speaker.stop`` Action -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^ This action will stop playing audio data from the speaker and discard the unplayed data. @@ -65,12 +73,59 @@ Configuration variables: ``speaker.finish`` Action ^^^^^^^^^^^^^^^^^^^^^^^^^ -This action will stop playing audio data from the speaker after all data **is** played. +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-mute_on: + +``speaker.mute_on`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will mute the speaker. + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. + +.. _speaker-mute_off: + +``speaker.mute_off`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will unmute the speaker. Configuration variables: - **id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. +.. _speaker-volume_set: + +``speaker.volume_set`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will set the volume of the speaker. + +.. code-block:: + + on_...: + # Simple + - speaker.volume_set: 50% + + # Full + - speaker.volume_set: + id: speaker_id + volume: 50% + + # Simple with lambda + - speaker.volume_set: !lambda "return 0.5;" + +Configuration variables: + +**volume** (**Required**, percentage): The volume to set the speaker to. + .. _speaker-conditions: Speaker Conditions @@ -82,7 +137,7 @@ your configuration YAML. .. _speaker-is_playing: ``speaker.is_playing`` Condition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This condition will check if the speaker is currently playing audio data. diff --git a/components/spi.rst b/components/spi.rst index bf2f2543c8..f3cd46bd3a 100644 --- a/components/spi.rst +++ b/components/spi.rst @@ -126,7 +126,7 @@ Reads and writes on the device can be performed with lambdas. For example: id: spidev cs_pin: GPIOXX data_rate: 2MHz - mode: 3 + spi_mode: 3 bit_order: lsb_first on...: @@ -143,7 +143,7 @@ Configuration variables: - **data_rate** (*Optional*): Set the data rate of the controller. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz``, ``5MHz``, ``4MHz``, ``2MHz``, ``1MHz`` (default), ``200kHz``, ``75kHz`` or ``1kHz``. A numeric value in Hz can alternatively be specified. -- **mode** (*Optional*): Set the controller mode - one of ``mode0``, ``mode1``, ``mode2``, ``mode3``. The default is ``mode3``. +- **spi_mode** (*Optional*): Set the controller mode - one of ``mode0``, ``mode1``, ``mode2``, ``mode3``. The default is ``mode3``. See table below for more information - **bit_order** (*Optional*): Set the bit order - choose one of ``msb_first`` (default) or ``lsb_first``. - **cs_pin** (*Optional*, :ref:`Pin Schema `): The CS pin. diff --git a/components/touchscreen/axs15231.rst b/components/touchscreen/axs15231.rst new file mode 100644 index 0000000000..923eb514cd --- /dev/null +++ b/components/touchscreen/axs15231.rst @@ -0,0 +1,37 @@ +AXS15231 Touch Screen Controller +================================ + +.. seo:: + :description: Instructions for setting up AXS15231 touch screen controller with ESPHome + :image: esp32_s3_box_3.png + :keywords: AXS15231 + +The ``axs15231`` touchscreen platform allows using the touch screen controllers based on the AXS15231 chip with ESPHome. +An :ref:`I²C ` bus is required to be set up in your configuration for this touchscreen to work. + + +Base Touchscreen Configuration +------------------------------ + +.. code-block:: yaml + + # Example configuration entry + touchscreen: + platform: axs15231 + id: my_touchscreen + +Configuration variables: +************************ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **interrupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The reset pin. + +- All other options from :ref:`Touchscreen `. + + +See Also +-------- + +- :apiref:`axs15231/touchscreen/axs15231.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index bfbb2c48da..527308d864 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -7,16 +7,8 @@ Touchscreen Components The ``touchscreen`` component contains the base code for most touchscreen driver components available in ESPHome and is responsible for passing the touch events to -``binary_sensors`` with the ``touchscreen`` platform. +``binary_sensors`` with the ``touchscreen`` platform. It is also used by the LVGL component. -.. warning:: - - As of version **2023.12** the way how the touchscreen component has changed a bit. - The following variables are now obsolite: - * **rotation** is (temporary) removed in favor the *new* **transform:** - * **size_x_y** is moved inside the **transform:** and renamed to **size_xy** - * **report_interval** is removed in favor of using the **update_interval** - The display id is only just to calculate the touch position reletive to the displays *height* and *width* .. _config-touchscreen: @@ -33,9 +25,6 @@ Base Touchscreen Configuration mirror_x: false mirror_y: false swap_xy: false - calibration: - x_max: 240 - y_max: 320 on_touch: then: @@ -50,26 +39,26 @@ Base Touchscreen Configuration Configuration variables: ************************ - **display** (*Required*, :ref:`config-id`): The display to use this touchscreen with. -- **transform** (*Optional*): Transform the touchscreen presentation using hardware. All defaults are ``false``. +- **transform** (*Optional*): Transform the reported position to match the display. - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes. - **mirror_x** (*Optional*, boolean): If true, mirror the x axis. - **mirror_y** (*Optional*, boolean): If true, mirror the y axis. -- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the touchscreen. Defaults to ``never``. **NOTE:** Set this to ``50ms`` when you dont have set the **interupt_pin**. -- **touch_timeout** (*Optional*, :ref:`config-time`): The time to automatically check if touch was released. Defaults to ``never``. -- **calibration** (*Optional*): When the touchscreen is not given the right configuration settings. You can set them here. +- **update_interval** (*Optional*, :ref:`config-time`): The touchscreen polling interval - used only if an interrupt pin is not in use. Defaults to ``50ms``. +- **touch_timeout** (*Optional*, :ref:`config-time`): A timeout for touchscreens that do not report the end of touch. The default varies depending on the touchscreen. +- **calibration** (*Optional*): Some touchscreens require calibration on a per-device basis. - - **x_min** (*Optional*, int): The raw value corresponding to the left + - **x_min** (**Required**, int): The raw value corresponding to the left (or top if ``swap_xy`` is specified) edge of the touchscreen. See :ref:`touchscreen-calibration` - for the process to calibrate the touchscreen. Defaults to ``0``. - - **x_max** (*Optional*, int): The raw value corresponding to the right - (or bottom if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. - - **y_min** (*Optional*, int): The raw value corresponding to the top - (or left if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. - - **y_max** (*Optional*, int): The raw value corresponding to the bottom - (or right if ``swap_xy`` is specified) edge of the touchscreen. Defaults to ``0``. + for the process to calibrate the touchscreen. + - **x_max** (**Required**, int): The raw value corresponding to the right + (or bottom if ``swap_xy`` is specified) edge of the touchscreen. + - **y_min** (**Required**, int): The raw value corresponding to the top + (or left if ``swap_xy`` is specified) edge of the touchscreen. + - **y_max** (**Required**, int): The raw value corresponding to the bottom + (or right if ``swap_xy`` is specified) edge of the touchscreen. - **on_touch** (*Optional*, :ref:`Automation `): An automation to perform @@ -103,23 +92,18 @@ The integer members for the touch positions below are in relation to the display Calibration ----------- -For most of the touchscreen drivers the dimensions of the touchscreen are automatically set when the driver is setup. -In some cases like for the **XPT2046** this can be different per used display panel. -Then you can set the values using the **calibrate** values. +For most touchscreen drivers the dimensions of the touchscreen are automatically set from the display driver to match the screen size. +In some cases such as the :ref:`XPT2046 ` (a resistive touch screen) the reported values bear no relation to the actual screen size. +The ``calibration`` configuration can be used to manually calibrate the touchscreen. To match the point of the touch to the display coordinates the touch screen has to be calibrated. -The touchscreen component returns raw values in the 0 to 4095 range. Those raw values are available -as the ``x_raw`` and ``y_raw`` member variables and for example write them out as in the example -:ref:`touchscreen-on_touch`. The goal of the calibration is to identify the raw values corresponding +The touchscreen component returns raw values in the calibration range. Those raw values are available +as the ``x_raw`` and ``y_raw`` member variables. The goal of the calibration is to identify the raw values corresponding to the edges of the screen. The calibration assumes a display oriented in a way that you will be using it, i.e. your :ref:`display-engine` component has to have the [0,0] logical coordinate at the top left. -.. note:: - - Do not set any calibration values nor ``transform`` settings. - .. code-block:: yaml # Touchscreen @@ -139,11 +123,6 @@ The calibration assumes a display oriented in a way that you will be using it, i Get a stylus or a similar object, run the project and touch the corners of the screen at the edge pixels. Repeat several times and note minimum and maximum x and y raw values. -.. warning:: - - As long the calibrate settings are not correctly set, the ``x`` and ``y`` coordinates are not calculated. - - .. code-block:: none ... top left ... diff --git a/components/touchscreen/xpt2046.rst b/components/touchscreen/xpt2046.rst index c89801efb5..d35f2ffa25 100644 --- a/components/touchscreen/xpt2046.rst +++ b/components/touchscreen/xpt2046.rst @@ -8,7 +8,7 @@ XPT2046 Touch Screen Controller (Updated version) .. _xpt2046-component: -The ``xpt2046`` touchscreen platform allows using the touch screen controllers +The ``xpt2046`` touchscreen platform allows using the resistive touch screen controllers based on the XPT2046 chip (`datasheet `__, `AZ-Delivery`_) with ESPHome. Many cheap LCD displays contain this controller. @@ -32,9 +32,11 @@ The :ref:`SPI ` is required to be set up in your configuration for this sen interrupt_pin: GPIOXX update_interval: 50ms threshold: 400 + transform: + mirror_x: true calibration: - x_min: 3860 - x_max: 280 + x_min: 280 + x_max: 3860 y_min: 340 y_max: 3860 @@ -45,32 +47,28 @@ The configuration is made up of two parts: The touch screen component, and optio Base Configuration: - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor. - - **cs_pin** (*Optional*, :ref:`Pin Schema `): The chip select pin. Often marked ``T_CS`` on the board. - - **interrupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. Often marked ``T_IRQ`` on the board. If not specified the component will use polling via SPI. This key is renamed from **irq_pin** - - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. If ``interrupt_pin`` is specified the touch will be detected nearly instantaneously and this setting will be used only for the release detection. Defaults to ``50ms``. - - **threshold** (*Optional*, int): The value to detect the touch or release. Defaults to ``400``. +- **calibration** (**Required**): The XPT2046 is a resistive touch screen and it will require calibration on a per-device basis. + - **x_min** (**Required**, int): The raw value corresponding to the left + (or top if ``swap_xy`` is specified) edge of the touchscreen. See :ref:`touchscreen-calibration` + for the process to calibrate the touchscreen. + - **x_max** (**Required**, int): The raw value corresponding to the right + (or bottom if ``swap_xy`` is specified) edge of the touchscreen. + - **y_min** (**Required**, int): The raw value corresponding to the top + (or left if ``swap_xy`` is specified) edge of the touchscreen. + - **y_max** (**Required**, int): The raw value corresponding to the bottom + (or right if ``swap_xy`` is specified) edge of the touchscreen. -- **calibration_x_min** (*Deprecated*): This value is moved to the ``calibration`` values - -- **calibration_x_max** (*Deprecated*): This value is moved to the ``calibration`` values. - -- **calibration_y_min** (*Deprecated*): This value is moved to the ``calibration`` values. - -- **calibration_y_max** (*Deprecated*): This value is moved to the ``calibration`` values. - -- **swap_x_y** (*Deprecated*): This value is moved to the ``transform`` values as ``swap_xy`` see :ref:`config-touchscreen`. -- **report_interval** (*Deprecated*): This interval is removed in favor of the ``update_interval``. - All other options from :ref:`config-touchscreen`. diff --git a/conf.py b/conf.py index 35105458e2..7e2f23f105 100644 --- a/conf.py +++ b/conf.py @@ -71,9 +71,9 @@ # built documents. # # The short X.Y version. -version = "2024.10" +version = "2024.11" # The full version, including alpha/beta/rc tags. -release = "2024.10.3" +release = "2024.11.0" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/getting_started_hassio.rst b/guides/getting_started_hassio.rst index 2094259777..3e0efc59fd 100644 --- a/guides/getting_started_hassio.rst +++ b/guides/getting_started_hassio.rst @@ -2,27 +2,29 @@ Getting Started with ESPHome and Home Assistant =============================================== .. seo:: - :description: Getting Started guide for installing ESPHome Dashboard as a Home Assistant add-on and creating a basic configuration. + :description: Getting Started guide for installing ESPHome Device Compiler as a Home Assistant add-on and creating a basic configuration. :image: home-assistant.svg -In this guide we’ll go through how to install ESPHome on a device using the ESPHome Dashboard, installed as a Home Assistant add-on. +In this guide we’ll go through how to install ESPHome on a device using the ESPHome Device Compiler, installed as a Home Assistant add-on. -First, here's a very quick introduction to how ESPHome works. ESPHome is a tool that aims to simplify managing your supported devices. It reads a YAML configuration file, creates custom firmware, and can install it on your device. Any devices or sensors defined in the ESPHome configuration will automatically appear in Home Assistant's user interface. +First, here's a very quick introduction to how ESPHome works. ESPHome allows you to write configurations and turn your microcontrollers +into smart home devices. It reads a YAML configuration file, creates custom firmware, and can install it directly on your device. Any devices +or sensors defined in the ESPHome configuration will automatically appear in Home Assistant's user interface. -Installing ESPHome Dashboard ----------------------------- - -The ESPHome Dashboard can be installed as a Home Assistant add-on, which you can find in the add-on store in the Supervisor panel. Open it using the following button then click on INSTALL: +Installing ESPHome Device Compiler +---------------------------------- -If you do not have the official ESPHome add-on repository added you can add with this button: +To install the ESPHome Device Compiler in Home Assistant, click the following button to open the ESPHome add-on page and hit the INSTALL button: .. raw:: html - Open your Home Assistant instance and show the dashboard of the ESPHome add-on. + Open your Home Assistant instance and show the user interface of the ESPHome add-on. -After that, wait a bit until it is installed (this can take a while). Click "Start" and then click "Open Web UI". If you see "502: Bad Gateway" it is currently starting, and you can refresh the page after a couple of seconds. +If you run a Home Assistant installation that does not have access to add-ons, take a look at the other installation methods here. + +It can take a bit until the add-on is installed. Once done, click "Start" and then click "Open Web UI". .. figure:: images/hassio_addon.png :align: center @@ -44,11 +46,11 @@ The wizard will guide you through creating your first configuration and, dependi For guidance on making this first connection, see :doc:`physical_device_connection` -Dashboard Interface +ESPHome Interface ------------------- Assuming you created your first configuration file with the wizard, let's take a quick -tour of the ESPHome Dashboard interface. +tour of the ESPHome Device Compiler interface. .. figure:: images/dashboard_states.png :align: center diff --git a/guides/supporters.rst b/guides/supporters.rst index 745ee5761d..c74ca1564c 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -54,6 +54,7 @@ Contributors - `adezerega (@adezerega) `__ - `Eugen (@Adminius) `__ - `Andrea Donno (@adonno) `__ +- `Adrian Campos (@adriancampos) `__ - `Adrian Cuzman (@adriancuzman) `__ - `Adrian Fretwell (@AdrianFretwell) `__ - `Adrien Brault (@adrienbrault) `__ @@ -79,6 +80,7 @@ Contributors - `Alone (@al-one) `__ - `Albin Kauffmann (@albinou) `__ - `Andre Lengwenus (@alengwenus) `__ +- `AlessandroTischer (@AlessandroTischer) `__ - `Alex (@alex-richards) `__ - `Alex Dekker (@Alex1602) `__ - `Alexander Leisentritt (@Alex9779) `__ @@ -143,6 +145,7 @@ Contributors - `arantius (@arantius) `__ - `Ryan DeShone (@ardichoke) `__ - `Ariff Saad (@arffsaad) `__ +- `Ari Mandjelikian (@arim215) `__ - `ArkanStasarik (@ArkanStasarik) `__ - `Aleksandr Artemev (@artemyevav) `__ - `arturo182 (@arturo182) `__ @@ -218,6 +221,7 @@ Contributors - `Bert Hertogen (@berthertogen) `__ - `Ivan Bessarabov (@bessarabov) `__ - `besteru (@besteru) `__ +- `Fabio Bonelli (@bfabio) `__ - `Brandon (@bgulla) `__ - `Benedikt Hübschen (@bhuebschen) `__ - `Bierchermuesli (@Bierchermuesli) `__ @@ -340,6 +344,7 @@ Contributors - `Yanik G (@clonyara) `__ - `Chester (@clowrey) `__ - `Clyde Stubbs (@clydebarrow) `__ +- `C. Mangla (@cmangla) `__ - `Colin McCambridge (@cmccambridge) `__ - `Clifford Roche (@cmroche) `__ - `code-review-doctor (@code-review-doctor) `__ @@ -605,6 +610,7 @@ Contributors - `Everything Smart Home (@EverythingSmartHome) `__ - `Evgeni Golov (@evgeni) `__ - `evlo (@evlo) `__ +- `Bonne Eggleston (@exciton) `__ - `Expaso (@Expaso) `__ - `Malte Franken (@exxamalte) `__ - `f0rdprefect (@f0rdprefect) `__ @@ -618,6 +624,7 @@ Contributors - `Fabian Berthold (@fbrthld) `__ - `F.D.Castel (@fdcastel) `__ - `Sun Xiangyu (@feizi) `__ +- `Felipe Santos (@felipecrs) `__ - `felixlungu (@felixlungu) `__ - `Felix Storm (@felixstorm) `__ - `felixstorm-c4a8 (@felixstorm-c4a8) `__ @@ -690,6 +697,7 @@ Contributors - `Geoffrey Van Landeghem (@geoffrey-vl) `__ - `Gérald Guiony (@gerald-guiony) `__ - `Gerard (@gerard33) `__ +- `German (@ghoeffner) `__ - `Giampiero Baggiani (@giampiero7) `__ - `Gideon Kanikevich (@gid204) `__ - `Giel Janssens (@gieljnssns) `__ @@ -800,6 +808,7 @@ Contributors - `Jan Pobořil (@iBobik) `__ - `icarome (@icarome) `__ - `icefest (@icefest) `__ +- `ChenHsingYu (@idreamshen) `__ - `igg (@igg) `__ - `Ignacio Hernandez-Ros (@IgnacioHR) `__ - `Petko Bordjukov (@ignisf) `__ @@ -1094,6 +1103,7 @@ Contributors - `Barry Loong (@loongyh) `__ - `Michael Bisbjerg (@LordMike) `__ - `lorenzspenger (@lorenzspenger) `__ +- `luar123 (@luar123) `__ - `LuBeDa (@lubeda) `__ - `Lukáš Maňas (@LucasCZE) `__ - `Lucas Prim (@lucasprim) `__ @@ -1188,6 +1198,7 @@ Contributors - `Christian (@max246) `__ - `Max Bachmann (@maxbachmann) `__ - `Maximilian Gerhardt (@maxgerhardt) `__ +- `Maxime BORGES (@maximeborges) `__ - `Michael Banther (@mbanth) `__ - `mbo18 (@mbo18) `__ - `Jack McCrea (@McCrea) `__ @@ -1440,6 +1451,7 @@ Contributors - `peq123 (@peq123) `__ - `Axotron (@per-magnusson) `__ - `per1234 (@per1234) `__ +- `Perchycs (@Perchycs) `__ - `perjury (@perjury) `__ - `David (@perldj) `__ - `Petapton (@Petapton) `__ @@ -1449,6 +1461,7 @@ Contributors - `Peter Halicky (@peterhalicky) `__ - `Peter Polacek (@PeterPolacek) `__ - `peterv99 (@peterv99) `__ +- `pethans (@pethans) `__ - `Peter Remøy Paulsen (@petrepa) `__ - `Peter Kieser (@pfak) `__ - `Lee (@phatone007) `__ @@ -1592,6 +1605,7 @@ Contributors - `Jérôme W. (@RomRider) `__ - `Robbie Page (@rorpage) `__ - `roscoegray (@roscoegray) `__ +- `Ross Troha (@rosstroha) `__ - `rotarykite (@rotarykite) `__ - `Roving Ronin (@Roving-Ronin) `__ - `Robert Paskowitz (@rpaskowitz) `__ @@ -1672,6 +1686,7 @@ Contributors - `shenxiaozheng (@shenxiaozheng) `__ - `sherbang (@sherbang) `__ - `Shish (@shish) `__ +- `Jerrod (@shomanjk) `__ - `Shreyas Karnik (@shreyaskarnik) `__ - `Sherman K (@shrmnk) `__ - `shuchitak (@shuchitak) `__ @@ -2014,4 +2029,4 @@ Contributors - `Christian Zufferey (@zuzu59) `__ - `Zynth-dev (@Zynth-dev) `__ -*This page was last updated November 8, 2024.* +*This page was last updated November 20, 2024.* diff --git a/images/axs15231.svg b/images/axs15231.svg new file mode 100644 index 0000000000..7bd952a10b --- /dev/null +++ b/images/axs15231.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/es8311.svg b/images/es8311.svg new file mode 100644 index 0000000000..0600c850b3 --- /dev/null +++ b/images/es8311.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/max17043.jpg b/images/max17043.jpg new file mode 100644 index 0000000000..3567f5d020 Binary files /dev/null and b/images/max17043.jpg differ diff --git a/images/opentherm.png b/images/opentherm.png new file mode 100644 index 0000000000..09fe099f23 Binary files /dev/null and b/images/opentherm.png differ diff --git a/images/tc74.jpg b/images/tc74.jpg new file mode 100644 index 0000000000..91e3979596 Binary files /dev/null and b/images/tc74.jpg differ diff --git a/index.rst b/index.rst index 494c9a76e1..74c4cf6d88 100644 --- a/index.rst +++ b/index.rst @@ -258,12 +258,13 @@ Hardware Peripheral Interfaces/Busses .. imgtable:: + 1-Wire, components/one_wire, one-wire.svg CAN Bus, components/canbus/index, canbus.svg I²C Bus, components/i2c, i2c.svg I²S Audio, components/i2s_audio, i2s_audio.svg + OpenTherm, components/opentherm, opentherm.png SPI Bus, components/spi, spi.svg UART, components/uart, uart.svg - 1-Wire, components/one_wire, one-wire.svg I/O Expanders/Multiplexers -------------------------- @@ -499,6 +500,7 @@ Environmental SHTCx, components/sensor/shtcx, shtc3.jpg, Temperature & Humidity SMT100, components/sensor/smt100, smt100.jpg, Moisture & Temperature STS3X, components/sensor/sts3x, sts3x.jpg, Temperature + TC74, components/sensor/tc74, tc74.jpg, Temperature TEE501, components/sensor/tee501, TEE501.png, Temperature TE-M3200, components/sensor/tem3200, tem3200.jpg, Temperature & Pressure TMP102, components/sensor/tmp102, tmp102.jpg, Temperature @@ -559,12 +561,14 @@ Miscellaneous Duty Time, components/sensor/duty_time, timer-play-outline.svg, dark-invert EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH) FS3000, components/sensor/fs3000, fs3000.jpg, Air velocity + GDK101, components/sensor/gdk101, gdk101.jpg, Radiation Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop 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 + MAX17043, components/sensor/max17043, max17043.jpg, Battery MicroNova pellet stove, components/micronova, micronova.svg Modbus Sensor, components/sensor/modbus_controller, modbus.png Nextion, components/sensor/nextion, nextion.jpg, Sensors from display @@ -577,7 +581,6 @@ Miscellaneous uFire EC sensor, components/sensor/ufire_ec, ufire_ec.png, EC & Temperature uFire ISE sensor, components/sensor/ufire_ise, ufire_ise.png, pH & Temperature WireGuard, components/wireguard, wireguard_custom_logo.svg, dark-invert - GDK101, components/sensor/gdk101, gdk101.jpg, Radiation Motion ****** @@ -872,7 +875,7 @@ Display Hardware Platforms Nextion, components/display/nextion, nextion.jpg PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg PVVX MiThermometer, components/display/pvvx_mithermometer, ../components/sensor/images/xiaomi_lywsd03mmc.jpg - Quad SPI AMOLED, components/display/qspi_amoled, t4-s3.jpg + Quad SPI Displays, components/display/qspi_dbi, t4-s3.jpg RPI_DPI_RGB, components/display/rpi_dpi_rgb, waveshare_touch-s3.jpg SSD1306, components/display/ssd1306, ssd1306.jpg SSD1322, components/display/ssd1322, ssd1322.jpg @@ -899,6 +902,7 @@ Touchscreen Components .. imgtable:: Touchscreen Core, components/touchscreen/index, folder-open.svg, dark-invert + AXS15231, components/touchscreen/axs15231, axs15231.svg CST226, components/touchscreen/cst226, t4-s3.jpg CST816, components/touchscreen/cst816, cst816.jpg EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus @@ -1017,6 +1021,7 @@ Audio DAC Components Audio DAC Core, components/audio_dac/index, audio_dac.svg AIC3204, components/audio_dac/aic3204, aic3204.svg + ES8311, components/audio_dac/es8311, es8311.svg Media Player Components -----------------------