Przewodnik TFT_eSPI po kolorowych wyświetlaczach ESP32

Ten przewodnik prowadzi kolorowy projekt TFT krok po kroku — od pustego obszaru rysowania w Lopaka do działającego wyświetlacza ESP32.

Podział pracy ma tu większe znaczenie niż na jakiejkolwiek innej platformie: Lopaka rysuje obraz, a ty konfigurujesz bibliotekę. TFT_eSPI jest konfigurowana w czasie kompilacji za pomocą pliku ustawień i Lopaka nigdy nie dotyka tego pliku. Najpierw spraw, aby biblioteka komunikowała się z twoim panelem, a potem pozwól Lopaka wygenerować kod rysowania.

Czym jest TFT_eSPI?

TFT_eSPI to szybka biblioteka wyświetlaczy SPI dla ESP32, ESP8266, RP2040 i STM32. Obsługuje kontrolery spotykane w większości niedrogich modułów kolorowych — ILI9341, ST7735, ST7789, GC9A01, ILI9488 i wiele innych — i zapewnia jedno API rysowania dla nich wszystkich.

Platforma TFT_eSPI, M5, Lovyan w Lopaka obejmuje również dwie biblioteki zgodne pod względem API:

Biblioteka	Typowy sprzęt	Obiekt wyświetlacza w twoim szkicu
TFT_eSPI	Ogólne ESP32/ESP8266/RP2040 + panel	`TFT_eSPI tft = TFT_eSPI();`
M5GFX (M5Unified)	M5Stack Core, StickC, Dial, Cardputer	`M5.Display`
LovyanGFX	Dowolny z powyższych, ESP32-S3 parallel	Twoja własna podklasa `LGFX`

Wszystkie trzy udostępniają te same wywołania rysowania (fillRect, drawString, pushImage, …), więc ten sam wygenerowany kod działa na wszystkich trzech, gdy obiekt wyświetlacza nazywa się tft.

Czym nie jest TFT_eSPI

Nie jest to zestaw narzędzi interfejsu użytkownika. Nie ma przycisków, silnika układu ani automatycznego przerysowania. Rysujesz piksele wtedy, gdy zdecydujesz się je narysować. Jeśli chcesz widżetów i obsługi zdarzeń, zobacz zamiast tego LVGL.

Zanim zaczniesz

Potrzebujesz:

Płytki ESP32 (lub ESP8266 / RP2040 / STM32) oraz kolorowego modułu TFT.
Nazwy kontrolera podanej w ofercie lub arkuszu danych twojego modułu — na przykład ILI9341, ST7789, GC9A01.
Rozdzielczości (240×320, 240×240, 128×160, …) oraz pinów, do których podłączyłeś wyświetlacz.
Arduino IDE lub PlatformIO, potrafiących kompilować i wgrywać na twoją płytkę.

Uwaga

Lopaka nie wykrywa twojego kontrolera, nie generuje okablowania ani nie zapisuje konfiguracji TFT_eSPI. Dwa moduły o identycznej rozdzielczości mogą wymagać zupełnie innych sterowników, przypisań pinów, kolejności kolorów i przesunięć. Ta część zawsze należy do ciebie.

Krok 0: Zainstaluj i skonfiguruj TFT_eSPI

To krok, który początkujący pomijają, a potem spędzają wieczór przed białym ekranem. Wykonaj go najpierw i nie otwieraj Lopaka, dopóki standardowy przykład nie zacznie rysować na twoim panelu.

Zainstaluj bibliotekę

Arduino IDE: otwórz Tools → Manage Libraries, wyszukaj TFT_eSPI autorstwa Bodmera i zainstaluj.

PlatformIO: dodaj ją do platformio.ini:

ini

lib_deps = bodmer/TFT_eSPI

Poinformuj ją o swoim wyświetlaczu

TFT_eSPI odczytuje swoją konfigurację z User_Setup.h w czasie kompilacji, a nie z konstruktora. Są dwa sposoby jej ustawienia i wybierasz tylko jeden:

Edytuj User_Setup.h w folderze biblioteki (Arduino/libraries/TFT_eSPI/User_Setup.h). Odkomentuj #define dla swojego sterownika, a następnie ustaw piny i rozdzielczość.
Użyj dołączonego pliku konfiguracji. Otwórz User_Setup_Select.h, zakomentuj linię #include <User_Setup.h> i odkomentuj jeden z plików User_Setups/Setup*.h, który pasuje do twojej płytki. To łatwiejsza ścieżka dla znanych płytek, takich jak ESP32 TTGO T-Display.

