kraftort/PLAN.md

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.