esphome · jesserockz · Feb 12, 2025 · Dec 11, 2024 · Dec 11, 2024 · Dec 15, 2024
diff --git 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.12.4
+PROJECT_NUMBER         = 2025.2.0b1
 
 # 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
@@ -1,5 +1,5 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2024.12.4
+ESPHOME_REF = 2025.2.0b1
 PAGEFIND_VERSION=1.1.1
 PAGEFIND=pagefind
 NET_PAGEFIND=../pagefindbin/pagefind

diff --git a/_redirects b/_redirects
@@ -14,6 +14,20 @@
 /components/sensor/mmc5063.html /components/sensor/mmc5603.html 301
 /components/sensor/kalman_combinator.html /components/sensor/combination.html 301
 
+/components/binary_sensor/custom* /guides/contributing#a-note-about-custom-components 301
+/components/climate/custom* /guides/contributing#a-note-about-custom-components 301
+/components/cover/custom* /guides/contributing#a-note-about-custom-components 301
+/components/light/custom* /guides/contributing#a-note-about-custom-components 301
+/components/output/custom* /guides/contributing#a-note-about-custom-components 301
+/components/sensor/custom* /guides/contributing#a-note-about-custom-components 301
+/components/switch/custom* /guides/contributing#a-note-about-custom-components 301
+/components/text_sensor/custom* /guides/contributing#a-note-about-custom-components 301
+/custom/custom_component* /guides/contributing#a-note-about-custom-components 301
+/custom/i2c* /guides/contributing#a-note-about-custom-components 301
+/custom/index* /guides/contributing#a-note-about-custom-components 301
+/custom/spi* /guides/contributing#a-note-about-custom-components 301
+/custom/uart* /guides/contributing#a-note-about-custom-components 301
+
 /cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301
 /cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301
 /cookbook/relay.html https://devices.esphome.io/devices/Generic-Relay 301

diff --git a/_static/changelog-2025.2.0.png b/_static/changelog-2025.2.0.png
diff --git a/_static/version b/_static/version
@@ -1 +1 @@
-2024.12.4
+2025.2.0b1
diff --git a/automations/all_actions.rst b/automations/all_actions.rst
@@ -32,10 +32,12 @@
 - **logger:** ``log``
 - **max6956:** ``set_brightness_global``, ``set_brightness_mode``
 - **media_player:** ``pause``, ``play``, ``play_media``, ``stop``, ``toggle``, ``volume_down``, ``volume_set``, ``volume_up``
+- **media_player.speaker:** ``play_on_device_media_file``
 - **mhz19:** ``abc_disable``, ``abc_enable``, ``calibrate_zero``
 - **micro_wake_word:** ``start``, ``stop``
 - **microphone:** ``capture``, ``stop_capture``
 - **midea_ac:** ``beeper_off``, ``beeper_on``, ``display_toggle``, ``follow_me``, ``power_off``, ``power_on``, ``power_toggle``, ``swing_step``
+- **mixer_speaker:** ``apply_ducking``
 - **mqtt:** ``publish``, ``publish_json``
 - **number:** ``decrement``, ``increment``, ``operation``, ``set``, ``to_max``, ``to_min``
 - **output:** ``set_level``, ``turn_off``, ``turn_on``

diff --git a/changelog/2025.2.0.rst b/changelog/2025.2.0.rst
diff --git a/changelog/index.rst b/changelog/index.rst
@@ -2,7 +2,7 @@ Changelog
 =========
 
 .. redirect::
-    :url: /changelog/2024.12.0.html
+    :url: /changelog/2025.2.0.html
 
 .. toctree::
     :glob:

diff --git a/changelog/v1.14.0.rst b/changelog/v1.14.0.rst
@@ -276,7 +276,7 @@ Notable Changes & New Features
   generated using automated scripts. This is a big step towards making the API more flexible, for
   example cross-device communication (:esphomepr:`633`).
 - New class :apiclass:`api::CustomAPIDevice` to declare user-defined services straight from custom components.
-  See the updated :doc:`custom component guide </custom/custom_component>`.
+  See the updated custom component guide.
 - :ref:`Sensors <config-sensor>` have a new ``force_update`` option (:esphomepr:`783`).
 - Add GPIO Switch :ref:`interlock_wait_time <switch-gpio-interlocking>` (:esphomepr:`777`).
 - Add a configurable priority for WiFi network selection (:esphomepr:`658`, :doc:`docs </components/wifi>`).

diff --git a/components/animation.rst b/components/animation.rst
@@ -12,6 +12,7 @@ It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_
       - file: "animation.gif"
         id: my_animation
         resize: 100x100
