Merge branch 'guide_for_noobs' of https://github.com/trip5/esphome-docs into guide_for_noobs

Author: trip5

.github/workflows/component-image.yml

@@ -50,7 +50,7 @@ jobs:
           component: ${{ needs.prepare.outputs.name }}
 
       - name: Upload
-        uses: actions/upload-artifact@v4.4.3
+        uses: actions/upload-artifact@v4.5.0
         id: upload-artifact
         with:
           name: ${{ needs.prepare.outputs.name }}

.github/workflows/docker.yml

@@ -25,7 +25,7 @@ jobs:
     steps:
       -
         name: Install pagefind
-        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        uses: jaxxstorm/action-install-gh-release@v1.14.0
         with:
           repo: cloudcannon/pagefind
       -

.github/workflows/lint.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Install pagefind
-      uses: jaxxstorm/action-install-gh-release@v1.12.0
+      uses: jaxxstorm/action-install-gh-release@v1.14.0
       with:
           repo: cloudcannon/pagefind
     - uses: actions/[email protected]

Doxygen

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ESPHome"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2024.10.3
+PROJECT_NUMBER         = 2024.12.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

Makefile

@@ -1,5 +1,5 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2024.10.3
+ESPHOME_REF = 2024.12.2
 PAGEFIND_VERSION=1.1.1
 PAGEFIND=pagefind
 NET_PAGEFIND=../pagefindbin/pagefind

_extensions/apiref.py

@@ -0,0 +1,64 @@
+import re
+import string
+from docutils import nodes, utils
+
+
+value_re = re.compile(r"^(.*)\s*<(.*)>$")
+DOXYGEN_LOOKUP = {}
+for s in string.ascii_lowercase + string.digits:
+    DOXYGEN_LOOKUP[s] = s
+for s in string.ascii_uppercase:
+    DOXYGEN_LOOKUP[s] = "_{}".format(s.lower())
+DOXYGEN_LOOKUP[":"] = "_1"
+DOXYGEN_LOOKUP["_"] = "__"
+DOXYGEN_LOOKUP["."] = "_8"
+
+
+def split_text_value(value):
+    match = value_re.match(value)
+    if match is None:
+        return None, value
+    return match.group(1), match.group(2)
+
+
+def encode_doxygen(value):
+    value = value.split("/")[-1]
+    try:
+        return "".join(DOXYGEN_LOOKUP[s] for s in value)
+    except KeyError:
+        raise ValueError("Unknown character in doxygen string! '{}'".format(value))
+
+
+def apiref_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    text, value = split_text_value(text)
+    if text is None:
+        text = "API Reference"
+    ref = "/api/{}.html".format(encode_doxygen(value))
+    return [make_link_node(rawtext, text, ref, options)], []
+
+
+def apiclass_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    text, value = split_text_value(text)
+    if text is None:
+        text = value
+    ref = "/api/classesphome_1_1{}.html".format(encode_doxygen(value))
+    return [make_link_node(rawtext, text, ref, options)], []
+
+
+def apistruct_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    text, value = split_text_value(text)
+    if text is None:
+        text = value
+    ref = "/api/structesphome_1_1{}.html".format(encode_doxygen(value))
+    return [make_link_node(rawtext, text, ref, options)], []
+
+def make_link_node(rawtext, text, ref, options=None):
+    options = options or {}
+    node = nodes.reference(rawtext, utils.unescape(text), refuri=ref, **options)
+    return node
+
+def setup(app):
+    app.add_role("apiref", apiref_role)
+    app.add_role("apiclass", apiclass_role)
+    app.add_role("apistruct", apistruct_role)
+    return {"version": "1.0.0", "parallel_read_safe": True, "parallel_write_safe": True}

components.py renamed to _extensions/components.py