Minimalny User_Setup.h dla panelu ILI9341 na ESP32 wygląda mniej więcej tak:

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

Pozostaw LOAD_GLCD i LOAD_GFXFF włączone

LOAD_GLCD zapewnia wbudowaną czcionkę 5×7. LOAD_GFXFF włącza setFreeFont(), z którego korzysta każda niedomyślna warstwa tekstowa Lopaka. Jeśli LOAD_GFXFF jest zakomentowane, twój tekst po cichu zniknie lub nie uda się go skompilować.

Użytkownicy PlatformIO mogą przekazać te same definicje jako flagi kompilacji zamiast edytować pliki biblioteki, co przetrwa aktualizacje biblioteki:

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

Udowodnij, że działa

Otwórz File → Examples → TFT_eSPI → Test and Diagnostics → Colour_Test (lub Generic → Free_Font_Demo) i wgraj go. Powinieneś zobaczyć kolory i tekst. Jeśli nie, napraw to przed dalszą pracą — każdy późniejszy problem w tym przewodniku stanie się nierozwiązywalny, dopóki konfiguracja biblioteki jest błędna.

Zachowaj ten działający przykład jako swój bazowy szkic. Od tego momentu zamieniasz tylko jego wywołania rysowania na wyjście Lopaka.

Krok 1: Utwórz projekt w Lopaka

Otwórz lopaka.app i utwórz projekt.
Wybierz platformę TFT_eSPI, M5, Lovyan.
Ustaw Rozmiar ekranu na rozdzielczość, której faktycznie używa twój szkic.
Wybierz kolor tła ekranu — stanie się argumentem fillScreen() w wygenerowanym kodzie.

Współrzędne zaczynają się od (0, 0) w lewym górnym rogu, X rośnie w prawo, a Y rośnie w dół. Lopaka używa tego samego systemu, więc warstwa na pozycji (10, 20) w edytorze jest na pozycji (10, 20) na panelu.

Obrót

Jeśli twój szkic wywołuje tft.setRotation(1) na panelu 240×320, logiczny ekran staje się 320×240 — więc obszar rysowania Lopaka powinien mieć 320×240. Lopaka nigdy nie generuje setRotation(); dopasuj obszar rysowania do orientacji, którą wybrałeś w kodzie.

Krok 2: Zaprojektuj ekran

Umieszczaj warstwy za pomocą paska narzędzi, zmieniaj ich kolejność w panelu Warstwy i edytuj wartości w inspektorze. Warstwy są rysowane w kolejności listy, więc późniejsza warstwa maluje ponad wcześniejszą — dokładnie tak, jak będą wykonywane wygenerowane wywołania.

Zmień nazwy warstw przed eksportem. Nazwy stają się komentarzami w kodzie, nazwami tablic bitmap, nazwami funkcji pomocniczych wielokątów, nagłówkami animacji i nazwami zmiennych.

Co generuje każda warstwa

Warstwa Lopaka	Wygenerowane wywołanie TFT_eSPI
Punkt	`tft.drawPixel(x, y, color)`
Linia	`tft.drawLine(x1, y1, x2, y2, color)`
Prostokąt	`tft.drawRect(...)` / `tft.fillRect(...)`
Zaokrąglony prostokąt	`tft.drawRoundRect(...)` / `tft.fillRoundRect(...)`
Elipsa	`tft.drawEllipse(x, y, rx, ry, color)` / `tft.fillEllipse(...)`
Trójkąt	`tft.drawTriangle(...)` / `tft.fillTriangle(...)`
Łuk	`tft.drawSmoothArc(...)` lub `tft.drawArc(...)`
Wielokąt	Wygenerowana funkcja pomocnicza `void drawMyShape(void)` zbudowana z wywołań `drawLine()`
Tekst	`setTextColor()`, `setTextSize()`, `setFreeFont()`, `drawString()`
Malowanie / ikona / obraz	`tft.drawBitmap(...)` (1-bit) lub `tft.pushImage(...)` (RGB565)
Animacja	Tablice klatek oraz funkcje pomocnicze `updateAnimations()` / `drawAnimations()`