+        type: RGB565
 
 The animation can be rendered just like the image component with the ``image()`` function of the display component.
 
@@ -50,18 +51,15 @@ Configuration variables:
   in your display code.
 - **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT``
   and preserve the aspect ratio.
-- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``.
+- **type** (**Required**): Specifies how to encode image internally. See the :ref:`image component <display-image>` for more information.
 
   - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
-    per pixel, 8 pixels per byte.
-  - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
-    will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
+    per pixel, 8 pixels per byte. Only ``chroma_key`` transparency is available.
   - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
-  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
-  - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
-  - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
+  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel, 3 with an alpha channel.
+  - ``RGB``: Full RGB color stored. Uses 3 bytes per pixel, 4 with an alpha channel.
 
-- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
+- **transparency** (*Optional*): If set the alpha channel of the input image will be taken into account. The possible values are ``opaque`` (default), ``chroma_key`` and ``alpha_channel``. See discussion on transparency in the :ref:`image component <display-image>`.
 - **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over.
 
   - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation.
@@ -83,4 +81,3 @@ Actions:
 
   - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
   - **frame** (**Required**, int): The frame index to show next.
-
diff --git a/components/api.rst b/components/api.rst
@@ -295,6 +295,8 @@ if logs are shown remotely.
         then:
           - logger.log: API is connected!
 
+The lambda equivalent for this is ``id(api_id).is_connected()``.
+
 .. _api-device-actions:
 
 User-defined Actions

