Merge branch 'next' into feat/#3215_modbus_controller_courtesy_response

Author: carlessole

Makefile

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

_static/version

@@ -1 +1 @@
-2025.7.4
+2025.8.0-dev

components/api.rst

@@ -98,6 +98,8 @@ Configuration variables:
       WiFi performance with many rapidly-changing sensors. Only use this setting when necessary.
 
 - **custom_services** (*Optional*, boolean): Enable compilation of custom API services for external components that use the C++ ``CustomAPIDevice`` class. Only needed when external components register their own services via the native API. Defaults to ``false``.
+- **homeassistant_services** (*Optional*, boolean): Enable compilation of Home Assistant service call support for external components that use the C++ ``CustomAPIDevice::call_homeassistant_service()`` or ``CustomAPIDevice::fire_homeassistant_event()`` methods. This is automatically enabled when using ``homeassistant.service`` or ``homeassistant.event`` actions, or the ``homeassistant`` platform for number or switch components. Only needs to be manually set when external components call Home Assistant services without using the built-in actions. Defaults to ``false``.
+- **homeassistant_states** (*Optional*, boolean): Enable compilation of Home Assistant state subscription support for external components that use the C++ ``CustomAPIDevice::subscribe_homeassistant_state()`` method. This is automatically enabled when using any ``homeassistant`` platform components (sensor, binary_sensor, text_sensor, switch, or number). Only needs to be manually set when external components subscribe to Home Assistant states without using the built-in components. Defaults to ``false``.
 - **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when no
   client connects to the API. This is needed because sometimes the low level ESP functions report that
   the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.

components/binary_sensor/packet_transport.rst

@@ -27,8 +27,8 @@ It requires a ``packet_transport`` component to be configured.
        - platform: ...
 
 
-Configuration variables
------------------------
+Configuration variables:
+------------------------
 
 -  **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 -  **provider** (**Required**, string): The name of the provider node.

components/button/factory_reset.rst

@@ -40,6 +40,7 @@ Configuration variables:
 See Also
 --------
 
+- :doc:`/components/factory_reset`
 - :doc:`shutdown`
 - :doc:`restart`
 - :doc:`safe_mode`

components/display/ili9xxx.rst

@@ -41,6 +41,11 @@ ILI9341 (`datasheet <https://cdn-shop.adafruit.com/datasheets/ILI9341.pdf>`__) a
 displays from the same chip family with ESPHome. As this is a somewhat higher resolution display and requires additional pins
 beyond the basic SPI connections, and a reasonable amount of RAM, it is not well suited for the ESP8266.
 
+.. warning::
+
+    This component has been made redundant since this class of displays is now supported by the :ref:`mipi_spi`.
+    This component may be removed in a future release.
+
 .. note::
 
     PSRAM is not automatically enabled on the ESP32 (this changed with the 2025.2 release.) If PSRAM is available, you

components/display/mipi_dsi.rst

