battery-charging-optimizer/FIX_CHARGING_CAPACITY.md

# Fix: Batterie wird nicht immer bis 100% geladen

## Problem

Die Batterie wird nicht immer bis 100% geladen, obwohl genug Zeit und günstige Stunden verfügbar sind.

### Ursache

Die Ladekapazität wird um **14:05 Uhr** berechnet, basierend auf dem SOC zu diesem Zeitpunkt:

**Beispiel:**
```
14:05 Uhr:
  SOC: 14%
  Benötigt: (100% - 14%) × 10kWh - 2kWh Reserve = 6.6 kWh
  Bei 5000W: 6.6kWh ÷ 5kW = 1.32h → 2 Stunden
  Geplant: 22:00 + 23:00
```

**ABER zwischen 14:05 und 22:00:**
- ☀️ PV-Nachproduktion (Nachmittag)
- 🏠 Eigenverbrauch aus Batterie
- 🔋 SOC ändert sich (z.B. auf 30%)

**Um 22:00** (Ladestart):
```
  SOC: 30% (nicht mehr 14%!)
  Benötigt: (100% - 30%) × 10kWh = 7.0 kWh
  Geplant: 2h × 5kW = 10kWh - 2kWh Reserve = 8 kWh
  → Zu wenig!
```

## Lösung: Sicherheitspuffer

### Implementierung v3.4.0

**Neuer konfigurierbarer Sicherheitspuffer** von 20% (Standard) wird zur berechneten Ladekapazität hinzugefügt.

**Code-Änderungen** (Zeile 300-319):
```python
# Verfügbare Ladekapazität berechnen
available_capacity_wh = (config['max_soc'] - current_soc) / 100 * config['battery_capacity']
available_capacity_wh -= config['reserve_capacity']

# SICHERHEITSPUFFER: +20% für untertägige Schwankungen
safety_buffer = config['safety_buffer']  # z.B. 0.20 = 20%
available_capacity_wh_with_buffer = available_capacity_wh * (1 + safety_buffer)

log.info(f"Verfügbare Ladekapazität (berechnet): {available_capacity_wh/1000:.2f} kWh")
log.info(f"Verfügbare Ladekapazität (mit {safety_buffer*100:.0f}% Puffer): {available_capacity_wh_with_buffer/1000:.2f} kWh")

# Berechne benötigte Ladestunden mit Puffer
needed_hours = int((available_capacity_wh_with_buffer + max_charge_per_hour - 1) / max_charge_per_hour)
```

**Neues Beispiel mit Puffer:**
```
14:05 Uhr:
  SOC: 14%
  Benötigt (ohne Puffer): 6.6 kWh
  Benötigt (mit 20% Puffer): 6.6 × 1.2 = 7.92 kWh
  Bei 5000W: 7.92kWh ÷ 5kW = 1.58h → 2 Stunden (bleibt gleich)
  ODER bei niedrigerem Start-SOC → 3 Stunden

Um 22:00:
  SOC: 30%
  Geplant: 2-3h × 5kW = 10-15kWh → Reicht jetzt!
```

## Konfiguration

### Neuer Input Helper

**In `configuration.yaml` oder via UI erstellen:**

```yaml
input_number:
  battery_optimizer_safety_buffer:
    name: "Batterie Optimizer: Sicherheitspuffer"
    min: 0
    max: 50
    step: 5
    unit_of_measurement: "%"
    icon: mdi:shield-plus
    mode: slider
    initial: 20
```

**Werte-Empfehlungen:**

| Puffer | Anwendungsfall |
|--------|----------------|
| 0% | Kein Puffer - exakte Berechnung (nicht empfohlen) |
| 10% | Stabile Bedingungen, wenig Eigenverbrauch |
| **20%** | **Standard** - Normale Bedingungen |
| 30% | Hoher Eigenverbrauch am Abend |
| 40% | Sehr dynamische Bedingungen |
| 50% | Maximum - nahezu garantiert volle Ladung |

### Installation

