Merge branch 'next' into current-mipi_dsi

Author: miniskipper

content/components/display/epaper_spi.md

@@ -12,7 +12,7 @@ with improved state management and non-blocking operation. This component implem
 queue-based state machine that eliminates blocking waits for the busy pin and provides
 better integration with ESPHome's async architecture.
 
-The communication method uses 4-wire [SPI](/components/spi), so you need to have an `spi:` section in your
+The communication method uses [SPI](/components/spi), so you need to have an `spi:` section in your
 configuration.
 
 The driver supports a number of displays and there are also specific configurations for ESP32 boards with integrated displays.
@@ -26,43 +26,85 @@ display:
       it.filled_circle(it.get_width() / 2, it.get_height() / 2, 50, Color::BLACK);
 ```
 
-## Supported displays
+## Supported display controllers
 
-| Model name             | Manufacturer | Product Description                                        |
-| ---------------------- | ------------ | ---------------------------------------------------------- |
-| Spectra-E6             | Eink         | <https://www.eink.com/brand/detail/Spectra6>               |
-| 7.3in Spectra-E6       | Eink         | <https://www.eink.com/product/detail/EL073TF1U5>           |
-| Seeed-reTerminal-E1002 | Seeed Studio | <https://www.seeedstudio.com/reTerminal-E1002-p-6533.html> |
+These are the supported controller chips. Using just the chip name as the model will require full configuration with
+pins and dimensions specified.
+
+| Chip name              | Manufacturer | Product Description                                                                                                          |
+|------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------|
+| Spectra-E6             | Eink         | <https://www.eink.com/brand/detail/Spectra6>                                                                                 |
+| SSD1677                | Solomon      | <https://www.solomon-systech.com/product/ssd1677/>                                                                           |
+
+## Supported integrated display boards
+
+These models correspond to displays integrated with a microcontroller, and have a full configuration predefined, so at
+a minimum only the model name need be configured. Other options can be overridden in the configuration if needed.
+
+| Model name             | Manufacturer | Product Description                                                                                                          |
+| ---------------------- |--------------| ---------------------------------------------------------------------------------------------------------------------------- |
+| Seeed-reTerminal-E1002 | Seeed Studio | <https://www.seeedstudio.com/reTerminal-E1002-p-6533.html>                                                                   |
+| Seeed-ee04-mono-4.26   | Seeed Studio | Seeed EE04 board with Waveshare 4.26" mono epaper. <https://www.seeedstudio.com/XIAO-ePaper-Display-Board-EE04-p-6560.html>  |
 
 ## Configuration variables
 
-When using a model defining an integrated ESP32 display board most of the configuration such as the pins and dimensions will be set by default,
+When using a model defining an integrated display board most of the configuration such as the pins and dimensions will be set by default,
 but can be overridden if needed.
 
-- **model** (**Required**): The model of the ePaper display. See the table above for options.
+- **model** (**Required**): The model of the ePaper display. See the table above for options (case is not significant).
 - **cs_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The CS pin. Predefined for integrated boards.
 - **dc_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The DC pin. Predefined for integrated boards.
 - **busy_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The BUSY pin, if used.
 - **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The RESET pin, if used.
   Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin.
+- **dimensions** (**Required**, dict): Dimensions of the screen, specified either as *width* **x** *height* (e.g `320x240`  )
+  or with separate config keys. For integrated boards with full pre-defined configuration this is optional and will be preset by
+  the model selected. The dimensions are specified in pixels, and the width and height must be greater than 0.
 
-- **rotation** (*Optional*): Set the rotation of the display. Everything you draw in `lambda:` will be rotated
+  - **height** (**Required**, int): Specifies height of display.
+  - **width** (**Required**, int): Specifies width of display.
+
+- **rotation** (*Optional*, int): Set the rotation of the display. Everything you draw in `lambda:` will be rotated
   by this option. One of `0°` (default), `90°`, `180°`, `270°`.
+- **transform** (*Optional*, dict): If `rotation` is not sufficient, use this to transform the display. Options are:
+  - **mirror_x** (**Required**, boolean): If true, mirror the x axis.
+  - **mirror_y** (**Required**, boolean): If true, mirror the y axis.
 
 - **reset_duration** (*Optional*, [Time](/guides/configuration-types#time)): Duration for the display reset operation. Defaults to `200ms`.
-
 - **lambda** (*Optional*, [lambda](/automations/templates#config-lambda)): The lambda to use for rendering the content on the display.
   See [Display Rendering Engine](/components/display#display-engine) for more information.
 - **pages** (*Optional*, list): Show pages instead of a single lambda. See [Display Pages](/components/display#display-pages).
-
 - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to re-draw the screen. Defaults to `60s`,
   use `never` to only manually update the screen via `component.update`.
-- **spi_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [SPI Component](/components/spi) if you want
-  to use multiple SPI buses.
+- **full_update_every** (*Optional*, int): On screens that support partial updates, this sets the number of updates
+  before a full update is forced. Defaults to `1` which will make every update a full update.
+- **spi_id** (*Optional*, [ID](/guides/configuration-types#id)): Required to specify the ID of the [SPI Component](/components/spi) if your
+  configuration defines multiple SPI buses. If only a single SPI bus is configured, this is optional.
 - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for code generation.
 
+### Full configuration example
+
+```yaml
+display:
+  - platform: epaper_spi
+    model: SSD1677
+    full_update_every: 10
+    update_interval: 5s
+    dimensions:
+      width: 800
+      height: 480
+    transform:
+      mirror_x: true
+      mirror_y: false
+    rotation: 90 # Rotate to portrait
+    cs_pin: GPIOXX
+    dc_pin: GPIOXX
+    reset_pin: GPIOXX
+    busy_pin: { number: GPIOXX, inverted: False, mode: { input: True, pulldown: True } }
+```
+
 ## See Also
 
-- {{< docref "index/" >}}
 - {{< apiref "epaper_spi/epaper_spi.h" "epaper_spi/epaper_spi.h" >}}
 - [ESPHome Display Rendering Engine](/components/display#display-engine)
+- {{< docref "components/lvgl" >}}

content/components/lvgl/_index.md

@@ -131,6 +131,11 @@ The following configuration variables apply to the main `lvgl` component, in ord
 > - If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby you can adjust the value of the object by turning the encoder.
 > - To leave edit mode, long press the button.
 
+- **update_when_display_idle** (*Optional*, boolean): When using the {{< docref "/components/display/epaper_spi" >}}
+  or other displays with long update times, setting this option
+  to `true` will cause the display to only be updated if the display is idle. During the update LVGL will pause.
+  The display `update_interval` should be set to `never` when this is used, as the display will be updated automatically
+  by LVGL.
 - **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 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. If unconfigured, the default is `100%` with runtime fallback to `12%` if a full size buffer allocation fails. For devices without PSRAM, the recommended value is `25%`.

content/components/lvgl/widgets.md

@@ -38,7 +38,12 @@ The properties below are common to all widgets.
   - `"ON"`  : Always show the scroll bars (use the double quotes!).
   - `"ACTIVE"`  : Show scroll bars while a widget is being scrolled.
   - `"AUTO"`  : Show scroll bars when the content is large enough to be scrolled (default).
-
+- **scroll_dir** (*Optional*, string): Sets the permissible scroll directions for an object - one of `LEFT`, `RIGHT`,
+  `BOTTOM`, `TOP`, `HOR`, `VER`, `ALL` (default).
+- **scroll_snap_x** (*Optional*, string): For a child of a scrollable object, this property defines the snap position
+  of the child in the X direction. One of `NONE` (default), `START`, `END`, `CENTER`.
+- **scroll_snap_y** (*Optional*, string): For a child of a scrollable object, this property defines the snap position
+  of the child in the Y direction. One of `NONE` (default), `START`, `END`, `CENTER`.
 - **align** (*Optional*, enum): Alignment of the widget relative to the parent. A child widget is clipped to its parent boundaries. One of the values *not* starting with `OUT_` (see picture below).
 - **align_to** (*Optional*, list): Alignment of the widget relative to another widget on the same level:
   - **id** (**Required**): The ID of a widget *to* which you want to align.
@@ -424,9 +429,17 @@ Simple push (momentary) or toggle (two-states) button.
 
 {{< img src="lvgl_button.png" alt="Image" class="align-center" >}}
 
+A button has no inherent content so requires child widgets to be added. As a shorthand for a button with a single text label,
+the `text:` option may be used to add a single `label` child, otherwise the `widgets:` key must be used to add other
+widgets inside the button.
+
+A button is momentary by default, which has a `pressed` state. If the `checkable` flag is set, it becomes a toggle button, which also has a `checked` state.
+
 **Configuration variables:**
 
-- **checkable** (*Optional*, boolean): A significant [flag](#lvgl-widget-flags) to make a toggle button (which remains pressed in `checked` state). Defaults to `false`.
+- **checkable** (*Optional*, boolean): A significant [flag](#lvgl-widget-flags) to make a toggle button (which reports its `checked` state). Defaults to `false`.
+- **text** (*Optional*, string): Text to be displayed on the button. This will create and add a single label widget to the button. May not be used
+  with the `widgets:` key.
 - Style options from [Style properties](/components/lvgl#lvgl-styling) for the background of the button. Uses the typical background style properties.
 
 A notable state is `checked` (boolean) which can have different styles applied.
@@ -440,30 +453,22 @@ A notable state is `checked` (boolean) which can have different styles applied.
 **Example:**
 
 ```yaml
