In diesem Tutorial lernst du, wie du die TFT_eSPI Library innerhalb der Arduino IDE zur Steuerung von TFT-Displays konfigurierst. Ich zeige dir mehrere Beispiele für verschiedene TFT-Displays.

Die TFT_eSPI-Bibliothek vereinfacht die Ansteuerung von TFT-Displays. Sie bietet eine einfache API zum Zeichnen von Formen, Anzeigen von Text und Verarbeiten von Touch-Eingaben.

Die Bibliothek ist für 32-Bit-Prozessoren ausgelegt und wurde für RP2040, STM32, ESP8266 und ESP32 performance-optimiert. Sie funktioniert auch mit Arduino-Boards, ist dort aber langsamer.

Außerdem unterstützt sie eine Vielzahl von TFT-Display-Controllern, darunter ILI9341, ST7735, ST7789, ST7796 und weitere. Für eine vollständige Liste und mehr Informationen siehe die Readme of the TFT_eSPI Library.

überblick

Installation der TFT_eSPI-Bibliothek

Um die TFT_eSPI library zu installieren, öffne den Library Manager, suche nach „TFT_eSPI“ und klicke auf „INSTALL“. Nach der Installation sollte es so aussehen:

TFT_eSPI library in Library Manager — TFT_eSPI-Bibliothek im Library Manager

Einrichten der TFT_eSPI-Bibliothek über User_Setup.h

Bevor du die TFT_eSPI Library verwenden kannst, musst du sie speziell für das TFT-Display konfigurieren, auf dem du zeichnen möchtest. Das umfasst den Treiber-IC des Displays, die Schnittstellenpins und Eigenschaften wie Abmessungen oder die Reihenfolge der RGB-Kanäle.

Diese Konfigurationsparameter werden in einer Datei namens User_Setup.h gespeichert, die Teil des TFT_eSPI-Bibliotheksordners ist. Typischerweise befindet sie sich unter Windows in einem Pfad ähnlich dem folgenden

C:\Users\stefa\OneDrive\Documents\Arduino\libraries\TFT_eSPI

Der genaue Pfad hängt von deinem Benutzernamen (bei mir „stefa„) sowie deinem Betriebssystem und der Nutzung von OneDrive ab. Du musst danach suchen, aber sie liegt dort, wo alle deine Arduino-Bibliotheken gespeichert sind.

Wenn du die User_Setup.h Datei öffnest, siehst du viele Parameter, die korrekt gesetzt werden müssen, damit ein bestimmtes TFT-Display funktioniert:

Du kannst diese Datei bearbeiten, aber jede Änderung wirkt sich auf alle deine Arduino-Projekte aus, die die TFT_eSPI-Bibliothek verwenden, da die Bibliothek und User_Setup.h projektübergreifend geteilt werden. Außerdem werden deine Änderungen an User_Setup.h bei einer Neuinstallation der TFT_eSPI-Bibliothek überschrieben.

Stattdessen empfehle ich, eine Datei namens tft_setup.h zu erstellen, die lokal für ein Projekt ist und nur dieses Projekt beeinflusst. Wie das geht, ist Thema des nächsten Abschnitts.

Einrichten der TFT_eSPI-Bibliothek über tft_setup.h

Jede Änderung an User_Setup.h wirkt sich auf alle Projekte aus. Wenn das Projekt jedoch eine Datei mit dem Namen tft_setup.h enthält, werden die Einstellungen in User_Setup.h ignoriert.

Die tft_setup.h Datei enthält im Wesentlichen die gleichen Einstellungen, User_Setup.h ist nur für das spezifische Projekt gültig. Das bedeutet, du kannst verschiedene Projekte mit unterschiedlichen Displays haben, ohne User_Setup.h bei jedem Displaywechsel ändern zu müssen.

Projektstruktur

Hier ein Beispiel, wie du die erforderliche Projektstruktur erstellst. Erstelle zuerst ein neues Arduino-Projekt und speichere es z.B. als „tft_test„. Dadurch wird ein Ordner tft_test mit einer Datei tft_test.ino darin erstellt:

Arduino Project Folder tft_test — Arduino-Projektordner tft_test

Erstelle in diesem Ordner nun eine Datei namens „tft_setup.h“ – genau mit diesem Namen! Dein Projektordner sollte dann so aussehen:

