LVGL pantalla ESP32 con ESPHome

En este tutorial voy a hablar de cómo puedes mejorar tu sistema domótico gracias a LVGL y a una pantalla ESP32 utilizando ESPHome.

Y esto es tremendamente útil si quieres mostrar información de la temperatura que hace en el salón, cuánta sal queda en el descalcificador o un panel para activar o desactivar la alarma de Home Assistant.

Si te interesa todo esto, en este tutorial vas a aprender varias cosas:

• Qué cojones es LVGL y por qué tendrías que utilizarlo
• Por qué hay pantallas ESP32 que cuestan un riñón y otras no
• Cómo configurar una pantalla ESP32 que cuesta menos de 15 leuros
• El código (completo) para poder mostrar la temperatura de una forma muy molona

Capítulos LVGL pantalla táctil ESP32

Y si quieres ir a tiro hecho, aquí te dejo los capítulos del vídeo:

00:00 Introducción

02:17 Resumen de pantalla ESP32 con ESPHome y LVGL para Home Assistant

02:48 Qué es LVGL

04:33 Qué tipo de pantallas ESP32 son compatibles con ESPHome y LVGL

06:11 Pantallas ESP32 baratas CYD

08:03 Código ESPHome pantalla y táctil

13:26 Código ESPHome componente LVGL

18:05 Integración con Home Assistant

20:13 Cómo llevarte de regalo 3 códigos ESPHome

Qué es LVGL

LVGL no es uno de los equipos que ha corrido el Tour de Francia, LVGL es el acrónimo de Light and Versatile Graphics Library (Librería Gráfica Versátil y Ligera). Se trata de una librería o biblioteca de programación para gráficos.

Es gratuita, de código abierto y proporciona todo lo necesario para crear interfaces gráficas espectaculares y con un consumo de memoria muy bajo lo que la hace especialmente útil para proyectos embebidos, es decir, para microcontroladores.

Es compatible con cualquier MCU, MPU y tipo de pantalla y se utiliza en electrónica de consumo como relojes, termostatos o estaciones meteorológicas y en la automatización industrial. La gran ventaja de esta librería es que es relativamente sencillo utilizarla ya que incorpora más de 30 widgets preconfigurados que se pueden modificar con 100 propiedades de estilo.

Y aunque todo esto puede parecer fantástico, uno de los mayores inconvenientes a la hora de utilizar esta librería es que, hasta hace poco, era necesario tener una amplia experiencia en programación con C++ lo que hacía muy complicado usar la librería LVGL en nuestros proyectos domóticos.

Todo esto a cambiado gracias a que ESPHome a incorporado LVGL en la versión 2024.8 y ahora podemos utilizar la librería LVGL en nuestros proyectos con ESPHome de una manera mucho más sencilla.

De eso es de lo que voy a habar en este tutorial, de cómo utilizar LVGL con ESPHome y una pantalla ESP32 porque para poder ver esas interfaces gráficas tan chulas, vamos a necesitar una pantalla.

Pantalla ESP32

Entrar en el mundo de las pantallas es abrir un melón que puede que nos explote en toda la cara así que voy a ceñirme en hablar muy por encima de algunas de las pantallas ESP32 más populares pero sobre todo de las pantallas ESP32 compatibles con ESPHome y LVGL.

Según la documentación oficial de ESPHome LVGL es compatible con cualquier pantalla, pero para utilizarlo con ESPHome s necesario utilizar un ESP32 o una variante compatible con ESP32 lo que descarta cualquier ESP8266.

Aunque no es necesario que utilice PSRAM (tecnología de memoria RAM más rápida y avanzada) se recomienda sobre todo en pantallas a color y con resoluciones superiores a 240 x 240 píxeles.

También se pueden utilizar pantalla táctiles para interactuar con los componentes LVGL a poder ser capacitiva.

Con estas características es muy habitual hoy en día encontrarse placas donde tienes todo integrado, es decir, vienen con un microcontrolador ESP32, un pantalla y toda la electrónica necesaria para que aquello funcione de forma independiente.

Se han hecho tan populares las pantallas basadas en el ESP32 que los chinos inundaron el mercado con cientos de pantallas baratas. Es más, no se cuál es el motivo (o sí) pero todas esas pantallas suelen ser de «color amarillo» las cuales tomaron el nombre de CYD (del inglés Cheap Yellow Display o Pantalla Amarilla Barata).

Y pasó lo que tenía que pasar, que se montó un lío de tres pares de pelotas. Sólo tienes que buscar «pantalla ESP32» o «ESP32 display» y verás de lo que hablo.

