Das ultimative CYD-Display-Problem: Wenn das Display nur drei Viertel anzeigt

Autor: DerSchneider

Einleitung: Ein gelbes Display, das mich zur Verzweiflung brachte

Es ist ein bekanntes Bild in den Entwicklerforen: Ein glücklicher Bastler hat sein neues „Cheap Yellow Display“ (CYD) ausgepackt, den ESP32-2432S028R an den USB-Port angeschlossen, die TFT_eSPI-Bibliothek installiert – und dann die Ernüchterung. Das Display zeigt zwar etwas an, aber nur die oberen drei Viertel. Das untere Viertel bleibt schwarz. Die Farben sind falsch, die Hoffnung schwindet.

Ich habe genau dieses Problem durchgemacht. Nach Tagen des Herumprobierens, unzähligen Kompilierungsfehlern und viel Frust möchte ich meine Lösung teilen. Dieser Artikel ist eine praktische Anleitung für alle, die mit genau diesem Problem kämpfen – kein technikhistorischer Rückblick, sondern eine handfeste Problemlösung.

Das Problem im Detail: Was passiert da eigentlich?

Bevor wir zur Lösung kommen, ein kurzer Blick auf das Problem selbst. Du hast eines dieser Boards:

Du lädst ein Beispiel hoch, aber das Display zeigt nur die oberen 240 Pixel von 320 Pixeln. Der untere Bereich bleibt schwarz. Das nennt sich das „drei-viertel-Problem“. Zusätzlich sind die Farben falsch – rot wird blau, blau wird rot.

Die Ursache: Die Bibliothek erkennt dein Board nicht korrekt. Sie denkt, das Display wäre kleiner, als es tatsächlich ist.

Warum die „Standard“-Lösung nicht funktioniert

Die meisten Online-Anleitungen und die offizielle Dokumentation der TFT_eSPI-Bibliothek empfehlen diese Einstellung:

cpp

#define ILI9341_DRIVER
#define TFT_WIDTH  240
#define TFT_HEIGHT 320

Diese Einstellung funktioniert für dein V3-Board nicht. Sie führt genau zu dem beschriebenen Problem. Der Grund liegt in der Revision deines Boards. Es gibt mehrere Versionen des CYD:

Dein V3-Board benötigt einen anderen Treiber und eine zusätzliche Inversion.

Die Lösung: Schritt-für-Schritt zur korrekten Konfiguration

Schritt 1: Die richtige User_Setup.h erstellen

Öffne die Datei User_Setup.h im TFT_eSPI-Bibliotheksordner. Bei Arduino IDE findest du sie unter:

text

C:\Users\DEIN_BENUTZER\Documents\Arduino\libraries\TFT_eSPI\User_Setup.h

Ersetze den gesamten Inhalt mit folgendem Code:

cpp

// ===================================================================
// KORREKTE User_Setup.h für ESP32-2432S028R V3 (USB-C Version)
// ===================================================================

// Für V3 (USB-C) MUSS ILI9341_2_DRIVER verwendet werden!
#define ILI9341_2_DRIVER

// NICHT verwenden für V3:
// #define ILI9341_DRIVER     // Führt zum 3/4-Problem!

// Display-Größe (240x320 Pixel)
#define TFT_WIDTH  240
#define TFT_HEIGHT 320

// Für V3 zwingend erforderlich (sonst sind Farben invertiert!)
#define TFT_INVERSION_ON

// GPIO-Pins für Display
#define TFT_MISO  12
#define TFT_MOSI  13
#define TFT_SCLK  14
#define TFT_CS    15
#define TFT_DC    2
#define TFT_RST   -1      // -1 = nicht verwendet (geteilt mit roter LED!)
#define TFT_BL    21

// Backlight: HIGH = an
#define TFT_BACKLIGHT_ON HIGH

// Touch (XPT2046) - für spätere Projekte
#define TOUCH_CS  33

// SPI-Geschwindigkeiten (27MHz ist stabiler als 40MHz!)
#define SPI_FREQUENCY       27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

// Farb-Reihenfolge (RGB ist korrekt bei V3)
#define TFT_RGB_ORDER TFT_RGB

// Schriftarten laden
#define LOAD_GLCD
#define LOAD_FONT2
#define LOAD_FONT4
#define LOAD_FONT6
#define LOAD_FONT7
#define LOAD_FONT8
#define LOAD_GFXFF
#define SMOOTH_FONT

Schritt 2: User_Setup_Select.h prüfen

Öffne die Datei User_Setup_Select.h im selben Ordner. Stelle sicher, dass NUR diese Zeile aktiv ist:

cpp

#include <User_Setup.h>   // <- DAS MUSS AKTIV SEIN!