In deiner Arduino IDE solltest du jetzt zwei Tabs sehen; tft_test.ino und tft_setup.h, auf die du klicken kannst, um die Dateien zu bearbeiten.

Arduino IDE with tft_test.ino and tft_setup.h tabs — Arduino IDE mit `tft_test.ino and tft_setup.h` Tabs

Beispiel-Einstellungen

In der Datei tft_setup.h kopierst du (z.B. aus User_Setup.h oder aus einem Tutorial) alle display-spezifischen Einstellungen. Unten ist die Einstellungsdatei für ein 1.8″ ST7735 TFT Display als Beispiel:

// tft_setup.h
#define ST7735_DRIVER
#define ST7735_BLACKTAB
   
#define TFT_WIDTH  128
#define TFT_HEIGHT 160

#define TFT_RGB_ORDER TFT_RGB  

// pins
#define TFT_CS    5   
#define TFT_RST   16  
#define TFT_DC    17   
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCLK
#define TFT_MISO  19  // not used
#define TFT_BL    22   // LED back-light
#define TFT_BACKLIGHT_ON HIGH

// fonts
#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

// SPI
#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

Die wichtigste Einstellung ist der Display-Treiber (ST7735_DRIVER), die Abmessungen des Displays (320×240) und die Pins, an die das Display angeschlossen ist.

Manchmal gibt es Treibervarianten, die über spezielle Flags gesetzt werden können (z.B. ST7735_BLACKTAB). Ebenso kann die Reihenfolge der RGB-Kanäle zwischen Displays variieren, was du ebenfalls angeben kannst (TFT_RGB_ORDER TFT_RGB).

Die SPI-FrequenzEinstellungen unterscheiden sich meist nicht stark zwischen Displays, aber wenn du Störmuster oder andere Verzerrungen siehst, kannst du versuchen, die SPI_FREQUENCY zu verringern. Höhere Frequenzen machen das Display schneller, damit kannst du experimentieren.

Unten ein Beispiel für Verzerrungen, die auftreten können, wenn die SPI-Frequenz zu hoch ist. Der erste Text wurde mit einer SPI_FREQUENCY von 27000000 ausgegeben, der zweite mit 40000000. Die Verzerrungen im zweiten Text sind deutlich sichtbar.

TFT text output with different SPI frequencies — Textausgabe mit unterschiedlichen SPI-Frequenzen

Normalerweise musst du die Liste der Schriftarten nicht ändern, aber wenn der Speicher knapp wird, kannst du nicht genutzte Fonts entfernen.

Viele vorhandene Einstellungen für verschiedene Kombinationen von Mikroprozessoren und Display-Treibern findest du im UserSetups Ordner der TFT_eSPI-Bibliothek. Für eine Übersicht aller Einstellungen schau dir die User_Setup.h Datei an.

Hardware SPI Pins finden

Die Geschwindigkeit, mit der der TFT-Bildschirm anzeigen kann, hängt stark davon ab, wie schnell die Daten vom Mikroprozessor zum Display übertragen werden. Meist kommunizieren Mikroprozessor und Display über SPI (Serial Peripheral Interface), es gibt aber auch eine parallele Schnittstelle.

Mikroprozessoren wie Arduino, ESP8266 oder ESP32 unterstützen Hardware SPI, das schneller ist als Software SPI. Siehe ein Geschwindigkeitsvergleichsvideo hier.

Hardware SPI erfordert jedoch, dass du das TFT-Display an die richtigen Pins anschließt. Diese Pins unterscheiden sich je nach Mikroprozessor. Du findest sie aber leicht, indem du dein Board in der Arduino IDE auswählst und dann den folgenden Code ausführst.

void setup() {
  Serial.begin(115200);
  Serial.print("MOSI: ");
  Serial.println(SDA / MOSI);
  Serial.print("MISO: ");
  Serial.println(MISO);
  Serial.print("SCL / SCLK: ");
  Serial.println(SCK);
  Serial.print("CS / SS: ");
  Serial.println(SS);  
}

void loop() { }

Er gibt die Pins aus, die du für Hardware SPI brauchst – speziell MOSI und SCLK. Die übrigen Pins wie TFT_CS, TFT_BL, TFT_DC kannst du frei wählen, und MISO wird typischerweise nicht verwendet.

Logikpegel

