Waveshare ESP32-S3 RLCD 4.2: Bilder anzeigen mit LVGL – ohne Code-Chaos

Nachdem ich das Waveshare ESP32-S3 RLCD 4.2 Display bereits in einem ersten Beitrag vorgestellt und im zweiten Teil die grundlegende Programmierung mit der Arduino IDE gezeigt habe, wird es nun etwas praktischer.

Denn ein Display wird natürlich erst dann richtig spannend, wenn nicht nur einfache Texte oder Demo-Elemente angezeigt werden, sondern auch eigene Grafiken, Icons oder Bilder. Genau darum soll es in diesem Beitrag gehen.

• ESP32-S3 mit 4,2″ Display: ePaper Killer? Unboxing & erster Eindruck (Teil 1)
• ESP32-S3 RLCD Display ansteuern: So klappt die Programmierung mit Arduino IDE (Teil 2)

Ich zeige dir, wie du Bilder auf dem Waveshare RLCD Display mit LVGL anzeigen kannst. Dafür nutze ich eine kleine eigene Library, mit der sich JPEG-Grafiken über eine URL laden und auf dem Display darstellen lassen.

Die Library findest du auf GitHub und kannst sie direkt in dein eigenes Projekt einbinden.

Transparenzhinweis:
Das Gerät wurde mir von Waveshare für dieses Review kostenfrei zur Verfügung gestellt. Ich freue mich immer, wenn ich in dieser Form unterstützt werde und neue Hardware frühzeitig testen kann.

Selbstverständlich hat dies keinen Einfluss auf meine Bewertung – ich teile wie gewohnt meine ehrliche Meinung und praktische Erfahrungen mit dem Board.

Ziel des Projektes

Nachdem das Waveshare ESP32-S3 RLCD 4.2 Display grundsätzlich eingerichtet ist und mit der Arduino IDE programmiert werden kann, geht es in diesem Beitrag um eine etwas praxisnähere Anwendung: Grafiken auf dem Display anzeigen.

Das Ziel ist es, eine Bilddatei nicht fest in den Quellcode einzubauen, sondern diese über eine URL aus dem Internet zu laden und anschließend mit LVGL auf dem RLCD Display darzustellen.

Gerade für kleine Anzeigeprojekte ist dieser Ansatz sehr praktisch. Die Grafik kann auf einem Webserver liegen und bei Bedarf einfach ausgetauscht werden, ohne dass der ESP32 jedes Mal neu programmiert werden muss.

Damit eignet sich das Projekt zum Beispiel für:

• Statusanzeigen
• Wettergrafiken
• Logos und Icons
• News-Displays
• einfache Dashboards
• dynamisch erzeugte Bilder von einem Server

Im Mittelpunkt steht dabei ein möglichst einfacher Ablauf: Der ESP32-S3 verbindet sich mit dem WLAN, lädt eine vorbereitete JPEG-Grafik über eine URL und zeigt diese anschließend mit LVGL auf dem Display an.

Warum eine eigene Library?

Das Anzeigen von Bildern mit LVGL auf dem Waveshare ESP32-S3 RLCD 4.2 Display ist grundsätzlich gut machbar, bringt aber schnell einiges an zusätzlichem Code mit sich. Besonders dann, wenn die Grafik nicht fest im Sketch hinterlegt ist, sondern dynamisch aus dem Internet geladen werden soll.

Für diesen Beitrag wollte ich den eigentlichen Beispielcode möglichst schlank und verständlich halten. Der Fokus soll nicht darauf liegen, sich durch viele Hilfsfunktionen, Dateiverarbeitung und interne Details zu arbeiten, sondern darauf, wie man eine Grafik praktisch auf dem Display anzeigen kann.

Ein weiterer Vorteil ist die Wiederverwendbarkeit. Die Library kann nicht nur für dieses eine Beispiel genutzt werden, sondern später auch in anderen Projekten eingesetzt oder erweitert werden. Gerade bei Displays ist das praktisch, weil man häufig ähnliche Funktionen benötigt, etwa zum Anzeigen von Logos, Icons, Wettergrafiken oder Statusbildern.

Auch spätere Erweiterungen lassen sich so sauberer umsetzen. Das Waveshare Board besitzt beispielsweise einen SD-Karten-Slot, der in dieser Version noch nicht unterstützt wird. Da die Bildlogik aber bereits in einer eigenen Library gekapselt ist, kann diese Funktion später gezielt ergänzt werden, ohne den eigentlichen Beispielsketch unnötig aufzublähen.

Die Library findest du auf GitHub: https://github.com/StefanDraeger/lvgl-image-loader-esp32

