# 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)