@@ -0,0 +1,178 @@
+.. seo::
+    :description: Details for the MIPI DSI display driver component in ESPHome
+    :image: tab5.jpg
+
+.. _mipi_dsi:
+
+MIPI DSI Display Driver
+=======================
+
+Introduction
+------------
+
+This driver is for displays that use the MIPI DSI display interface available in the ESP32-P4.
+
+.. figure:: /images/tab5.jpg
+    :align: center
+    :width: 75.0%
+
+    M5STACK-TAB5 with ESP32-P4
+
+Background
+----------
+
+The MIPI (Mobile Industry Processor Interface) Alliance publishes various hardware and software interface specifications
+including the Display Serial Interface (DSI), which transfers pixel data over a high-speed serial bus to an LCD display.
+
+The display panels controlled by the driver may be of various types, including TFT, IPS, and others. Each driver
+chip and panel combination requires a specific set of initialisation commands, and standard initialisation sequences are provided for many common
+boards and chips, but the driver is also designed to be customisable in YAML for other displays.
+
+Supported boards and driver chips
+---------------------------------
+
+There are specific configurations for several ESP32 boards with integrated displays. For those boards
+the predefined configuration will set the correct pins and dimensions for the display.
+
+For custom displays, the driver can be configured with the correct pins and dimensions, and the driver chip can be
+specified, or a custom init sequence can be provided.
+
+Driver chips
+^^^^^^^^^^^^
+
+.. csv-table::
+    :header: "Driver Chip", "Typical Dimensions"
+    :widths: 15, 20
+
+    "CUSTOM", "Customisable"
+
+Boards with integrated displays
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. csv-table::
+    :header: "Model", "Manufacturer", "Product Description"
+    :widths: 30, 20, 30
+
+    "JC1060P470", "Guition", "https://aliexpress.com/item/1005008328088576.html"
+    "M5STACK-TAB5", "M5Stack", "https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4"
+    "WAVESHARE-P4-NANO-10.1", "Waveshare", "https://www.waveshare.com/esp32-p4-nano.htm?sku=29031"
+    "WAVESHARE-P4-86-PANEL", "Waveshare", "https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570"
+
+
+Configuration
+-------------
+
+.. code-block:: yaml
+
+    # Example minimal configuration entry
+    display:
+        - platform: mipi_dsi
+          model: WAVESHARE-P4-NANO-10.1
+
+Configuration options
+^^^^^^^^^^^^^^^^^^^^^
+
+All :ref:`graphical display configuration<display-configuration>` options are available, plus the following. For integrated display boards
+most of the configuration will be set by default, but can be overridden if needed.
+
+- **model** (**Required**): Chosen from the lists of supported chips and models above, or ``CUSTOM`` for custom displays.
+- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin, if required.
+- **enable_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): An optional pin to enable the display, if required. A list of pins can be provided for displays that require multiple enable pins. A full pin configuration may be provided
+  to set the pin mode and inverted property. By default the pin will be driven high to enable the display.
+- **color_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``. This specifies the order of the color channels in the display panel. The default is ``bgr`` for most displays, but some displays may require ``rgb``. It does not affect the color order of the display buffer, which is always RGB.
+- **dimensions** (*Optional*): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys. If not provided the dimensions will be determined by the model selected. This is required for the ``CUSTOM`` model, and is optional for other models. The dimensions are specified in pixels, and the width and height must be greater than 0. The following keys are available:
+
+    - **height** (**Required**, int): Specifies height of display in pixels.
+    - **width** (**Required**, int): Specifies width of display.
+    - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0
+    - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0.
+
+- **invert_colors** (*Optional*, boolean): Specifies whether the display colors should be inverted. Options are ``true`` or ``false``. Defaults to ``false``.
+- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. If the driver chip supports hardware rotation for the given orientation this will be translated to the appropriate hardware command. If hardware rotation is not supported, the display will be rotated in software.
+- **transform** (*Optional*): If ``rotation`` is not sufficient, use this to transform the display. If this option is specified, then the ``dimensions`` option must also be provided. Options are:
+
+   - **swap_xy** (**Required**, boolean): If true, exchange the x and y axes.
+   - **mirror_x** (**Required**, boolean): If true, mirror the x axis.
+   - **mirror_y** (**Required**, boolean): If true, mirror the y axis.
+
+- **hsync_pulse_width** (*Optional*, int): The horizontal sync pulse width.
+- **hsync_front_porch** (*Optional*, int): The horizontal front porch length.
+- **hsync_back_porch** (*Optional*, int): The horizontal back porch length.
+- **vsync_pulse_width** (*Optional*, int): The vertical sync pulse width.
+- **vsync_front_porch** (*Optional*, int): The vertical front porch length.
+- **vsync_back_porch** (*Optional*, int): The vertical back porch length.
+- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 40MHz.
+- **pclk_inverted** (*Optional*, bool): If the pclk is active negative (default is True)
+- **lanes** (*Optional*, int): Number of serial data lanes to use - 1 or 2. Default is 2.
+- **lane_bit_rate** (*Optional*, int): The bit rate of the serial data lanes. No default unless a non-custom model is selected.
+
+Advanced options
+^^^^^^^^^^^^^^^^
+
+- **init_sequence** (*Optional*): Allows custom initialisation sequences to be added. See below for more information.
+- **pixel_mode** (*Optional*): Select the interface mode for the display driver. Options are ``16bit`` (default) and ``24bit``.
+- **color_depth** (*Optional*): The color depth of the display buffer, expressed in bits. Options are ``16`` (default) and ``24``. Preferably should be the same as the ``pixel_mode`` option.
+- **draw_rounding** (*Optional*): The rounding factor for drawing operations. Defaults to 2. Some chips require a higher value to avoid display artifacts. Must be a power of 2.
+- **use_axis_flips** (*Optional*): If true, the driver will use alternate bits in the MADCTL register to implement x and y mirroring. Defaults to false.
+- **byte_order** (*Optional*): The byte order of the display buffer. Options are ``big_endian`` and ``little_endian`` (default). This affects the byte order for the buffer when
+  using 16 bit color depth. The default is appropriate for the majority of displays.
+
+
+Additional initialisation sequences
+-----------------------------------
+
+The ``init_sequence`` option allows additional configuration of the driver chip. Provided commands will be sent to the
+driver chip in addition to, and after the chosen model's pre-defined commands. It requires a list of byte sequences:
+
+.. code-block:: yaml
+
+    init_sequence:
+      - [ 0xD0, 0x07, 0x42, 0x18]
+      - delay 10ms
+      - [ 0xD1, 0x00, 0x07, 0x10]
+
+Each entry represents a single-byte command followed by zero or more data bytes. Delays can be inserted with the ``delay`` keyword followed by a time in milliseconds. The delay is not precise, but will be at least the specified time.
+If converting from other code, make sure the length byte, if present, is not copied as the length of each command sequence is determined by the number of bytes in the list.
+
+CUSTOM model
+------------
+
+The ``CUSTOM`` model selection is provided for otherwise unsupported displays, and requires both ``dimensions:`` and ``init_sequence:`` to be specified. There is no pre-defined init sequence.
+
+Using the ``transform`` options
+-------------------------------
+
+In most cases, the ``rotation`` option will be sufficient to orient the display correctly. However, some displays may require additional transformations. The ``transform`` option allows for these transformations to be applied in any of 8 different
+combinations. It may be necessary to experiment with different combinations to achieve the desired result. When using the ``transform`` option, the ``rotation`` option should not be set unless the display does not support axis-swapping.
+If the ``swap_xy`` option is set, then the ``dimensions`` option is required, and the ``width`` and ``height`` values should be set to reflect the final screen dimensions after rotation.
+
+.. code-block:: yaml
+
+    transform:
+      swap_xy: true
+      mirror_x: true
+      mirror_y: false
+    dimensions:
+      height: 480
+      width: 320
+
+
+LCD Backlights
+--------------
+
+Many displays have an integrated backlight, which may need to be turned on for the display to show. This backlight is not controlled
+by the driver, but can be controlled by a separate GPIO pin. Depending on the display, the backlight may be active high or active low, and may
+be able to be dimmed using a :doc:`/components/light/monochromatic` with a :doc:`/components/output/ledc`.
+
+Touchscreens
+------------
+
+A touchscreen, if present, must be configured separately. See the :doc:`/components/touchscreen/index` documentation for more information.
+
+See Also
+--------
+
+- :doc:`index`
+- :doc:`/components/lvgl/index`
+- :apiref:`mipi_dsi/mipi_dsi.h`
+- :ghedit:`Edit`