So bleibt der Beispielcode nachvollziehbar und die Bildlogik sauber gekapselt.

Benötigte Komponenten

Für dieses Projekt benötigst du neben dem Waveshare ESP32-S3 RLCD 4.2 Display nur wenige zusätzliche Komponenten. Wichtig ist ein ESP32-Board mit ausreichend PSRAM, da die Bilddaten im Speicher verarbeitet werden.

Hardware

Für den Aufbau verwende ich:

• Waveshare ESP32-S3 RLCD 4.2
• USB-C Kabel
• WLAN-Verbindung
• PC mit Arduino IDE
• Bilddatei auf einem Webserver oder GitHub

Das Waveshare Board eignet sich für dieses Projekt besonders gut, da es bereits einen ESP32-S3 mit PSRAM besitzt. Genau dieser zusätzliche Speicher ist wichtig, wenn Bilddaten geladen, zwischengespeichert und anschließend mit LVGL auf dem Display angezeigt werden sollen.

Warum PSRAM wichtig ist

Beim Anzeigen von Grafiken werden deutlich mehr Speicherressourcen benötigt als bei einfachen Textausgaben oder kleinen UI-Elementen. Die Bilddaten müssen zunächst geladen und anschließend so bereitgestellt werden, dass LVGL diese als Grafik anzeigen kann.

Ein ESP32 ohne ausreichend PSRAM kann hier schnell an seine Grenzen kommen. Deshalb richtet sich diese Library aktuell an Boards mit genügend Speicher, wie zum Beispiel das Waveshare ESP32-S3 RLCD 4.2.

Software

Auf der Softwareseite benötigst du:

• Arduino IDE
• ESP32 Boardpaket
• LVGL
• Waveshare Display-Konfiguration aus Teil 2
• lvgl-image-loader-esp32 Library

Hinweis zum Cheap Yellow Display

Das weit verbreitete Cheap Yellow Display ESP32-2432S028R wird von dieser Library derzeit nicht unterstützt.

Der Grund dafür ist, dass dieses Board in der bekannten Standardvariante nicht die gleichen Speicherreserven wie das Waveshare ESP32-S3 RLCD Board bietet. Für einfache LVGL-Oberflächen ist das Cheap Yellow Display weiterhin sehr interessant, für dieses konkrete Projekt mit dynamisch geladenen Grafiken aus dem Internet ist es aktuell jedoch nicht vorgesehen.

Der Fokus dieser Anleitung liegt daher klar auf dem Waveshare ESP32-S3 RLCD 4.2 Display beziehungsweise auf ESP32-Boards mit ausreichend PSRAM.

Vorbereitung der Grafiken

Bevor eine Grafik auf dem Waveshare ESP32-S3 RLCD 4.2 Display angezeigt wird, sollte sie möglichst gut für das Display vorbereitet werden. Das ist bei diesem Display besonders wichtig, da es sich nicht um ein klassisches Farbdisplay handelt.

Das RLCD Display kann nur Schwarz, Weiß und Graustufen darstellen. Grundsätzlich lassen sich damit auch Bilder mit Helligkeitsverläufen anzeigen, in der Praxis wirkt die Darstellung von Graustufen jedoch schnell etwas körnig. Besonders bei Fotos oder sehr detailreichen Grafiken fällt das deutlich auf.

Die besten Ergebnisse erzielst du daher mit Grafiken, die möglichst klar auf Schwarz und Weiß reduziert sind.

Für dieses Projekt empfiehlt es sich daher, die Grafik bereits vorab passend aufzubereiten. Idealerweise wird das Bild auf die benötigte Größe skaliert und anschließend in ein klares Schwarz-Weiß-Bild umgewandelt. Dadurch wirkt die Darstellung auf dem RLCD Display deutlich sauberer und besser lesbar.

Die Auflösung des Displays beträgt 300 × 400 Pixel. Wenn du eine Grafik bildschirmfüllend anzeigen möchtest, sollte sie daher möglichst genau auf diese Größe vorbereitet werden. Kleinere Grafiken, Icons oder Logos können natürlich ebenfalls verwendet und später passend auf dem Display positioniert werden.

Besonders wichtig ist ein hoher Kontrast. Je klarer sich helle und dunkle Bereiche voneinander unterscheiden, desto besser wirkt das Ergebnis auf dem RLCD Display.

Library von GitHub einbinden

Die Library wird direkt über GitHub als ZIP-Datei heruntergeladen.

In der Arduino IDE wird die ZIP-Datei anschließend über folgenden Menüpunkt eingebunden:

Sketch > Bibliothek einbinden > .ZIP-Bibliothek hinzufügen...

Nach der Installation muss im Sketch nur noch diese Include-Zeile ergänzt werden:

#include "lvgl_image_loader.h"

Damit steht die Library im Projekt zur Verfügung und kann für das Laden und Anzeigen der Grafiken verwendet werden.

Beispielcode Schritt für Schritt erklärt

Nachdem die Library eingebunden wurde, kann der eigentliche Sketch sehr übersichtlich gehalten werden. Wichtig sind im Wesentlichen drei Punkte: Die Library wird eingebunden, ein ImageLoader-Objekt wird erzeugt und anschließend wird die gewünschte Grafik geladen und auf einem LVGL-Objekt angezeigt.

/**
 * LvglImageLoader - Example for Waveshare RLCD 4.2"
 *
 * Hardware:
 * - Waveshare RLCD 4.2" (400x300) (https://www.waveshare.com/esp32-s3-rlcd-4.2.htm)
 * - ESP32-S3 with PSRAM
 * 
 * Wiring:
 * - GPIO 12 → MOSI
 * - GPIO 11 → CLK
 * - GPIO  5 → CS
 * - GPIO 40 → DC
 * - GPIO 41 → RST
 */

#include "display_bsp.h"
#include "src/app_bsp/lvgl_bsp.h"
#include "src/ui_src/generated/gui_guider.h"
#include <lvgl.h>
#include <WiFi.h>
#include "lvgl_image_loader.h"

#define MOSI 12
#define SCL 11
#define DC 5
#define CS 40
#define RST 41
#define SCREEN_WIDTH 400
#define SCREEN_HEIGHT 300

const char *ssid = "YOUR_WIFI_SSID";
const char *password = "YOUR_WIFI_PASSWORD";
const char *imageUrl = "https://github.com/StefanDraeger/lvgl-image-loader-esp32/blob/main/images/drache.jpg?raw=true";

const int IMAGE_WIDTH = 300;
const int IMAGE_HEIGHT = 300;

DisplayPort RlcdPort(MOSI, SCL, DC, CS, RST, SCREEN_WIDTH, SCREEN_HEIGHT);
LvglImageLoader imageLoader;

static void Lvgl_FlushCallback(lv_display_t *drv, const lv_area_t *area,
                               uint8_t *color_map) {
  uint16_t *buffer = (uint16_t *)color_map;
  for (int y = area->y1; y <= area->y2; y++) {
    for (int x = area->x1; x <= area->x2; x++) {
      uint8_t color = (*buffer < 0x7fff) ? ColorBlack : ColorWhite;
      RlcdPort.RLCD_SetPixel(x, y, color);
      buffer++;
    }
  }
  RlcdPort.RLCD_Display();
  lv_disp_flush_ready(drv);
}

void setup() {
  Serial.begin(115200);
  RlcdPort.RLCD_Init();
  Lvgl_PortInit(400, 300, Lvgl_FlushCallback);

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\nVerbunden!");

  if (Lvgl_lock(-1)) {
    // Screen vorbereiten
    lv_obj_t *screen = lv_scr_act();
    lv_obj_set_style_bg_color(screen, lv_color_white(), LV_PART_MAIN);

    // Container mittig
    lv_obj_t *container = lv_obj_create(screen);
    lv_obj_set_size(container, IMAGE_WIDTH, IMAGE_HEIGHT);
    lv_obj_set_style_border_width(container, 0, LV_PART_MAIN);
    lv_obj_set_style_pad_all(container, 0, LV_PART_MAIN);
    lv_obj_set_style_bg_color(container, lv_color_white(), LV_PART_MAIN);
    lv_obj_center(container);

    // Bild laden
    imageLoader.loadImage(imageUrl, container, IMAGE_WIDTH, IMAGE_HEIGHT);

    Lvgl_unlock();
  }
}

void loop() {
  vTaskDelay(pdMS_TO_TICKS(1000));
}

Zunächst wird die Library im Sketch eingebunden:

#include "lvgl_image_loader.h"

Danach wird ein Objekt der Library erzeugt:

LvglImageLoader imageLoader;

Dieses Objekt übernimmt später das Laden der Bilddatei und die Übergabe an LVGL.

Damit das Bild auf dem Display angezeigt werden kann, wird zunächst ein Container erstellt. Dieser Container dient als Zielbereich für die Grafik:

lv_obj_t *container = lv_obj_create(lv_scr_act());
lv_obj_set_size(container, 300, 300);
lv_obj_center(container);

