Merge e2b1f83256 into 696a828156

components/binary_sensor/lvgl.rst

@@ -0,0 +1,41 @@
+.. _lvgl-bse:
+
+LVGL Binary Sensor
+==================
+
+.. seo::
+    :description: Instructions for setting up a LVGL widget binary sensor.
+    :image: ../images/lvgl_c_bns.png
+
+The ``lvgl`` binary sensor platform creates a binary sensor from a LVGL widget
+and requires :ref:`LVGL <lvgl-main>` to be configured.
+
+Supported widget is :ref:`lvgl-wgt-btn`. A single binary sensor supports
+a single widget, thus you need to choose among which one's state you want to use.
+
+Configuration options:
+----------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (**Required**, string): The name of the binary sensor.
+- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the binary sensor.
+- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
+
+Example:
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: lvgl
+        widget: btn_id
+        name: LVGL push button
+
+See Also
+--------
+- :ref:`LVGL Main component <lvgl-main>`
+- :ref:`Button widget <lvgl-wgt-btn>`
+- :doc:`/components/number/lvgl`
+- :doc:`/components/switch/lvgl`
+- :doc:`/components/select/lvgl`
+- :doc:`/components/light/lvgl`
+- :ghedit:`Edit`

components/display/fonts.rst

@@ -9,7 +9,8 @@ Font Renderer Component
 
 ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF <https://en.wikipedia.org/wiki/Portable_Compiled_Format>`_ and `BDF <https://en.wikipedia.org/wiki/Glyph_Bitmap_Distribution_Format>`_ bitmap fonts.
 
-These fonts can be used in ESPHome's :ref:`own rendering engine <display-engine>`.
+
+These fonts can be used in ESPHome's :ref:`own rendering engine <display-engine>` or in the :ref:`LVGL Graphics <lvgl-main>` component.
 
 To use fonts you can either
  - Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file.
@@ -83,8 +84,9 @@ Next, create a ``font:`` section in your configuration:
     display:
       # ...
 
-Configuration variables:
-------------------------
+
+Configuration options:
+----------------------
 
 - **file** (**Required**, string): The path (relative to where the .yaml file is) of the font
   file. You can also use the ``gfonts://`` short form to use Google Fonts, or use the below structure:
@@ -155,6 +157,7 @@ See Also
 
 - :apiref:`display/display_buffer.h`
 - :ref:`display-engine`
+- :ref:`lvgl-main`
 - `MDI cheatsheet <https://pictogrammers.com/library/mdi/>`_
 - `MDI font repository <https://github.com/Pictogrammers/pictogrammers.github.io/tree/main/%40mdi/font/>`_
 - :ghedit:`Edit`

components/display/index.rst

@@ -14,8 +14,18 @@ engine. Fundamentally, there are these types of displays:
 - Graphical binary displays which can toggle ON/OFF any pixel, like :doc:`E-Paper <waveshare_epaper>`,
   :doc:`OLED <ssd1306>` or :doc:`TFT <ili9xxx>` displays.
 
-For the last type, ESPHome has a powerful rendering engine that can do
-many things like draw some basic shapes, print text with any font you want, or even show images.
+For graphical binary displays, there are two options: 
+
+- ESPHome's :ref:`own powerful rendering engine <display-engine>`
+- :ref:`LVGL <lvgl-main>` - Light and Versatile Graphics Library
+
+.. _display-engine:
+
+Display Rendering Engine
+------------------------
+
+ESPHome's own powerful rendering engine can do many things like draw some basic shapes, print text with any font
+you want, or even show images.
 
 To achieve all this flexibility displays tie in directly into ESPHome's :ref:`lambda system <config-lambda>`.
 So when you want to write some text or sensor values to the screen you will be writing in C++ code
@@ -24,11 +34,6 @@ using an API that is designed to
 - be simple and to be used without programming experience
 - but also be flexible enough to work with more complex tasks like displaying an analog clock.
 
