Merge branch 'next' into next

components/animation.rst

@@ -12,6 +12,7 @@ It adds additional lambda methods: ``next_frame()``, ``prev_frame()`` and ``set_
       - file: "animation.gif"
         id: my_animation
         resize: 100x100
+        type: RGB565
 
 The animation can be rendered just like the image component with the ``image()`` function of the display component.
 
@@ -50,18 +51,15 @@ Configuration variables:
   in your display code.
 - **resize** (*Optional*, string): If set, this will resize all the frames to fit inside the given dimensions ``WIDTHxHEIGHT``
   and preserve the aspect ratio.
-- **type** (*Optional*): Specifies how to encode each frame internally. Defaults to ``BINARY``.
+- **type** (**Required**): Specifies how to encode image internally. See the :ref:`image component <display-image>` for more information.
 
   - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
-    per pixel, 8 pixels per byte.
-  - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
-    will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
+    per pixel, 8 pixels per byte. Only ``chroma_key`` transparency is available.
   - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
-  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
-  - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
-  - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
+  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel, 3 with an alpha channel.
+  - ``RGB``: Full RGB color stored. Uses 3 bytes per pixel, 4 with an alpha channel.
 
-- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
+- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account. The possible values are ``opaque`` (default), ``chroma_key`` and ``alpha_channel``. See discussion on transparency in the :ref:`image component <display-image>`.
 - **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over.
 
   - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation.
@@ -83,4 +81,3 @@ Actions:
 
   - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate.
   - **frame** (**Required**, int): The frame index to show next.
-

components/display/index.rst

@@ -33,7 +33,7 @@ All display components inherit these configuration variables.
 
 All *graphical* displays also inherit these configuration variables.
 
-- **auto_clear_enabled** (*Optional*, boolean): If the display should be cleared before each update. Defaults to ``true``.
+- **auto_clear_enabled** (*Optional*, boolean): If the display should be cleared before each update. Defaults to ``true`` if a lambda or pages are configured, false otherwise.
 - **show_test_card** (*Optional*, boolean): If the display should show a test card. Defaults to ``false``. If set, any code in the ``lambda`` config option will be ignored.
 - **rotation** (*Optional*, integer): The rotation of the display in degrees, one of 0, 90, 180 or 270. Defaults to ``0``.
 - **pages** (*Optional*, list): Pages configuration - see below.

components/display/pvvx_mithermometer.rst

@@ -55,7 +55,7 @@ Configuration variables:
 - **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use to define the information to be displayed.
   See :ref:`display-pvvx_mithermometer_lambda` for more information.
 - **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display data before each lambda call,
-  or to keep the existing display content (must overwrite explicitly, e.g., only on data change). Defaults to ``true``.
+  or to keep the existing display content (must overwrite explicitly, e.g., only on data change). Defaults to ``true`` if a lambda or pages are configured, false otherwise.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 
 .. _display-pvvx_mithermometer_lambda:

components/display/qspi_dbi.rst

@@ -70,8 +70,8 @@ Configuration variables:
 - **enable_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The display enable pin.
 - **brightness** (*Optional*, int): A brightness value in the range 0-255
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
-- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
-  or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display data before each lambda call,
+  or to keep the existing display content (must overwrite explicitly, e.g., only on data change). Defaults to ``true`` if a lambda or pages are configured, false otherwise.
 - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - **color_order** (*Optional*): Should be one of ``rgb`` (default) or ``bgr``.
@@ -137,8 +137,6 @@ Lilygo T4-S3
         cs_pin: 11
         reset_pin: 13
         enable_pin: 9
-        update_interval: never
-        auto_clear_enabled: false
 
     psram:
       mode: octal

components/display/rpi_dpi_rgb.rst

@@ -86,7 +86,7 @@ Configuration variables:
 - **vsync_front_porch** (*Optional*, int): The vertical front porch length.
 - **vsync_back_porch** (*Optional*, int): The vertical back porch length.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
-- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+- **auto_clear_enabled** (*Optional*, boolean): If the display should be cleared before each update. Defaults to ``true`` if a lambda or pages are configured, false otherwise.
   or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
 - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
@@ -120,7 +120,6 @@ Waveshare ESP32-S3 Touch 4.3
 
     display:
       - platform: rpi_dpi_rgb
-        auto_clear_enabled: false
         color_order: RGB
         pclk_frequency: 16MHz
         dimensions:
@@ -171,7 +170,6 @@ Makerfabs 4.3" 800x480 display
     display:
       - platform: rpi_dpi_rgb
         update_interval: never
-        auto_clear_enabled: false
         id: rpi_display
         color_order: RGB
         rotation: 90

components/display/st7701s.rst

