# 🚀 Battery Charging Optimizer - Installations-Anleitung

## Übersicht

Dieses System optimiert die Batterieladung basierend auf:
- ✅ Dynamischen Strompreisen (haStrom FLEX PRO)
- ✅ PV-Prognose (Forecast.Solar Ost/West)
- ✅ Batterie-SOC und Kapazität
- ✅ Haushalts-Reserve

**Besonderheit:** Nutzt dein bestehendes, bewährtes manuelles Steuerungssystem!

---

## 📋 Voraussetzungen

### Bereits vorhanden (✅):
1. **PyScript Integration** installiert und aktiviert
2. **OpenEMS** läuft auf BeagleBone mit GoodWe Batterie
3. **Modbus TCP Integration** für OpenEMS
4. **haStrom FLEX PRO** Sensor für Strompreise
5. **Forecast.Solar** Integration für PV-Prognose (Ost + West)
6. **Funktionierendes manuelles System**:
   - `pyscript/ess_set_power.py`
   - 3 Automationen für manuelles Laden
   - REST Commands für Mode-Wechsel
   - Input Helper `goodwe_manual_control` und `charge_power_battery`

### Zu installieren:
- Neue Konfigurationsdateien
- Neues Optimierungs-Script
- Dashboard (optional)

---

## 🔧 Installation

### Schritt 1: Konfiguration installieren

**Methode A: Als Package (empfohlen)**

1. Erstelle Verzeichnis `/config/packages/` falls nicht vorhanden
2. Kopiere `battery_optimizer_config.yaml` nach `/config/packages/`
3. In `configuration.yaml` sicherstellen:
   ```yaml
   homeassistant:
     packages: !include_dir_named packages
   ```

**Methode B: In configuration.yaml**

Kopiere den Inhalt von `battery_optimizer_config.yaml` in die entsprechenden Sektionen deiner `configuration.yaml`.

### Schritt 2: PyScript installieren

1. Kopiere `battery_optimizer.py` nach `/config/pyscript/`
2. **Wichtig:** Dein bestehendes `ess_set_power.py` bleibt unverändert!

### Schritt 3: Home Assistant neu starten

```bash
# Developer Tools → YAML → Restart
```

Oder über CLI:
```bash
ha core restart
```

### Schritt 4: Input Helper prüfen

Nach dem Neustart, gehe zu **Einstellungen → Geräte & Dienste → Helfer**

Folgende Helper sollten jetzt existieren:
- `input_boolean.battery_optimizer_enabled`
- `input_boolean.battery_optimizer_manual_override`
- `input_number.battery_capacity_kwh`
- `input_number.battery_optimizer_min_soc`
- `input_number.battery_optimizer_max_soc`
- `input_number.battery_max_charge_power`
- `input_number.battery_optimizer_price_threshold`
- `input_number.battery_reserve_capacity_kwh`
- `input_number.battery_optimizer_pv_threshold`
- `input_text.battery_optimizer_status`

**Falls nicht:** Prüfe die Konfiguration und Logs!

### Schritt 5: PyScript-Dienste prüfen

Gehe zu **Entwicklerwerkzeuge → Dienste**

Suche nach `pyscript` - folgende Dienste sollten vorhanden sein:
- `pyscript.calculate_charging_schedule`
- `pyscript.execute_charging_schedule`
- `pyscript.ess_set_power` (bestehend)

**Falls nicht:** 
- Prüfe `/config/pyscript/battery_optimizer.py` existiert
- Prüfe Logs: `custom_components.pyscript`

---

## ⚙️ Konfiguration

### Batterie-Parameter einstellen

Gehe zu **Einstellungen → Geräte & Dienste → Helfer** und setze:

1. **Batterie-Kapazität**: `10 kWh` (GoodWe)
2. **Min. SOC**: `20%` (Schutz vor Tiefentladung)
3. **Max. SOC**: `100%` (oder z.B. 90% für Langlebigkeit)
4. **Max. Ladeleistung**: `5000W` (5 kW - dein System-Limit)

### Optimierungs-Parameter anpassen

1. **Preis-Schwellwert**: `28 ct/kWh` (Startwert, wird automatisch angepasst)
2. **Reserve-Kapazität**: `2 kWh` (Reserve für Haushalt)
3. **PV-Schwellwert**: `500 Wh` (Bei mehr PV keine Netz-Ladung)

