ESP32 CYD mit 1,9 Zoll ST7789: ESP-Klon-Board richtig ansteuern

Wer auf der Suche nach einem günstigen ESP32-Board mit integriertem Display ist, stößt früher oder später auf kleine 1,9-Zoll-Module, die optisch stark an das bekannte ESP32-1732S019 erinnern. Doch Vorsicht: Es gibt davon eine Klon-Variante im Umlauf, die zwar fast identisch aussieht, intern aber erheblich anders aufgebaut ist — und die Händler schweigen darüber meistens.

Was ist dieses Board überhaupt?

Das Original-Board ESP32-1732S019 setzt auf einen ESP32-S3-Mikrocontroller und ist mit einem 1,9-Zoll ST7789-TFT-Display (170 × 320 Pixel, 16 Bit Farbe) ausgestattet. Es gehört zur wachsenden Familie der sogenannten Cheap Yellow Displays (CYD) — eine Bezeichnung aus der Maker-Szene für kompakte ESP32-Boards mit direkt verlötetem Display.

Der hier beschriebene Klon sieht dem Original sehr ähnlich, bestückt das Board aber mit einem klassischen ESP32 (Xtensa LX6, Dual-Core) statt einem ESP32-S3. Das klingt zunächst wie ein kleines Detail, hat aber praktische Konsequenzen: Die Pinbelegung des integrierten Displays weicht vom Original ab und das wird von den meisten Verkäufern auf AliExpress, eBay oder Amazon mit keinem Wort erwähnt.

Das Display selbst bleibt gleich: ST7789-Controller, 170 × 320 Pixel Auflösung, angebunden über SPI.

Warum die falsche Pinbelegung ein Problem ist

Wer das Board kauft und annimmt, es handele sich um ein normales ESP32-1732S019, greift zur naheliegendsten Konfiguration aus GitHub oder einschlägigen Blogs. Die schlägt fehl. Das Display bleibt schwarz, oder es flackert zufällig — ohne klare Fehlermeldung in der IDE.

Der Grund: Der Klon nutzt den HSPI-Bus des ESP32 statt des Standard-VSPI, und einige Steuerpins (DC, CS, RST) sind anders verdrahtet als beim S3-Original. Außerdem hat das Display einen bidirektionalen SDA-Pin, was in der Library-Konfiguration explizit gesetzt werden muss.

Einrichtung mit TFT_eSPI: Die richtige User_Setup.h

Die TFT_eSPI-Library von Bodmer ist die Standardwahl für solche Displays in der Arduino-Welt. Die Konfiguration erfolgt über die Datei User_Setup.h, die sich nach der Installation der Library hier befindet:

• Windows: C:\Users\Username\Documents\Arduino\libraries\TFT_eSPI\User_Setup.h
• Mac: /Users/Username/Documents/Arduino/libraries/TFT_eSPI/User_Setup.h

Für den ESP32-CYD-Klon mit 1,9-Zoll ST7789 musst du die Datei wie folgt anpassen (alle anderen #define-Einträge für alternative Treiber sollten auskommentiert sein):

#define ST7789_DRIVER
#define TFT_SDA_READ   // Display has a bidirectional SDA pin

#define TFT_WIDTH  170
#define TFT_HEIGHT 320

#define CGRAM_OFFSET      // Library will add offsets required

//#define TFT_BL    21  // Display backlight control pin
//#define TFT_BACKLIGHT_ON HIGH  // HIGH or LOW are options

// The ESP32 has 2 free SPI ports i.e. VSPI and HSPI, the VSPI is the default.
// If the VSPI port is in use and pins are not accessible (e.g. TTGO T-Beam)
// then uncomment the following line:
#define USE_HSPI_PORT

// #define TFT_MISO 12 // don't define this pin when using Touch and SD Card on the CYD
#define TFT_MOSI 13
#define TFT_SCLK 14
#define TFT_CS   15  // Chip select control pin
#define TFT_DC    2  // Data Command control pin
#define TFT_RST  -1  // Set TFT_RST to -1 if display RESET is connected to ESP32 board RST

#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_FREQUENCY  40000000
#define SPI_FREQUENCY  80000000

#define SPI_READ_FREQUENCY  6000000 // 6 MHz is the maximum SPI read speed for the ST7789V

Was bedeuten die kritischen Einträge?

Hinterleuchung per PWM steuern

Das Backlight des Displays hängt an GPIO 21 und lässt sich über PWM dimmen. Das TFT_BL-Define wird in der User_Setup.h absichtlich auskommentiert gelassen — die Helligkeitssteuerung übernimmt der Sketch selbst. Das hat den Vorteil, dass du die Helligkeit zur Laufzeit flexibel regeln kannst, ohne die Library-Konfiguration anfassen zu müssen.

Für neue ESP32-Arduino-Core-Versionen (ab 3.0.0) hat Espressif die ledcWrite-API leicht verändert: ledcSetup() und ledcAttachPin() wurden zu einem einzigen ledcAttach()-Aufruf zusammengeführt. Der Hello-World-Sketch unten behandelt beide Varianten über eine Versionsprüfung zur Compile-Zeit.

Hello World: Funktionst mit Farbwechsel und PWM

Das folgende Programm testet alle wesentlichen Funktionen auf einmal: Display-Initialisierung, Farbe, Text und Helligkeitssteuerung. Es wechselt alle 1,5 Sekunden zwischen roten, grünen und blauen Vollbildschirmen mit weißem Text, abschließend folgt ein Regenbogenstreifen-Muster.

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

TFT_eSPI tft = TFT_eSPI();

// Backlight Pin Definition
#define TFT_BL 21

// PWM Einstellungen
#define PWM_FREQ    5000
#define PWM_RES     13     // 13-Bit Auflösung (0 - 8191)
#define PWM_CHANNEL 0      

/**
 * Hilfsfunktion zur Steuerung der Helligkeit
 */
void setBrightness(int percentage) {
  percentage = constrain(percentage, 0, 100);
  int dutyCycle = map(percentage, 0, 100, 0, 8191);

  #if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
    ledcWrite(TFT_BL, dutyCycle);
  #else
    ledcWrite(PWM_CHANNEL, dutyCycle);
  #endif
}

void setup() {
  // PWM Initialisierung
  #if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
    ledcAttach(TFT_BL, PWM_FREQ, PWM_RES);
  #else
    ledcSetup(PWM_CHANNEL, PWM_FREQ, PWM_RES);
    ledcAttachPin(TFT_BL, PWM_CHANNEL);
  #endif

  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);

  // Helligkeit auf 10% festlegen
  setBrightness(10);
}