Na tej platformie nie ma narzędzia Koło — użyj narzędzia Elipsa o równych promieniach; prymitywy elips TFT_eSPI to pokrywają.

Kolory

Lopaka pozwala wybrać dowolny kolor RGB, a następnie pakuje go do 16-bitowej wartości RGB565, której oczekuje TFT_eSPI, więc #FF0000 staje się 0xF800. To 5 bitów czerwieni, 6 zieleni i 5 niebieskiego — 65 536 kolorów, a nie 16 milionów. Subtelne gradienty będą pasmować. Przezroczyste piksele w obrazie źródłowym RGB są domyślnie komponowane na tle ekranu; zaznacz opcję Przezroczystość w inspektorze, aby zachować ich przezroczystość przy użyciu jednobitowej maski (zobacz Obrazy poniżej).

Tekst

Warstwy tekstowe generują drawString(text, x, y), gdzie x, y to lewy górny róg tekstu — domyślny TL_DATUM TFT_eSPI. Lopaka dostosowuje współrzędną Y do metryk wybranej czcionki, więc nie musisz ręcznie obliczać linii bazowej.

Trzy właściwości mapują się na stan biblioteki, a Lopaka generuje każde wywołanie tylko wtedy, gdy zmienia się między warstwami:

Kolor → setTextColor(fg) lub setTextColor(fg, bg), gdy ustawisz kolor tła tekstu. Tło sprawia, że przerysowany tekst nadpisuje swoje stare piksele, zamiast zostawiać smugi.
Rozmiar → setTextSize(n), całkowity mnożnik pikseli. 2 podwaja każdy piksel, więc wygląda na blokowy, a nie gładki.
Czcionka → setFreeFont(&FreeSans9pt7b) dla czcionki GFX lub setFreeFont(NULL) dla wbudowanej czcionki 5×7.

Uwaga

Jeśli twój własny kod zmieni punkt odniesienia tekstu (tft.setTextDatum(MC_DATUM)), wygenerowany tekst znajdzie się w złym miejscu. Zresetuj go za pomocą tft.setTextDatum(TL_DATUM) przed wywołaniem funkcji Lopaka.

Łuki

Narzędzie Łuk jest unikalne dla tej platformy. Kąty są stopniami mierzonymi zgodnie z ruchem wskazówek zegara od godziny 12, więc wskaźnik od 30 do 330 otwiera się na dole. Przełącznik gładkości w inspektorze wybiera między dwoma wywołaniami biblioteki:

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

Oba przyjmują kolor tła, ponieważ piksele z wygładzaniem są z nim mieszane. Ustaw tło łuku na to, na czym faktycznie się znajduje, inaczej jego krawędzie będą miały poświatę. drawSmoothArc() wymaga TFT_eSPI 2.4.x lub nowszej — zaktualizuj bibliotekę, jeśli kompilator mówi, że jest niezdefiniowana.

Krok 3: Skonfiguruj wygenerowany kod

Otwórz Ustawienia kodu pod panelem kodu. Ta platforma ma dwa szablony C++ i następujące przełączniki:

Składnia wybiera docelowe środowisko (framework). Arduino (C++) jest domyślna. ESP-IDF (C++) generuje te same wywołania rysowania dla komponentu ESP-IDF: tablice obrazów, masek i animacji są zwykłymi tablicami static const uint8_t / uint16_t bez PROGMEM, taktowanie animacji używa esp_timer_get_time() z esp_timer.h i nie jest generowane żadne setup() / loop() — wywołuj draw{ScreenName}() i drawAnimations() z pętli własnego zadania. Pobrane nagłówki obrazów i animacji podążają za wybranym szablonem.

Ustawienie	Co robi
Funkcja opakowująca	Opakowuje ekran w `void draw{ScreenName}(void)`
Dołącz czcionki	Generuje `#include "FontName.h"` dla czcionek niestandardowych (zobacz Czcionki)
Deklaruj obrazy	Generuje tablice bitmap, do których odwołują się warstwy obrazów
Funkcje pomocnicze animacji	Generuje include'y nagłówków animacji oraz funkcje pomocnicze czasu i rysowania
Deklaruj zmienne	Generuje deklaracje dla właściwości warstw oznaczonych jako zmienne
Komentarze, tytuły warstw	Dodaje komentarz `// Nazwa warstwy` nad wywołaniami każdej warstwy
Wyczyść/wypełnij wyświetlacz	Rozpoczyna blok od `tft.fillScreen(backgroundColor)`