**Schritt 1: Input Helper erstellen**

**Via UI** (Empfohlen):
1. Einstellungen → Geräte & Dienste → Helfer
2. "Helfer hinzufügen" → "Zahl"
3. Name: `Batterie Optimizer: Sicherheitspuffer`
4. Entity ID: `input_number.battery_optimizer_safety_buffer`
5. Minimum: 0
6. Maximum: 50
7. Schritt: 5
8. Einheit: %
9. Modus: Slider
10. Anfangswert: 20

**Via YAML**:
```yaml
# In configuration.yaml
input_number:
  battery_optimizer_safety_buffer:
    name: "Batterie Optimizer: Sicherheitspuffer"
    min: 0
    max: 50
    step: 5
    unit_of_measurement: "%"
    icon: mdi:shield-plus
    mode: slider
```

Dann: Konfiguration neu laden

**Schritt 2: Script aktualisieren**

```bash
cp openems/battery_charging_optimizer.py /config/pyscript/
```

```yaml
service: pyscript.reload
data: {}
```

**Schritt 3: Neue Berechnung triggern**

```yaml
service: pyscript.calculate_charging_schedule
data: {}
```

Prüfe die Logs:
```
Verfügbare Ladekapazität (berechnet): 6.60 kWh
Verfügbare Ladekapazität (mit 20% Puffer): 7.92 kWh
🎯 Benötigte Ladestunden: 2 (bei 5000W pro Stunde, inkl. Puffer)
```

## Zusätzliche Verbesserungen

### SOC-Logging beim Ladestart

**Code-Änderung** (Zeile 644-649):
```python
if action == 'charge':
    # Prüfe aktuellen SOC beim Ladestart
    current_soc_now = float(state.get('sensor.esssoc') or 50)
    log.info(f"📊 SOC beim Ladestart: {current_soc_now}%")
```

**In den Logs siehst du jetzt:**
```
📊 SOC beim Ladestart: 30%
🔋 AKTIVIERE LADEN mit 5000W
```

Das hilft dir zu verstehen ob der Puffer ausreicht.

## Feinabstimmung

### Puffer anpassen

**Wenn Batterie regelmäßig nicht voll wird:**
1. Erhöhe den Puffer auf 30%
2. Warte 1-2 Tage
3. Prüfe ob Batterie jetzt voller wird

**Wenn zu viel geladen wird (teure Stunden genutzt):**
1. Reduziere den Puffer auf 10%
2. Warte 1-2 Tage
3. Prüfe ob immer noch ausreichend geladen wird

### Analyse der Logs

**Um 14:05** (Planung):
```
Aktueller SOC: 14%
Verfügbare Ladekapazität (berechnet): 6.60 kWh
Verfügbare Ladekapazität (mit 20% Puffer): 7.92 kWh
🎯 Benötigte Ladestunden: 2
```

**Um 22:05** (Ladestart):
```
📊 SOC beim Ladestart: 30%
🔋 AKTIVIERE LADEN mit 5000W
```

**Berechne Differenz:**
```
Geplant basierend auf: 14% SOC
Tatsächlich beim Start: 30% SOC
Differenz: +16%
→ 16% × 10kWh = 1.6 kWh zusätzlich benötigt
→ Puffer von 20% × 6.6kWh = 1.32 kWh
→ Puffer reicht knapp! (Eventuell auf 25-30% erhöhen)
```

## Hardware-Stopp bei 100%

**Wichtig**: Die GoodWe-Hardware stoppt automatisch bei 100% SOC, unabhängig von den Befehlen!

Das bedeutet:
- ✅ Es ist **sicher** mehr zu laden als benötigt
- ✅ Kein Risiko von Überladung
- ✅ Puffer kann großzügig gewählt werden

**Empfehlung**: Lieber etwas mehr Puffer (25-30%) als zu wenig!

## Alternative: Max-SOC auf 100% setzen

Wenn du **immer** bis 100% laden willst:

**Option A: Reserve entfernen**
```yaml
input_number:
  battery_optimizer_reserve_capacity:
    # Setze auf 0 statt 2 kWh
```

**Option B: Puffer auf 50% setzen**
```yaml
input_number:
  battery_optimizer_safety_buffer:
    # Setze auf 50%
```

**Beachte**: Das nutzt eventuell mehr teure Stunden als nötig!

## Monitoring

### Dashboard-Karte hinzufügen

```yaml
type: entities
title: Batterie Optimizer - Konfiguration
entities:
  - entity: input_number.battery_capacity_kwh
  - entity: input_number.battery_optimizer_min_soc
  - entity: input_number.battery_optimizer_max_soc
  - entity: input_number.battery_optimizer_max_charge_power
  - entity: input_number.battery_optimizer_reserve_capacity
  - entity: input_number.battery_optimizer_safety_buffer  # NEU
```

### Notification bei niedrigem SOC am Morgen

Erstelle eine Automation die dich warnt wenn die Batterie morgens nicht voll ist:

```yaml
alias: "Batterie Optimizer: Morgen-Check"
description: "Warnt wenn Batterie morgens nicht voll ist"
trigger:
  - platform: time
    at: "07:00:00"
condition:
  - condition: numeric_state
    entity_id: sensor.esssoc
    below: 95  # Schwellwert anpassen
action:
  - service: notify.persistent_notification
    data:
      title: "Batterie nicht voll"
      message: >
        Batterie SOC ist nur {{ states('sensor.esssoc') }}% um 7 Uhr.
        Eventuell Sicherheitspuffer erhöhen?
        Aktueller Puffer: {{ states('input_number.battery_optimizer_safety_buffer') }}%
```

## Testing

### Test-Szenario

1. **Heute um 14:05**: Notiere den SOC
2. **Heute um 22:00**: Notiere den SOC beim Ladestart (aus Logs)
3. **Morgen um 07:00**: Notiere den finalen SOC

**Beispiel-Messung:**
```
Tag 1 (Puffer 20%):
  14:05 → SOC 15%
  22:05 → SOC 32% (geplant: 15% + Schwankung)
  07:00 → SOC 94% (nicht voll!)
  → Puffer zu niedrig

Tag 2 (Puffer 30%):
  14:05 → SOC 18%
  22:05 → SOC 28%
  07:00 → SOC 100% ✓
  → Puffer passt!
```

## Zusammenfassung

### Was wurde geändert

| Änderung | Version | Beschreibung |
|----------|---------|--------------|
| Sicherheitspuffer | v3.4.0 | +20% zur Ladekapazität |
| Konfigurierbarer Puffer | v3.4.0 | `input_number.battery_optimizer_safety_buffer` |
| SOC-Logging beim Start | v3.4.0 | Zeigt tatsächlichen SOC beim Ladestart |

### Vorher vs. Nachher

**Vorher (v3.3.1)**:
```
SOC 14% → Plane 6.6 kWh → 2 Stunden
Tatsächlich beim Start: SOC 30% → Braucht 7.0 kWh
Ergebnis: Nur 92% geladen
```

**Nachher (v3.4.0 mit 20% Puffer)**:
```
SOC 14% → Plane 6.6 × 1.2 = 7.92 kWh → 2 Stunden
Tatsächlich beim Start: SOC 30% → Braucht 7.0 kWh
Ergebnis: 100% geladen ✓
```

### Empfehlung

1. ✅ Setze Puffer auf **20%** (Standard)
2. ✅ Beobachte 2-3 Tage
3. ✅ Passe Puffer an basierend auf Ergebnissen:
   - Nicht voll? → Erhöhe auf 25-30%
   - Immer voll, aber zu viele Ladestunden? → Reduziere auf 15%
4. ✅ Nutze die Morgen-Check Automation für Monitoring

## Version

- **battery_charging_optimizer.py**: v3.4.0
- **Datum**: 2025-11-25
- **Fix**: Sicherheitspuffer für untertägige SOC-Schwankungen