Merge branch 'next' into voice-assist-improvements

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.8.1
+PROJECT_NUMBER         = 2024.9.0-dev
 
 # 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

_static/version

@@ -1 +1 @@
-2024.8.1
+2024.9.0-dev

components/binary_sensor/udp.rst

@@ -0,0 +1,49 @@
+UDP Binary Sensor
+=================
+
+.. seo::
+    :description: Instructions for setting up a UDP binary sensor.
+    :image: udp.svg
+
+The ``udp`` binary sensor platform allows you to receive binary sensor data directly from another ESPHome node.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    binary_sensor:
+      - platform: udp
+        id: switch_status
+        provider: light-switch
+        remote_id: light_switch
+
+Configuration variables
+-----------------------
+
+-  **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+-  **provider** (**Required**, string): The name of the provider node.
+-  **remote_id** (*Optional*, :ref:`config-id`): The ID of the original binary sensor in the provider device. If not specified defaults to the ID configured with ``id:``.
+-  **name** (*Optional*, string): The name of the binary sensor.
+-  **internal** (*Optional*, boolean): Whether the sensor should be exposed via API (e.g. to Home Assistant.) Defaults to ``true`` if name is not set, required if name is provided.
+-  All other options from :ref:`Binary Sensor <config-binary_sensor>`.
+
+At least one of ``id`` and ``remote_id`` must be configured.
+
+Publishing to Home Assistant
+----------------------------
+
+Typically this type of binary sensor would be used for internal automation purposes rather than having it published back to
+Home Assistant, since it would be a duplicate of the original sensor.
+
+If it *is* desired to expose the binary sensor to Home Assistant, then the ``internal:`` configuration setting needs to be explicitly
+set to ``false`` and a name provided.
+Only the state (i.e. binary value) of the remote sensor is received by the consumer, so any other attributes must be explicitly
+configured.
+
+See Also
+--------
+
+- :doc:`/components/udp`
+- :doc:`/components/sensor/index`
+- :ref:`automation`
+- :apiref:`udp/udp_component.h`
+- :ghedit:`Edit`

components/canbus/esp32_can.rst

@@ -26,6 +26,8 @@ Configuration variables:
 
 - **rx_pin** (**Required**, :ref:`Pin <config-pin>`): Receive pin.
 - **tx_pin** (**Required**, :ref:`Pin <config-pin>`): Transmit pin.
+- **rx_queue_len** (**Optional**, int): Length of RX queue.
+- **tx_queue_len** (**Optional**, int): Length of TX queue, 0 to disable.
 - All other options from :ref:`Canbus <config-canbus>`.
 
 .. _esp32-can-bit-rate:

components/display/ili9xxx.rst

@@ -61,9 +61,8 @@ beyond the basic SPI connections, and a reasonable amount of RAM, it is not well
         model: ili9341
         dc_pin: GPIOXX
         reset_pin: GPIOXX
-        lambda: |-
-          it.fill(COLOR_BLACK);
-          it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!");
+        invert_colors: false
+        show_test_card: true
 
 Configuration variables:
 ************************
@@ -101,7 +100,7 @@ Configuration variables:
     - **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*): With this boolean option you can invert the display colors.
+- **invert_colors** (**Required**): Specifies whether the display colors should be inverted. Options are ``true`` or ``false`` - if you are unsure, use ``false`` and change if the colors are not as expected.
 - **pixel_mode** (*Optional*): Allows forcing the display into 18 or 16 bit mode. Options are ``18bit`` or ``16bit``. If unspecified, the pixel mode will be determined by the model choice. Not all displays will work in both modes.
 - **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. This option cannot be used with ``transform``.
 - **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``.
@@ -265,6 +264,7 @@ This config rotates the display into landscape mode using the driver chip.
           mirror_x: false
           mirror_y: true
         color_order: bgr
+        invert_colors: true
         data_rate: 80MHz
         cs_pin: GPIOXX
         dc_pin: GPIO13

components/display/st7701s.rst

