Guia TFT_eSPI para displays coloridos ESP32

Este guia leva um projeto TFT colorido de uma tela vazia do Lopaka a um display ESP32 funcional, passo a passo.

A divisão de trabalho importa aqui mais do que em qualquer outra plataforma: o Lopaka desenha a imagem, você configura a biblioteca. A TFT_eSPI é configurada em tempo de compilação por um arquivo de configurações, e o Lopaka nunca toca nesse arquivo. Faça a biblioteca conversar com seu painel primeiro e então deixe o Lopaka gerar o código de desenho.

O que é a TFT_eSPI?

A TFT_eSPI é uma biblioteca rápida de displays SPI para ESP32, ESP8266, RP2040 e STM32. Ela oferece suporte aos controladores encontrados na maioria dos módulos coloridos baratos — ILI9341, ST7735, ST7789, GC9A01, ILI9488 e muitos outros — e oferece uma única API de desenho para todos eles.

A plataforma TFT_eSPI, M5, Lovyan do Lopaka também abrange duas bibliotecas compatíveis com a API:

Biblioteca	Hardware típico	Objeto de display no seu sketch
TFT_eSPI	ESP32/ESP8266/RP2040 genérico + painel	`TFT_eSPI tft = TFT_eSPI();`
M5GFX (M5Unified)	M5Stack Core, StickC, Dial, Cardputer	`M5.Display`
LovyanGFX	Qualquer um dos acima, ESP32-S3 paralelo	Sua própria subclasse `LGFX`

As três expõem as mesmas chamadas de desenho (fillRect, drawString, pushImage, …), então o mesmo código gerado funciona nas três quando o objeto de display se chama tft.

O que a TFT_eSPI não é

Não é um kit de interface. Não há botões, nenhum mecanismo de layout e nenhum redesenho automático. Você desenha pixels quando decide desenhá-los. Se você quer widgets e tratamento de eventos, consulte a LVGL.

Antes de começar

Você precisa de:

Uma placa ESP32 (ou ESP8266 / RP2040 / STM32) e um módulo TFT colorido.
O nome do controlador impresso no anúncio ou na folha de dados do seu módulo — por exemplo, ILI9341, ST7789, GC9A01.
A resolução (240×320, 240×240, 128×160, …) e os pinos aos quais você conectou o display.
Arduino IDE ou PlatformIO, capaz de compilar e enviar para sua placa.

Atenção

O Lopaka não detecta seu controlador, não gera a fiação nem escreve a configuração da TFT_eSPI. Dois módulos com resolução idêntica podem precisar de drivers, atribuições de pinos, ordem de cores e deslocamentos completamente diferentes. Essa parte é sempre sua.

Etapa 0: Instale e configure a TFT_eSPI

Esta é a etapa que os iniciantes pulam e depois passam uma noite diante de uma tela branca. Faça-a primeiro e não abra o Lopaka até que um exemplo padrão desenhe no seu painel.

Instale a biblioteca

Arduino IDE: abra Tools → Manage Libraries, busque TFT_eSPI de Bodmer e instale.

PlatformIO: adicione ao platformio.ini:

ini

lib_deps = bodmer/TFT_eSPI

Conte a ela sobre o seu display

A TFT_eSPI lê sua configuração de User_Setup.h em tempo de compilação, não do construtor. Há duas maneiras de defini-la, e você escolhe apenas uma:

Edite User_Setup.h na pasta da biblioteca (Arduino/libraries/TFT_eSPI/User_Setup.h). Descomente o #define do seu driver e então defina os pinos e a resolução.
Use um arquivo de configuração incluído. Abra User_Setup_Select.h, comente a linha #include <User_Setup.h> e descomente um dos arquivos User_Setups/Setup*.h que corresponde à sua placa. Esse é o caminho mais fácil para placas conhecidas, como o ESP32 TTGO T-Display.

Um User_Setup.h mínimo para um painel ILI9341 em um ESP32 fica mais ou menos assim:

cpp

#define ILI9341_DRIVER          // one driver, uncommented

#define TFT_WIDTH  240
#define TFT_HEIGHT 320

