Merge branch 'next' into qesan

2024-05-07 18:31:13 +00:00 · 2024-05-07 18:31:13 +00:00 · 0940a79a11
parent e1d4aafb80 696a828156
commit 0940a79a11
241 changed files with 2865 additions and 2157 deletions
--- a/21
+++ b/21
@ -1,4 +1,4 @@
-FROM python:3.8-slim
+FROM python:3.12-slim

 RUN apt-get update && apt-get install -y --no-install-recommends \
        curl \
@ -9,10 +9,25 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
        software-properties-common \
        && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*

-COPY requirements.txt .
+RUN useradd -ms /bin/bash esphome
+
+USER esphome
+
+WORKDIR /workspaces/esphome-docs
+ENV PATH="${PATH}:/home/esphome/.local/bin"
+
+COPY requirements.txt ./
 RUN pip3 install --no-cache-dir --no-binary :all: -r requirements.txt

 EXPOSE 8000
-WORKDIR /data/esphomedocs

 CMD ["make", "live-html"]
+
+LABEL \
+        org.opencontainers.image.title="esphome-docs" \
+        org.opencontainers.image.description="An image to help with ESPHomes documentation development" \
+        org.opencontainers.image.vendor="ESPHome" \
+        org.opencontainers.image.licenses="CC BY-NC-SA 4.0" \
+        org.opencontainers.image.url="https://esphome.io" \
+        org.opencontainers.image.source="https://github.com/esphome/esphome-docs" \
+        org.opencontainers.image.documentation="https://github.com/esphome/esphome-docs/blob/current/README.md"
--- a/2
+++ b/2
@ -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.4.0
+PROJECT_NUMBER         = 2024.4.2

 # 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
--- a/2
+++ b/2
@ -1,5 +1,5 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2024.4.0
+ESPHOME_REF = 2024.4.2

 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify

--- a/_static/custom.css
+++ b/_static/custom.css
@ -240,6 +240,11 @@ a:hover code {
  background: none;
 }

+/* don't underline links that contain an image and nothing else */
+a:has(> img:only-child) {
+  border-bottom: none;
+}
+
 div.body p, div.body dd, div.body li, div.body blockquote {
  hyphens: none;
 }
--- a/_static/version
+++ b/_static/version
@ -1 +1 @@
-2024.4.0
+2024.4.2
--- a/_templates/layout.html
+++ b/_templates/layout.html
@ -16,6 +16,7 @@
  <link rel="icon" type="image/png" sizes="16x16" href="/_static/favicon-16x16.png">
  <link rel="manifest" href="/_static/site.webmanifest">
  <link rel="mask-icon" href="/_static/safari-pinned-tab.svg" color="#646464">
+  <link rel="me" href="https://fosstodon.org/@esphome">
  <meta name="apple-mobile-web-app-title" content="ESPHome">
  <meta name="application-name" content="ESPHome">
  <meta name="msapplication-TileColor" content="#dfdfdf">
--- a/changelog/2023.12.0.rst
+++ b/changelog/2023.12.0.rst
@ -14,7 +14,7 @@ ESPHome 2023.12.0 - 20th December 2023
    GT911, components/touchscreen/gt911, esp32_s3_box_3.png
    Pylontech Batteries, components/pylontech, pylontech.jpg
    HE60R Cover, components/cover/he60r, he60r.jpg
-    Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.jpg
+    Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png
    FT63X6, components/touchscreen/ft63x6, wt32-sc01.png
    A02YYUW, components/sensor/a02yyuw, a02yyuw.jpg
    PN7150, components/binary_sensor/pn7150, pn7150.jpg
--- a/changelog/2024.4.0.rst
+++ b/changelog/2024.4.0.rst
@ -38,6 +38,27 @@ use that route instead. This is more reliable because the ESPHome API uses a TCP
 your audio will also be encrypted in transit.


+Release 2024.4.1 - April 23
+---------------------------
+
+- [Tuya Climate] Fix compilation error caused by codegen :esphomepr:`6568` by :ghuser:`zry98`
+- wifi: fix reconnect issue due to enablement of fast connect :esphomepr:`6598` by :ghuser:`jpeletier`
+- Calibrate Beken internal temperature :esphomepr:`6599` by :ghuser:`Mat931`
+- fix streaming logs from MQTT for ESP32 devices using TLS :esphomepr:`6605` by :ghuser:`ccutrer`
+- Disallow variant/family override for known boards :esphomepr:`6512` by :ghuser:`clydebarrow`
+- esp32_ble: Consider ESP_BT_STATUS_DONE a successful state :esphomepr:`6493` by :ghuser:`polyfloyd`
+- Fix or filter :esphomepr:`6574` by :ghuser:`swoboda1337`
+
+
+Release 2024.4.2 - April 30
+---------------------------
+
+- Fix SHT3xd fails sometimes in 2024.4.0 :esphomepr:`6592` by :ghuser:`mrtoy-me`
+- allow defaults with no include vars :esphomepr:`6613` by :ghuser:`ssieb`
+- Revert #6458 :esphomepr:`6650` by :ghuser:`tronikos`
+- [i2s_audio.microphone] Fixing adc bug :esphomepr:`6654` by :ghuser:`jesserockz`
+
+
 Full list of changes
 --------------------

--- a/components/alarm_control_panel/template.rst
+++ b/components/alarm_control_panel/template.rst
@ -169,7 +169,7 @@ Example:
        name: Zone 1
        device_class: door
        pin:
-          number: D1
+          number: GPIOXX
          mode: INPUT_PULLUP
          inverted: True
      - platform: gpio
@ -177,7 +177,7 @@ Example:
        name: Zone 2
        device_class: door
        pin:
-          number: D2
+          number: GPIOXX
          mode: INPUT_PULLUP
          inverted: True
      - platform: gpio
@ -185,7 +185,7 @@ Example:
        name: Zone 3
        device_class: motion
        pin:
-          number: D3
+          number: GPIOXX
          mode: INPUT_PULLUP
          inverted: True
      - platform: gpio
@ -193,7 +193,7 @@ Example:
        name: Zone 4
        device_class: door
        pin:
-          number: D4
+          number: GPIOXX
          mode: INPUT_PULLUP
          inverted: True
      - platform: homeassistant
@ -206,7 +206,7 @@ Example:
        id: siren
        name: Siren
        icon: mdi:alarm-bell
-        pin: D7
+        pin: GPIOXX


 See Also
--- a/components/api.rst
+++ b/components/api.rst
@ -75,20 +75,35 @@ Configuration variables:

 .. _api-actions:

-.. note::
-
-    Before a newly added ESPHome device can interact with the Home Assistant API it needs to be allowed to communicate
-    with it. This setting can be found in the ESPHome integration (NOT in the Add-On) by clicking "CONFIGURE" for
-    that device and enabling the "Allow device to make service calls" option.
-
 Actions
 -------

+Before using any of the actions below, you'll need to tell Home Assistant to allow your device to
+make service calls.
+
+Open the ESPHome integration page on your Home Assistant instance:
+
+.. raw:: html
+
+    <a href="https://my.home-assistant.io/redirect/integration/?domain=esphome" target="_blank" rel="noreferrer noopener"><img src="https://my.home-assistant.io/badges/integration.svg" alt="Open your Home Assistant instance and show an integration." /></a>
+
+Then:
+
+#. Fnd your device in the device list
+#. Click the "configure" button next to it
+#. Check the "Allow the device to make Home Assistant service calls" box
+#. Then click "submit".
+
 .. _api-homeassistant_event_action:

 ``homeassistant.event`` Action
 ******************************

+.. note::
+
+    Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
+    your device to make service calls.
+
 When using the native API with Home Assistant, you can create events in the Home Assistant event bus
 straight from ESPHome :ref:`Automations <automation>`.

@ -117,6 +132,11 @@ Configuration variables:
 ``homeassistant.service`` Action
 ********************************

+.. note::
+
+    Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
+    your device to make service calls.
+
 When using the native API with Home Assistant, you can create Home Assistant service
 calls straight from ESPHome :ref:`Automations <automation>`.

@ -189,6 +209,11 @@ Then, in ESPHome:
 ``homeassistant.tag_scanned`` Action
 ************************************

+.. note::
+
+    Be sure to :ref:`follow the instructions above <api-actions>` to tell Home Assistant to allow
+    your device to make service calls.
+
 When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
 straight from ESPHome :ref:`Automations <automation>`.

--- a/components/at581x.rst
+++ b/components/at581x.rst
@ -32,17 +32,6 @@ a :doc:`/components/i2c` component (and its requisite GPIO pins) is required in
      id: "Radar"
      i2c_id: bus_a

-    binary_sensor:
-      - platform: gpio
-        pin: GPIO21
-        name: "Radar motion"
-
-    switch:
-      # Switch to turn on/off RF emission
-      - platform: at581x
-        at581x_id: "Radar"
-        name: "Enable Radar"
-
 .. _at581x-component:

 Component/Hub
@ -87,7 +76,7 @@ The state of the radar detection is available via its GPIO pin. It's required to
    binary_sensor:
      - platform: gpio
        name: "Human in front"
-        pin: GPIO21
+        pin: GPIOXX

 Configuration variables:
 ************************
--- a/components/binary_sensor/cap1188.rst
+++ b/components/binary_sensor/cap1188.rst
@ -30,7 +30,7 @@ required to be set up in your configuration for this sensor to work.
    cap1188:
      id: cap1188_component
      address: 0x29
-      reset_pin: 14
+      reset_pin: GPIOXX
      touch_threshold: 0x40
      allow_multiple_touches: true

--- a/components/binary_sensor/custom.rst
+++ b/components/binary_sensor/custom.rst
@ -1,22 +1,28 @@
 Custom Binary Sensor
 ====================

+.. seo::
+    :description: Instructions for setting up Custom C++ binary sensors with ESPHome.
+    :image: language-cpp.svg
+    :keywords: C++, Custom
+
 .. warning::

-    Custom components are deprecated, not recommended for new configurations
-    and will be removed from ESPHome in a future release.
-    Please look at creating a real ESPHome component and "importing" it into your
-    configuration with :doc:`/components/external_components`.
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+    :doc:`/components/external_components`.