@@ -130,6 +130,8 @@ The ``init_sequence`` requires a list of elements, one of which may be a single
 sequence (the default and currently the only sequence is 1), the remainder must be byte arrays providing additional
 init commands, each consisting of a command byte followed by zero or more data bytes.
 
+A delay may be specified with ``delay <N>ms``
+
 These will be collected and sent to the display via SPI during initialisation.
 
 Example configurations
@@ -165,6 +167,7 @@ Seeed Sensecap Indicator
         pclk_pin: 21
         init_sequence:
           - 1 # select canned init sequence number 1
+          - delay 5ms
           - [ 0xE0, 0x1F ]  # Set sunlight readable enhancement
         data_pins:
           red:

components/light/esp32_rmt_led_strip.rst

@@ -34,6 +34,7 @@ Configuration variables
       "ESP32-C3", "0, 1"
 
 - **chipset** (**Required**, enum): The chipset to apply known timings from. Not used if specifying the timings manually, see below.
+    - ``WS2811``
     - ``WS2812``
     - ``SK6812``
     - ``APA106``
@@ -67,6 +68,10 @@ please consider adding support to the codebase and add it to the list above.
 - **bit0_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``0`` bit.
 - **bit1_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``1`` bit.
 - **bit1_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``1`` bit.
+- **reset_high** (*Optional*, :ref:`config-time`): The time to hold the data line high after writing
+  the state. Defaults to ``0 us``.
+- **reset_low** (*Optional*, :ref:`config-time`): The time to hold the data line low after writing
+  the state. Defaults to ``0 us``.
 
 See Also
 --------

components/lvgl/index.rst

@@ -10,7 +10,7 @@ embedded graphics library to create beautiful UIs for any MCU, MPU and display t
 
 .. figure:: /components/lvgl/images/lvgl_main_screenshot.png
 
-To use LVGL with a :ref:`display <display-hw>` in ESPHome, you'll need an ESP32 or supported ESP32 variant. PSRAM is not a strict requirement but it is generally recommended, especially for color displays with resolutions larger than approximately 240x240 pixels.
+To use LVGL with a :ref:`display <display-hw>` in ESPHome, you'll need an ESP32 or RP2040. PSRAM is not a strict requirement but it is generally recommended, especially for large color displays.
 
 The graphic display should be configured with ``auto_clear_enabled: false`` and ``update_interval: never``, and should not have any ``lambda`` set.
 
