New branding for ESPHome (#3926)

* Update for higher i2c frequencies on IDF

* Update sht3xd.rst

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
 {
   "name": "ESPHome - docs",
   "image": "mcr.microsoft.com/vscode/devcontainers/python:0-3.11",
-  "postCreateCommand": "pip3 install -r requirements.txt -r requirements_test.txt",
+  "postCreateCommand": ".devcontainer/postCreate.sh",
   "postAttachCommand": "make live-html",
   "forwardPorts": [8000],
   "features": {

.devcontainer/postCreate.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+
+pip3 install -r requirements.txt -r requirements_test.txt
+curl -L https://github.com/CloudCannon/pagefind/releases/download/v1.1.0/pagefind-v1.1.0-x86_64-unknown-linux-musl.tar.gz | tar -xz -C ~/.local/bin

.github/workflows/docker.yml

@@ -18,9 +18,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+      -
+        name: Install pagefind
+        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        with:
+          repo: cloudcannon/pagefind
       -
         name: Checkout source code
-        uses: actions/checkout@v4.1.0
+        uses: actions/checkout@v4.1.6
       -
         name: Set up QEMU
         uses: docker/setup-qemu-action@v3

.github/workflows/lint.yml

@@ -19,7 +19,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4.1.0
+    - name: Install pagefind
+      uses: jaxxstorm/action-install-gh-release@v1.12.0
+      with:
+          repo: cloudcannon/pagefind
+    - uses: actions/checkout@v4.1.6
     - name: Set up Python 3.8
       uses: actions/setup-python@v5
       with:

.gitignore

@@ -11,3 +11,5 @@ venv
 .vscode
 *.DS_Store
 /.idea/
+
+_pagefind/

Dockerfile

@@ -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,39 @@ 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 .
+ENV PAGEFIND_VERSION="1.1.0"
+ARG TARGETARCH
+SHELL ["/bin/bash", "-c"]
+RUN <<EOF
+    export TARGETARCH=${TARGETARCH/arm64/aarch64}
+    export TARGETARCH=${TARGETARCH/amd64/x86_64}
+    curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$PAGEFIND_VERSION/pagefind-v$PAGEFIND_VERSION-$TARGETARCH-unknown-linux-musl.tar.gz -L
+    tar xzf pagefind.tar.gz
+    rm pagefind.tar.gz
+    mv pagefind /usr/bin
+    chmod +x /usr/bin/pagefind
+EOF
+
+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"

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.4.0b1
+PROJECT_NUMBER         = 2024.5.5
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

Makefile

@@ -1,12 +1,21 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2024.4.0b1
+ESPHOME_REF = 2024.5.5
+PAGEFIND_VERSION=1.1.0
+PAGEFIND=pagefind
+NET_PAGEFIND=../pagefindbin/pagefind
 
-.PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
+.PHONY: pagefind build-html html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
 
-html:
+html: pagefind
+	sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
+
+pagefind:
 	sphinx-build -M html . _build -j auto -n $(O)
-live-html:
+	mkdir -p _pagefind/pagefind
-	sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0
+	${PAGEFIND}
+
+live-html:	pagefind
+	sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0 -Dhtml_extra_path=_redirects,_pagefind
 
 html-strict:
 	sphinx-build -M html . _build -W -j auto -n $(O)
@@ -32,6 +41,12 @@ api:
 	fi
 	ESPHOME_PATH=$(ESPHOME_PATH) doxygen Doxygen
 
+net-html:
+	sphinx-build -M html . _build -j auto -n $(O)
+	mkdir -p _pagefind/pagefind
+	${NET_PAGEFIND}
+	sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
+
 netlify-api: netlify-dependencies
 	mkdir -p _build/html/api
 	@if [ ! -d "$(ESPHOME_PATH)" ]; then \
@@ -40,19 +55,31 @@ netlify-api: netlify-dependencies
 	fi
 	ESPHOME_PATH=$(ESPHOME_PATH) ../doxybin/doxygen Doxygen
 
-netlify-dependencies:
+netlify-dependencies: pagefind-binary
 	mkdir -p ../doxybin
 	curl -L https://github.com/esphome/esphome-docs/releases/download/v1.10.1/doxygen-1.8.13.xz | xz -d >../doxybin/doxygen
 	chmod +x ../doxybin/doxygen
 
+pagefind-binary:
+	mkdir -p ../pagefindbin
+	curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$(PAGEFIND_VERSION)/pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz -L
+	tar xzf pagefind.tar.gz
+	rm pagefind.tar.gz
+	mv pagefind ${NET_PAGEFIND}
+
+
 copy-svg2png:
 	cp svg2png/*.png _build/html/_images/
 
-netlify: netlify-dependencies netlify-api html copy-svg2png
+netlify: netlify-dependencies netlify-api net-html copy-svg2png
 
 lint: html-strict
 	python3 lint.py
 
+clean:
+	rm -rf _pagefind/
+	sphinx-build -M clean . _build $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

_static/browserconfig.xml

@@ -3,7 +3,7 @@
     <msapplication>
         <tile>
             <square150x150logo src="/_static/mstile-150x150.png"/>
-            <TileColor>#dfdfdf</TileColor>
+            <TileColor>#18bcf2</TileColor>
         </tile>
     </msapplication>
 </browserconfig>

_static/custom.css

@@ -1,3 +1,9 @@
+/* provide this to be queried in JS. Sadly can't be used in media-queries just yet*/
+
+:root {
+  --mobile-width-stop: 875;
+}
+
 .row-odd {
   background-color: #f3f6f6;
 }
@@ -240,9 +246,77 @@ 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;
 }
+.pagefind-ui__form {
+    width: 100%;
+    max-width: 300px;
+    left: auto;
+    right: auto;
+    position: relative;
+}
+
+.pagefind-modular-list-excerpt, .pagefind-modular-list-title {
+    color: #111111 !important;
+}
+
+.search-results {
+    background-color: #f8f8f8;
+    box-shadow: 0 6px 10px rgb(0 0 0 / 0.2);
+    position: fixed;
+    z-index: 1500;
+    padding-right: 6px;
+    padding-left: 6px;
+    border-radius: 12px;
+    overflow: auto;
+    width: 0;
+    height: fit-content;
+    max-width: 650px;
+    transition: height, width 0.1s ease-in-out;
+    display: none;
+}
+
+/* New branding changes */
+
+div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6, div.sphinxsidebar h3, div.sphinxsidebar h4, div.admonition p.admonition-title {
+  font-family: Figtree, system, -apple-system, ".SFNSText-Regular", "San Francisco", "Roboto", "Segoe UI", "Helvetica Neue", "Lucida Grande", sans-serif;
+  font-weight: 600;
+}
+
+div.body h1 {
+  font-size: 2.5rem;
+}
+
+body {
+  font-family: "Instrument Sans", system, -apple-system, ".SFNSText-Regular", "San Francisco", "Roboto", "Segoe UI", "Helvetica Neue", "Lucida Grande", sans-serif;
+  line-height: 1.5;
+  letter-spacing: 0.01rem;
+}
+
+div.body p, div.body dd, div.body li {
+  line-height: 1.6;
+}
+
+@media screen and (max-width: 875px) {
+  /* hide search result thumbnails on mobile */
+  .pagefind-modular-list-thumb {
+    width: 0;
+  }
+  /* reduce height of search box */
+  .pagefind-modular-input-wrapper {
+    scale: 90%;
+  }
+  .logo {
+    scale: 60%;
+  }
+}
+
 
 /* dark theme */
 @media (prefers-color-scheme: dark) {
@@ -339,4 +413,25 @@ div.body p, div.body dd, div.body li, div.body blockquote {
     background-color: #8e8129;
   }
 
+  .search-results {
+    background-color: #313131;
+    box-shadow: 0 6px 10px rgb(0 0 0 / 0.8);
+  }
+  .pagefind-modular-list-excerpt, .pagefind-modular-list-title {
+      color: #eeeeee !important;
+  }
+
+  .pagefind-ui__form, .pagefind-modular-input, .search-results {
+    color: #ececec !important;
+  }
+
+  :root {
+    --pagefind-ui-primary: #eeeeee;
+    --pagefind-ui-text: #eeeeee;
+    --pagefind-ui-background: #152028;
+    --pagefind-ui-border: #152028;
+    --pagefind-ui-tag: #152028;
+  }
+
+
 }

_static/safari-pinned-tab.svg

@@ -1 +1,10 @@
-<svg version="1.0" xmlns="http://www.w3.org/2000/svg" width="1066.667" height="1066.667" viewBox="0 0 800 800"><path d="M266.5 149.6c-12.4 3.1-19.4 8.1-24.5 17.5l-3.5 6.4-.3 17.6-.4 17.6-4.3.6c-6.1.9-11.1 4.2-14.3 9.6l-2.7 4.6-.3 160.2L216 544H94v-15h49c34.4 0 49.6-.3 51.4-1.1 5-2.3 5.7-6.1 5.4-27.4l-.3-19.5-2.8-2.7-2.7-2.8-50-.3-50-.3V460h99l3.2-2.9 3.3-2.9V412l-2.8-2.7-2.7-2.8-50-.3-50-.3v-14.8l50-.3 50-.3 2.7-2.8 2.8-2.7v-42.2l-3.3-2.9-3.2-2.9H94v-99.8l-2.6-3.1c-3.6-4.3-9.3-4.4-13.5-.2l-2.9 2.9v113.4l2.9 2.9 2.9 2.9H180v16H80.8l-2.9 2.9-2.9 2.9v41.4l2.9 2.9 2.9 2.9H180v16H80.8l-2.9 2.9-2.9 2.9v41l2.6 3.1 2.6 3.1H180v16H81.1l-2.8 2.4-2.8 2.4-.3 21-.3 21 3 3.4 2.9 3.3 67.5.3 67.5.2.7 4.3c.4 2.3 1.3 5.3 2 6.7 2.8 5.4 10.1 10 15.9 10h3.5l.3 19.7c.3 19 .4 20 3 25.5 5.4 11.6 15.2 18.1 28.3 18.6 9.8.5 17.1-1.9 23.7-7.7 9.3-8.2 11.8-17 11.8-41.4V585h12v15.3c0 8.4.5 18 1.1 21.3 2.2 11.9 9.9 21.4 20.8 25.5 7.8 2.9 19.4 2.4 26.6-1.3 6.4-3.4 12.8-10 15.7-16.3 2.1-4.6 2.3-6.7 2.6-24.8l.4-19.7h12.6l.4 19.7c.3 17.7.6 20.3 2.5 24.5 2.9 6.3 9.7 13.4 15.8 16.6 7.2 3.7 18.8 4.2 26.6 1.3 7.9-3 14.1-8.8 18.1-16.9l3.3-6.7.3-19.3.4-19.3 6.1.3 6.2.3.5 20c.5 19.5.6 20.1 3.3 25.3 3.5 6.7 9 12.2 15.3 15.3 4.1 2 6.4 2.4 14.4 2.4 8.1 0 10.3-.4 14.5-2.4 6.3-3.2 12.4-9.3 15.6-15.6 2.2-4.7 2.4-6.3 2.9-25l.5-20 6.1-.3 6.2-.3.3 19.3.4 19.3 3.3 6.7c4 8.1 10.2 13.9 18.1 16.9 7.8 2.9 19.4 2.4 26.6-1.3 6.1-3.2 12.9-10.3 15.8-16.6 2-4.2 2.2-6.7 2.5-24.5l.4-19.7h12.6l.4 19.7c.3 22.6 1.3 26.1 9.1 34.1 6.4 6.7 12.7 9.5 22.2 10 9.8.5 17-1.9 23.7-7.7 9.2-8.2 11.8-17 11.8-41.2v-14.6l4.5-.5c5.4-.7 10.2-3.7 13.6-8.7l2.4-3.6.3-173c.2-121 0-174.1-.8-176.7-2.1-7.2-10.2-13.7-17.1-13.8h-2.6l-.5-16.9c-.4-16.6-.5-17-3.6-23.4-5.9-12-16.9-19-29.6-19-13.6 0-24.8 7-30.4 19.1-2.5 5.4-2.7 6.7-3 22.9l-.4 17.3H623v-15.3c0-17.2-1.1-22.4-6.1-30.1-6.5-9.7-20.5-15.8-31.9-13.8-11.9 2.1-20.7 8.9-25.7 19.7-2.6 5.6-2.7 7-3.1 22.7l-.4 16.8H543v-16.5c0-14.1-.3-17.2-2-21.9-2.9-7.6-8.8-13.9-16.6-17.7-5.7-2.8-7.6-3.3-14.4-3.3-6.8 0-8.7.5-14.4 3.3-7.1 3.5-12.2 8.6-15.8 16-2.1 4.2-2.3 6.3-2.6 22.3l-.4 17.8h-12.6l-.4-16.8c-.6-19.7-1.7-23.7-8.8-31.5-8.6-9.5-20.5-13.2-32.1-10.2-10.5 2.6-18.2 9-22.8 18.5-2.4 5.1-2.6 6.6-2.9 22.7l-.4 17.3H384v-15.3c0-17.2-1.1-22.4-6.1-30.1-6.5-9.7-20.5-15.8-31.9-13.8-11.9 2.1-20.7 9-25.8 20.1-2.4 5.1-2.6 7-3 22.3l-.5 16.8H305v-12.3c0-21.3-2.8-30.7-11.3-38.4-7-6.2-20-10.4-27.2-8.7zm11.5 20.9c1.5.8 3.8 3 4.9 4.8 1.9 3.1 2.1 4.9 2.1 18.6V209h-28v-13.9c0-7.7.5-15.2 1.1-16.8 1.3-3.4 4.7-7.2 7.4-8.3 3.2-1.4 9.4-1.1 12.5.5zm81.6 1.6c4.6 4.2 5.4 7.6 5.4 22.9v14h-28v-15c0-16.9.8-19.6 6.3-23.1 4.5-2.8 12.7-2.2 16.3 1.2zm77.5-1.6c6 3.1 6.9 6.3 6.9 23.2V209h-28.2l.4-15.3c.2-12.7.6-15.8 2.1-18 4-6.1 12.4-8.4 18.8-5.2zm80.4.5c5.5 3.4 6.5 6.9 6.5 23.4V209h-28v-14.6c0-13 .2-15 2.1-18.3 1.1-2.1 3.3-4.5 4.7-5.4 3.7-2.3 10.7-2.2 14.7.3zm81.5 1.5c4.1 4 5 7.9 5 23.2V209h-28v-15c0-16.9.8-19.6 6.3-23.1 4.8-3 12.7-2.2 16.7 1.6zm77.1-2c6 3.1 6.9 6.3 6.9 23.2V209h-28v-13.9c0-7.7.5-15.2 1.1-16.8 1.3-3.4 4.7-7.2 7.4-8.3 3.3-1.4 9.4-1.1 12.6.5zm26.7 226.7l-.3 166.3-232.2.3-232.3.2V231h465l-.2 166.2zM285 602.3c0 14.8-.3 17.7-1.8 20.6-3.7 6.8-12.9 9.1-19.3 4.8-6.1-4-6.9-7.1-6.9-26V585h28v17.3zm79.5.7c0 19.5-.5 21.2-6.8 25-6.4 3.9-15.4 1.5-18.9-5.1-1.5-2.9-1.8-5.8-1.8-20.7v-17.3l13.8.3 13.7.3V603zm79.5-.3c0 15.7-.2 18.2-1.9 20.9-3.7 6.1-13.4 8.1-19.6 4-5-3.3-6-6.8-6.3-23.9-.2-8.7-.1-16.4.2-17.2.4-1.2 3.2-1.5 14.1-1.5H444v17.7zm80-.5c0 15.5-.2 17.6-2 20.6-4.3 7-12.8 9.2-19.1 4.9-6.1-4-6.9-7.1-6.9-26V585h28v17.2zm79.5.8c0 19.5-.5 21.2-6.8 25-6.1 3.8-14.9 1.7-18.7-4.5-1.8-2.9-2-4.9-2-20.9v-17.7l13.8.3 13.7.3V603zm79.5-.7c0 14.8-.3 17.7-1.8 20.6-3.7 6.8-12.9 9.1-19.3 4.8-6-4-6.9-7.1-6.9-25.3 0-8.8.3-16.4.7-16.7.3-.4 6.6-.7 14-.7H683v17.3z"/><path d="M413.7 359.8c-39.5 39.5-53.7 54.3-53.7 56 0 3.5 2.8 8.1 5.3 8.7 1.2.3 6.3.6 11.2.8l9 .2.5 32.3.5 32.4 2.4 1.9c2.2 1.8 5.1 1.9 82.1 1.9s79.9-.1 82.1-1.9l2.4-1.9.5-32.4.5-32.3 9-.2c11.8-.4 13.2-.8 15-4.3 2.8-5.4 2.1-6.6-11.5-20.5l-13-13.2v-22.4c-.1-16-.4-22.9-1.3-24-2.4-3.1-5.6-3.9-15.7-3.9-9.9 0-10.2.1-13.1 2.9-2.4 2.5-2.9 3.7-2.9 8 0 2.8-.3 5.1-.8 5.1-.4 0-11.3-10.6-24.2-23.5-21.8-21.8-23.7-23.5-27-23.5-3.3 0-6.6 3.1-57.3 53.8z"/></svg>
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_2_408)">
+<path d="M372.68 238.9L267.32 133.52C261.1 127.3 250.92 127.3 244.7 133.52L139.32 238.9C133.1 245.12 128 257.42 128 266.22V362.22C128 371.02 135.2 378.22 144 378.22H206.94V218.92C206.94 215.38 209.8 212.52 213.34 212.52H298.68C302.22 212.52 305.08 215.38 305.08 218.92V244.52C305.08 248.06 302.22 250.92 298.68 250.92H245.34V263.72H298.68C302.22 263.72 305.08 266.58 305.08 270.12V295.72C305.08 299.26 302.22 302.12 298.68 302.12H245.34V314.92H298.68C302.22 314.92 305.08 317.78 305.08 321.32V346.92C305.08 350.46 302.22 353.32 298.68 353.32H238.94C235.4 353.32 232.54 350.46 232.54 346.92C232.54 343.38 235.4 340.52 238.94 340.52H292.28V327.72H238.94C235.4 327.72 232.54 324.86 232.54 321.32V295.72C232.54 292.18 235.4 289.32 238.94 289.32H292.28V276.52H238.94C235.4 276.52 232.54 273.66 232.54 270.12V244.52C232.54 240.98 235.4 238.12 238.94 238.12H292.28V225.32H219.74V378.22H368C376.8 378.22 384 371.02 384 362.22V266.22C384 257.42 378.9 245.12 372.68 238.9Z" fill="#F2F4F9"/>
+</g>
+<defs>
+<clipPath id="clip0_2_408">
+<rect width="256" height="256" fill="white" transform="translate(128 128.62)"/>
+</clipPath>
+</defs>
+</svg>

_static/site.webmanifest

@@ -33,8 +33,8 @@
             "type": "image/png"
         }
     ],
