AGENTS.md

Projektübersicht

WT32-SC01 Plus Dashboard für ESP32-S3 (3.5" kapazitiver Touch-IPS-Display, 320×480 Hochformat). Zeigt Wetter, Kalendertermine und MVG-Abfahrten an, gesteuert ausschließlich über Touch.

Tech-Stack:

PlatformIO mit Arduino-Framework
LovyanGFX als Display-/Touch-Treiber
LVGL 9 für UI-Widgets
ESP32-S3 mit PSRAM

Wichtige Dateien

platformio.ini - Build-Konfiguration, Board-Einstellungen, Abhängigkeiten
include/board_pins.h - Pinbelegung für WT32-SC01 Plus
include/secrets.h - WLAN-Zugangsdaten (nicht im Repo)
include/theme.h - Dark-Mode-Farbschema
src/main.cpp - Screen-Controller, Navigation, Inaktivitäts-Timer
src/ui/screen_base.h - Screen-Lifecycle (create/show/refresh/tick)
src/ui/home_screen.* - Hauptseite mit 3 Touch-Kacheln
src/ui/weather_detail_screen.* - Wetter-Detailseite
src/ui/calendar_detail_screen.* - Kalender-Detailseite
src/ui/mvg_screen.* - MVG-Abfahrtsseite
src/api/ - HTTP-Clients für Wetter, Kalender, MVG
src/icons/ - Prozedurale LVGL-Canvas-Icons
scripts/deploy.sh / deploy.cmd - Build + Flash
scripts/build.sh / build.cmd - Nur Build

Build & Deploy

# Build + Flash (automatische Port-Erkennung)
./scripts/deploy.sh

# Build + Flash mit explizitem Port
./scripts/deploy.sh /dev/ttyUSB0

# Nur Build (ohne Flash) - Erfordert virtuelle Umgebung
.venv-platformio/bin/pio run

# Serieller Monitor
pio device monitor

Projektstruktur

/
├── platformio.ini              # esp32-s3, LovyanGFX + LVGL9
├── lv_conf.h                   # LVGL-Konfiguration
├── include/
│   ├── board_pins.h            # WT32-SC01-Plus-Pinout
│   ├── secrets.h.example       # Platzhalter für WLAN/API-URLs
│   ├── theme.h                 # Dark-Mode-Farbschema (LVGL)
│   ├── text_utils.h            # UTF-8->ASCII-Transliteration
│   └── date_utils.h            # Datumsformatierung (kein NTP)
├── src/
│   ├── main.cpp                # Screen-Controller + Inaktivitäts-Timer
│   ├── display/                # LovyanGFX-Setup + LVGL-Anbindung
│   ├── ui/                     # Screens + wiederverwendbare Widgets
│   │   ├── screen_base.h       # Screen-Lifecycle (create/show/refresh/tick)
│   │   ├── home_screen.*       # 3 Touch-Kacheln
│   │   ├── weather_detail_screen.*
│   │   ├── calendar_detail_screen.*
│   │   ├── mvg_screen.*
│   │   └── widgets/            # tile_button, back_button
│   ├── api/                    # HTTP-Clients (1:1 aus m5stack-dashboard)
│   └── icons/                  # prozedurale LVGL-Canvas-Icons
├── scripts/
│   ├── deploy.sh / deploy.cmd  # Build + Flash
│   └── build.sh / build.cmd    # Nur Build
└── docs/                       # Migrationshistorie (SPEC-old, PLAN, TODO)

Screen-Architektur

Jeder Screen implementiert die Screen-Struktur aus screen_base.h:

create_fn() - Baut UI-Komponenten einmalig beim ersten Aufruf
refresh_fn() - Holt neue Daten und aktualisiert Widgets
tick_fn() - Wird jeden Loop-Durchlauf aufgerufen (für Timer)
show() - Zeigt den Screen (erstellt ihn bei Bedarf)

Navigation erfolgt über navigate(ScreenId) Funktion in main.cpp.

API-Endpunkte

Alle APIs liefern JSON per HTTP GET (URLs in include/secrets.h konfigurierbar):

Wetter: /api/weather
Kalender: /api/events
MVG: /api/departures

Refresh-Intervalle

Seite	Intervall	Background-Refresh
Hauptseite (Wetter + Kalender)	10 Minuten	Ja (data_manager)
MVG-Abfahrtsseite	1 Minute	Nein (nur tick())
Detailseiten	Folgen Hauptseiten-Intervall	Ja (data_manager)

Coding-Konventionen

C++ mit Arduino-Framework
Keine externen Libraries außer: LovyanGFX, LVGL 9, ArduinoJson
Screen-Dateien: *_screen.h + *_screen.cpp
API-Dateien: *_api.h + *_api.cpp
Widgets in src/ui/widgets/
Icons als prozedurale LVGL-Canvas-Objekte (keine Bitmaps)
Dark-Mode-Farbschema mit #000000/#0B0B0D Hintergrund
Touch-taugliche Mindestgröße: ≥ 80-100 px Höhe
UTF-8-Transliteration für deutsche Umlaute (text_utils.h)

Fehlerbehandlung

Bei nicht erreichbarer API: Fehleranzeige auf Screen/Kachel, letzte gültige Daten bleiben erhalten (außer MVG: nur aktuelle Daten, kein Background-Refresh)
Retry automatisch beim nächsten Refresh-Intervall
Manueller Retry durch erneutes Antippen der Kachel
Kein "letzter bekannter Wert" über Fehlerzustand hinaus

Referenzprojekt

Vorgängerprojekt mit M5Stack Core: https://github.com/skoelle/m5stack-dashboard (Funktionalität übernommen, komplett neu geschrieben für WT32-SC01 Plus)

4.9 KiB Raw Permalink Blame History Unescape Escape