TFT_eSPI-Anleitung für Farbdisplays mit ESP32

Diese Anleitung führt dich Schritt für Schritt von einer leeren Lopaka-Zeichenfläche zu einem funktionierenden Farb-TFT-Display am ESP32.

Die Arbeitsteilung ist hier wichtiger als bei jeder anderen Plattform: Lopaka zeichnet das Bild, du konfigurierst die Bibliothek. TFT_eSPI wird beim Kompilieren über eine Einstellungsdatei konfiguriert, und Lopaka fasst diese Datei nie an. Bring zuerst die Bibliothek dazu, mit deinem Panel zu sprechen, und lass dann Lopaka den Zeichencode erzeugen.

Was ist TFT_eSPI?

TFT_eSPI ist eine schnelle SPI-Displaybibliothek für ESP32, ESP8266, RP2040 und STM32. Sie unterstützt die Controller der meisten günstigen Farbmodule – ILI9341, ST7735, ST7789, GC9A01, ILI9488 und viele mehr – und bietet dir für alle eine einzige Zeichen-API.

Die Plattform TFT_eSPI, M5, Lovyan in Lopaka deckt außerdem zwei API-kompatible Bibliotheken ab:

Bibliothek	Typische Hardware	Display-Objekt in deinem Sketch
TFT_eSPI	Generisches ESP32/ESP8266/RP2040 + Panel	TFT_eSPI tft = TFT_eSPI();
M5GFX (M5Unified)	M5Stack Core, StickC, Dial, Cardputer	M5.Display
LovyanGFX	Alle oben genannten, ESP32-S3 parallel	Deine eigene LGFX-Unterklasse

Alle drei bieten dieselben Zeichenaufrufe (fillRect, drawString, pushImage, …), daher funktioniert derselbe generierte Code mit allen dreien, sobald das Display-Objekt tft heißt.

Was TFT_eSPI nicht ist

Es ist kein UI-Toolkit. Es gibt keine Buttons, keine Layout-Engine und kein automatisches Neuzeichnen. Du zeichnest Pixel, wenn du dich dafür entscheidest. Wenn du Widgets und Event-Handling willst, sieh dir stattdessen LVGL an.

Bevor du anfängst

Du brauchst:

• Ein ESP32-Board (oder ESP8266 / RP2040 / STM32) und ein Farb-TFT-Modul.
• Den Controller-Namen aus der Produktbeschreibung oder dem Datenblatt deines Moduls, zum Beispiel ILI9341, ST7789, GC9A01.
• Die Auflösung (240×320, 240×240, 128×160, …) und die Pins, an die du das Display angeschlossen hast.
• Arduino IDE oder PlatformIO, womit du für dein Board kompilieren und hochladen kannst.

Achtung

Lopaka erkennt deinen Controller nicht, erzeugt keine Verdrahtung und schreibt keine TFT_eSPI-Konfiguration. Zwei Module mit identischer Auflösung können völlig unterschiedliche Treiber, Pinbelegungen, Farbreihenfolgen und Offsets brauchen. Dieser Teil liegt immer bei dir.

Schritt 0: TFT_eSPI installieren und konfigurieren

Diesen Schritt überspringen Einsteiger gern – und verbringen dann einen Abend vor einem weißen Display. Erledige ihn zuerst und öffne Lopaka erst, wenn ein mitgeliefertes Beispiel auf deinem Panel zeichnet.

Bibliothek installieren

Arduino IDE: Öffne Tools → Manage Libraries, suche nach TFT_eSPI von Bodmer und installiere die Bibliothek.

PlatformIO: Füge sie zu platformio.ini hinzu:

lib_deps = bodmer/TFT_eSPI

Der Bibliothek dein Display beschreiben

TFT_eSPI liest seine Konfiguration beim Kompilieren aus User_Setup.h, nicht aus dem Konstruktor. Es gibt zwei Wege, sie festzulegen, und du wählst nur einen:

1. Bearbeite User_Setup.h im Bibliotheksordner (Arduino/libraries/TFT_eSPI/User_Setup.h). Entferne die Auskommentierung beim #define deines Treibers und lege dann Pins und Auflösung fest.
2. Nutze eine mitgelieferte Setup-Datei. Öffne User_Setup_Select.h, kommentiere die Zeile #include <User_Setup.h> aus und aktiviere eine der User_Setups/Setup*.h-Dateien, die zu deinem Board passt. Für bekannte Boards wie das ESP32 TTGO T-Display ist das der einfachere Weg.

Eine minimale User_Setup.h für ein ILI9341-Panel an einem ESP32 sieht ungefähr so aus:

#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

LOAD_GLCD und LOAD_GFXFF aktiviert lassen

LOAD_GLCD liefert die integrierte 5×7-Schriftart. LOAD_GFXFF aktiviert setFreeFont(), das jede Lopaka-Textebene mit einer anderen als der Standardschriftart nutzt. Ist LOAD_GFXFF auskommentiert, verschwindet dein Text kommentarlos oder lässt sich nicht kompilieren.

Wer PlatformIO nutzt, kann dieselben Defines als Build-Flags übergeben, statt Bibliotheksdateien zu bearbeiten – das übersteht auch Updates der Bibliothek:

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

Testen, ob es funktioniert

Öffne File → Examples → TFT_eSPI → Test and Diagnostics → Colour_Test (oder Generic → Free_Font_Demo) und lade es hoch. Du solltest Farben und Text sehen. Wenn nicht, behebe das, bevor du weitermachst – solange die Bibliothekskonfiguration falsch ist, lässt sich keines der späteren Probleme in dieser Anleitung lösen.

Behalte dieses funktionierende Beispiel als Basis-Sketch. Ab jetzt ersetzt du nur noch seine Zeichenaufrufe durch die Ausgabe von Lopaka.

Schritt 1: Lopaka-Projekt anlegen

1. Öffne lopaka.app und lege ein Projekt an.
2. Wähle die Plattform TFT_eSPI, M5, Lovyan.
3. Stelle Screen-Größe auf die Auflösung ein, die dein Sketch tatsächlich nutzt.
4. Wähle die Hintergrundfarbe des Screens – sie wird im generierten Code zum Argument von fillScreen().

Die Koordinaten beginnen bei (0, 0) in der linken oberen Ecke, X wächst nach rechts, Y nach unten. Lopaka nutzt dasselbe System, eine Ebene bei (10, 20) im Editor liegt also auch auf dem Panel bei (10, 20).

Drehung

Ruft dein Sketch auf einem 240×320-Panel tft.setRotation(1) auf, wird der logische Screen 320×240 groß – die Lopaka-Zeichenfläche sollte also 320×240 sein. Lopaka erzeugt nie setRotation(); richte die Zeichenfläche nach der Ausrichtung aus, die du im Code gewählt hast.

Schritt 2: Screen gestalten

Platziere Ebenen über die Werkzeugleiste, ordne sie im Bereich Ebenen und bearbeite Werte im Inspektor. Ebenen werden in Listenreihenfolge gezeichnet, eine spätere Ebene übermalt also eine frühere – genau so, wie die generierten Aufrufe ablaufen.

Benenne Ebenen vor dem Export um. Aus den Namen werden Code-Kommentare, Namen von Bitmap-Arrays, Namen von Polygon-Hilfsfunktionen, Animations-Header und Variablennamen.

Was jede Ebene erzeugt

Lopaka-Ebene	Generierter TFT_eSPI-Aufruf
Punkt	tft.drawPixel(x, y, color)
Linie	tft.drawLine(x1, y1, x2, y2, color)
Rechteck	tft.drawRect(...) / tft.fillRect(...)
Abgerundetes Rechteck	tft.drawRoundRect(...) / tft.fillRoundRect(...)
Ellipse	tft.drawEllipse(x, y, rx, ry, color) / tft.fillEllipse(...)
Dreieck	tft.drawTriangle(...) / tft.fillTriangle(...)
Bogen	tft.drawSmoothArc(...) oder tft.drawArc(...)
Polygon	Eine generierte Hilfsfunktion void drawMyShape(void) aus drawLine()-Aufrufen
Text	setTextColor(), setTextSize(), setFreeFont(), drawString()
Malebene / Icon / Bild	tft.drawBitmap(...) (1 Bit) oder tft.pushImage(...) (RGB565)
Animation	Frame-Arrays plus die Hilfsfunktionen updateAnimations() / drawAnimations()