-    You can find some basic documentation on creating your own components
-    at :ref:`contributing_to_esphome`.
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

-This integration can be used to create custom binary sensors in ESPHome
-using the C++ (Arduino) API.
+.. warning::

-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here and binary sensors are very similar
-to sensors internally.
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom binary sensors in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here and binary
+sensors are very similar to sensors internally.

 The example below is an example of a custom binary sensor; this custom sensor is essentially the
 same as the gpio binary sensor.
--- a/components/binary_sensor/esp32_touch.rst
+++ b/components/binary_sensor/esp32_touch.rst
@ -130,8 +130,8 @@ an ``OFF`` state.

    binary_sensor:
      - platform: esp32_touch
-        name: "ESP32 Touch Pad GPIO27"
-        pin: GPIO27
+        name: "ESP32 Touch Pad"
+        pin: GPIOXX
        threshold: 1000

 Configuration variables:
@ -164,7 +164,7 @@ If access to the raw values is required, a template sensor can be created that p
    binary_sensor:
      - platform: esp32_touch
        id: esp32_touch_pad
-        pin: GPIO4
+        pin: GPIOXX
        threshold: 0

    sensor:
--- a/components/binary_sensor/haier.rst
+++ b/components/binary_sensor/haier.rst
@ -17,8 +17,8 @@ Additional sensors for Haier Climate device. **These sensors are supported only
    # Example configuration entry
    uart:
      baud_rate: 9600
-      tx_pin: 17
-      rx_pin: 16
+      tx_pin: GPIOXX
+      rx_pin: GPIOXX
      id: ac_port

    climate:
--- a/components/binary_sensor/homeassistant.rst
+++ b/components/binary_sensor/homeassistant.rst
@ -34,7 +34,6 @@ Configuration variables:
 - **entity_id** (**Required**, string): The entity ID to import from Home Assistant.
 - **attribute** (*Optional*, string): The name of the state attribute to import from the
  specified entity. The entity state is used when this option is omitted.
-  Requires Home Assistant 2021.6 or newer.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - All other options from :ref:`Binary Sensor <config-binary_sensor>`.

--- a/components/binary_sensor/hydreon_rgxx.rst
+++ b/components/binary_sensor/hydreon_rgxx.rst
@ -12,12 +12,6 @@ For this sensor to work, a :doc:`/components/sensor/hydreon_rgxx` must be set up
 .. code-block:: yaml

    # Example RG-9 entry
-
-    uart:
-      rx_pin: GPIO16
-      tx_pin: GPIO17
-      baud_rate: 9600
-
    sensor:
      - platform: hydreon_rgxx
        model: "RG_9"
--- a/components/binary_sensor/index.rst
+++ b/components/binary_sensor/index.rst
@ -66,12 +66,12 @@ Advanced options:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  Defaults to ``false``.
 - **publish_initial_state** (*Optional*, boolean): If true, then the sensor will publish its initial state at boot or when
  HA first connects, depending on the platform.  This means that any applicable triggers will be run. 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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.
 - If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.

--- a/components/binary_sensor/rc522.rst
+++ b/components/binary_sensor/rc522.rst
@ -42,7 +42,7 @@ you can then create individual binary sensors that track if an NFC/RFID tag is c
    spi:

    rc522_spi:
-      cs_pin: GPIO15
+      cs_pin: GPIOXX

    binary_sensor:
      - platform: rc522
--- a/components/bluetooth_proxy.rst
+++ b/components/bluetooth_proxy.rst
@ -43,15 +43,11 @@ Configuration:

    bluetooth_proxy:

- **active** (*Optional*, boolean): Enables proxying active connections. Defaults to ``false``. Requires Home Assistant 2022.10 or later.
+- **active** (*Optional*, boolean): Enables proxying active connections. Defaults to ``false``.
 - **cache_services** (*Optional*, boolean): Enables caching GATT services in NVS flash storage which significantly speeds up active connections. Defaults to ``true`` when using the ESP-IDF framework.

 The Bluetooth proxy depends on :doc:`esp32_ble_tracker` so make sure to add that to your configuration.

-.. note::
-
-    Bluetooth proxy requires Home Assistant 2022.9 or later. ESPHome 2022.12.0 and Home Assistant 2022.12.6 or later is recommended.
-
 Improving reception performance
 -------------------------------

--- a/components/button/output.rst
+++ b/components/button/output.rst
@ -17,7 +17,7 @@ momentarily set a GPIO pin using a button.
    # Example configuration entry
    output:
      - platform: gpio
-        pin: 25
+        pin: GPIOXX
        id: output1

    button:
--- a/components/button/uart.rst
+++ b/components/button/uart.rst
@ -11,10 +11,6 @@ The ``uart`` button platform allows you to send a pre-defined sequence of bytes
 .. code-block:: yaml

    # Example configuration entry
-    uart:
-      baud_rate: 9600
-      tx_pin: D0
-
    button:
      - platform: uart
        name: "UART String Output"
--- a/components/canbus.rst
+++ b/components/canbus.rst
@ -197,8 +197,8 @@ You only need to specify the RX and TX pins. Any GPIO will work.
    # Example configuration entry
    canbus:
      - platform: esp32_can
-        tx_pin: GPIO5
-        rx_pin: GPIO4
+        tx_pin: GPIOXX
+        rx_pin: GPIOXX
        can_id: 4
        bit_rate: 50kbps
        on_frame:
@ -273,7 +273,7 @@ For wiring up the MSP2515 please refer to the section below.
    # Example configuration entry
    canbus:
      - platform: mcp2515
-        cs_pin: D5
+        cs_pin: GPIOXX
        can_id: 4
        bit_rate: 50kbps
        on_frame:
@ -359,7 +359,7 @@ Standard IDs and Extended IDs can coexist on the same segment.
      - platform: mcp2515
        id: my_mcp2515
        spi_id: McpSpi
-        cs_pin: GPIO14
+        cs_pin: GPIOXX
        can_id: 0x1fff
        use_extended_id: true
        bit_rate: 125kbps
@ -385,9 +385,9 @@ Button is connected on a can node which sends an A message on ID 0x100 with payl

    spi:
      id: McpSpi
-      clk_pin: GPIO16
-      mosi_pin: GPIO5
-      miso_pin: GPIO4
+      clk_pin: GPIOXX
+      mosi_pin: GPIOXX
+      miso_pin: GPIOXX

    binary_sensor:
      - platform: template
@ -398,7 +398,7 @@ Button is connected on a can node which sends an A message on ID 0x100 with payl
      - platform: mcp2515
        id: my_mcp2515
        spi_id: McpSpi
-        cs_pin: GPIO14
+        cs_pin: GPIOXX
        can_id: 4
        bit_rate: 125kbps
        on_frame:
@ -430,15 +430,15 @@ Buttons are connected on the CAN-Node and also the motor is connected via CAN.

    spi:
      id: McpSpi
-      clk_pin: GPIO16
-      mosi_pin: GPIO5
-      miso_pin: GPIO4
+      clk_pin: GPIOXX
+      mosi_pin: GPIOXX
+      miso_pin: GPIOXX

    canbus:
      - platform: mcp2515
        id: my_mcp2515
        spi_id: McpSpi
-        cs_pin: GPIO14
+        cs_pin: GPIOXX
        can_id: 4
        bit_rate: 125kbps
        on_frame:
--- a/components/climate/climate_ir.rst
+++ b/components/climate/climate_ir.rst
@ -76,7 +76,7 @@ controller unit.

    # Example configuration entry
    remote_transmitter:
-      pin: GPIO32
+      pin: GPIOXX
      carrier_duty_percent: 50%

    climate:
@ -156,7 +156,7 @@ IR receiver.
    remote_receiver:
      id: rcvr
      pin:
-        number: GPIO14
+        number: GPIOXX
        inverted: true
        mode:
          input: true
--- a/components/climate/custom.rst
+++ b/components/climate/custom.rst
@ -1,21 +1,27 @@
 Custom Climate
 ==============

+.. seo::
+    :description: Instructions for setting up Custom C++ climate components with ESPHome.
+    :image: language-cpp.svg
+    :keywords: C++, Custom
+
 .. warning::

-    Custom components are deprecated, not recommended for new configurations
-    and will be removed from ESPHome in a future release.
-    Please look at creating a real ESPHome component and "importing" it into your
-    configuration with :doc:`/components/external_components`.
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+    :doc:`/components/external_components`.

-    You can find some basic documentation on creating your own components
-    at :ref:`contributing_to_esphome`.
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

-This integration can be used to create custom climate devices in ESPHome
-using the C++ (Arduino) API.
+.. warning::

-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom climate devices in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.

 The example below is an example of a custom climate device - all climate devices must override
 two methods (:apiclass:`Climate <climate::Climate>`):
--- a/components/climate/haier.rst
+++ b/components/climate/haier.rst
@ -58,13 +58,6 @@ This component requires a :ref:`uart` to be setup.
 .. code-block:: yaml

    # Example configuration entry
-
-    uart:
-      baud_rate: 9600
-      tx_pin: 17
-      rx_pin: 16
-      id: ac_port  
-    
    climate:
      - platform: haier
        id: haier_ac
--- a/components/climate/index.rst
+++ b/components/climate/index.rst
@ -80,10 +80,10 @@ Advanced options:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.

 MQTT options:
--- a/components/climate/midea.rst
+++ b/components/climate/midea.rst
@ -25,17 +25,6 @@ The ``midea`` component creates a Midea air conditioner climate device.
 .. code-block:: yaml

    # Example configuration entry
-
-    # Disable logging over UART (required)
-    logger:
-      baud_rate: 0
-
-    # UART settings for Midea dongle (required)
-    uart:
-      tx_pin: 1         # hardware dependant
-      rx_pin: 3         # hardware dependant
-      baud_rate: 9600
-
    # Main settings
    climate:
      - platform: midea
--- a/components/copy.rst
+++ b/components/copy.rst
@ -1,11 +1,11 @@
-Copy Integration
-================
+Copy Component
+==============

 .. seo::