#define TFT_MISO 19
#define TFT_MOSI 23
#define TFT_SCLK 18
#define TFT_CS   15
#define TFT_DC    2
#define TFT_RST   4

#define LOAD_GLCD               // built-in Adafruit 5x7 font
#define LOAD_GFXFF              // Free Fonts — required for Lopaka font layers

#define SPI_FREQUENCY 40000000

Mantenha LOAD_GLCD e LOAD_GFXFF ativados

LOAD_GLCD fornece a fonte integrada 5×7. LOAD_GFXFF ativa setFreeFont(), que cada camada de texto do Lopaka que não é o padrão usa. Se LOAD_GFXFF estiver comentado, seu texto desaparece silenciosamente ou falha ao compilar.

Usuários do PlatformIO podem passar os mesmos defines como flags de compilação em vez de editar os arquivos da biblioteca, o que sobrevive às atualizações da biblioteca:

ini

build_flags =
    -DUSER_SETUP_LOADED=1
    -DILI9341_DRIVER=1
    -DTFT_WIDTH=240
    -DTFT_HEIGHT=320
    -DTFT_MOSI=23
    -DTFT_SCLK=18
    -DTFT_CS=15
    -DTFT_DC=2
    -DTFT_RST=4
    -DLOAD_GLCD=1
    -DLOAD_GFXFF=1
    -DSPI_FREQUENCY=40000000

Prove que funciona

Abra File → Examples → TFT_eSPI → Test and Diagnostics → Colour_Test (ou Generic → Free_Font_Demo) e envie. Você deve ver cores e texto. Se não vir, corrija isso antes de continuar — cada problema posterior neste guia fica insolúvel enquanto a configuração da biblioteca estiver errada.

Mantenha esse exemplo funcional como seu sketch base. A partir daqui, você só substitui suas chamadas de desenho pela saída do Lopaka.

Etapa 1: Crie o projeto no Lopaka

Abra lopaka.app e crie um projeto.
Selecione a plataforma TFT_eSPI, M5, Lovyan.
Defina o Tamanho da tela com a resolução que seu sketch realmente usa.
Escolha a cor de fundo da tela — ela vira o argumento de fillScreen() no código gerado.

As coordenadas começam em (0, 0) no canto superior esquerdo, X cresce para a direita, Y cresce para baixo. O Lopaka usa o mesmo sistema, então uma camada em (10, 20) no editor fica em (10, 20) no painel.

Rotação

Se o seu sketch chamar tft.setRotation(1) em um painel 240×320, a tela lógica vira 320×240 — então a tela de desenho do Lopaka deve ser 320×240. O Lopaka nunca emite setRotation(); faça a tela de desenho corresponder à orientação que você escolheu no código.

Etapa 2: Projete uma tela

Posicione camadas com a barra de ferramentas, reordene-as no painel Camadas e edite os valores no Inspetor. As camadas são desenhadas na ordem da lista, então uma camada posterior pinta sobre uma anterior — exatamente como as chamadas geradas serão executadas.

Renomeie as camadas antes de exportar. Os nomes viram comentários de código, nomes de arrays de bitmap, nomes de funções auxiliares de polígono, cabeçalhos de animação e nomes de variáveis.

O que cada camada gera

Camada do Lopaka	Chamada TFT_eSPI gerada
Ponto	`tft.drawPixel(x, y, color)`
Linha	`tft.drawLine(x1, y1, x2, y2, color)`
Retângulo	`tft.drawRect(...)` / `tft.fillRect(...)`
Retângulo arredondado	`tft.drawRoundRect(...)` / `tft.fillRoundRect(...)`
Elipse	`tft.drawEllipse(x, y, rx, ry, color)` / `tft.fillEllipse(...)`
Triângulo	`tft.drawTriangle(...)` / `tft.fillTriangle(...)`
Arco	`tft.drawSmoothArc(...)` ou `tft.drawArc(...)`
Polígono	Um auxiliar gerado `void drawMyShape(void)` feito de chamadas `drawLine()`
Texto	`setTextColor()`, `setTextSize()`, `setFreeFont()`, `drawString()`
Pintura / ícone / imagem	`tft.drawBitmap(...)` (1 bit) ou `tft.pushImage(...)` (RGB565)
Animação	Arrays de quadros mais auxiliares `updateAnimations()` / `drawAnimations()`

