m5stack-dashboard/PLAN.md

PLAN.md – Umsetzungsplan M5Stack Dashboard

Letztes Update: 2026-08-01 23:18 CEST

Dieses Dokument beschreibt, in welcher Reihenfolge und mit welchem Ansatz das Projekt aus SPEC-final.md umgesetzt wird. Ziel ist ein iteratives Vorgehen mit kleinen, in sich funktionierenden Schritten, sodass nach jedem Schritt ein sichtbares Ergebnis auf dem M5Stack Core zu sehen ist.

Leitprinzip

Jeder Schritt wird als eigener, eng gefasster Prompt an OpenCode gegeben. Kein Schritt soll mehr als 20-30 Minuten inkl. Flash und Test auf dem Gerät dauern. Erst wenn ein Schritt lauffähig ist, wird der nächste angegangen.

Phase 0 – Projekt-Grundgerüst

Ziel: Ein leeres, aber lauffähiges PlatformIO-Projekt, das auf dem M5Stack Core bootet und einen Testtext anzeigt.

• PlatformIO-Projekt für M5Stack Core anlegen (platformio.ini mit passendem Board, Framework Arduino, M5Stack-Library als Dependency)
• Ordnerstruktur gemäß SPEC-final.md Abschnitt 10 anlegen (include/, src/screens/, src/api/, src/icons/, scripts/)
• secrets.h.example mit Platzhaltern für WLAN SSID/Passwort anlegen, .gitignore vorbereiten (auch wenn Git noch nicht initialisiert wird)
• Minimaler main.cpp, der nur "Hello Dashboard" auf dem Display zeigt
• scripts/deploy.sh erstellen: Build + Flash via PlatformIO CLI, automatische Port-Erkennung mit optionalem Port-Parameter

Abnahmekriterium: ./scripts/deploy.sh baut und flasht erfolgreich, Display zeigt Testtext.

Phase 1 – WLAN & HTTP-Grundlage

Ziel: Das Gerät verbindet sich mit dem WLAN und kann eine der drei APIs erfolgreich abrufen und als Rohtext auf dem Display anzeigen.

• WLAN-Verbindung mit secrets.h-Werten aufbauen, Verbindungsstatus auf Display anzeigen
• Generischen HTTP-GET-Client (src/api/) bauen, der eine URL abruft und den Response-Body zurückgibt
• JSON-Parsing-Library einbinden (z.B. ArduinoJson)
• Testweise Wetter-API abrufen und Rohwerte (Temperatur, Beschreibung) als Text anzeigen

Abnahmekriterium: Aktuelle Temperatur von der echten Wetter-API wird nach Boot auf dem Display angezeigt.

Phase 2 – Screen-Grundgerüst & Navigation

Ziel: Die Screen-Struktur und Button-Navigation stehen, noch ohne fertiges Design.

• Screen-Abstraktion bauen (z.B. einfaches State-Machine-Pattern: aktueller Screen als Enum, Render-Funktion pro Screen)
• Vier Screens als leere Platzhalter anlegen: Home, WeatherDetail, CalendarDetail, MVG
• Button-Logik gemäß SPEC-final.md Abschnitt 6 umsetzen (A: Toggle Wetter/Kalender-Detail, B: zurück zu Home, C: MVG-Screen)
• 5-Minuten-Inaktivitäts-Timeout implementieren, der zurück zu Home springt
• Grundlegendes Farbschema (schwarz/weiß, iOS-Dark-Mode-Look) als globale Konstanten/Theme-Datei anlegen

Abnahmekriterium: Mit den drei Buttons kann zuverlässig zwischen allen vier Screens (Platzhaltertexte reichen) navigiert werden, Timeout funktioniert.

Phase 3 – Home-Screen (final)

Ziel: Der wichtigste Screen ist fertig gestaltet und mit echten Daten befüllt.

• Wetter-API und Kalender-API in den Home-Screen integrieren
• Weicher Regen-Hinweis über die nächsten 8 Vorhersage-Stunden implementieren (Banner/Icon)
• Anzeige der nächsten 2 Kalendertermine inkl. Sonderbehandlung für all_day
• 10-Minuten-Refresh-Timer implementieren
• Layout und Typografie gemäß UI-Konzept (Abschnitt 7) verfeinern: große Temperatur, klare Hierarchie