-    :description: Instructions for setting up the copy integration in ESPHome
+    :description: Instructions for setting up the copy component in ESPHome
    :image: content-copy.svg

-The ``copy`` integration can be used to copy an existing component (like a sensor, switch, etc.)
+The ``copy`` component can be used to copy an existing component (like a sensor, switch, etc.)
 and create a duplicate mirroring the source's state and forwarding actions such as turning on to the source.

 For each of the supported platforms, the configuration consists of the required configuration
--- a/components/cover/custom.rst
+++ b/components/cover/custom.rst
@ -1,24 +1,29 @@
 Custom Cover
 ============

+.. seo::
+    :description: Instructions for setting up Custom C++ covers with ESPHome.
+    :image: language-cpp.svg
+    :keywords: C++, Custom
+
 .. warning::

-    Custom components are deprecated, not recommended for new configurations
-    and will be removed from ESPHome in a future release.
-    Please look at creating a real ESPHome component and "importing" it into your
-    configuration with :doc:`/components/external_components`.
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+    :doc:`/components/external_components`.

-    You can find some basic documentation on creating your own components
-    at :ref:`contributing_to_esphome`.
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

-This integration can be used to create custom covers in ESPHome
-using the C++ (Arduino) API.
+.. warning::

-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.

-The example below is an example of a custom cover - all covers must override
-two methods:
+This component can be used to create custom covers in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
+
+The example below is an example of a custom cover - all covers must override two methods:

 - ``get_traits``: This should return a :apiclass:`CoverTraits <cover::CoverTraits>` object
  representing the capabilities of the cover.
--- a/components/cover/index.rst
+++ b/components/cover/index.rst
@ -46,10 +46,10 @@ Advanced options:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.

 MQTT options:
--- a/components/cover/time_based.rst
+++ b/components/cover/time_based.rst
@ -77,7 +77,22 @@ Configuration variables:
    ``esp8266_restore_from_flash: true`` option set. 
    See :doc:`esp8266_restore_from_flash </components/esphome>` for details.

+Handle stop_action:
+------------------------
+For some cover controllers, separate switches for UP and DOWN action are used while a stop is issued when sending a counter command.
+This can be handled at the **stop_action** by using the folling lamda function:

+.. code-block:: yaml
+
+    stop_action: 
+      - lambda: !lambda |-
+          if (id(cover).last_operation() == CoverOperation::COVER_OPERATION_OPENING) {
+            // Cover is currently opening
+            id(cover_button_down).press();
+          } else if (id(cover).last_operation() == CoverOperation::COVER_OPERATION_CLOSING) {
+            // Cover is currently closing
+            id(cover_button_up).press();
+          }

 See Also
 --------
--- a/components/cover/tuya.rst
+++ b/components/cover/tuya.rst
@ -45,7 +45,7 @@ Configuration variables:
 Supported devices
 -----------------

-Tuya cover devices known to be supported by this integration:
+Tuya cover devices known to be supported by this component:

 - Tuya ``M515EGWT`` (motor for bead chain roller blinds)

--- a/components/datetime/index.rst
+++ b/components/datetime/index.rst
@ -42,22 +42,27 @@ Configuration variables:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.
+- **time_id** (**Required**, :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.

 MQTT Options:

 - All other options from :ref:`MQTT Component <config-mqtt-component>`.

-Datetime Automation
-------------------
+Time and DateTime Options:

-You can access the most recent state as a string of the datetime in :ref:`lambdas <config-lambda>` using
-``id(datetime_id).state``.
-You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time``
+- **on_time** (*Optional*, :ref:`automation`): Automation to run when the current datetime or time matches the current state.
+  Only valid on ``time`` or ``datetime`` types.
+
+Automation
+----------
+
+You can access the most recent state as a ``ESPTime`` object by ``id(datetime_id).state_as_esptime()``

 .. _datetime-on_value:

@ -225,14 +230,94 @@ advanced stuff (see the full API Reference for more info).
      ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_time).second);


+DateTime Automation
+-------------------
+
+.. _datetime-datetime_set_action:
+
+``datetime.datetime.set`` Action
+********************************
+
+This is an :ref:`Action <config-action>` for setting a datetime datetime state.
+The ``datetime`` provided can be in one of 3 formats:
+
+.. code-block:: yaml
+
+    # String datetime
+    - datetime.time.set:
+        id: my_datetime
+        datetime: "2024-12-31 12:34:56"
+
+    # Individual datetime parts
+    - datetime.datetime.set:
+        id: my_datetime
+        datetime:
+          year: 2024
+          month: 12
+          day: 31
+          hour: 12
+          minute: 34
+          second: 56
+
+    # Using a lambda
+    - datetime.datetime.set:
+        id: my_datetime
+        datetime: !lambda |-
+          // Return an ESPTime struct
+          return {.second: 56, .minute: 34, .hour: 12, .day_of_month: 31, .month: 12, .year: 2024};
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the datetime to set.
+- **datetime** (**Required**, string, datetime parts, :ref:`templatable <config-templatable>`):
+  The value to set the datetime to.
+
+
+.. _datetime-datetime-lambda_calls:
+
+Lambda calls
+************
+
+For more complex use cases, several methods are available for use on datetimes from within :ref:`lambdas <config-lambda>`. See the full API Reference for more information.
+
+- ``.make_call()``: Make a call for updating the datetime value.
+
+  .. code-block:: cpp
+
+      // Within lambda, set the datetime to 2024-12-31 12:34:56
+      auto call = id(my_datetime).make_call();
+      call.set_date("2024-12-31 12:34:56");
+      call.perform();
+
+  Check the API reference for information on the methods that are available for
+  the ``DateTimeCall`` object.
+
+- ``.year``: Retrieve the current year of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.month``: Retrieve the current month of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.day``: Retrieve the current day of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.hour``: Retrieve the current hour of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.minute``: Retrieve the current minute of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.second``: Retrieve the current second of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object.
+
+  .. code-block:: cpp
+
+      // For example, create a custom log message when a value is received:
+      ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d %0d:%02d:%02d",
+               id(my_datetime).year, id(my_datetime).month, id(my_datetime).day,
+               id(my_datetime).hour, id(my_datetime).minute, id(my_datetime).second);
+
+
 See Also
 --------

 - :apiref:`DateTimeBase <datetime/datetime_base.h>`
 - :apiref:`DateEntity <datetime/date_entity.h>`
 - :apiref:`DateCall <datetime/date_entity.h>`
- :apiref:`TimeeEntity <datetime/time_entity.h>`
+- :apiref:`TimeEntity <datetime/time_entity.h>`
 - :apiref:`TimeCall <datetime/time_entity.h>`
+- :apiref:`DateTimeEntity <datetime/datetime_entity.h>`
+- :apiref:`DateTimeCall <datetime/datetime_entity.h>`
 - :ghedit:`Edit`

 .. toctree::
--- a/components/datetime/template.rst
+++ b/components/datetime/template.rst
@ -29,6 +29,15 @@ using :ref:`lambdas <config-lambda>`.
        initial_value: "12:34:56"
        restore_value: true

+      # Example DateTime
+      - platform: template
+        id: my_datetime
+        type: datetime
+        name: Pick a DateTime
+        optimistic: yes
+        initial_value: "2024-12-31 12:34:56"
+        restore_value: true
+
 Configuration variables:
 ------------------------

@ -72,6 +81,21 @@ Configuration variables:
          minute: 34
          second: 56

+  - For ``type: datetime``:
+
+    - A string in the format ``%Y-%m-%d %H:%M:%S`` , eg: ``"2023-12-04 12:34:56"``.
+    - An object including ``year``, ``month``, ``day``, ``hour``, ``minute``, ``second``.
+
+    .. code-block:: yaml
+
+        initial_value:
+          year: 2023
+          month: 12
+          day: 4
+          hour: 12
+          minute: 34
+          second: 56
+
 - All other options from :ref:`Datetime <config-datetime>`.

 See Also
--- a/components/demo.rst
+++ b/components/demo.rst
@ -1,12 +1,12 @@
-Demo Integration
-================
+Demo Component
+==============

 .. seo::
-    :description: Instructions for setting up the demo integration in ESPHome
+    :description: Instructions for setting up the demo component in ESPHome
    :image: description.svg

-The ``demo`` integration can be used for testing to generate sample instances of many
-different integrations (sensors, lights, ...)
+The ``demo`` component can be used for testing to generate sample instances of many
+different components (sensors, lights, ...)

 .. figure:: images/demo-ui.png
    :align: center
@ -20,7 +20,7 @@ different integrations (sensors, lights, ...)
 Configuration variables:
 ------------------------

-This integration has no configuration variables
+This component has no configuration variables

 See Also
 --------
--- a/components/dfplayer.rst
+++ b/components/dfplayer.rst
@ -2,7 +2,7 @@ DF-Player mini
 ==============

 .. seo::
-    :description: Instructions for setting up DF Player Mini integration in ESPHome.
+    :description: Instructions for setting up DF Player Mini component in ESPHome.
    :image: dfplayer.svg

 The ``dfplayer`` (`datasheet <https://wiki.dfrobot.com/DFPlayer_Mini_SKU_DFR0299>`__), component
@ -14,8 +14,7 @@ allows you to play sound and music stored in an SD card or USB flash drive.

    DF-Player mini Module.

-For this integration to work you need to have set up a :ref:`UART bus <uart>`
-in your configuration.
+For this component to work you need to have set up a :ref:`UART bus <uart>` in your configuration.

 Overview
 --------
@ -31,16 +30,7 @@ will be required.
 .. code-block:: yaml

    # Example configuration entry
-    uart:
-      tx_pin: GPIO2
-      rx_pin: GPIO5
-      baud_rate: 9600
-
-    # Declare DFPlayer mini module
    dfplayer:
-      on_finished_playback:
-        then:
-          logger.log: 'Somebody press play!'

 Configuration variables:
 ------------------------
@ -345,8 +335,8 @@ Sample code
 .. code-block:: yaml

    uart:
-      tx_pin: GPIO2
-      rx_pin: GPIO5
+      tx_pin: GPIOXX
+      rx_pin: GPIOXX
      baud_rate: 9600

    dfplayer:
--- a/components/display/addressable_light.rst
+++ b/components/display/addressable_light.rst
@ -19,18 +19,6 @@ The display requires that an :apiclass:`AddressableLight <light::AddressableLigh

 .. code-block:: yaml

-    light:
-      - platform: fastled_clockless
-        chipset: WS2812B
-        pin: GPIO4
-        num_leds: 64
-        rgb_order: GRB
-        name: "led_matrix"
-        id: led_matrix_light
-        default_transition_length: 0s
-        color_correct: [50%, 50%, 50%]
-        restore_mode: ALWAYS_ON
-
    display:
      - platform: addressable_light
        id: led_matrix_display
--- a/components/display/ili9xxx.rst
+++ b/components/display/ili9xxx.rst
@ -55,8 +55,8 @@ beyond the basic SPI connections, and a reasonable amount of RAM, it is not well
    display:
      - platform: ili9xxx
        model: ili9341
-        dc_pin: 27
-        reset_pin: 33
+        dc_pin: GPIOXX
+        reset_pin: GPIOXX
        lambda: |-
          it.fill(COLOR_BLACK);
          it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!");
@ -180,13 +180,13 @@ To configure a dimmable backlight:
    # Define a PWM output on the ESP32
    output:
      - platform: ledc
-        pin: 32
-        id: gpio_32_backlight_pwm
+        pin: GPIOXX
+        id: backlight_pwm

    # Define a monochromatic, dimmable light for the backlight
    light:
      - platform: monochromatic
-        output: gpio_32_backlight_pwm
+        output: backlight_pwm
        name: "Display Backlight"
        id: back_light
        restore_mode: ALWAYS_ON
@ -204,8 +204,8 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep
    display:
      - platform: ili9xxx
        model: ili9341
-        dc_pin: 4
-        reset_pin: 22
+        dc_pin: GPIOXX
+        reset_pin: GPIOXX
        rotation: 90
        id: tft_ha
        color_palette: IMAGE_ADAPTIVE
@ -234,7 +234,7 @@ This config rotates the display into landscape mode using the driver chip.
          mirror_y: true
        color_order: bgr
        data_rate: 80MHz
-        cs_pin: 10
+        cs_pin: GPIOXX
        dc_pin: GPIO13
        reset_pin: GPIO9

--- a/components/display/images/test_card.jpg
+++ b/components/display/images/test_card.jpg
--- a/components/display/index.rst
+++ b/components/display/index.rst
@ -2,7 +2,7 @@ Display Component
 =================

 .. seo::
-    :description: Instructions for setting up the display integration.
+    :description: Instructions for setting up the display component.
    :image: folder-open.svg

 The ``display`` component houses ESPHome's powerful rendering and display
@ -935,49 +935,30 @@ Additionally the old page will be given as the variable ``from`` and the new one
 Troubleshooting
 ---------------

-Color Test Pattern
------------------
+Using the Color Test Card
+-------------------------

-If you're experiencing issues with your color display, the script below can help you to identify what might be wrong.
-It will show 3 color bars in **RED**, **GREEN** and **BLUE**. To help the graphics display team determine
-the best way to help you, **a picture of the result of this script is very helpful.**
+If you're experiencing issues with your color display, the ``show_test_card: true`` option can help you to identify what might be wrong.
+
+- It will show bars for Red, Green and Blue, graduating to black and white.
+- Together with that it will show the letters "**R**", "**G**" and "**B**" to validate the display geometry.
+- There will be a rectangle around the corners of the display with a marker at the 0,0 corner which should be at the top left of the screen.
+
+.. figure:: images/test_card.jpg
+    :align: center
+    :width: 50.0%
+
+
+
+When all points above are shown correctly then the display is working as expected.
+To help the graphics display team determine the best way to help you, **a picture of the result of this option is very helpful.**

 Should you `create an issue <https://github.com/esphome/issues/issues>`__ in GitHub regarding your display, please
-be sure to **include a link to where you purchased it** so that we can validate the configuration you've used.
+be sure to **include a link to where you purchased the display** so that we can validate the configuration you've used.

-.. code-block:: yaml
+.. note::

-    display:
-      - platform: ...
-        ...
-        lambda: |-
-          int shift_x = (it.get_width()-310)/2;
-          int shift_y = (it.get_height()-256)/2;
-          for(auto i = 0; i<256; i++) {
-            it.horizontal_line(shift_x+  0,i+shift_y,50, my_red.fade_to_white(i));
-            it.horizontal_line(shift_x+ 50,i+shift_y,50, my_red.fade_to_black(i));
-
-            it.horizontal_line(shift_x+105,i+shift_y,50, my_green.fade_to_white(i));
-            it.horizontal_line(shift_x+155,i+shift_y,50, my_green.fade_to_black(i));
-
-            it.horizontal_line(shift_x+210,i+shift_y,50, my_blue.fade_to_white(i));
-            it.horizontal_line(shift_x+260,i+shift_y,50, my_blue.fade_to_black(i));
-          }
-          it.rectangle(shift_x+ 0, 0+shift_y, shift_x+ 310, 256+shift_y, my_yellow);
-
-    color:
-      - id: my_blue
-        blue: 100%
-      - id: my_red
-        red: 100%
-      - id: my_green
-        green: 100%
-      - id: my_white
-        red: 100%
-        blue: 100%
-        green: 100%
-      - id: my_yellow
-        hex: ffff00
+    For displays in 8 bit mode you will see distinct color blocks rather than a smooth gradient.

 See Also
 --------
--- a/components/display/lcd_display.rst
+++ b/components/display/lcd_display.rst
@ -2,12 +2,12 @@ Character-Based LCD Display
 ===========================

 .. seo::
-    :description: Instructions for setting up character-based HD44780 LCD displays.
+    :description: Instructions for setting up character-based HD44780 LCDs.
    :image: lcd.jpg

-The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCD displays 
-with ESPHome. This integration is only for LCD displays that display individual characters on a screen 
-(usually 8-40 columns and 2-4 rows), and not for LCD displays that can control each pixel individually.
+The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCDs
+with ESPHome. This component is only for LCDs that display individual characters on a screen
+(usually 8-40 columns and 2-4 rows), and not for LCDs that can control each pixel individually.

 .. figure:: images/lcd-hello_world.jpg
    :align: center
@ -90,12 +90,12 @@ faster refresh, especially in conjunction with an :ref:`LCD Menu <lcd_menu>`.
      - platform: lcd_gpio
        dimensions: 20x4
        data_pins:
-          - GPIO32
-          - GPIO33
-          - GPIO5
-          - GPIO17
-        enable_pin: D4
-        rs_pin: D5
+          - GPIOXX
+          - GPIOXX
+          - GPIOXX
+          - GPIOXX
+        enable_pin: GPIOXX
+        rs_pin: GPIOXX
        lambda: |-
          it.print("Hello World!");

--- a/components/display/max7219.rst
+++ b/components/display/max7219.rst
@ -8,7 +8,7 @@ MAX7219 7-Segment Display
 The ``max7219`` display platform allows you to use MAX7219 7-segment display drivers (
 `datasheet <https://datasheets.maximintegrated.com/en/ds/MAX7219-MAX7221.pdf>`__,
 `hobbycomponents <https://hobbycomponents.com/displays/597-max7219-8-digit-seven-segment-display-module>`__)
-with ESPHome. Please note that this integration is *only* for 7-segment display, not matrix configurations.
+with ESPHome. Please note that this component is *only* for 7-segment display, not matrix configurations.

 .. figure:: images/max7219-full.jpg
    :align: center
@ -16,7 +16,7 @@ with ESPHome. Please note that this integration is *only* for 7-segment display,

    MAX7219 7-Segment Display.

-As the communication with the MAX7219 is done using SPI for this integration, you need
+As the communication with the MAX7219 is done using SPI for this component, you need
 to have an :ref:`SPI bus <spi>` in your configuration with both the **mosi_pin** set (miso_pin is not required).
 Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and
 CS to your set ``cs_pin`` and finally GND to GND.
--- a/components/display/max7219digit.rst
+++ b/components/display/max7219digit.rst
@ -5,7 +5,7 @@ MAX7219 Digit Display
    :description: Instructions for setting up MAX7219 Digit displays.
    :image: max7219digit.jpg

-The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this integration
+The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this component
 is *only* for the digit "matrix" display, for the 7 segment display see :doc:`max7219`.

 .. figure:: images/max7219digit.png
@ -14,7 +14,7 @@ is *only* for the digit "matrix" display, for the 7 segment display see :doc:`ma

    MAX7219 Digit Display.

-As the communication with the MAX7219 Digit is done using SPI for this integration, you need
+As the communication with the MAX7219 Digit is done using SPI for this component, you need
 to have an :ref:`SPI bus <spi>` in your configuration with both the **mosi_pin** set (miso_pin is not required).
 Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and
 CS to your set ``cs_pin`` and finally GND to GND.
--- a/components/display/nextion.rst
+++ b/components/display/nextion.rst
@ -36,17 +36,9 @@ The below example configures a UART for the Nextion display to use
 .. code-block:: yaml

    # Example configuration entry
-    uart:
-      id: uart_2
-      rx_pin: GPIO16
-      tx_pin: GPIO17
-      baud_rate: 115200
-
-
    display:
      - platform: nextion
        id: nextion1
-        uart_id: uart_2      
        lambda: |-
          it.set_component_value("gauge", 50);
          it.set_component_text("textview", "Hello World!");
--- a/components/display/qspi_amoled.rst
+++ b/components/display/qspi_amoled.rst
@ -50,9 +50,9 @@ ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`q
        color_order: rgb
        invert_colors: false
        brightness: 255
-        cs_pin: 11
-        reset_pin: 13
-        enable_pin: 9
+        cs_pin: GPIOXX
+        reset_pin: GPIOXX
+        enable_pin: GPIOXX


 Configuration variables:
--- a/components/display/st7789v.rst
+++ b/components/display/st7789v.rst
@ -40,17 +40,13 @@ to an ESP module.
 .. code-block:: yaml

    # Example minimal configuration entry