Auf dieser Plattform gibt es kein Werkzeug Kreis – nutze das Werkzeug Ellipse mit gleichen Radien; die Ellipsen-Primitive von TFT_eSPI decken das ab.

Farben

In Lopaka kannst du jede RGB-Farbe wählen; Lopaka packt sie dann in den 16-Bit-RGB565-Wert, den TFT_eSPI erwartet, aus #FF0000 wird also 0xF800. Das sind 5 Bit Rot, 6 Bit Grün und 5 Bit Blau – 65.536 Farben, nicht 16 Millionen. Feine Verläufe zeigen Streifen. Transparente Pixel in einem RGB-Quellbild werden standardmäßig mit dem Screen-Hintergrund verrechnet; aktiviere Transparenz im Inspektor, damit sie über eine 1-Bit-Maske durchsichtig bleiben (siehe Bilder weiter unten).

Text

Textebenen erzeugen drawString(text, x, y), wobei x, y die linke obere Ecke des Textes ist – das Standard-TL_DATUM von TFT_eSPI. Lopaka passt die Y-Koordinate an die Metriken der gewählten Schriftart an, du musst die Grundlinie also nicht von Hand berechnen.

Drei Eigenschaften entsprechen dem Zustand der Bibliothek, und Lopaka erzeugt jeden Aufruf nur dann, wenn er sich von einer Ebene zur nächsten ändert:

• Farbe → setTextColor(fg) oder setTextColor(fg, bg), wenn du eine Hintergrundfarbe für den Text festlegst. Mit Hintergrund überschreibt neu gezeichneter Text seine alten Pixel, statt Spuren zu hinterlassen.
• Größe → setTextSize(n), ein ganzzahliger Pixelfaktor. 2 verdoppelt jedes Pixel, das Ergebnis wirkt also klobig statt glatt.
• Schriftart → setFreeFont(&FreeSans9pt7b) für eine GFX-Schriftart oder setFreeFont(NULL) für die integrierte 5×7-Schrift.

Achtung

Ändert dein eigener Code das Text-Datum (tft.setTextDatum(MC_DATUM)), landet der generierte Text an der falschen Stelle. Setze es mit tft.setTextDatum(TL_DATUM) zurück, bevor du die Lopaka-Funktion aufrufst.

Bögen

Das Werkzeug Bogen gibt es nur auf dieser Plattform. Winkel werden in Grad im Uhrzeigersinn ab 12 Uhr gemessen, eine Anzeige von 30 bis 330 ist also unten offen. Die Option Glatt im Inspektor wählt zwischen den beiden Bibliotheksaufrufen:

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

Beide erwarten eine Hintergrundfarbe, weil kantengeglättete Pixel mit ihr gemischt werden. Stelle den Hintergrund des Bogens auf die Farbe ein, auf der er tatsächlich liegt, sonst bekommen seine Kanten einen Halo. drawSmoothArc() braucht TFT_eSPI 2.4.x oder neuer – aktualisiere die Bibliothek, wenn der Compiler meldet, dass die Funktion nicht definiert ist.

Schritt 3: Generierten Code konfigurieren

Öffne die Code-Einstellungen unter dem Code-Bereich. Diese Plattform hat zwei C++-Vorlagen und diese Schalter:

Syntax wählt das Ziel-Framework. Arduino (C++) ist voreingestellt. ESP-IDF (C++) erzeugt dieselben Zeichenaufrufe für eine ESP-IDF-Komponente: Bild-, Masken- und Animations-Arrays sind einfache static const uint8_t / uint16_t-Arrays ohne PROGMEM, das Animations-Timing nutzt esp_timer_get_time() aus esp_timer.h, und es werden kein setup() / loop() erzeugt – rufe draw{ScreenName}() und drawAnimations() aus deiner eigenen Task-Schleife auf. Heruntergeladene Bild- und Animations-Header folgen der gewählten Vorlage.