### Sensor-Namen prüfen

Falls deine Sensoren andere Namen haben, passe diese in `battery_optimizer.py` an:

```python
# Zeile ~100
sensor_east = 'sensor.energy_production_today'  # Dein Ost-Array
sensor_west = 'sensor.energy_production_today_2'  # Dein West-Array

# Zeile ~35
price_entity = 'sensor.hastrom_flex_pro'  # Dein Strompreis-Sensor

# Zeile ~185
current_soc = float(state.get('sensor.openems_ess0_soc') or 50)  # Dein SOC-Sensor
```

---

## 🧪 Testen

### Test 1: Manuelle Berechnung

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

**Erwartetes Ergebnis:**
- Log-Einträge in **Einstellungen → System → Protokolle**
- State `pyscript.battery_charging_schedule` existiert
- Attribute `schedule` enthält Array mit Stunden

**Prüfen in Developer Tools → Zustände:**
```
pyscript.battery_charging_schedule
Attributes:
  schedule: [...]
  last_update: 2025-11-09T17:30:00
  num_hours: 24
  num_charges: 3
```

### Test 2: Plan ansehen

```yaml
# Entwicklerwerkzeuge → Template
{{ state_attr('pyscript.battery_charging_schedule', 'schedule') }}
```

Sollte eine Liste mit Stunden-Einträgen zeigen:
```json
[
  {
    "datetime": "2025-11-09T23:00:00",
    "hour": 23,
    "action": "charge",
    "power_w": -5000,
    "price": 26.85,
    "reason": "Günstig (26.85 ct) + wenig PV (0 Wh)"
  },
  ...
]
```

### Test 3: Manuelle Ausführung

**ACHTUNG:** Nur testen wenn Batterie geladen werden kann!

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

**Was passiert:**
- Wenn aktuelle Stunde = Ladezeit → Aktiviert `input_boolean.goodwe_manual_control`
- Wenn nicht → Deaktiviert manuellen Modus

**Prüfen:**
- Log-Einträge zeigen welche Aktion ausgeführt wird
- Bei Ladung: `goodwe_manual_control` schaltet auf "on"
- Deine bestehende Automation übernimmt → Batterie lädt!

### Test 4: Automatische Zeitsteuerung warten

Die Zeit-Trigger sind aktiv:
- **14:05 Uhr täglich**: Neue Berechnung
- **xx:05 Uhr stündlich**: Ausführung

Warte bis zur nächsten vollen Stunde + 5 Min und prüfe Logs!

---

## 📊 Dashboard installieren (Optional)

1. Gehe zu deinem Lovelace Dashboard
2. **Bearbeiten** → **Raw-Konfigurations-Editor** (3 Punkte oben rechts)
3. Füge den Inhalt von `battery_optimizer_dashboard.yaml` ein

**Oder:** Manuell Cards erstellen über die UI

---

## 🔍 Troubleshooting

### Problem: "Keine Strompreis-Daten"

**Lösung:**
1. Prüfe Sensor `sensor.hastrom_flex_pro` existiert
2. Prüfe Attribut `hours` ist vorhanden:
   ```yaml
   # Developer Tools → Zustände
   sensor.hastrom_flex_pro
   Attributes:
     hours: [...]
   ```
3. Falls anderer Name → Anpassen in `battery_optimizer.py` Zeile ~35

### Problem: "Keine PV-Prognose"

**Lösung:**
1. Prüfe Forecast.Solar Sensoren existieren:
   - `sensor.energy_production_today`
   - `sensor.energy_production_today_2`
   - `sensor.energy_production_tomorrow`
   - `sensor.energy_production_tomorrow_2`
2. Falls andere Namen → Anpassen in `battery_optimizer.py` Zeile ~100

### Problem: PyScript-Dienste nicht sichtbar

**Lösung:**
1. Prüfe PyScript ist installiert: **HACS → Integrationen → PyScript**
2. Prüfe `/config/pyscript/battery_optimizer.py` existiert
3. Home Assistant neu starten
4. Logs prüfen: `grep pyscript /config/home-assistant.log`

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