-    "theme_color": "#dfdfdf",
+    "theme_color": "#18bcf2",
-    "background_color": "#dfdfdf",
+    "background_color": "#18bcf2",
     "start_url": "https://esphome.io/",
     "display": "standalone"
 }

_static/version

@@ -1 +1 @@
-2024.4.0b1
+2024.5.5

_templates/layout.html

@@ -5,6 +5,7 @@
 {% endblock %}
 
 {%- block extrahead %}
+  <link href="/pagefind/pagefind-modular-ui.css" rel="stylesheet">
   <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}?hash={{ custom_css_hash }}" type="text/css" />
   <link rel="apple-touch-icon" sizes="180x180" href="/_static/apple-touch-icon.png">
   <link rel="shortcut icon" href="/_static/favicon.ico">
@@ -15,27 +16,30 @@
   <link rel="icon" type="image/png" sizes="32x32" href="/_static/favicon-32x32.png">
   <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="mask-icon" href="/_static/safari-pinned-tab.svg" color="#18bcf2">
+  <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">
+  <meta name="msapplication-TileColor" content="#18bcf2">
   <meta name="msapplication-config" content="/_static/browserconfig.xml">
-  <meta name="theme-color" content="#dfdfdf">
+  <meta name="theme-color" content="#18bcf2">
   <meta name="HandheldFriendly" content="True">
   <meta name="MobileOptimized" content="320">
   <meta property="og:site_name" content="ESPHome">
-  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
+  <meta name="viewport"
+        content="width=device-width, initial-scale=1, maximum-scale=3, interactive-widget=overlays-content">
 {% endblock %}
 
 {% block relbar_top %}
-  {% if parents|length > 0 %}
   <ul class="breadcrumbs">
+  {% if parents|length > 0 %}
     {%- for doc in parents %}
       <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> ➔</li>
     {%- endfor %}
       <li>{{title}}</li>
-  </ul>
+
   {% endif %}
+  </ul>
 {% endblock %}
 
 {% block footer %}

_templates/search.html

@@ -0,0 +1,36 @@
+<!-- docs/_templates/search.html -->
+{% extends "page.html" %}
+
+{%- block htmltitle -%}
+<title>{{ _("Search") }} - {{ docstitle }}</title>
+{%- endblock htmltitle -%}
+
+{% block content %}
+<h1>{{ _("Search") }}</h1>
+<div id="search"></div>
+{% endblock %}
+
+{% block scripts -%}
+{{ super() }}
+{%- endblock scripts %}
+
+{% block extra_styles -%}
+{{ super() }}
+  <style type="text/css">
+    #search form input[type="text"] {
+      box-sizing: border-box;
+      width: 100%;
+      line-height: 2em;
+      padding-inline: 0.6em;
+      font-size: 1.2rem;
+      border-radius: 0.05rem;
+      border: 2px solid var(--color-foreground-border);
+      border-bottom-color: 2px solid var(--color-foreground-secondary);
+      transition: border-color 20ms ease;
+    }
+    #search form input[type="text"]:focus {
+      border-color: var(--color-foreground-primary);
+    }
+  </style>
+{%- endblock extra_styles %}
+

_templates/searchbox.html

@@ -0,0 +1,188 @@
+<script src="/pagefind/pagefind-modular-ui.js"></script>
+<div class="pagefind-ui__form" id="search"></div>
+<script>
+
+
+    class El {
+        constructor(tagname) {
+            this.element = document.createElement(tagname);
+        }
+
+        id(s) {
+            this.element.id = s;
+            return this;
+        }
+
+        class(s) {
+            this.element.classList.add(s);
+            return this;
+        }
+
+        attrs(obj) {
+            for (const [k,v] of Object.entries(obj)) {
+                this.element.setAttribute(k, v);
+            }
+            return this;
+        }
+
+        text(t) {
+            this.element.innerText = t;
+            return this;
+        }
+
+        html(t) {
+            this.element.innerHTML = t;
+            return this;
+        }
+
+        handle(e, f) {
+            this.element.addEventListener(e, f);
+            return this;
+        }
+
+        addTo(el) {
+            if (el instanceof El) {
+                el.element.appendChild(this.element);
+            } else {
+                el.appendChild(this.element);
+            }
+            return this.element;
+        }
+    }
+
+    window.addEventListener('DOMContentLoaded', (event) => {
+
+        const targetClass = "search-results";
+        const docel = document.getElementsByClassName("document");
+        if (docel.length === 0)
+            return;
+        const inpel = document.getElementById("search");
+        if (!inpel)
+            return;
+
+        var mobileWidth = getComputedStyle(document.body).getPropertyValue("--mobile-width-stop");
+
+        function isMobile() {
+            return window.innerWidth <= mobileWidth;
+        }
+
+        const target = document.createElement("div");
+        target.classList.add(targetClass);
+        target.id = targetClass;
+        target.style.display = "none";
+        docel.item(0).appendChild(target);
+
+        const margin = 20;
+
+        const resultTemplate = (result) => {
+            let wrapper = new El("li").class("pagefind-modular-list-result");
+
+            let thumb = new El("div").class("pagefind-modular-list-thumb").addTo(wrapper);
+            if (result?.meta?.image) {
+                new El("img").class("pagefind-modular-list-image").attrs({
+                    src: result.meta.image,
+                    alt: result.meta.image_alt || result.meta.title
+                }).addTo(thumb);
+            }
+
+            let inner = new El("div").class("pagefind-modular-list-inner").addTo(wrapper);
+            let title = new El("p").class("pagefind-modular-list-title").addTo(inner);
+            new El("a").class("pagefind-modular-list-link").text(result.meta?.title).attrs({
+                href: result.meta?.url || result.url
+            }).addTo(title);
+
+            let excerpt = new El("p").class("pagefind-modular-list-excerpt").addTo(inner);
+            new El("a").class("pagefind-modular-list-link").html(result.excerpt).attrs({
+                href: result.meta?.url || result.url
+            }).addTo(excerpt);
+
+            return wrapper.element;
+        }
+
+
+        function resizeTarget() {
+            const searchPos = inpel.getBoundingClientRect();
+            var leftPos;
+            var topPos;
+            var maxWidth = 650;
+            target.style.width = "auto;"
+            target.style.height = "fit-content";
+            target.style.maxWidth = maxWidth + "px";
+            let rightPos = margin;
+            if (isMobile()) {
+                // position search results left aligned with the search box, and below.
+                leftPos = margin / 2;
+                topPos = searchPos.bottom + margin / 2;
+                rightPos = margin / 2;
+            } else {
+                // position search results top aligned with the search box, and to its right.
+                leftPos = searchPos.right + margin * 2;
+                topPos = searchPos.top;
+                if (rightPos - leftPos > maxWidth)
+                    rightPos = leftPos + maxWidth;
+            }
+            target.style.right = rightPos + "px";
+            target.style.top = topPos + "px";
+            target.style.left = leftPos + "px";
+            let twidth = window.innerWidth - margin - leftPos;
+            if (twidth > maxWidth)
+                twidth = maxWidth;
+            target.style.width = twidth + "px";
+            target.style.maxHeight = (window.innerHeight - margin - topPos) + "px";
+        }
+
+        window.addEventListener("resize", (event) => { resizeTarget(); });
+
+        function showTarget() {
+            if (target.style.display !== "block") {
+                target.style.display = "block";
+                document.addEventListener('click', clickCallback);
+            }
+            resizeTarget();
+        }
+
+        function hideTargets() {
+            if (target.style.display !== "none") {
+                target.style.display = "none";
+                document.removeEventListener('click', clickCallback);
+            }
+        }
+
+
+        const instance = new PagefindModularUI.Instance({
+            showSubResults: true,
+            showImages: false,
+            ranking: {
+                pageLength: 0.0,
+                termSaturation: 1.6,
+                termFrequency: 0.4,
+                termSimilarity: 6.0
+            }
+        });
+
+        instance.add(new PagefindModularUI.Input({
+            containerElement: "#search"
+        }));
+
+        instance.add(new PagefindModularUI.ResultList({
+            containerElement: "#search-results",
+            resultTemplate: resultTemplate
+        }));
+
+        const clickCallback = (event) => {
+            const path = event.composedPath();
+            if (path.includes(target) || path.includes(inpel))
+                return;
+            hideTargets();
+        };
+        if (target) {
+            instance.on("results", (results) => {
+                if (results.results.length) {
+                    showTarget();
+                } else {
+                    hideTargets();
+                }
+            });
+        }
+    });
+</script>

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