Einstellung	Was sie bewirkt
Wrapper-Funktion	Packt den Screen in void draw{ScreenName}(void)
Schriftarten einbinden	Erzeugt #include "FontName.h" für eigene Schriftarten (siehe Schriftarten)
Bilder deklarieren	Erzeugt die Bitmap-Arrays, auf die Bildebenen verweisen
Animations-Hilfsfunktionen	Erzeugt Includes für Animations-Header sowie Hilfsfunktionen für Timing und Zeichnen
Variablen deklarieren	Erzeugt Deklarationen für Ebeneneigenschaften, die du als Variablen markiert hast
Kommentare, Ebenentitel	Fügt über den Aufrufen jeder Ebene einen Kommentar // Layer name ein
Display leeren/füllen	Beginnt den Block mit tft.fillScreen(backgroundColor)

Lass beim ersten Export alles eingeschaltet. Der Button Kopieren kopiert genau das, was der Bereich anzeigt.

Das Objekt muss tft heißen

Jede generierte Zeile beginnt mit tft.. Am einfachsten nennst du dein Display-Objekt im Sketch tft. Auf M5Stack ergänzt du eine Alias-Zeile: M5GFX& tft = M5.Display;

Schritt 4: Schriftarten, Bilder und Animationen

Schriftarten

Die integrierte Adafruit-5×7-Schrift und die Free Fonts (FreeSans, FreeMono, FreeSerif in 9/12/18/24pt, mit fetten und schrägen Varianten) brauchen keine Header-Datei. TFT_eSPI kompiliert die Free Fonts bereits mit ein, wenn LOAD_GFXFF definiert ist (siehe Der Bibliothek dein Display beschreiben), deshalb erzeugt Lopaka für sie kein #include und listet sie nicht unter Code-Einstellungen → Schriftarten auf.

Jede andere Schriftart braucht einen Header: die kleineren Adafruit-Schriftarten (Org_01, Picopixel, Tiny3x3a2pt7b, Petme8x8) und alles, was du hochlädst. Für jede dieser Schriftarten auf dem Screen:

1. Öffne die Code-Einstellungen und suche den Abschnitt Schriftarten.
2. Klicke auf den Download-Button neben der Schriftart, um ihre .h-Datei zu erhalten.
3. Lege diese Datei in denselben Ordner wie deine .ino oder .cpp.
4. Lass Schriftarten einbinden aktiviert, damit die Zeile #include "Picopixel.h" in der Ausgabe bleibt.

Lopaka kann hochgeladene TrueType- (.ttf, .otf, .woff) und BDF-Schriftarten ins GFX-Format umwandeln. Die Importwege beschreibt der Schriftarten-Leitfaden.

Schriftdaten liegen im Flash. Eine 24pt-Schriftart mit vollständigem Zeichensatz kostet zig Kilobyte, setze große Schriften also sparsam ein.

Bilder

Importiere Grafiken mit dem Werkzeug Bild und schneide sie auf ihre endgültige Pixelgröße zu. Was erzeugt wird, hängt vom Farbmodus der Ebene ab:

• Monochrom → ein 1-Bit-PROGMEM-Array, gezeichnet mit tft.drawBitmap(x, y, bits, w, h, color). Eine Farbe, nicht gesetzte Pixel transparent, 1 Bit pro Pixel. Ideal für Icons.
• RGB → ein RGB565-Array uint16_t PROGMEM, gezeichnet mit tft.pushImage(x, y, w, h, pixels). Volle Farbe, 2 Byte pro Pixel. Ein importiertes Bild füllt seine transparenten Pixel mit dem Screen-Hintergrund. Aktiviere im Inspektor Transparenz neben Overlay (die Option erscheint, wenn das Bild transparente Pixel hat), dann erzeugt Lopaka zusätzlich ein 1-Bit-Array image_<Name>_mask und zeichnet mit tft.pushMaskedImage(...), sodass diese Pixel das behalten, was der Screen bereits zeigt.