Alle anderen Zeilen (wie #include <User_Setups/Setup0_ILI9341_ESP32.h>) müssen auskommentiert sein (mit // am Anfang).

Schritt 3: Backlight einschalten (nicht vergessen!)

Viele vergessen diesen wichtigen Punkt: Die Backlight (Hintergrundbeleuchtung) muss explizit eingeschaltet werden. Füge in deinem Sketch hinzu:

cpp

pinMode(21, OUTPUT);      // GPIO21 = TFT_BL
digitalWrite(21, HIGH);   // Backlight EIN

Schritt 4: Den Test-Sketch hochladen

Jetzt kommt der Moment der Wahrheit. Lade folgenden Sketch auf dein Board:

cpp

#include <Arduino.h>
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  Serial.begin(115200);
  
  // Backlight einschalten (WICHTIG!)
  pinMode(21, OUTPUT);
  digitalWrite(21, HIGH);
  
  // Display initialisieren
  tft.init();
  tft.setRotation(1);  // 1 = Querformat (USB rechts/links)
  
  // Farbtest
  tft.fillScreen(TFT_RED);
  delay(1000);
  tft.fillScreen(TFT_GREEN);
  delay(1000);
  tft.fillScreen(TFT_BLUE);
  delay(1000);
  tft.fillScreen(TFT_WHITE);
  delay(1000);
  tft.fillScreen(TFT_BLACK);
  
  // Textausgabe
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextSize(2);
  tft.drawString("CYD V3 OK!", 80, 100);
  
  Serial.println("Display funktioniert!");
}

void loop() {}

Was du nach der Korrektur sehen solltest

Die häufigsten Stolpersteine – und wie du sie vermeidest

Stolperstein 1: Die rote RGB-LED

Die rote LED auf dem Board teilt sich den Pin GPIO4 mit dem Display-Reset (TFT_RST). Wenn du die rote LED einschaltest (digitalWrite(4, LOW)), setzt du das Display zurück – es stürzt ab oder zeigt Müll an.

Lösung: Lasse die rote LED dauerhaft aus (digitalWrite(LED_RED, HIGH)). Nutze nur die grüne (GPIO16) und blaue (GPIO17) LED.

Stolperstein 2: Die USB-C Buchse

Die USB-C Buchse deines Boards ist nicht vollständig korrekt beschaltet. Die CC-Leitungen (Configuration Channel) fehlen.

Auswirkung: Du kannst kein reines USB-C-zu-USB-C-Kabel verwenden.

Lösung: Verwende entweder ein USB-A-auf-USB-C-Kabel oder einen USB-C-auf-USB-C-Adapter.

Stolperstein 3: Veraltete Plattform-Versionen (für PlatformIO-Nutzer)

Wenn du PlatformIO verwendest, musst du eine ältere Version der ESP32-Plattform angeben. Die neueste Version ist nicht kompatibel.

Lösung: In deiner platformio.ini:

ini

[env:esp32dev]
platform = espressif32@6.5.0    # <- WICHTIG: Version 6.5.0, nicht neuer!
board = esp32dev
framework = arduino

lib_deps = bodmer/TFT_eSPI@^2.5.43

Kompletter Test-Sketch für alle Fälle

Hier ist ein vollständiger Test-Sketch, der alle relevanten Funktionen prüft:

cpp

/**
 * CYD V3 (ESP32-2432S028R) - Kompletter Hardware-Test
 * 
 * Prüft: Display, Farben, LDR, Touch-Kalibrierung, RGB-LED
 */

#include <Arduino.h>
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

// Pin-Definitionen (aus deiner Dokumentation)
#define PIN_LED_GREEN  16
#define PIN_LED_BLUE   17
#define PIN_LDR        34
#define PIN_TOUCH_CS   33