Przy pierwszym eksporcie pozostaw wszystko włączone. Przycisk Kopiuj kopiuje dokładnie to, co pokazuje panel.

Obiekt musi nazywać się tft

Każda wygenerowana linia zaczyna się od tft.. Najprostszą poprawką jest nazwanie obiektu wyświetlacza tft w szkicu. W M5Stack dodaj jedną linię aliasu: M5GFX& tft = M5.Display;

Krok 4: Czcionki, obrazy i animacje

Czcionki

Wbudowana czcionka Adafruit 5×7 oraz Free Fonts (FreeSans, FreeMono, FreeSerif w rozmiarach 9/12/18/24pt, z wariantami pogrubionymi i pochyłymi) nie potrzebują pliku nagłówkowego. TFT_eSPI kompiluje Free Fonts, gdy zdefiniowane jest LOAD_GFXFF (zobacz Poinformuj ją o swoim wyświetlaczu), więc Lopaka nie generuje dla nich #include i nie wymienia ich w sekcji Ustawienia kodu → Czcionki.

Każda inna czcionka potrzebuje nagłówka: mniejsze czcionki Adafruit (Org_01, Picopixel, Tiny3x3a2pt7b, Petme8x8) oraz wszystko, co prześlesz. Dla każdej takiej czcionki na ekranie:

Otwórz Ustawienia kodu i znajdź sekcję Czcionki.
Kliknij przycisk pobierania obok czcionki, aby otrzymać jej plik .h.
Umieść ten plik w tym samym folderze co twój plik .ino lub .cpp.
Pozostaw opcję Dołącz czcionki włączoną, aby linia #include "Picopixel.h" pozostała w wyjściu.

Lopaka może konwertować przesłane czcionki TrueType (.ttf, .otf, .woff) i BDF do formatu GFX. Zobacz przewodnik po czcionkach dla ścieżek importu.

Dane czcionek znajdują się w pamięci flash. Czcionka 24pt z pełnym zestawem znaków kosztuje dziesiątki kilobajtów, więc dużych krojów używaj oszczędnie.

Obrazy

Użyj narzędzia Obraz, aby zaimportować i przyciąć grafikę w jej docelowym rozmiarze pikseli. To, co zostanie wygenerowane, zależy od trybu koloru warstwy:

Monochromatyczny → jednobitowa tablica PROGMEM rysowana za pomocą tft.drawBitmap(x, y, bits, w, h, color). Jeden kolor, nieustawione piksele przezroczyste, 1 bit na piksel. Najlepsze dla ikon.
RGB → tablica RGB565 uint16_t PROGMEM rysowana za pomocą tft.pushImage(x, y, w, h, pixels). Pełny kolor, 2 bajty na piksel. Zaimportowany obraz wypełnia swoje przezroczyste piksele tłem ekranu. Zaznacz opcję Przezroczystość obok opcji Nakładka w inspektorze (pojawia się, gdy obraz ma przezroczyste piksele), a Lopaka wygeneruje również jednobitową tablicę image_<Name>_mask i będzie rysować za pomocą tft.pushMaskedImage(...), dzięki czemu te piksele zachowają to, co ekran już pokazuje.

Sekcja Ustawienia kodu → Obrazy wymienia każdy obraz jako image_<Name>_bits.h lub image_<Name>_pixels.h, zawierający dokładnie te bajty, które zawiera tablica w kodzie. Włącz opcję Dołącz pliki obrazów, aby generować #include "<symbol>.h" zamiast tablicy i przechowywać piksele w pobranym nagłówku.

Uważaj na budżet pamięci flash

Pełnoekranowy obraz RGB 240×320 ma 153 600 bajtów — około 12% standardowej partycji szkicu ESP32 na jeden obraz. Przycinaj ciasno, zmniejszaj skalę i używaj monochromatycznego dla wszystkiego, co jest jednokolorowe.

Jeśli kolory obrazów wychodzą błędne, a kształty wyglądają poprawnie, zobacz kolejność bajtów w Rozwiązywaniu problemów.

Przewodnik importu obrazów omawia zmianę rozmiaru, przycinanie, dithering i szacowanie rozmiaru.

Animacje

Warstwy animacji eksportują się jako klatki jednobitowe — dwukolorowy flipbook, a nie wideo. Każda klatka jest rysowana za pomocą setBitmapColor(foreground, background), po którym następuje pushImage().