Abnahmekriterium: Home-Screen zeigt aktuelles Wetter, Regen-Hinweis (wenn zutreffend) und die nächsten 2 Termine an, aktualisiert sich automatisch alle 10 Minuten.

Phase 4 – Icon-Set (farbig, RGB565)

Ziel: Text-Platzhalter werden durch die im UI-Konzept beschriebenen farbigen Bitmap-Icons ersetzt.

• Icon-Liste finalisieren (Sonne/klar, bewölkt, Regen, Nacht-Varianten, U-Bahn, S-Bahn, Kalender, Regen-Warnung, Retry/Fehler)
• Icons als RGB565-Bitmap-Arrays erzeugen (z.B. per Konvertierungsskript aus PNG-Vorlagen) und in src/icons/ ablegen
• Icons in Home-Screen integrieren (Wettericon, Regen-Warnsymbol)
• Mapping von symbol-Feld (z.B. mo____, mb____, wb____) auf das jeweilige Icon implementieren

Abnahmekriterium: Home-Screen nutzt farbige Icons statt reinem Text für Wetterzustand und Regen-Hinweis.

Phase 5 – Wetter-Detailseite

Ziel: Vollständige stundenweise Vorhersage mit Icons.

• Abruf und Darstellung der vollständigen forecast-Liste (bis zu 8 Stunden)
• Pro Stunde: Zeit, Temperatur, Icon, Regenwahrscheinlichkeit
• Scroll- oder Paginierungslogik falls nicht alle Einträge auf einen Screen passen

Abnahmekriterium: Über Button A von Home aus erreichbar, zeigt stündliche Vorhersage mit Icons korrekt an.

Phase 6 – Kalender-Detailseite

Ziel: Vollständige Terminliste.

• Abruf und Darstellung aller 10 Termine aus der Kalender-API
• Gleiche Sonderbehandlung für all_day wie auf der Hauptseite
• Scroll-/Paginierungslogik analog zu Phase 5

Abnahmekriterium: Über Button A (Toggle von Wetter-Detail) erreichbar, zeigt alle 10 Termine übersichtlich an.

Phase 7 – MVG-Abfahrtsseite

Ziel: Vollständige, ungefilterte Abfahrtenliste mit 1-Minuten-Refresh.

• Abruf und Darstellung aller Einträge aus departures (beide Stationen, U- und S-Bahn gemischt)
• Farbliche Kennzeichnung U-Bahn vs. S-Bahn (dezente Akzentfarben gemäß Theme)
• Darstellung von Verspätung (delay_min) und Ausfall (cancelled)
• 1-Minuten-Refresh-Timer implementieren

Abnahmekriterium: Über Button C von jedem Screen aus erreichbar, zeigt aktuelle Abfahrten an, aktualisiert sich jede Minute.

Phase 8 – Fehlerbehandlung

Ziel: Robustheit bei nicht erreichbaren APIs.

• Timeout- und Fehlerbehandlung für alle drei API-Clients implementieren
• Einheitliche Fehleranzeige (Retry-Icon + Text) pro betroffenem Screen
• Retry-Logik: automatisch beim nächsten regulären Refresh-Intervall, zusätzlich manuell durch erneuten Tastendruck auf den jeweiligen Screen-Button

Abnahmekriterium: Bei simuliertem API-Ausfall (z.B. Docker-Service kurz stoppen) zeigt das Gerät eine saubere Fehlermeldung statt abzustürzen oder hängen zu bleiben, und erholt sich automatisch nach Wiederverfügbarkeit.

Phase 9 – Politur & Feinschliff

Ziel: Letzter Schliff für ein rundes Gesamtbild.

• Konsistenzprüfung aller Screens gegen das UI-Konzept (Kontrast, Schriftgrößen, Abstände)
• Performance-Check (Speicherverbrauch, Rendering-Geschwindigkeit bei Refresh)
• Code-Aufräumen, Kommentare, README.md mit Setup-Anleitung (WLAN-Konfiguration, Flash-Vorgang) schreiben

Abnahmekriterium: Projekt läuft stabil im Dauerbetrieb, README erklärt Setup für zukünftiges Ich.

Spätere Schritte (nicht Teil dieser Phasen)

• Git-Repository initialisieren und optional mit GitHub/GitLab-Remote verknüpfen (bewusst erst nach funktionierendem Code, siehe SPEC-final.md Abschnitt 3)