Merge branch 'current' into next

changelog/2024.11.0.rst

@@ -34,8 +34,17 @@ actually compile anything.
 OpenTherm
 ---------
 
-This release brings :doc:`/components/opentherm` support to ESPHome. Please see the :doc:`documentation </components/opentherm>` for detailed information about
-it and how to use it.
+This release brings :doc:`/components/opentherm` support to ESPHome. Please see the
+:doc:`documentation </components/opentherm>` for detailed information about it and how to use it.
+
+ESPHome ``armv7`` Docker Support
+--------------------------------
+
+We will be retiring ESPHome's Docker support for ``armv7`` hardware in the February 2025 release.
+
+This is due to both waning support as it relates to tooling and performance reasons. We strongly recommend moving to a
+more modern architecture, especiallly if you're using the ESPHome Device Compiler to build/compile firmware for your
+devices.
 
 Release 2024.11.1 - November 22
 -------------------------------

components/lvgl/index.rst

@@ -125,7 +125,7 @@ The following configuration variables apply to the main ``lvgl`` component, in o
 
 
 - **resume_on_input** (*Optional*, boolean): If LVGL is paused and the user interacts with the screen, resume the activity of LVGL. Defaults to ``true``. "Interacts" means to release a touch or button, or rotate an encoder.
-- **color_depth** (*Optional*, string): The color deph at which the contents are generated. Currently only ``16`` is supported (RGB565, 2 bytes/pixel), which is the default value.
+- **color_depth** (*Optional*, string): The color depth at which the contents are generated. Currently only ``16`` is supported (RGB565, 2 bytes/pixel), which is the default value.
 - **buffer_size** (*Optional*, percentage): The percentage of screen size to allocate buffer memory. Default is ``100%`` (or ``1.0``). For devices without PSRAM, the recommended value is ``25%``.
 - **draw_rounding** (*Optional*, int): An optional value to use for rounding draw areas to a specified boundary. Defaults to 2. Useful for displays that require draw windows to be on specified boundaries (usually powers of 2.)
 - **log_level** (*Optional*, string): Set the logger level specifically for the messages of the LVGL library: ``TRACE``, ``INFO``, ``WARN``, ``ERROR``, ``USER``, ``NONE``. Defaults to ``WARN``.

components/vbus.rst

@@ -27,7 +27,7 @@ The following table shows the currently supported models of Vbus devices.
     "Dux H3214","deltasol_bs_2009","427B", "Pump 2 unsupported"
     "DeltaSol C","deltasol_c","4212"
     "DeltaSol CS2","deltasol_cs2","1121"
-    "DeltaSol CS2 Plus","deltasol_cs2_plus","2211"
+    "DeltaSol CS Plus","deltasol_cs_plus","2211"
 
 The ``Config Value`` should be used for the ``model`` parameter in your ``sensor`` and ``binary_sensor`` entries.
 

guides/contributing.rst

@@ -546,9 +546,6 @@ wish to use it.
 Now you can open ESPHome in your IDE of choice (many of us are using `VSCode <https://code.visualstudio.com/download>`__)
 with the PlatformIO addons (see PlatformIO docs for more info) and develop the new feature with the guidelines below.
 
-All PRs are automatically checked and tested for some common formatting/code errors with Github Actions. *These checks*
-**must all pass** *before we will review (and eventually merge) your PR.*
-
 Setting Up Git Environment
 --------------------------
 