Włączenie opcji Funkcje pomocnicze animacji znacząco zmienia kształt wyjścia:

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

Połącz, nie wklejaj

To wygenerowane setup() i loop() jest szkieletem startowym. Twój szkic ma już oba. Zachowaj jedno setup() i jedno loop(): weź include'y, tablice klatek, updateAnimations() i funkcje pomocnicze rysowania, a następnie wywołuj drawAnimations() z istniejącej pętli.

Pobierz każdy plik .h wymieniony w sekcji Ustawienia kodu → Animacje i przechowuj go obok szkicu. Zobacz Animacje, aby zapoznać się z przebiegiem pracy w edytorze.

Krok 5: Skopiuj i zintegruj

Nazwij swój ekran Main, dodaj warstwę tekstową i prostokąt, a następnie kliknij Kopiuj. Otrzymasz coś takiego:

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

Wstawione do kompletnego szkicu:

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() {}

TFT_eSPI zapisuje bezpośrednio na panelu, więc nie ma bufora do opróżnienia — nic w rodzaju wywołania display.display(), którego potrzebują biblioteki monochromatyczne.

M5Stack

M5GFX to to samo API za innym obiektem. Wystarczy jedna linia aliasu:

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

M5Unified automatycznie konfiguruje panel dla konkretnej płytki M5, więc całkowicie pomijasz User_Setup.h. W przypadku M5.begin() postępuj zgodnie z oficjalnym przykładem dla swojej płytki.

LovyanGFX

LovyanGFX potrzebuje klasy LGFX opisującej twój panel (jej repozytorium ma gotowe konfiguracje dla popularnych płytek). Nazwij instancję tft, a wygenerowany kod wpasuje się bez zmian.

Krok 6: Dane w czasie wykonywania i więcej ekranów

Nadawanie wartościom dynamiki

Statyczny tekst sprawdza się w makiecie, ale nie w termometrze. Wybierz warstwę, włącz przełącznik zmiennej dla obsługiwanej właściwości w inspektorze i pozostaw opcję Deklaruj zmienne włączoną. Lopaka zastępuje literał deklaracją nazwaną od warstwy:

cpp

const char* temperature = "21.5 C";

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

Zaktualizuj zmienną w swoim kodzie, wywołaj ponownie drawMain(), a nowa wartość się pojawi.

Unikaj migotania na całym ekranie

Wywoływanie drawMain() w ciasnej pętli przerysowuje wszystko i migocze. Dla wartości, która często się zmienia, nadaj jej warstwie tekstowej kolor tła i przerysuj tylko wywołanie tej warstwy — albo rysuj do TFT_eSprite i wysyłaj sprite'a. Sprite'y to funkcja TFT_eSPI, którą dodajesz samodzielnie; Lopaka ich nie generuje.

Wiele ekranów

Każdy ekran Lopaka eksportuje się niezależnie, a jego tytuł staje się nazwą funkcji. Skopiuj każdy z nich, połącz zduplikowane include'y i tablice bitmap, a następnie pozwól swojemu kodowi wybrać:

cpp

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

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

Importowanie istniejącego kodu

Panel kodu ma przycisk Importuj kod, który odczytuje plik .ino, .c, .cpp lub .txt i zamienia rozpoznane wywołania tft.* na edytowalne warstwy. Jest eksperymentalny i najlepiej działa na kodzie wygenerowanym przez samą Lopaka — ręcznie napisane szkice z pętlami, zmiennymi i funkcjami pomocniczymi nie przejdą pełnej konwersji w obie strony. Zaimportowane warstwy są dopisywane do bieżącego ekranu.

Co robi Lopaka, a co robisz ty

Lopaka robi	Ty robisz
Układ pikseli, kolejność warstw i wywołania rysowania	`User_Setup.h`, wybór sterownika, piny i częstotliwość SPI
Pakowanie RGB → RGB565 dla kształtów, tekstu i obrazów	Kolejność kolorów panelu, odwrócenie i przesunięcia
Tablice bitmap, nagłówki czcionek GFX, klatki animacji	Budżet pamięci flash i przechowywanie pobranych plików `.h` wraz ze szkicem
Obliczenia linii bazowej tekstu i wywołania stanu czcionki	Punkt odniesienia tekstu, jeśli twój kod go zmienia
Nazwaną funkcję rysowania dla każdego ekranu	Jej wywoływanie, taktowanie przerysowań, wejścia i nawigację
Opcjonalne deklaracje zmiennych	Aktualizowanie tych zmiennych prawdziwymi danymi