-.. _display-engine:
-
-Display Rendering Engine
-------------------------
-
 In this section we will be discussing how to use ESPHome's display rendering engine from ESPHome
 and some basic commands. Please note that this only applies to displays that can control each pixel
 individually.
@@ -964,6 +969,7 @@ See Also
 --------
 
 - :apiref:`display/display_buffer.h`
+- :ref:`LVGL <lvgl-main>`
 - :ref:`Fonts <display-fonts>`
 - :ghedit:`Edit`
 

components/key_collector.rst

@@ -6,13 +6,15 @@ Key collector component
 .. seo::
     :description: Key collector component
 
-The ``key_collector`` component collects key presses from
-components like :ref:`matrix_keypad` or ``wiegand``. It allows you to process
+The ``key_collector`` component collects key presses from components 
+like :ref:`matrix_keypad`, :ref:`Wiegand keypad <wiegand>`
+or :ref:`LVGL Button Matrix widget <lvgl-wgt-bmx>`. It allows you to process
 key sequences and treat them as one, for example to allow inputting of 
 a PIN code or a passkey. The component outputs the result of the keypress
 sequence as a variable usable in automations.
 
 
+
 Component
 ---------
 
@@ -92,7 +94,6 @@ See Also
 --------
 
 - :doc:`/components/matrix_keypad`
-
-.. - :doc:`/components/wiegand`
-
+- :doc:`/components/wiegand`
+- :ref:`LVGL Button Matrix widget <lvgl-wgt-bmx>`
 - :ghedit:`Edit`

components/light/lvgl.rst

@@ -0,0 +1,48 @@
+.. _lvgl-lgh:
+
+LVGL Light
+==========
+
+.. seo::
+    :description: Instructions for setting up a LVGL widget light.
+    :image: ../images/lvgl_c_lig.png
+
+The ``lvgl`` light platform creates a light from a LVGL widget
+and requires :ref:`LVGL <lvgl-main>` to be configured.
+
+Supported widgets are :ref:`lvgl-wgt-led`. A single light supports
+a single widget, thus you need to choose among which one's state you want to use.
+
+
+Configuration options:
+----------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (**Required**, string): The name of the light.
+- **led** (**Required**): The ID of a ``led`` widget configured in LVGL, which will reflect the state of the light.
+- All other options from :ref:`light <config-light>`.
+
+
+Example:
+
+.. code-block:: yaml
+
+    light:
+      - platform: lvgl
+        led: led_id
+        name: LVGL light
+
+.. note::
+
+    To have linear brightness control, ``gamma_correct`` of the light is set by default to ``0``.
+
+
+See Also
+--------
+- :ref:`LVGL Main component <lvgl-main>`
+- :ref:`LED widget <lvgl-wgt-led>`
+- :doc:`/components/binary_sensor/lvgl`
+- :doc:`/components/switch/lvgl`
+- :doc:`/components/number/lvgl`
+- :doc:`/components/select/lvgl`
+- :ghedit:`Edit`

components/number/lvgl.rst

@@ -0,0 +1,45 @@
+.. _lvgl-num:
+
+LVGL Number
+===========
+
+.. seo::
+    :description: Instructions for setting up a LVGL widget number component.
+    :image: ../images/lvgl_c_num.png
+
+The ``lvgl`` number platform creates a number component from a LVGL widget
+and requires :ref:`LVGL <lvgl-main>` to be configured.
+
+Supported widgets are :ref:`lvgl-wgt-arc`, :ref:`lvgl-wgt-bar`, :ref:`lvgl-wgt-sli` and :ref:`lvgl-wgt-spb`. A single number supports a single widget, thus you need to choose among which one's state you want to use.
+
+Configuration options:
+----------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (**Required**, string): The name of the number.
+- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the number.
+- **animated** (*Optional*, boolean): Whether to set the value of the widget with an animation (if supported by the widget). Defaults to ``true``.
+- All other options from :ref:`Number <config-number>`.
+
+Example:
+
+.. code-block:: yaml
+
+    number:
+      - platform: lvgl
+        widget: slider_id
+        name: LVGL Slider
+
+
+See Also
+--------
+- :ref:`LVGL Main component <lvgl-main>`
+- :ref:`Arc widget <lvgl-wgt-arc>`
+- :ref:`Bar widget <lvgl-wgt-bar>`
+- :ref:`Slider widget <lvgl-wgt-sli>`
+- :ref:`Spinbox widget <lvgl-wgt-spb>`
+- :doc:`/components/binary_sensor/lvgl`
+- :doc:`/components/switch/lvgl`
+- :doc:`/components/select/lvgl`
+- :doc:`/components/light/lvgl`
+- :ghedit:`Edit`