Não há uma ferramenta Círculo nesta plataforma — use a ferramenta Elipse com raios iguais; as primitivas de elipse da TFT_eSPI cobrem isso.

Cores

O Lopaka permite escolher qualquer cor RGB e então a empacota no valor RGB565 de 16 bits que a TFT_eSPI espera, então #FF0000 vira 0xF800. Isso são 5 bits de vermelho, 6 de verde, 5 de azul — 65.536 cores, não 16 milhões. Gradientes sutis formarão faixas. Os pixels transparentes em uma imagem de origem RGB são compostos contra o fundo da tela por padrão; marque Transparência no inspetor para mantê-los translúcidos com uma máscara de um bit (consulte Imagens abaixo).

Texto

Camadas de texto produzem drawString(text, x, y), em que x, y é o canto superior esquerdo do texto — o TL_DATUM padrão da TFT_eSPI. O Lopaka ajusta a coordenada Y para as métricas da fonte selecionada, então você não faz a matemática da linha de base à mão.

Três propriedades correspondem ao estado da biblioteca, e o Lopaka emite cada chamada apenas quando ela muda entre camadas:

Cor → setTextColor(fg), ou setTextColor(fg, bg) quando você define uma cor de fundo do texto. Um fundo faz o texto redesenhado sobrescrever seus pixels antigos em vez de deixar rastros.
Tamanho → setTextSize(n), um multiplicador inteiro de pixels. 2 dobra cada pixel, então ele parece robusto, e não suave.
Fonte → setFreeFont(&FreeSans9pt7b) para uma fonte GFX, ou setFreeFont(NULL) para a face integrada 5×7.

Atenção

Se o seu próprio código alterar o datum do texto (tft.setTextDatum(MC_DATUM)), o texto gerado cai no lugar errado. Redefina-o com tft.setTextDatum(TL_DATUM) antes de chamar a função do Lopaka.

Arcos

A ferramenta Arco é exclusiva desta plataforma. Os ângulos são graus medidos no sentido horário a partir das 12 horas, então um medidor de 30 a 330 se abre na parte inferior. O alternador de suavidade do Inspetor escolhe entre as duas chamadas da biblioteca:

cpp

// Smooth: antialiased edges, rounded ends
tft.drawSmoothArc(120, 120, 100, 92, 30, 330, 0x07E0, 0x0000, true);
// Not smooth: hard pixel edges
tft.drawArc(120, 120, 100, 92, 30, 330, 0x07E0, 0x0000, false);

As duas recebem uma cor de fundo, porque os pixels com antisserrilhamento são misturados contra ela. Defina o fundo do arco com aquilo sobre o que ele realmente fica, ou suas bordas ficarão com halo. drawSmoothArc() exige a TFT_eSPI 2.4.x ou mais recente — atualize a biblioteca se o compilador disser que ela não está definida.

Etapa 3: Configure o código gerado

Abra Configurações de código abaixo do painel de código. Esta plataforma tem dois modelos C++ e estes alternadores:

A Sintaxe escolhe o framework de destino. Arduino (C++) é o padrão. ESP-IDF (C++) emite as mesmas chamadas de desenho para um componente ESP-IDF: os arrays de imagens, máscaras e animações são arrays simples static const uint8_t / uint16_t sem PROGMEM, o tempo das animações usa esp_timer_get_time() de esp_timer.h, e nenhum setup() / loop() é gerado — chame draw{ScreenName}() e drawAnimations() a partir do loop da sua própria tarefa. Os cabeçalhos de imagens e animações baixados seguem o modelo selecionado.

Configuração	O que ela faz
Função wrapper	Envolve a tela em `void draw{ScreenName}(void)`
Incluir fontes	Emite `#include "FontName.h"` para fontes personalizadas (consulte Fontes)
Declarar imagens	Emite os arrays de bitmap que as camadas de imagem referenciam
Auxiliares de animação	Emite includes de cabeçalhos de animação mais auxiliares de tempo e desenho
Declarar variáveis	Emite declarações para propriedades de camadas que você marcou como variáveis
Comentários, títulos das camadas	Adiciona um comentário `// Nome da camada` acima das chamadas de cada camada
Limpar/preencher o display	Inicia o bloco com `tft.fillScreen(backgroundColor)`