Zum Schluss eine Warnung zu Logic Levels. TFT-Displays arbeiten typischerweise mit 3,3V CMOS-Logik, und du kannst die SPI-Leitungen direkt an einen Mikroprozessor anschließen, der ebenfalls 3,3V CMOS-Logik verwendet, z.B. den ESP32.

Arduino-Boards hingegen arbeiten mit 5V TTL-Logik und du darfst ihre GPIO-Pins nicht direkt an ein TFT-Display anschließen, das 3,3V CMOS-Logik verwendet. Du benötigst einen Spannungsteiler oder besser einen Logic level converter.

Manche TFT-Displays haben einen solchen Logikpegelwandler eingebaut, aber wenn das im Datenblatt oder in der Produktbeschreibung nicht ausdrücklich steht, kannst du dir nicht sicher sein. Wenn das Display mit 5V läuft, kann es einen Wandler haben oder auch nicht. Läuft es mit 3,3V, hat es höchstwahrscheinlich keinen.

Wenn dein Display also mit einem Arduino nicht richtig funktioniert (leerer Bildschirm, Störmuster, Flackern, …), brauchst du möglicherweise einen Logikpegelwandler.

Anschlussbeispiel für 1,8″ TFT mit ST7735-Treiber

In diesem Abschnitt zeige ich dir ein Anschlussbeispiel. Wir verbinden ein 1.8″ TFT Display mit einem ST7735S Treiber an einen WEMOS Lolin32 lite. Die komplette Verkabelung siehst du im Bild unten:

Connecting TFT ST7735 Display with WEMOS Lolin ESP32 lite — Anschluss TFT ST7735 Display mit WEMOS Lolin ESP32 lite

Und hier zur Übersicht die Verkabelung nochmal als Tabelle:

Display	ESP32
CS / SS	5
RST	16
DC	17
SDA / MOSI	23
SCL / SCLK	18
BKL/BL	22
GND	GND
VCC	3,3V

Das TFT-Display in diesem Beispiel ist ein 3,3V-Display ohne Logikpegelwandler. Du musst daher VCC des Displays an 3,3V anschließen und kannst es nicht direkt an einen Arduino Uno anschließen.

Codebeispiel für 1,8″ TFT mit ST7735-Treiber

In diesem Abschnitt betrachten wir ein kleines Codebeispiel, das die TFT_eSPI-Bibliothek verwendet. Es ist nützlich, um zu testen, ob die Einstellungen in der tft_setup.h Datei korrekt sind.

Kopiere den folgenden Code in die Datei tft_test.ino. Dieser Code zeigt ein grünes Quadrat, einen roten Kreis, ein blaues Dreieck und den Text „Makerguides“.

// tft_test.ino
#include "tft_setup.h"
#include"TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();

const int cw = tft.width()/2;
const int ch = tft.height()/2;
const int s = min(cw/3,ch/3);

void setup(void) {  
  tft.init();
  tft.fillScreen(TFT_BLACK);  
  tft.setRotation(1);

  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", ch, cw+s);

  tft.fillCircle(ch, cw/2+s/2, s/2, TFT_RED);
  tft.fillRect(1.5*ch-s, cw/2, s, s, TFT_GREEN);
  tft.fillTriangle(ch/2, cw/2, ch/2+s, cw/2, ch/2, cw/2+s, TFT_BLUE);
}

void loop() { }

Beachte, dass tft_setup.h am Anfang des Programms eingebunden ist. Der Code selbst ist leicht verständlich. Wir erstellen ein TFT_eSPI Objekt und Konstanten für das Zentrum (cw, ch) sowie die Größe s der zu zeichnenden Objekte.

In der setup Funktion initialisieren wir den TFT-Bildschirm, füllen ihn schwarz und drehen ihn in den Hochformatmodus.

Dann setzen wir Schriftart, Größe, Farbe und Ausrichtung und schreiben den Text „Makerguides“ auf den Bildschirm. In den nächsten drei Zeilen zeichnen wir den roten Kreis, das grüne Quadrat und das blaue Dreieck. Die Ausgabe auf deinem TFT-Display sollte ähnlich aussehen:

Output of test code on TFT — Ausgabe des Testcodes auf TFT

Wenn nicht, stimmt etwas mit den Einstellungen in tft_test.ino oder der Verkabelung des TFT-Displays nicht.

Anschlussbeispiel für 1,3″ TFT ST7789 Display