components/select/lvgl.rst

@@ -0,0 +1,42 @@
+.. _lvgl-sel:
+
+LVGL Select
+===========
+
+.. seo::
+    :description: Instructions for setting up a LVGL widget select.
+    :image: ../images/lvgl_c_sel.png
+
+The ``lvgl`` switch platform creates a select from a LVGL widget
+and requires :ref:`LVGL <lvgl-main>` to be configured.
+
+Supported widgets are :ref:`lvgl-wgt-drp` and :ref:`lvgl-wgt-rol`. A single select supports
+a single widget, thus you need to choose among which one's state you want to use.
+
+Configuration options:
+----------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (**Required**, string): The name of the select.
+- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the select.
+- All other options from :ref:`Select <config-select>`.
+
+Example:
+
+.. code-block:: yaml
+
+    select:
+      - platform: lvgl
+        widget: dropdown_id
+        name: LVGL Dropdown
+
+See Also
+--------
+- :ref:`LVGL Main component <lvgl-main>`
+- :ref:`Roller widget <lvgl-wgt-rol>`
+- :ref:`Dropdown widget <lvgl-wgt-drp>`
+- :doc:`/components/binary_sensor/lvgl`
+- :doc:`/components/switch/lvgl`
+- :doc:`/components/number/lvgl`
+- :doc:`/components/light/lvgl`
+- :ghedit:`Edit`

components/switch/lvgl.rst

@@ -0,0 +1,47 @@
+.. _lvgl-swi:
+
+LVGL Switch
+===========
+
+.. seo::
+    :description: Instructions for setting up a LVGL widget switch.
+    :image: ../images/lvgl_c_swi.png
+
+The ``lvgl`` switch platform creates a switch from a LVGL widget
+and requires :ref:`LVGL <lvgl-main>` to be configured.
+
+Supported widgets are :ref:`lvgl-wgt-btn` (with ``checkable`` option enabled), :ref:`lvgl-wgt-swi` and :ref:`lvgl-wgt-chk`. A single switch supports a single widget, thus you need to choose among which one's state you want to use.
+
+
+Configuration options:
+----------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (**Required**, string): The name of the switch.
+- **widget** (**Required**): The ID of a supported widget configured in LVGL, which will reflect the state of the switch.
+- **output_id** (*Optional*, :ref:`config-id`): The ID of a **binary** output to drive in sync with the ``checked`` state of the configured widget.
+- All other options from :ref:`Switch <config-switch>`.
+
+Example:
+
+.. code-block:: yaml
+
+    switch:
+      - platform: lvgl
+        widget: checkbox_id
+        name: LVGL switch
+
+Check out :ref:`lvgl-cook-outbin` in the Cookbook for an example how to set up a LVGL Switch component to interact directly with a GPIO.
+
+See Also
+--------
+- :ref:`LVGL Main component <lvgl-main>`
+- :ref:`Button widget <lvgl-wgt-btn>`
+- :ref:`Switch widget <lvgl-wgt-swi>`
+- :ref:`Checkbox widget <lvgl-wgt-chk>`
+- :doc:`/components/binary_sensor/lvgl`
+- :doc:`/components/number/lvgl`
+- :doc:`/components/select/lvgl`
+- :doc:`/components/light/lvgl`
+- :doc:`/components/output/index`
+- :ghedit:`Edit`