**Lösung:**
1. Prüfe `input_boolean.battery_optimizer_enabled` ist "on"
2. Prüfe `input_boolean.battery_optimizer_manual_override` ist "off"
3. Prüfe deine bestehenden Automationen sind aktiv:
   - "Switch: Manuelle Speicherbeladung aktivieren"
   - "Automation: Speicher manuell laden"
4. Manuell testen:
   ```yaml
   service: input_boolean.turn_on
   target:
     entity_id: input_boolean.goodwe_manual_control
   ```
   → Sollte Ladung starten über deine Automation!

### Problem: "Keine Daten für aktuelle Stunde"

**Ursache:** Plan wurde zu spät erstellt oder enthält nicht alle Stunden

**Lösung:**
1. Plan manuell neu erstellen:
   ```yaml
   service: pyscript.calculate_charging_schedule
   ```
2. Prüfe ob tägliche Automation um 14:05 läuft
3. Plan sollte **aktuelle Stunde inkludieren**

---

## 🎓 Wie das System funktioniert

### Täglicher Ablauf

**14:05 Uhr:**
1. PyScript berechnet optimalen Ladeplan für nächste 24-36h
2. Berücksichtigt:
   - Strompreise (dynamischer Schwellwert = 90. Perzentil)
   - PV-Prognose Ost + West kombiniert
   - Aktueller Batterie-SOC
   - Konfigurierte Parameter
3. Speichert Plan als `pyscript.battery_charging_schedule` State

**Jede Stunde um xx:05:**
1. PyScript prüft was für aktuelle Stunde geplant ist
2. **Wenn "charge":**
   - Setzt `input_number.charge_power_battery` auf Ziel-Leistung
   - Aktiviert `input_boolean.goodwe_manual_control`
   - Deine Automation übernimmt → Schreibt alle 30s via Modbus
3. **Wenn "auto":**
   - Deaktiviert `goodwe_manual_control`
   - System läuft im Automatik-Modus

### Strategie-Logik

**Laden wenn:**
- Strompreis < dynamischer Schwellwert (90. Perzentil)
- UND PV-Prognose < 500 Wh für diese Stunde
- UND Batterie nicht voll
- Sortiert nach: Niedrigster Preis zuerst

**Nicht laden wenn:**
- Preis zu hoch
- Genug PV-Erzeugung erwartet
- Batterie voll (inkl. Reserve)

---

## 🚀 Nächste Schritte

### Nach erfolgreicher Installation:

1. **Erste Woche beobachten**
   - Prüfe Logs täglich
   - Verifiziere dass Plan erstellt wird (14:05)
   - Verifiziere dass Ausführung läuft (stündlich)
   - Prüfe ob Batterie zur richtigen Zeit lädt

2. **Parameter optimieren**
   - Preis-Schwellwert anpassen falls zu oft/selten lädt
   - PV-Schwellwert anpassen basierend auf Erfahrung
   - Reserve-Kapazität optimieren

3. **Statistiken sammeln**
   - Notiere Einsparungen
   - Vergleiche mit vorherigem Verbrauch
   - Dokumentiere für Community

4. **Community-Veröffentlichung vorbereiten**
   - Anonymisiere IP-Adressen und Passwörter
   - Erstelle README mit deinen Erfahrungen
   - Screenshots vom Dashboard
   - Beispiel-Logs

---

## 📝 Wartung

### Regelmäßig prüfen:
- Logs auf Fehler durchsuchen
- Plan-Qualität bewerten (gute Vorhersagen?)
- Sensor-Verfügbarkeit (Strompreis, PV-Forecast)

### Bei Problemen:
1. Logs prüfen: `custom_components.pyscript`
2. Sensor-Zustände prüfen
3. Manuell Plan neu berechnen
4. Bei Bedarf Parameter anpassen

---

## 🎉 Fertig!

Dein intelligentes Batterie-Optimierungs-System ist jetzt installiert und nutzt dein bewährtes manuelles Steuerungssystem als solide Basis.

**Das System wird:**
- ✅ Automatisch täglich planen (14:05)
- ✅ Automatisch stündlich ausführen (xx:05)
- ✅ Zu günstigsten Zeiten laden
- ✅ PV-Eigenverbrauch maximieren
- ✅ Stromkosten minimieren

**Viel Erfolg! ⚡💰**