Para sua primeira exportação, deixe tudo ativado. O botão Copiar copia exatamente o que o painel mostra.

O objeto precisa se chamar tft

Cada linha gerada começa com tft.. A correção mais simples é nomear seu objeto de display como tft no sketch. No M5Stack, adicione uma linha de apelido: M5GFX& tft = M5.Display;

Etapa 4: Fontes, imagens e animações

Fontes

A fonte integrada 5×7 da Adafruit e as Free Fonts (FreeSans, FreeMono, FreeSerif em 9/12/18/24pt, com variantes em negrito e oblíquo) não precisam de arquivo de cabeçalho. A TFT_eSPI já compila as Free Fonts quando LOAD_GFXFF está definido (consulte Conte a ela sobre o seu display), então o Lopaka não emite um #include para elas e não as lista em Configurações de código → Fontes.

Todas as outras fontes precisam de um cabeçalho: as fontes menores da Adafruit (Org_01, Picopixel, Tiny3x3a2pt7b, Petme8x8) e qualquer coisa que você enviar. Para cada uma dessas fontes na tela:

Abra Configurações de código e encontre a seção Fontes.
Clique no botão de download ao lado da fonte para obter seu arquivo .h.
Coloque esse arquivo na mesma pasta que seu .ino ou .cpp.
Mantenha Incluir fontes ativado para que a linha #include "Picopixel.h" permaneça na saída.

O Lopaka pode converter fontes TrueType enviadas (.ttf, .otf, .woff) e fontes BDF para o formato GFX. Consulte o guia de fontes para os caminhos de importação.

Os dados das fontes ficam na flash. Uma fonte de 24pt com um conjunto completo de caracteres custa dezenas de kilobytes, então use faces grandes com moderação.

Imagens

Use a ferramenta Imagem para importar e recortar a arte em seu tamanho final em pixels. O que é gerado depende do modo de cor da camada:

Monocromático → um array PROGMEM de 1 bit desenhado com tft.drawBitmap(x, y, bits, w, h, color). Uma cor, pixels não definidos transparentes, 1 bit por pixel. Melhor para ícones.
RGB → um array RGB565 uint16_t PROGMEM desenhado com tft.pushImage(x, y, w, h, pixels). Cor completa, 2 bytes por pixel. Uma imagem importada preenche seus pixels transparentes com o fundo da tela. Marque Transparência ao lado de Sobreposição no inspetor (ela aparece quando a imagem tem pixels transparentes) e o Lopaka também emite um array image_<Name>_mask de um bit e desenha com tft.pushMaskedImage(...), para que esses pixels mantenham o que a tela já exibe.

Configurações de código → Imagens lista cada imagem como image_<Name>_bits.h ou image_<Name>_pixels.h, carregando exatamente os bytes que o array em linha carrega. Ative Incluir arquivos de imagem para emitir #include "<symbol>.h" em vez do array e manter os pixels no cabeçalho baixado.

Cuidado com o orçamento de flash

Uma imagem RGB de tela inteira de 240×320 tem 153.600 bytes — cerca de 12% de uma partição de sketch padrão do ESP32, para uma imagem. Recorte bem, reduza e use monocromático para qualquer coisa que seja de uma única cor.

Se as cores das imagens saírem erradas enquanto as formas parecerem corretas, consulte a ordem dos bytes em Solução de problemas.

O guia de importação de imagens abrange redimensionamento, recorte, pontilhamento e estimativas de tamanho.

Animações

As camadas de animação exportam como quadros de 1 bit — um flipbook de duas cores, não vídeo. Cada quadro é desenhado com setBitmapColor(foreground, background) seguido de pushImage().

Ativar os Auxiliares de animação altera significativamente a forma da saída:

cpp

#include "spinner.h"

void updateAnimations() {
    animation_spinner_frame = millis() / 100 % 12;
}

void drawAnimation_spinner(void) {
    tft.setBitmapColor(0xFFFF, 0x0);
    tft.pushImage(80, 60, 32, 32, animation_spinner_frames[animation_spinner_frame], false, nullptr);
}