Entonces, ¿Cuáles son las mejores? ¿Qué diferencia hay entre unas y otras? ¿Son todas compatibles con ESPHome y LVGL?

Todo depende de lo que necesites y cuánto te quieras gastar pero vamos a dividir las pantallas en dos tipos: pantallas de fabricantes y pantallas de la marca Nisu (Ni Su Padre Los Conoce). En este último grupo entran todas las pantallas CYD.

A la hora de comprar una pantalla ESP32 tienes que fijarte en cuatro cosas:

• El chip o driver que gestiona la pantalla.
• El chip o driver que gestiona la pantalla táctil si tiene.
• Los pines que utiliza para conectar estos dos chips con el ESP32.
• El modelo de ESP32 que utiliza.

Esta información es fundamental para poder utilizar una pantalla ESP32 con ESPHome y LVGL. No saber esto significa que vas a dar palos de ciego y que puede que no funcione. De ahí que la mejor opción, y quizás la más cara, sea utilizar pantallas de algún fabricante reconocido ya que están totalmente documentadas y son compatibles con ESPHome.

Las dos más populares son de la empresa Lilygo, aunque hay otras.

Lilygo T4-S3

Pantalla de la empresa Lilygo con un microcontrolador ESP32-S3, 8MB de PSRAM y una pantalla táctil con una resolución de 600 x 450 píxeles.

Eso sí, el precio de esta pantalla dependerá de donde la compres pero ronda los 60€.

• Amazon
• Aliexpress

Configuración de la pantalla con ESPHome:

• Lilygo T4-S3

Lilygo T-Display-S3

Se trata de un modelo más asequible de Lilygo que utiliza un microcontrolador ESP32-S3, 8MB de PSRAM y una pantalla táctil con una resolución de 320 x 170.

El precio de la pantalla ronda los 30€:

• Amazon
• Aliexpress

Configuración de la pantalla con ESPHome:

• Lilygo T-Display-S3

Otros modelos

Aparte de estos modelos, puedes echar un vistazo a estas pantallas:

• Nextion TFT LCD Display
• E-paper Inkplate 6, 10 and 6 Plus

Tienes más información sobre pantallas en las sección de Display Hardware Platform y Touchscreen Components. Veamos qué pasa si compro una pantalla Nisu

Pantallas Amarillas Baratas CYD

A ver, las pantallas que hemos visto están muy bien pero si por lo que sea quieres utilizar pantallas hasta en el cagadero te va a salir un poco caro. Si es tu caso puedes utilizar pantallas más baratas como las CYD y otros modelos que veremos a continuación.

El problema de utilizar estas pantallas es que vas a necesitar investigar para averiguar el chip que gestiona la pantalla, el chip que gestiona la parte táctil, cómo están conectados con el ESP32 (los pines) y qué modelo de ESP32 utiliza. Y esto puede ser una tarea bastante compleja.

Un buen punto de partida es este proyecto de GitHub donde tienes documentados muchas de las pantallas amarillas baratas CYD del mercado.

Esta es la razón por la que voy a hablar de la única que he probado y que sé que funciona la pantalla ESP32-2432S028 que he investigado y documentado. Del resto no puedo opinar por el momento.

El modelo ESP32-2432S028 es bastante popular y lo puedes encontrar en Amazon por unos 25€ y en Aliexpress por 14€.

Importante. Ojo con lo que compras en Aliexpress no vaya a ser que te den gato por pollo.

Todas estas placas se identifican muy fácilmente por la parte trasera ya que cada modelo es diferente. Cada una de ellas tiene sus conectores, pulsadores e incluso en este caso tiene un LED RGB. Pero sobre todo porque viene serigrafiado el modelo.

Sus características son las siguientes:

• Microcontrolador ESP32-WROOM-32
• No tiene memoria PSRAM
• Utiliza una pantalla TFT de 240×320
• El driver para la pantalla es el ILI9341 (compatible con ESPHome)
• El driver para la pantalla táctil es el XPT2046 (compatible con ESPHome)

En cuanto a los pines, las conexiones son las siguientes. Tanto para la pantalla como para el táctil utiliza el bus de datos SPI con los siguientes pines.

Pantalla:

• CLK: GPIO14
• MOSI: GPIO13
• MISO: GPIO12
• CS: GPIO15
• DC: GPIO2

En cuanto a la pantalla táctil utiliza los siguientes:

• CLK: GPIO25
• MOSI: GPIO32
• MISO: GPIO39
• CS: GPIO33
• INTERRUPT: GPIO36

