wt32sc01-dashboard/SPEC.md

WT32-SC01 Plus – Wetter/Kalender/MVG Dashboard (Touch)

Letztes Update: 2026-08-02

1. Ziel

Ein WT32-SC01 Plus (ESP32-S3, 3.5" kapazitiver Touch-IPS-Display) zeigt Wetter, Kalendertermine und MVG-Abfahrten an – funktional analog zum bestehenden M5Stack-Dashboard, aber als eigenständiges, komplett neu geschriebenes Projekt in einem neuen, eigenen Git-Repository. Es wird kein Code aus dem M5Stack-Projekt übernommen; lediglich das UI-/API-Konzept und die Backend-Endpunkte werden wiederverwendet.

Kernunterschiede zum M5Stack:

• Touch statt Buttons: Navigation ausschließlich über Touch-Buttons auf dem Screen, keine physischen Tasten.
• Deutlich größeres Display (3.5" statt 2.0"), dadurch großzügigere, besser lesbare Darstellung von Listen (Abfahrten, Termine, Stundenvorhersage).
• Hochformat (Portrait) statt Querformat, damit sich Listen (MVG-Abfahrten, Termine, stündliche Vorhersage) besser vertikal darstellen lassen.
• Home-Screen als Buttons/Kacheln: Wetter- und Kalenderbereich sind selbst antippbare Kacheln, die direkt zur jeweiligen Detailseite führen (kein separater Toggle-Button nötig).

2. Hardware

• Gerät: WT32-SC01 Plus, ESP32-S3-WROVER (Dual-Core Xtensa LX7, PSRAM)
• Display: 3.5" IPS, Treiber-IC ST7796UI, physische Auflösung 480×320 (Querformat ab Werk), Ansteuerung über 8-Bit-Parallel-Interface (i80/8080)
• Software-Orientierung: Hochformat (Portrait) → logische Auflösung 320×480 (Breite × Höhe), per Display-Rotation im Code erzwungen
• Touch: Kapazitiver Touchcontroller FT6336U, I2C, Single-Touch ausreichend für diese App
• Sonstige Peripherie am Board: Lautsprecher, SD-Karte, RS485 – werden für dieses Projekt nicht benötigt
• Netzwerk: WLAN (Heimnetz, Zugriff auf *.fritz.box Hosts, gleiches Netz wie M5Stack)

Hinweis: Pinbelegung (Display-Datenleitungen, Touch-I2C, Backlight, Reset) ist je nach Board-Revision leicht unterschiedlich dokumentiert und wird beim Projektstart anhand des konkret vorliegenden Boards verifiziert und in einer eigenen board_pins.h fixiert.

3. Toolchain

• Build-System: PlatformIO (kein Arduino IDE), analog zum M5Stack-Projekt
• Grafik-Stack: LovyanGFX als Display-/Touch-Treiber in Kombination mit LVGL (Version 9) für UI-Widgets, Touch-Buttons, Listen und Scroll-Verhalten – bewährte Kombination für das WT32-SC01 Plus
• Deployment: Eigenes Deploy-Skript scripts/deploy.sh, das ausschließlich Build + Flash durchführt (kein automatisches Öffnen des seriellen Monitors, kein Zusatzschritt danach). USB-Port wird standardmäßig automatisch erkannt, kann aber optional als Parameter übergeben werden (z.B. ./deploy.sh /dev/ttyUSB0)
• WLAN-Zugangsdaten: Fest im Code, ausgelagert in include/secrets.h, per .gitignore vom Repo ausgeschlossen. Ein secrets.h.example mit Platzhaltern wird eingecheckt
• Zeitsynchronisation: Keine eigene NTP-Sync im Gerät. Alle Zeitangaben werden 1:1 so übernommen und dargestellt, wie sie von den APIs geliefert werden (keine relative Umrechnung wie "in 20 Minuten")
• Versionskontrolle: Es wird von Anfang an ein neues, eigenes Git-Repository angelegt (git init + eigener Remote, z.B. wt32sc01-dashboard). Kein Fork und kein geteilter Code mit dem M5Stack-Repo – lediglich als Referenz/Vorbild verlinkt

4. Datenquellen (APIs)

Identisch zum M5Stack-Projekt, gleiche Backend-Services im lokalen Netz, JSON per HTTP GET. Response-Formate werden 1:1 übernommen, keine Änderungen am Backend nötig.

4.1 Wetter-API

• Endpoint: /api/weather (konfigurierbar in include/secrets.h)
• Liefert current (aktuelles Wetter: temperature, symbol, description, emoji) und forecast (stündliche Vorhersage inkl. precipitation.probability und precipitation.type)
• symbol (z.B. mo____, mb____, wb____) ist Basis für die Icon-Auswahl

4.2 Kalender-API

• Endpoint: /api/events (konfigurierbar in include/secrets.h)
• Liefert die nächsten 10 Termine, serverseitig chronologisch sortiert (summary, start_at, end_at, all_day, status, u.a.)
• Für den Home-Screen werden die ersten 2 Einträge verwendet, für die Detailseite alle 10
• all_day-Termine werden anders dargestellt (nur Datum statt Uhrzeit); Zeiten werden unverändert übernommen

4.3 MVG-Abfahrten-API

• Endpoint: /api/departures (konfigurierbar in include/secrets.h)
• Liefert eine ungefilterte Liste aller Abfahrten (beide Stationen, U-Bahn/S-Bahn gemischt, Reihenfolge wie geliefert): station, type, icon, line, destination, time_str, delay_min, cancelled, messages
• time_str wird direkt übernommen, keine eigene Zeitberechnung

5. Screens (Hochformat, 320×480)

5.1 Hauptseite (Home)

Ruhezustand nach Boot. Besteht aus großen, antippbaren Kacheln/Touch-Buttons, angeordnet untereinander (Portrait-Layout), im Kachel-Stil ähnlich der Referenzoptik (siehe Abschnitt 7):

• Wetter-Kachel (groß, oben): aktuelle Temperatur, Icon, Beschreibung, ggf. Regen-Hinweis-Badge. Antippen → Wetter-Detailseite
• Kalender-Kachel (groß, darunter): zeigt die nächsten 2 Termine (Summary + Datum/Uhrzeit, all_day gesondert markiert) direkt auf der Kachel als Vorschau. Antippen → Kalender-Detailseite
• MVG-Kachel (klein, unten, ohne Abfahrten-Vorschau – nur Icon/Label "MVG" bzw. "Abfahrten"): Antippen → MVG-Abfahrtsseite

Regen-Hinweis (weicher Schwellwert): Sobald irgendein Eintrag der nächsten 8 Vorhersage-Stunden precipitation.type == "rain" mit probability > 0 enthält, erscheint ein Regen-Hinweis-Icon/Badge auf der Wetter-Kachel.

Refresh: alle 10 Minuten (Wetter + Kalender neu abrufen)

5.2 Wetter-Detailseite

• Aktuelles Wetter ausführlicher als auf der Home-Kachel
• Stundenweise Vorhersage aus forecast als vertikal scrollbare Liste (Zeit, Temperatur, Icon, Regenwahrscheinlichkeit) – dank Portrait-Format und größerem Display deutlich übersichtlicher als auf dem M5Stack
• Zurück-Button unten links → zurück zur Hauptseite

5.3 Kalender-Detailseite

• Liste aller 10 Termine aus events als vertikal scrollbare Liste (nicht nur die ersten 2 wie auf der Home-Kachel)
• Zurück-Button unten links → zurück zur Hauptseite

5.4 MVG-Abfahrtsseite

• Liste aller Abfahrten aus departures, ohne Filterung nach Station oder Linie, als vertikal scrollbare Liste (Linie, Ziel, Zeit, Verspätung, ggf. Ausfall-Hinweis)
• Zurück-Button unten links → zurück zur Hauptseite
• Kein Background-Refresh (nur beim Betreten der Seite und via tick() alle 60 Sekunden)

6. Navigation (Touch)

Keine physischen Buttons – ausschließlich Touch-Bedienung:

Aktion	Funktion
Tap auf Wetter-Kachel (Home)	Öffnet Wetter-Detailseite
Tap auf Kalender-Kachel (Home)	Öffnet Kalender-Detailseite
Tap auf MVG-Kachel (Home)	Öffnet MVG-Abfahrtsseite
Tap auf Zurück-Button (unten links, auf jeder Detailseite)	Zurück zur Hauptseite

Zusätzlich: Automatischer Rücksprung zur Hauptseite nach 5 Minuten Inaktivität (keine Touch-Eingabe), unabhängig davon, auf welcher Seite man sich gerade befindet.

7. UI- und Icon-Konzept

Gleiches Grundprinzip wie beim M5Stack (hochwertig, farbig, dunkles Farbschema), zusätzlich angelehnt an die im Referenzbild gezeigte Kachel-Optik (große, abgerundete Rechtecke mit Icon + Label + kleinem Zusatzwert), übertragen auf ein Hochformat-Dashboard:

• Farbschema "iPhone Dark Mode"-Look: Sehr dunkles Schwarz (#000000/#0B0B0D) als Hintergrund, weißer/heller Text (#FFFFFF/#F2F2F7) als Basis. Jede Home-Kachel bekommt einen eigenen, dezenten Akzentton als Kachel-Hintergrund (z.B. gedämpftes Blau für Wetter, eigene Akzentfarbe für Kalender, an MVV-Linienfarben angelehnte Töne für MVG), ähnlich den farbigen Funktionskacheln im Referenzbild, aber ruhiger/dunkler
• Größere, touch-taugliche Kacheln: Mindestgröße der Home-Kacheln so bemessen, dass sie bequem mit dem Finger treffbar sind (Richtwert ≥ 80–100 px Höhe bei 320 px Breite); Zurück-Button ebenfalls als große, gut treffbare Fläche unten links
• Eigene prozedurale Icons als LVGL-Canvas-Objekte (keine externen Bitmap-Dateien), Icon-Set: Sonne/klar, bewölkt, Regen, Nacht-Varianten (Basis: symbol-Feld), U-Bahn-Symbol, S-Bahn-Symbol, Kalender-Symbol, Regen-Hinweis-Symbol, Zurück-Pfeil, Retry-/Fehler-Symbol
• Layout-Prinzipien: Klare visuelle Hierarchie (große Temperatur/Uhrzeit, kleinere Nebeninfos), hoher Kontrast schwarz/weiß als Basis, großzügiger als beim M5Stack dank 3.5"-Display und Portrait-Ausrichtung, dezente Akzentfarben statt vieler bunter Flächen
• Typografie: Deutlich größere, gut lesbare Schriftgrößen als beim M5Stack (mehr Platz vorhanden), wichtige Werte (Temperatur, Abfahrtszeit) groß und fett gegenüber Nebeninfos

8. Fehlerbehandlung

• Bei nicht erreichbarer API: Fehleranzeige auf dem betroffenen Screen bzw. der betroffenen Kachel (Retry-Icon + kurzer Text wie "Keine Verbindung"). Letzte gültige Daten bleiben erhalten (außer bei MVG: nur aktuelle Daten, da kein Background-Refresh)
• Retry-Auslöser: Automatisch beim nächsten regulären Refresh-Intervall, zusätzlich manuell durch erneuten Tap auf die betroffene Kachel bzw. durch Zurück- und wieder-Reinnavigieren in den Screen

9. Refresh-Intervalle

Seite/Datenquelle	Intervall	Background-Refresh
Hauptseite (Wetter + Kalender)	10 Minuten	Ja (data_manager)
MVG-Abfahrtsseite	1 Minute	Nein (nur tick())
Wetter-Detailseite	folgt Hauptseiten-Intervall (10 Minuten), da gleiche Datenquelle	Ja (data_manager)
Kalender-Detailseite	folgt Hauptseiten-Intervall (10 Minuten), da gleiche Datenquelle	Ja (data_manager)

10. Projektstruktur (PlatformIO, neues Repository)

Eigenständiges, neues Git-Repository (z.B. wt32sc01-dashboard), von Anfang an mit git init + eigenem Remote, komplett unabhängig vom M5Stack-Repo:

/
├── .git/                     (eigenes, neues Repository – kein Fork)
├── .gitignore                (schließt u.a. include/secrets.h, .pio/ aus)
├── platformio.ini            (Board: esp32-s3, LovyanGFX + LVGL9 als Dependencies)
├── include/
│   ├── secrets.h.example     (Platzhalter für WLAN)
│   ├── secrets.h             (lokal, nicht eingecheckt)
│   ├── board_pins.h          (Display-/Touch-Pinbelegung für WT32-SC01 Plus)
│   ├── theme.h               (Dark-Mode-Farbschema)
│   ├── text_utils.h          (UTF-8->ASCII-Transliteration)
│   └── date_utils.h          (Datumsformatierung ohne NTP)
├── src/
│   ├── main.cpp
│   ├── display/              (LovyanGFX-Setup, Rotation/Portrait-Konfiguration)
│   ├── ui/                   (LVGL-Screens: Home, WeatherDetail, CalendarDetail, MVG; Kachel-/Button-Widgets)
│   ├── api/                  (HTTP-Clients für Weather, Calendar, MVG – eigenständig implementiert)
│   └── icons/                (prozedurale LVGL-Canvas-Icons)
├── scripts/
│   ├── deploy.sh / deploy.cmd  (Build + Flash via PlatformIO CLI, kein Monitor)
│   └── build.sh / build.cmd    (Nur Build)
└── README.md                  (verweist als Referenz auf https://github.com/skoelle/m5stack-dashboard)

• deploy.sh ruft im Kern pio run --target upload auf; ohne Parameter automatische Port-Erkennung, mit Parameter (z.B. ./deploy.sh /dev/ttyUSB0) fester Port. Kein automatisches Starten des seriellen Monitors

11. Offene Punkte / Rückfragen

• Exakte Pinbelegung (Display-Datenbus, Touch-I2C-Pins, Backlight) muss anhand des konkret vorliegenden WT32-SC01-Plus-Boards verifiziert werden (Board-Revisionen unterscheiden sich in der Dokumentation leicht)
• Name des neuen GitHub-Repositories ist noch final zu bestätigen (Vorschlag: wt32sc01-dashboard)