# Kraftort – Umsetzungsplan

## Ziel

Ein portables ESP32-Gerät, das per GPS den nächsten Kraftort bestimmt und dessen Richtung bzw. Intensität auf einem 54er-WS2812B-Ring visualisiert.

## Leitideen

- klare Modultrennung
- keine Magic Numbers im Code
- nicht-blockierende Main Loop
- robust gegenüber GPS-Ausfällen
- BLE-Wartungsfenster direkt nach dem Boot
- LittleFS für Orte-Konfiguration
- testbare Geometrie- und Entscheidungslogik

## Projektphasen

### Phase 1 – Grundgerüst
- PlatformIO-Projekt anlegen
- Verzeichnisstruktur gemäss Spezifikation erzeugen
- `platformio.ini` vorbereiten
- Header-/CPP-Skelette für alle Module anlegen
- Beispiel-Konfigurationsdateien hinzufügen

### Phase 2 – Hardware-Basis
- LED-Basisfunktion testen
- Button-Handling mit Debounce und Long-Press umsetzen
- GPS-UART initialisieren und Rohdaten prüfen
- LittleFS initialisieren

### Phase 3 – GPS und Geo
- `GPSData`-Struktur definieren
- TinyGPSPlus anbinden
- Fix-Validierung implementieren
- EMA-Filter für Geschwindigkeit
- Haversine, Bearing und Score-Funktionen implementieren
- Unit-Tests für Geo-Funktionen erstellen

### Phase 4 – Zustandsmaschine
- Zustände `BOOT`, `BLE_MAINTENANCE`, `GPS_WAIT`, `ACTIVE`, `DEEP_SLEEP`
- definierte Übergänge implementieren
- BLE-Fenster-Timeout integrieren
- GPS-Fix-Stabilität und -Verlust sauber behandeln

### Phase 5 – Zielauswahl und LED-Rendering
- nächstgelegenen Kraftort bestimmen
- Hysterese gegen Flattern implementieren
- Richtungsmodus bei Bewegung
- Score-Modus im Stand
- On-Target-Aura
- Themes CALM, PULSE, AURORA
- Framerate-Steuerung und Gamma-Korrektur

### Phase 6 – BLE-Wartung
- NimBLE-Service definieren
- Upload von `places.json`
- OTA-Datenpfad vorbereiten
- Status-Notify implementieren
- BLE nach Timeout oder Disconnect sauber deinitialisieren

### Phase 7 – Power und Integration
- Deep Sleep über Long Press
- Wake-up über Button
- Logging standardisieren
- Fehlerfälle sauber behandeln
- Watchdog integrieren

### Phase 8 – Tests und Doku
- Unity-Tests für Geo und Arbitration
- Build-Workflow für GitHub Actions
- Pinout- und Wiring-Doku
- BLE-Protokoll dokumentieren
- Flash-/Nutzungsanleitung vervollständigen

## Dateien, die angelegt werden sollen

### Root
- `README.md`
- `CHANGELOG.md`
- `platformio.ini`
- `PLAN.md`

### src/
- `main.cpp`
- `gps.cpp`, `gps.h`
- `geo.cpp`, `geo.h`
- `leds.cpp`, `leds.h`
- `button.cpp`, `button.h`
- `ble_maintenance.cpp`, `ble_maintenance.h`
- `power.cpp`, `power.h`
- `config.h`
- `state_machine.cpp`, `state_machine.h`

### data/
- `places.json`

### docs/
- `architecture.md`
- `ble_protocol.md`
- später: `pinout.png`, `state_machine.png`

### hw/
- `bom.txt`
- `wiring_notes.txt`

### tests/
- `test_geo.cpp`
- `test_arbitration.cpp`

### .github/workflows/
- `build.yml`

## Technische Entscheidungen

- **ESP32 Arduino Core + PlatformIO** wegen einfacher Embedded-Iteration
- **TinyGPSPlus** für NMEA Parsing
- **FastLED** für den Ring
- **NimBLE-Arduino** statt klassischem BLE wegen geringerem Ressourcenverbrauch
- **LittleFS** für `places.json`
- **Single-threaded cooperative loop** statt separater Tasks für geringere Komplexität

## Reihenfolge für die Implementierung

1. Skeleton + Build-Konfiguration
2. LED-Test und Hardware-Validierung
3. GPS Parser + Fix-Qualität
4. Geo-Funktionen + Tests
5. State Machine
6. LED-Renderer
7. Target Arbitration
8. BLE Maintenance
9. Deep Sleep
10. Integration + Outdoor-Test

## Abnahmekriterien

- Boot bis sichtbare LED-Rückmeldung in unter 1.5 s
- Stabiler Übergang in ACTIVE nach gültigem Fix
- Richtungsanzeige plausibel bei Bewegung
- Intensität steigt nachvollziehbar mit Nähe
- Kein sichtbares Flackern
- Sauberer Rückfall in GPS_WAIT bei Fix-Verlust
- BLE-Fenster nach Boot sichtbar und danach verschwunden
- Keine Speicherdrift > 10 % im Dauertest

## Nächster konkreter Schritt

Als nächstes wird das vollständige PlatformIO-Skelett mit allen Headern, CPP-Dateien, Beispieltests und Basis-Konfiguration erzeugt.