@@ -635,6 +635,56 @@ This :ref:`action <actions-action>` shows a specific page (including pages with
       then:
         - lvgl.page.show: secret_page  # shorthand version
 
+.. _lvgl-widget-focus-action:
+
+``lvgl.widget.focus``
+*********************
+
+This :ref:`action <actions-action>` moves the input focus to the nominated widget. Used mainly with encoder inputs
+to select a specific widget to receive input events. It may also allow the focus to be frozen on that widget,
+or can be used to move the focus to the next or previous widget in the focus group.
+
+The required config options take one of several forms:
+
+- **id** (**Required**): The ID of the widget to be given focus.
+- **freeze** (*Optional*, boolean): If true will lock the focus to this widget.
+- **editing** (*Optional*, boolean): Sets the editing mode of the widget, i.e. encoder rotation will change the value
+  of the widget, not move the focus. Defaults to false.
+
+or
+
+- **action** (**Required**): Should be one of ``next``, ``previous``, ``mark`` or ``restore``.
+- **group** (*Optional*): The ID of the group within which to move the focus. The default group will be used if not specified
+- **freeze** (*Optional*, boolean): If true will lock the focus to the now selected widget.
+
+
+The ``next`` and ``previous`` actions will move the focus to the next or previous widget within the group.
+The ``mark`` action will save the currently focused widget within the group, and restore it when the ``restore`` action is triggered.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - lvgl.widget.focus:
+            id: my_button
+            freeze: true
+
+    on_...:
+      then:
+        - lvgl.widget.focus: my_button
+
+    on_...:
+      then:
+        - lvgl.widget.focus:
+            group: encoder_group
+            direction: next
+            freeze: true
+
+    on_...:
+      then:
+        - lvgl.widget.focus: previous
+
+
 .. _lvgl-conditions:
 
 Conditions

components/lvgl/widgets.rst

@@ -1807,9 +1807,15 @@ ESPHome implements as universal triggers the following interaction events genera
 - ``on_scroll``: The widget was scrolled.
 - ``on_focus``:  The widget is focused.
 - ``on_defocus``: The widget is unfocused.
+- ``on_all_events``: Will be triggered on any event sent to the widget - this is useful for debugging.
 
 These triggers can be applied directly to any widget in the LVGL configuration, *given that the widget itself supports generating such events*. For the widgets having a value, the triggers return the current value in variable ``x``; this variable may be used in lambdas defined within those triggers.
 
+Each trigger also deliver an ``event`` parameter, which is a pointer to the LVGL C type ``lv_event_t``. This may be used in lambdas defined within those triggers. Refer to the `LVGL documentation <https://docs.lvgl.io/8.4/overview/event.html/>`_ for more information.
+
+There are additional triggers for pages - each page may have an ``on_load`` and ``on_unload`` trigger. These will be called
+when the page becomes active or inactive respectively.
+
 .. code-block:: yaml
 
     # Example triggers:

components/number/tuya.rst

@@ -61,6 +61,27 @@ For instance, assume we have a pH sensor that reads from 0.00 to 15.00 with a sc
       max_value: 15.00
       multiply: 100
 
+Hidden datapoints:
+------------------
+The above configurations will work fine as long as Tuya device publishes the datapoint value (along with its type) at initialization.
+However this is not always the case. To be able to use such "hidden" datapoints as Number, you need to specify additional ``datapoint_hidden`` configuration block.
+This block allows to specify the missing datapoint type and, optionally, the value that should be written to the datapoint at initialization.
+
+TuyaMCU restores the state of all its datapoints after reboot, but with the hidden datapoints there is no way to know what their values are.
+Therefore there is also an option to store them on the ESPHome side and they will be set at initialization. To use this feature, set the ``restore_value`` yaml key to True.
+
+.. code-block:: yaml
+
+    - platform: "tuya"
+      name: "Alarm at maximum"
+      number_datapoint: 116
+      min_value: 0
+      max_value: 100
+      datapoint_hidden:
+        datapoint_type: int
+        initial_value: 85
+        restore_value: yes
+
 Configuration variables:
 ------------------------
 
@@ -69,6 +90,11 @@ Configuration variables:
 - **max_value** (**Required**, float): The maximum value this number can be.
 - **step** (*Optional*, float): The granularity with which the number can be set. Defaults to 1.
 - **multiply** (*Optional*, float): multiply the new value with this factor before sending the requests.
+- **datapoint_hidden** (*Optional*): Specify information required for hidden datapoints.
+
+  - **datapoint_type** (**Required**, string): The datapoint type, one of *int*, *uint*, *enum*.
+  - **initial_value** (*Optional*, float): The value to be written at initialization. Must be between ``min_value`` and ``max_value``.
+  - **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to ``false``.
 
 - All other options from :ref:`Number <config-number>`.
 

components/pipsolar.rst

@@ -242,6 +242,8 @@ Not all possible switches are exposed as they lead to the possibility to make se
           name: inverter0_output_source_priority_solar
         output_source_priority_battery:
           name: inverter0_output_source_priority_battery
+        output_source_priority_hybrid:
+          name: inverter0_output_source_priority_hybrid
         input_voltage_range:
           name: inverter0_input_voltage_range
         pv_ok_condition_for_parallel:
@@ -256,6 +258,7 @@ All sensors are normal text sensors... so all text sensor variables are working
 - **output_source_priority_utility** (*Optional*): output source priority utility
 - **output_source_priority_solar** (*Optional*): output source priority solar
 - **output_source_priority_battery** (*Optional*): output source priority battery
+- **output_source_priority_hybrid** (*Optional*): output source priority hybrid
 - **input_voltage_range** (*Optional*): input voltage range
 - **pv_ok_condition_for_parallel** (*Optional*): pv ok condition for parallel
 - **pv_power_balance** (*Optional*): pv power balance