Kompiluj, wgrywaj i iteruj

Kompiluj przed wgraniem i najpierw napraw brakujące nagłówki lub niezdefiniowane symbole.
Wgraj i porównaj panel z obszarem rysowania Lopaka.
Dostosuj rozmiar obszaru rysowania, obrót lub pozycje warstw i wyeksportuj ponownie.
Gdy projekt się zmieni, zastąp cały wygenerowany blok. Nie edytuj ręcznie pojedynczych wywołań rysowania — kolejny eksport je nadpisze.

Oznaczenie bloku sprawia, że jest to bezbolesne:

cpp

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

Rozwiązywanie problemów

Ekran jest biały, czarny lub pusty

Prawie zawsze konfiguracja biblioteki, a nie wygenerowany kod.

Ponownie uruchom standardowy przykład TFT_eSPI. Jeśli on też jest pusty, problemem jest User_Setup.h, okablowanie lub zasilanie.
Potwierdź, że właściwy #define sterownika jest odkomentowany i tylko jeden.
Sprawdź pin podświetlenia — wiele modułów wymaga ustawienia TFT_BL na wysoki poziom.
Potwierdź, że tft.init() jest wykonywane przed twoją funkcją rysowania.
Obniż SPI_FREQUENCY do 27000000; długie przewody połączeniowe nie przetrwają 40 MHz.

`'tft' was not declared in this scope`

Wygenerowany kod wywołuje tft.*. Nazwij swój obiekt wyświetlacza tft lub dodaj alias, taki jak M5GFX& tft = M5.Display;.

`setFreeFont` lub `drawSmoothArc` jest niezdefiniowana

setFreeFont() potrzebuje #define LOAD_GFXFF w User_Setup.h. drawSmoothArc() potrzebuje TFT_eSPI 2.4.x lub nowszej — zaktualizuj przez Menedżer bibliotek.

Nagłówek czcionki się nie kompiluje

Dla Free Font (FreeSans9pt7b i podobne) nie ma nagłówka do dodania: sprawdź, czy LOAD_GFXFF jest zdefiniowane w User_Setup.h i czy szkic nie ma pozostawionego #include "FreeSans9pt7b.h" ze starszego eksportu. Dla każdej innej czcionki pobierz plik .h z sekcji Ustawienia kodu → Czcionki, umieść go obok szkicu i pozostaw opcję Dołącz czcionki włączoną, aby nazwa pliku, include i symbol &FontName się zgadzały.

Kolory są wszędzie błędne

Zamienione czerwony i niebieski na całym ekranie to problem kolejności kolorów panelu: wypróbuj TFT_RGB_ORDER TFT_BGR (lub TFT_RGB) w User_Setup.h. Obraz wyglądający na odwrócony to #define TFT_INVERSION_ON / TFT_INVERSION_OFF. Napraw to w pliku konfiguracji — nigdy przez zmianę każdego koloru w projekcie.

Kolory obrazów są błędne, ale kształty są poprawne

Lopaka zapisuje dane obrazu RGB565 z zamienioną kolejnością bajtów, w tej samej konwencji, której używa większość konwerterów obrazów TFT_eSPI. Powiedz bibliotece, aby zamieniła je z powrotem przed wysłaniem obrazów:

cpp

tft.setSwapBytes(true);

Wywołaj to raz w setup(), po tft.init(). Jeśli obrazy były już poprawne i to je psuje, ustaw false.

Tekst jest w złym miejscu

Zresetuj punkt odniesienia za pomocą tft.setTextDatum(TL_DATUM) przed wygenerowaną funkcją — Lopaka zakłada domyślny punkt odniesienia w lewym górnym rogu. Jeśli zamiast tego wszystko jest przesunięte lub przycięte, rozmiar obszaru rysowania nie odpowiada wyświetlaczowi po setRotation().

Tekst zostawia smugi przy aktualizacji

drawString() maluje tylko piksele glifów; stare pozostają. Nadaj warstwie tekstowej kolor tła w Lopaka, aby generowała setTextColor(fg, bg), albo najpierw wyczyść obszar za pomocą fillRect().