-    spi:
-      clk_pin: GPIO18
-      mosi_pin: GPIO19
-
    display:
      - platform: st7789v
        model: TTGO TDisplay 135x240
-        backlight_pin: GPIO4
-        cs_pin: GPIO5
-        dc_pin: GPIO16
-        reset_pin: GPIO23
+        backlight_pin: GPIOXX
+        cs_pin: GPIOXX
+        dc_pin: GPIOXX
+        reset_pin: GPIOXX
        lambda: |-
          it.print(0, 0, id(font), "Hello World!");

--- a/components/display/tm1621.rst
+++ b/components/display/tm1621.rst
@ -22,10 +22,10 @@ The LCD have four signal, ``cs`` for chip select, ``data`` for data signal, ``re
    display:
      platform: tm1621
      id: tm1621_display
-      cs_pin: GPIO17
-      data_pin: GPIO5
-      read_pin: GPIO23
-      write_pin: GPIO18
+      cs_pin: GPIOXX
+      data_pin: GPIOXX
+      read_pin: GPIOXX
+      write_pin: GPIOXX
      lambda: |-
        it.printf(0, "%.1f", id(my_sensor1).state);
        it.display_celsius(true);
--- a/components/display/tm1638.rst
+++ b/components/display/tm1638.rst
@ -23,9 +23,9 @@ The module can be powered with 5v DC. To display the colon punctuation use the
    display:
        platform: tm1638
        id: tm1638_display
-        stb_pin: 5
-        clk_pin: 18
-        dio_pin: 23
+        stb_pin: GPIOXX
+        clk_pin: GPIOXX
+        dio_pin: GPIOXX
        intensity: 5
        update_interval: 5s
        lambda: |-
@ -113,9 +113,9 @@ The following example creates a typical digital clock with the ``:`` colon flash

    display:
      platform: tm1638
-      clk_pin: 18
-      dio_pin: 23
-      stb_pin: 5
+      clk_pin: GPIOXX
+      dio_pin: GPIOXX
+      stb_pin: GPIOXX
      update_interval: 500ms
      lambda: |-
          static int i = 0;
--- a/components/display/waveshare_epaper.rst
+++ b/components/display/waveshare_epaper.rst
@ -23,7 +23,7 @@ single-color E-Ink displays are implemented and of those only a few modules.

    Waveshare E-Paper 2.9 Inch E-Paper Display.

-The communication ESPHome has chosen to use for this integration is 4-wire :ref:`SPI <spi>`, as it's the most stable
+The communication ESPHome has chosen to use for this component is 4-wire :ref:`SPI <spi>`, as it's the most stable
 and high-speed. So you need to make sure your board is set to the 4-wire SPI mode and have an ``spi:`` section in your
 configuration.

@ -96,6 +96,7 @@ Configuration variables:
  - ``2.70in-b`` - Black/White/Red
  - ``2.70in-bv2`` - Black/White/Red
  - ``2.90in``
+  - ``2.90in-dke``
  - ``2.90inv2``
  - ``2.90inv2-r2`` - 2.9in V2 display, but with different initialization and full/partial display refresh management than ``2.90inv2`` 
  - ``2.90in-b`` - B/W rendering only
--- a/components/display_menu/graphical_display_menu.rst
+++ b/components/display_menu/graphical_display_menu.rst
@ -12,14 +12,14 @@ on graphical displays. This offers the user an interactive method to display
 labels, control entities like ``switch``, ``select``, ``number``  available locally on the 
 ESPHome node, without the requirement of a network connection.

-.. figure:: images/graphical_display_menu.jpg
+.. figure:: images/graphical_display_menu.png
    :align: center
    :width: 60.0%

 Overview
 --------

-The integration implements the :ref:`Display Menu <display_menu>` integration providing
+The component implements the :ref:`Display Menu <display_menu>` component providing
 a hierarchical menu primarily intended to be controlled either by a rotary encoder
 with a button or a five-button joystick controller.

--- a/components/display_menu/images/graphical_display_menu.jpg
+++ b/components/display_menu/images/graphical_display_menu.jpg
--- a/components/display_menu/images/graphical_display_menu.png
+++ b/components/display_menu/images/graphical_display_menu.png
--- a/components/display_menu/index.rst
+++ b/components/display_menu/index.rst
@ -7,7 +7,7 @@ Display Menu

 .. _display_menu:

-The integration provides a menu primarily intended to be controlled either by a rotary encoder
+The component provides a menu primarily intended to be controlled either by a rotary encoder
 with a button or a five-button joystick controller. It allows to navigate a hierarchy of items
 and submenus with the ability to change the values and execute commands. The menu can
 be activated and deactivated on demand, allowing alternating between using the screen for
@ -17,8 +17,8 @@ Overview
 --------

 This document describes the configuration and automations common for the components implementing
-this integration. At the moment the character based LCD displays are supported using
-the :ref:`lcd_menu <lcd_menu>` integration and an instance of this is used in the configuration
+this component. At the moment the character based LCD displays are supported using
+the :ref:`lcd_menu <lcd_menu>` component and an instance of this is used in the configuration
 examples.


--- a/components/display_menu/lcd_menu.rst
+++ b/components/display_menu/lcd_menu.rst
@ -19,7 +19,7 @@ ESPHome node, without the requirement of a network connection.
 Overview
 --------

-The integration implements the :ref:`Display Menu <display_menu>` integration providing
+The component implements the :ref:`Display Menu <display_menu>` component providing
 a hierarchical menu primarily intended to be controlled either by a rotary encoder
 with a button or a five-button joystick controller.

--- a/components/esp32_camera.rst
+++ b/components/esp32_camera.rst
@ -14,16 +14,16 @@ directly integrate into Home Assistant through the native API.
    esp32_camera:
      name: My Camera
      external_clock:
-        pin: GPIO27
+        pin: GPIOXX
        frequency: 20MHz
      i2c_pins:
-        sda: GPIO25
-        scl: GPIO23
-      data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
-      vsync_pin: GPIO22
-      href_pin: GPIO26
-      pixel_clock_pin: GPIO21
-      reset_pin: GPIO15
+        sda: GPIOXX
+        scl: GPIOXX
+      data_pins: [GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX]
+      vsync_pin: GPIOXX
+      href_pin: GPIOXX
+      pixel_clock_pin: GPIOXX
+      reset_pin: GPIOXX
      resolution: 640x480
      jpeg_quality: 10

@ -37,10 +37,10 @@ Configuration variables:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.

 Connection Options:
--- a/components/ethernet.rst
+++ b/components/ethernet.rst
@ -17,8 +17,8 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
    # Example configuration entry for RMII chips
    ethernet:
      type: LAN8720
-      mdc_pin: GPIO23
-      mdio_pin: GPIO18
+      mdc_pin: GPIOXX
+      mdio_pin: GPIOXX
      clk_mode: GPIO0_IN
      phy_addr: 0

@ -33,12 +33,12 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
    # Example configuration entry for SPI chips
    ethernet:
      type: W5500
-      clk_pin: GPIO19
-      mosi_pin: GPIO21
-      miso_pin: GPIO23
-      cs_pin: GPIO18
-      interrupt_pin: GPIO36
-      reset_pin: GPIO22
+      clk_pin: GPIOXX
+      mosi_pin: GPIOXX
+      miso_pin: GPIOXX
+      cs_pin: GPIOXX
+      interrupt_pin: GPIOXX
+      reset_pin: GPIOXX

 Configuration variables:
 ------------------------
--- a/components/event/index.rst
+++ b/components/event/index.rst
@ -0,0 +1,147 @@
+Event Component
+===============
+
+.. seo::
+    :description: Instructions for setting up event components in ESPHome.
+    :image: folder-open.svg
+
+ESPHome supports the creation of event entities in Home Assistant.
+These entities allow for the triggering of custom events within the Home Assistant ecosystem,
+enabling complex automations and integrations. An event entity is represented as a stateless
+entity associated with a device that has a pre-defined set of event types which can be
+triggered in Home Assistant via automations.
+
+.. note::
+
+    Events in ESPHome are designed to trigger an action in Home Assistant, and have a unidirectional flow from ESPHome to Home Assistant.
+    Home Assistant event entities are different from events on event bus. If you just want to trigger an event on the
+    Home Assistant event bus, you should use a :ref:`Home Assistant event <api-homeassistant_event_action>` instead.
+
+
+.. note::
+
+    Home Assistant Core 2024.5 or higher is required for ESPHome event entities to work.
+
+.. _config-event:
+
+Base Event Configuration
+------------------------
+
+Each event in ESPHome needs to be configured with a list of event types it can trigger and an optional device class.
+
+.. code-block:: yaml
+
+    # Example event configuration
+    event:
+      - platform: ...
+        name: Motion Detected Event
+        id: my_event
+
+        # Optional variables:
+        icon: "mdi:motion-sensor"
+        device_class: "motion"
+        on_event:
+          then:
+            - logger.log: "Event triggered"
+
+Configuration variables:
+
+One of ``id`` or ``name`` is required.
+
+- **id** (**Required**, :ref:`config-id`): Manually specify the ID used for code generation, allowing for further customization or interaction with this event within ESPHome scripts or lambda functions.
+- **name** (**Required**, string): The name for the event.
+
+  .. note::
+
+      If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
+      you want the event to use that name, you can set ``name: None``.
+
+- **icon** (*Optional*, icon): Manually set the icon to use for the event in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+- **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.
+- **device_class** (*Optional*, string): The device class for the event. The following device classes are supported by event entities:
+
+  - None: Generic event. This is the default and doesn't need to be set.
+  - ``button``: For remote control buttons.
+  - ``doorbell``: Specifically for buttons that are used as a doorbell.
+  - ``motion``: For motion events detected by a motion sensor.
+
+  See https://www.home-assistant.io/integrations/event/#device-class
+  for a list of available options.
+
+Automations:
+
+- **on_event** (*Optional*, :ref:`Automation <automation>`): An automation to perform when an event is triggered.
+
+MQTT options:
+
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+Event Automation
+----------------
+
+.. _event-on_event:
+
+``on_event``
+************
+
+This automation will be triggered when an event of the specified types is triggered.
+
+.. code-block:: yaml
+
+    event:
+      - platform: template
+        # ...
+        on_event:
+          then:
+            - logger.log: "Event Triggered"
+
+Configuration variables: see :ref:`Automation <automation>`.
+
+``event.trigger`` Action
+************************
+
+This action allows for the triggering of an event from within an automation.
+
+.. code-block:: yaml
+
+    - event.trigger:
+        id: my_event
+        event_type: "custom_event"
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the event.
+- **event_type** (**Required**, string): The type of event to trigger.
+
+.. _event-lambda_calls:
+
+lambda Calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can trigger an event.
+
+- ``trigger(std::string event_type)``: Trigger an event with the specified type.
+
+  .. code-block:: cpp
+
+      // Within lambda, trigger the event.
+      id(my_event).trigger("custom_event");
+
+See Also
+--------
+
+- :apiref:`event/event.h`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
--- a/components/event/template.rst
+++ b/components/event/template.rst
@ -0,0 +1,31 @@
+Template Event
+==============
+
+.. seo::
+    :description: Instructions for setting up template events that can trigger arbitrary automations when an event occurs.
+    :image: description.svg
+
+The ``template`` event platform enables you to define events that trigger specific automations or actions within Home Assistant. These custom events can be utilized to orchestrate complex behaviors across your smart home ecosystem based on conditions or sequences defined in your ESPHome configuration.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    event:
+      - platform: template
+        name: "Template Event"
+        event_types:
+          - "custom_event_1"
+          - "custom_event_2"
+
+Configuration variables:
+------------------------
+
+- **event_types** (**Required**, list): A list of custom event identifiers that this template event is capable of triggering. These identifiers can be used in Home Assistant automations or ESPHome scripts to perform actions when the event occurs.
+- All other options from :ref:`Event <config-event>`.
+
+See Also
+--------
+
+- :doc:`/guides/automations`
+- :doc:`/components/event/index`
+- :ghedit:`Edit`
--- a/components/exposure_notifications.rst
+++ b/components/exposure_notifications.rst
@ -52,7 +52,7 @@ minute, the indicator will be on.

    switch:
      - platform: gpio
