ESPHome

Este tutorial orienta você a projetar uma interface no Lopaka e exportá-la para uma configuração ESPHome para qualquer microcontrolador compatível com ESPHome.

O que é o ESPHome?

O ESPHome transforma microcontroladores comuns ESP8266/ESP32 em dispositivos de casa inteligente gerenciados por um único arquivo YAML. Seu componente display: controla uma ampla variedade de telas — OLED, TFT, e-paper e mais — usando uma lambda C++ para comandos de desenho.

Primeiros passos com ESPHome e Home Assistant: https://esphome.io/guides/getting_started_hassio/

Pré-requisitos

• Um dispositivo compatível com ESPHome.
• Uma configuração YAML básica do ESPHome para o seu dispositivo com uma plataforma display definida.

Etapa 0: Crie um novo projeto

1. Navegue até lopaka.app e crie um novo projeto.
2. Selecione ESPHome na lista de plataformas.
3. Defina o Tamanho da tela para corresponder à resolução do seu display.
4. Defina a cor de fundo (o padrão é preto #000000).

Etapa 1: Projete e exporte do Lopaka

1. Desenhe sua interface usando a barra de ferramentas. Nomeie cada camada com clareza — os nomes das camadas viram comentários de código e nomes de variáveis na saída. Use o ícone de olho na lista de camadas para ocultar camadas que você não quer exportar.
2. No painel Configurações de código, configure suas opções de exportação:
   • Incluir fontes — obrigatório se você usar texto ou fontes personalizadas.
   • Declarar imagens — ative se o seu design contiver ícones ou gráficos pintados.
   • Declarar variáveis — ative se a sua interface depender de dados dinâmicos.
3. Desmarque Função wrapper se você estiver colando diretamente em um bloco lambda: existente do ESPHome, para que o Lopaka emita apenas as chamadas de desenho it.*.
4. Clique em Copiar para salvar o código gerado na sua área de transferência.

Características da plataforma

Antes de desenhar, observe as restrições que se aplicam a todos os projetos ESPHome no Lopaka:

• Modelo de cor: RGB completo. As cores são codificadas como Color(R, G, B) na lambda gerada; o branco é o padrão do ESPHome (COLOR_ON), então o Lopaka omite o argumento de cor para camadas brancas.
• Imagens: somente XBMP (monocromático de 1 bit) — não há exportação de bitmap RGB para ESPHome. Ícones e camadas pintadas são sempre exportados como bitmaps binários.
• Sem retângulos arredondados: a API de display do ESPHome não tem uma primitiva de retângulo arredondado.

Ferramentas de desenho disponíveis

Todas as ferramentas padrão do Lopaka estão disponíveis para projetos ESPHome:

Ferramenta	Método ESPHome
Linha	it.line(x1, y1, x2, y2, color)
Retângulo (contorno)	it.rectangle(x, y, w, h, color)
Retângulo (preenchido)	it.filled_rectangle(x, y, w, h, color)
Círculo (contorno)	it.circle(x, y, r, color)
Círculo (preenchido)	it.filled_circle(x, y, r, color)
Triângulo (contorno)	it.triangle(x1,y1, x2,y2, x3,y3, color)
Triângulo (preenchido)	it.filled_triangle(x1,y1, x2,y2, x3,y3, color)
Polígono	Série de chamadas it.line()
Texto	it.print(x, y, id(font), color, "text")
Ícone / Imagem	it.image(x, y, id(image), color)

Etapa 2: Adicione o código ao ESPHome

1. Abra o arquivo de configuração YAML do ESPHome do seu dispositivo.
2. Localize o componente display e seu bloco lambda ou use um do Lopaka se ele não existir.
3. Cole o código de renderização da interface dentro da seção lambda. Certifique-se de que o recuo (tabulações ou espaços) corresponda aos requisitos rígidos de YAML do ESPHome.

Quando a configuração Função wrapper está ativada, a saída completa fica assim:

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);

