Lopaka

Português

English
Español
Deutsch
Polski

Português

English
Español
Deutsch
Polski

Aparência

Guia Adafruit GFX para ESP32 e Arduino ​

Este tutorial de Adafruit GFX leva um projeto de display ESP32 ou Arduino de uma tela vazia do Lopaka a um hardware funcional. O Lopaka cria o código de desenho e os recursos de bitmap; você escolhe, conecta e inicializa a biblioteca de display específica do hardware.

O que é a biblioteca Adafruit GFX? ​

A Adafruit GFX é a camada gráfica comum usada por muitas bibliotecas de display para placas compatíveis com Arduino, incluindo ESP32. Ela oferece métodos de desenho para pixels, linhas, formas, texto e bitmaps.

A Adafruit GFX não controla um display sozinha. Ela trabalha com uma biblioteca específica do hardware, como Adafruit_SSD1306, Adafruit_ST7789 ou outro driver para o controlador exato do seu módulo. O driver cuida do barramento, da inicialização e da transferência para o display; a GFX fornece a API de desenho compartilhada. Consulte a visão geral da biblioteca da Adafruit para exemplos dessa divisão.

Antes de começar ​

Você precisa de:

  • Um microcontrolador e um display com um driver compatível com Adafruit GFX.
  • O nome do controlador, a resolução, a interface e a pinagem do seu módulo.
  • Um projeto Arduino ou ESP32 usando o framework Arduino que consiga compilar e enviar o sketch de exemplo do driver.
  • Flash suficiente para fontes e recursos de bitmap, e RAM suficiente para qualquer framebuffer usado pelo driver.

Atenção

O Lopaka não detecta seu controlador nem gera a fiação e a configuração do driver. Displays com a mesma resolução podem exigir bibliotecas, construtores, endereços, pinos, chamadas de inicialização ou deslocamentos de display diferentes.

Etapa 0: Instale e teste o driver do display ​

No Arduino IDE, abra Tools → Manage Libraries e busque o driver usado pelo seu display, como Adafruit SSD1306 ou Adafruit ST7735 and ST7789 Library. As versões atuais do Arduino IDE instalam as dependências declaradas, como Adafruit GFX e Adafruit BusIO, junto com o driver. Se você instalar as bibliotecas manualmente, siga as instruções do repositório Adafruit GFX e o repositório do seu driver de display.

Para camadas de elipse, instale a Adafruit GFX 1.12.2 ou posterior. A API 1.12.2 inclui drawEllipse() e fillEllipse(); a 1.12.1 não.

Para ESP32, instale o núcleo Arduino para ESP32 e selecione sua placa. Os sketches de ESP32 usam a mesma estrutura setup() e loop() mostrada neste guia.

Antes de adicionar código do Lopaka, compile e envie um exemplo oficial para o seu display exato. Por exemplo:

Um exemplo do fornecedor funcional prova que a biblioteca, o construtor, a fiação, o endereço, o barramento e a inicialização estão corretos. Mantenha esse exemplo como o sketch base e substitua apenas suas chamadas de desenho de demonstração pela saída do Lopaka.

Etapa 1: Escolha a plataforma do Lopaka ​

O Lopaka tem dois destinos Adafruit GFX:

Plataforma do LopakaUse paraObjeto geradoSaída de cor e imagem
AdafruitGFX ColorDrivers TFT, OLED ou de matriz coloridostftCores RGB565; imagens de um bit com drawBitmap() ou RGB565 com drawRGBBitmap()
AdafruitGFX MonoDrivers OLED ou LCD de um bitdisplayCores 0 e 1; imagens de um bit com drawBitmap()

Escolha o destino que corresponde ao driver, não apenas à aparência do design. Um destino monocromático não gera pixels RGB nem em escala de cinza. O destino colorido empacota as cores nos valores RGB565 de 16 bits usados pela Adafruit GFX; consulte o modelo de coordenadas e cores da Adafruit.

O nome do objeto gerado faz parte do contrato de integração. A abordagem mais simples é nomear sua instância do driver como tft para a saída colorida ou display para a saída monocromática. Caso contrário, renomeie esse identificador no bloco gerado.