components/display/mipi_spi.rst

@@ -1,12 +1,12 @@
-MIPI SPI Display Driver
-=======================
-
 .. seo::
     :description: Details for the MIPI SPI display driver component in ESPHome
     :image: ili9341.jpg
 
 .. _mipi_spi:
 
+MIPI SPI Display Driver
+=======================
+
 Introduction
 ------------
 
@@ -65,6 +65,8 @@ Boards with integrated displays
     :header: "Model", "Manufacturer", "Product Description"
     :widths: 30, 20, 30
 
+    "ADAFRUIT-S2-TFT-FEATHER", "Adafruit", "https://www.adafruit.com/product/6312"
+    "ADAFRUIT-FUNHOUSE", "Adafruit", "https://www.adafruit.com/product/4985"
     "M5CORE", "M5Stack", "https://docs.m5stack.com/en/core/BASIC%20v2.6"
     "S3BOX", "Espressif", "https://www.espressif.com/en/products/devkits/esp32-s3-box"
     "S3BOXLITE", "Espressif", "https://www.espressif.com/en/products/devkits/esp32-s3-box-lite"
@@ -138,6 +140,8 @@ most of the configuration will be set by default, but can be overridden if neede
    - **mirror_y** (**Required**, boolean): If true, mirror the y axis.
 
 - **color_depth** (*Optional*): The color depth of the display buffer, expressed in bits. Options are ``16`` (default) and ``8``. 8 bit depth will result in only 256 possible colors and should be used only if the microcontroller has limited memory. The driver will convert the 8 bit color to the display chip's required format.
+- **buffer_size** (*Optional*): The percentage of screen size to allocate buffer memory. The default is ``100%`` when PSRAM is configured, and otherwise will be calculated to
+  achieve a buffer size less than 20K bytes. See the discussion below about buffer sizes.
 
 Advanced options
 ^^^^^^^^^^^^^^^^