Aparte, necesitamos conocer el pin donde está conectada la luz trasera para poder encenderla.

• Pin luz trasera: GPIO21

Con esta información sería suficiente para empezar a programar nuestra pantalla con ESPHome.

Pantalla ESP32 con ESPHome

Lo primero es tener un proyecto base donde configuramos el nombre, el modelo de placa, OTA y la WiFi. Sería algo como esto.

Sobre todo fíjate en el tipo de placa que tienes que ser un ESP32 y el módulo esp32dev. El resto suele ser estándar. A continuación vamos a incorporar la configuración del componente SPI tanto de la pantalla como del táctil donde vamos a indicar los pines que hemos visto antes.

Este código lo tienes que configurar a continuación.

A continuación configuramos el componente display de la plataforma ili9xxx con los siguientes parámetros.

Donde:

• platform: es la plataforma que vamos a utilizar ili9xxx.
• id: tienes que poner un identificador único.
• model: es el driver que utiliza la pantalla en este caso ILI9341.
• spi_id: es el identificador de la configuración SPI para la pantalla y lo encontramos en el componente SPI que hemos configurado antes.
• auto_clear_enabled: la documentación de LVGL de ESPHome dice que hay que desactivar esta opción (false).
• update_interval: la documentación de LVGL de ESPHome dice que nunca hay que actualizar (never).
• dimensions: se establece el alto y el ancho. En este caso, la posición por defecto de la pantalla es en vertical por eso la altura (height) es 320 y el ancho (width) es 240.
• cs_pin: el pin CS.
• dc_pin: el pin DC.

Continuamos con la configuración de la pantalla táctil.

Donde:

• platform: es el driver de la pantalla táctil en este caso es XPT2046.
• id: tienes que poner un identificador único a la pantalla.
• spi_id: es el identificador de la configuración SPI para la pantalla táctil y lo encontramos en el componente SPI que hemos configurado antes.
• cs_pin: es el pin CS.
• inerrupt_pin: es el pin INTERRUPT.

Por último, para poder ver la pantalla es necesario encender la luz trasera que tienen estas pantallas ya que por defecto vienen apagadas y si no se enciende no se va a ver nada. Para ello utilizamos el siguiente código.

El código completo sería el siguiente.

Prueba a subirlo y verás cómo la pantalla se enciende y se queda en blanco.

Importante. Puedes gestionar el encendido y apagado de la luz trasera utilizando un componente interval y un evento en la pantalla táctil para que cuando se toque si está apagada se encienda.

El siguiente paso es darle vida con un gráfico de un sensor de Home Assistant utilizando LVGL con ESPHome.

LVGL ESPHome y pantalla ESP32

Una vez configurada la pantalla ya podemos empezar a dibujar con la librería LVGL. Si has trabajado alguna vez con páginas web verás que se diseña de forma muy parecida. Intentar resumir todo lo que se puede hacer con LVGL en un tutorial sería imposible.

Sin embargo, hay varios puntos claves que deberías tener en cuenta:

1. En LVGL los elementos gráficos como botones, etiquetas, controles deslizantes, gráficos, etc.. se denominan widgets. Puedes consultar la lista de widgets compatibles con ESPHome en la documentación oficial.
2. Cada widget pertenece a un widget padre donde se crea. Por ejemplo, un gráfico puede tener un hijo que sea una etiqueta que indique qué valor se representa en el eje X. Hay widgets complejos que tienen con varios widgets hijos más pequeños y simples dotando al widget padre. Esto es lo que realmente hace que las interfaces sean tan espectaculares.
3. En ESPHome el widget principal de donde salen los demás widgets son las páginas. Son widgets especiales que no tienen padre y siempre tiene que haber una página activa en cada pantalla.
4. Los widgets se pueden comunicar con los dispositivos y entidades de Home Assistant para obtener información y mostrarla en la interfaz gráfica de diferentes maneras.

Con esas premisas vamos a ir creando el código LVGL de ESPHome para la pantalla ESP32. Y lo primero es la configuración básica del componente LVGL.

A destacar:

• displays: es un listado con los identificadores de las pantallas configuradas que vamos a utilizar en nuestro caso ponemos el identificador de la pantalla ESP32 que hemos configurado.
• touchscreens: igual que el anterior, listado de identificadores de las pantallas táctiles que vas a utilizar y que tienes configuradas en el archivo de ESPHome.
• buffer_size: qué porcentaje de la pantalla se almacena en la memoria. Para pantallas sin PSRAM lo aconsejable es 25%.
• bg_color: color de fondo de la pantalla.