@@ -0,0 +1,49 @@
+
+import os
+
+from docutils import nodes, utils
+
+
+def libpr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    ref = "https://github.com/esphome/esphome-core/pull/{}".format(text)
+    return [make_link_node(rawtext, "core#{}".format(text), ref, options)], []
+
+
+def yamlpr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    ref = "https://github.com/esphome/esphome/pull/{}".format(text)
+    return [make_link_node(rawtext, "esphome#{}".format(text), ref, options)], []
+
+
+def docspr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    ref = "https://github.com/esphome/esphome-docs/pull/{}".format(text)
+    return [make_link_node(rawtext, "docs#{}".format(text), ref, options)], []
+
+
+def ghuser_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    ref = "https://github.com/{}".format(text)
+    return [make_link_node(rawtext, "@{}".format(text), ref, options)], []
+
+
+def ghedit_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    path = os.path.relpath(
+        inliner.document.current_source, inliner.document.settings.env.app.srcdir
+    )
+    ref = "https://github.com/esphome/esphome-docs/blob/current/{}".format(path)
+    return [make_link_node(rawtext, "Edit this page on GitHub", ref, options)], []
+
+
+def make_link_node(rawtext, text, ref, options=None):
+    options = options or {}
+    node = nodes.reference(rawtext, utils.unescape(text), refuri=ref, **options)
+    return node
+
+
+def setup(app):
+    app.add_role("libpr", libpr_role)
+    app.add_role("corepr", libpr_role)
+    app.add_role("yamlpr", yamlpr_role)
+    app.add_role("esphomepr", yamlpr_role)
+    app.add_role("docspr", docspr_role)
+    app.add_role("ghuser", ghuser_role)
+    app.add_role("ghedit", ghedit_role)
+    return {"version": "1.0.0", "parallel_read_safe": True, "parallel_write_safe": True}

_extensions/github.py

@@ -129,7 +129,7 @@ def run(self):
             if not image.startswith("/"):
                 local_img = f"/images/{image}"
                 image = "/_images/" + image
-            p = Path(__file__).parent / local_img[1:]
+            p = Path(__file__).parent.parent / local_img[1:]
             if not p.is_file():
                 raise ValueError(f"File {p} for seo tag does not exist {self.state.document}")
 

seo.py renamed to _extensions/seo.py

@@ -1,98 +1,11 @@
+
 import csv
 from itertools import zip_longest
-import os
-import re
-import string
 
 from docutils import nodes, utils
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.tables import Table
 