-        pin: GPIO22
+        pin: GPIOXX
        id: led

    script:
--- a/components/external_components.rst
+++ b/components/external_components.rst
@ -46,6 +46,7 @@ Configuration variables:
  - **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used.
  - **username** (*Optional*, string): Username for the Git server, if one is required
  - **password** (*Optional*, string): Password for the Git server, if one is required
+  - **path** (*Optional*, string): Path inside the repo, if different from ``components`` or ``esphome/components``

  local options:

--- a/components/fan/binary.rst
+++ b/components/fan/binary.rst
@ -14,11 +14,6 @@ The ``binary`` fan platform lets you represent any binary :ref:`output` as a fan
 .. code-block:: yaml

    # Example configuration entry
-    output:
-      - id: fan_output
-        platform: gpio
-        pin: GPIO16
-        
    fan:
      - platform: binary
        output: fan_output
--- a/components/fan/hbridge.rst
+++ b/components/fan/hbridge.rst
@ -23,14 +23,6 @@ The ``hbridge`` fan platform allows you to use a compatible *h-bridge* (L298N, D
 .. code-block:: yaml

    # Example configuration entry
-    output:
-      - platform: ...
-        id: motor_forward_pin
-        pin: GPIO5
-      - platform: ...
-        id: motor_reverse_pin
-        pin: GPIO4
-
    fan:
      - platform: hbridge
        id: my_fan
--- a/components/fan/index.rst
+++ b/components/fan/index.rst
@ -49,10 +49,10 @@ Configuration variables:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.

 MQTT options:
--- a/components/fingerprint_grow.rst
+++ b/components/fingerprint_grow.rst
@ -2,7 +2,7 @@ Grow Fingerprint Reader
 =======================

 .. seo::
-    :description: Instructions for setting up Grow Fingerprint Reader integration in ESPHome.
+    :description: Instructions for setting up Grow Fingerprint Reader component in ESPHome.
    :image: fingerprint.svg

 The ``fingerprint_grow`` component allows you to use your R307, R503, R503-RGB, ZFM-20, ... fingerprint sensors with ESPHome.
@ -30,16 +30,10 @@ If available on your reader model, it's recommended to connect 3.3VT (touch indu
 .. code-block:: yaml

    # Example configuration entry
-    uart:
-      rx_pin: GPIO13
-      tx_pin: GPIO15
-      baud_rate: 57600
-
-    # Declare Grow Fingerprint Reader
    fingerprint_grow:
-      sensing_pin: GPIO12
+      sensing_pin: GPIOXX
      sensor_power_pin:
-          number: GPIO18
+          number: GPIOXX
          inverted: true
      idle_period_to_sleep: 5s

@ -93,46 +87,27 @@ Configuration variables:
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - All other options from :ref:`Binary Sensor <config-binary_sensor>`.

-Optional Sensor Configuration:

 Sensor
 ------

 - **fingerprint_count**: The number of enrolled fingerprints stored on the reader.
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 - **last_finger_id**: The last matched enrolled fingerprint as set by :ref:`fingerprint_grow-on_finger_scan_matched`.
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 - **last_confidence**: The last matched confidence as set by :ref:`fingerprint_grow-on_finger_scan_matched`.
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 - **status**: The integer representation of the internal status register of the reader.
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 - **capacity**: The fingerprint storage capacity of the reader.
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 - **security_level**: The integer representation of the currently configured security level of the reader. Higher security levels reduce the false acceptance rate (FAR) at the expense of increasing the false rejection rate (FRR). Range is 1 (lowest) to 5 (highest).
-
-  - **name** (**Required**, string): The name for the sensor.
-  - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-  - All other options from :ref:`Sensor <config-sensor>`.
+  All options from :ref:`Sensor <config-sensor>`.

 .. _fingerprint_grow-sleep_mode:

@ -150,14 +125,14 @@ This is a wiring example for the R503 and below you can find the respective conf
 .. code-block:: yaml

    uart:
-      rx_pin: GPIO16
-      tx_pin: GPIO17
+      rx_pin: GPIOXX
+      tx_pin: GPIOXX
      baud_rate: 57600

    fingerprint_grow:
-      sensing_pin: GPIO4
+      sensing_pin: GPIOXX
      sensor_power_pin:
-          number: GPIO18
+          number: GPIOXX
          inverted: true
      idle_period_to_sleep: 5s

@ -513,12 +488,12 @@ Sample code
 .. code-block:: yaml

    uart:
-      rx_pin: GPIO13
-      tx_pin: GPIO15
+      rx_pin: GPIOXX
+      tx_pin: GPIOXX
      baud_rate: 57600

    fingerprint_grow:
-      sensing_pin: GPIO12
+      sensing_pin: GPIOXX
      on_finger_scan_invalid:
        - homeassistant.event:
            event: esphome.test_node_finger_scan_invalid
--- a/components/gps.rst
+++ b/components/gps.rst
@ -2,7 +2,7 @@ GPS Component
 =============

 .. seo::
-    :description: Instructions for setting up GPS integration in ESPHome.
+    :description: Instructions for setting up GPS component in ESPHome.
    :image: crosshairs-gps.svg

 The ``gps`` component allows you to connect GPS modules to your ESPHome project.
@ -16,15 +16,12 @@ Any GPS module that uses the standardized NMEA communication protocol will work.

 .. _Adafruit: https://www.adafruit.com/product/746

-For this integration to work you need to have set up a :ref:`UART bus <uart>`
+For this component to work you need to have set up a :ref:`UART bus <uart>`
 in your configuration - only the RX pin should be necessary.

 .. code-block:: yaml

    # Example configuration entry
-    uart:
-      rx_pin: D7
-      baud_rate: 9600

    # Declare GPS module
    gps:
--- a/components/i2c.rst
+++ b/components/i2c.rst
@ -20,8 +20,8 @@ connecting the wires from each device back to the two I²C pins on the ESP.

    # Example configuration entry for ESP32
    i2c:
-      sda: 21
-      scl: 22
+      sda: GPIOXX
+      scl: GPIOXX
      scan: true
      id: bus_a

@ -51,12 +51,12 @@ Configuration variables:
        # Example configuration entry
        i2c:
          - id: bus_a
-            sda: 13
-            scl: 16
+            sda: GPIOXX
+            scl: GPIOXX
            scan: true
          - id: bus_b
-            sda: 14
-            scl: 15
+            sda: GPIOXX
+            scl: GPIOXX
            scan: true
       # Sensors should be specified as follows
       - platform: bme680
--- a/components/i2s_audio.rst
+++ b/components/i2s_audio.rst
@ -14,8 +14,8 @@ This component only works on ESP32 based chips.

    # Example configuration entry
    i2s_audio:
-      i2s_lrclk_pin: GPIO33
-      i2s_bclk_pin: GPIO19
+      i2s_lrclk_pin: GPIOXX
+      i2s_bclk_pin: GPIOXX

 Configuration variables:
 ------------------------
--- a/components/images/DFR0627.jpg
+++ b/components/images/DFR0627.jpg
--- a/components/index.rst
+++ b/components/index.rst
@ -17,6 +17,7 @@ Components
    sensor/index
    switch/index
    button/index
+    event/index
    display/index
    text_sensor/index
    stepper/index
@ -29,4 +30,5 @@ Components
    time/index
    alarm_control_panel/index
    text/index
+    valve/index
    *
--- a/components/light/binary.rst
+++ b/components/light/binary.rst
@ -20,10 +20,6 @@ The ``binary`` light platform creates a simple ON/OFF-only light from a
        name: "Desk Lamp"
        output: light_output

-    output:
-      - id: light_output
-        platform: gpio
-        pin: GPIO16

 Configuration variables:
 ------------------------
--- a/components/light/custom.rst
+++ b/components/light/custom.rst
@ -1,21 +1,27 @@
 Custom Light Output
 ===================

+.. seo::
+    :description: Instructions for setting up Custom C++ lights with ESPHome.
+    :image: language-cpp.svg
+    :keywords: C++, Custom
+
 .. warning::

-    Custom components are deprecated, not recommended for new configurations
-    and will be removed from ESPHome in a future release.
-    Please look at creating a real ESPHome component and "importing" it into your
-    configuration with :doc:`/components/external_components`.
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+    :doc:`/components/external_components`.

-    You can find some basic documentation on creating your own components
-    at :ref:`contributing_to_esphome`.
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

-This integration can be used to create custom lights in ESPHome
-using the C++ (Arduino) API.
+.. warning::

-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom lights in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.

 All internal stuff (like effects, transitions etc) is handled by the light core
 and cannot be overridden. Light outputs are only responsible for displaying some state
--- a/components/light/esp32_rmt_led_strip.rst
+++ b/components/light/esp32_rmt_led_strip.rst
@ -12,7 +12,7 @@ This is a component using the ESP32 RMT peripheral to drive most addressable LED
    light:
      - platform: esp32_rmt_led_strip
        rgb_order: GRB
-        pin: GPIO13
+        pin: GPIOXX
        num_leds: 30
        rmt_channel: 0
        chipset: ws2812
--- a/components/light/fastled.rst
+++ b/components/light/fastled.rst
@ -47,7 +47,7 @@ Clockless FastLED lights differ from the
    light:
      - platform: fastled_clockless
        chipset: WS2811
-        pin: GPIO23
+        pin: GPIOXX
        num_leds: 60
        rgb_order: BRG
        name: "FastLED WS2811 Light"
@ -126,8 +126,8 @@ whereas the clockless lights only need a single pin.
    light:
      - platform: fastled_spi
        chipset: WS2801
-        data_pin: GPIO23
-        clock_pin: GPIO22
+        data_pin: GPIOXX
+        clock_pin: GPIOXX
        num_leds: 60
        rgb_order: BRG
        name: "FastLED SPI Light"
--- a/components/light/hbridge.rst
+++ b/components/light/hbridge.rst
@ -18,17 +18,6 @@ The pins are switched alternatively to allow two sets of lights to operate.
 .. code-block:: yaml

    # Example configuration entry
-
-    # Specify the two pins of the h-bridge as PWM pins
-    output:
-      - platform: esp8266_pwm
-        id: pina
-        pin: GPIO12
-      - platform: esp8266_pwm
-        id: pinb
-        pin: GPIO14
-
-    # Create a light using the hbridge
    light:
      - platform: hbridge
        id: mainlight
--- a/components/light/index.rst
+++ b/components/light/index.rst
@ -77,10 +77,10 @@ Advanced options:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.
 - If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.

@ -583,6 +583,7 @@ Configuration variables:
  - **cold_white** (*Optional*, percentage): The cold white channel of the light, if applicable. Defaults to ``100%``.
  - **warm_white** (*Optional*, percentage): The warm white channel of the light, if applicable. Defaults to ``100%``.
  - **duration** (**Required**, :ref:`config-time`): The duration this color should be active.
+  - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``0s``.

 See `light.turn_on <light-turn_on_action>` for more information on the various color fields.

--- a/components/light/monochromatic.rst
+++ b/components/light/monochromatic.rst
@ -26,11 +26,6 @@ The ``monochromatic`` light platform creates a simple brightness-only light from
        name: "Kitchen Lights"
        output: output_component1

-    # Example output entry
-    output:
-      - platform: esp8266_pwm
-        id: output_component1
-        pin: D1

 Configuration variables:
 ------------------------
--- a/components/light/neopixelbus.rst
+++ b/components/light/neopixelbus.rst
@ -18,7 +18,7 @@ in ESPHome for individually addressable lights like NeoPixel or WS2812.
 It is very similar to the :doc:`fastled` platform.
 In fact, most addressable lights are supported through both light platforms. The
 difference is that they use different libraries: while the fastled platform uses
-the `FastLED <https://github.com/FastLED/FastLED>`__ library, this integration uses
+the `FastLED <https://github.com/FastLED/FastLED>`__ library, this component uses
 the `NeoPixelBus <https://github.com/Makuna/NeoPixelBus/>`__ library internally.

 .. code-block:: yaml
@ -28,7 +28,7 @@ the `NeoPixelBus <https://github.com/Makuna/NeoPixelBus/>`__ library internally.
      - platform: neopixelbus
        type: GRB
        variant: WS2811
-        pin: GPIO23
+        pin: GPIOXX
        num_leds: 60
        name: "NeoPixel Light"

--- a/components/light/rgb.rst
+++ b/components/light/rgb.rst
@ -28,12 +28,6 @@ The ``rgb`` light platform creates an RGB light from 3 :ref:`float output compon
        green: output_component2
        blue: output_component3

-    # Example output entry
-    output:
-      - platform: esp8266_pwm
-        id: output_component1
-        pin: D1
-      # Repeat for green and blue output

 Color Correction
 ----------------
@ -54,9 +48,8 @@ perceived intensity of different colors will generally vary. This can be done by

    # Example output entry
    output:
-      - platform: esp8266_pwm
+      - platform: ...
        id: output_component1
-        pin: D1
        max_power: 80%
      # Repeat for green and blue output

--- a/components/light/rgbw.rst
+++ b/components/light/rgbw.rst
@ -38,9 +38,8 @@ perceived intensity of different colors will generally vary. This can be done by

    # Example output entry
    output:
-      - platform: esp8266_pwm
+      - platform: ...
        id: output_component1
-        pin: D1
        max_power: 80%

 .. note::
--- a/components/light/rgbww.rst
+++ b/components/light/rgbww.rst
@ -44,9 +44,8 @@ perceived intensity of different colors will generally vary. This can be done by

    # Example output entry
    output:
-      - platform: esp8266_pwm
+      - platform: ...
        id: output_component1
-        pin: D1
        max_power: 80%

 .. note::
--- a/components/light/rp2040_pio_led_strip.rst
+++ b/components/light/rp2040_pio_led_strip.rst
@ -13,7 +13,7 @@ This is a component using the RP2040 PIO peripheral to drive most addressable LE
      - platform: rp2040_pio_led_strip
        name: led_strip
        id: led_strip
-        pin: GPIO13
+        pin: GPIOXX
        num_leds: 10
        pio: 0
        rgb_order: GRB
--- a/components/light/spi_led_strip.rst
+++ b/components/light/spi_led_strip.rst
@ -18,14 +18,9 @@ LEDs, or any others with a similar interface - SPI, 8 bits per colour and BGR or
 .. code-block:: yaml

    # Example configuration entry
-    spi:
-      mosi_pin: GPIO3
-      clk_pin: GPIO9
-
    light:
      - platform: spi_led_strip
        num_leds: 30
-        color_correct: [80%, 60%, 100%]
        id: rgb_led
        name: "RGB LED Strip"
        data_rate: 1MHz
--- a/components/light/status_led.rst
+++ b/components/light/status_led.rst
@ -22,7 +22,7 @@ When the device is in OK state, the LED will be restored to the state of the ``b
    light:
      - platform: status_led
        name: "Switch state"
-        pin: GPIO2
+        pin: GPIOXX

 .. note::

@ -50,7 +50,7 @@ Configuration variables:
    .. code-block:: yaml

        pin:
-          number: GPIO2
+          number: GPIOXX
          inverted: true


--- a/components/lightwaverf.rst
+++ b/components/lightwaverf.rst
@ -22,19 +22,8 @@ Using an inexpensive RF transmitter and receiver you can control your devices vi

    # Specify the two pins to connect the receiver and transmitter
    lightwaverf:
-      read_pin: 13
-      write_pin: 14
-
-    # Create a switch to trigger a light
-    switch:
-      - platform: template
-        name: "Turn off sofa"
-        id: light_off_ceiling_sofa
-        turn_on_action:
-          lightwaverf.send_raw:
-            code:  [0x04, 0x00, 0x00, 0x00, 0x0f, 0x03, 0x0d, 0x09, 0x08, 0x08]
-            name: "Sofa"
-            repeat: 1
+      read_pin: GPIOXX
+      write_pin: GPIOXX


 Note: To gather the RAW codes from the remote, setup the ``read_pin`` and observe in the logs the printing of the codes.
--- a/components/lock/index.rst
+++ b/components/lock/index.rst
@ -8,10 +8,6 @@ Lock Component
 The ``lock`` domain includes all platforms that should function like a lock
 with lock/unlock actions.

-.. note::
-
-    ESPHome lock components requires Home Assistant 2022.3 or newer
-
 .. _config-lock:

 Base Lock Configuration
--- a/components/lock/output.rst
+++ b/components/lock/output.rst
@ -16,7 +16,7 @@ The ``output`` lock platform allows you to use any output component as a lock.
    # Example configuration entry
    output:
      - platform: gpio
-        pin: 25
+        pin: GPIOXX
        id: 'generic_out'
    lock:
      - platform: output
--- a/components/matrix_keypad.rst
+++ b/components/matrix_keypad.rst
@ -23,15 +23,15 @@ Component
    matrix_keypad:
      id: mykeypad
      rows:
-        - pin: 21
-        - pin: 19
-        - pin: 18
-        - pin: 5
+        - pin: GPIOXX
+        - pin: GPIOXX
+        - pin: GPIOXX
+        - pin: GPIOXX
      columns:
-        - pin: 17
-        - pin: 16
-        - pin: 4
-        - pin: 15
+        - pin: GPIOXX
+        - pin: GPIOXX
+        - pin: GPIOXX
+        - pin: GPIOXX
      keys: "123A456B789C*0#D"
      has_diodes: false

--- a/components/max6956.rst
+++ b/components/max6956.rst
@ -58,19 +58,7 @@ Binary Sensor Example

 .. code-block:: yaml

-    # Example configuration : pin as input with pullup
-    i2c:
-      id: bus_a
-      sda: GPIO13
-      scl: GPIO16
-      scan: false
-
-    max6956:
-      - id: max6956_1
-        address: 0x40
-        i2c_id: bus_a
-
-    # Individual input
+    # Example configuration
    binary_sensor:
      - platform: gpio
        name: "MaxIn Pin 4"
@ -91,18 +79,7 @@ Switch Example

 .. code-block:: yaml

-    # Example configuration : pin as output
-    i2c:
-      id: bus_a
-      sda: GPIO13
-      scl: GPIO16
-
-      max6956:
-        - id: max6956_1
-          address: 0x40
-          i2c_id: bus_a
-
-      # Individual output
+    # Example configuration
      switch:
        - platform: gpio
          name: "MaxIn Pin 8"
@ -126,8 +103,8 @@ Led driver Example
    # Example configuration : pin as led driver, current globaly
    i2c:
      id: bus_a
-      sda: GPIO13
-      scl: GPIO16
+      sda: GPIOXX
+      scl: GPIOXX

    switch:
      - platform: template
@ -178,8 +155,8 @@ Led driver Example
    # Example configuration : pin as led driver, current managed individualy (RBG led)
    i2c:
      id: bus_a
-      sda: GPIO13
-      scl: GPIO16
+      sda: GPIOXX
+      scl: GPIOXX

    max6956:
      - id: max6956_1
--- a/components/mcp23Sxx.rst
+++ b/components/mcp23Sxx.rst
@ -26,7 +26,7 @@ The MCP23S08 component (`datasheet <http://ww1.microchip.com/downloads/en/Device
    # Example configuration entry
    mcp23s08:
      - id: 'mcp23s08_hub'
-        cs_pin: D8
+        cs_pin: GPIOXX
        deviceaddress: 0

    # Individual outputs
@ -94,7 +94,7 @@ binary sensor or GPIO switch.
    # Example configuration entry
    mcp23s17:
      - id: 'mcp23s17_hub'
-        cs_pin: D8
+        cs_pin: GPIOXX
        deviceaddress: 0

    # Individual outputs
--- a/components/media_player/i2s_audio.rst
+++ b/components/media_player/i2s_audio.rst
@ -15,7 +15,7 @@ via the :doc:`/components/i2s_audio`. This platform only works on ESP32 based ch
      - platform: i2s_audio
        name: ESPHome I2S Media Player
        dac_type: external
-        i2s_dout_pin: GPIO22
+        i2s_dout_pin: GPIOXX
        mode: mono

 Configuration variables:
--- a/components/micronova.rst
+++ b/components/micronova.rst
@ -18,7 +18,7 @@ The :ref:`UART <uart>` must be configured with a baud rate 1200, 8 data bits, 2

    Also, switching your stove on or off can behave different on the various MicroNova flavours.

-    Use this integration at your own risk.
+    Use this component at your own risk.

 Connecting your stove
 ---------------------
--- a/components/microphone/i2s_audio.rst
+++ b/components/microphone/i2s_audio.rst
@ -24,12 +24,12 @@ This platform only works on ESP32 based chips.
      - platform: i2s_audio
        id: external_mic
        adc_type: external
-        i2s_din_pin: GPIO23
+        i2s_din_pin: GPIOXX

      - platform: i2s_audio
        id: adc_mic
        adc_type: internal
-        adc_pin: GPIO35
+        adc_pin: GPIOXX


 Configuration variables:
@ -80,7 +80,7 @@ M5Stack Atom Echo
    microphone:
      - platform: i2s_audio
        adc_type: external
-        i2s_din_pin: GPIO23
+        i2s_din_pin: GPIOXX
        pdm: true

 RaspiAudio Muse Luxe
@ -90,7 +90,7 @@ RaspiAudio Muse Luxe

    microphone:
      - platform: i2s_audio
-        i2s_din_pin: GPIO35
+        i2s_din_pin: GPIOXX
        adc_type: external
        pdm: false

--- a/components/modbus_controller.rst
+++ b/components/modbus_controller.rst
@ -78,7 +78,7 @@ Technically there is no difference between the "inline" and the standard definit
      ...

    modbus:
-      flow_control_pin: 5
+      flow_control_pin: GPIOXX
      id: modbus1

    modbus_controller:
@ -586,13 +586,13 @@ The response is mapped to the sensor based on ``register_count`` and offset in b

        uart:
          id: mod_bus
-          tx_pin: 19
-          rx_pin: 18
+          tx_pin: GPIOXX
+          rx_pin: GPIOXX
          baud_rate: 115200
          stop_bits: 1

        modbus:
-          #flow_control_pin: 23
+          #flow_control_pin: GPIOXX
          send_wait_time: 200ms
          id: mod_bus_epever

--- a/components/mqtt.rst
+++ b/components/mqtt.rst
@ -184,13 +184,12 @@ Home Assistant generates entity names for all discovered devices based on entity
 entity name (e.g. ``sensor.uptime``). Numeric suffixes are appended to entity names when
 multiple devices use the same name for a sensor, making it harder to distinguish between
 similar sensors on different devices. Home Assistant 2021.12 allows MQTT devices to change
-this behaviour by specifying ``object_id`` discovery attribute which replaces the sensor
+this behaviour by specifying the ``object_id`` discovery attribute which replaces the sensor
 name part of the generated entity name. Setting ``discovery_object_id_generator: device_name``
-in ESPHome MQTT integration configuration will cause Home Assistant to include device name
+in the ESPHome MQTT component configuration will cause Home Assistant to include device name
 in the generated entity names (e.g. ``sensor.uptime`` becomes ``sensor.<device name>_uptime``),
 making it easier to distinguish the entities in various entity lists.

-
 .. _mqtt-defaults:

 Defaults
@ -266,7 +265,7 @@ then run the ``mqtt-fingerprint`` script of ESPHome to get the certificate:

 .. code-block:: bash

-    esphome livingroom.yaml mqtt-fingerprint
+    esphome mqtt-fingerprint livingroom.yaml
    > SHA1 Fingerprint: a502ff13999f8b398ef1834f1123650b3236fc07
    > Copy above string into mqtt.ssl_fingerprints section of livingroom.yaml

--- a/components/number/index.rst
+++ b/components/number/index.rst
@ -43,16 +43,16 @@ Configuration variables:
  a ``name`` will implicitly set this to true.
 - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
-  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+  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. Requires Home Assistant 2021.11 or newer.
+  for a list of available options.
  Set to ``""`` to remove the default entity category.
 - **unit_of_measurement** (*Optional*, string): Manually set the unit
-  of measurement for the number. Requires Home Assistant Core 2021.12 or newer.
+  of measurement for the number.
 - **mode** (*Optional*, string): Defines how the number should be displayed in the frontend.
  See https://developers.home-assistant.io/docs/core/entity/number/#properties
-  for a list of available options. Requires Home Assistant Core 2021.12 or newer.
+  for a list of available options.
  Defaults to ``"auto"``.
 - **device_class** (*Optional*, string): The device class for the number.
  See https://www.home-assistant.io/integrations/number/#device-class
--- a/components/output/ac_dimmer.rst
+++ b/components/output/ac_dimmer.rst
@ -2,7 +2,7 @@ AC Dimmer Component
 ===================

 .. seo::
-    :description: Instructions for setting up AC Dimmer integration in ESPHome.
+    :description: Instructions for setting up AC Dimmer component in ESPHome.
    :image: ac_dimmer.svg

 .. warning::
@ -16,9 +16,8 @@ AC Dimmer Component
 The ``ac_dimmer`` component allows you to connect a dimmable light or other load
 which supports phase control dimming to your ESPHome project.

-There are several already made boards which are compatible with this integration,
-for example the `RobotDyn dimmer
-<https://robotdyn.com/ac-light-dimmer-module-1-channel-3-3v-5v-logic-ac-50-60hz-220v-110v.html>`__.
+There are several already made boards which are compatible with this component, such as the
+`RobotDyn dimmer <https://robotdyn.com/ac-light-dimmer-module-1-channel-3-3v-5v-logic-ac-50-60hz-220v-110v.html>`__.

 .. figure:: images/robotdyn_dimmer.jpg
    :align: center
@ -34,9 +33,9 @@ for example the `RobotDyn dimmer
    output:
      - platform: ac_dimmer
        id: dimmer1
-        gate_pin: D7
+        gate_pin: GPIOXX
        zero_cross_pin:
-          number: D6
+          number: GPIOXX
          mode:
            input: true
          inverted: yes
--- a/components/output/bp1658cj.rst
+++ b/components/output/bp1658cj.rst
@ -24,8 +24,8 @@ It is used in some smart light bulbs:

    # Example configuration entry
    bp1658cj:
-      data_pin: GPIO6
-      clock_pin: GPIO7
+      data_pin: GPIOXX
+      clock_pin: GPIOXX
      max_power_color_channels: 4 # Valid values 0-15
      max_power_white_channels: 6 # Valid values 0-15

--- a/components/output/bp5758d.rst
+++ b/components/output/bp5758d.rst
@ -24,8 +24,8 @@ It is used in some smart light bulbs:

    # Example configuration entry
    bp5758d:
-      data_pin: GPIO3
-      clock_pin: GPIO5
+      data_pin: GPIOXX
+      clock_pin: GPIOXX


 Configuration variables:
--- a/components/output/custom.rst
+++ b/components/output/custom.rst
@ -1,17 +1,25 @@
 Custom Output
 =============

+.. seo::
+    :description: Instructions for setting up Custom C++ outputs with ESPHome.
+    :image: language-cpp.svg
+    :keywords: C++, Custom
+
 .. warning::

-    Custom components are deprecated, not recommended for new configurations
-    and will be removed from ESPHome in a future release.
-    Please look at creating a real ESPHome component and "importing" it into your
-    configuration with :doc:`/components/external_components`.
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+    :doc:`/components/external_components`.

-    You can find some basic documentation on creating your own components
-    at :ref:`contributing_to_esphome`.
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.

-This integration can be used to create custom binary and float :doc:`outputs </components/output/index>`
+.. warning::
+
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom binary and float :doc:`outputs </components/output/index>`
 in ESPHome using the C++ (Arduino) API.

 Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
--- a/Show More
+++ b/Show More
 @ -1 +1 @@
 .4.0
 .4.2