A continuación tenemos que añadir las páginas, en nuestro caso va a ser una, y los widgets que vamos a tener en esa página. Dentro del listado de widgets LVGL de ESPHome vamos a utilizar el widget meter que nos permite mostrar una magnitud con el típico gráfico de aguja pero vamos a darle algo de color y diseño.

La configuración principal de esta parte es la siguiente.

Fíjate como la indentación (los espacios libres desde el margen izquierdo) ponen en relieve la jerarquía de los componentes.

Primero tenemos las páginas (pages) donde van a colgar todas las páginas cada una identificada con un id. De ahí cuelgan los hijos, los widgets de esta pantalla. En nuestro caso tendremos 3 widgets y el primero es el gráfico de aguja meter.

El widget meter permite varias configuraciones pero las más importantes son las que vemos colgando del propio widget. Aparte de los parámetros de configuración de este widget van a colgar otros widgets más simples que darán forma al gráfico empezando por el scales.

Las escalas indican cómo se van a mostrar los datos y lo básico es determinar el rango, es decir, el valor mínimo (range_from) y el valor máximo (range_to). En el caso de la temperatura de mi salón va de 0 a 40.

A continuación vamos a establecer los separadores o líneas, en mi caso no me gustan ya que voy a mostrar la temperatura con texto y decido que no aparezcan separadores para indicar la temperatura añadiendo el siguiente código.

El siguiente paso es añadir los widgets indicadores que nos van a permitir representar esa magnitud en la gráfica y el primer indicador es la línea que representa la manecilla del reloj indicando la temperatura en la gráfica. Para ello añade el siguiente código.

Es importante que asignes un identificador (id) a widget line ya que luego lo actualizaremos de forma dinámica. El resto de parámetros sirven para determinar el grosor de la línea (width), el color (color) y el valor inicial (value).

Si cargas este código verás algo parecido a esto donde ya se empieza a ver la gráfica aunque todavía nos queda darle un poco de color y diseño.

Para dar un poco de color vamos a crear varios arcos en diferentes rangos y con diferentes colores para que, según la temperatura, podamos ver si hace frío o calor. La idea es hacer estos rangos:

• De 0 a 15 grados color azul
• De 15 a 25 grados color azul verdoso
• De 25 a 32 grados color naranja
• De 32 a 40 grados color rojo

Esto se traduce en 4 widgets tipo arc con la siguiente configuración.

Si cargas el código verás algo parecido a esto.

Esto se va pareciendo cada vez más a una estación meteorológica pero aún podemos hacer algo más y es poner dos etiquetas para dar más información. Esto se hace añadiendo dos widgets del tipo label. Estos componentes deben colgar directamente de los widgets de la página.

Hay que dar un poco de diseño estableciendo la fuente, el color del texto e incluso un valor inicial. A la primera etiqueta pon un identificador único porque luego la actualizaremos de forma dinámica. Si cargas el código a la pantalla ESP32 verás algo parecido a esto.

Con esto ya tendríamos el diseño de la gráfica y lo único que nos quedaría sería poder obtener los datos de Home Assistant y vincularlos a la gráfica. Para ello vamos a utilizar un sensor de ESPHome con la plataforma homeassistant.

Este tipo de sensores nos permiten rescatar información de Home Assistant para tratarla y manipularla dentro de un código de ESPHome. La declaración básica de este tipo de sensores es la siguiente.

Donde:

• platform: plataforma que utiliza el sensor en este caso es homeassistant.
• name: da un nombre al sensor dentro del código ESPHome
• entity_id: es el identificador de la entidad con la que se va a vincular el sensor de Home Assistant. Tienes que entrar en Home Assistant, buscar la entidad y copiar el identificador.

• id: identificador único de este sensor dentro del código de Home Assistant.

De esta forma hemos configurado un sensor en ESPHome que está vinculado con un sensor dentro de Home Assistant. Lo único que nos queda es configurar las acciones para que cuando cambie el valor del sensor también cambie el valor de la aguja de la gráfica y del texto del widget label.

Esto se hace añadiendo las siguientes acciones.

Hay que crear una acción para cada componente que quieres actualizar, el widget indicador y el label.

Código completo LVGL ESPHome y pantalla ESP32

Este es el código completo.

Es importante que una vez cargado el código a la pantalla ESP32, añadas el dispositivo a Home Assistant a través de la integración de ESPHome y que autorices la actualización de datos desde Home Assistant a ESPHome para ese nodo.

Y con eso damos por finalizado este tutorial, cualquier duda o sugerencia en los comentarios.

Gracias a Depositphotos por ceder algunas de las imágenes de este artículo.