Im nächsten Beispiel zeige ich dir, wie du das verbreitete 1.3″ ST7789 TFT Display an einen WEMOS Lolin32 lite (ESP32) anschließt:

Connecting TFT ST7789 Display with WEMOS Lolin ESP32 lite — Anschluss TFT ST7789 Display mit WEMOS Lolin ESP32 lite

Und hier nochmal die erforderlichen Verbindungen als Tabelle. Beachte, dass dieses Display-Modul keinen Chip Select (CS) hat und daher kein Pin dafür benötigt wird.

Display	ESP32
RST	16
DC	17
SDA / MOSI	23
SCL / SCLK	18
BKL/BL	22
GND	GND
VCC	3,3V

Achte darauf, VCC des Displays an 3,3V anzuschließen! Es ist nicht kompatibel mit 5V und kann nicht direkt mit einem Arduino UNO verwendet werden. Außerdem solltest du die Hardware SPI Pins verwenden. Je nach Mikrocontroller unterscheiden sich die Hardware SPI Pins.

Codebeispiel für 1,3″ TFT ST7789 Display

Hier ist die Konfiguration und der Code für das 1.3″ ST7789 TFT Display. Kopiere die folgende Konfiguration in die tft_setup.h Datei.

// 1.3" TFT Display (GMT130 V.10), 
// no CS pin
// 240x240, ST7789
// tft_setup.h
#define ST7789_DRIVER

#define TFT_WIDTH  240
#define TFT_HEIGHT 240

#define TFT_RGB_ORDER TFT_BGR

#define TFT_CS    -1   
#define TFT_RST   16  
#define TFT_DC    17  
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCL
#define TFT_MISO  19  // not used
#define TFT_BL    22  // LED back-light
#define TFT_BACKLIGHT_ON HIGH


#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

Und der Testcode für den Sketch kommt in die tft_test.ino Datei:

// tft_test.ino
#include "tft_setup.h"
#include"TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();

const int cw = tft.width()/2;
const int ch = tft.height()/2;
const int s = min(cw/4,ch/4);

void setup(void) {  
  tft.init();
  tft.fillScreen(TFT_BLACK);  
  tft.setRotation(1);

  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", ch, cw+s);

  tft.fillCircle(ch, cw/2+s/2, s/2, TFT_RED);
  tft.fillRect(1.5*ch-s, cw/2, s, s, TFT_GREEN);
  tft.fillTriangle(ch/2, cw/2, ch/2+s, cw/2, ch/2, cw/2+s, TFT_BLUE);
}

void loop() { }

Du solltest folgende Ausgabe auf deinem Display sehen:

Anschlussbeispiel für 2,8″ TFT ILI9341 Touch Display

Im letzten Beispiel zeige ich dir, wie du ein 2.8″ TFT ILI9341 Touch Display an einen WEMOS Lolin32 lite (ESP32) anschließt:

Connecting the TFT ILI9341 Touch Display to ESP32 — Anschluss des TFT ILI9341 Touch Displays an ESP32

Es gibt einige Verbindungen herzustellen, und die folgende Tabelle sollte helfen. Beachte, dass die SDI(MOSI) und SCK Leitungen der SPI-Schnittstelle zwischen Touch- und TFT-Display-Controller geteilt werden:

ESP32	TFT	Touch
5	CS	–
4	–	T_CS
17	RESET	–
16	DC	–
23	SDI(MOSI)	T_DIN
18	SCK	T_CLK
19	–	T_DO
22	LED	–

Du könntest Pin 19 des ESP32 auch an SDO(MISO) anschließen, aber wir brauchen ihn nicht, und es gibt Berichte, dass das in manchen Fällen Probleme verursacht. Ich habe nicht Pin 19 an SDO(MISO) angeschlossen, und das Display funktionierte einwandfrei.

Codebeispiel für 2,8″ TFT ILI9341 Touch Display

Hier ist die Konfiguration und der Code für das 2.8″ TFT ILI9341 Touch Display. Kopiere die folgende Konfiguration in die tft_setup.h Datei.

// tft_setup.h
// 2.8" TFT Touch Display
// 240x 320, Driver: ILI9341 

#define ILI9341_DRIVER      
//#define ILI9341_2_DRIVER  

#define TFT_WIDTH  240
#define TFT_HEIGHT 320
#define TFT_RGB_ORDER TFT_BGR  

