diff --git a/.github/workflows/component-image.yml b/.github/workflows/component-image.yml index 2ed1ca7808..f9b3629eaa 100644 --- a/.github/workflows/component-image.yml +++ b/.github/workflows/component-image.yml @@ -50,7 +50,7 @@ jobs: component: ${{ needs.prepare.outputs.name }} - name: Upload - uses: actions/upload-artifact@v4.3.4 + uses: actions/upload-artifact@v4.4.2 id: upload-artifact with: name: ${{ needs.prepare.outputs.name }} diff --git a/Doxygen b/Doxygen index 4a71e7183f..0f72372da4 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.9.2 +PROJECT_NUMBER = 2024.11.0-dev # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index 840643544a..aaf14f9512 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2024.9.2 +ESPHOME_REF = dev PAGEFIND_VERSION=1.1.0 PAGEFIND=pagefind NET_PAGEFIND=../pagefindbin/pagefind diff --git a/_static/changelog-2024.10.0.png b/_static/changelog-2024.10.0.png new file mode 100644 index 0000000000..ac59061ea8 Binary files /dev/null and b/_static/changelog-2024.10.0.png differ diff --git a/_static/version b/_static/version index c3099637c6..5a20e58724 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2024.9.2 \ No newline at end of file +2024.11.0-dev \ No newline at end of file diff --git a/changelog/2024.10.0.rst b/changelog/2024.10.0.rst new file mode 100644 index 0000000000..f66cc51a3f --- /dev/null +++ b/changelog/2024.10.0.rst @@ -0,0 +1,183 @@ +ESPHome 2024.10.0 - 16th October 2024 +===================================== + +.. seo:: + :description: Changelog for ESPHome 2024.10.0. + :image: /_static/changelog-2024.10.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + Audio DAC Core, components/audio_dac/index, audio_dac.svg + AIC3204, components/audio_dac/aic3204, aic3204.svg + GP2Y1010AU0F, components/sensor/gp2y1010au0f, gp2y1010au0f.png + Grove Gas V2, components/sensor/grove_gas_mc_v2, grove-gas-mc-v2.png + NAU7802, components/sensor/nau7802, nau7802.jpg + NPI-19, components/sensor/npi19, npi19.jpg + TCA9555, components/tca9555, tca9555.svg + TE-M3200, components/sensor/tem3200, tem3200.jpg + + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add tca9555 GPIO driver :esphomepr:`7146` by :ghuser:`mobrembski` (new-integration) +- Add support for Sharp GP2Y1010AU0F PM2.5 sensor :esphomepr:`6007` by :ghuser:`zry98` (new-integration) +- [audio_dac] [aic3204] Add new component + platform :esphomepr:`7505` by :ghuser:`kbx81` (new-integration) +- Feature/add seeed grove gmxxx multichannel gas support :esphomepr:`4304` by :ghuser:`YorkshireIoT` (new-integration) +- Add Initial TE-M3200 pressure sensor support :esphomepr:`6862` by :ghuser:`bakerkj` (new-integration) +- Add Initial NPI-19 pressure sensor support :esphomepr:`7181` by :ghuser:`bakerkj` (new-integration) +- nau7802: new component :esphomepr:`6291` by :ghuser:`cujomalainey` (new-integration) + +New Platforms +^^^^^^^^^^^^^ + +- Haier climate integration update :esphomepr:`7416` by :ghuser:`paveldn` (breaking-change) (new-platform) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Haier climate integration update :esphomepr:`7416` by :ghuser:`paveldn` (breaking-change) (new-platform) +- [ch422g] Add support for pins 8-11; make input work. :esphomepr:`7467` by :ghuser:`clydebarrow` (breaking-change) +- CSE7766 needs even parity :esphomepr:`7549` by :ghuser:`ssieb` (breaking-change) +- [web_server] v3 entity grouping :esphomepr:`6833` by :ghuser:`RFDarter` (breaking-change) + +All changes +^^^^^^^^^^^ + +- Bump peter-evans/create-pull-request from 7.0.0 to 7.0.2 :esphomepr:`7437` by :ghuser:`dependabot[bot]` +- Bump recommended ESP-IDF to 4.4.8 :esphomepr:`7349` by :ghuser:`bdraco` +- [tm1638] Fix linting and formatting issues :esphomepr:`7443` by :ghuser:`jesserockz` +- [image] Fix linting and formatting issues :esphomepr:`7440` by :ghuser:`jesserockz` +- [animation] Fix linting and formatting issues :esphomepr:`7439` by :ghuser:`jesserockz` +- [thermostat] Fix linting and formatting issues :esphomepr:`7442` by :ghuser:`jesserockz` +- Add OpenTherm component (part 1: communication layer and hub) :esphomepr:`6645` by :ghuser:`olegtarasov` (new-integration) +- [st7701s] Make use of IDF5.x to speed up display operations :esphomepr:`7447` by :ghuser:`clydebarrow` +- [modbus_controller] Fix linting and formatting issues :esphomepr:`7441` by :ghuser:`jesserockz` +- Bump pylint from 3.1.0 to 3.2.7 :esphomepr:`7438` by :ghuser:`jesserockz` +- Bump peter-evans/create-pull-request from 7.0.2 to 7.0.3 :esphomepr:`7457` by :ghuser:`dependabot[bot]` +- openeth ethernet / qemu support :esphomepr:`7020` by :ghuser:`apbodrov` +- [nextion] Optionally skip connection handshake :esphomepr:`6905` by :ghuser:`edwardtfn` +- Haier climate integration update :esphomepr:`7416` by :ghuser:`paveldn` (breaking-change) (new-platform) +- Added i2s_comm_fmt parameter to i2s speaker component :esphomepr:`7449` by :ghuser:`PxPert` +- [lvgl] Enhancements :esphomepr:`7453` by :ghuser:`clydebarrow` +- Add tca9555 GPIO driver :esphomepr:`7146` by :ghuser:`mobrembski` (new-integration) +- [st7701s] Fix initialisation race :esphomepr:`7462` by :ghuser:`clydebarrow` +- add "fan_mode" and "swing_mode" to REST API :esphomepr:`7476` by :ghuser:`Tarik2142` +- [esp32_improv] Add triggers for various states :esphomepr:`7461` by :ghuser:`kbx81` +- [micro_wake_word] Workaround for failing IDF 5+ tests :esphomepr:`7484` by :ghuser:`kbx81` +- Bump peter-evans/create-pull-request from 7.0.3 to 7.0.5 :esphomepr:`7469` by :ghuser:`dependabot[bot]` +- Add CSE7766 reactive power :esphomepr:`7301` by :ghuser:`nkinnan` +- Support inkplate 5 and 5 V2 :esphomepr:`7448` by :ghuser:`DavidSichau` +- Add remote transmitter triggers :esphomepr:`7483` by :ghuser:`swoboda1337` +- tcs34725: fix color/clear channel percentage calculations on long exposures :esphomepr:`7493` by :ghuser:`RubenKelevra` +- tcs34725: Add check for Division by Zero :esphomepr:`7485` by :ghuser:`RubenKelevra` +- [core] add ring buffer destructor :esphomepr:`7500` by :ghuser:`kahrendt` +- [ch422g] Add support for pins 8-11; make input work. :esphomepr:`7467` by :ghuser:`clydebarrow` (breaking-change) +- Add clean_session as configurable option to the MQTT component :esphomepr:`7501` by :ghuser:`victorclaessen` +- [wifi] Use custom MAC address if programmed :esphomepr:`7498` by :ghuser:`kbx81` +- Add support for Sharp GP2Y1010AU0F PM2.5 sensor :esphomepr:`6007` by :ghuser:`zry98` (new-integration) +- Make time dependency optional :esphomepr:`7425` by :ghuser:`nkinnan` +- Add OHF logo to README :esphomepr:`7509` by :ghuser:`mrdarrengriffin` +- Bump pypa/gh-action-pypi-publish from 1.10.1 to 1.10.2 :esphomepr:`7487` by :ghuser:`dependabot[bot]` +- tcs34725: optimize fetch time with burst read for RGB and clear values :esphomepr:`7494` by :ghuser:`RubenKelevra` +- tcs34725: Remove IR compensation and improve illuminance and color temperature handling in extreme conditions :esphomepr:`7492` by :ghuser:`RubenKelevra` +- [CI] Remove ``sorted`` from library include dirs :esphomepr:`7526` by :ghuser:`kbx81` +- [wifi] Fix error message when no custom MAC is set :esphomepr:`7515` by :ghuser:`kbx81` +- [esp32] Add ``ignore_efuse_custom_mac`` config var :esphomepr:`7527` by :ghuser:`kbx81` +- [mics_4514] Move consts to consts.py :esphomepr:`7528` by :ghuser:`jesserockz` +- Fix parsing of µs time periods in config :esphomepr:`7495` by :ghuser:`dwmw2` +- [web_server] Expose detail=all on all components :esphomepr:`7531` by :ghuser:`RFDarter` +- [CI] Use a list when reading idedata for includes :esphomepr:`7535` by :ghuser:`kbx81` +- Use "puremagic" instead of "magic" python module :esphomepr:`7536` by :ghuser:`guillempages` +- [lvgl] Remap image to img in "set_style_*" :esphomepr:`7546` by :ghuser:`guillempages` +- CSE7766 needs even parity :esphomepr:`7549` by :ghuser:`ssieb` (breaking-change) +- Allow use of all pulse count unit channels if needed. :esphomepr:`7550` by :ghuser:`ToSa27` +- [bang-bang] Remove ``assert()`` :esphomepr:`7533` by :ghuser:`kbx81` +- [thermostat] Remove ``assert()`` :esphomepr:`7544` by :ghuser:`kbx81` +- [bedjet_codec] Remove ``assert()`` :esphomepr:`7543` by :ghuser:`kbx81` +- [audio_dac] [aic3204] Add new component + platform :esphomepr:`7505` by :ghuser:`kbx81` (new-integration) +- [wifi] Replace ``USE_ESP32_IGNORE_EFUSE_MAC_CRC`` with IDF's ``CONFIG_ESP_MAC_IGNORE_MAC_CRC_ERROR`` :esphomepr:`7502` by :ghuser:`kbx81` +- Bump docker/setup-buildx-action from 3.6.1 to 3.7.1 in the docker-actions group across 1 directory :esphomepr:`7542` by :ghuser:`dependabot[bot]` +- Bump pypa/gh-action-pypi-publish from 1.10.2 to 1.10.3 :esphomepr:`7541` by :ghuser:`dependabot[bot]` +- Bump docker/build-push-action from 6.7.0 to 6.9.0 in /.github/actions/build-image :esphomepr:`7511` by :ghuser:`dependabot[bot]` +- [code-quality] fix clang-tidy md5 and hmac_md5 :esphomepr:`7325` by :ghuser:`tomaszduda23` +- [code-quality] fix clang-tidy api :esphomepr:`7279` by :ghuser:`tomaszduda23` +- [lvgl] Bugfixes #3 :esphomepr:`7472` by :ghuser:`clydebarrow` +- Feature/add seeed grove gmxxx multichannel gas support :esphomepr:`4304` by :ghuser:`YorkshireIoT` (new-integration) +- [lvgl] Fix: allow full range of styles on dropdown list. :esphomepr:`7552` by :ghuser:`clydebarrow` +- [web_server] v3 entity grouping :esphomepr:`6833` by :ghuser:`RFDarter` (breaking-change) +- Add Initial TE-M3200 pressure sensor support :esphomepr:`6862` by :ghuser:`bakerkj` (new-integration) +- Add Initial NPI-19 pressure sensor support :esphomepr:`7181` by :ghuser:`bakerkj` (new-integration) +- nau7802: new component :esphomepr:`6291` by :ghuser:`cujomalainey` (new-integration) +- Update webserver local assets to 20241007-025551 :esphomepr:`7553` by :ghuser:`esphomebot` +- [online_image] Bugfix: Use std::string instead of const char * :esphomepr:`7556` by :ghuser:`clydebarrow` +- [ili9xxx] Put display into sleep mode on shutdown. :esphomepr:`7555` by :ghuser:`clydebarrow` +- Bump actions/upload-artifact from 4.4.0 to 4.4.1 :esphomepr:`7559` by :ghuser:`dependabot[bot]` +- Bump actions/cache from 4.0.2 to 4.1.0 in /.github/actions/restore-python :esphomepr:`7560` by :ghuser:`dependabot[bot]` +- Bump actions/cache from 4.0.2 to 4.1.0 :esphomepr:`7558` by :ghuser:`dependabot[bot]` +- Update radon_eye_listener.cpp for more possible variants :esphomepr:`7567` by :ghuser:`baldisos` +- [cst816] Allow skipping i2c probe :esphomepr:`7557` by :ghuser:`clydebarrow` +- [lvgl] Fix text component :esphomepr:`7563` by :ghuser:`clydebarrow` +- [template/binary_sensor] Implement `condition:` option as alternative to lambda. :esphomepr:`7561` by :ghuser:`clydebarrow` +- Bump actions/upload-artifact from 4.4.1 to 4.4.2 :esphomepr:`7569` by :ghuser:`dependabot[bot]` +- Bump actions/cache from 4.1.0 to 4.1.1 :esphomepr:`7570` by :ghuser:`dependabot[bot]` +- Bump actions/cache from 4.1.0 to 4.1.1 in /.github/actions/restore-python :esphomepr:`7571` by :ghuser:`dependabot[bot]` + +Past Changelogs +--------------- + +- :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 614356b809..5083b6fc9f 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2024.9.0.html + :url: /changelog/2024.10.0.html .. toctree:: :glob: diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index 76703b8740..ea28000603 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -50,8 +50,8 @@ Configuration variables: - **on_chime** (*Optional*, :ref:`Action `): An automation to perform when a zone has been marked as chime in the configuration, and it changes from closed to open. See :ref:`alarm_control_panel_on_chime_trigger`. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. - If MQTT enabled, all other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. Automation: diff --git a/components/audio_dac/aic3204.rst b/components/audio_dac/aic3204.rst new file mode 100644 index 0000000000..a9f19cd7f3 --- /dev/null +++ b/components/audio_dac/aic3204.rst @@ -0,0 +1,54 @@ +AIC3204 +======= + +.. seo:: + :description: Instructions for using ESPHome's AIC3204 audio DAC platform to play media from your devices. + :image: i2s_audio.svg + :keywords: AIC3204, Audio, DAC, I2S, ESP32 + +The ``aic3204`` platform allows your ESPHome devices to use the AIC3204 ultra low power stereo audio codec (DAC). +This allows the playback of audio via the microcontroller from a range of sources via +:doc:`/components/media_player/index`. + +The :ref:`I²C bus ` is required in your configuration as this is used to communicate with the AIC3204. + +.. code-block:: yaml + + # Example configuration entry + audio_dac: + - platform: aic3204 + +.. _config-aic3204: + +Configuration variables: +------------------------ + +- **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 AIC3204 is connected to. +- All other options from :ref:`Audio DAC `. + +Automations +----------- + +``aic3204.set_auto_mute_mode`` Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This action sets the auto-mute mode of the AIC3204. See page 111 in the +`reference manual `__ +for more information. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the ``aic3204`` platform. +- **mode** (**Required**, int, :ref:`templatable `): The auto-mute mode to be used; must be in the + range of 0 (auto-mute disabled) to 7. + +All :ref:`Audio DAC Automations ` are supported by this platform, as well. + +See Also +-------- + +- :doc:`index` +- :apiref:`aic3204/aic3204.h` +- :apiref:`audio_dac/audio_dac.h` +- :ghedit:`Edit` diff --git a/components/audio_dac/index.rst b/components/audio_dac/index.rst new file mode 100644 index 0000000000..8105c768ff --- /dev/null +++ b/components/audio_dac/index.rst @@ -0,0 +1,71 @@ +Audio DAC Core +============== + +.. seo:: + :description: Instructions for using ESPHome's Audio DAC Core component. + :image: i2s_audio.svg + :keywords: Audio, DAC, I2S, ESP32 + +The `audio_dac` component allows your ESPHome devices to use audio DAC hardware components, allowing the playback of +audio via the microcontroller from a range of sources via :doc:`/components/media_player/index`. + +.. code-block:: yaml + + # Example configuration entry + audio_dac: + - platform: ... + +.. _config-audio_dac: + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + +.. _automations-audio_dac: + +Automations +----------- + +``audio_dac.mute_off`` Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This action unmutes the output of the DAC. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the ``audio_dac`` platform. + +``audio_dac.mute_on`` Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This action mutes the output of the DAC. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the ``audio_dac`` platform. + +``audio_dac.set_volume`` Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This action sets the output volume of the DAC. + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the ``audio_dac`` platform. +- **volume** (**Required**, percentage, :ref:`templatable `): The desired volume level for the + output from 0% to 100%. + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index 949a2bf154..8548080706 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -75,7 +75,7 @@ Advanced options: 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, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. .. _binary_sensor-filters: diff --git a/components/binary_sensor/template.rst b/components/binary_sensor/template.rst index c1c8e645b1..d486a55bbd 100644 --- a/components/binary_sensor/template.rst +++ b/components/binary_sensor/template.rst @@ -5,12 +5,11 @@ Template Binary Sensor :description: Instructions for setting up template binary sensors. :image: description.svg -The ``template`` binary sensor platform allows you to define any :ref:`lambda template ` -and construct a binary sensor out if it. The lambda will run continuously; it isn't possible to specify -an interval at which the lambda runs. +The ``template`` binary sensor platform allows you to define a boolean condition and use it to provide a binary sensor. +The condition may be expressed as a C++ lambda, or as a :ref:`YAML expression `. +The condition expression will be evaluated continually, on each call to the component's ``loop()`` method, which is typically every 16ms. -For example, below configuration would turn the state of an ultrasonic sensor into -a binary sensor. +The example below polls an analog sensor and yields a value dependent on whether the sensor value is above a threshold. .. code-block:: yaml @@ -31,13 +30,28 @@ Possible return values of the lambda: - ``return true;`` if the binary sensor should be ON. - ``return false;`` if the binary sensor should be OFF. - - ``return {};`` if the state is not known (use last known state) + - ``return {};`` if the state is not known. The last known state will be maintained. + +As an alternative to using a lambda you may use ESPHome :ref:`condition expressions `: + +.. code-block:: yaml + + # Example configuration entry + binary_sensor: + - platform: template + id: engine_running + condition: + sensor.in_range: + id: engine_rpm + above: 300.0 + Configuration variables: ------------------------ - **lambda** (*Optional*, :ref:`lambda `): - Lambda to be evaluated repeatedly to get the current state of the binary sensor. + C++ Lambda to be evaluated repeatedly to get the current state of the binary sensor. +- **condition** (*Optional*, :ref:`Condition `): The condition to check to determine the value of the binary sensor. ``lambda`` and ``condition`` may not both be present in the configuration. - All other options from :ref:`Binary Sensor `. .. _binary_sensor-template-publish_action: diff --git a/components/button/index.rst b/components/button/index.rst index 921d37848e..c3f330b72d 100644 --- a/components/button/index.rst +++ b/components/button/index.rst @@ -60,7 +60,7 @@ Configuration variables: - **device_class** (*Optional*, string): The device class for the button. See https://www.home-assistant.io/integrations/button/#device-class for a list of available options. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/climate/index.rst b/components/climate/index.rst index 8badd6d9bb..188b3efa32 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -86,6 +86,7 @@ Advanced options: 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. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. MQTT options: @@ -128,7 +129,6 @@ MQTT options: - **target_humidity_command_topic** (*Optional*, string): The topic to receive target humidity commands on. - All other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. Climate Automation ------------------ diff --git a/components/cover/index.rst b/components/cover/index.rst index 3ac2e9b667..9ae2e0f17e 100644 --- a/components/cover/index.rst +++ b/components/cover/index.rst @@ -52,6 +52,8 @@ Advanced options: 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. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. + MQTT options: @@ -64,7 +66,6 @@ MQTT options: - **tilt_command_topic** (*Optional*, string): The topic to receive cover tilt commands on. - All other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. .. _cover-open_action: diff --git a/components/datetime/index.rst b/components/datetime/index.rst index 53459d304a..b704072fbb 100644 --- a/components/datetime/index.rst +++ b/components/datetime/index.rst @@ -50,7 +50,7 @@ Configuration variables: Set to ``""`` to remove the default entity category. - **time_id** (**Optional**, :ref:`config-id`): The ID of the time entity. Automatically set to the ID of a time component if only a single one is defined. Required if ``on_time`` is used. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. MQTT Options: diff --git a/components/fan/index.rst b/components/fan/index.rst index c0e34ef058..a219d869cf 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -55,6 +55,7 @@ Configuration variables: 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. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. MQTT options: @@ -71,7 +72,6 @@ MQTT options: - **speed_command_topic** (*Optional*, string): The topic to receive speed commands on (options: LOW, MEDIUM, HIGH). - All other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. Automation triggers: diff --git a/components/font.rst b/components/font.rst index 8f215822c1..1a800bdb1f 100644 --- a/components/font.rst +++ b/components/font.rst @@ -149,7 +149,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 -------- diff --git a/components/index.rst b/components/index.rst index df4c68c255..9cb49dcc82 100644 --- a/components/index.rst +++ b/components/index.rst @@ -27,6 +27,7 @@ Components lock/index display_menu/index lvgl/index + audio_dac/index media_player/index microphone/index speaker/index diff --git a/components/light/index.rst b/components/light/index.rst index 7c50bc2968..9d0ac4ed3e 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -82,7 +82,7 @@ Advanced options: 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, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. .. _light-toggle_action: diff --git a/components/lock/index.rst b/components/lock/index.rst index f88c939780..bb30062dd2 100644 --- a/components/lock/index.rst +++ b/components/lock/index.rst @@ -45,7 +45,7 @@ Configuration variables: 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. - If MQTT enabled, All other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. .. _lock-lock_action: diff --git a/components/lvgl/index.rst b/components/lvgl/index.rst index 1a88404a95..797395c4d7 100644 --- a/components/lvgl/index.rst +++ b/components/lvgl/index.rst @@ -113,6 +113,17 @@ The following configuration variables apply to the main ``lvgl`` component, in o The ``long_press_time`` and ``long_press_repeat_time`` can be fine-tuned also by setting them to ``never`` and using the ``autorepeat`` filter on each binary sensor separately. + .. tip:: + + When using an encoder input device the navigation works as follows: + + - By turning the encoder you can focus on the next/previous object. + - When you press the encoder on a simple object (like a button), it will be clicked. + - If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby you can adjust the value of the object by turning the encoder. + - To leave edit mode, long press the button. + + + - **color_depth** (*Optional*, string): The color deph at which the contents are generated. Currently only ``16`` is supported (RGB565, 2 bytes/pixel), which is the default value. - **buffer_size** (*Optional*, percentage): The percentage of screen size to allocate buffer memory. Default is ``100%`` (or ``1.0``). For devices without PSRAM, the recommended value is ``25%``. - **log_level** (*Optional*, string): Set the logger level specifically for the messages of the LVGL library: ``TRACE``, ``INFO``, ``WARN``, ``ERROR``, ``USER``, ``NONE``. Defaults to ``WARN``. diff --git a/components/lvgl/widgets.rst b/components/lvgl/widgets.rst index 1909bebcf8..9bcb2dff7c 100644 --- a/components/lvgl/widgets.rst +++ b/components/lvgl/widgets.rst @@ -684,15 +684,13 @@ The Dropdown widget is built internally from a *button* part and a *list* part ( **Configuration variables:** -- **dir** (*Optional*, dict): Where the list part of the dropdown gets created relative to the button part. ``LEFT``, ``RIGHT``, ``BOTTOM``, ``TOP``, defaults to ``BOTTOM``. -- **dropdown_list** (*Optional*, list): Settings for the dropdown_list *part*, the list with items. Supports a list of :ref:`styles ` to customize. Notable are ``text_line_space`` and ``pad_all`` for spacing of list items, and ``text_font`` to separately change the font in the list. -- **indicator** (*Optional*, list): Settings for the the parent of ``symbol``. Supports a list of :ref:`styles ` to customize. +- **dir** (*Optional*, str): Where the list part of the dropdown gets created relative to the button part. ``LEFT``, ``RIGHT``, ``BOTTOM``, ``TOP``, defaults to ``BOTTOM``. +- **dropdown_list** (*Optional*, dict): Settings for the the list with items. Supports a list of :ref:`styles ` to customize. Notable are ``text_line_space`` and ``pad_all`` for spacing of list items, and ``text_font`` to separately change the font in the list. The parts ``main``, ``scrollbar`` and ``selected`` may be customised. Note that changing styles on the selected item should be done in the ``selected`` part with ``checked`` state. ``max_height`` can be used to limit the height of the list. +- **indicator** (*Optional*, dict): Styles for the dropdown symbol. - **options** (**Required**, list): The list of available options in the drop-down. -- **scrollbar** (*Optional*, list): Settings for the scrollbar *part*. Supports a list of :ref:`styles ` to customize. The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right. - **selected_index** (*Optional*, int8): The index of the item you wish to be selected. -- **selected** (*Optional*, list): Settings for the selected item in the list. Supports a list of :ref:`styles ` to customize. - **symbol** (*Optional*, dict): A symbol (typically an chevron) is shown in dropdown list. If ``dir`` of the drop-down list is ``LEFT`` the symbol will be shown on the left, otherwise on the right. Choose a different :ref:`symbol ` from those built-in or from your own customized font. -- Style options from :ref:`lvgl-styling` for the background of the button and the list. Uses the typical background properties and :ref:`lvgl-widget-label` text properties for the text on it. ``max_height`` can be used to limit the height of the list. ``text_font`` can be used to set the font of the button part, including the symbol. +- 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:** @@ -722,6 +720,10 @@ The Dropdown widget is built internally from a *button* part and a *list* part ( - Chello - Drums selected_index: 2 + dropdown_list: + selected: + checked: + text_color: 0xFF0000 # Example action: on_...: @@ -1057,20 +1059,21 @@ The meter widget can visualize data in very flexible ways. It can use arcs, need - **r_mod**: Adjust the position of the arc from the scale radius with this amount (can be negative). Defaults to ``0``. - **start_value**: The value in the scale range to start drawing the arc from. - **width**: Arc width in pixels. Defaults to ``4``. - - Style options for the *arc* using the :ref:`lvgl-widget-arc` style properties. + - **opa**: Opacity of the arc. Defaults to 100%. - **image** (*Optional*): Add a rotating needle image to the scale: - **id**: Manually specify the :ref:`config-id` used for updating the indicator value at runtime. - **pivot_x**: Horizontal position of the pivot point of rotation, in pixels, relative to the top left corner of the image. - **pivot_y**: Vertical position of the pivot point of rotation, in pixels, relative to the top left corner of the image. - **src**: The ID of an existing image configuration, representing a needle pointing to the right like ``-o--->``. - **value**: The value in the scale range to show at start. + - **opa**: Opacity of the image. Defaults to 100%. - **line** (*Optional*): Add a needle line to the scale. By default, the length of the line is the same as the scale's radius: - **color**: :ref:`Color ` for the needle line. Defaults to ``0`` (black). - **id**: Manually specify the :ref:`config-id` used for updating the indicator value at runtime. - **r_mod**: Adjust the length of the needle from the scale radius with this amount (can be negative). Defaults to ``0``. - **value**: The value in the scale range to show at start. - **width**: Needle line width in pixels. Defaults to ``4``. - - Style options for the *needle line* using the :ref:`lvgl-widget-line` style properties, as well as the background properties from :ref:`lvgl-styling` to draw a square (or circle) on the pivot of the needles. Padding makes the square larger. + - **opa**: Opacity of the needle. Defaults to 100%. - **tick_style** (**Optional**): Add tick style modifications: - **color_end**: :ref:`Color ` for the gradient end of the ticks. - **color_start**: :ref:`Color ` for the gradient start of the ticks. @@ -1104,8 +1107,12 @@ The meter widget can visualize data in very flexible ways. It can use arcs, need **Actions:** -- ``lvgl.indicator.update`` :ref:`action ` updates indicator options except ``src``, which cannot be updated at runtime. :ref:`lvgl.widget.update ` action can be used for the common styles, states or flags of the meter widget (not the indicators). - - **id** (**Required**): The ID or a list of IDs of line or image indicators which you want update. +- ``lvgl.indicator.update`` :ref:`action ` updates indicator options as below. :ref:`lvgl.widget.update ` action can be used for the common styles, states or flags of the meter widget. + - **id** (**Required**): The ID or a list of IDs of indicators to update. + - **end_value** (*Optional*): The value in the scale range to end drawing the arc to. + - **start_value** (*Optional*): The value in the scale range to start drawing the arc from. + - **opa** (*Optional*): Opacity of the indicator. + **Triggers:** diff --git a/components/number/index.rst b/components/number/index.rst index 117c170e25..e9fa94c541 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -58,7 +58,7 @@ Configuration variables: - **device_class** (*Optional*, string): The device class for the number. See https://www.home-assistant.io/integrations/number/#device-class for a list of available options. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/select/index.rst b/components/select/index.rst index 688f4132bc..49bd208e86 100644 --- a/components/select/index.rst +++ b/components/select/index.rst @@ -49,7 +49,7 @@ Configuration variables: 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. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/sensor/cse7766.rst b/components/sensor/cse7766.rst index e7fb1ab1dd..0165db6b53 100644 --- a/components/sensor/cse7766.rst +++ b/components/sensor/cse7766.rst @@ -17,7 +17,7 @@ and works with this component. As the communication with the CSE7766 done using UART, you need to have an :ref:`UART bus ` in your configuration with the ``rx_pin`` connected to the CSE7766. -Additionally, you need to set the baud rate to 4800. The device sends multiple updates per second, so you +Additionally, you need to set the baud rate to 4800 and parity to EVEN. The device sends multiple updates per second, so you will probably want some sort of averaging or throttle filter on the sensors. .. code-block:: yaml @@ -33,6 +33,7 @@ will probably want some sort of averaging or throttle filter on the sensors. uart: rx_pin: RX baud_rate: 4800 + parity: EVEN sensor: - platform: cse7766 diff --git a/components/sensor/grove_gas_mc_v2.rst b/components/sensor/grove_gas_mc_v2.rst new file mode 100644 index 0000000000..1230af43be --- /dev/null +++ b/components/sensor/grove_gas_mc_v2.rst @@ -0,0 +1,85 @@ +Grove Multichannel Gas Sensor V2 +================================================ + +.. seo:: + :description: Instructions for setting up Grove Multichannel Gas Sensor V2 that + can measure Nitrogen Dioxide, Carbon Monoxide, Ethanol and Volatile Organic + Compounds. + :image: grove-gas-mc-v2.png + :keywords: Grove, gm102b, gm302b, gm502b, gm702b + +The ``grove_gas_mc_v2`` sensor platform allows you to use your `Grove Multichannel Gas +Sensor V2 `__ +with ESPHome. It exposes 4 different gas sensors for qualitatively measuring +Nitrogen Dioxide (NO2), Carbon Monoxide (CO), Ethanol (C2H5OH), and Volatile Organic +Compounds (VOCs). + +.. note:: + + The Grove Multichannel Gas Sensor V2 is a qualitative, not quantitative, sensor. + This means values reported back are raw ADC values. Values are **not** in a common unit + of measurement, such as PPM (parts per million). If you have known baseline readings + for any of the gases, :ref:`sensor-filters` could be used to calibrate the raw readings. + +.. figure:: /images/grove-gas-mc-v2.png + :align: center + :width: 50.0% + + Grove Multichannel Gas Sensor V2 + +The communication with this sensor is done via :ref:`I²C Bus `, so you need to have +an ``i2c:`` section in your config for this integration to work. + +.. code-block:: yaml + + sensor: + - platform: grove_gas_mc_v2 + no2: + name: "Nitrogen Dioxide" + ethanol: + name: "Ethanol" + carbon_monoxide: + name: "Carbon Monoxide" + tvoc: + name: "Volatile Organic Compounds" + +Configuration variables: +------------------------ + +- **no2** (**Required**): The Nitrogen Dioxide sensor data. + All options from :ref:`Sensor `. +- **ethanol** (**Required**): The Ethanol (C2H5OH) sensor data. + All options from :ref:`Sensor `. +- **carbon_monoxide** (**Required**): The Carbon Monoxide sensor data. + All options from :ref:`Sensor `. +- **tvoc** (**Required**): The Total Volatile Organic Compounds (TVOC) sensor data. + All options from :ref:`Sensor `. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +Advanced: + +- **address** (*Optional*, int): The :ref:`I²C ` address of the sensor. + Defaults to ``0x08`` + +.. _grove-gas-mc-v2-preheating: + +Preheating +-------------------- + +If the sensor is stored for a long period of time (without power) there is a recommended +minimum warm-up time required for the sensor before the readings settle down and become +more accurate. + +A recommended warm-up time of 24 hours is recommend if the sensor has been stored +less than a month, 48 hours for 1-6 months and at least 72 hours for anything longer +than 6 months. + +See Also +-------- + +- :ref:`sensor-filters` +- `Grove Multichannel V2 Library `__ +- :apiref:`grove_gas_mc_v2/grove_gas_mc_v2.h` +- :ghedit:`Edit` diff --git a/components/sensor/images/nau7802.png b/components/sensor/images/nau7802.png new file mode 100644 index 0000000000..c530f1ea2c Binary files /dev/null and b/components/sensor/images/nau7802.png differ diff --git a/components/sensor/images/npi19.jpg b/components/sensor/images/npi19.jpg new file mode 100644 index 0000000000..c2d19be739 Binary files /dev/null and b/components/sensor/images/npi19.jpg differ diff --git a/components/sensor/images/tem3200.jpg b/components/sensor/images/tem3200.jpg new file mode 100644 index 0000000000..72ae0d72a3 Binary files /dev/null and b/components/sensor/images/tem3200.jpg differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 177b952852..00433fc0e7 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -73,7 +73,7 @@ Configuration variables: 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. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/sensor/nau7802.rst b/components/sensor/nau7802.rst new file mode 100644 index 0000000000..c0042a3247 --- /dev/null +++ b/components/sensor/nau7802.rst @@ -0,0 +1,126 @@ +NAU7802 24-bit ADC +========================= + +.. seo:: + :description: Instructions for setting up NAU7802 ADC with ESPHome + :image: nau7802.jpg + :keywords: NAU7802 + +The ``nau7802`` sensor platform allows you to use your NAU7802 ADC +(`datasheet `__, `Adafruit`_) with ESPHome. This ADC is typically used with strain gauges to act as a weight sensor. + +.. figure:: images/nau7802.png + :align: center + :target: `Adafruit`_ + :width: 60.0% + + NAU7802 on a breakout board. Image by `Adafruit`_ + +.. _Adafruit: https://www.adafruit.com/product/4538 +.. _Sparkfun: https://www.sparkfun.com/products/15242 + +Connect power pins (``VCC``/``GND``) and I2C (``SDA``/``SCL``). If using external reference voltage connect (``AV``/``AVDD``). Interrupt (``INT``/``DRDY``) is not supported. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: nau7802 + name: "NAU7802 Value" + gain: 128 + ldo_voltage: "3.0V" + update_interval: 60s + +Configuration variables: +------------------------ + +- **gain** (*Optional*, enum): ADC gain. + + - ``1`` + - ``2`` + - ``4`` + - ``8`` + - ``16`` + - ``32`` + - ``64`` + - ``128`` *(default)* + +- **ldo_voltage** (*Optional*, enum): Voltage used for reference, should be less than ``VCC`` + + - ``2.4V`` + - ``2.7V`` + - ``3.0V`` *(default)* + - ``3.3V`` + - ``3.6V`` + - ``3.9V`` + - ``4.2V`` + - ``4.5V`` + - ``External``, ``Ext`` Use this if are using the ``AV``/``AVDD`` Pin + +- **samples_per_second** (*Optional*, enum): Sets the internal chip sample rate + + - ``10`` *(default)* + - ``20`` + - ``40`` + - ``80`` + - ``320`` + +- **offset_calibration** (*Optional*, int): Pre calibrated offset value, range -8388608 to 8388607 +- **gain_calibration** (*Optional*, float): Pre calibrated gain value, range 0 to 511.9999998807907 + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +- All other options from :ref:`Sensor `. + +Calibration +----------- +The NAU7802 includes 3 types of calibration, Internal offset, External Offset, and External Gain. Using the +Internal calibration should result in a consistent offset as it uses only reference voltage to calibrate. +External calibration uses the sensor reading in its current state. That means if the load is not consistent +when the action is executed then you will end up with varying results between calibrations and potential +loss of range on the ADC. + +For high precision applications it is recommended to perform your calibration and store then store the +results in your config using ``offset_calibration`` and ``gain_calibration`` fields for final usage. +You can retrieve the calibrated values when the component dumps its config or when you execute the +action to calibrate. + +Converting Units +---------------- + +The NAU7802 does not translate its ADC values to weights directly and can be used with varying types of gauges, +therefore you have to convert the measurement to units yourself. +To calibrate the sensor: + +.. The rest of this section is copied from the HX711 doc as the procedure is essentially the same + +1. Place a zero load or a known mass on the sensor, for example ``0kg`` +2. Wait for the data to arrive in the logs and write down the value. For example ``120``. +3. Place another (different) known mass on the sensor, for example ``1kg`` +4. Again wait for the data to arrive and note the value, for example ``810``. + +Once you've done those steps, you can use the ``calibrate_linear`` filter to map the incoming value +to the calibrated one: + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: nau7802 + # ... Other NAU7802 options + filters: + - calibrate_linear: + - 120 -> 0 + - 810 -> 1 + unit_of_measurement: kg + +Replace the masses and values ``120.0``, ``810.0``, etc with your values. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`adc` +- :apiref:`nau7802/nau7802.h` +- `Adafruit NAU7802 Library `__ + `NAU7802 Datasheet `__ +- :ghedit:`Edit` diff --git a/components/sensor/npi19.rst b/components/sensor/npi19.rst new file mode 100644 index 0000000000..3c466023ca --- /dev/null +++ b/components/sensor/npi19.rst @@ -0,0 +1,108 @@ +NPI-19 Pressure Sensor +=========================================== + +.. seo:: + :description: Instructions for setting up NPI-19 pressure sensors with ESPHome + :image: npi19.jpg + :keywords: NPI-19 NPI19 + +The ``npi19`` sensor platform allows you to use your NPI-19 (`datasheet `__, +`product page `__) pressure sensors with ESPHome. + +.. figure:: images/npi19.jpg + :align: center + :width: 50.0% + + NPI-19 Pressure Sensor. + + +Configuration +------------- +:ref:`I²C ` bus is required to be set up in your configuration for this sensor to work. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: npi19 + raw_pressure: + name: "Raw Pressure" + temperature: + name: Temperature + + +Configuration variables +----------------------- + +- **raw_pressure** (*Optional*): The information for the pressure sensor. See :ref:`npi19-converting`. + + - All other options from :ref:`Sensor `. + +- **temperature** (*Optional*): The information for the temperature sensor. Readings in degrees celsius (°C). + + - All other options from :ref:`Sensor `. + +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component `. Defaults to the default I²C bus. + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. + All known sensors currently configured to ``0x28``. Defaults to ``0x28``. + + +.. _npi19-converting: + +Converting units +----------------- + +The NPI-19 pressure sensor is not calibrated to units, you have to convert the measurement to units yourself. + +Estimated +********* + +On page 1 of the `product application note `__ +the value ``1638`` maps to approximately ``10%`` of the maximum value of the sensor (e.g. ``0.5`` psi for a ``5`` psi sensor); +the value ``14746`` maps to approximately ``90%`` of the maximum value of the sensor (e.g. ``4.5`` psi for a ``5`` psi sensor). +Use ``calibrate_linear`` filter to map these sensor values: + +.. code-block:: yaml + + # Extract of configuration + filters: + - calibrate_linear: + - 1638 -> 0.5 + - 14746 -> 4.5 + +Calibrated +********** +1. Expose the sensor to a low known pressure, for example ``5`` psi. +2. Observe the value of the raw pressure sensor, for example ``1500``. +3. Expose the sensor to a high pressure, for example ``90`` psi. +4. Observe the value of the raw pressure sensor, for example ``14500``. +5. Use ``calibrate_linear`` filter to map the incoming value to the calibrated one: + +.. code-block:: yaml + + # Extract of configuration + filters: + - calibrate_linear: + - 1500 -> 5.0 + - 14500 -> 90.0 + + +Notes +----- + +The NPI-19 I²C has a temperature output, however the manufacturer does +not specify its accuracy on the published datasheet. They indicate +that the sensor should not be used as a calibrated temperature +reading; it’s only intended for curve fitting data during +compensation. + + +See Also +-------- + +- :ref:`sensor-filters` +- `NPI-19 Product Page `__ +- `NPI-19 Datasheet `__ +- `NPI-19 Product Application Note `__ +- :ghedit:`Edit` diff --git a/components/sensor/tem3200.rst b/components/sensor/tem3200.rst new file mode 100644 index 0000000000..d79a1e1f2c --- /dev/null +++ b/components/sensor/tem3200.rst @@ -0,0 +1,100 @@ +TE-M3200 Pressure Sensor +=========================================== + +.. seo:: + :description: Instructions for setting up TE-M3200 pressure sensors with ESPHome + :image: tem3200.jpg + :keywords: TEM3200 TE-M3200 + +The ``tem3200`` sensor platform allows you to use your TE-M3200 (`datasheet `__, +`product page `__) pressure sensors with ESPHome. + +.. figure:: images/tem3200.jpg + :align: center + :width: 50.0% + + TE-M3200 Pressure Sensor. + + +Configuration +------------- +:ref:`I²C ` bus is required to be set up in your configuration for this sensor to work. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: tem3200 + raw_pressure: + name: "Raw Pressure" + temperature: + name: Temperature + + +Configuration variables +----------------------- + +- **raw_pressure** (*Optional*): The information for the pressure sensor. See :ref:`tem3200-converting`. + + - All other options from :ref:`Sensor `. + +- **temperature** (*Optional*): The information for the temperature sensor. Readings in degrees celsius (°C). + + - All other options from :ref:`Sensor `. + +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component `. Defaults to the default I²C bus. + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x28``. See `datasheet + `__ + (page 10). + + +.. _tem3200-converting: + +Converting units +----------------- + +The TE-M3200 pressure sensor is not calibrated to units, you have to convert the measurement to units yourself. + +Estimated +********* + +On page 6 of the `datasheet `__ +the value ``1000`` maps to approximately ``0%`` of the maximum value of the sensor (e.g. ``0`` psi for a ``100`` psi sensor); +the value ``8000`` maps to approximately ``50%`` of the maximum value of the sensor (e.g. ``50`` psi for a ``100`` psi sensor); +the value ``15000`` maps to approximately ``100%`` of the maximum value of the sensor (e.g. ``100`` psi for the ``100`` psi sensor). +Use ``calibrate_linear`` filter to map these sensor values: + +.. code-block:: yaml + + # Extract of configuration + filters: + - calibrate_linear: + - 1000 -> 0.0 + - 8000 -> 50.0 + - 15000 -> 100.0 + +Calibrated +********** +1. Expose the sensor to a low known pressure, for example ``5`` psi. +2. Observe the value of the raw pressure sensor, for example ``990``. +3. Expose the sensor to a high pressure, for example ``90`` psi. +4. Observe the value of the raw pressure sensor, for example ``13550``. +5. Use ``calibrate_linear`` filter to map the incoming value to the calibrated one: + +.. code-block:: yaml + + # Extract of configuration + filters: + - calibrate_linear: + - 990 -> 5.0 + - 13550 -> 90.0 + + +See Also +-------- + +- :ref:`sensor-filters` +- `TE-M3200 Product Page `__ +- `TE-M3200 Datasheet `__ +- :ghedit:`Edit` diff --git a/components/switch/index.rst b/components/switch/index.rst index 4cbca2778f..e2b100ff43 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -69,7 +69,7 @@ Configuration variables: See https://www.home-assistant.io/integrations/switch/#device-class for a list of available options. - If MQTT enabled, All other options from :ref:`MQTT Component `. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. .. _switch-toggle_action: diff --git a/components/text/index.rst b/components/text/index.rst index bc706928cb..6ef27f8b96 100644 --- a/components/text/index.rst +++ b/components/text/index.rst @@ -50,7 +50,7 @@ Configuration variables: for a list of available options. Set to ``""`` to remove the default entity category. - **mode** (**Required**, string): Defines how the text should be displayed in the frontend. One of ``text`` or ``password``. -- If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst index e94f1a1bea..71380b071c 100644 --- a/components/text_sensor/index.rst +++ b/components/text_sensor/index.rst @@ -48,7 +48,7 @@ Configuration variables: 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, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations: diff --git a/components/touchscreen/cst816.rst b/components/touchscreen/cst816.rst index b08d70aa15..27a56e5a10 100644 --- a/components/touchscreen/cst816.rst +++ b/components/touchscreen/cst816.rst @@ -37,6 +37,7 @@ 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 chip reset pin. +- **skip_probe** (*Optional*, boolean): Skip reading the chip ID on startup. May be required for some variants (e.g. CST816S) that do not respond to i2c commands except after touches are registered. Defaults to false. - All other options from :ref:`Touchscreen `. diff --git a/components/update/index.rst b/components/update/index.rst index db15a876f5..db2603dcd4 100644 --- a/components/update/index.rst +++ b/components/update/index.rst @@ -38,8 +38,8 @@ Configuration variables: - **icon** (*Optional*, icon): The icon to use for the update entity in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Specifying an ``id`` without a ``name`` will - implicitly set this to true. - **on_update_available** (*Optional*, :ref:`Action `): An automation to perform when an update is available. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. Automations ----------- diff --git a/components/valve/index.rst b/components/valve/index.rst index 912bc676cc..4a977604bc 100644 --- a/components/valve/index.rst +++ b/components/valve/index.rst @@ -50,6 +50,7 @@ Advanced options: (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. +- If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See :ref:`Webserver Version 3 `. MQTT options: diff --git a/components/web_server.rst b/components/web_server.rst index 198d49c81a..d830620a57 100644 --- a/components/web_server.rst +++ b/components/web_server.rst @@ -71,6 +71,11 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **local** (*Optional*, boolean): Include supporting javascript locally allowing it to work without internet access. Defaults to ``false``. - **version** (*Optional*, string): ``1``, ``2`` or ``3``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Version 3 uses HA-Styling. Defaults to ``2``. +- **sorting_groups** (*Optional*, list): Avaliable only on ``version: 3``. A list of group ID's and names to group the entities. See :ref:`Webserver Entity Grouping `. + + - **id** (*Required*, :ref:`config-id`): Manually specify the ID used for the group. + - **name** (*Required*, string): A string representing the group name which is displayed as the header of the group + - **sorting_weight** (*Optional*, float) A float representing the weight of the group. A group with a smaler ``sorting_weight`` will be displayed first. Defaults to ``50`` To conserve flash size, the CSS and JS files used on the root page to show a simple user interface are hosted by esphome.io. If you want to use your own service, use the @@ -149,6 +154,68 @@ Copy https://oi.esphome.io/v2/www.js to a V2 folder in your yaml folder. Version 3 features --------------------------- + +.. _config-webserver-sorting: + +Entity sorting +************** + +Version `3` supports the sorting of the entities. +You can set a ``sorting_weight`` on each entity. +Smaller numbers will be displayed first, defaults to 50. +``My Sensor 2`` is displayed before ``My Sensor 1`` + +Example configuration: + +.. code-block:: yaml + + sensor: + - platform: template + name: "My Sensor 1" + web_server: + sorting_weight: 10 + - platform: template + name: "My Sensor 2" + web_server: + sorting_weight: -1 + + +.. _config-webserver-grouping: + +Entity grouping +*************** + +Version `3` of the ``web_server`` allows for grouping of entities in custom groups. +Groups can be sorted by providing a ``sorting_weight``. Groups with a smaller ``sorting_weight`` will be displayed first. +If you don't provide a ``web_server_sorting_group`` on the component, the ``entity_category`` will be used as the group. + +Example configuration: + +.. code-block:: yaml + + web_server: + version: 3 + sorting_groups: + - id: sorting_group_time_settings + name: "Time Settings" + sorting_weight: 10 + - id: sorting_group_number_settings + name: "Number settings" + sorting_weight: 20 + + datetime: + - platform: template + ... + web_server: + sorting_group_id: sorting_group_time_settings + + number: + - platform: template + ... + web_server: + sorting_group_id: sorting_group_number_settings + + Number in slider mode ********************* .. figure:: /components/images/web_server/number-slider-popup.png @@ -196,27 +263,6 @@ Sensor value graph By clicking on any sensor it will expand a graph with the historical values for that sensor. -.. _config-webserver-sorting: - -Entity sorting --------------- - -``web_server`` version 3 supports the sorting of the entitys. -You can set a ``web_server_sorting_weight`` on each entity. -Smaller numbers will be displayed first, defaults to 50. -Example ``sensor`` configuration. -``My Sensor 2`` is displayed first, then ``My Sensor 1`` - -.. code-block:: yaml - - sensor: - - platform: template - name: "My Sensor 1" - web_server_sorting_weight: 10 - - platform: template - name: "My Sensor 2" - web_server_sorting_weight: -1 - See Also -------- diff --git a/conf.py b/conf.py index 2b343ebbfd..e580399fd2 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2024.9" +version = "2024.11" # The full version, including alpha/beta/rc tags. -release = "2024.9.2" +release = "2024.11.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/supporters.rst b/guides/supporters.rst index 54642c4aef..fde1b7397f 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -37,6 +37,7 @@ Contributors - `Aaron Gamble (@aarongamble) `__ - `Aaron S. Jackson (@AaronJackson) `__ - `Abel Matser (@abelmatser) `__ +- `Rasmus Abildgren (@Abildgren) `__ - `Abílio Costa (@abmantis) `__ - `Antonio (@acarvajalperez) `__ - `Angel Cascarino (@ACascarino) `__ @@ -174,6 +175,7 @@ Contributors - `Florian Mösch (@badbadc0ffee) `__ - `Baden (@baden03) `__ - `Marco Tombesi (@baggior) `__ +- `Ken Baker (@bakerkj) `__ - `balk77 (@balk77) `__ - `Paulus Schoutsen (@balloob) `__ - `Andrew Zaborowski (@balrog-kun) `__ @@ -517,6 +519,7 @@ Contributors - `Drzony (@drzony) `__ - `Dmitry Savinkin (@dsavinkin) `__ - `Dmitrii Shcherbakov (@dshcherb) `__ +- `Dan Slatford (@dslatford) `__ - `Daniel Müller (@dtmuller) `__ - `Tom Soer (@dtx3k) `__ - `dubit0 (@dubit0) `__ @@ -973,6 +976,7 @@ Contributors - `Keith Burzinski (@kbx81) `__ - `Ken Piper (@Kealper) `__ - `kecajtop (@kecajtop) `__ +- `keczejo (@keczejo) `__ - `keithm-xmos (@keithm-xmos) `__ - `Tom Keller (@kellertk) `__ - `Kelvie Wong (@kelvie) `__ @@ -1046,6 +1050,7 @@ Contributors - `Laszlo Gazdag (@lazlyhu) `__ - `Ludovic BOUÉ (@lboue) `__ - `lcavalli (@lcavalli) `__ +- `Luis del Valle (@ldelvalleh) `__ - `Craig Fletcher (@leakypixel) `__ - `Dominik Wagenknecht (@LeDominik) `__ - `leejoow (@leejoow) `__ @@ -1176,6 +1181,7 @@ Contributors - `Michael Banther (@mbanth) `__ - `mbo18 (@mbo18) `__ - `Jack McCrea (@McCrea) `__ +- `mcflypl (@mcflypl) `__ - `mckaymatthew (@mckaymatthew) `__ - `mcmuller (@mcmuller) `__ - `Miguel Diaz Gonçalves (@mdiazgoncalves) `__ @@ -1436,6 +1442,7 @@ Contributors - `Peter Kieser (@pfak) `__ - `Lee (@phatone007) `__ - `Philippe Delodder (@phdelodder) `__ +- `Pat Hermens (@PHeonix25) `__ - `Philipp Helo Rehs (@Phhere) `__ - `philbowers (@philbowers) `__ - `Philippe FOUQUET (@Philippe12) `__ @@ -1691,6 +1698,7 @@ Contributors - `square99 (@square99) `__ - `Paul Krischer (@SqyD) `__ - `sredfern (@sredfern) `__ +- `sredni (@sredni) `__ - `srg74 (@srg74) `__ - `Samuel Sieb (@ssieb) `__ - `Stefan Staub (@sstaub) `__ @@ -1880,6 +1888,7 @@ Contributors - `Vicent Climent (@vcliment89) `__ - `Veli Veromann (@velijv) `__ - `André Lademann (@vergissberlin) `__ +- `VersedBook0 (@VersedBook0) `__ - `Víctor Ferrer García (@vicfergar) `__ - `victorclaessen (@victorclaessen) `__ - `Austin (@vidplace7) `__ @@ -1986,4 +1995,4 @@ Contributors - `Christian Zufferey (@zuzu59) `__ - `Zynth-dev (@Zynth-dev) `__ -*This page was last updated October 1, 2024.* +*This page was last updated October 9, 2024.* diff --git a/images/aic3204.svg b/images/aic3204.svg new file mode 100644 index 0000000000..bedb2a8330 --- /dev/null +++ b/images/aic3204.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/audio_dac.svg b/images/audio_dac.svg new file mode 100644 index 0000000000..a01a23a110 --- /dev/null +++ b/images/audio_dac.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/grove-gas-mc-v2.png b/images/grove-gas-mc-v2.png new file mode 100644 index 0000000000..88a7f5a24b Binary files /dev/null and b/images/grove-gas-mc-v2.png differ diff --git a/images/nau7802.jpg b/images/nau7802.jpg new file mode 100644 index 0000000000..fb514f68be Binary files /dev/null and b/images/nau7802.jpg differ diff --git a/images/npi19.jpg b/images/npi19.jpg new file mode 100644 index 0000000000..c2d19be739 Binary files /dev/null and b/images/npi19.jpg differ diff --git a/images/tca9555.svg b/images/tca9555.svg new file mode 100644 index 0000000000..a93732ff39 --- /dev/null +++ b/images/tca9555.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/tem3200.jpg b/images/tem3200.jpg new file mode 100644 index 0000000000..72ae0d72a3 Binary files /dev/null and b/images/tem3200.jpg differ diff --git a/index.rst b/index.rst index 4aa3ba9bea..fbedca5374 100644 --- a/index.rst +++ b/index.rst @@ -280,6 +280,7 @@ I/O Expanders/Multiplexers SN74HC595, components/sn74hc595, sn74hc595.jpg SX1509, components/sx1509, sx1509.jpg TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg + TCA9555, components/tca9555, tca9555.svg WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg XL9535, components/xl9535, xl9535.svg @@ -321,6 +322,7 @@ Air Quality ENS160, components/sensor/ens160, ens160.jpg, CO2 & Air Quality GCJA5, components/sensor/gcja5, gcja5.svg, Particulate GP2Y1010AU0F, components/sensor/gp2y1010au0f, gp2y1010au0f.png, Particulate + Grove Multichannel Gas V2, components/sensor/grove_gas_mc_v2, grove-gas-mc-v2.png, NO2 & CO & Ethanol & Volatile organics HM3301, components/sensor/hm3301, hm3301.jpg, Particulate iAQ-Core, components/sensor/iaqcore, iaqcore.jpg, CO2 & Volatile organics MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature @@ -355,6 +357,7 @@ Analogue CD74HC4067, components/sensor/cd74hc4067, cd74hc4067.jpg, 16-channel analog multiplexer MCP3008, components/sensor/mcp3008, mcp3008.jpg, 8-channel ADC MCP3204 / MCP3208, components/sensor/mcp3204, mcp3204.jpg, 4-channel ADC + NAU7802, components/sensor/nau7802, nau7802.jpg, ADC Resistance, components/sensor/resistance, omega.svg, dark-invert Bluetooth Low Energy (BLE) @@ -480,6 +483,7 @@ Environmental MPL3115A2, components/sensor/mpl3115a2, mpl3115a2.jpg, Temperature & Pressure MS5611, components/sensor/ms5611, ms5611.jpg, Pressure MS8607, components/sensor/ms8607, ms8607.jpg, Temperature & Humidity & Pressure + NPI-19, components/sensor/npi19, npi19.jpg, Pressure NTC Thermistor, components/sensor/ntc, ntc.jpg, Temperature PMWCS3, components/sensor/pmwcs3, pmwcs3.jpg, Soil moisture & Temperature QMP6988, components/sensor/qmp6988, qmp6988_env3.png, Temperature & Pressure @@ -495,6 +499,7 @@ Environmental SMT100, components/sensor/smt100, smt100.jpg, Moisture & Temperature STS3X, components/sensor/sts3x, sts3x.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 TMP1075, components/sensor/tmp1075, tmp1075.jpg, Temperature TMP117, components/sensor/tmp117, tmp117.jpg, Temperature @@ -1005,6 +1010,14 @@ Lock Components Template Lock, components/lock/template, description.svg, dark-invert Generic Output Lock, components/lock/output, upload.svg, dark-invert +Audio DAC Components +-------------------- + +.. imgtable:: + + Audio DAC Core, components/audio_dac/index, audio_dac.svg + AIC3204, components/audio_dac/aic3204, aic3204.svg + Media Player Components -----------------------