Projekt jest obrócony, odbity lub przesunięty o kilka pikseli

Dopasuj obszar rysowania Lopaka do logicznego rozmiaru po setRotation(). Stałe przesunięcie o kilka pikseli zwykle oznacza niewłaściwy wariant sterownika — niektóre panele mają pamięć RAM kontrolera większą niż widoczny obszar i wymagają definicji przesunięcia specyficznej dla sterownika.

Szkic nie mieści się w pamięci flash

Obrazy RGB565 są zwykle sprawcą — 2 bajty na piksel. Przycinaj ciaśniej, zmniejszaj skalę, konwertuj jednokolorową grafikę na monochromatyczną i usuwaj nieużywane duże czcionki.

Kod animacji konfliktuje z moim szkicem

Zachowaj jedno setup() i jedno loop(). Weź include'y, tablice klatek i funkcje pomocnicze z wygenerowanego wyjścia; zachowaj własne inicjowanie; wywołuj drawAnimations() z istniejącej pętli.

Częste pytania

Czy Lopaka konfiguruje TFT_eSPI za mnie?

Nie. User_Setup.h, wybór sterownika, piny i częstotliwość SPI należą w całości do ciebie. Lopaka generuje wywołania rysowania i zasoby, które zakładają działający, zainicjowany obiekt wyświetlacza o nazwie tft.

Czy mój wyświetlacz działa z Lopaka?

Jeśli steruje nim TFT_eSPI, M5GFX lub LovyanGFX, to tak — Lopaka kieruje się wspólnym API, a nie listą modułów. Najpierw zweryfikuj moduł za pomocą standardowego przykładu biblioteki.

Czy mogę eksportować obrazy w pełnym kolorze?

Tak — warstwy obrazów RGB stają się tablicami RGB565 rysowanymi za pomocą pushImage(). Klatki animacji są zawsze jednobitowe, niezależnie od kolorów, których używają w edytorze.

Czy Lopaka generuje sprite'y, DMA lub częściowe przerysowania?

Nie. Generuje bezpośrednie wywołania rysowania. TFT_eSprite, transfery DMA i przerysowania „brudnych prostokątów” to optymalizacje, które dodajesz wokół wygenerowanej funkcji.

Przewodnik TFT_eSPI po kolorowych wyświetlaczach ESP32 ​

Czym jest TFT_eSPI? ​

Zanim zaczniesz ​

Krok 0: Zainstaluj i skonfiguruj TFT_eSPI ​

Zainstaluj bibliotekę ​

Poinformuj ją o swoim wyświetlaczu ​

Udowodnij, że działa ​

Krok 1: Utwórz projekt w Lopaka ​

Krok 2: Zaprojektuj ekran ​

Co generuje każda warstwa ​

Kolory ​

Tekst ​

Łuki ​

Krok 3: Skonfiguruj wygenerowany kod ​

Krok 4: Czcionki, obrazy i animacje ​

Czcionki ​

Obrazy ​

Animacje ​

Krok 5: Skopiuj i zintegruj ​

M5Stack ​

LovyanGFX ​

Krok 6: Dane w czasie wykonywania i więcej ekranów ​

Nadawanie wartościom dynamiki ​

Wiele ekranów ​

Importowanie istniejącego kodu ​

Co robi Lopaka, a co robisz ty ​

Kompiluj, wgrywaj i iteruj ​

Rozwiązywanie problemów ​

Ekran jest biały, czarny lub pusty ​

'tft' was not declared in this scope ​

setFreeFont lub drawSmoothArc jest niezdefiniowana ​

Nagłówek czcionki się nie kompiluje ​

Kolory są wszędzie błędne ​

Kolory obrazów są błędne, ale kształty są poprawne ​

Tekst jest w złym miejscu ​

Tekst zostawia smugi przy aktualizacji ​

Projekt jest obrócony, odbity lub przesunięty o kilka pikseli ​

Szkic nie mieści się w pamięci flash ​

Kod animacji konfliktuje z moim szkicem ​

Częste pytania ​

Czy Lopaka konfiguruje TFT_eSPI za mnie? ​

Czy mój wyświetlacz działa z Lopaka? ​

Czy mogę eksportować obrazy w pełnym kolorze? ​

Czy Lopaka generuje sprite'y, DMA lub częściowe przerysowania? ​

Gdzie mogę dowiedzieć się więcej? ​