changelog/2024.4.0.rst

@@ -20,6 +20,45 @@ ESPHome 2024.4.0 - 17th April 2024
     TLC5971, components/output/tlc5971, tlc5971.jpg
     Dooya, components/remote_transmitter, remote.svg
 
+
+Time Entities
+-------------
+
+ESPHome now has support for ``time`` entities that can be set from the frontend (like Home Assistant). THis allows you to set a timer to execute future automations on device.
+
+ESPHome Dates require Home Assistant 2024.4 or later.
+
+
+Voice Assistant Audio
+---------------------
+
+This release adds support for sending and receiving audio to/from voice assistants via the API. Currently ESPHome sends and receives the Voice Assistant audio bytes
+via a UDP socket which can be unreliable and insecure. Beginning with Home Assistant 2024.5, both sides will automatically recognise that they both support API Audio and will
+use that route instead. This is more reliable because the ESPHome API uses a TCP socket, so packet order and delivery is guaranteed, and if you use API Encryption,
+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
 --------------------
 
@@ -39,6 +78,16 @@ Breaking Changes
 - Add support for new modes in Tuya Climate :esphomepr:`5159` by :ghuser:`moriahmorgan` (breaking-change)
 - IPv6 string representation follows RFC5952 :esphomepr:`6449` by :ghuser:`HeMan` (breaking-change)
 
+Beta Changes
+^^^^^^^^^^^^
+
+- Add dooya remote transmitter test :esphomepr:`6508` by :ghuser:`jesserockz`
+- ads1115: remove auto-load and split sensor into platform folder :esphomepr:`5981` by :ghuser:`jesserockz` (new-platform)
+- Bump esphome-dashboard to 20240412.0 :esphomepr:`6517` by :ghuser:`jesserockz`
+- Fix missing ifdefs in voice assistant :esphomepr:`6520` by :ghuser:`jesserockz`
+- Fix project version longer than 30 characters breaking compilation :esphomepr:`6535` by :ghuser:`jesserockz`
+- Fix no-release bug on ft6x36 :esphomepr:`6527` by :ghuser:`clydebarrow`
+
 All changes
 ^^^^^^^^^^^
 
@@ -127,6 +176,12 @@ All changes
 - Add Dooya protocol to remote_base :esphomepr:`6488` by :ghuser:`bukureckid`
 - Only give error for connected sensors at startup :esphomepr:`6474` by :ghuser:`leejoow`
 - Webserver float to string fix :esphomepr:`6507` by :ghuser:`RFDarter`
+- Add dooya remote transmitter test :esphomepr:`6508` by :ghuser:`jesserockz`
+- ads1115: remove auto-load and split sensor into platform folder :esphomepr:`5981` by :ghuser:`jesserockz` (new-platform)
+- Bump esphome-dashboard to 20240412.0 :esphomepr:`6517` by :ghuser:`jesserockz`
+- Fix missing ifdefs in voice assistant :esphomepr:`6520` by :ghuser:`jesserockz`
+- Fix project version longer than 30 characters breaking compilation :esphomepr:`6535` by :ghuser:`jesserockz`
+- Fix no-release bug on ft6x36 :esphomepr:`6527` by :ghuser:`clydebarrow`
 
 Past Changelogs
 ---------------

changelog/2024.5.0.rst