void drawAnimations() {
    updateAnimations();
    drawAnimation_spinner();
}

void drawMain(void) { /* static layers */ }

void loop(){
    drawAnimations();
};

void setup() {
    tft.begin();
    drawMain();
}

Mescle, não cole

Esse setup() e loop() gerados são um esqueleto inicial. Seu sketch já tem os dois. Mantenha um setup() e um loop(): pegue os includes, os arrays de quadros, updateAnimations() e os auxiliares de desenho, e então chame drawAnimations() a partir do seu loop existente.

Baixe cada arquivo .h listado em Configurações de código → Animações e mantenha-o ao lado do sketch. Consulte Animações para o fluxo do editor.

Etapa 5: Copie e integre

Nomeie sua tela como Main, adicione uma camada de texto e um retângulo, e clique em Copiar. Você obtém algo assim:

cpp

void drawMain(void) {
    tft.fillScreen(0x0);
    // Title
    tft.setTextColor(0xFFFF);
    tft.setTextSize(1);
    tft.setFreeFont(&FreeSans9pt7b);
    tft.drawString("Hello!", 8, 12);
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}

Colocado em um sketch completo:

cpp

#include <SPI.h>
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

// ---- BEGIN LOPAKA GENERATED CODE ----
void drawMain(void) {
    tft.fillScreen(0x0);
    // Title
    tft.setTextColor(0xFFFF);
    tft.setTextSize(1);
    tft.setFreeFont(&FreeSans9pt7b);
    tft.drawString("Hello!", 8, 12);
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}
// ---- END LOPAKA GENERATED CODE ----

void setup() {
    tft.init();
    tft.setRotation(0);
    drawMain();
}

void loop() {}

A TFT_eSPI escreve direto no painel, então não há um buffer para descarregar — nada como a chamada display.display() de que as bibliotecas monocromáticas precisam.

M5Stack

A M5GFX é a mesma API por trás de um objeto diferente. Uma linha de apelido é tudo de que você precisa:

cpp

#include <M5Unified.h>

M5GFX& tft = M5.Display;   // now every generated tft.* call works

// Paste the Lopaka block here.

void setup() {
    auto cfg = M5.config();
    M5.begin(cfg);
    drawMain();
}

void loop() { M5.update(); }

A M5Unified configura o painel para a placa M5 específica automaticamente, então você pula o User_Setup.h por completo. Siga o exemplo oficial da sua placa para M5.begin().

LovyanGFX

A LovyanGFX precisa de uma classe LGFX que descreva seu painel (seu repositório tem configurações prontas para placas comuns). Nomeie a instância como tft e o código gerado entra inalterado.

Etapa 6: Dados em tempo de execução e mais telas

Tornar os valores dinâmicos

Texto estático serve para uma maquete, não para um termômetro. Selecione uma camada, ative o alternador de variável para uma propriedade compatível no Inspetor e mantenha Declarar variáveis ativado. O Lopaka substitui o literal por uma declaração nomeada a partir da camada:

cpp

const char* temperature = "21.5 C";

void drawMain(void) {
    // ...
    tft.drawString(temperature, 8, 40);
}

Atualize a variável no seu código, chame drawMain() de novo e o novo valor aparece.

Evite a cintilação da tela inteira

Chamar drawMain() em um loop apertado repinta tudo e cintila. Para um valor que muda com frequência, dê à sua camada de texto uma cor de fundo e redesenhe apenas a chamada dessa camada — ou desenhe em um TFT_eSprite e envie o sprite. Sprites são um recurso da TFT_eSPI que você adiciona por conta própria; o Lopaka não os gera.

Várias telas

Cada tela do Lopaka exporta independentemente, e seu título vira o nome da função. Copie cada uma, mescle includes e arrays de bitmap duplicados, e então deixe seu código escolher:

cpp

enum Screen { MAIN, SETTINGS };
Screen currentScreen = MAIN;

void drawCurrentScreen(void) {
    if (currentScreen == MAIN) {
        drawMain();
    } else {
        drawSettings();
    }
}

Importar código existente