// WEMOLS Lolin32 lite
#define TFT_CS    5   
#define TFT_RST   17  
#define TFT_DC    16   
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCLK
#define TFT_MISO  19  // HW MISO
#define TFT_BL    22  // LED back-light
#define TFT_BACKLIGHT_ON HIGH

#define TOUCH_CS 4 
#define TOUCH_CLK TFT_SCLK
#define TOUCH_DIN TFT_MOSI
#define TOUCH_DO TFT_MISO

#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

Und hier etwas Testcode für das Display, der in die tft_test.ino Datei kommt:

// tft_test.ino
#include "tft_setup.h"
#include "TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();
uint16_t cal[5] = { 0, 0, 0, 0, 0 };

void calibrate_touch() {
  if (!cal[1]) {
    tft.fillScreen(TFT_BLACK);
    tft.calibrateTouch(cal, TFT_YELLOW, TFT_BLACK, 20);
    Serial.printf("cal[5] = {%d, %d, %d, %d, %d};\n",
                  cal[0], cal[1], cal[2], cal[3], cal[4]);
  }
}

void setup(void) {
  Serial.begin(115200);

  tft.init();
  tft.setRotation(1);
  calibrate_touch();
  tft.setTouch(cal);

  tft.fillScreen(TFT_BLACK);
  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", TFT_HEIGHT / 2, TFT_WIDTH / 2);
}

void loop() {
  uint16_t x, y;
  if (tft.getTouch(&x, &y)) {
    Serial.printf("%d %d\n", x, y);
    tft.fillCircle(x, y, 2, TFT_YELLOW);
  }
}

Dieser Code ermöglicht es dir, den Touchscreen zu kalibrieren und Berührungen auf dem Display zu erkennen:

Touch input on TFT ILI9341 Touch Display — Touch-Eingabe auf TFT ILI9341 Touch Display

Für detailliertere Informationen siehe das Interface TFT ILI9341 Touch Display with ESP32 Tutorial.

Fazit

In diesem Tutorial hast du gelernt, wie du die TFT_eSPI Library innerhalb der Arduino IDE zur Steuerung von TFT-Displays konfigurierst.

Die TFT_eSPI Library ist sehr vielseitig und unterstützt viele verschiedene TFT-Displays. Die richtigen Einstellungen für ein neues TFT-Display zu finden, kann jedoch schwierig sein.

Beginne damit, den Treiber-IC des Displays zu identifizieren. Häufige Treiber sind ST7735, ST7789, ST7796 und ILI9341. Suche nach diesen Namen in der Produktbeschreibung, dem Datenblatt und auf der Platine des Displays.

Finde als Nächstes die Auflösung (Breite, Höhe) des Displays in Pixeln heraus, z.B. 128×160. Diese Information findest du ebenfalls in der Produktbeschreibung, dem Datenblatt oder auf der Platine.

Verdrahte dann das Display mit deinem Mikrocontroller. Wenn es einen Backlight-Pin gibt, stelle sicher, dass er mit 3,3V (oder 5V, je nach Display) verbunden ist. Wenn du nicht sicher bist, ob das Display 5V-kompatibel ist, verwende keinen Arduino, sondern einen ESP32 mit 3,3V. Sonst könntest du den Display-Treiber-IC zerstören.

Lade schließlich den Testcode hoch und schau, was passiert. Es gibt einige häufige Szenarien:

Schwarzer Bildschirm: Prüfe den Backlight-Pin und setze #define TFT_BACKLIGHT_ON HIGH
Falsche Farben: Versuche #define TFT_RGB_ORDER TFT_RGB oder TFT_BGR
Schwarz & Weiß sind vertauscht: #define TFT_INVERSION_ON or TFT_INVERSION_OFF
Text des Testcodes ist nicht zentriert oder abgeschnitten: Display-Abmessungen sind falsch.
Setze TFT_HEIGHT und TFT_WIDTH korrekt.
Störmuster, Verzerrungen oder Flackern: SPI_FREQUENCY ist zu hoch
Fehlende Pins: Wenn es keinen Pin für Reset (RST), Chip Select (CS) oder Backlight (BL) am Display gibt, setze die entsprechenden Konstanten auf -1, z.B. #define TFT_RST -1

Wenn du Kommentare hast, kannst du sie gerne im Kommentarbereich hinterlassen.

Viel Spaß beim Tüfteln ; )

Stefan Maetschke