@@ -0,0 +1,327 @@
+ESPHome 2024.5.0 - 15th May 2024
+================================
+
+.. seo::
+    :description: Changelog for ESPHome 2024.5.0.
+    :image: /_static/changelog-2024.5.0.png
+    :author: Jesse Hills
+    :author_twitter: @jesserockz
+
+.. imgtable::
+    :columns: 3
+
+
+    Valve Core, components/valve/index, folder-open.svg, dark-invert
+    Template Valve, components/valve/template, description.svg, dark-invert
+    Event Core, components/event/index, folder-open.svg, dark-invert
+    Template Event, components/event/template, description.svg, dark-invert
+    Template Time, components/datetime/template, description.svg, dark-invert
+    Template Datetime, components/datetime/template, description.svg, dark-invert
+    WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg
+
+
+Valves, Events, and More
+------------------------
+
+This release brings a new ``Valve`` component, which can be used to control valves.
+A ``Valve`` can be opened, closed, or a specific position set if supported.
+
+``Event`` entities were added to Home Assistant in `2023.8 <https://www.home-assistant.io/blog/2023/08/02/release-20238/#introducing-the-event-entity>`__.
+They allow better structure and also history and logging of the events sent from ESPHome to Home Assistant compared to just using publishing events onto the
+Home Assistant event bus with the ``homeassistant.event`` action.
+
+The ``datetime`` component has also been extended with ``DateTime`` and ``Time`` entity types this release.
+
+
+ESP32 ADC Attenuation
+---------------------
+
+The attenuation configuration option for ESP32 ``adc`` sensors has had a deprecation in the underlying ESP-IDF framework with the ``11dB`` option.
+The value to replace ``11dB`` with is ``12dB``. There are no functionality changes otherwise. There will be a warning in the logs when installing if you
+are using ``11dB`` and it will be removed in **2024.8.0**.
+
+Remote Receiver tolerance
+-------------------------
+
+The ``tolerance`` option in the ``remote_receiver`` component has been extended to allow time values, but at the same time the validation is now more strict.
+If you were using a raw value with no unit before 2024.5.0, for example ``25``, you will need to change it to ``25%``.
+
+
+Release 2024.5.1 - May 20
+-------------------------
+
+- Add device_class to valve core config :esphomepr:`6765` by :ghuser:`acshef`
+- Synchronise Device Classes from Home Assistant :esphomepr:`6768` by :ghuser:`esphomebot`
+- Fix Upload from Dashboard with MQTT discovery. :esphomepr:`6774` by :ghuser:`Links2004`
+- Fix MQTT dashboard discovery (Exception in MqttStatusThread). :esphomepr:`6775` by :ghuser:`Links2004`
+
+
+Release 2024.5.2 - May 21
+-------------------------
+
+- Revert "Fix MQTT dashboard discovery (Exception in MqttStatusThread)." :esphomepr:`6782` by :ghuser:`bdraco`
+- Fix DashboardEntries.all() call :esphomepr:`6783` by :ghuser:`bdraco`
+- [remote_receiver] Add better error message for tolerance breaking change :esphomepr:`6784` by :ghuser:`jesserockz`
+- Update webserver local assets to 20240519-215627 :esphomepr:`6779` by :ghuser:`esphomebot`
+
+
+Release 2024.5.3 - May 25
+-------------------------
+
+- [voice_assistant] Don't allocate buffers until starting the microphone for the first time :esphomepr:`6800` by :ghuser:`jesserockz`
+
+
+Release 2024.5.4 - May 28
+-------------------------
+
+- [web_server_base] Bump ESPAsyncWebServer-esphome to 3.2.2 :esphomepr:`6797` by :ghuser:`jesserockz`
+- [helpers] Move Base64 string to cpp :esphomepr:`6819` by :ghuser:`gabest11`
+
+
+Release 2024.5.5 - June 5
+-------------------------
+
+- [voice_assistant] Half the microphone ringbuffer size :esphomepr:`6830` by :ghuser:`jesserockz`
+- [i2s_speaker] Add buffer allocation failure checks :esphomepr:`6829` by :ghuser:`jesserockz`
+- [improv_serial] Fix for IDF 4.4.7 :esphomepr:`6855` by :ghuser:`kbx81`
+
+
+Full list of changes
+--------------------
+
+New Components
+^^^^^^^^^^^^^^
+
+- Add valve component :esphomepr:`6447` by :ghuser:`kbx81` (new-integration)
+- Add the WeiKai SPI/I2C UART/IO Expander components to esphome  :esphomepr:`5218` by :ghuser:`DrCoolzic` (new-integration)
+- Event entity support :esphomepr:`6451` by :ghuser:`nohat` (new-integration)
+- SPI and I2C for BMP390 and BMP380 :esphomepr:`6652` by :ghuser:`latonita` (new-integration) (breaking-change)
+
+Breaking Changes
+^^^^^^^^^^^^^^^^
+
+- Add DNS sensor and simplify format :esphomepr:`6450` by :ghuser:`HeMan` (breaking-change)
+- SM2135 - Use standard channel ordering. :esphomepr:`6573` by :ghuser:`Cossid` (breaking-change)
+- [sn74hc595] Enforce type field to distinguish gpio vs spi mode :esphomepr:`6609` by :ghuser:`jesserockz` (breaking-change)
+- Add datetime entities :esphomepr:`6513` by :ghuser:`jesserockz` (breaking-change)
+- SPI and I2C for BMP390 and BMP380 :esphomepr:`6652` by :ghuser:`latonita` (new-integration) (breaking-change)
+
+Beta Changes
+^^^^^^^^^^^^
+
+- [github] Upgrade to actions/[upload,download]-artifact v4 :esphomepr:`6698` by :ghuser:`jesserockz`
+- [nextion] Replace flags to ``USE_ARDUINO`` :esphomepr:`6700` by :ghuser:`edwardtfn`
+- [remote_receiver, remote_transmitter] Improve error messages on the ESP32 :esphomepr:`6701` by :ghuser:`Mat931`
+- [ethernet] Use constexpr instead of inline define for KSZ80XX_PC2R_REG_ADDR :esphomepr:`6705` by :ghuser:`jesserockz`
+- Add PHY register writes to enable external clock on Ethernet with RTL8201 :esphomepr:`6704` by :ghuser:`heythisisnate`
+- Bump recommended ESP-IDF to 4.4.7 :esphomepr:`6703` by :ghuser:`bdraco`
+- [core] Ensure that a generated ID name is distinct from its type. :esphomepr:`6706` by :ghuser:`clydebarrow`
+- [color] Fix crash when hex color parses as int, improve error reporting. :esphomepr:`6707` by :ghuser:`clydebarrow`
+- [github] Fix digest artifact name :esphomepr:`6710` by :ghuser:`jesserockz`
+- fix(ltr390): stuck ALS values when configured for ALS+UV readings :esphomepr:`6723` by :ghuser:`CodeInPolish`
+- Set FEATURE_API_AUDIO flag also if the speaker component is not used :esphomepr:`6712` by :ghuser:`gnumpi`
+- Bump platformio from 6.1.13 to 6.1.15 :esphomepr:`6634` by :ghuser:`dependabot[bot]`
+- Fix ESPHOME_PROJECT_VERSION_30 :esphomepr:`6731` by :ghuser:`jesserockz`
+- Voice-Assistant: Start-order change for VAD disabled: start va-pipeline when microphon… :esphomepr:`6391` by :ghuser:`gnumpi`
+- Add ANNOUNCING state to media_player. :esphomepr:`6691` by :ghuser:`gnumpi`
+- [adc] Fix 11db deprecation warning :esphomepr:`6749` by :ghuser:`jesserockz` (notable-change)
+
+Notable Changes
+^^^^^^^^^^^^^^^
+
+- [adc] Fix 11db deprecation warning :esphomepr:`6749` by :ghuser:`jesserockz` (notable-change)
+
+All changes
+^^^^^^^^^^^
+
+- Add some components to the new testing framework (H) :esphomepr:`6179` by :ghuser:`kbx81`
+- Added Htu21d model option :esphomepr:`6511` by :ghuser:`MRemy2`
+- Add bk72xx base test file :esphomepr:`6522` by :ghuser:`jesserockz`
+- Add "log" alias for "logs" command :esphomepr:`6519` by :ghuser:`pzich`
+- Add DNS sensor and simplify format :esphomepr:`6450` by :ghuser:`HeMan` (breaking-change)
+- Add all missing ``remote_receiver`` ``on_...`` tests :esphomepr:`6524` by :ghuser:`kbx81`
+- Add actions to http_request tests :esphomepr:`6529` by :ghuser:`kbx81`
+- Update homeassistant component tests with actions :esphomepr:`6528` by :ghuser:`kbx81`
+- Define ``USE_PSRAM`` :esphomepr:`6526` by :ghuser:`edwardtfn`
+- Bump black from 24.2.0 to 24.4.0 :esphomepr:`6539` by :ghuser:`dependabot[bot]`
+- Bump peter-evans/create-pull-request from 6.0.2 to 6.0.3 :esphomepr:`6525` by :ghuser:`dependabot[bot]`
+- Bump python version in sync-device-classes workflow to 3.12 for HA :esphomepr:`6541` by :ghuser:`jesserockz`
+- Bump pylint from 3.0.3 to 3.1.0 :esphomepr:`6287` by :ghuser:`dependabot[bot]`
+- Bump aioesphomeapi from 23.2.0 to 24.0.0 :esphomepr:`6544` by :ghuser:`dependabot[bot]`
+- Bump pyupgrade from 3.15.1 to 3.15.2 :esphomepr:`6543` by :ghuser:`dependabot[bot]`
+- Add enum option to typed_schema :esphomepr:`6546` by :ghuser:`jesserockz`
+- Move esphome-fork startup script to main repo. :esphomepr:`6523` by :ghuser:`jesserockz`
+- Call workflow for addon with dev version :esphomepr:`6549` by :ghuser:`jesserockz`
+- Use trusted publishing token for pypi :esphomepr:`6545` by :ghuser:`jesserockz`
+- Fix uart to work with new enum definition in esp-idf-v5.2.1 :esphomepr:`6487` by :ghuser:`luar123`
+- Housecleaning: Use walrus operator in datetime :esphomepr:`6552` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in text :esphomepr:`6560` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in light :esphomepr:`6556` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in select :esphomepr:`6557` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in number :esphomepr:`6561` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in cover :esphomepr:`6562` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in climate :esphomepr:`6551` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in fan :esphomepr:`6555` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in text_sensor :esphomepr:`6559` by :ghuser:`jesserockz`
+- Bump zeroconf to 0.132.2 :esphomepr:`6548` by :ghuser:`bdraco`
+- Housecleaning: Use walrus operator in switch :esphomepr:`6558` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in lock :esphomepr:`6554` by :ghuser:`jesserockz`
+- Housecleaning: Use walrus operator in sensor :esphomepr:`6553` by :ghuser:`jesserockz`
+- Bump pytest-mock from 3.12.0 to 3.14.0 :esphomepr:`6572` by :ghuser:`dependabot[bot]`
+- Bump peter-evans/create-pull-request from 6.0.3 to 6.0.4 :esphomepr:`6569` by :ghuser:`dependabot[bot]`
+- Nextion - Review set_protocol_reparse_mode() :esphomepr:`6567` by :ghuser:`edwardtfn`
+- Allow component final_validate :esphomepr:`6475` by :ghuser:`kbx81`
+- SM2135 - Use standard channel ordering. :esphomepr:`6573` by :ghuser:`Cossid` (breaking-change)
+- Nextion - Do not refresh sensors while updating :esphomepr:`6566` by :ghuser:`edwardtfn`
+- Nextion - Review types :esphomepr:`6565` by :ghuser:`edwardtfn`
+- On failure, dump the output of preceding jobs in CI status :esphomepr:`6564` by :ghuser:`clydebarrow`
+- Nextion ``send_command`` method :esphomepr:`6540` by :ghuser:`edwardtfn`
+- Fix some printf formats for size_t. :esphomepr:`6542` by :ghuser:`clydebarrow`
+- remove delay from tmp102 :esphomepr:`6577` by :ghuser:`ssieb`
+- Create ``component_dir`` substitution for local files to be included in… :esphomepr:`6575` by :ghuser:`jesserockz`
+- Define ``USE_ESP32_BLE`` :esphomepr:`6585` by :ghuser:`edwardtfn`
+- Bump aioesphomeapi from 24.0.0 to 24.3.0 :esphomepr:`6602` by :ghuser:`dependabot[bot]`
+- Add yamllint and clang-format to pre-commit hooks :esphomepr:`6578` by :ghuser:`clydebarrow`
+- Use clang-format version from requirements_dev file :esphomepr:`6606` by :ghuser:`jesserockz`
+- Add some components to the new testing framework (P) :esphomepr:`6213` by :ghuser:`kbx81`
+- Add some components to the new testing framework (M part 1) :esphomepr:`6207` by :ghuser:`kbx81`
+- Add some components to the new testing framework (M part 2) :esphomepr:`6208` by :ghuser:`kbx81`
+- Add some components to the new testing framework (O) :esphomepr:`6211` by :ghuser:`kbx81`
+- [mopeka_std_check] Fix test file indentation :esphomepr:`6610` by :ghuser:`jesserockz`
+- Add valve component :esphomepr:`6447` by :ghuser:`kbx81` (new-integration)
+- Add some components to the new testing framework (R) :esphomepr:`6219` by :ghuser:`kbx81`
+- [sn74hc595] Enforce type field to distinguish gpio vs spi mode :esphomepr:`6609` by :ghuser:`jesserockz` (breaking-change)
+- [tests] Run yaml tests in groups if over 100 to run :esphomepr:`6612` by :ghuser:`jesserockz`
+- Add some components to the new testing framework (I) :esphomepr:`6185` by :ghuser:`kbx81`
+- Add some components to the new testing framework (T) :esphomepr:`6229` by :ghuser:`kbx81`
+- Add some components to the new testing framework (S part 1) :esphomepr:`6224` by :ghuser:`kbx81`
+- Add some components to the new testing framework (S part 2) :esphomepr:`6227` by :ghuser:`kbx81`
+- ``graphical_display_menu`` requires a Display, not DisplayBuffer :esphomepr:`6614` by :ghuser:`clydebarrow`
+- Add null GPIO pin  :esphomepr:`6611` by :ghuser:`clydebarrow`
+- Allow UART to be AUTO LOADed :esphomepr:`6617` by :ghuser:`jesserockz`
+- Add the WeiKai SPI/I2C UART/IO Expander components to esphome  :esphomepr:`5218` by :ghuser:`DrCoolzic` (new-integration)
+- Sort mqtt_const alphabetically :esphomepr:`6619` by :ghuser:`jesserockz`
+- Limit Rx wait loop time to 3 seconds. :esphomepr:`6594` by :ghuser:`descipher`
+- Event entity support :esphomepr:`6451` by :ghuser:`nohat` (new-integration)
+- Only check c/c++ files with clang-format :esphomepr:`6620` by :ghuser:`jesserockz`
+- Added base64 helper :esphomepr:`4866` by :ghuser:`freekode`
+- Add Roomba IR protocol :esphomepr:`4595` by :ghuser:`rforro`
+- Fix issue when setting cw/ww brightness via temperature :esphomepr:`5976` by :ghuser:`patagonaa`
+- Add get/set color temperature functions in Kelvin :esphomepr:`5006` by :ghuser:`danielkent-net`
+- Move CONF_PLATFORM_VERSION to global const.py :esphomepr:`6629` by :ghuser:`tomaszduda23`
+- Ble client fixes for proxy :esphomepr:`6596` by :ghuser:`elupus`
+- Fix for #6614- use background_color, improve anti-aliasing :esphomepr:`6618` by :ghuser:`clydebarrow`
+- Fix graph hangs when y <= 0 :esphomepr:`6593` by :ghuser:`chiahsing`
+- Feature add last_operation to time based cover :esphomepr:`6084` by :ghuser:`xprofiler`
+- Add ``event``, ``text_sensor`` and ``valve`` device classes to sync script :esphomepr:`6624` by :ghuser:`kbx81`
+- Add datetime entities :esphomepr:`6513` by :ghuser:`jesserockz` (breaking-change)
+- Multiple Daly-BMS support :esphomepr:`6615` by :ghuser:`latonita`
+- Remove text_sensor from sync-device-class job :esphomepr:`6637` by :ghuser:`kbx81`
+- Synchronise Device Classes from Home Assistant :esphomepr:`6638` by :ghuser:`esphomebot`
+- Display: add diagnostic test_card option :esphomepr:`6608` by :ghuser:`nielsnl68`
+- waveshare_epaper: Add 2.90in-dke :esphomepr:`6492` by :ghuser:`polyfloyd`
+- Extract core comments from #6241 :esphomepr:`6643` by :ghuser:`javawizard`
+- [hm3301] Updated the AQI based on the airnow document :esphomepr:`6004` by :ghuser:`optimusprimespace`
+- Fix command line substitutions without any yaml substitutions :esphomepr:`6644` by :ghuser:`jesserockz`
+- Allow platform dependencies :esphomepr:`6623` by :ghuser:`kbx81`
+- [light] Add transition_length to strobe effect. :esphomepr:`6595` by :ghuser:`lhartmann`
+- Fixed the issue that graph draws out of the boundary. :esphomepr:`6651` by :ghuser:`chiahsing`
+- Fix upload command. MQTT user and password is missing from configuration. #5093 :esphomepr:`5766` by :ghuser:`dylan09`
+- patch esphome cli to skip mqtt based device discovery if --device option is specified :esphomepr:`6371` by :ghuser:`quigleymd`
+- Fix for #4866 - inconsistent arguments :esphomepr:`6639` by :ghuser:`clydebarrow`
+- [template/text] Fix lambda config :esphomepr:`6655` by :ghuser:`asergunov`
+- web_server: Add support for v3 local server_index :esphomepr:`6563` by :ghuser:`pzich`
+- Update webserver local assets to 20240429-211523 :esphomepr:`6657` by :ghuser:`esphomebot`
+- [nextion] Exit reparse before update TFT :esphomepr:`6589` by :ghuser:`edwardtfn`
+- [nextion] Set alternative TFT update baud rate :esphomepr:`6587` by :ghuser:`edwardtfn`
+- [TM1637] Let turn off the display :esphomepr:`6656` by :ghuser:`asergunov`
+- [nextion] Use persistent http connection for TFT upload (Arduino) :esphomepr:`6582` by :ghuser:`edwardtfn`
+- Extend MQTT tests :esphomepr:`6648` by :ghuser:`kbx81`
+- Extend and consolidate ``script`` tests :esphomepr:`6663` by :ghuser:`kbx81`
+- [nextion] Use persistent http connection for TFT upload (ESP-IDF) :esphomepr:`6576` by :ghuser:`edwardtfn`
+- Add a function to return the loop_interval :esphomepr:`6666` by :ghuser:`tronikos`
+- Remote receiver improvements :esphomepr:`4642` by :ghuser:`Mat931`
+- Make fast update intervals in qmc5883l work :esphomepr:`6647` by :ghuser:`tronikos`
+- SPI and I2C for BMP390 and BMP380 :esphomepr:`6652` by :ghuser:`latonita` (new-integration) (breaking-change)
+- Set ``CONF_`` CI counter to fail on 3 or more definitions :esphomepr:`6668` by :ghuser:`jesserockz`
+- [core] Rename ALWAYS_INLINE to ESPHOME_ALWAYS_INLINE :esphomepr:`6636` by :ghuser:`tomaszduda23`
+- print task name if logger is called from other than main thread :esphomepr:`6630` by :ghuser:`tomaszduda23`
+- Fix recent definitions into `defines.h` :esphomepr:`6667` by :ghuser:`edwardtfn`
+- Add fast update to HMC5883L :esphomepr:`6669` by :ghuser:`mkmer`
+- Minor tidy up of BME280 code :esphomepr:`6672` by :ghuser:`latonita`
+- External components: optional configurable path for git source :esphomepr:`6677` by :ghuser:`twasilczyk`
+- Use clang-apply-replacements when clang-apply-replacements-14 does not exist :esphomepr:`6684` by :ghuser:`Links2004`
+- fix conflict with EMPTY macro in zephyr :esphomepr:`6679` by :ghuser:`tomaszduda23`
+- Bump actions/checkout from 4.1.1 to 4.1.5 :esphomepr:`6685` by :ghuser:`dependabot[bot]`
+- Fix Datetime-Datetime compiler error :esphomepr:`6686` by :ghuser:`RFDarter`
+- Bump esphome/ESPAsyncWebServer-esphome to 3.2.0 :esphomepr:`6687` by :ghuser:`jesserockz`
+- fix date_time validation :esphomepr:`6688` by :ghuser:`RFDarter`
+- proceed if AP mode is set up :esphomepr:`6631` by :ghuser:`ssieb`
+- Migrate some constants to core code :esphomepr:`6692` by :ghuser:`clydebarrow`
+- Consolidate test files where all tests are identical :esphomepr:`6690` by :ghuser:`kbx81`
+- Make ``pulse_meter`` PULSE filter report the pulse as soon as it can :esphomepr:`6014` by :ghuser:`TrentHouliston`
+- Update webserver local assets to 20240507-231331 :esphomepr:`6696` by :ghuser:`esphomebot`
+- [github] Upgrade to actions/[upload,download]-artifact v4 :esphomepr:`6698` by :ghuser:`jesserockz`
+- [nextion] Replace flags to ``USE_ARDUINO`` :esphomepr:`6700` by :ghuser:`edwardtfn`
+- [remote_receiver, remote_transmitter] Improve error messages on the ESP32 :esphomepr:`6701` by :ghuser:`Mat931`
+- [ethernet] Use constexpr instead of inline define for KSZ80XX_PC2R_REG_ADDR :esphomepr:`6705` by :ghuser:`jesserockz`
+- Add PHY register writes to enable external clock on Ethernet with RTL8201 :esphomepr:`6704` by :ghuser:`heythisisnate`
+- Bump recommended ESP-IDF to 4.4.7 :esphomepr:`6703` by :ghuser:`bdraco`
+- [core] Ensure that a generated ID name is distinct from its type. :esphomepr:`6706` by :ghuser:`clydebarrow`
+- [color] Fix crash when hex color parses as int, improve error reporting. :esphomepr:`6707` by :ghuser:`clydebarrow`
+- [github] Fix digest artifact name :esphomepr:`6710` by :ghuser:`jesserockz`
+- fix(ltr390): stuck ALS values when configured for ALS+UV readings :esphomepr:`6723` by :ghuser:`CodeInPolish`
+- Set FEATURE_API_AUDIO flag also if the speaker component is not used :esphomepr:`6712` by :ghuser:`gnumpi`
+- Bump platformio from 6.1.13 to 6.1.15 :esphomepr:`6634` by :ghuser:`dependabot[bot]`
+- Fix ESPHOME_PROJECT_VERSION_30 :esphomepr:`6731` by :ghuser:`jesserockz`
+- Voice-Assistant: Start-order change for VAD disabled: start va-pipeline when microphon… :esphomepr:`6391` by :ghuser:`gnumpi`
+- Add ANNOUNCING state to media_player. :esphomepr:`6691` by :ghuser:`gnumpi`
+- [adc] Fix 11db deprecation warning :esphomepr:`6749` by :ghuser:`jesserockz` (notable-change)
+
+Past Changelogs
+---------------
+
+- :doc:`2024.4.0`
+- :doc:`2024.3.0`
+- :doc:`2024.2.0`
+- :doc:`2023.12.0`
+- :doc:`2023.11.0`
+- :doc:`2023.10.0`
+- :doc:`2023.9.0`
+- :doc:`2023.8.0`
+- :doc:`2023.7.0`
+- :doc:`2023.6.0`
+- :doc:`2023.5.0`
+- :doc:`2023.4.0`
+- :doc:`2023.3.0`
+- :doc:`2023.2.0`
+- :doc:`2022.12.0`
+- :doc:`2022.11.0`
+- :doc:`2022.10.0`
+- :doc:`2022.9.0`
+- :doc:`2022.8.0`
+- :doc:`2022.6.0`
+- :doc:`2022.5.0`
+- :doc:`2022.4.0`
+- :doc:`2022.3.0`
+- :doc:`2022.2.0`
+- :doc:`2022.1.0`
+- :doc:`2021.12.0`
+- :doc:`2021.11.0`
+- :doc:`2021.10.0`
+- :doc:`2021.9.0`
+- :doc:`2021.8.0`
+- :doc:`v1.20.0`
+- :doc:`v1.19.0`
+- :doc:`v1.18.0`
+- :doc:`v1.17.0`
+- :doc:`v1.16.0`
+- :doc:`v1.15.0`
+- :doc:`v1.14.0`
+- :doc:`v1.13.0`
+- :doc:`v1.12.0`
+- :doc:`v1.11.0`
+- :doc:`v1.10.0`
+- :doc:`v1.9.0`
+- :doc:`v1.8.0`
+- :doc:`v1.7.0`

