# Kraftort

V1-Firmware-Grundgeruest fuer ein tragbares ESP32-GPS-Geraet, das Naehe und Richtung zu konfigurierten Kraftorten auf einem 54er-WS2812B-Ring anzeigt.

## Status-Überblick
Details zu erledigten, laufenden und geplanten Aufgaben stehen in [STATUS.md](STATUS.md).

## V1-Status

Implementiert:

- PlatformIO-Projekt mit `Arduino` auf ESP32
- Modulare Firmware-Struktur (`gps`, `geo`, `button`, `leds`, `state_machine`, `power`, `ble_maintenance`)
- Nicht-blockierende Main Loop mit State Machine
- GPS-Datenstruktur und NMEA-Parser-Grundstruktur (`RMC`, `GGA`)
- Geo-Funktionen (Haversine, Bearing, Scoring, LED-Mapping, nearest place)
- Button-Grundlogik (Debounce, Short/Long-Press)
- LED-Renderer-Grundstruktur mit Zustandsszenen
- `places.json`-Laden via LittleFS
- LittleFS/places.json loader gibt Fehler jetzt direkt per Serial aus, damit fehlende oder korrupte Konfigurationen sichtbar bleiben.
- BLE-Maintenance-State loggt das Fenster und reagiert auf einfache Serial-Kommandos (`status`, `stop`, `help`) als pragmatischen Platzhalter.
- Einfache Unity-Tests fuer Geo und State Machine

Noch Stub in V1:

- BLE-Maintenance-Details (Service/Characteristics/Upload- und OTA-Pfad) bleiben Stub, die Serial-Kommandos sind nur pragmatische Platzhalter.
- Erweiterte LED-Themes/Animationen
- Erweiterte GPS-Qualitaetsheuristiken

## Build und Test

Voraussetzung: installiertes `platformio` CLI.

```bash
pio run -e esp32dev
```

Tests lokal (native):

```bash
pio test -e native
```

Native Unity-Tests decken Geo-Mathematik, State-Transitions und Ausnahmef�lle ab (BLE-Timeouts ohne Button, R�ckfall auf `GpsWait` bei Fix-Verlust, DeepSleep aus Long-Press, etc.).

Optional auf Hardware:

```bash
pio run -e esp32dev -t upload
pio device monitor -b 115200
```

## Projektstruktur

- `src/main.cpp`: Setup, Main Loop, Modulverdrahtung
- `src/config.h`: zentrale Konstanten
- `src/state_machine.*`: Betriebszustaende und Uebergaenge
- `src/geo.*`: Geometrie, Scoring und Zielauswahl
- `src/gps.*`: GPS-Datenmodell + NMEA-Parser-Grundlage
- `src/button.*`: Button-Events
- `src/leds.*`: LED-Rendering-Basis
- `src/ble_maintenance.*`: BLE-Wartung (Stub mit stabiler Schnittstelle)
- `src/power.*`: Deep-Sleep-Einstieg
- `data/places.json`: Beispiel-Kraftorte
- `tests/`: Unity-Tests

## Hardware-Default-Konfiguration (V1)

- ESP32 DevKit (`esp32dev`)
- GPS UART1: RX `GPIO16`, TX `GPIO17`, `9600 baud`
- WS2812B Data: `GPIO5`
- Button: `GPIO0` (active-low)

Alle Parameter sind zentral in `src/config.h` gepflegt.