@@ -148,13 +152,35 @@ Advanced options
 - **data_rate** (*Optional*): The SPI data rate. Defaults to 10MHz but board presets may override this.
 - **spi_mode** (*Optional*): The SPI mode. Options are ``MODE0``, ``MODE1``, ``MODE2``, and ``MODE3``. Defaults to ``MODE0`` for single bit SPI and ``MODE3`` for octal SPI (parallel bus.)
 - **draw_rounding** (*Optional*): The rounding factor for drawing operations. Defaults to 2. Some chips require a higher value to avoid display artifacts. Must be a power of 2.
-- **draw_from_origin** (*Optional*): If true, drawing operations will always start from the origin (0,0) of the display. Defaults to false.
 - **use_axis_flips** (*Optional*): If true, the driver will use alternate bits in the MADCTL register to implement x and y mirroring. Defaults to false.
+- **byte_order** (*Optional*): The byte order of the display buffer. Options are ``big_endian`` (default) and ``little_endian``. This affects the byte order for the buffer when
+  using 16 bit color depth. The default is appropriate for the majority of displays.
 
 **Note:** The maximum achievable data rate will depend on the chip type (e.g. ESP32 vs ESP32-S3) the pins used (on ESP32 using the default SPI pins allows higher rates) and the connection type (on-board connections will support higher rates than long cables or DuPont wires.) If in doubt, start with a low speed and test higher rates to find what works. A MISO pin should preferably not be specified, as this will limit the maximum rate in some circumstances, and is not required if the SPI bus is used only for the display.
 
+
+Buffer Size
+------------
+
+The display driver writes data from a buffer to the display chip. When using :doc:`/components/lvgl/index` no buffer is required in the display driver itself, as LVGL will
+allocate and use its own buffer.
+When instead using a lambda function to update the display (and not LVGL), a buffer is required to be allocated by the display driver.
+The size of this buffer is determined by the ``buffer_size`` option. The default is ``100%`` when PSRAM is configured, and otherwise will be calculated to
+achieve a buffer size less than 20K bytes. For example a display of size 320x240 will have a buffer size of ``320 * 240 * 2`` bytes (for RGB565) = ``153600`` bytes.
+If the buffer size is set to ``50%``, then the buffer would occupy ``76800`` bytes. If 8 bit color depth is used, then each pixel occupies only 1 byte.
+
+Effect on Drawing Performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The buffer size is a trade-off between the size of the buffer and the performance of the display driver. A larger buffer size will provide better performance,
+but on boards with limited memory, a smaller buffer size may be required to avoid running out of memory. When using a buffer less than 100%, the driver will
+call the drawing lambda multiple times to draw each chunk of the display. For example, with a 25% buffer size, the driver will call the drawing lambda four times to draw the display.
+This has an effect on performance, and should be considered when setting the buffer size, but it is also important that the drawing lambda does not have
+side effects - this should be avoided in any case, but becomes more critical when using a buffer less than 100%.
+
+
 Additional inititialisation sequences
-*************************************
+--------------------------------------
 
 The ``init_sequence`` option allows additional configuration of the driver chip. Provided commands will be sent to the
 driver chip in addition to, and after the chosen model's pre-defined commands. It requires a list of byte sequences:
@@ -170,12 +196,12 @@ Each entry represents a single-byte command followed by zero or more data bytes.
 If converting from other code, make sure the length byte, if present, is not copied as the length of each command sequence is determined by the number of bytes in the list.
 
 CUSTOM model
-************
+------------
 
 The ``CUSTOM`` model selection is provided for otherwise unsupported displays, and requires both ``dimensions:`` and ``init_sequence:`` to be specfied. There is no pre-defined init sequence.
 
 Using the ``transform`` options
-*******************************
+-------------------------------
 
 In most cases, the ``rotation`` option will be sufficient to orient the display correctly. However, some displays may require additional transformations. The ``transform`` option allows for these transformations to be applied in any of 8 different
 combinations. It may be necessary to experiment with different combinations to achieve the desired result. When using the ``transform`` option, the ``rotation`` option should not be set unless the display does not support axis-swapping.
@@ -209,5 +235,6 @@ See Also
 --------
 
 - :doc:`index`
+- :doc:`/components/lvgl/index`
 - :apiref:`mipi_spi/mipi_spi.h`
 - :ghedit:`Edit`