Code-Einstellungen → Bilder listet jedes Bild als image_<Name>_bits.h oder image_<Name>_pixels.h auf, mit genau denselben Bytes wie das Inline-Array. Aktiviere Bilddateien einbinden, um statt des Arrays #include "<symbol>.h" zu erzeugen und die Pixel im heruntergeladenen Header zu behalten.

Behalte das Flash-Budget im Blick

Ein bildschirmfüllendes RGB-Bild mit 240×320 Pixeln belegt 153.600 Byte – rund 12 % einer Standard-Sketch-Partition des ESP32, für ein einziges Bild. Schneide knapp zu, skaliere herunter und nutze Monochrom für alles, was nur eine Farbe hat.

Wenn Bildfarben falsch erscheinen, Formen aber stimmen, sieh unter Byte-Reihenfolge in der Fehlerbehebung nach.

Der Leitfaden zum Bildimport behandelt Skalieren, Zuschneiden, Dithering und Größenschätzungen.

Animationen

Animationsebenen werden als 1-Bit-Frames exportiert – ein zweifarbiges Daumenkino, kein Video. Jedes Frame wird mit setBitmapColor(foreground, background) und anschließend pushImage() gezeichnet.

Wenn du Animations-Hilfsfunktionen einschaltest, ändert sich die Form der Ausgabe deutlich:

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

Zusammenführen, nicht einfügen

Das generierte setup() und loop() ist nur ein Startgerüst. Dein Sketch hat beide schon. Behalte ein setup() und ein loop(): Übernimm die Includes, die Frame-Arrays, updateAnimations() und die Zeichen-Hilfsfunktionen und rufe dann drawAnimations() aus deiner vorhandenen Schleife auf.

Lade jede unter Code-Einstellungen → Animationen aufgeführte .h-Datei herunter und lege sie neben den Sketch. Den Ablauf im Editor beschreibt Animationen.

Schritt 5: Kopieren und einbinden

Nenne deinen Screen Main, füge eine Textebene und ein Rechteck hinzu und klicke auf Kopieren. Du erhältst etwa Folgendes:

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

In einem vollständigen Sketch:

#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 schreibt direkt auf das Panel, es gibt also keinen Puffer, der übertragen werden müsste – nichts wie den display.display()-Aufruf, den monochrome Bibliotheken brauchen.

M5Stack

M5GFX ist dieselbe API hinter einem anderen Objekt. Eine Alias-Zeile genügt:

#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 konfiguriert das Panel für das jeweilige M5-Board automatisch, User_Setup.h entfällt also komplett. Halte dich für M5.begin() an das offizielle Beispiel deines Boards.

LovyanGFX

LovyanGFX braucht eine LGFX-Klasse, die dein Panel beschreibt (das Repository enthält fertige Konfigurationen für gängige Boards). Nenne die Instanz tft, dann funktioniert der generierte Code unverändert.

Schritt 6: Laufzeitdaten und weitere Screens

Werte dynamisch machen

Statischer Text reicht für ein Mockup, für ein Thermometer ist er nutzlos. Wähle eine Ebene aus, aktiviere im Inspektor den Variablenschalter einer unterstützten Eigenschaft und lass Variablen deklarieren aktiviert. Lopaka ersetzt das Literal durch eine Deklaration, die nach der Ebene benannt ist:

const char* temperature = "21.5 C";

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

Aktualisiere die Variable in deinem Code, rufe drawMain() erneut auf, und der neue Wert erscheint.

Flackern des ganzen Screens vermeiden

Rufst du drawMain() in einer engen Schleife auf, wird alles neu gemalt und es flackert. Gib einem Wert, der sich oft ändert, eine Textebene mit Hintergrundfarbe und zeichne nur den Aufruf dieser Ebene neu – oder zeichne in ein TFT_eSprite und übertrage das Sprite. Sprites sind eine TFT_eSPI-Funktion, die du selbst ergänzt; Lopaka erzeugt sie nicht.

Mehrere Screens

Jeder Lopaka-Screen wird unabhängig exportiert, und sein Titel wird zum Funktionsnamen. Kopiere jeden einzeln hinein, führe doppelte Includes und Bitmap-Arrays zusammen und lass deinen Code entscheiden:

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

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