-# Example widget:
+# Example widget with text:
 - button:
-    x: 10
-    y: 10
-    width: 50
-    height: 30
     id: btn_id
+    text: "Click me!"
 ```
 
-To have a button with a text label on it, add a child [`label`](#lvgl-widget-label) widget to it:
+To create an image button, add a child [`image`](#lvgl-widget-image) widget to it:
 
 ```yaml
-# Example toggle button with text:
+# Example toggle button with image:
 - button:
-    x: 10
-    y: 10
-    width: 70
-    height: 30
     id: btn_id
     checkable: true
     widgets:
-      - label:
-          align: center
-          text: "Light"
+      - image:
+          src: my_image_id
 
 # Example trigger:
 - button:
@@ -473,12 +478,37 @@ To have a button with a text label on it, add a child [`label`](#lvgl-widget-lab
         - logger.log:
             format: "Button checked state: %d"
             args: [ x ]
+
 ```
 
 The `button` can be also integrated as a {{< docref "/components/binary_sensor/lvgl" "Binary Sensor" >}} or as a {{< docref "/components/switch/lvgl" "Switch" >}} component.
+> [!NOTE]
+> A binary sensor linked to a button reports its `pressed` state, while a switch linked to a button reports its `checked` state.
 
 See [Remote light button](/cookbook/lvgl#lvgl-cookbook-binent) for an example which demonstrates how to use a checkable button to act on a Home Assistant service.
 
+**Actions:**
+
+- `lvgl.button.update` [action](/automations/actions#actions-action) may be used to update the button styles at runtime. If
+  the button has a `text:` option then it may also be updated with this action.
+  - **id** (**Required**): The ID or a list of IDs of button widgets to be updated.
+  - **text** (*Optional*, string): Update the button's text (only if the button was configured with the `text:` option).
+  - Style options from [Style properties](/components/lvgl#lvgl-styling) for the background of the button.
+
+  > [!NOTE]
+  > Where other widgets are added as children, they must be updated directly.
+
+```yaml
+# Text update example
+- button:
+    id: btn_id
+    text: "Click me!"
+    on_click:
+      lvgl.button.update:
+        id: btn_id
+        text: "Clicked"
+```
+
 {{< anchor "lvgl-widget-buttonmatrix" >}}
 
 ## `buttonmatrix`