@@ -90,8 +90,7 @@ Configuration variables:
 - **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 8MHz.
 - **pclk_inverted** (*Optional* bool): If the pclk is active negative (default is True)
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
-- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
-  or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
+- **auto_clear_enabled** (*Optional*, boolean): If the display should be cleared before each update. Defaults to ``true`` if a lambda or pages are configured, false otherwise.
 - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - **color_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``.
@@ -139,7 +138,6 @@ Seeed Sensecap Indicator
 
     display:
       - platform: st7701s
-        auto_clear_enabled: false
         update_interval: never
         spi_mode: MODE3
         color_order: RGB

components/image.rst

@@ -15,6 +15,7 @@ For showing images downloaded at runtime, take a look at the :ref:`Online Image
 
     image:
       - file: "image.png"
+        type: binary
         id: my_image
         resize: 100x100
 
@@ -23,12 +24,15 @@ For showing images downloaded at runtime, take a look at the :ref:`Online Image
     image:
       - file: mdi:alert-outline
         id: alert
+        type: grayscale
+        use_transparency: alpha_channel
         resize: 80x80
 
 .. code-block:: yaml
 
     image:
       - file: https://esphome.io/_images/logo.png
+        type: rgb565
         id: esphome_logo
         resize: 200x162
 
@@ -46,36 +50,70 @@ Configuration variables:
   in your display code.
 - **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT``
   and preserve the aspect ratio.
-- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local and remote images and ``TRANSPARENT_BINARY`` for MDIs.
+- **type** (**Required**): Specifies how to encode image internally.
 
   - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit
-    per pixel, 8 pixels per byte.
-  - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel
-    will be the on color. Uses 1 bit per pixel, 8 pixels per byte.
+    per pixel, 8 pixels per byte. Only ``chroma_key`` transparency is available.
   - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte.
-  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel.
-  - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel.
-  - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn.
+  - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel, 3 with an alpha channel.
+  - ``RGB``: Full RGB color stored. Uses 3 bytes per pixel, 4 with an alpha channel.
 
-- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``.
+- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account. The possible values are ``opaque`` (default), ``chroma_key`` and ``alpha_channel``. See discussion on transparency below.
 
 - **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here <https://pillow.readthedocs.io/en/stable/reference/Image.html?highlight=Dither#PIL.Image.Image.convert>`__ and `here <https://en.wikipedia.org/wiki/Dither>`__.
 
-  - ``NONE``: Every pixel convert to its nearest color.
+  - ``NONE``: Every pixel converts to its nearest color.
   - ``FLOYDSTEINBERG``: Uses Floyd-Steinberg dither to approximate the original image luminosity levels.
 
 .. note::
 
     To use images you will need to have the python ``pillow`` package installed.
     Additionally, if you want to use SVG images (including MDI images), you will
-    additionally need to have the python ``cairosvg`` package installed.
+    additionally need to have the python ``cairosvg`` package installed. These are automatically installed when
+    setting up ESPHome via the usual methods.
 
-    If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed.
+Grouping images by type
+-----------------------
 
-    Use ``pip install "esphome[displays]"`` to install these optional dependencies with
-    the versions that ESPHome requires.
+You can group images by type to make it easier to manage them. This is useful when you have a lot of images to be encoded in the same way, and avoids having to repeat the same type for each image. The type name is used as the key for the group. For example:
 
-And then later in code:
+.. code-block:: yaml
+
+    image:
+      grayscale:
+        - file: "image1.png"
+          id: image1
+        - file: "image2.png"
+          id: image2
+        - file: "image3.png"
+          id: image3
+
+      rgb565:
+        - file: "image4.png"
+          id: image4
+        - file: "image5.png"
+          id: image5
+
+In addition, the default transparency type can be set within a type group by using the transparency type as a key.
+
+.. code-block:: yaml
+
+    image:
+      rgb565:
+        alpha_channel:
+        - file: "image1.png"
+          id: image1
+        - file: "image2.png"
+          id: image2
+        opaque:
+        - file: "image2.png"
+
+Displaying Images
+-----------------
+
+Images may be used in LVGL configurations wherever an image is required. See the :doc:`LVGL </components/lvgl/index>` documentation for more information.
+
+To display an image directly on an ESPHome display, you can use the ``image`` method in the display lambda.
 
 .. code-block:: yaml
 
@@ -123,3 +161,12 @@ be supplied to modify the color used to represent the on and off bits respective
 
 You can also use this to invert images in two color displays, use ``COLOR_OFF`` then ``COLOR_ON``
 as the additional parameters.
