Ein 3,5-Zoll-Touchdisplay, das ohne ein einziges Kabel direkt auf den Raspberry Pi Pico gesteckt wird – das klingt nach einem Projekt für einen entspannten Nachmittag. In der Praxis vergehen dann doch etliche Stunden, bis das erste Bild in den richtigen Farben erscheint. Wer im Netz sucht, findet reichlich Beispielcode für genau dieses Board, und ein erstaunlich großer Teil davon liefert einen weißen Schirm, einen schwarzen Schirm oder Farben, die mit der Vorlage wenig zu tun haben.
Damit sich das niemand ein zweites Mal erarbeiten muss, gibt es hier ein fertiges Referenzprojekt zum Herunterladen: ein lauffähiger Arduino-Sketch mit Treiber, Textausgabe, Diagrammfunktionen und Touch-Auswertung – dazu eine Dokumentation sämtlicher Stolperfallen, über die man auf dem Weg dorthin fällt.
Die verwendete Hardware
Zum Einsatz kommt das Waveshare Pico-ResTouch-LCD-3.5. welches aktuell (Stand August 2026) sehr preiswert bei AZ-Delivery angeboten wird. Diese TFT-Board ist als Aufsteckplatine für den Raspberry Pi Pico ausgelegt: Der Pico wird von unten eingesteckt, sämtliche Verbindungen laufen über die Stiftleisten. Löten oder verkabeln entfällt vollständig.
Die Eckdaten:
* Auflösung 480 × 320 Pixel bei 3,5 Zoll Diagonale
* Resistiver Touch über einen XPT2046-Controller
* Anbindung über SPI, Display und Touch teilen sich denselben Bus
* microSD-Steckplatz auf der Rückseite (in diesem Projekt nicht genutzt)
* Hintergrundbeleuchtung über einen eigenen GPIO schaltbar
Als Rechner dient ein gewöhnlicher **Raspberry Pi Pico** mit RP2040. Ein Pico W funktioniert ebenso, wird für dieses Projekt aber nicht zwingend gebraucht.
Preislich liegt die Kombination damit bei rund 20 EUR – für ein Display dieser Größe mit Touch eigentlich spottbillig – was natürlich an der Sonderaktion bei AZ-Delivery lag. Im Normalfall sind für das Display zwischen 20 und 35 EUR fällig und weitere 6-7 EUR für den Pico Pi.
Hier der Blick auf den Lieferumfang:
Ein Wort zum resistiven Touch: Er reagiert auf Druck, nicht auf Hautkontakt. Das ist beim Bedienen mit dem Finger gewöhnungsbedürftig, hat aber einen praktischen Vorteil – man kann ihn mit Handschuhen oder einem beliebigen Stift bedienen. Für Werkstatt- und Außeneinsatz ist das oft die bessere Wahl.
Für welches SDK ist das gedacht?
Diese Frage ist wichtiger, als sie zunächst klingt, denn für den Pico PI mit RP2040 stehen mehrere Entwicklungsumgebungen zur Auswahl, und bei Beispielcodes ist selten dazugeschrieben, für welche er gedacht ist.
Das Referenzprojekt hier ist gebaut für:
* die Arduino IDE 2.x
* mit dem Board-Paket **„Raspberry Pi Pico/RP2040/RP2350″ von Earle Philhower**, getestet mit Version 6.0.0
Warum Arduino? Nun, weil es sehr einfach zu bedienen ist, für fast jede Plattform erhältlich ist und zu guter Letzt, weil ich damit vertraut bin, also schnell produktiv damit arbeiten kann.
WICHTIG: Es gibt zwei verschiedene Arduino-Board-Pakete für den Pico. Das offizielle „Arduino Mbed OS RP2040″ ist **nicht** gemeint und funktioniert hier auch nicht – der Sketch nutzt unter anderem `SPI1.setSCK()`, das es nur im Philhower-Core gibt. Wer das falsche Paket installiert hat, bekommt Übersetzungsfehler und sucht die Ursache erfahrungsgemäß an der falschen Stelle.
Ebenfalls nicht gedacht ist das Projekt für das offizielle Pico C/C++ SDK, für MicroPython oder für PlatformIO. Der Treiber selbst ließe sich zwar mit überschaubarem Aufwand portieren, der Sketch drumherum nicht.
Was nach dem Download zu tun ist
Für alle die nicht so viel Erfahrung mit der Arduino IDE Haben hier eine kurze Zusammenfassung der wichigsten Schritte.
Die ZIP-Datei enthält drei Dinge: den Sketch-Ordner `picopi_tft`, eine ausführliche `README.md` und die Lizenzdatei. Der Weg zum laufenden Display in fünf Schritten:
1. Board-Paket installieren
In der Arduino IDE unter *Datei → Einstellungen → Zusätzliche Boardverwalter-URLs* diese Adresse eintragen:
„`
https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
„`
Anschließend über *Werkzeuge → Board → Boardverwalter* nach „pico“ suchen und das Paket von Earle Philhower installieren. Der Download ist einige hundert Megabyte groß, das dauert einen Moment.
2. Bibliotheken nachrüsten
Über *Werkzeuge → Bibliotheken verwalten* werden drei Bibliotheken benötigt:
* Adafruit GFX Library (getestet 1.12.6) – Text, Schriften, Zeichenfunktionen
* Adafruit BusIO (1.17.4) – Abhängigkeit der vorigen, wird meist automatisch mit angeboten
* XPT2046_Touchscreen (1.4) – der Touch-Controller
3. Sketch einsortieren
Aus der ZIP-Datei den Ordner `picopi_tft` in das eigene Sketchbook kopieren, unter Windows üblicherweise `Dokumente\Arduino\`. Der Ordner muss genauso heißen wie die `.ino`-Datei darin – das ist eine Eigenart der Arduino IDE und keine Schikane des Autors.
4. Board auswählen
Unter *Werkzeuge → Board* die Einstellung **„Raspberry Pi Pico“** wählen, unter *Werkzeuge → Port* den seriellen Anschluss.
Erscheint dort **kein Port**, ist das der Normalfall bei einem fabrikneuen oder frisch geflashten Pico. Dann den Pico abziehen, die BOOTSEL-Taste auf dem Pico Board gedrückt halten, wieder einstecken und loslassen. Er meldet sich nun als Laufwerk `RPI-RP2`. Über *Sketch → Kompilierte Binärdatei exportieren* entsteht eine `.uf2`-Datei, die man einfach auf dieses Laufwerk kopiert. Danach startet das Board neu und ist von da an ganz normal über den Port ansprechbar.
5. Hochladen
Der übliche Pfeil-Knopf. Nach wenigen Sekunden erscheint die Demo.
Die Stolperfallen – oder warum die Entwicklung so lange gedauert hat
Der eigentliche Wert dieses Arduino-Referenz-Pakets steckt weniger im Code als in dieser Liste. Alle vier Punkte sind durch umfangreiche Tests an der realen Hardware überprüft und belegt, nicht nur aus Datenblättern abgeleitet. Es sind als die zentralen Erkenntnisse der bisherigen Entwicklungsarbeit.
Die Display-Inversion fehlt fast überall
Das Panel muss mit dem Kommando **`0x21` (Display Inversion ON)** initialisiert werden. Ohne dieses eine Kommando zeigt es jede Farbe als Komplement: Rot wird zu Cyan, Weiß wird zu Schwarz, Schwarz zu Weiß. Zahlreiche kursierende Treiber für dieses Board senden weder `0x21` noch `0x20` und überlassen die Sache dem Reset-Zustand – auf diesem Panel ist das schlicht falsch.
Wer an dieser Stelle versucht, das Problem durch Vertauschen der Farbkonstanten `RED` und `BLUE` zu beheben, kommt nicht weiter. Bei einer Inversion ist nicht die Kanalzuordnung falsch, sondern jeder einzelne Bitwert.
Die ILI9488-Angabe führt in die Irre
Waveshare nennt für dieses Board teilweise den Controller ILI9488. Ein ILI9488 kann am SPI-Bus grundsätzlich **kein** 16-Bit-Farbformat, er braucht 18 Bit mit drei Byte je Pixel. Das hier verbaute Panel verhält sich genau umgekehrt: Mit `0x3A = 0x55` (16 Bit) läuft es, mit `0x3A = 0x66` (18 Bit) bleibt das Bild schwarz.
Wer der Herstellerangabe folgt und auf 18 Bit umstellt, bekommt kein Bild – und sucht den Fehler garantiert woanders. Die Chip-Kennung wurde nicht ausgelesen; das Verhalten spricht für einen ST7796-kompatiblen Controller.
GP10, GP11 und GP12 liegen auf SPI1
Nicht auf SPI0. Das klingt banal, ist aber die häufigste Ursache für ein totes Display bei Verwendung fertiger Bibliotheken – dazu unten mehr.
Chip-Select darf pro Byte umschalten
Der mitgelieferte Treiber zieht CS für jedes einzelne Byte auf LOW und wieder auf HIGH. Nach Datenblattlogik müsste das mehrbyteige Kommandos zerlegen und deren Parameter verwerfen. Auf diesem Controller tut es das nicht. Erwähnenswert, weil die naheliegende „Verbesserung“ – CS über die ganze Sequenz gedrückt halten – hier keinen Nutzen bringt und in der Erprobung Ärger gemacht hat.
Der Trick zur Fehlersuche
Wer ein Display mit unklarem Verhalten vor sich hat, sollte nicht mit bunten Farbbalken anfangen. Acht Balken nebeneinander sind mehrdeutig: Eine ungewohnte Reihenfolge kann von falschen Farben kommen – oder von einem um 180 Grad gedrehten Bild. Genau daran ist meine Fehlersuche hier dann auch zweimal vorbeigelaufen.
Eindeutig wird es mit zwei Zeilen:
„`c
LCD_Clear(RED); // eine Farbe über den ganzen Schirm
LCD_FillRect(0, 0, 80, 50, WHITE); // Marke am Koordinatenursprung
„`
Daraus ergeben sich beim Testen zwei Fragen ohne Interpretationsspielraum:
* Welche Farbe hat der Hintergrund? Cyan statt Rot bedeutet fehlende Inversion. Blau statt Rot bedeutet vertauschte Rot- und Blaukanäle. Gelb bedeutet beides zusammen.
* In welcher Ecke sitzt die weiße Marke? Sitzt sie nicht oben links, stimmt die Ausrichtung nicht.
Eine einfarbige Fläche hat keine Reihenfolge, die sich durch eine Drehung umkehren ließe. Das ist der ganze Trick – und er hätte mir einige Stunden des experimentierens erspart.
Warum Adafruit GFX und nicht TFT_eSPI
TFT_eSPI ist die verbreitetere Wahl, deutlich schneller und bringt Sprites und geglättete Schriften mit. Für dieses Projekt fiel die Entscheidung trotzdem auf **Adafruit GFX**, und zwar aus einem pragmatischen Grund: TFT_eSPI lieferte auf diesem Aufbau auch nach Korrektur mehrerer belegbarer Konfigurationsfehler kein Bild. Die Ursache blieb offen.
Adafruit GFX verlangt von einer abgeleiteten Klasse lediglich eine `drawPixel()`-Funktion und baut alles Weitere darauf auf. Damit ließ sich die Bibliothek auf den bereits funktionierenden eigenen Treiber aufsetzen, statt eine fremde – womöglich unpassende – Initialisierung zu übernehmen. Eine laufende Grundlage ist mehr wert als offene Fehlersuche.
Wer TFT_eSPI dennoch einsetzen möchte, findet in der README die gesicherten Erkenntnisse. Die wichtigste vorweg: In kursierenden Setup-Dateien steht häufig
„`c
#define RP2040_SPI1_PORT
„`
Dieses Symbol wertet TFT_eSPI **nirgends** aus. Die Portwahl hängt allein an `TFT_SPI_PORT` und fällt ohne diese Zeile auf SPI0 zurück. Die Bibliothek spricht dann die falsche SPI-Hardware an, während die Pins auf SPI1 liegen – Ergebnis ist ein schwarzer Schirm bei scheinbar korrekter Konfiguration. Richtig ist `#define TFT_SPI_PORT 1`.
Was das Referenz-Projekt bereits kann
Die mitgelieferte Demo zeigt, was ohne weiteren Aufwand verfügbar ist:
* Kopfzeile mit proportionaler Schrift
* Diagramm mit Raster, Achsen, Beschriftung, zwei Kurven und Legende
* Schaltfläche mit abgerundeten Ecken, die auf Berührung reagiert
* Anzeige der Touch-Rohwerte – praktisch für die spätere Kalibrierung
Darüber steht die vollständige Adafruit-GFX-Schnittstelle zur Verfügung: `print()`, freie Schriften über `setFont()`, Linien, Rechtecke, Kreise, Dreiecke, Bitmaps. Für Messwertanzeigen, Statusbildschirme oder kleine Bedienoberflächen reicht das ohne Zutaten.
Eine Einschränkung sei genannt: Der Treiber arbeitet ohne DMA und schaltet CS pro Byte. Ein kompletter Bildaufbau dauert dadurch spürbar. Für statische Oberflächen und teilweise aktualisierte Diagramme ist das kein Thema, für Vollbildanimation schon. Allerdings ist der geplante Einsatzzweck die visualisierung von Meßwerten und da stört das nicht.
Linksammlung
Hier also das besprochene Arduino-Referenzprojekt als ZIP: [picopi_tft_referenz_v0.1.zip] zum Download
Weitere hilfreiche Links:
* Anwenderhandbuch zum TFT-Display-Board von AZ-Delivery
* Waveshare Pico-ResTouch-LCD-3.5 – Herstellerseite und Wiki
* arduino-pico Board-Paket von Earle Philhower: <https://github.com/earlephilhower/arduino-pico>
* Adafruit GFX Library: <https://github.com/adafruit/Adafruit-GFX-Library>
* XPT2046_Touchscreen: <https://github.com/PaulStoffregen/XPT2046_Touchscreen>
Mein Referenz-Projekt hier steht unter MIT-Lizenz und darf frei verwendet, geändert und weitergegeben werden, auch kommerziell.
—
Wer das Display mit anderer Hardware oder anderen Bibliotheken zum Laufen gebracht hat – gerne in die Kommentare damit. Besonders interessant wäre eine funktionierende TFT_eSPI-Konfiguration für dieses Board; die ist mir nämlich nicht gelungen.