-
-def libpr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    ref = "https://github.com/esphome/esphome-core/pull/{}".format(text)
-    return [make_link_node(rawtext, "core#{}".format(text), ref, options)], []
-
-
-def yamlpr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    ref = "https://github.com/esphome/esphome/pull/{}".format(text)
-    return [make_link_node(rawtext, "esphome#{}".format(text), ref, options)], []
-
-
-def docspr_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    ref = "https://github.com/esphome/esphome-docs/pull/{}".format(text)
-    return [make_link_node(rawtext, "docs#{}".format(text), ref, options)], []
-
-
-def ghuser_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    ref = "https://github.com/{}".format(text)
-    return [make_link_node(rawtext, "@{}".format(text), ref, options)], []
-
-
-value_re = re.compile(r"^(.*)\s*<(.*)>$")
-DOXYGEN_LOOKUP = {}
-for s in string.ascii_lowercase + string.digits:
-    DOXYGEN_LOOKUP[s] = s
-for s in string.ascii_uppercase:
-    DOXYGEN_LOOKUP[s] = "_{}".format(s.lower())
-DOXYGEN_LOOKUP[":"] = "_1"
-DOXYGEN_LOOKUP["_"] = "__"
-DOXYGEN_LOOKUP["."] = "_8"
-
-
-def split_text_value(value):
-    match = value_re.match(value)
-    if match is None:
-        return None, value
-    return match.group(1), match.group(2)
-
-
-def encode_doxygen(value):
-    value = value.split("/")[-1]
-    try:
-        return "".join(DOXYGEN_LOOKUP[s] for s in value)
-    except KeyError:
-        raise ValueError("Unknown character in doxygen string! '{}'".format(value))
-
-
-def apiref_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    text, value = split_text_value(text)
-    if text is None:
-        text = "API Reference"
-    ref = "/api/{}.html".format(encode_doxygen(value))
-    return [make_link_node(rawtext, text, ref, options)], []
-
-
-def apiclass_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    text, value = split_text_value(text)
-    if text is None:
-        text = value
-    ref = "/api/classesphome_1_1{}.html".format(encode_doxygen(value))
-    return [make_link_node(rawtext, text, ref, options)], []
-
-
-def apistruct_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    text, value = split_text_value(text)
-    if text is None:
-        text = value
-    ref = "/api/structesphome_1_1{}.html".format(encode_doxygen(value))
-    return [make_link_node(rawtext, text, ref, options)], []
-
-
-def ghedit_role(name, rawtext, text, lineno, inliner, options=None, content=None):
-    path = os.path.relpath(
-        inliner.document.current_source, inliner.document.settings.env.app.srcdir
-    )
-    ref = "https://github.com/esphome/esphome-docs/blob/current/{}".format(path)
-    return [make_link_node(rawtext, "Edit this page on GitHub", ref, options)], []
-
-
-def make_link_node(rawtext, text, ref, options=None):
-    options = options or {}
-    node = nodes.reference(rawtext, utils.unescape(text), refuri=ref, **options)
-    return node
-
-
 # https://stackoverflow.com/a/3415150/8924614
 def grouper(n, iterable, fillvalue=None):
     """Pythonic way to iterate over sequence, 4 items at a time.
@@ -105,7 +18,6 @@ def grouper(n, iterable, fillvalue=None):
 
 # Based on https://www.slideshare.net/doughellmann/better-documentation-through-automation-creating-docutils-sphinx-extensions
 class ImageTableDirective(Table):
-
     option_spec = {
         "columns": directives.positive_int,
     }
@@ -272,16 +184,6 @@ def run(self):
 
 
 def setup(app):
-    app.add_role("libpr", libpr_role)
-    app.add_role("corepr", libpr_role)
-    app.add_role("yamlpr", yamlpr_role)
-    app.add_role("esphomepr", yamlpr_role)
-    app.add_role("docspr", docspr_role)
-    app.add_role("ghuser", ghuser_role)
-    app.add_role("apiref", apiref_role)
-    app.add_role("apiclass", apiclass_role)
-    app.add_role("apistruct", apistruct_role)
-    app.add_role("ghedit", ghedit_role)
     app.add_directive("imgtable", ImageTableDirective)
     app.add_directive("pintable", PinTableDirective)
     return {"version": "1.0.0", "parallel_read_safe": True, "parallel_write_safe": True}

sitemap.py renamed to _extensions/sitemap.py

@@ -12,6 +12,7 @@
 /components/ota.html /components/ota/esphome.html 301
 /components/ota_http_request.html /components/ota/http_request.html 301
 /components/sensor/mmc5063.html /components/sensor/mmc5603.html 301
+/components/sensor/kalman_combinator.html /components/sensor/combination.html 301
 
 /cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301
 /cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301
@@ -42,3 +43,4 @@
 
 /ready-made/projects /projects/ 301
 /components/images /components/image 301
+/components/display/qspi_amoled.html /components/display/qspi_dbi.html 301

github.py renamed to _extensions/tables.py

@@ -1 +1 @@
-2024.10.3
+2024.12.2

_redirects

@@ -217,7 +217,11 @@ turns on a light for 5 seconds. Otherwise, the light is turned off immediately.
 
 Configuration variables:
 
-- **condition** (**Required**, :ref:`Condition <config-condition>`): The condition to check to determine which branch to take.
+At least one of ``condition``, ``all`` or ``any`` must be provided.
+  
+- **condition** (*Optional*, :ref:`Condition <config-condition>`): The condition to check to determine which branch to take. If this is configured with a list of conditions then they must all be true for the condition to be true.
+- **all** (*Optional*, :ref:`Condition <config-condition>`): Takes a list of conditions, all of which must be true (and is therefore equivalent to ``condition``.)
+- **any** (*Optional*, :ref:`Condition <config-condition>`): Takes a list of conditions; if at least one is true, the condition will be true.
 - **then** (*Optional*, :ref:`Action <config-action>`): The action to perform if the condition evaluates to true.
   Defaults to doing nothing.
 - **else** (*Optional*, :ref:`Action <config-action>`): The action to perform if the condition evaluates to false.
@@ -406,14 +410,17 @@ Common Conditions
 "Conditions" provide a way for your device to take an action only when a specific (set of) condition(s) is satisfied.
 
 .. _and_condition:
+.. _all_condition:
 .. _or_condition:
+.. _any_condition:
 .. _xor_condition:
 .. _not_condition:
 
-``and`` / ``or`` / ``xor`` / ``not`` Condition
-**********************************************
+``and`` / ``all`` / ``or`` / ``any`` / ``xor`` / ``not`` Condition
+******************************************************************
 
-Check a combination of conditions
+Check a combination of conditions. ``all`` is a synonym for ``and``, and ``any`` is a synonym for ``or``.
+``all`` and ``any`` may also be used directly in place of ``condition``.
 
 .. code-block:: yaml
 
@@ -428,9 +435,10 @@ Check a combination of conditions
             # ...
 
         - if:
-            condition:
-              not:
-                binary_sensor.is_off: some_binary_sensor
+            any:
+              - not:
+                  binary_sensor.is_off: some_binary_sensor
+              - binary_sensor.is_on: some_other_sensor
 
 .. _for_condition:
 

_static/changelog-2024.10.0.png

@@ -57,7 +57,7 @@
 - **senseair:** ``abc_disable``, ``abc_enable``, ``abc_get_period``, ``background_calibration``, ``background_calibration_result``
 - **servo:** ``detach``, ``write``
 - **sim800l:** ``connect``, ``dial``, ``disconnect``, ``send_sms``, ``send_ussd``
-- **speaker:** ``play``, ``stop``
+- **speaker:** ``play``, ``stop``, ``finish``, ``volume_set``
 - **sprinkler:** ``clear_queued_valves``, ``next_valve``, ``pause``, ``previous_valve``, ``queue_valve``, ``resume``, ``resume_or_start_full_cycle``, ``set_divider``, ``set_multiplier``, ``set_repeat``, ``set_valve_run_duration``, ``shutdown``, ``start_from_queue``, ``start_full_cycle``, ``start_single_valve``
 - **sps30:** ``start_fan_autoclean``
 - **stepper:** ``report_position``, ``set_acceleration``, ``set_deceleration``, ``set_speed``, ``set_target``

_static/changelog-2024.11.0.png

@@ -8,7 +8,7 @@
 - **fan:** ``is_off``, ``is_on``
 - **light:** ``is_off``, ``is_on``
 - **lock:** ``is_locked``, ``is_unlocked``
-- **media_player:** ``is_idle``, ``is_playing``
+- **media_player:** ``is_announcing``, ``is_idle``, ``is_paused``, ``is_playing``
 - **micro_wake_word:** ``is_running``
 - **microphone:** ``is_capturing``
 - **mqtt:** ``connected``

_static/changelog-2024.12.0.png

@@ -20,7 +20,7 @@ ESPHome 2022.1.0 - 19th January 2022
     Kalman Combinator, components/sensor/kalman_combinator, function.svg, dark-invert
     MCP3204, components/sensor/mcp3204, mcp3204.jpg
     MCP47A1, components/output/mcp47a1, mcp47a1.svg
-    Midea IR Climate, components/climate/ir_climate, air-conditioner-ir.svg, dark-invert
+    Midea IR Climate, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
     Safe Mode Button, components/button/safe_mode, restart-alert.svg, dark-invert
     Shutdown Button, components/button/shutdown, power_settings.svg, dark-invert
     Tuya Number, components/number/tuya, tuya.png

_static/changelog-2024.9.0.png

@@ -17,8 +17,8 @@ ESPHome 2023.12.0 - 20th December 2023
     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
-    PN716X, components/binary_sensor/pn7160, pn716x.jpg
+    PN7150, components/pn7150, pn7150.jpg
+    PN716X, components/pn7160, pn716x.jpg
 
 Graphical Menu
 --------------