changelog/index.rst

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

changelog/v1.9.0.rst

@@ -30,7 +30,7 @@ awesome things with DIY hardware!
 
 The features I'm particularly excited about are:
 
-* :ref:`esphomeflasher <esphome-flasher>` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
+* ``esphomeflasher`` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
   No problem, esphomeflasher is a tool designed to make that super easy. Just let esphomeyaml generate the binary and flash
   from your PC.
 * :doc:`Over-the-Air Updates </components/ota>` have been completely re-written to make them a lot more
@@ -76,7 +76,7 @@ New Features
 
 - esphomelib now has a new tool: `esphomeflasher <https://github.com/esphome/esphome-flasher>`__ to simplify
   flashing on Windows/MacOS machines **without having to install esphomeyaml**. So if esphomeyaml for some reason
-  can't find your USB port, you now can use the esphomeflasher app. See :ref:`esphome-flasher`.
+  can't find your USB port, you now can use the esphomeflasher app. See ``esphomeflasher``.
 
 - ESP8266s now save the states of lights/switches/... internally and restores them on boot.
   Additionally, esphomelib can now operate in fully offline mode if your WiFi network goes down

components/alarm_control_panel/template.rst

@@ -27,8 +27,8 @@ Configuration variables:
 - **codes** (*Optional*, list of string): A list of codes for disarming the alarm, if *requires_code_to_arm* set to true then for arming the alarm too.
 - **requires_code_to_arm** (*Optional*, boolean): Code required for arming the alarm, *codes* must be provided.
 - **arming_away_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to away mode. Defaults to ``0s``.
-- **arming_home_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to home mode.  
+- **arming_home_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to home mode.
-- **arming_night_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to night mode.  
+- **arming_night_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to night mode.
 - **pending_time** (*Optional*, :ref:`config-time`): The entry delay before the alarm is triggered. Defaults to ``0s``.
 - **trigger_time** (*Optional*, :ref:`config-time`): The time after a triggered alarm before resetting to previous state if the sensors are cleared/off. Defaults to ``0s``.
 - **binary_sensors** (*Optional*, *list*): A list of binary sensors the panel should use. Each consists of:
@@ -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

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

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:
 ************************
@@ -127,8 +116,8 @@ Actions
 
 .. warning::
 
-    The hardware frontend reset option is only required to reset the frontend in case it is struck, before sending the 
+    The hardware frontend reset option is only required to reset the frontend in case it is struck, before sending the
-    new configuration. However, a frontend reset is always performed after changing the settings. 
+    new configuration. However, a frontend reset is always performed after changing the settings.
 
 The radar has several settings which can be changed. These settings are not saved in non-volatile memory
 and need to be set on each boot.

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
 

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
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    and will be removed from ESPHome in a future release.
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    Please look at creating a real ESPHome component and "importing" it into your
+    :doc:`/components/external_components`.
-    configuration with :doc:`/components/external_components`.
 
-    You can find some basic documentation on creating your own components
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-    at :ref:`contributing_to_esphome`.
 
-This integration can be used to create custom binary sensors in ESPHome
+.. warning::
-using the C++ (Arduino) API.
 
-Please first read :doc:`/components/sensor/custom` guide,
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
-the same principles apply here and binary sensors are very similar
+    stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
-to sensors internally.
+
+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.

components/binary_sensor/esp32_touch.rst

@@ -130,8 +130,8 @@ an ``OFF`` state.
 
     binary_sensor:
       - platform: esp32_touch
-        name: "ESP32 Touch Pad GPIO27"
+        name: "ESP32 Touch Pad"
-        pin: GPIO27
+        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:
@@ -174,8 +174,8 @@ If access to the raw values is required, a template sensor can be created that p
             return id(esp32_touch_pad).get_value();
         update_interval: 3s
 
-One example of use is a wide area pressure sensor that integrates a number of smaller sensors in an area. Make two strips 
+One example of use is a wide area pressure sensor that integrates a number of smaller sensors in an area. Make two strips
-of aluminium foil that sandwich paper, and connect one wire to a touch pin and the other to ground. Set up several sensors 
+of aluminium foil that sandwich paper, and connect one wire to a touch pin and the other to ground. Set up several sensors
 under a flexible object like a plastic mat, add the raw values, and apply a threshold.
 
 .. _esp32-touch-pad-pins:

components/binary_sensor/haier.rst

@@ -17,17 +17,17 @@ Additional sensors for Haier Climate device. **These sensors are supported only
     # Example configuration entry
     uart:
       baud_rate: 9600
-      tx_pin: 17
+      tx_pin: GPIOXX
-      rx_pin: 16
+      rx_pin: GPIOXX
       id: ac_port
-    
+
     climate:
       - platform: haier
         id: haier_ac
         protocol: hOn
         name: Haier AC
         uart_id: ac_port
-    
+
     binary_sensor:
       - platform: haier
         haier_id: haier_ac
@@ -56,9 +56,9 @@ Configuration variables:
   All options from :ref:`Binary Sensor <config-binary_sensor>`.
 - **indoor_electric_heating_status** (*Optional*): A binary sensor that indicates electrical heating system activity.
   All options from :ref:`Binary Sensor <config-binary_sensor>`.
-- **indoor_fan_status** (*Optional*): A binary sensor that indicates indoor fan activity. 
+- **indoor_fan_status** (*Optional*): A binary sensor that indicates indoor fan activity.
   All options from :ref:`Binary Sensor <config-binary_sensor>`.
-- **outdoor_fan_status** (*Optional*): A binary sensor that indicates outdoor fan activity. 
+- **outdoor_fan_status** (*Optional*): A binary sensor that indicates outdoor fan activity.
   All options from :ref:`Binary Sensor <config-binary_sensor>`.
 
 See Also

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

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"

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

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

components/bluetooth_proxy.rst

@@ -32,7 +32,7 @@ our `Bluetooth Proxy installer <https://esphome.github.io/bluetooth-proxies/>`__
 
     The :doc:`web_server` component should be disabled as the device is likely
     to run out of memory and will malfunction when both components are enabled simultaneously.
-    
+
     Not all devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported,
     please search for it in the `Home Assistant Integrations <https://www.home-assistant.io/integrations/>`__ list.
 
@@ -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
 -------------------------------
 

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:

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"

components/canbus.rst

@@ -69,7 +69,7 @@ Configuration variables:
     - ``12K5BPS`` - Support by ``esp32_can`` depends on ESP32 variant
     - ``16KBPS`` - Support by ``esp32_can`` depends on ESP32 variant
     - ``20KBPS`` - Support by ``esp32_can`` depends on ESP32 variant
-    - ``25KBPS`` 
+    - ``25KBPS``
     - ``31K25BPS`` - Not supported by ``esp32_can``
     - ``33KBPS`` - Not supported by ``esp32_can``
     - ``40KBPS`` - Not supported by ``esp32_can``
@@ -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
+        tx_pin: GPIOXX
-        rx_pin: GPIO4
+        rx_pin: GPIOXX
         can_id: 4
         bit_rate: 50kbps
         on_frame:
@@ -209,28 +209,28 @@ You only need to specify the RX and TX pins. Any GPIO will work.
 
 The table lists the specific bit rates supported by the component for ESP32 variants:
  =================== ======= ========== ========== ========== ========== ==========
-  bit_rate            ESP32   ESP32-S2   ESP32-S3   ESP32-C3   ESP32-C6   ESP32-H2   
+  bit_rate            ESP32   ESP32-S2   ESP32-S3   ESP32-C3   ESP32-C6   ESP32-H2
  =================== ======= ========== ========== ========== ========== ==========
-  1KBPS                        x          x          x          x          x          
+  1KBPS                        x          x          x          x          x
-  5KBPS                        x          x          x          x          x          
+  5KBPS                        x          x          x          x          x
-  10KBPS                       x          x          x          x          x          
+  10KBPS                       x          x          x          x          x
-  12K5BPS                      x          x          x          x          x          
+  12K5BPS                      x          x          x          x          x
-  16KBPS                       x          x          x          x          x          
+  16KBPS                       x          x          x          x          x
-  20KBPS                       x          x          x          x          x          
+  20KBPS                       x          x          x          x          x
-  25KBPS               x       x          x          x          x          x          
+  25KBPS               x       x          x          x          x          x
-  31K25BPS                                                                           
+  31K25BPS
-  33KBPS                                                                              
+  33KBPS
-  40KBPS                                                                              
+  40KBPS
-  50KBPS               x       x          x          x          x          x          
+  50KBPS               x       x          x          x          x          x
-  80KBPS                                                                              
+  80KBPS
-  83K38BPS                                                                           
+  83K38BPS
-  95KBPS                                                                              
+  95KBPS
-  100KBPS              x       x          x          x          x          x          
+  100KBPS              x       x          x          x          x          x
-  125KBPS (Default)    x       x          x          x          x          x          
+  125KBPS (Default)    x       x          x          x          x          x
-  250KBPS              x       x          x          x          x          x          
+  250KBPS              x       x          x          x          x          x
-  500KBPS              x       x          x          x          x          x          
+  500KBPS              x       x          x          x          x          x
-  800KBPS              x       x          x          x          x          x          
+  800KBPS              x       x          x          x          x          x
-  1000KBPS             x       x          x          x          x          x          
+  1000KBPS             x       x          x          x          x          x
  =================== ======= ========== ========== ========== ========== ==========
 
 
@@ -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
+      clk_pin: GPIOXX
-      mosi_pin: GPIO5
+      mosi_pin: GPIOXX
-      miso_pin: GPIO4
+      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
+      clk_pin: GPIOXX
-      mosi_pin: GPIO5
+      mosi_pin: GPIOXX
-      miso_pin: GPIO4
+      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:

components/climate/bang_bang.rst

@@ -10,8 +10,7 @@ The ``bang_bang`` climate platform allows you to regulate a value with a
 
 .. note::
 
-    A number of people have asked about the behavior of the bang-bang controller. In version 1.15, a
+    The :doc:`thermostat <thermostat>` component behaves more like a common thermostat; it is
-    :doc:`thermostat <thermostat>` component was added which behaves more like a common thermostat; it is
     essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below
     if you are not sure which is appropriate for your application.
 

components/climate/climate_ir.rst

@@ -44,7 +44,7 @@ submit a feature request (see FAQ).
 +---------------------------------------+---------------------+----------------------+
 | :ref:`LG<climate_ir_lg>`              | ``climate_ir_lg``   | yes                  |
 +---------------------------------------+---------------------+----------------------+
-| Midea                                 | ``midea_ir``        | yes                  |
+| :ref:`Midea<midea_ir>`                | ``midea_ir``        | yes                  |
 +---------------------------------------+---------------------+----------------------+
 | :ref:`Mitsubishi<mitsubishi>`         | ``mitsubishi``      | yes                  |
 +---------------------------------------+---------------------+----------------------+
@@ -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
@@ -169,35 +169,6 @@ IR receiver.
         name: "Living Room AC"
         receiver_id: rcvr
 
-.. _midea_ir:
-
-``midea_ir`` Climate
--------------------------
-
-These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states.
-
-Additional configuration is available for this platform
-
-
-Configuration variables:
-
-- **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``.
-
-.. code-block:: yaml
-
-    # Example configuration entry
-    climate:
-      - platform: midea_ir
-        name: "AC"
-        sensor: room_temperature
-        use_fahrenheit: true
-
-.. note::
-
-    - See :ref:`Transmit Midea<remote_transmitter-transmit_midea>` to send custom commands, including Follow Me mode.
-    - See :ref:`Toshiba<toshiba>` below if you are looking for compatibility with Midea model MAP14HS1TBL or similar.
-
-
 .. _climate_ir_lg:
 
 ``climate_ir_lg`` Climate