Vorhandenen Code importieren

Der Code-Bereich hat einen Button Code importieren, der eine .ino-, .c-, .cpp- oder .txt-Datei liest und erkannte tft.*-Aufrufe in bearbeitbare Ebenen umwandelt. Die Funktion ist experimentell und funktioniert am besten mit Code, den Lopaka selbst erzeugt hat – handgeschriebene Sketches mit Schleifen, Variablen und Hilfsfunktionen lassen sich nicht vollständig zurückverwandeln. Importierte Ebenen werden an den aktuellen Screen angehängt.

Was Lopaka übernimmt und was du übernimmst

Lopaka übernimmt	Du übernimmst
Pixel-Layout, Ebenenreihenfolge und Zeichenaufrufe	User_Setup.h, Treiberwahl, Pins und SPI-Frequenz
Packen von RGB → RGB565 für Formen, Text und Bilder	Farbreihenfolge, Invertierung und Offsets des Panels
Bitmap-Arrays, GFX-Font-Header, Animations-Frames	Flash-Budget und die heruntergeladenen .h-Dateien beim Sketch behalten
Berechnung der Text-Grundlinie und Aufrufe für den Schriftzustand	Das Text-Datum, falls dein Code es ändert
Eine benannte Zeichenfunktion pro Screen	Ihr Aufruf, Zeitpunkt des Neuzeichnens, Eingaben und Navigation
Optionale Variablendeklarationen	Diese Variablen mit echten Daten aktualisieren

Kompilieren, hochladen und iterieren

1. Kompiliere vor dem Hochladen und behebe zuerst fehlende Header oder nicht definierte Symbole.
2. Lade hoch und vergleiche das Panel mit der Lopaka-Zeichenfläche.
3. Passe Größe der Zeichenfläche, Drehung oder Ebenenpositionen an und exportiere erneut.
4. Wenn sich das Design ändert, ersetze den ganzen generierten Block. Bearbeite einzelne Zeichenaufrufe nicht von Hand – der nächste Export überschreibt sie.

Markierst du den Block, ist das ganz einfach:

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

Fehlerbehebung

Der Screen ist weiß, schwarz oder leer

Fast immer liegt es an der Bibliothekskonfiguration, nicht am generierten Code.

• Führe ein mitgeliefertes TFT_eSPI-Beispiel erneut aus. Bleibt auch das leer, liegt das Problem in User_Setup.h, der Verdrahtung oder der Stromversorgung.
• Stelle sicher, dass das #define für den richtigen Treiber aktiv ist – und nur dieses eine.
• Prüfe den Backlight-Pin – viele Module brauchen TFT_BL auf High.
• Stelle sicher, dass tft.init() vor deiner Zeichenfunktion läuft.
• Senke SPI_FREQUENCY auf 27000000; lange Jumper-Kabel schaffen keine 40 MHz.

'tft' was not declared in this scope

Der generierte Code ruft tft.* auf. Nenne dein Display-Objekt tft oder ergänze einen Alias wie M5GFX& tft = M5.Display;.

setFreeFont oder drawSmoothArc ist nicht definiert

setFreeFont() braucht #define LOAD_GFXFF in User_Setup.h. drawSmoothArc() braucht TFT_eSPI 2.4.x oder neuer – aktualisiere die Bibliothek über den Library Manager.

Ein Schriftart-Header lässt sich nicht kompilieren

Für eine Free Font (FreeSans9pt7b und Verwandte) gibt es keinen Header zum Hinzufügen: Prüfe, ob LOAD_GFXFF in User_Setup.h definiert ist und ob im Sketch kein #include "FreeSans9pt7b.h" aus einem älteren Export übrig ist. Für jede andere Schriftart lädst du die .h unter Code-Einstellungen → Schriftarten herunter, legst sie neben den Sketch und lässt Schriftarten einbinden aktiviert, damit Dateiname, Include und das Symbol &FontName übereinstimmen.

Die Farben sind überall falsch