Etapa 2: Crie o projeto no Lopaka ​

  1. Abra lopaka.app e crie um projeto.
  2. Selecione AdafruitGFX Color ou AdafruitGFX Mono.
  3. Defina o Tamanho da tela com a largura e a altura lógicas que seu sketch usará.
  4. Para um projeto colorido, escolha a cor de fundo da tela. Para um projeto monocromático, projete com a paleta fixa em preto e branco.

As coordenadas da Adafruit GFX começam em (0, 0) no canto superior esquerdo, com X aumentando para a direita e Y aumentando para baixo. O Lopaka usa a mesma orientação.

Se o sketch chamar setRotation(), faça a tela de desenho do Lopaka corresponder às dimensões lógicas giradas informadas por width() e height(). O Lopaka não emite setRotation() nem gira o hardware para você. A Adafruit documenta as quatro orientações em Girar o display.

Etapa 3: Projete uma tela ​

Posicione camadas com a barra de ferramentas, organize-as no painel Camadas e edite seus valores no Inspetor. Renomeie as camadas importantes antes de exportar: os nomes viram comentários, identificadores de bitmap, nomes de auxiliares de polígono, cabeçalhos de animação e nomes de variáveis opcionais.

Os geradores Adafruit GFX atuais emitem estes conceitos:

Camada do LopakaSaída Adafruit GFX
LinhadrawLine()
RetângulodrawRect() / fillRect()
Retângulo arredondadodrawRoundRect() / fillRoundRect()
CírculodrawCircle() / fillCircle()
ElipsedrawEllipse() / fillEllipse()
TriângulodrawTriangle() / fillTriangle()
PolígonoUm auxiliar feito de chamadas fechadas de drawLine(); somente contorno
TextosetTextColor(), setTextSize(), setFont(), setCursor(), print()
Pintura, ícone, imagemdrawBitmap() ou, no destino colorido, drawRGBBitmap()
AnimaçãoDados de quadros de um bit mais auxiliares de seleção e desenho de quadros

Use a ferramenta Elipse para formas ovais nos dois destinos Adafruit. Defina seus raios horizontal e vertical iguais para desenhar um círculo; camadas de círculo importadas ainda geram drawCircle() ou fillCircle().

Comportamento do texto ​

A fonte padrão da Adafruit é a face integrada de largura fixa 5×7. Outras fontes GFX usam uma linha de base: a coordenada Y do cursor é a linha em que os glifos se apoiam, não o topo das letras visíveis. O Lopaka ajusta a coordenada Y gerada para a fonte selecionada, mas você ainda deve verificar o alinhamento no display real.

O destino colorido expõe uma cor de fundo do texto e emite a forma de dois argumentos setTextColor(foreground, background). A Adafruit GFX ignora esse argumento de fundo para fontes GFX personalizadas; ele funciona apenas com a fonte integrada clássica. Para sobrescrever um texto de fonte personalizada, limpe seus limites antigos com um retângulo preenchido antes de desenhá-lo de novo. O destino monocromático do Lopaka não expõe fundos de texto. Consulte as notas sobre comportamento de fontes e linha de base da Adafruit.

Etapa 4: Configure o código gerado ​

Abra Configurações de código. Os destinos Adafruit GFX têm dois modelos C++ e estas opções:

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çãoO que ela altera
Função wrapperEnvolve a tela ativa em void draw{ScreenName}(void)
Incluir fontesAdiciona includes de cabeçalhos locais para fontes GFX que não são o padrão
Declarar imagensEmite arrays de bitmap de um bit ou RGB565 usados por camadas de imagem
Incluir arquivos de imagemEmite #include "<symbol>.h" em vez dos arrays de bitmap em linha
Auxiliares de animaçãoAdiciona includes de cabeçalhos de animação, auxiliares de tempo e setup/loop iniciais
Declarar variáveisEmite declarações para propriedades de camadas compatíveis marcadas como variáveis
Comentários, títulos das camadasAdiciona comentários com o nome da camada à saída de desenho estática
Limpar/preencher o displayLimpa a saída mono ou preenche a saída colorida no início do bloco de desenho

Mantenha Função wrapper, Incluir fontes, Declarar imagens e Limpar/preencher o display ativados para a primeira renderização.