components/touchscreen/index.rst

@@ -1,3 +1,5 @@
+.. _touchscreen-main:
+
 Touchscreen Components
 ======================
 

components/wiegand.rst

@@ -1,3 +1,5 @@
+.. _wiegand:
+
 Wiegand keypad and tag reader
 =============================
 

index.rst

@@ -589,6 +589,7 @@ Touchscreen
     GT911, components/touchscreen/gt911, esp32_s3_box_3.png
     Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg
     TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png
+    LVGL widget, components/binary_sensor/lvgl, lvgl_c_bns.png
 
 Presence Detection
 ******************
@@ -668,6 +669,7 @@ Light Components
     H-bridge Light, components/light/hbridge, brightness-medium.svg, dark-invert
     Light Partition, components/light/partition, color_lens.svg, dark-invert
     LightWaveRF, components/lightwaverf, brightness-medium.svg
+    LVGL widget, components/light/lvgl, lvgl_c_lig.png
     Monochromatic Light, components/light/monochromatic, brightness-medium.svg, dark-invert
     NeoPixelBus Light, components/light/neopixelbus, color_lens.svg, dark-invert
     RGB Light, components/light/rgb, rgb.png
@@ -696,6 +698,7 @@ Switch Components
     Factory Reset Switch, components/switch/factory_reset, restart-alert.svg, dark-invert
     Generic Output Switch, components/switch/output, upload.svg, dark-invert
     GPIO Switch, components/switch/gpio, pin.svg, dark-invert
+    LVGL Widget, components/switch/lvgl, lvgl_c_swi.png
     Modbus Switch, components/switch/modbus_controller, modbus.png
     Nextion Switch, components/switch/nextion, nextion.jpg
     Restart Switch, components/switch/restart, restart.svg, dark-invert
@@ -747,9 +750,11 @@ Display Components
     Display Core, components/display/index, folder-open.svg, dark-invert
     Display Menu Core, components/display_menu/index, folder-open.svg, dark-invert
     Font Renderer, components/display/fonts, format-font.svg, dark-invert
-
     Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png
     LCD Menu, components/display_menu/lcd_menu, lcd_menu.png
+    LVGL Graphics, components/lvgl, lvgl.png
+
+.. _display-hw:
 
 Display Hardware Platforms
 --------------------------
@@ -881,6 +886,7 @@ Number Components
 
     Number Core, components/number/index, folder-open.svg, dark-invert
     Template Number, components/number/template, description.svg, dark-invert
+    LVGL widget Number, components/number/lvgl, lvgl_c_num.png
     Modbus Number, components/number/modbus_controller, modbus.png
     Tuya Number, components/number/tuya, tuya.png
 
@@ -891,6 +897,7 @@ Select Components
 
     Select Core, components/select/index, folder-open.svg, dark-invert
     Template Select, components/select/template, description.svg, dark-invert
+    LVGL widget Select, components/select/lvgl, lvgl_c_sel.png
     Modbus Select, components/select/modbus_controller, modbus.png
     Tuya Select, components/select/tuya, tuya.png
 
@@ -1053,6 +1060,7 @@ Cookbook
 .. imgtable::
 
     Lambda Magic: Tips and Tricks, cookbook/lambda_magic, head-lightbulb-outline.svg, dark-invert
+    LVGL Graphic recipes, cookbook/lvgl, lvgl.png
     Garage Door Template Cover, cookbook/garage-door, garage-variant.svg, dark-invert
     Time & Temperature on OLED Display, cookbook/display_time_temp_oled, display_time_temp_oled_2.jpg
     ESP32 Water Leak Detector, cookbook/leak-detector-m5stickC, leak-detector-m5stickC_main_index.jpg

lint.py

@@ -396,6 +396,7 @@ def lint_directive_formatting(fname, content):
     exclude=[
         "components/web_server.rst",
         "components/display/index.rst",
+        "cookbook/lvgl.rst",
     ],
 )
 def lint_esphome_io_link(fname, match):