In diesem Beispiel wird der Container auf 300 × 300 Pixel gesetzt und mittig auf dem Display platziert. Das passt gut zu den zuvor vorbereiteten Beispielgrafiken.

Wichtig ist, dass der ESP32-S3 zu diesem Zeitpunkt bereits mit dem WLAN verbunden ist, da die Grafik über eine URL geladen wird.

Anschließend wird die Grafik über eine URL geladen:

imageLoader.loadImage("https://github.com/StefanDraeger/lvgl-image-loader-esp32/blob/main/images/drache.jpg?raw=true", container, 300, 300);

Die erste Angabe ist die URL zur Bilddatei. Danach folgt der LVGL-Container, in dem die Grafik angezeigt werden soll. Die letzten beiden Werte geben die gewünschte Breite und Höhe des Bildes an.

Die Library selbst unterstützt das Laden von JPEG-Bildern über HTTPS, nutzt PSRAM für den Bildpuffer und kann die Grafik für RLCD- beziehungsweise ePaper-ähnliche Displays in Graustufen umwandeln. Außerdem sind Wiederholungsversuche, Redirects und Timeouts vorgesehen.

Optional können die Verbindungsparameter angepasst werden:

imageLoader.setMaxRetries(3);
imageLoader.setRetryDelay(5000);
imageLoader.setTimeout(15000);

Damit lässt sich festlegen, wie oft ein Download erneut versucht wird, wie lange zwischen zwei Versuchen gewartet wird und wann ein Verbindungsversuch abgebrochen werden soll.

Für den Einstieg reicht der Ablauf aber bereits aus:

#include "lvgl_image_loader.h"
LvglImageLoader imageLoader;
lv_obj_t *container = lv_obj_create(lv_scr_act());
lv_obj_set_size(container, 300, 300);
lv_obj_center(container);
imageLoader.loadImage("https://github.com/StefanDraeger/lvgl-image-loader-esp32/blob/main/images/drache.jpg?raw=true", container, 300, 300);

Der eigentliche Sketch bleibt dadurch angenehm kurz. Die Display-Initialisierung und LVGL-Konfiguration stammen aus dem vorherigen Teil der Beitragsreihe. In diesem Abschnitt geht es nur noch darum, eine vorbereitete Grafik über eine URL zu laden und auf dem RLCD Display auszugeben.

Ergebnis auf dem RLCD Display

Nach dem Hochladen des Sketches verbindet sich der ESP32-S3 mit dem WLAN und lädt die hinterlegte Bilddatei aus dem Internet. Anschließend wird die Grafik über die Library verarbeitet und im LVGL-Container auf dem RLCD Display angezeigt.

In meinem Beispiel verwende ich eine Grafik mit 300 × 300 Pixeln, die mittig auf dem Display platziert wird. Dadurch bleibt rundherum noch etwas Abstand, und das Motiv wirkt nicht gequetscht.

Das Ergebnis zeigt, dass sich das Waveshare RLCD nicht nur für Texte oder UI-Elemente eignet, sondern auch für eigene Grafiken.

Aktuelle Einschränkungen

Die Library ist aktuell bewusst schlank gehalten und unterstützt derzeit nur JPEG-Bilder. Andere Bildformate wie PNG, BMP oder GIF werden in dieser Version noch nicht verarbeitet.

Außerdem werden die Bilder momentan ausschließlich von einem Webspace beziehungsweise über eine URL geladen. Das bedeutet: Die Grafik muss online erreichbar sein, damit der ESP32-S3 sie herunterladen und anschließend auf dem RLCD Display anzeigen kann.

Der vorhandene SD-Karten-Slot des Waveshare ESP32-S3 RLCD 4.2 wird in dieser Version noch nicht genutzt. Eine spätere Erweiterung, bei der Bilder direkt von der SD-Karte geladen werden können, ist jedoch geplant.

Ausblick & Fazit

Einfache Schwarz-Weiß-Bilder lassen sich auf dem Waveshare ESP32-S3 RLCD 4.2 gut darstellen. Besonders bei klaren Motiven wirkt das Ergebnis sauber und gut lesbar.

Im nächsten Beitrag geht es einen Schritt weiter: Ich zeige dir, wie du eine News von Tagesschau.de lädst und anschließend Text und Bild gemeinsam auf dem Display anzeigen kannst.

Damit wird aus der reinen Bildanzeige ein kleines Praxisprojekt für eine dynamische Informationsanzeige.

FAQ – Bilder auf dem Waveshare ESP32-S3 RLCD 4.2 anzeigen

Letzte Aktualisierung am: 09. Mai 2026