O wrapper colorido começa com tft.fillScreen(...). O wrapper monocromático começa com display.clearDisplay() e termina com display.display() para que um display com buffer, como o SSD1306, seja atualizado. Alguns outros drivers monocromáticos usam um método de atualização diferente; adapte a chamada final ao exemplo oficial do seu driver.

Etapa 5: Adicione fontes, imagens e animações ​

Fontes ​

A fonte integrada 5×7 da Adafruit não precisa de cabeçalho. O Lopaka também oferece fontes GFX e aceita cabeçalhos de fontes no formato GFX importados. Ele pode converter importações de fontes BDF e vetoriais compatíveis para o formato GFX; consulte o guia de fontes do Lopaka para os caminhos de importação disponíveis.

Para cada fonte que não seja o padrão usada pela tela:

  1. Abra Configurações de código → Fontes e baixe o arquivo .h.
  2. Coloque o arquivo ao lado do seu sketch ou do código-fonte gerado.
  3. Mantenha Incluir fontes ativado para que o #include "FontName.h" gerado permaneça presente.

Os dados das fontes usam espaço de programa, e fontes maiores usam mais. O guia de fontes da Adafruit explica a família Free incluída e o formato de fonte GFX.

Imagens ​

Use a ferramenta Imagem para importar e recortar uma imagem em seu tamanho final em pixels. A saída depende do destino do Lopaka selecionado e do modo de cor da imagem:

  • Monocromático: um array PROGMEM de um bit desenhado com uma cor de primeiro plano selecionada. Os pixels não definidos são transparentes na chamada drawBitmap() gerada.
  • RGB no AdafruitGFX Color: um array RGB565 uint16_t PROGMEM desenhado com drawRGBBitmap(). Uma imagem importada preenche seus pixels transparentes com o fundo da tela, na tela de desenho e no dispositivo. Para mantê-los translúcidos, marque Transparência ao lado de Sobreposição no inspetor (ela aparece quando a imagem tem pixels transparentes): o Lopaka então também emite um array image_<Name>_mask de um bit e usa a sobrecarga com máscara de drawRGBBitmap(), para que esses pixels mantenham o que a tela já exibe. A máscara custa um bit por pixel de flash, e a chamada com máscara desenha pixel a pixel, o que é mais lento.

Mantenha Declarar imagens ativado para incluir os arrays no código copiado. O RGB565 usa dois bytes por pixel antes da sobrecarga do compilador e do armazenamento, então imagens grandes de tela inteira podem consumir flash substancial. O guia de importação de imagens do Lopaka abrange redimensionamento, recorte, reamostragem, pontilhamento e estimativas de tamanho. A Adafruit documenta as chamadas de bitmap subjacentes em Primitivas gráficas.

Configurações de código → Imagens também lista cada imagem com seu arquivo de recurso — image_<Name>_bits.h para dados de um bit, image_<Name>_pixels.h para RGB565 — carregando exatamente os bytes que o array em linha carrega. Ative Incluir arquivos de imagem para emitir #include "image_<Name>_bits.h" em vez do array e manter os pixels no cabeçalho baixado.

Animações ​

Os dois destinos Adafruit do Lopaka oferecem suporte a animações de quadros. Os quadros exportados são bitmaps de um bit, inclusive no destino colorido; a cor da camada selecionada é aplicada quando cada quadro é desenhado. Isso não é reprodução de vídeo em cores.

Baixe cada arquivo .h listado em Configurações de código → Animações e mantenha-o com o sketch. O auxiliar escolhe um quadro usando millis() na sintaxe Arduino (C++) e esp_timer_get_time() na sintaxe ESP-IDF (C++).

Atenção

Com a sintaxe Arduino (C++), a exportação de animações adiciona os pontos de entrada padrão do Arduino setup() e loop(), que também funcionam no ESP32 com o núcleo Arduino. O código de display dentro do setup() gerado é apenas um ponto de partida: os drivers da Adafruit usam chamadas de inicialização diferentes. Mescle os includes de animação, o auxiliar de atualização e os auxiliares de desenho no exemplo funcional do fornecedor, mantenha o construtor e a inicialização desse driver e mantenha apenas um setup() e um loop().