@@ -272,6 +243,34 @@ Known working with:
 
 - Delonghi PAC WE 120HP
 
+.. _midea_ir:
+
+``midea_ir`` Climate
+-------------------------
+
+These air conditioners support two protocols: Midea and Coolix. Therefore, when using an IR receiver, it considers both protocols and publishes the received states.
+
+Additional configuration is available for this platform
+
+
+Configuration variables:
+
+- **use_fahrenheit** (*Optional*, boolean): Allows you to transfer the temperature to the air conditioner in degrees Fahrenheit. The air conditioner display also shows the temperature in Fahrenheit. Defaults to ``false``.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    climate:
+      - platform: midea_ir
+        name: "AC"
+        sensor: room_temperature
+        use_fahrenheit: true
+
+.. note::
+
+    - See :ref:`Transmit Midea<remote_transmitter-transmit_midea>` to send custom commands, including Follow Me mode.
+    - See :ref:`Toshiba<toshiba>` below if you are looking for compatibility with Midea model MAP14HS1TBL or similar.
+
 .. _mitsubishi:
 
 ``mitsubishi`` Climate
@@ -283,8 +282,8 @@ Configuration variables:
 
 - **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to ``3levels``
 
-  - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``. 
+  - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``.
-  
+
     - ``3levels``; Low [fan speed 1], Medium [2], High [3]
     - ``4levels``; Low [1], Middle [2], Medium [3], High [4]
     - ``quiet_4levels``; Low [1], Middle [2], Medium [3], High [4], Quiet [5]
@@ -292,10 +291,10 @@ Configuration variables:
 - **supports_dry** (*Optional*, boolean): Enables setting dry mode for this unit. Defaults to ``false``.
 - **supports_fan_only** (*Optional*, boolean): Enables setting fan only mode for this unit. Confirm that mode is supported on your remote. Defaults to ``false``.
 
-- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``. 
+- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``.
 
   - Options are: ``left``, ``middle-left``, ``middle``, ``middle-right``, ``right``, ``auto``
-- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``. 
+- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``.
 
   - Options are: ``down``, ``middle-down``, ``middle``, ``middle-up``, ``up``, ``auto``
 
@@ -423,8 +422,8 @@ Configuration variables:
 ``zhlt01`` Climate
 ---------------------
 
-ZH/LT-01 is a remote control that is used with many locally branded split airconditioners. 
+ZH/LT-01 is a remote control that is used with many locally branded split airconditioners.
-Supported brands include: 
+Supported brands include:
 
 - Eurom
 - Chigo

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
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    and will be removed from ESPHome in a future release.
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    Please look at creating a real ESPHome component and "importing" it into your
+    :doc:`/components/external_components`.
-    configuration with :doc:`/components/external_components`.
 
-    You can find some basic documentation on creating your own components
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-    at :ref:`contributing_to_esphome`.
 
-This integration can be used to create custom climate devices in ESPHome
+.. warning::
-using the C++ (Arduino) API.
 
-Please first read :doc:`/components/sensor/custom` guide,
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
-the same principles apply here.
+    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>`):

components/climate/haier.rst

@@ -58,18 +58,11 @@ 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
         protocol: hOn
-        name: Haier AC 
+        name: Haier AC
         uart_id: ac_port
         wifi_signal: true
         beeper: true

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:

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

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

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
+    Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
-    and will be removed from ESPHome in a future release.
+    future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
-    Please look at creating a real ESPHome component and "importing" it into your
+    :doc:`/components/external_components`.
-    configuration with :doc:`/components/external_components`.
 
-    You can find some basic documentation on creating your own components
+    You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-    at :ref:`contributing_to_esphome`.
 
-This integration can be used to create custom covers in ESPHome
+.. warning::
-using the C++ (Arduino) API.
 
-Please first read :doc:`/components/sensor/custom` guide,
+    While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
-the same principles apply here.
+    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
+This component can be used to create custom covers in ESPHome using the C++ (Arduino) API.
-two methods:
+
+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.

components/cover/he60r.rst

@@ -26,8 +26,8 @@ below for a sample hardware interface.
         baud_rate: 1200
         parity: even
         stop_bits: 1
-        tx_pin: REPLACEME
+        tx_pin: GPIOXX
-        rx_pin: REPLACEME
+        rx_pin: GPIOXX
 
     cover:
       platform: he60r
@@ -72,9 +72,9 @@ Note that this circuit inverts the TX line. A configuration for this would look
         parity: even
         stop_bits: 1
         tx_pin:
-          number: REPLACEME
+          number: GPIOXX
           inverted: true
-        rx_pin: REPLACEME
+        rx_pin: GPIOXX
 
     cover:
       platform: he60r
@@ -84,7 +84,7 @@ Note that this circuit inverts the TX line. A configuration for this would look
     binary_sensor:
       - platform: gpio
         pin:
-          number: REPLACEME
+          number: GPIOXX
           inverted: true
           mode:
             input: true

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:

components/cover/template.rst

@@ -62,7 +62,6 @@ Configuration variables:
   of hiding one of them. Defaults to ``false``.
 - **has_position** (*Optional*, boolean): Whether this cover will publish its position as a floating point number.
   By default (``false``), the cover only publishes OPEN/CLOSED position.
-  Parameter useless if you set the POSITION_ACTION (is set to TRUE).
 - **tilt_action** (*Optional*, :ref:`Action <config-action>`): The action that should
   be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
   tilt position. The desired tilt is available in the lambda in the ``tilt`` variable.
@@ -71,6 +70,7 @@ Configuration variables:
 - **position_action** (*Optional*, :ref:`Action <config-action>`): The action that should
   be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
   position. The desired position is available in the lambda in the ``pos`` variable.
+  Useless if `has_position` is not set to ``true``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - All other options from :ref:`Cover <config-cover>`.
 

components/cover/time_based.rst

@@ -77,7 +77,25 @@ 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 following lambda function:
 
+.. code-block:: yaml
+
+    stop_action: 
+      - lambda: !lambda |-
+          if (id(cover).get_last_operation() == CoverOperation::COVER_OPERATION_OPENING) {
+            // Cover is currently opening
+            id(cover_button_down).press();
+          } else if (id(cover).get_last_operation() == CoverOperation::COVER_OPERATION_CLOSING) {
+            // Cover is currently closing
+            id(cover_button_up).press();
+          }
+
+Be aware that ``get_last_operation`` will only return the last opening or closing operation, but not the last idle operation. 
+This issue is tracked `here <https://github.com/esphome/issues/issues/4252#issuecomment-2132727377>`_.
 
 See Also
 --------

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)
 

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
+- **on_time** (*Optional*, :ref:`automation`): Automation to run when the current datetime or time matches the current state.
-``id(datetime_id).state``.
+  Only valid on ``time`` or ``datetime`` types.
-You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time``
+
+Automation
+----------
+
+You can access the most recent state as a ``ESPTime`` object by ``id(datetime_id).state_as_esptime()``
 
 .. _datetime-on_value:
 
@@ -98,12 +103,12 @@ The ``date`` provided can be in one of 3 formats:
 
     # String date
     - datetime.date.set:
-        id: my_date
+        id: my_datetime_date
         date: "2023-12-04"
 
     # Individual date parts
     - datetime.date.set:
-        id: my_date
+        id: my_datetime_date
         date:
           year: 2023
           month: 12
@@ -111,7 +116,7 @@ The ``date`` provided can be in one of 3 formats:
 
     # Using a lambda
     - datetime.date.set:
-        id: my_date
+        id: my_datetime_date
         date: !lambda |-
           // Return an ESPTime struct
           return {.day_of_month: 4, .month: 12, .year: 2023};
@@ -137,7 +142,7 @@ advanced stuff (see the full API Reference for more info).
   .. code-block:: cpp
 
       // Within lambda, set the date to 2024-02-25
-      auto call = id(my_date).make_call();
+      auto call = id(my_datetime_date).make_call();
       call.set_date("2024-02-25");
       call.perform();
 
@@ -169,12 +174,12 @@ The ``time`` provided can be in one of 3 formats:
 
     # String time
     - datetime.time.set:
-        id: my_time
+        id: my_datetime_time
         time: "12:34:56"
 
     # Individual time parts
     - datetime.time.set:
-        id: my_time
+        id: my_datetime_time
         time:
           hour: 12
           minute: 34
@@ -182,7 +187,7 @@ The ``time`` provided can be in one of 3 formats:
 
     # Using a lambda
     - datetime.time.set:
-        id: my_time
+        id: my_datetime_time
         time: !lambda |-
           // Return an ESPTime struct
           return {.second: 56, .minute: 34, .hour: 12};
@@ -207,8 +212,8 @@ advanced stuff (see the full API Reference for more info).
   .. code-block:: cpp
 
       // Within lambda, set the time to 12:34:56
-      auto call = id(my_time).make_call();
+      auto call = id(my_datetime_time).make_call();
-      call.set_date("12:34:56");
+      call.set_time("12:34:56");
       call.perform();
 
   Check the API reference for information on the methods that are available for
@@ -222,7 +227,85 @@ advanced stuff (see the full API Reference for more info).
   .. code-block:: cpp
 
       // For example, create a custom log message when a value is received:
-      ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_time).second);
+      ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_datetime_time).hour, id(my_datetime_time).minute, id(my_datetime_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
@@ -231,8 +314,10 @@ 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::

components/datetime/template.rst

@@ -13,7 +13,7 @@ using :ref:`lambdas <config-lambda>`.
     datetime:
       # Example Date
       - platform: template
-        id: my_date
+        id: my_datetime_date
         type: date
         name: Pick a Date
         optimistic: yes
@@ -22,13 +22,22 @@ using :ref:`lambdas <config-lambda>`.
 
       # Example Time
       - platform: template
-        id: my_time
+        id: my_datetime_time
         type: time
         name: Pick a Time
         optimistic: yes
         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

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
+The ``demo`` component can be used for testing to generate sample instances of many
-different integrations (sensors, lights, ...)
+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
 --------

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>`
+For this component to work you need to have set up a :ref:`UART bus <uart>` in your configuration.
-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:
 ------------------------
@@ -114,11 +104,11 @@ Configuration options:
 ``dfplayer.play_mp3`` Action
 ----------------------------
 
-Plays a track inside the folder ``mp3``. Files inside the folder must be numbered from 1 
+Plays a track inside the folder ``mp3``. Files inside the folder must be numbered from 1
 to 9999, like ``0001.mp3``, ``0002.mp3``, ... etc.
-The folder name needs to be ``mp3``, placed under the SD card root directory, and the 
+The folder name needs to be ``mp3``, placed under the SD card root directory, and the
-mp3 file name needs to be 4 digits, for example, "0001.mp3", placed under the mp3 folder. 
+mp3 file name needs to be 4 digits, for example, "0001.mp3", placed under the mp3 folder.
-If you want, you can add additional text after the number in the filename, for example, 
+If you want, you can add additional text after the number in the filename, for example,
 ``0001hello.mp3``, but must always be referenced by number only in yaml.
 
 .. code-block:: bash
@@ -345,8 +335,8 @@ Sample code
 .. code-block:: yaml
 
     uart:
-      tx_pin: GPIO2
+      tx_pin: GPIOXX
-      rx_pin: GPIO5
+      rx_pin: GPIOXX
       baud_rate: 9600
 
     dfplayer:

components/dfrobot_sen0395.rst

@@ -36,7 +36,7 @@ a :doc:`/components/uart` component (and its requisite GPIO pins) is required in
         name: Mmwave Detected via GPIO
         device_class: motion
         pin:
-          number: REPLACEME
+          number: GPIOXX
           mode: INPUT_PULLDOWN
 
     switch:
@@ -97,7 +97,7 @@ If you don't want/need to change the radar's settings and only need to determine
         name: Presence Detected via GPIO
         device_class: motion
         pin:
-          number: REPLACEME
+          number: GPIOXX
           mode: INPUT_PULLDOWN
 
 .. _dfrobot_sen0395-via_uart:

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
@@ -61,10 +49,10 @@ Configuration variables:
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to call the lambda to update the display.
   Defaults to ``16ms``.
 - **pixel_mapper** (*Optional*, :ref:`lambda <config-lambda>`): A lambda that returns the integer address of the LED
-  given the supplied the ``x`` and ``y`` pixel coordinate. By default, a left-to-right direct pixel mapper is used. 
+  given the supplied the ``x`` and ``y`` pixel coordinate. By default, a left-to-right direct pixel mapper is used.
 - **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
   ``it`` will be an instance of :apiclass:`DisplayBuffer <display::DisplayBuffer>`.
-  See :ref:`display-engine` for more information. 
+  See :ref:`display-engine` for more information.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 
 
@@ -73,7 +61,7 @@ Configuration variables:
     When enabled (the default, but also via ``it.set_enabled(true)``), any effect currently running on the
     addressable light will be disabled. When disabled (``it.set_enabled(false)``), the last configured effect will
     be restored.
-    
+
     While the display is enabled, it is still possible to control the parent addressable light component in some
     limited capacity. Changing the brightness will still work, but changing the color will have no affect. It is not
     adivsable to enable any effects (ex: rainbow, color wipe, etc) while the display is enabled, as this will cause a

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
+        dc_pin: GPIOXX
-        reset_pin: 33
+        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
+        pin: GPIOXX
-        id: gpio_32_backlight_pwm
+        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
+        dc_pin: GPIOXX
-        reset_pin: 22
+        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
 

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
@@ -45,6 +45,9 @@ this behavior by setting ``auto_clear_enabled: false``.
 In the lambda, you can write code like in any :ref:`lambda <config-lambda>` in ESPHome. Display
 lambdas are additionally passed a variable called ``it`` which represents the rendering engine object.
 
+.. figure:: images/display_rendering_line.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
@@ -74,8 +77,10 @@ the rendering engine is always first specify the ``x`` coordinate and then the `
 Basic Shapes
 ------------
 
-Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles
+Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles, circles or even polygons:
-and circles:
+
+.. figure:: images/display_rendering_shapes.png
+    :align: center
 
 .. code-block:: yaml
 
@@ -85,31 +90,27 @@ and circles:
         lambda: |-
           // Draw a line from [0,0] to [100,50]
           it.line(0, 0, 100, 50);
-          // Draw an angled line from [0,0] at 45° with a length of 30
+          // Draw the outline of a rectangle with the top left at [5,20], a width of 30 and a height of 42
-          it.line_at_angle(0, 0, 45, 30);
+          it.rectangle(5, 20, 30, 42);
-          // Draw an angled line from [0,0] at 30° with a start radius of 10 and stop radius of 20
+          // Draw the same rectangle a few pixels apart, but this time filled
-          it.line_at_angle(0, 0, 30, 10, 20);
+          it.filled_rectangle(40, 40, 30, 42);
-          // Draw the outline of a rectangle with the top left at [50,60], a width of 30 and a height of 42
-          it.rectangle(50, 60, 30, 42);
-          // Draw the same rectangle, but this time filled.
-          it.filled_rectangle(50, 60, 30, 42);
 
-          // Circles! Let's draw one with the center at [25,25] and a radius of 10
+          // Circles! Let's draw one with the center at [20,40] and a radius of 10
-          it.circle(25, 25, 10);
+          it.circle(20, 40, 10);
           // ... and the same thing filled again
-          it.filled_circle(25, 25, 10);
+          it.filled_circle(20, 75, 10);
 
           // Triangles... Let's draw the outline of a triangle from the [x,y] coordinates of its three points
-          // [25,5], [5,25], [50,50]
+          // [25,5], [100,5], [80,25]
-          it.triangle(25, 5, 5, 25, 50, 50);
+          it.triangle(25, 5, 100, 5, 80, 25);
           // and a filled triangle !
-          it.filled_triangle(125, 5, 105, 25, 150, 50);
+          it.filled_triangle(115, 5, 95, 25, 125, 70);
 
-          // Regular Polygons? Let's draw the outline of a pointy-topped hexagon inscribed in a circle 
+          // Regular Polygons? Let's draw a filled, pointy-topped hexagon inscribed in a circle
-          // centered on [x1=100,y1=100] with a radius of 50
+          // centered on [170,45] with a radius of 20
-          it.regular_polygon(100, 100, 50, EDGES_HEXAGON);
+          it.filled_regular_polygon(170, 45, 20, EDGES_HEXAGON);
-          // and a filled flat-topped octagon!
+          // and the outline of flat-topped octagon around it!
-          it.filled_regular_polygon(200, 200, 50, EDGES_OCTAGON, VARIATION_FLAT_TOP);
+          it.regular_polygon(170, 45, 40, EDGES_OCTAGON, VARIATION_FLAT_TOP);
           // Need to rotate the polygon, or retrieve the coordinates of its vertices? Check the API!
 
 All the above methods can optionally also be called with an argument at the end which specifies in which
@@ -121,33 +122,35 @@ color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color
       - platform: ...
         # ...
         lambda: |-
-          // Turn the whole display on.
+          // Turn the whole display on
           it.fill(COLOR_ON);
-          // Turn the whole display off.
+          // Turn the whole display off
           it.fill(COLOR_OFF);
 
           // Turn a single pixel off at [50,60]
           it.draw_pixel_at(50, 60, COLOR_OFF);
 
-          // Turn off a whole display portion.
-          it.rectangle(50, 50, 30, 42, COLOR_OFF);
-
 For color displays (e.g. TFT displays), you can use the Color class.
 
+.. figure:: images/display_rendering_colors.png
+    :align: center
+
 .. code-block:: yaml
 
     display:
       - platform: ...
         # ...
         lambda: |-
+          auto black = Color(0, 0, 0);
           auto red = Color(255, 0, 0);
           auto green = Color(0, 255, 0);
           auto blue = Color(0, 0, 255);
           auto white = Color(255, 255, 255);
-          it.rectangle(20, 50, 30, 30, white);
+          it.filled_circle(20, 32, 15, black);
-          it.rectangle(25, 55, 30, 30, red);
+          it.filled_circle(40, 32, 15, red);
-          it.rectangle(30, 60, 30, 30, green);
+          it.filled_circle(60, 32, 15, green);
-          it.rectangle(35, 65, 30, 30, blue);
+          it.filled_circle(80, 32, 15, blue);
+          it.filled_circle(100, 32, 15, white);
 
 Additionally, you have access to two helper methods which will fetch the width and height of the display:
 
@@ -160,6 +163,8 @@ Additionally, you have access to two helper methods which will fetch the width a
           // Draw a circle in the middle of the display
           it.filled_circle(it.get_width() / 2, it.get_height() / 2, 20);
 
+          // Turn off bottom half of the screen
+          it.filled_rectangle(0, it.get_height()/2, it.get_width(), it.get_height()/2, COLOR_OFF);
 
 You can view the full API documentation for the rendering engine in the "API Reference" in the See Also section.
 
@@ -222,6 +227,10 @@ In case of fonts rendered at higher bit depths, the background color has to be s
           // Syntax is always: it.print(<x>, <y>, <font>, [color=COLOR_ON], [align], <text>, [color=COLOR_OFF]);
           it.print(0, 0, id(my_font_with_icons), COLOR_ON, TextAlign::CENTER, "Just\U000f05d4here. Already\U000F02D1this.", COLOR_OFF);
 
+
+.. figure:: images/display_rendering_text.png
+    :align: center
+
 .. _display-printf:
 
 Formatted Text
@@ -351,8 +360,7 @@ You can display current time using a time component. Please see the example :ref
 Screen Clipping
 ---------------
 
-Screen clipping is a new set of methods since version 2023.2.0 of esphome. It could be useful when you just want to show
+Screen clipping can be useful when you just want to show a part of an image or make sure that what you draw on the screen does not go outside a specific region on the screen.
-a part of an image or make sure that what you draw on the screen does not go outside a specific region on the screen.
 
 With ``start_clipping(left, top, right, bottom);`` start you the clipping process and when you are done drawing in that region
 you can stop the clipping process with ``end_clipping();`` . You can nest as many ``start_clipping();`` as you want as long
@@ -461,13 +469,8 @@ memory at the time the sensor updates and will be lost when the device reboots.
 
 Examples:
 
-.. figure:: images/graph_screen.png
+.. figure:: images/display_rendering_graph.png
     :align: center
-    :width: 60.0%
-
-.. figure:: images/graph_dualtrace.png
-    :align: center
-    :width: 60.0%
 
 Graph component with options for grids, border and line-types.
 
@@ -931,49 +934,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.
+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 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.**
+- 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:
+    For displays in 8 bit mode you will see distinct color blocks rather than a smooth gradient.
-      - 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
 
 See Also
 --------

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 
+The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCDs
-with ESPHome. This integration is only for LCD displays that display individual characters on a screen 
+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 LCD displays that can control each pixel individually.
+(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
@@ -15,12 +15,12 @@ with ESPHome. This integration is only for LCD displays that display individual
 
 .. note::
 
-    Multiple versions of the display exist, supporting different character sets: 
+    Multiple versions of the display exist, supporting different character sets:
-    
+
     - HD44780UA00 English-Japanese which includes katakana characters, some Greek letters and mathematical symbols
     - HD44780UA02 English-European which includes Greek, Cyrillic and Western European characters (with some diacritics)
     - HD44780UBxx custom, manufacturer-specific character sets
-    
+
     It is also possible to add eight user-defined characters.
 
 .. _lcd-pcf8574:
@@ -28,7 +28,7 @@ with ESPHome. This integration is only for LCD displays that display individual
 lcd_pcf8574 Component
 ---------------------
 
-``lcd_pcf8574`` is for LCD displays with a PCF8574 GPIO expander module connected to all the data pins. This has the 
+``lcd_pcf8574`` is for LCD displays with a PCF8574 GPIO expander module connected to all the data pins. This has the
 benefit that you only need to connect two data wires to the ESP instead of the six or ten as with the :ref:`lcd-gpio`.
 The communication happens via :ref:`I²C Bus <i2c>`, you need to have an ``i2c:`` section in your configuration.
 
@@ -65,7 +65,7 @@ Configuration variables:
 
 .. note::
 
-    If you're not seeing anything on the display, try turning the contrast potentiometer around on the 
+    If you're not seeing anything on the display, try turning the contrast potentiometer around on the
     PCF8574 board.
 
 .. _lcd-gpio:
@@ -74,7 +74,7 @@ lcd_gpio Component
 ------------------
 
 The ``lcd_gpio`` version of this component addresses the screen directly and does not employ a GPIO expander module.
-Each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. Connecting the screen this way offers 
+Each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. Connecting the screen this way offers
 faster refresh, especially in conjunction with an :ref:`LCD Menu <lcd_menu>`.
 
 .. figure:: images/lcd_gpio.svg
@@ -90,12 +90,12 @@ faster refresh, especially in conjunction with an :ref:`LCD Menu <lcd_menu>`.
       - platform: lcd_gpio
         dimensions: 20x4
         data_pins:
-          - GPIO32
+          - GPIOXX
-          - GPIO33
+          - GPIOXX
-          - GPIO5
+          - GPIOXX
-          - GPIO17
+          - GPIOXX
-        enable_pin: D4
+        enable_pin: GPIOXX
-        rs_pin: D5
+        rs_pin: GPIOXX
         lambda: |-
           it.print("Hello World!");
 
@@ -105,8 +105,8 @@ Configuration variables:
 - **dimensions** (**Required**, string): The dimensions of the display with ``COLUMNSxROWS``. If you're not
   sure, power the display on, turn contrast high up and just count them.
 - **data_pins** (**Required**, list of :ref:`pins <config-pin_schema>`): A list of the data pins you
-  have hooked up to the LCD. The list can either be 4 items long (operating in 4-bit mode with 
+  have hooked up to the LCD. The list can either be 4 items long (operating in 4-bit mode with
-  either the first 4 data pins connected or the last 4 data pins connected), or 8 items long (when you have 
+  either the first 4 data pins connected or the last 4 data pins connected), or 8 items long (when you have
   connected all 8 data pins).
 - **enable_pin** (**Required**, :ref:`pin <config-pin_schema>`): The pin you have ``E`` (``06``) hooked up to.
 - **rs_pin** (**Required**, :ref:`pin <config-pin_schema>`): The pin you have ``RS`` (``04``) hooked up to.
@@ -118,7 +118,7 @@ Configuration variables:
 
 .. note::
 
-    If you're not seeing anything on the display, make sure you apply ``3.3V`` to the ``VEE`` (``03``) contrast control 
+    If you're not seeing anything on the display, make sure you apply ``3.3V`` to the ``VEE`` (``03``) contrast control
     pin of the board. You can use a potentiometer to make it adjustable.
 
 
@@ -177,7 +177,7 @@ The LCD display has the possibility to define up to eight user defined character
 ``0`` to ``7`` and mirrored at ``8`` to ``15`` (i.e. ``\x08`` can be used instead of the ``\0`` that can
 be problematic in strings). Each character has eight lines of five bits, with the first line on the top
 and the most significant bit on the left, meaning that ``0b10000`` followed by six zeros and a ``0b00001``
-defines a dot at the upper left and lower right of the character. 
+defines a dot at the upper left and lower right of the character.
 
 .. code-block:: yaml
 
@@ -221,7 +221,7 @@ Keep in mind that the display lambda runs for every ``update_interval``, so if t
 it cannot be overridden from other parts.
 
 With the ``lcd_gpio``, the backlight is lit by applying ``Vcc`` to the ``BLA`` (``15``) pin and connect ``BLK`` (``16``)
-pin to ``GND``. The backlight can draw more power than the microcontroller output pins can supply, so it is advisable 
+pin to ``GND``. The backlight can draw more power than the microcontroller output pins can supply, so it is advisable
 to use a transistor as a switch to control the power for the backlight pins.
 
 Below an example for a typical use-case where the backlight is turned on when a motion sensor activates and

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.

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.

components/display/nextion.rst

@@ -18,15 +18,15 @@ with ESPHome.
 As the communication with the Nextion LCD display is done using UART, you need to have an :ref:`UART bus <uart>`
 in your configuration with ``rx_pin`` both the ``tx_pin`` set to the respective pins on the display.
 The Nextion uses a baud rate of 9600 by default. It may be configured to use a faster speed by adding (for
-example) 
+example)
 
 .. code-block:: c++
 
     baud=115200   // Sets the baud rate to 115200
     bkcmd=0       // Tells the Nextion to not send responses on commands. This is the current default but can be set just in case
 
- 
+
-  
+
 to the ``program.s`` source file (in the Nextion Editor) before the ``page`` line.
 This permits faster communication with the Nextion display and it is highly recommended when using :ref:`uart-hardware_uarts`. Without a hardware uart make sure to set the baud rate to 9600.
 
@@ -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!");
@@ -73,7 +65,7 @@ Configuration variables:
 - **on_wake** (*Optional*, :ref:`Action <config-action>`): An action to be performed when the Nextion wakes up. See :ref:`Nextion Automation <nextion-on_sleep>`.
 - **on_page** (*Optional*, :ref:`Action <config-action>`): An action to be performed after a page change. See :ref:`Nextion Automation <nextion-on_page>`.
 - **on_touch** (*Optional*, :ref:`Action <config-action>`): An action to be performed after a touch event (press or release). See :ref:`Nextion Automation <nextion-on_touch>`.
-  
+
 .. _display-nextion_lambda:
 
 Rendering Lambda
@@ -113,7 +105,7 @@ Lambda Calls
 ************
 
 Several methods are available for use within :ref:`lambdas <config-lambda>`; these permit advanced functionality beyond simple
-display updates. See the full :apiref:`nextion/nextion.h` for more info. 
+display updates. See the full :apiref:`nextion/nextion.h` for more info.
 
 .. _nextion_upload_tft:
 
@@ -126,7 +118,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
         services:
           - service: update_nextion
             then:
-              - lambda: 'id(nextion1)->upload_tft();' 
+              - lambda: 'id(nextion1)->upload_tft();'
 
 .. _nextion_update_all_components:
 
@@ -178,7 +170,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
 
 .. _nextion_queue_types:
 
- Queue Types: 
+ Queue Types:
   - SENSOR            0
   - BINARY_SENSOR     1
   - SWITCH            2
@@ -291,7 +283,7 @@ The following arguments will be available:
 Uploading A TFT File
 --------------------
 This will download the file from the tft_url and will transfer it over the UART to the Nextion.
-Once completed both the ESP and Nextion will reboot. During the upload process esphome will be 
+Once completed both the ESP and Nextion will reboot. During the upload process esphome will be
 unresponsive and no logging will take place. This uses the same protocol as the Nextion editor and
 only updates the changes of the TFT file. If HTTPS/SSL is enabled it will be about 1kB/sec.
 
@@ -304,7 +296,7 @@ To host the TFT file you can use Home Assistant itself or any other web server.
 
 Home Assistant
 **************
-To host the TFT file from Home Assistant, create a www directory if it doesn't exist in your config 
+To host the TFT file from Home Assistant, create a www directory if it doesn't exist in your config
 directory. You can create a subdirectory for those files as well.
 
 For example if the file is located
@@ -321,8 +313,8 @@ The below NGINX example configuration will serve files out of the /var/www/nexti
 .. code-block:: nginx
 
     server {
-      listen 80;    
+      listen 80;
-      access_log  /var/log/nginx/nextion_access.log;    
+      access_log  /var/log/nginx/nextion_access.log;
       error_log  /var/log/nginx/nextion_error.log;
       root /var/www/nextion;
     }

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
+        cs_pin: GPIOXX
-        reset_pin: 13
+        reset_pin: GPIOXX
-        enable_pin: 9
+        enable_pin: GPIOXX
 
 
 Configuration variables:
@@ -150,17 +150,17 @@ Lilygo T-Display S3 AMOLED
         - 7
         - 48
         - 5
-  
+
     i2c:
       sda: 3
       scl: 2
-  
+
     touchscreen:
       - platform: cst816
         id: my_touchscreen
         interrupt_pin:
           number: 21
-  
+
     display:
       - platform: qspi_amoled
         model: RM67162

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
+        backlight_pin: GPIOXX
-        cs_pin: GPIO5
+        cs_pin: GPIOXX
-        dc_pin: GPIO16
+        dc_pin: GPIOXX
-        reset_pin: GPIO23
+        reset_pin: GPIOXX
         lambda: |-
           it.print(0, 0, id(font), "Hello World!");
 
@@ -191,7 +187,7 @@ Items marked RQ are hardware dependent but required and not preset. Items marked
      - 22
      - 23
      - 4
-     - 
+     -
      - 18
      - 19
    * - Custom

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
+      cs_pin: GPIOXX
-      data_pin: GPIO5
+      data_pin: GPIOXX
-      read_pin: GPIO23
+      read_pin: GPIOXX
-      write_pin: GPIO18
+      write_pin: GPIOXX
       lambda: |-
         it.printf(0, "%.1f", id(my_sensor1).state);
         it.display_celsius(true);
@@ -82,7 +82,7 @@ Also we have five function to display or not some unites:
   - °F on the first line : ``display_fahrenheit(bool)``
   - %HR on the second line : ``display_humidity(bool)``
   - V on the first line and A on the second line : ``display_voltage(bool)``
-  - kW/h on the first line and W on the second line : ``display_kwh(bool)``  
+  - kW/h on the first line and W on the second line : ``display_kwh(bool)``
 
 See Also
 --------

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
+        stb_pin: GPIOXX
-        clk_pin: 18
+        clk_pin: GPIOXX
-        dio_pin: 23
+        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
+      clk_pin: GPIOXX
-      dio_pin: 23
+      dio_pin: GPIOXX
-      stb_pin: 5
+      stb_pin: GPIOXX
       update_interval: 500ms
       lambda: |-
           static int i = 0;
@@ -132,16 +132,16 @@ The TM1638 7 Segment Display Keypad & LED Module has 8 LED lights across the top
 
 .. code-block:: yaml
 
-    switch:                 
+    switch:
       - platform: tm1638
         id: TM1638Led1
         led: 0
-        
+
     output:
       - platform: tm1638
         id: TM1638Led2
         led: 1
-    
+
 
 
 Buttons
@@ -163,7 +163,7 @@ The TM1638 7 Segment Display Keypad & LED Module has 8 buttons across the top or
         on_release:
          then:
             - switch.turn_off: TM1638Led1
-                   
+
       - platform: tm1638
         name: "TM1638 Button 2"
         id: TM1638Button2

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

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.
 

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
+this component. 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
+the :ref:`lcd_menu <lcd_menu>` component and an instance of this is used in the configuration
 examples.
 
 

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.
 

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
+        sda: GPIOXX
-        scl: GPIO23
+        scl: GPIOXX
-      data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
+      data_pins: [GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX]
-      vsync_pin: GPIO22
+      vsync_pin: GPIOXX
-      href_pin: GPIO26
+      href_pin: GPIOXX
-      pixel_clock_pin: GPIO21
+      pixel_clock_pin: GPIOXX
-      reset_pin: GPIO15
+      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:
@@ -80,24 +80,24 @@ Image Settings:
 - **resolution** (*Optional*, enum): The resolution the camera will capture images at. Higher
   resolutions require more memory, if there's not enough memory you will see an error during startup.
 
-    - ``160x120`` (QQVGA)
+    - ``160x120`` (QQVGA, 4:3)
-    - ``176x144`` (QCIF)
+    - ``176x144`` (QCIF, 11:9)
-    - ``240x176`` (HQVGA)
+    - ``240x176`` (HQVGA, 15:11)
-    - ``320x240`` (QVGA)
+    - ``320x240`` (QVGA, 4:3)
-    - ``400x296`` (CIF)
+    - ``400x296`` (CIF, 50:37)
-    - ``640x480`` (VGA, default)
+    - ``640x480`` (VGA, 4:3, default)
-    - ``800x600`` (SVGA)
+    - ``800x600`` (SVGA, 4:3)
-    - ``1024x768`` (XGA)
+    - ``1024x768`` (XGA, 4:3)
-    - ``1280x1024`` (SXGA)
+    - ``1280x1024`` (SXGA, 5:4)
-    - ``1600x1200`` (UXGA)
+    - ``1600x1200`` (UXGA, 4:3)
-    - ``1920x1080`` (FHD)
+    - ``1920x1080`` (FHD, 16:9)
-    - ``720x1280`` (Portrait HD)
+    - ``720x1280`` (Portrait HD, 9:16)
-    - ``864x1536`` (Portrait 3MP)
+    - ``864x1536`` (Portrait 3MP, 9:16)
-    - ``2048x1536`` (QXGA)
+    - ``2048x1536`` (QXGA, 4:3)
-    - ``2560x1440`` (QHD)
+    - ``2560x1440`` (QHD, 16:9)
-    - ``2560x1600`` (WQXGA)
+    - ``2560x1600`` (WQXGA, 8:5)
-    - ``1080x1920`` (Portrait FHD)
+    - ``1080x1920`` (Portrait FHD, 9:16)
-    - ``2560x1920`` (QSXGA)
+    - ``2560x1920`` (QSXGA, 4:3)
 
 
 - **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with.
@@ -174,12 +174,14 @@ Test Setting:
     Camera uses PWM timer #1. If you need PWM (via the ``ledc`` platform) you need to manually specify
     a channel there (with the ``channel: 2``  parameter)
 
-Configuration for Ai-Thinker Camera
+Configuration examples
------------------------------------
+----------------------
+
+**Ai-Thinker Camera**:
 
 .. warning::
 
-    GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM. 
+    GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM.
     Using this GPIO for other purposes (eg as a button) will trigger the watchdog.
     Further information on pin notes can be found here: https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md
 
@@ -203,8 +205,7 @@ Configuration for Ai-Thinker Camera
       name: My Camera
       # ...
 
-Configuration for M5Stack Camera
+**M5Stack Camera**:
---------------------------------
 
 .. warning::
 
@@ -235,8 +236,7 @@ Configuration for M5Stack Camera
       name: My Camera
       # ...
 
-Configuration for M5Stack Timer Camera X/F
+**M5Stack Timer Camera X/F**:
-------------------------------------------
 
 .. code-block:: yaml
 
@@ -258,8 +258,7 @@ Configuration for M5Stack Timer Camera X/F
       name: My Camera
       # ...
 
-Confguration for M5Stack M5CameraF New
+**M5Stack M5CameraF New**:
---------------------------------------
 
 .. code-block:: yaml
 
@@ -277,8 +276,7 @@ Confguration for M5Stack M5CameraF New
       pixel_clock_pin: GPIO21
       reset_pin: GPIO15
 
-Configuration for Wrover Kit Boards
+**Wrover Kit Boards**:
------------------------------------
 
 .. code-block:: yaml
 
@@ -299,8 +297,7 @@ Configuration for Wrover Kit Boards
       name: My Camera
       # ...
 
-Configuration for TTGO T-Camera V05
+**TTGO T-Camera V05**:
------------------------------------
 
 .. code-block:: yaml
 
@@ -322,8 +319,7 @@ Configuration for TTGO T-Camera V05
       name: My Camera
       # ...
 
-Configuration for TTGO T-Camera V162
+**TTGO T-Camera V162**:
-------------------------------------
 
 .. code-block:: yaml
 
@@ -346,8 +342,7 @@ Configuration for TTGO T-Camera V162
       name: My Camera
       # ...
 
-Configuration for TTGO T-Camera V17
+**TTGO T-Camera V17**:
------------------------------------
 
 .. code-block:: yaml
 
@@ -371,8 +366,7 @@ Configuration for TTGO T-Camera V17
       name: My Camera
       # ...
 
-Configuration for TTGO T-Journal
+**TTGO T-Journal**:
---------------------------------
 
 .. code-block:: yaml
 
@@ -394,8 +388,7 @@ Configuration for TTGO T-Journal
       # ...
 
 
-Configuration for TTGO-Camera Plus
+**TTGO-Camera Plus**:
-----------------------------------
 
 .. code-block:: yaml
 
@@ -418,8 +411,7 @@ Configuration for TTGO-Camera Plus
       name: My Camera
       # ...
 
-Configuration for TTGO-Camera Mini
+**TTGO-Camera Mini**:
-----------------------------------
 
 .. code-block:: yaml
 
@@ -440,8 +432,7 @@ Configuration for TTGO-Camera Mini
       name: My Camera
       # ...
 
-Configuration for ESP-EYE
+**ESP-EYE**:
-----------------------------------
 
 .. code-block:: yaml
 
@@ -462,8 +453,7 @@ Configuration for ESP-EYE
       name: My Camera
       # ...
 
-Configuration for ESP32S3_EYE on `Freenove ESP32-S3-DevKitC-1 <https://github.com/Freenove/Freenove_ESP32_S3_WROOM_Board>`_
+**ESP32S3_EYE** on `Freenove ESP32-S3-DevKitC-1 <https://github.com/Freenove/Freenove_ESP32_S3_WROOM_Board>`__:
----------------------------------------------------------------------------------------------------------------------------
 
 .. code-block:: yaml
 
@@ -490,6 +480,26 @@ Configuration for ESP32S3_EYE on `Freenove ESP32-S3-DevKitC-1 <https://github.co
       name: My Camera
       # ...
 
+**Seeed Studio XIAO ESP32S3 Sense**:
+
+.. code-block:: yaml
+
+    esp32_camera:
+      external_clock:
+        pin: GPIO10
+        frequency: 20MHz
+      i2c_pins:
+        sda: GPIO40
+        scl: GPIO39
+      data_pins: [GPIO15, GPIO17, GPIO18, GPIO16, GPIO14, GPIO12, GPIO11, GPIO48]
+      vsync_pin: GPIO38
+      href_pin: GPIO47
+      pixel_clock_pin: GPIO13
+
+      # Image settings
+      name: My Camera
+      # ...
+
 See Also
 --------