void setup() {
  Serial.begin(115200);
  delay(1000);
  
  Serial.println("\n=== CYD V3 HARDWARE-TEST ===\n");
  
  // Backlight einschalten
  pinMode(21, OUTPUT);
  digitalWrite(21, HIGH);
  
  // RGB-LED (rote LED wird ignoriert!)
  pinMode(PIN_LED_GREEN, OUTPUT);
  pinMode(PIN_LED_BLUE, OUTPUT);
  digitalWrite(PIN_LED_GREEN, HIGH);
  digitalWrite(PIN_LED_BLUE, HIGH);
  
  // Display initialisieren
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  
  // 1. FARBTEST (muss vollflächig sein)
  Serial.println("Test 1: Farben (Rot, Gruen, Blau, Weiss)");
  tft.fillScreen(TFT_RED);   delay(800);
  tft.fillScreen(TFT_GREEN); delay(800);
  tft.fillScreen(TFT_BLUE);  delay(800);
  tft.fillScreen(TFT_WHITE); delay(800);
  tft.fillScreen(TFT_BLACK);
  
  // 2. TEXT-TEST
  Serial.println("Test 2: Textausgabe");
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextSize(2);
  tft.drawString("CYD V3 READY", 70, 100);
  delay(1500);
  
  // 3. LICHT-SENSOR (LDR)
  Serial.println("Test 3: Lichtsensor (GPIO34)");
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_CYAN, TFT_BLACK);
  tft.setTextSize(1);
  tft.drawString("LDR Wert:", 20, 50);
  
  for(int i = 0; i < 10; i++) {
    int ldrValue = analogRead(PIN_LDR);
    int percent = map(ldrValue, 0, 4095, 0, 100);
    
    // Balkenanzeige
    int barWidth = map(ldrValue, 0, 4095, 0, 250);
    tft.fillRect(20, 80, 250, 20, TFT_DARKGREY);
    tft.fillRect(20, 80, barWidth, 20, TFT_YELLOW);
    
    tft.setCursor(20, 120);
    tft.print("Wert: ");
    tft.print(ldrValue);
    tft.print(" (");
    tft.print(percent);
    tft.println("%)");
    
    Serial.printf("  LDR: %d (%d%%)\n", ldrValue, percent);
    delay(500);
  }
  
  // 4. RGB-LED TEST (nur grün und blau)
  Serial.println("Test 4: RGB-LED (Gruen + Blau)");
  tft.fillScreen(TFT_BLACK);
  tft.drawString("LED Test", 100, 80);
  tft.drawString("Gruen...", 110, 120);
  digitalWrite(PIN_LED_GREEN, LOW);  // Grün an
  delay(1000);
  digitalWrite(PIN_LED_GREEN, HIGH); // Grün aus
  
  tft.fillScreen(TFT_BLACK);
  tft.drawString("LED Test", 100, 80);
  tft.drawString("Blau...", 110, 120);
  digitalWrite(PIN_LED_BLUE, LOW);   // Blau an
  delay(1000);
  digitalWrite(PIN_LED_BLUE, HIGH);  // Blau aus
  
  // 5. Touch-Kalibrierung (Startwerte)
  Serial.println("Test 5: Touch-Kalibrierung (Startwerte)");
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_GREEN, TFT_BLACK);
  tft.drawString("Touch Startwerte:", 60, 80);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.drawString("x: 280 - 3860", 80, 120);
  tft.drawString("y: 340 - 3860", 80, 150);
  
  // ERFOLGSMELDUNG
  Serial.println("\n=== ALLE TESTS BESTANDEN! ===\n");
  tft.fillScreen(TFT_BLACK);
  tft.setTextColor(TFT_GREEN, TFT_BLACK);
  tft.setTextSize(2);
  tft.drawString("TEST", 120, 100);
  tft.drawString("FERTIG!", 100, 140);
  tft.setTextSize(1);
  tft.drawString("Board ist bereit!", 90, 200);
}

void loop() {}

Wichtige Hinweise für deine zukünftigen Projekte

Die entscheidende Erkenntnis (für alle, die es eilig haben)

Wenn du nur eine Sache aus diesem Artikel mitnehmen möchtest, dann diese:

Dein ESP32-2432S028R V3 (mit USB-C) benötigt in der User_Setup.h:

cpp

#define ILI9341_2_DRIVER  // NICHT ILI9341_DRIVER!
#define TFT_INVERSION_ON  // Zwingend erforderlich!

Diese zwei Zeilen sind der Schlüssel. Alles andere sind Details.

Fazit: Dein Board ist jetzt bereit

Nach all den Tests und Korrekturen ist dein ESP32-2432S028R V3 nun perfekt konfiguriert. Das Display zeigt das gesamte Bild an, die Farben stimmen, und du kennst alle Einschränkungen (rote LED, USB-C).

Du kannst jetzt mit den spannenden Projekten beginnen:

• Touch-Menüs mit LVGL
• WLAN-Dashboards
• I2C-Sensoren (Temperatur, Luftfeuchtigkeit)
• SD-Karten-Dateibrowser
• Audio-Visualizer

Die vollständige Dokumentation für das CYD findest du auf GitHub unter witnessmenow/ESP32-Cheap-Yellow-Display.

Quellen

• Bodmer, TFT_eSPI Library Documentation: https://github.com/Bodmer/TFT_eSPI
• witnessmenow, ESP32-Cheap-Yellow-Display: https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display
• Cool-Web.de, „ESP32-2432S028 mit 2.8″ Touchscreen“ (2025)
• Espressif Systems, ESP32 Technical Reference Manual (2024)
• PlattformIO, ESP32 Platform Releases: https://registry.platformio.org/platforms/espressif32