Consulte Animações para o fluxo do editor e os controles de exportação.

Etapa 6: Copie e integre o código ​

Crie uma tela chamada Main, adicione uma camada de texto e um retângulo de contorno, e então clique em Copiar no painel de código. Sua saída exata usará suas camadas, cores, fontes e coordenadas.

Exemplo colorido com TFT ST7789 ​

Para o AdafruitGFX Color, uma função representativa do Lopaka fica assim:

cpp
void drawMain(void) {
    tft.fillScreen(0x0);
    // Greeting
    tft.setTextColor(0xFFFF);
    tft.setCursor(8, 12);
    tft.print("Hello!");
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}

O sketch mínimo a seguir segue o exemplo oficial da Adafruit para ST7789 240×240. Substitua as definições de pinos e os argumentos de init() pelos do exemplo funcional do seu módulo.

cpp
#include <SPI.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>

#define TFT_CS 10
#define TFT_DC 8
#define TFT_RST 9

Adafruit_ST7789 tft(TFT_CS, TFT_DC, TFT_RST);

// Paste the complete Lopaka-generated block here.
void drawMain(void) {
    tft.fillScreen(0x0);
    // Greeting
    tft.setTextColor(0xFFFF);
    tft.setCursor(8, 12);
    tft.print("Hello!");
    // Border
    tft.drawRect(0, 0, 240, 240, 0xFFFF);
}

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

void loop(void) {}

Drivers TFT coloridos geralmente desenham diretamente no display, então este exemplo não precisa de uma chamada separada de apresentar ou descarregar. Siga o exemplo específico do hardware se o seu driver armazenar a saída em buffer.

Exemplo monocromático com OLED SSD1306 ​

Para o AdafruitGFX Mono, o wrapper inclui as chamadas de limpar e atualizar:

cpp
void drawMain(void) {
    display.clearDisplay();
    // Greeting
    display.setTextColor(1);
    display.setCursor(8, 12);
    display.print("Hello!");
    // Border
    display.drawRect(0, 0, 128, 64, 1);
    display.display();
}

Este sketch mínimo segue o exemplo oficial da Adafruit para SSD1306 128×64 I2C. Substitua o pino de reset e o endereço I2C pelos valores do seu módulo.

cpp
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3D

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Paste the complete Lopaka-generated block here.
void drawMain(void) {
    display.clearDisplay();
    // Greeting
    display.setTextColor(1);
    display.setCursor(8, 12);
    display.print("Hello!");
    // Border
    display.drawRect(0, 0, 128, 64, 1);
    display.display();
}

void setup(void) {
    if (!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
        for (;;) {}
    }
    drawMain();
}

void loop(void) {}

Etapa 7: Adicione dados em tempo de execução e mais telas ​

Para tornar uma propriedade compatível dinâmica, ative seu alternador de variável no Inspetor e mantenha Declarar variáveis ativado. O Lopaka substitui o literal por uma declaração baseada no nome da camada. Atualize esse valor no seu aplicativo antes de chamar a função de desenho de novo.

Cada tela do Lopaka exporta separadamente, e seu título vira o nome da função wrapper. Copie a função de cada tela para o sketch, mescle includes e recursos duplicados, e então deixe seu aplicativo decidir qual função chamar:

cpp
enum Screen { MAIN, DETAILS };
Screen currentScreen = MAIN;

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

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

O Lopaka fazVocê faz
Layout em pixels, ordem das camadas e chamadas GFX compatíveisDriver de display exato, construtor, pinos, barramento e tensão
Cores RGB565 para o destino coloridoOrdem de cores, deslocamentos e inicialização específicos do driver
Declarações de bitmap de um bit e RGB565Orçamento de flash/RAM e qualquer carregamento de sistema de arquivos ou cartão SD
Seleção de fontes GFX e cabeçalhos locais para downloadInstalar bibliotecas e manter os cabeçalhos com o código-fonte
Variáveis opcionais e auxiliares de animação de um bitTempo de atualização, entradas, navegação e estado do aplicativo
Uma função de desenho nomeada para cada tela exportadaChamar essa função e apresentar a saída em buffer corretamente