Cole isso no nível raiz do seu YAML. Se você já tiver uma seção font: ou display:, mescle as novas entradas em vez de duplicar a chave.

Etapa 3: Corrija erros de fontes e declarações

Um erro comum ao colar código do Lopaka diretamente no ESPHome é ter declarações de fontes ausentes ou posicionadas incorretamente.

Mova as fontes para fora da lambda

O código exportado do Lopaka inclui uma seção font:. Ela precisa ser colocada no nível raiz do seu YAML — não dentro da lambda de display.

Atenção

font: e image: são chaves YAML de nível superior. Colocá-las dentro da string lambda: causará um erro de compilação.

Remova duplicatas

Se a sua configuração ESPHome já tiver um bloco font:, não adicione um segundo. Mescle as entradas de fontes do Lopaka nas suas declarações existentes.

Tipos de fontes

Google Fonts são a opção mais fácil — buscadas automaticamente em tempo de compilação via gfonts://:

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

Imagens

Camadas de ícones e pintadas são convertidas para XBMP e exportadas como imagens BINARY. Configurações de código → Imagens lista cada imagem como <Name>.png, nomeada a partir de sua camada; o YAML a referencia como images/<Name>.png. Baixe o PNG e coloque-o em uma subpasta images/:

# Talvez você precise baixar as imagens e colocá-las na pasta do esphome
image:
    - file: 'images/my_icon.png'
      id: img_my_icon
      resize: 32x32
      type: BINARY

Variáveis

Ative Declarar variáveis para tornar as propriedades das camadas dinâmicas em tempo de execução. Qualquer propriedade de camada (posição, tamanho, texto, cor) marcada como variável é extraída para uma declaração tipada no topo da 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);

Os nomes das variáveis vêm do título da camada — renomeie as camadas na lista de camadas para obter nomes limpos na saída.

Ler valores do ESPHome e do Home Assistant

Desative Declarar variáveis para desenhar texto que vem de um componente ESPHome, como um sensor ou text_sensor do Home Assistant. Marque o texto da camada de texto como uma variável e nomeie a camada com o id do componente:

• Texto simples lê um valor de texto: it.print(30, 20, id(Montserrat_26), id(day_of_week).state.c_str());
• Texto com um formato printf, como %.1f °C, imprime um valor numérico: it.printf(75, 298, id(Montserrat_30), "%.1f °C", id(temp_in).state);

Os valores dos sensores são números de ponto flutuante, então use %.0f, %.1f e assim por diante, e escreva %% para um sinal de porcentagem literal. A tela de desenho mostra o texto do formato como digitado. Declare o bloco sensor: ou text_sensor: correspondente com o mesmo id no seu YAML.

Etapa 4: Instale e grave

Quando as fontes estiverem devidamente separadas da lambda e não restarem erros de validação:

1. Clique em Install no painel do ESPHome.
2. Escolha seu método de instalação — Sem fio (OTA) ou Via USB.
3. Aguarde o firmware compilar e ser enviado. Quando o envio for bem-sucedido, seu dispositivo reinicia e exibe a interface que você criou no Lopaka.

Referência de configurações de código

Configuração	Padrão	Efeito
Função wrapper	Ativada	Envolve a saída em um bloco display: lambda:
Comentários	Ativada	Adiciona um comentário // nome da camada antes de cada chamada de desenho
Incluir fontes	Ativada	Emite o bloco font: para todas as fontes usadas
Declarar imagens	Ativada	Emite o bloco image: para todas as camadas de bitmap
Declarar variáveis	Ativada	Extrai propriedades variáveis das camadas para declarações tipadas no topo da lambda

Solução de problemas

Fonte não declarada O bloco font: está ausente ou colocado dentro da lambda. Mova-o para o nível raiz do seu YAML.

Chave duplicada font Você já tem um bloco font:. Mescle as entradas de fontes do Lopaka nele em vez de adicionar um segundo bloco.

Arquivo de imagem não encontrado Crie uma subpasta images/ ao lado do seu YAML do ESPHome e coloque os arquivos PNG lá.