ESPHome

Este tutorial te guía para diseñar una interfaz en Lopaka y exportarla a una configuración de ESPHome para cualquier microcontrolador compatible con ESPHome.

¿Qué es ESPHome?

ESPHome convierte los microcontroladores ESP8266/ESP32 más comunes en dispositivos de hogar inteligente que se administran desde un único archivo YAML. Su componente display: controla una gran variedad de pantallas (OLED, TFT, e-paper y más) mediante un lambda de C++ con los comandos de dibujo.

Primeros pasos con ESPHome y Home Assistant: https://esphome.io/guides/getting_started_hassio/

Requisitos previos

• Un dispositivo compatible con ESPHome.
• Una configuración YAML básica de ESPHome para tu dispositivo, con una plataforma display definida.

Paso 0: crea un proyecto nuevo

1. Ve a lopaka.app y crea un proyecto nuevo.
2. Selecciona ESPHome en la lista de plataformas.
3. Ajusta el Tamaño de pantalla a la resolución de tu pantalla.
4. Define el color de fondo (el predeterminado es negro, #000000).

Paso 1: diseña y exporta desde Lopaka

1. Dibuja tu interfaz con la barra de herramientas. Ponle un nombre claro a cada capa: los nombres de las capas se convierten en comentarios del código y en nombres de variables en la salida. Usa el ícono del ojo en la lista de capas para ocultar las capas que no quieras exportar.
2. En el panel Ajustes de código, configura las opciones de exportación:
   • Incluir fuentes: necesario si usas texto o fuentes personalizadas.
   • Declarar imágenes: actívalo si tu diseño contiene íconos o gráficos pintados.
   • Declarar variables: actívalo si tu interfaz depende de datos dinámicos.
3. Desmarca Función contenedora si vas a pegar el código directamente en un bloque lambda: de ESPHome existente, para que Lopaka solo emita las llamadas de dibujo it.*.
4. Haz clic en Copiar para guardar el código generado en el portapapeles.

Características de la plataforma

Antes de dibujar, ten en cuenta las restricciones que se aplican a todos los proyectos de ESPHome en Lopaka:

• Modelo de color: RGB completo. Los colores se codifican como Color(R, G, B) en el lambda generado; el blanco es el color predeterminado de ESPHome (COLOR_ON), así que Lopaka omite el argumento de color en las capas blancas.
• Imágenes: solo XBMP (monocromo de 1 bit); no hay exportación de mapas de bits RGB para ESPHome. Los íconos y las capas pintadas siempre se exportan como mapas de bits binarios.
• Sin rectángulos redondeados: la API de pantallas de ESPHome no tiene una primitiva de rectángulo redondeado.

Herramientas de dibujo disponibles

Todas las herramientas estándar de Lopaka están disponibles en los proyectos de ESPHome:

Herramienta	Método de ESPHome
Línea	it.line(x1, y1, x2, y2, color)
Rectángulo (contorno)	it.rectangle(x, y, w, h, color)
Rectángulo (relleno)	it.filled_rectangle(x, y, w, h, color)
Círculo (contorno)	it.circle(x, y, r, color)
Círculo (relleno)	it.filled_circle(x, y, r, color)
Triángulo (contorno)	it.triangle(x1,y1, x2,y2, x3,y3, color)
Triángulo (relleno)	it.filled_triangle(x1,y1, x2,y2, x3,y3, color)
Polígono	Serie de llamadas a it.line()
Texto	it.print(x, y, id(font), color, "text")
Ícono / Imagen	it.image(x, y, id(image), color)

Paso 2: agrega el código a ESPHome

1. Abre el archivo de configuración YAML de ESPHome de tu dispositivo.
2. Busca el componente display y su bloque lambda, o usa el de Lopaka si no existe.
3. Pega el código que dibuja la interfaz dentro de la sección lambda. Asegúrate de que la sangría (tabulaciones o espacios) cumpla los estrictos requisitos YAML de ESPHome.

Con el ajuste Función contenedora activado, la salida completa se ve así:

font:
    - file: 'gfonts://Roboto'
      id: roboto_24
      size: 24

display:
    lambda: |-
        // title
        it.print(10, 10, id(roboto_24), "Hello ESPHome!");
        // border
        it.rectangle(0, 0, 128, 64);

Pega esto en el nivel raíz de tu YAML. Si ya tienes una sección font: o display:, combina las entradas nuevas en lugar de duplicar la clave.

Paso 3: corrige los errores de fuentes y declaraciones

Un error habitual al pegar código de Lopaka directamente en ESPHome es que falten declaraciones de fuentes o que estén mal ubicadas.

Saca las fuentes del lambda

El código exportado desde Lopaka incluye una sección font:. Debe ir en el nivel raíz de tu YAML, no dentro del lambda de display.

Advertencia

font: e image: son claves YAML de nivel superior. Si las colocas dentro de la cadena lambda:, se producirá un error de compilación.

Elimina los duplicados

Si tu configuración de ESPHome ya tiene un bloque font:, no agregues un segundo. Combina las entradas de fuentes de Lopaka con tus declaraciones existentes.

Tipos de fuentes

Google Fonts es la opción más sencilla: las fuentes se descargan automáticamente al compilar mediante gfonts://:

font:
    - file: 'gfonts://Roboto'
      id: roboto_24
      size: 24

Imágenes

Los íconos y las capas pintadas se convierten a XBMP y se exportan como imágenes BINARY. Ajustes de código → Imágenes muestra cada imagen como <Name>.png, con el nombre de su capa; el YAML hace referencia a ella como images/<Name>.png. Descarga el PNG y colócalo en una subcarpeta images/:

# You may need to download images and put them into esphome folder
image:
    - file: 'images/my_icon.png'
      id: img_my_icon
      resize: 32x32
      type: BINARY

Variables

Activa Declarar variables para que las propiedades de las capas sean dinámicas en tiempo de ejecución. Cualquier propiedad de capa (posición, tamaño, texto, color) marcada como variable se extrae en una declaración con tipo al principio del lambda:

const char* my_label_text = "Hello";
int my_label_x = 10;

// my_label
it.print(my_label_x, 20, id(roboto_24), my_label_text);

Los nombres de las variables salen del título de la capa: cambia el nombre de las capas en la lista de capas para obtener nombres limpios en la salida.

Leer valores de ESPHome y Home Assistant

Desactiva Declarar variables para dibujar texto que proviene de un componente de ESPHome, como un sensor o un text_sensor de Home Assistant. Marca el texto de la capa de texto como variable y ponle a la capa el id del componente:

• El texto simple lee un valor de texto: it.print(30, 20, id(Montserrat_26), id(day_of_week).state.c_str());
• El texto con un formato printf, como %.1f °C, imprime un valor numérico: it.printf(75, 298, id(Montserrat_30), "%.1f °C", id(temp_in).state);

Los valores de los sensores son números de coma flotante, así que usa %.0f, %.1f, etc., y escribe %% para un signo de porcentaje literal. El lienzo muestra el texto de formato tal como lo escribiste. Declara en tu YAML el bloque sensor: o text_sensor: correspondiente con el mismo id.

Paso 4: instala y flashea

Cuando las fuentes estén separadas del lambda y no queden errores de validación:

1. Haz clic en Install en el panel de ESPHome.
2. Elige el método de instalación: Wirelessly (OTA) o Via USB.
3. Espera a que el firmware se compile y se cargue. Cuando la carga termine correctamente, el dispositivo se reinicia y muestra la interfaz que creaste en Lopaka.

Referencia de ajustes de código

Ajuste	Predeterminado	Efecto
Función contenedora	Activado	Envuelve la salida en un bloque display: lambda:
Comentarios, títulos de capas	Activado	Agrega un comentario // layer name antes de cada llamada de dibujo
Incluir fuentes	Activado	Emite el bloque font: con todas las fuentes usadas
Declarar imágenes	Activado	Emite el bloque image: con todas las capas de mapa de bits
Declarar variables	Activado	Extrae las propiedades variables de las capas en declaraciones con tipo al principio del lambda

Solución de problemas

Font not declared Falta el bloque font: o está dentro del lambda. Muévelo al nivel raíz de tu YAML.

Duplicate key font Ya tienes un bloque font:. Combina en él las entradas de fuentes de Lopaka en lugar de agregar un segundo bloque.

Image file not found Crea una subcarpeta images/ junto a tu YAML de ESPHome y coloca ahí los archivos PNG.