battery-charging-optimizer/legacy/v1/INSTALLATION_GUIDE.md

# Batterie-Optimierung Installation Guide

## Übersicht

Dieses System optimiert die Batterieladung deines GoodWe/OpenEMS Systems basierend auf:
- Dynamischen Strompreisen (haStrom FLEX PRO)
- PV-Prognosen (Forecast.Solar)
- Batterie-Status und Kapazität

## System-Anforderungen

- ✅ Home Assistant mit PyScript Integration
- ✅ OpenEMS Edge auf BeagleBone (IP: 192.168.89.144)
- ✅ GoodWe Wechselrichter mit 10kWh Batterie
- ✅ Strompreis-Sensor (sensor.hastrom_flex_pro)
- ✅ Forecast.Solar Integration (Ost + West)

## Installation

### Schritt 1: PyScript Installation

Falls noch nicht installiert:

1. Über HACS → Integrationen → PyScript suchen und installieren
2. Home Assistant neu starten
3. Konfiguration → Integrationen → PyScript hinzufügen

### Schritt 2: Konfigurationsdateien

#### 2.1 Configuration.yaml erweitern

Füge den Inhalt aus `battery_optimizer_config.yaml` zu deiner `configuration.yaml` hinzu:

```yaml
# In configuration.yaml einfügen:
input_text: !include input_text.yaml
input_number: !include input_number.yaml
input_boolean: !include input_boolean.yaml
input_select: !include input_select.yaml
template: !include templates.yaml
rest_command: !include rest_commands.yaml
modbus: !include modbus.yaml
```

Oder direkt in die configuration.yaml kopieren (siehe battery_optimizer_config.yaml).

#### 2.2 REST Commands hinzufügen

Erstelle `rest_commands.yaml` oder füge zu deiner bestehenden Datei hinzu:
- Inhalt aus `battery_optimizer_rest_commands.yaml`

#### 2.3 Modbus Konfiguration

Falls noch nicht vorhanden, füge die Modbus-Konfiguration hinzu:

```yaml
modbus:
  - name: openems
    type: tcp
    host: 192.168.89.144
    port: 502
    sensors:
      - name: "OpenEMS Batterie Sollwert"
        address: 706
        data_type: float32
        scan_interval: 30
        unit_of_measurement: "W"
        device_class: power
```

### Schritt 3: PyScript Dateien kopieren

Kopiere die folgenden Dateien nach `/config/pyscript/`:

1. `battery_charging_optimizer.py` → `/config/pyscript/battery_charging_optimizer.py`
2. `battery_power_control.py` → `/config/pyscript/battery_power_control.py`

```bash
# Auf deinem Home Assistant System:
cd /config/pyscript/
# Dann Dateien hochladen via File Editor oder SSH
```

### Schritt 4: Automatisierungen erstellen

Füge die Automatisierungen aus `battery_optimizer_automations.yaml` hinzu:

**Option A: Über UI**
- Einstellungen → Automatisierungen & Szenen
- Jede Automatisierung manuell erstellen

**Option B: YAML**
- Zu `automations.yaml` hinzufügen
- Oder als separate Datei inkludieren

### Schritt 5: Home Assistant neu starten

Vollständiger Neustart erforderlich für:
- Neue Input Helper
- REST Commands
- Modbus Konfiguration
- PyScript Module

### Schritt 6: Initial-Konfiguration

Nach dem Neustart:

1. **Input Helper prüfen**
   - Einstellungen → Geräte & Dienste → Helfer
   - Alle "Batterie Optimizer" Helfer sollten vorhanden sein

2. **Grundeinstellungen setzen**
   - `input_number.battery_optimizer_min_soc`: 20%
   - `input_number.battery_optimizer_max_soc`: 100%
   - `input_number.battery_optimizer_price_threshold`: 28 ct/kWh
   - `input_number.battery_optimizer_max_charge_power`: 10000 W
   - `input_number.battery_optimizer_reserve_capacity`: 2 kWh
   - `input_select.battery_optimizer_strategy`: "Konservativ (nur sehr günstig)"

3. **Optimierung aktivieren**
   - `input_boolean.battery_optimizer_enabled`: AN

4. **Ersten Plan berechnen**
   - Entwicklerwerkzeuge → Dienste
   - Dienst: `pyscript.calculate_charging_schedule`
   - Ausführen

### Schritt 7: Dashboard einrichten (optional)

Füge eine neue Ansicht in Lovelace hinzu:
- Inhalt aus `battery_optimizer_dashboard.yaml`

## Test & Verifizierung

### Test 1: Manuelle Plan-Berechnung

```yaml
# Entwicklerwerkzeuge → Dienste
service: pyscript.calculate_charging_schedule
```

Prüfe danach:
- `input_text.battery_charging_schedule` sollte JSON enthalten
- Logs prüfen: Einstellungen → System → Protokolle

### Test 2: Manuelles Laden testen

```yaml
# Entwicklerwerkzeuge → Dienste
service: pyscript.start_charging_cycle
data:
  power_w: -3000  # 3kW laden
```

Prüfe:
- `sensor.battery_power` sollte ca. -3000W zeigen
- ESS Mode sollte REMOTE sein
- Nach 1 Minute stoppen:

```yaml
service: pyscript.stop_charging_cycle
```

### Test 3: Automatische Ausführung

Warte auf die nächste volle Stunde (xx:05 Uhr).
Die Automation sollte automatisch:
- Den Plan prüfen
- Bei Ladestunde: Laden aktivieren
- Sonst: Automatik-Modus

## Konfiguration & Tuning

### Strategien