Compile, envie e itere ​

  1. Compile antes de enviar. Resolva primeiro cabeçalhos ausentes, objetos indefinidos e erros de métodos específicos do driver.
  2. Envie e compare o display físico com a tela de desenho do Lopaka.
  3. Ajuste a variante do driver, o endereço, a rotação, o tamanho da tela de desenho ou as posições das camadas conforme necessário.
  4. Quando o design mudar, substitua o bloco gerado completo em vez de manter chamadas de desenho individuais à mão.

Mantenha o código de hardware e do aplicativo fora da seção gerada:

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

Solução de problemas ​

O display está em branco ​

  • Restaure e envie o exemplo oficial do driver. Se ele também estiver em branco, verifique energia, tensão, terra, fiação, controlador, endereço, reset e pinos do barramento.
  • Confirme que o método de inicialização do driver é bem-sucedido antes de chamar a função do Lopaka.
  • Confirme que o nome do objeto gerado corresponde à sua instância: tft para colorido ou display para mono.
  • Para um driver com buffer, como o SSD1306, chame seu método de atualização depois de desenhar. O modelo mono do Lopaka emite display.display(); outro driver pode exigir um método diferente.

A imagem está deslocada, cortada, espelhada ou girada ​

Faça a tela de desenho do Lopaka corresponder às dimensões lógicas depois de setRotation(). Use a variante exata do driver para o painel: a RAM do controlador pode ser maior que a área visível, e alguns módulos precisam de deslocamentos específicos do driver.

As cores estão erradas ​

O destino colorido emite valores RGB565. Confirme que a biblioteca específica do hardware espera valores de cor de 16 bits padrão da Adafruit GFX e que sua inicialização seleciona a variante correta do painel. Se o vermelho e o azul estiverem trocados, investigue a ordem de cores ou a configuração do painel do driver em vez de alterar cada cor do Lopaka.

Uma fonte personalizada não compila ou não se alinha ​

  • Baixe seu arquivo .h em Configurações de código → Fontes e coloque-o ao lado do sketch.
  • Mantenha Incluir fontes ativado e confirme que o nome do arquivo, o nome incluído e o símbolo GFX correspondem.
  • Lembre-se de que fontes GFX personalizadas usam uma linha de base e ignoram o argumento de fundo de setTextColor().
  • Use menos fontes ou fontes menores se o programa ultrapassar a capacidade de flash.

Uma imagem não compila ou usa flash demais ​

Mantenha Declarar imagens ativado se a chamada de desenho gerada referenciar um bitmap em linha. Recorte e redimensione a origem para suas dimensões finais. Troque um ícone simples de RGB para monocromático quando uma cor de primeiro plano bastar.

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

Mantenha um setup() e um loop(). Mantenha a inicialização do driver do exemplo oficial de hardware e então mescle o cabeçalho de animação gerado, a função de atualização e as funções de desenho. As animações do Lopaka usam quadros de um bit; elas não preservam quadros de vídeo RGB.

Perguntas frequentes ​

O Lopaka é compatível com todos os displays Adafruit? ​

O Lopaka mira a API de desenho compartilhada Adafruit GFX, não uma lista de módulos de display. Um display é uma combinação prática quando ele tem um driver compatível com Adafruit GFX para o seu ambiente Arduino ou ESP32 e esse driver oferece suporte aos métodos emitidos para o seu design. Verifique o módulo exato com o exemplo oficial do seu driver.

O Lopaka instala ou configura a Adafruit GFX? ​

Não. Instale o driver específico do hardware e suas dependências, crie o objeto de display e inicialize-o no seu sketch. O Lopaka fornece chamadas de desenho e recursos.

O destino colorido pode exportar imagens em cores completas? ​

Sim. Camadas de imagem RGB geram arrays RGB565 e chamadas drawRGBBitmap(), com uma máscara opcional de um bit para pixels transparentes no destino colorido (a caixa de seleção Transparência). Camadas de imagem monocromáticas e todos os quadros de animação permanecem com um bit por pixel. A exportação de bitmap em escala de cinza não é compatível com os modelos Adafruit do Lopaka.

Onde posso aprender mais? ​