2024.11.0

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

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

_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

_static/version

@@ -1 +1 @@
-2024.10.3
+2024.11.0

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 <config-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 <config-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 <config-condition>`): Takes a list of conditions, all of which must be true (and is therefore equivalent to ``condition``.)
+- **any** (*Optional*, :ref:`Condition <config-condition>`): Takes a list of conditions; if at least one is true, the condition will be true.
 - **then** (*Optional*, :ref:`Action <config-action>`): The action to perform if the condition evaluates to true.
   Defaults to doing nothing.
 - **else** (*Optional*, :ref:`Action <config-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:
 

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

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

changelog/index.rst

@@ -2,7 +2,7 @@ Changelog
 =========
 
 .. redirect::
-    :url: /changelog/2024.10.0.html
+    :url: /changelog/2024.11.0.html
 
 .. toctree::
     :glob:

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/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);

components/display/qspi_amoled.rst → 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 <config-pin_schema>`): The chip select pin.
 - **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin.
 - **enable_pin** (*Optional*, :ref:`Pin Schema <config-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 <config-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`

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