**Konservativ (empfohlen für Start)**
- Lädt nur bei sehr günstigen Preisen
- Minimales Risiko
- Schwellwert: Min-Preis + 30% der Spanne

**Moderat**
- Lädt bei allen Preisen unter Durchschnitt
- Ausgewogenes Verhältnis
- Schwellwert: Durchschnittspreis

**Aggressiv**
- Maximale Arbitrage
- Lädt bei Preisen unter 70% des Durchschnitts
- Kann auch Entladung bei hohen Preisen umsetzen (noch nicht implementiert)

### Wichtige Parameter

**Preis-Schwellwert** (`input_number.battery_optimizer_price_threshold`)
- Maximum das du bereit bist zu zahlen
- Bei "Konservativ": Wird automatisch niedriger gesetzt
- Beispiel: 28 ct/kWh → lädt nur wenn Preis < 28 ct

**Reserve-Kapazität** (`input_number.battery_optimizer_reserve_capacity`)
- Wie viel kWh für Eigenverbrauch reserviert bleiben sollen
- Verhindert, dass Batterie komplett für günstiges Laden "verbraucht" wird
- Beispiel: 2 kWh → max. 8 kWh werden aus Netz geladen

**Min/Max SOC**
- Schützt die Batterie
- Standard: 20-100%
- Kann je nach Batterietyp angepasst werden

## Erweiterte Funktionen

### Keep-Alive

Das System schreibt alle 30 Sekunden die Leistung neu, um Timeouts im REMOTE-Mode zu verhindern.

### Notfall-Stop

Bei Problemen:

```yaml
service: pyscript.emergency_stop
```

Deaktiviert sofort:
- Alle manuellen Steuerungen
- Automatisierungen
- Setzt ESS zurück auf INTERNAL/Auto

### Manueller Override

Aktiviere `input_boolean.battery_optimizer_manual_override` um:
- Automatische Ausführung zu pausieren
- System läuft weiter im Hintergrund
- Wird nach 4 Stunden automatisch deaktiviert

## Monitoring & Logs

### Log-Level einstellen

In `configuration.yaml`:

```yaml
logger:
  default: info
  logs:
    custom_components.pyscript: debug
    custom_components.pyscript.file.battery_charging_optimizer: debug
    custom_components.pyscript.file.battery_power_control: debug
```

### Wichtige Log-Meldungen

- "Batterie-Optimierung gestartet" → Plan wird berechnet
- "Strompreise geladen: X Stunden" → Preisdaten OK
- "Geplante Ladungen: X Stunden" → Anzahl Ladestunden
- "Aktiviere Laden: XW" → Ladezyklus startet
- "Keep-Alive: Schreibe XW" → Timeout-Verhinderung

## Troubleshooting

### Problem: Kein Ladeplan erstellt

**Ursache**: Strompreise nicht verfügbar
**Lösung**: 
- Prüfe `sensor.hastrom_flex_pro`
- Warte bis 14:05 Uhr
- Manuell triggern: `pyscript.calculate_charging_schedule`

### Problem: Batterie lädt nicht trotz Plan

**Ursache**: OpenEMS antwortet nicht
**Lösung**:
- Prüfe REST Commands einzeln
- Teste: `rest_command.set_ess_remote_mode`
- Prüfe OpenEMS Logs auf BeagleBone

### Problem: Laden stoppt nach kurzer Zeit

**Ursache**: Keep-Alive funktioniert nicht
**Lösung**:
- Prüfe PyScript Logs
- Prüfe `pyscript.battery_charging_active` State
- Neu starten: `pyscript.start_charging_cycle`

### Problem: Unrealistische Ladepläne

**Ursache**: PV-Prognose oder Verbrauch falsch
**Lösung**:
- Prüfe Forecast.Solar Sensoren
- Passe `input_number.battery_optimizer_reserve_capacity` an
- Ändere Strategie auf "Konservativ"

## Nächste Schritte / Erweiterungen

### Phase 2: InfluxDB Integration
- Historische Verbrauchsdaten nutzen
- Bessere Vorhersagen
- Lernender Algorithmus

### Phase 3: Erweiterte PV-Prognose
- Stündliche Verteilung statt Tagessumme
- Wetterabhängige Anpassungen
- Cloud-Cover Berücksichtigung

### Phase 4: Arbitrage-Funktion
- Entladung bei hohen Preisen
- Peak-Shaving
- Netzdienliche Steuerung

### Phase 5: Machine Learning
- Verbrauchsprognose
- Optimierte Ladezeiten
- Selbstlernende Parameter

## Support & Logs

Bei Problemen bitte folgende Informationen bereitstellen:

1. Home Assistant Version
2. PyScript Version
3. Relevante Logs aus "Einstellungen → System → Protokolle"
4. Screenshots der Input Helper Werte
5. `input_text.battery_charging_schedule` Inhalt

## Sicherheitshinweise

⚠️ **Wichtig**:
- System greift direkt in Batteriesteuerung ein
- Bei Fehlfunktion kann Batterie beschädigt werden
- Überwache die ersten Tage intensiv
- Setze sinnvolle SOC-Grenzen
- Nutze Notfall-Stop bei Problemen

✅ **Best Practices**:
- Starte mit konservativer Strategie
- Teste erst mit kleinen Ladeleistungen
- Überwache Batterie-Temperatur
- Prüfe regelmäßig die Logs
- Halte OpenEMS aktuell

## Lizenz & Haftung

Dieses System wird "as-is" bereitgestellt.
Keine Haftung für Schäden an Hardware oder Datenverlust.
Verwendung auf eigene Gefahr.

---

**Version**: 1.0
**Datum**: 2025-11-07
**Autor**: Felix's Batterie-Optimierungs-Projekt