O painel de código tem um botão Importar código que lê um arquivo .ino, .c, .cpp ou .txt e transforma chamadas tft.* reconhecidas em camadas editáveis. Ele é experimental e funciona melhor em código que o próprio Lopaka gerou — sketches escritos à mão com loops, variáveis e funções auxiliares não farão a viagem de ida e volta por completo. As camadas importadas são anexadas à tela atual.

O que o Lopaka faz e o que você faz

O Lopaka faz	Você faz
Layout em pixels, ordem das camadas e as chamadas de desenho	`User_Setup.h`, seleção do driver, pinos e frequência SPI
Empacotamento RGB → RGB565 para formas, texto e imagens	Ordem de cores do painel, inversão e deslocamentos
Arrays de bitmap, cabeçalhos de fontes GFX, quadros de animação	Orçamento de flash e manter os arquivos `.h` baixados com o sketch
Matemática da linha de base do texto e chamadas de estado da fonte	Datum do texto, se o seu código o alterar
Uma função de desenho nomeada por tela	Chamá-la, tempo de redesenho, entradas e navegação
Declarações opcionais de variáveis	Atualizar essas variáveis com dados reais

Compile, envie e itere

Compile antes de enviar e corrija primeiro cabeçalhos ausentes ou símbolos indefinidos.
Envie e compare o painel com a tela de desenho do Lopaka.
Ajuste o tamanho da tela de desenho, a rotação ou as posições das camadas e exporte de novo.
Quando o design mudar, substitua o bloco gerado inteiro. Não edite chamadas de desenho individuais à mão — a próxima exportação as sobrescreverá.

Marcar o bloco torna isso indolor:

cpp

// ---- BEGIN LOPAKA GENERATED CODE ----
// Replace this entire block after exporting again.
// ---- END LOPAKA GENERATED CODE ----

Solução de problemas

A tela está branca, preta ou em branco

Quase sempre é a configuração da biblioteca, não o código gerado.

Execute de novo um exemplo padrão da TFT_eSPI. Se ele também estiver em branco, o problema é User_Setup.h, a fiação ou a energia.
Confirme que o #define do driver correto está descomentado, e apenas um.
Verifique o pino da luz de fundo — muitos módulos precisam que TFT_BL seja levado a alto.
Confirme que tft.init() é executado antes da sua função de desenho.
Reduza SPI_FREQUENCY para 27000000; fios jumper longos não sobrevivem a 40 MHz.

`'tft' was not declared in this scope`

O código gerado chama tft.*. Nomeie seu objeto de display como tft, ou adicione um apelido como M5GFX& tft = M5.Display;.

`setFreeFont` ou `drawSmoothArc` não está definida

setFreeFont() precisa de #define LOAD_GFXFF em User_Setup.h. drawSmoothArc() precisa da TFT_eSPI 2.4.x ou mais recente — atualize pelo Gerenciador de bibliotecas.

Um cabeçalho de fonte não compila

Para uma Free Font (FreeSans9pt7b e amigas), não há um cabeçalho para adicionar: verifique se LOAD_GFXFF está definido em User_Setup.h e se o sketch não tem um #include "FreeSans9pt7b.h" restante de uma exportação mais antiga. Para qualquer outra fonte, baixe o .h em Configurações de código → Fontes, coloque-o ao lado do sketch e mantenha Incluir fontes ativado para que o nome do arquivo, o include e o símbolo &FontName concordem.

As cores estão erradas em toda parte

Vermelho e azul trocados na tela inteira é um problema de ordem de cores do painel: experimente TFT_RGB_ORDER TFT_BGR (ou TFT_RGB) em User_Setup.h. Uma imagem com aparência invertida é #define TFT_INVERSION_ON / TFT_INVERSION_OFF. Corrija no arquivo de configuração — nunca alterando cada cor do seu design.

As cores das imagens estão erradas, mas as formas estão bem

O Lopaka grava os dados de imagem RGB565 com os bytes trocados, a mesma convenção que a maioria dos conversores de imagem da TFT_eSPI usa. Diga à biblioteca para trocá-los de volta antes de enviar as imagens:

cpp

tft.setSwapBytes(true);

Chame uma vez em setup(), depois de tft.init(). Se as imagens já estavam corretas e isso as quebra, defina como false.