@@ -597,7 +594,7 @@ near the top of the page (or, alternatively, go to branches and create it from t
 - Complete the Pull Request template:
 
   - Include a brief (but complete) summary of your changes.
-  - PRs without a descrption/summary of the changes will not be reviewed or merged, although exceptions may
+  - PRs without a description/summary of the changes will not be reviewed or merged, although exceptions may
     occasionally be made for small PRs and/or PRs made by frequent contributors/maintainers.
   - **Do not delete the template.**
 
@@ -611,15 +608,47 @@ near the top of the page (or, alternatively, go to branches and create it from t
   it is ready. We do this because, if a PR is reviewed and then it changes, it must be re-reviewed. Reviewing a single
   PR multiple times is not a productive use of time and we try as much as possible to avoid doing so.
 
+So now that you've created your PR...you're not quite done! Read on to the next section below so you know what to
+expect next.
+
 Review Process
 **************
 
-ESPHome's maintainers work hard to maintain a high standard for its code, so reviews can take some time. At the bottom
-of each pull request you will see the "Github Actions" continuous integration (CI) checks which will automatically
-analyize all code changed in your branch. These checks try to spot (and suggest corrections for) errors. If any CI
-check fails, please look at the Github Actions log and fix all errors that appear there.
+.. _automated_checks:
 
-**All automated checks must be passing** before a given PR will be reviewed and (eventually) merged!
+Automated Checks
+^^^^^^^^^^^^^^^^
+
+At the bottom of each pull request you will see the "Github Actions" continuous integration (CI) checks which will
+automatically analyze all code changed in your branch. These checks try to spot (and suggest corrections for) common
+errors; they look like this:
+
+.. figure:: images/gha_checks.jpg
+    :align: center
+    :width: 100.0%
+    :alt: Automated checks on PR by GitHub Actions
+    :class: light-invert
+
+You can click the "Details" link to the right of each check to see the logs for that check. If a red ❌ appears next to
+any given check, *you'll need to view that check's logs and make the suggested changes so that the test will pass.*
+
+**Implementing Feedback from Automated Checks**
+
+Occasionally, an automated check may suggest a change that either isn't directly related to your PR or that may require
+changes to other components/platforms. When this happens, please create a new/additional PR to implement this change.
+
+For example, the automated checks may suggest moving a constant from your (new) component/platform into ``const.py``.
+This is a simple change, but we require that it is done in a separate PR.
+
+Ultimately, **all automated checks must be passing** before maintainers will review and (eventually) merge your PR!
+
+Review by Maintainers
+^^^^^^^^^^^^^^^^^^^^^
+
+ESPHome's maintainers work hard to maintain a high standard for its code, so reviews by a human can take some time.
+
+**All automated checks must be passing** before maintainers will review and (eventually) merge your PR! See
+:ref:`automated_checks` above.
 
 **When will my PR be reviewed/merged?**
 
@@ -709,7 +738,7 @@ Beyond basic functionality (*"does it work?"*), here are a few other items we ch
 .. _prs-are-being-drafted-when-changes-are-needed:
 
 Why was my PR marked as a draft?
-************************************
+********************************
 
 If your PR was reviewed and changes were requested, our bot will automatically mark your PR as a draft. This means that
 the PR is not ready to be merged or further reviewed for the moment.
@@ -1006,7 +1035,7 @@ it then attempts to read back the measurement from the sensor.
 :apiclass:`PollingComponent`.
 
 For any :apiclass:`Component` (which is nearly everything), the well-known ``set_timeout`` method is also available;
-this can be a handy alternative to implemeting a state machine.
+this can be a handy alternative to implementing a state machine.
 
 .. _a_note_about_custom_components:
 
@@ -1124,8 +1153,8 @@ ESPHome's maintainers work hard to maintain a high standard for its code. We try
 
 - Components should dump their configuration using ``ESP_LOGCONFIG`` at startup in ``dump_config()``.
 - ESPHome uses a unified formatting tool for all source files (but this tool can be difficult to install).
-  When creating a new PR in GitHub, be sure to check the Github Actions output to see what formatting needs to be
-  changed and what potential problems are detected.
+  When creating a new PR in GitHub, be sure to check the :ref:`Github Actions<automated_checks>` output to see what
+  formatting needs to be changed and what potential problems are detected.
 - Use of external libraries should be kept to a minimum:
 
   - If the component you're developing has a simple communication interface, please consider implementing the library
@@ -1135,7 +1164,7 @@ ESPHome's maintainers work hard to maintain a high standard for its code. We try
     communication abstractions.
   - If the library accesses a global variable/state (``Wire`` is a good example) then there's likely a problem because
     the component may not be modular. Put another way, this approach may mean that it's not possible to create multiple
-    instances of the component for use wihtin ESPHome.
+    instances of the component for use within ESPHome.
 
 - Components **must** use the provided abstractions like ``sensor``, ``switch``, etc. Components specifically should
   **not** directly access other components -- for example, to publish to MQTT topics.

guides/devboard_as_flasher.rst

@@ -0,0 +1,50 @@
+Using an ESP devboard as a USB-UART bridge
+==========================================
+
+.. _devboard-as-flasher:
+
+ESP development boards usually have an onboard USB interface, either built into the chip (e.g. ESP32-S3) or via an onboard USB-UART bridge chip.
+However some ESP based devices not designed for development work don't bother with this,
+and only expose the UART0 pins (TX and RX) for flashing purposes.
+
+Normally you would use a dedicated USB-UART interface board for this but what if you don't have one?
+In this "emergency" situation it is possible to use a development board that does have a USB-UART bridge chip to flash another device.
+This is achieved by holding the ESP chip in reset so that it doesn't interfere with the bridge chip operation.
+
+It does NOT require any firmware to be flashed onto the development board
+and will not change anything already flashed onto it - it's purely a way to use the serial interface chip.
+
+We will refer to the devboard with functional USB_UART bridge chip as flasher board for this guide.
+
+Make sure you've read the :doc:`/guides/physical_device_connection` for properly understanding the functionality of your flasher devboard.
+
+.. figure:: /guides/images/devboard-as-flasher.png
+    :align: center
+    :width: 75.0%
+
+    Connection diagram for an ESP flash target
+
+You need to make the following electrical connections:
+
+.. note::
+
+    - Most ESP32 S and C series boards do *not* have a separate USB-UART chip - they have it built into the ESP - so are not suitable for this application.
+    - The 5V connection on either board may be labelled either ``5V`` or ``VIN``. Some boards may not have a 5V connection and will require 3.3V only.
+    - Rather than powering the target board from the flasher board, it is also possible to use a separate power supply, just make sure all the ground pins are connected together.
+
+- connect both ``EN`` and ``GND`` together in the flasher devboard
+- ``+5.0V`` or ``3V3`` on the flasher devboard to ``VIN`` or ``3V3`` respectively of the target device
+- ``GND``, or ground of flasher devboard to ``GND`` of the target device
+- ``TX`` of flasher devboard to ``TX`` of the target device
+- ``RX`` of flasher devboard to ``RX`` of the target device
+
+Pulling down ``EN`` by connecting it to ``GND`` on the flasher board prevents
+the ESP chip on flasher module from booting and polluting the serial lines.
+
+.. note::
+
+    - If the board has not previously had ESPHome loaded, you may need to pull the ``IO0`` pin low (i.e. connected to ``GND``) to force the board into flash mode.
+      This must be done before power is applied.
+    - Do not connect 3V3 to VIN of the target devices with a 3V3 LDO as it may lead to brownouts.
+
+Once the connections are made, plug the flasher board into your computer via USB and proceed with flashing the target board via whichever means you intend to use.

guides/physical_device_connection.rst

@@ -3,7 +3,7 @@ Physically Connecting to your Device
 
 The most difficult part of setting up a new ESPHome device is the initial
 installation, which requires connecting your ESP device to a computer using a
-cable.
+data cable.
 
 **You only need to do this once per device.** Once you've flashed ESPHome on a
 device, you can use :doc:`/components/ota/index` to upload new
@@ -119,8 +119,9 @@ USB Port on Device
 
 Development boards often come with a USB port built in. This USB port is
 connected to a serial adapter, so you don't need a separate serial adapter. You
-can use just a :ref:`USB cable <usb-cable>` to connect it to your computer to
-program it.
+can use just a :ref:`USB data cable <usb-cable>` to connect it to your computer to
+program it. Additionally, a development board can also be used to flash other ESPs.
+:doc:`Read more here. </guides/devboard_as_flasher>`
 
 This isn't likely to be very useful without connecting additional sensors to it
 by either soldering or using a breadboard, but you do not need anything else to
@@ -241,7 +242,8 @@ require different parts and tools.
         .. _usb-cable:
     * - :ref:`USB to micro-USB/mini-USB/USB-C <usb-cable>`
       - If your target device has a USB port on it, you need the appropriate
-        cable to connect to it.
+        data cable to connect to it. A power only USB cable that usually
+        comes presupplied with powerbanks won't work.
       - $3 to $10
       - .. image:: /guides/images/usb-cable.jpg
             :alt: From https://www.stockvault.net/photo/271754/usb-cable
@@ -259,6 +261,9 @@ require different parts and tools.
 
         The `Tasmota website provides a good set of suggestions on what to buy
         <https://tasmota.github.io/docs/Getting-Started/#needed-hardware>`_.
+
+        Any ESP development board with functioning USB_UART bridge chip can also be used instead.
+        :doc:`Read instructions here. </guides/devboard_as_flasher>`
       - $3 to $10
       - .. image:: /guides/images/usb-serial-adapter.jpg
             :alt: From https://tasmota.github.io/docs/Getting-Started/