void loop() {
  // Rot
  tft.fillScreen(TFT_RED);
  tft.setTextColor(TFT_WHITE, TFT_RED);
  tft.setTextSize(3);
  tft.setCursor(60, 70);
  tft.println("Hello");
  tft.setCursor(60, 110);
  tft.println("10% Bright");
  delay(1500);

  // Grün
  tft.fillScreen(TFT_GREEN);
  tft.setTextColor(TFT_BLACK, TFT_GREEN);
  tft.setTextSize(3);
  tft.setCursor(60, 70);
  tft.println("Hello");
  tft.setCursor(60, 110);
  tft.println("10% Bright");
  delay(1500);

  // Blau
  tft.fillScreen(TFT_BLUE);
  tft.setTextColor(TFT_YELLOW, TFT_BLUE);
  tft.setTextSize(3);
  tft.setCursor(60, 70);
  tft.println("Hello");
  tft.setCursor(60, 110);
  tft.println("10% Bright");
  delay(1500);
	
  // Regenbogen-Streifen
  int colors[] = {TFT_RED, TFT_ORANGE, TFT_YELLOW, TFT_GREEN, TFT_BLUE, TFT_PURPLE};
  int numColors = 6;
  int stripeHeight = tft.height() / numColors;

  for (int i = 0; i < numColors; i++) {
    tft.fillRect(0, i * stripeHeight, tft.width(), stripeHeight, colors[i]);
  }

  tft.setTextColor(TFT_WHITE);
  tft.setTextSize(3);
  tft.setCursor(55, 60);
  tft.println("Constant");
  tft.setCursor(55, 100);
  tft.println("Brightness");
  delay(2000);
}

Nach dem Flashen sollte das Display sofort mit dem ersten roten Bildschirm anlaufen. Bleibt das Display dunkel, ist die Helligkeit mit setBrightness(10) zunächst auf 10% gedrosselt — das ist Absicht, um das Display nachts nicht als Scheinwerfer zu nutzen. Für erste Tests einfach auf setBrightness(80) erhöhen.

Typische Fehler und ihre Ursachen

Display bleibt schwarz: Häufigste Ursache ist das fehlende #define USE_HSPI_PORT. Ohne dieses Makro greift TFT_eSPI auf den VSPI-Bus zu, an dem bei diesem Board das Display nicht hängt.

Farben sind invertiert oder verrauscht: Das CGRAM_OFFSET-Define fehlt, oder der ST7789-Treiber ist nicht als einziger aktiver Treiber eingetragen. Alle anderen Treiber-Defines (ILI9341, ILI9486 etc.) müssen auskommentiert sein.

Sketch kompiliert, aber PWM funktioniert nicht: Ab ESP32-Arduino-Core 3.0.0 hat sich die LEDC-API geändert. Der Sketch oben berücksichtigt beide Versionen per #if ESP_ARDUINO_VERSION-Abfrage — das erfordert allerdings, dass der Core korrekt installiert ist (Boardverwalter: "esp32 by Espressif Systems").

Upload-Probleme: Verwendet die folgenden Einstellungen in der Arduino IDE falls ihr Probleme beim Upload haben solltet. Wählt als Board "ESP32 Dev Module" aus und verwendet bei Flash Size die Option "4MB (32 MB)" sowie einen Upload-Speed von "115200":

Einsatzmöglichkeiten

Das Board eignet sich trotz der kleinen Displaygröße gut für kompakte Anwendungsfälle:

• Sensor-Dashboards (Temperatur, Luftfeuchtigkeit, CO2)
• IoT-Statusanzeigen für Smart-Home-Systeme (z. B. Home Assistant via MQTT)
• Energiemonitor für Balkonkraftwerke oder Stromzähler
• Standalone-Anzeigen ohne Netzverbindung (z. B. Uhr, Stoppuhr, Spielereien)

Durch die vielen freien GPIO-Pins gegenüber dem vollausgestatteten CYD (ESP32-2432S028) lassen sich problemlos I2C-Sensoren, UART-Module oder Servos direkt anschließen, ohne auf Port-Expander angewiesen zu sein.

Fazit

Der ESP32-CYD-Klon mit 1,9-Zoll ST7789 ist ein nützliches kleines Board — aber nur, wenn man weiß, womit man es wirklich zu tun hat. Die abweichende Pinbelegung gegenüber dem ESP32-S3-Original und das Fehlen jeglicher Dokumentation seitens der Händler machen den Einstieg unnötig schwer. Mit der korrekten User_Setup.h (insbesondere USE_HSPI_PORT und TFT_SDA_READ) und dem obigen Beispiel-Sketch läuft das Display jedoch zuverlässig und liefert durch die 80-MHz-SPI-Taktrate eine flüssige Darstellung.