O texto está no lugar errado

Redefina o datum com tft.setTextDatum(TL_DATUM) antes da função gerada — o Lopaka presume o datum padrão do canto superior esquerdo. Se tudo estiver deslocado ou cortado, o tamanho da tela de desenho não corresponde ao display depois de setRotation().

O texto deixa manchas quando se atualiza

drawString() pinta apenas os pixels dos glifos; os antigos permanecem. Dê à camada de texto uma cor de fundo no Lopaka para que ela emita setTextColor(fg, bg), ou limpe a área com fillRect() primeiro.

O design está girado, espelhado ou deslocado por alguns pixels

Faça a tela de desenho do Lopaka corresponder ao tamanho lógico depois de setRotation(). Um deslocamento constante de alguns pixels geralmente significa a variante errada do driver — alguns painéis têm RAM do controlador maior que a área visível e precisam de um define de deslocamento específico do driver.

O sketch não cabe na flash

Imagens RGB565 são a culpada de costume, com 2 bytes por pixel. Recorte mais, reduza, converta arte de uma única cor para monocromático e descarte fontes grandes não utilizadas.

O código de animação entra em conflito com meu sketch

Mantenha um setup() e um loop(). Pegue os includes, os arrays de quadros e as funções auxiliares da saída gerada; mantenha sua própria inicialização; chame drawAnimations() a partir do seu loop existente.

Perguntas frequentes

O Lopaka configura a TFT_eSPI para mim?

Não. User_Setup.h, a seleção do driver, os pinos e a frequência SPI são inteiramente seus. O Lopaka gera chamadas de desenho e recursos que presumem um objeto de display funcional e inicializado chamado tft.

Meu display funciona com o Lopaka?

Se a TFT_eSPI, a M5GFX ou a LovyanGFX o controla, sim — o Lopaka mira a API compartilhada, não uma lista de módulos. Verifique o módulo primeiro com um exemplo padrão da biblioteca.

Posso exportar imagens em cores completas?

Sim — camadas de imagem RGB viram arrays RGB565 desenhados com pushImage(). Os quadros de animação são sempre de 1 bit, quaisquer que sejam as cores que usem no editor.

O Lopaka gera sprites, DMA ou redesenhos parciais?

Não. Ele emite chamadas de desenho diretas. TFT_eSprite, transferências DMA e redesenho por retângulos sujos são otimizações que você adiciona ao redor da função gerada.

Guia TFT_eSPI para displays coloridos ESP32 ​

O que é a TFT_eSPI? ​

Antes de começar ​

Etapa 0: Instale e configure a TFT_eSPI ​

Instale a biblioteca ​

Conte a ela sobre o seu display ​

Prove que funciona ​

Etapa 1: Crie o projeto no Lopaka ​

Etapa 2: Projete uma tela ​

O que cada camada gera ​

Cores ​

Texto ​

Arcos ​

Etapa 3: Configure o código gerado ​

Etapa 4: Fontes, imagens e animações ​

Fontes ​

Imagens ​

Animações ​

Etapa 5: Copie e integre ​

M5Stack ​

LovyanGFX ​

Etapa 6: Dados em tempo de execução e mais telas ​

Tornar os valores dinâmicos ​

Várias telas ​

Importar código existente ​

O que o Lopaka faz e o que você faz ​

Compile, envie e itere ​

Solução de problemas ​

A tela está branca, preta ou em branco ​

'tft' was not declared in this scope ​

setFreeFont ou drawSmoothArc não está definida ​

Um cabeçalho de fonte não compila ​

As cores estão erradas em toda parte ​

As cores das imagens estão erradas, mas as formas estão bem ​

O texto está no lugar errado ​

O texto deixa manchas quando se atualiza ​

O design está girado, espelhado ou deslocado por alguns pixels ​

O sketch não cabe na flash ​

O código de animação entra em conflito com meu sketch ​

Perguntas frequentes ​

O Lopaka configura a TFT_eSPI para mim? ​

Meu display funciona com o Lopaka? ​

Posso exportar imagens em cores completas? ​

O Lopaka gera sprites, DMA ou redesenhos parciais? ​

Onde posso aprender mais? ​