Sind Rot und Blau auf dem ganzen Screen vertauscht, liegt es an der Farbreihenfolge des Panels: Probiere TFT_RGB_ORDER TFT_BGR (oder TFT_RGB) in User_Setup.h. Wirkt das Bild invertiert, hilft #define TFT_INVERSION_ON / TFT_INVERSION_OFF. Behebe das in der Setup-Datei – niemals, indem du jede Farbe in deinem Design änderst.

Bildfarben sind falsch, Formen aber nicht

Lopaka schreibt RGB565-Bilddaten mit vertauschten Bytes, nach derselben Konvention wie die meisten Bildkonverter für TFT_eSPI. Weise die Bibliothek an, sie vor dem Übertragen von Bildern zurückzutauschen:

tft.setSwapBytes(true);

Rufe das einmal in setup() nach tft.init() auf. Waren die Bilder vorher korrekt und sind danach kaputt, setze den Wert auf false.

Text steht an der falschen Stelle

Setze das Datum vor der generierten Funktion mit tft.setTextDatum(TL_DATUM) zurück – Lopaka geht vom Standard-Datum oben links aus. Ist stattdessen alles verschoben oder abgeschnitten, passt die Größe der Zeichenfläche nach setRotation() nicht zum Display.

Text hinterlässt beim Aktualisieren Schlieren

drawString() malt nur die Pixel der Glyphen; alte Pixel bleiben stehen. Gib der Textebene in Lopaka eine Hintergrundfarbe, damit setTextColor(fg, bg) erzeugt wird, oder lösche den Bereich vorher mit fillRect().

Das Design ist gedreht, gespiegelt oder um ein paar Pixel verschoben

Richte die Lopaka-Zeichenfläche nach der logischen Größe nach setRotation() aus. Ein konstanter Versatz um ein paar Pixel deutet meist auf die falsche Treibervariante hin – manche Panels haben mehr Controller-RAM als sichtbare Fläche und brauchen ein treiberspezifisches Offset-Define.

Der Sketch passt nicht in den Flash

Meist sind RGB565-Bilder mit 2 Byte pro Pixel schuld. Schneide knapper zu, skaliere herunter, wandle einfarbige Grafiken in Monochrom um und entferne ungenutzte große Schriftarten.

Animationscode kollidiert mit meinem Sketch

Behalte ein setup() und ein loop(). Übernimm die Includes, Frame-Arrays und Hilfsfunktionen aus der generierten Ausgabe, behalte deine eigene Initialisierung und rufe drawAnimations() aus deiner vorhandenen Schleife auf.

FAQ

Konfiguriert Lopaka TFT_eSPI für mich?

Nein. User_Setup.h, Treiberwahl, Pins und SPI-Frequenz liegen ganz bei dir. Lopaka erzeugt Zeichenaufrufe und Assets, die ein funktionierendes, initialisiertes Display-Objekt namens tft voraussetzen.

Funktioniert mein Display mit Lopaka?

Wenn TFT_eSPI, M5GFX oder LovyanGFX es ansteuern kann, ja – Lopaka zielt auf die gemeinsame API, nicht auf eine Liste von Modulen. Prüfe das Modul zuerst mit einem mitgelieferten Beispiel der Bibliothek.

Kann ich Vollfarbbilder exportieren?

Ja – RGB-Bildebenen werden zu RGB565-Arrays, die mit pushImage() gezeichnet werden. Animations-Frames haben immer 1 Bit pro Pixel, egal welche Farben sie im Editor nutzen.

Erzeugt Lopaka Sprites, DMA oder Teil-Neuzeichnungen?

Nein. Lopaka erzeugt direkte Zeichenaufrufe. TFT_eSprite, DMA-Übertragungen und Neuzeichnen nur geänderter Bereiche sind Optimierungen, die du rund um die generierte Funktion ergänzt.

Wo erfahre ich mehr?

• TFT_eSPI-Repository
• Setup-Anleitung für TFT_eSPI
• M5GFX und LovyanGFX
• Plattformübersicht von Lopaka
• Schriftarten-Leitfaden von Lopaka
• Leitfaden zum Bildimport in Lopaka
• Animations-Leitfaden von Lopaka
• Leitfaden zur Code-Generierung in Lopaka