diff --git a/components/audio_adc/es7210.rst b/components/audio_adc/es7210.rst
@@ -0,0 +1,73 @@
+ES7210
+======
+
+.. seo::
+    :description: Instructions for using ESPHome's ES7210 platform to configure microphone inputs.
+    :image: es7210.svg
+    :keywords: ES7210, Audio, ADC, I2S, ESP32
+
+The ``es7210`` platform allows your ESPHome devices to use the ES7210 high performance four channel audio ADC
+(`datasheet <http://www.everest-semi.com/pdf/ES7210%20PB.pdf>`__).
+This allows attached microphones to be used as a microphone input via :doc:`/components/microphone/i2s_audio`.
+
+The :ref:`I²C bus <i2c>` is required in your configuration as this is used to communicate with the ES7210.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    audio_adc:
+      - platform: es7210
+
+.. _config-es7210:
+
+Configuration variables:
+------------------------
+
+- **bits_per_sample** (*Optional*, enum): The bit depth of the audio samples. One of ``16bit``, ``24bit`` or ``32bit``.
+  Defaults to ``16bit``.
+- **mic_gain** (*Optional*, enum): The gain applied to the ADC microphones. One of ``0DB``, ``3DB``, ``6DB``, ``9DB``,
+  ``12DB``, ``15DB``, ``18DB``, ``21DB``, ``24DB``, ``27DB``, ``30DB``, ``33DB``, ``34.5DB``, ``36DB``, or ``37.5DB``.
+  Defaults to ``24DB``.
+- **sample_rate** (*Optional*, positive integer): I2S sample rate. Defaults to ``16000``.
+- **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x40``.
+- **i2c_id** (*Optional*): The ID of the :ref:`I²C bus <i2c>` the ES7210 is connected to.
+- All other options from :ref:`Audio ADC <config-audio_adc>`.
+
+Automations
+-----------
+
+All :ref:`Audio ADC Automations <automations-audio_adc>` are supported by this platform.
+
+Configuration Examples
+----------------------
+
+**ESP32 S3 Box 3**:
+
+.. code-block:: yaml
+
+    audio_adc:
+      - platform: es7210
+        id: es7210_adc
+        bits_per_sample: 16bit
+        sample_rate: 16000
+
+    i2s_audio:
+      - id: i2s_audio_bus
+        i2s_lrclk_pin: GPIO45
+        i2s_bclk_pin: GPIO17
+        i2s_mclk_pin: GPIO2
+
+    microphone:
+      - platform: i2s_audio
+        id: box_mic
+        sample_rate: 16000
+        i2s_din_pin: GPIO16
+        bits_per_sample: 16bit
+        adc_type: external
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`es7210/es7210.h`
+- :ghedit:`Edit`
diff --git a/components/audio_adc/es7243e.rst b/components/audio_adc/es7243e.rst
@@ -0,0 +1,68 @@
+ES7243E
+=======
+
+.. seo::
+    :description: Instructions for using ESPHome's ES7243E platform to configure microphone inputs.
+    :image: es7243e.svg
+    :keywords: ES7243E, Audio, ADC, I2S, ESP32
+
+The ``es7243e`` platform allows your ESPHome devices to use the ES7243E high performance four channel audio ADC
+(`datasheet <https://www.lcsc.com/datasheet/lcsc_datasheet_2410121611_Everest-semi-Everest-Semiconductor-ES7243E_C2929446.pdf>`__).
+This allows attached microphones to be used as a microphone input via :doc:`/components/microphone/i2s_audio`.
+
+The :ref:`I²C bus <i2c>` is required in your configuration as this is used to communicate with the ES7243e.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    audio_adc:
+      - platform: es7243e
+
+.. _config-es7243e:
+
+Configuration variables:
+------------------------
+
+- **mic_gain** (*Optional*, enum): The gain applied to the ADC microphones. One of ``0DB``, ``3DB``, ``6DB``, ``9DB``,
+  ``12DB``, ``15DB``, ``18DB``, ``21DB``, ``24DB``, ``27DB``, ``30DB``, ``33DB``, ``34.5DB``, ``36DB``, or ``37.5DB``.
+  Defaults to ``24DB``.
+- **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x40``.
+- **i2c_id** (*Optional*): The ID of the :ref:`I²C bus <i2c>` the ES7243e is connected to.
+- All other options from :ref:`Audio ADC <config-audio_adc>`.
+
+Automations
+-----------
+
+All :ref:`Audio ADC Automations <automations-audio_adc>` are supported by this platform.
+
+Configuration Examples
+----------------------
+
+**ESP32 S3 Box Lite**:
+
+.. code-block:: yaml
+
+    audio_adc:
+      - platform: es7243e
+        id: es7243e_adc
+
+    i2s_audio:
+      - id: i2s_audio_bus
+        i2s_lrclk_pin: GPIO47
+        i2s_bclk_pin: GPIO17
+        i2s_mclk_pin: GPIO2
+
+    microphone:
+      - platform: i2s_audio
+        id: box_mic
+        sample_rate: 16000
+        i2s_din_pin: GPIO16
+        bits_per_sample: 16bit
+        adc_type: external
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`es7243e/es7243e.h`
+- :ghedit:`Edit`
diff --git a/components/audio_adc/index.rst b/components/audio_adc/index.rst
@@ -0,0 +1,53 @@
+Audio ADC Core
+==============
+
+.. seo::
+    :description: Instructions for using ESPHome's Audio ADC Core component.
+    :image: i2s_audio.svg
+    :keywords: Audio, ADC, I2S, ESP32
+
+The `audio_adc` component allows your ESPHome devices to use audio ADC hardware components, allowing the
+capture/recording of audio via the microcontroller from a range of sources.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    audio_adc:
+      - platform: ...
+
+Platforms
+---------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+
+.. _config-audio_adc:
+
+Configuration variables:
+------------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+
+.. _automations-audio_adc:
+
+Automations
+-----------
+
+``audio_adc.set_mic_gain`` Action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This action sets the (microphone) gain of the ADC.
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the ``audio_adc`` platform.
+- **mic_gain** (**Required**, percentage, :ref:`templatable <config-templatable>`): The desired gain level in decibels
+  for the input.
+
+See Also
+--------
+
+- :ghedit:`Edit`
diff --git a/components/audio_dac/es8156.rst b/components/audio_dac/es8156.rst
@@ -0,0 +1,75 @@
+ES8156
+======
+
+.. seo::
+    :description: Instructions for using ESPHome's ES8156 audio DAC platform to play media from your devices.
+    :image: es8156.svg
+    :keywords: ES8156, Audio, DAC, I2S, ESP32
+
+The ``es8156`` platform allows your ESPHome devices to use the ES8156 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 ES8156.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    audio_dac:
+      - platform: es8156
+
+.. _config-es8156:
+
+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 <i2c>` the ES8156 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 Lite**:
+
+.. code-block:: yaml
+
+    audio_dac:
+      - platform: es8156
+        id: es8156_dac
+
+    i2s_audio:
+      - id: i2s_output
+        i2s_lrclk_pin: GPIO47
+        i2s_bclk_pin: GPIO17
+        i2s_mclk_pin: GPIO2
+
+    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: es8156_dac
+
+    switch:
+      - platform: gpio
+        name: "Speaker Enable"
+        pin: GPIO46
+        restore_mode: RESTORE_DEFAULT_ON
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`es8156/es8156.h`
+- :apiref:`audio_dac/audio_dac.h`
+- :ghedit:`Edit`