+
+Transparency options
+--------------------
+
+By default transparency is not used. If ``use_transparency: chroma_key`` is set then a specific colour (0, 1, 0) will be used to replace any transparent or partially transparent portions of the image. This will not be drawn when rendering the image, allowing the background to be visible.
+
+If ``use_transparency: alpha_channel`` is set, then each pixel of the image will be assigned an additional byte with a transparency value. This is useful mainly when using :doc:`LVGL </components/lvgl/index>` as the ``alpha_channel`` transparency will enable smooth blending of transparent images with the background.
+When using the display lambda image drawing functions these will draw or not draw the pixel, no blending with the background will be done.
+The ``BINARY`` format only permits ``chroma_key`` transparency, which effectively turns the image into an alpha mask with one bit per pixel. GRAYSCALE images with transparency store the alpha channel only, and remain 1 byte per pixel.

components/lvgl/index.rst

@@ -857,6 +857,24 @@ This :ref:`condition <common_conditions>` checks if LVGL is in the paused state
             then:
               - lvgl.resume:
 
+``lvgl.page.is_showing``
+************************
+
+This :ref:`condition <common_conditions>` checks if the nominated page is the one currently showing.
+
+- **id** (**Required**): The ID of the page to check. May be supplied as a simple value.
+
+.. code-block:: yaml
+
+    # In some trigger:
+    on_...:
+      then:
+        - if:
+            condition:
+              lvgl.page.is_showing: main_page
+            then:
+              - logger.log: "Main page is showing"
+
 Triggers
 --------
 

components/lvgl/widgets.rst

@@ -60,7 +60,6 @@ The properties below are common to all widgets.
 
 - **state** (*Optional*, dict): Widgets or their (sub)parts can have have states, which support separate styling. These state styles inherit from the theme, but can be locally set or overridden within style definitions. Can be one of:
     - **checked** (*Optional*, boolean): Toggled or checked state.
-    - **default** (*Optional*, boolean): Normal, released state.
     - **disabled** (*Optional*, boolean): Disabled state (also usable with :ref:`shorthand <lvgl-automation-shorthands>` actions ``lvgl.widget.enable`` and ``lvgl.widget.disable``).
     - **edited** (*Optional*, boolean): Edit by an encoder.
     - **focus_key** (*Optional*, boolean): Focused via keypad or encoder but *not* via touch screen.
@@ -805,7 +804,7 @@ Images are the basic widgets used to display images.
 
 .. note::
 
-    Currently ``RGB565`` type images are supported, with transparency using the optional parameter ``use_transparency`` set to ``true``. See :ref:`display-image` for how to load an image for rendering in ESPHome.
+    Currently ``RGB565`` type images are supported, with transparency using the optional parameter ``use_transparency`` set. See :ref:`display-image` for how to load an image for rendering in ESPHome.
 
 .. tip::
 

cookbook/lvgl.rst

@@ -1190,7 +1190,7 @@ To display a boot image with a spinner animation which disappears automatically
         id: boot_logo
         resize: 200x200
         type: RGB565
-        use_transparency: true
+        use_transparency: alpha_channel
 
     lvgl:
       ...

guides/getting_started_command_line.rst

@@ -237,6 +237,8 @@ To start the ESPHome dashboard, simply start ESPHome with the following command
 
 After that, you will be able to access the dashboard through ``localhost:6052``.
 
+Logging level can be set with the env var `ESPHOME_LOG_LEVEL` (default is `INFO`).
+
 .. figure:: images/dashboard_states.png
 
 See Also

web-api/index.rst

@@ -320,6 +320,33 @@ method is ``set``. The following parameter can be used:
 
 For example POST ``/number/desired_delay/set?value=24`` will set the number to 24.
 
+Alarm Control Panel
+*******************
+
+The current state of an Alarm Control Panel can be retrieved by a GET request to ``alarm_control_panel/my_alarm``
+which may yield:
+
+.. code-block:: json
+
+    {
+      "id": "alarm-control-panel-my_alarm",
+      "state": "ARMED_AWAY",
+      "value": 2
+    }
+
+-  **id**: The ID of the alarm control panel, prefixed with ``alarm-control-panel-``.
+-  **state**: ``DISARMED``, ``ARMED_HOME``, ``ARMED_AWAY``, ``ARMED_NIGHT``, ``ARMED_VACATION``, 
+   ``ARMED_CUSTOM_BYPASS``, ``PENDING``, ``ARMING``, ``DISARMING``, or ``TRIGGERED``.
+-  **value**: Current state as number. See the ``AlarmControlPanelState`` enum.
+
+A POST request allows arming and disarming the alarm control panel. Available methods are ``arm_away``, ``arm_home``,
+``arm_night``, ``arm_vacation`` and ``disarm``. The ``code`` parameter may be given if the alarm control panel requires
+a code for disarming or arming. For example, a POST to ``alarm_control_panel/my_alarm/disarm?code=1234`` would attempt to
+disarm the alarm control panel named "My Alarm" using the code 1234.
+
+A valid POST request will always return a 200 OK status response. This does not indicate that the alarm was armed or
+disarmed successfully. It only indicates that the command was received and processed by the web server.
+
 See Also
 --------