Merge branch 'next' into waveshare-bwr

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``

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 <i2c>` 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 <i2c>` the ES8311 is connected to.
+- All other options from :ref:`Audio DAC <config-audio_dac>`.
+
+Automations
+-----------
+
+All :ref:`Audio DAC Automations <automations-audio_dac>` 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`

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:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 <https://github.com/googlefonts/glyphsets/blob/main/GLYPHSETS.md>`_
+  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.
@@ -159,4 +186,5 @@ See Also
 - :doc:`/components/lvgl/index`
 - `MDI cheatsheet <https://pictogrammers.com/library/mdi/>`_
 - `MDI font repository <https://github.com/Pictogrammers/pictogrammers.github.io/tree/main/%40mdi/font/>`_
+- `Google Fonts Glyphsets <https://github.com/googlefonts/glyphsets/blob/main/GLYPHSETS.md>`_
 - :ghedit:`Edit`

components/http_request.rst

@@ -105,6 +105,7 @@ This :ref:`action <config-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 <automation>`): An automation to perform after the request is received.
+- **on_error** (*Optional*, :ref:`Automation <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 <config-lambda>`:
 - ``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 <config-lambda>`:
                       - 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 <config-lambda>`. See example usage above.
 
 
 .. _http_request-examples:
@@ -261,11 +281,19 @@ whose ``id`` is  set to ``player_volume``:
         capture_response: true
         on_response:
           then:
-            - lambda: |-
-                json::parse_json(body, [](JsonObject root) -> bool {
-                    id(player_volume).publish_state(root["vol"]);
-                    return true;
-                });
+            - if:
+                condition:
+                    lambda: return response->status_code == 200;
+                then:
+                    - lambda: |-
+                        json::parse_json(body, [](JsonObject root) -> bool {
+                            id(player_volume).publish_state(root["vol"]);
+                            return true;
+                        });
+                else:
+                    - logger.log:
+                        format: "Error: Response status: %d, message %s"
+                        args: [response->status_code, body.c_str()];
 
 
 See Also

components/lvgl/widgets.rst

@@ -1248,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 <lvgl-color>`): Color for the light areas of the QR. Defaults to white.
+- **dark_color** (*Optional*, :ref:`color <lvgl-color>`): Color for the dark areas of the QR. Defaults to black.
+- Style options from :ref:`lvgl-styling`.
+
+**Actions:**
+
+- ``lvgl.qrcode.update`` :ref:`action <actions-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-automation-triggers>` 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``

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.
@@ -733,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