battery-charging-optimizer/INSTALLATION.md

# Installation Guide - OpenEMS Battery Optimizer

Vollständige Schritt-für-Schritt-Anleitung zur Installation des Battery Charging Optimizers.

## Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [PyScript Installation](#1-pyscript-installation)
3. [Script-Dateien kopieren](#2-script-dateien-kopieren)
4. [Konfiguration](#3-konfiguration)
5. [Automationen einrichten](#4-automationen-einrichten)
6. [Dashboard installieren](#5-dashboard-installieren)
7. [Erste Inbetriebnahme](#6-erste-inbetriebnahme)
8. [Verifizierung](#7-verifizierung)

---

## Voraussetzungen

### Home Assistant

- Home Assistant 2024.2 oder neuer
- Zugriff auf `/config/` Verzeichnis (via File Editor oder SSH)
- HACS installiert

### Hardware

- OpenEMS auf BeagleBone (oder vergleichbar)
- GoodWe Batterie & Inverter
- Netzwerkverbindung zu OpenEMS (Modbus TCP Port 502, JSON-RPC Port 8074)

### Erforderliche Integrationen

1. **PyScript** (via HACS)
   - Settings → Devices & Services → Add Integration → PyScript

2. **Forecast.Solar** (Standard Integration)
   - Settings → Devices & Services → Add Integration → Forecast.Solar
   - Konfiguriere deine PV-Arrays (Azimut, Neigung, kWp)

3. **Modbus** (Standard Integration)
   - Wird in `configuration.yaml` konfiguriert (siehe unten)

---

## 1. PyScript Installation

### Via HACS

1. HACS → Integrations → "Explore & Download Repositories"
2. Suche nach "PyScript"
3. Download & Install
4. Home Assistant neu starten

### Konfiguration

Füge zu `configuration.yaml` hinzu:

```yaml
pyscript:
  allow_all_imports: true
  hass_is_global: true
```

**Neustart erforderlich!**

---

## 2. Script-Dateien kopieren

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

```bash
/config/pyscript/
├── battery_charging_optimizer.py    # Haupt-Optimizer
├── hastrom_flex_extended.py         # Strompreis-Fetcher
└── ess_set_power.py                 # Modbus Power Control
```

### Via File Editor

1. Settings → Add-ons → File Editor
2. Navigiere zu `/config/pyscript/`
3. Erstelle neue Dateien und kopiere den Inhalt

### Via SSH/Terminal

```bash
cd /config/pyscript
wget https://gitea.ges4.net/felix/openems-battery-optimizer/raw/branch/main/pyscripts/battery_charging_optimizer.py
wget https://gitea.ges4.net/felix/openems-battery-optimizer/raw/branch/main/pyscripts/hastrom_flex_extended.py
wget https://gitea.ges4.net/felix/openems-battery-optimizer/raw/branch/main/pyscripts/ess_set_power.py
```

---

## 3. Konfiguration

### 3.1 Input Helper erstellen

Kopiere `config/battery_optimizer_config.yaml` und füge den Inhalt zu deiner `configuration.yaml` hinzu:

<details>
<summary>Input Helper Konfiguration (Klicken zum Ausklappen)</summary>

```yaml
input_boolean:
  battery_optimizer_enabled:
    name: "Batterie-Optimierung aktiviert"
    icon: mdi:battery-charging

  goodwe_manual_control:
    name: "Manuelle Batteriesteuerung"
    icon: mdi:battery-sync

  battery_optimizer_manual_override:
    name: "Manueller Override (Automatik pausieren)"
    icon: mdi:pause-circle

input_number:
  battery_capacity_kwh:
    name: "Batteriekapazität"
    min: 1
    max: 50
    step: 0.1
    unit_of_measurement: "kWh"
    icon: mdi:battery
    initial: 10  # ← DEINE KAPAZITÄT

  battery_optimizer_min_soc:
    name: "Minimum SOC"
    min: 0
    max: 100
    step: 1
    unit_of_measurement: "%"
    initial: 20

  battery_optimizer_max_soc:
    name: "Maximum SOC"
    min: 0
    max: 100
    step: 1
    unit_of_measurement: "%"
    initial: 100

  battery_optimizer_max_charge_power:
    name: "Maximale Ladeleistung"
    min: 1000
    max: 10000
    step: 100
    unit_of_measurement: "W"
    initial: 5000  # ← DEINE MAX LADELEISTUNG

  charge_power_battery:
    name: "Ziel-Ladeleistung"
    min: -10000
    max: 10000
    step: 100
    unit_of_measurement: "W"
    icon: mdi:flash

  # ... weitere Input Helper aus battery_optimizer_config.yaml
```

</details>

### 3.2 REST Commands

Füge `config/rest_requests.yaml` zu deiner `configuration.yaml` hinzu:

```yaml
rest_command:
  set_ess_remote_mode:
    url: "http://x:admin@192.168.89.144:8074/jsonrpc"  # ← DEINE OPENEMS IP
    method: POST
    payload: '{"method": "updateComponentConfig", "params": {"componentId": "ess0","properties":[{"name": "controlMode","value": "REMOTE"}]}}'

  set_ess_internal_mode:
    url: "http://x:admin@192.168.89.144:8074/jsonrpc"  # ← DEINE OPENEMS IP
    method: POST
    payload: '{"method": "updateComponentConfig", "params": {"componentId": "ess0","properties":[{"name": "controlMode","value": "INTERNAL"}]}}'
```

### 3.3 Modbus Konfiguration

Füge zu `configuration.yaml` hinzu:

```yaml
modbus:
  - name: openEMS
    type: tcp
    host: 192.168.89.144  # ← DEINE OPENEMS IP
    port: 502

    sensors:
      - name: "EssSoc"
        address: 802
        slave: 1
        scan_interval: 5
        unit_of_measurement: "%"
        device_class: battery

      - name: "EssActivepower"
        address: 806
        slave: 1
        scan_interval: 5
        unit_of_measurement: "W"
        device_class: power

      - name: "GridActivepower"
        address: 2822
        slave: 1
        scan_interval: 5
        unit_of_measurement: "W"
        device_class: power

      - name: "ProductionActivepower"
        address: 2837
        slave: 1
        scan_interval: 5
        unit_of_measurement: "W"
        device_class: power

      - name: "ConsumptionActivepower"
        address: 2827
        slave: 1
        scan_interval: 5
        unit_of_measurement: "W"
        device_class: power
```

**Nach jeder Änderung**: Configuration → Reload YAML Configuration (oder Neustart)

---

## 4. Automationen einrichten

### 4.1 Optimizer Automationen

Importiere `automations/battery_optimizer_automations.yaml`:

**Option A: Via UI**

1. Settings → Automations & Scenes
2. Rechts unten: "⋮" → "Edit in YAML"
3. Kopiere jede Automation einzeln

**Option B: Via automations.yaml**

Füge alle Automations aus der Datei zu deiner `/config/automations.yaml` hinzu.

**Wichtig**: Passe IDs an, falls Konflikte:

```yaml
- id: battery_optimizer_daily_calculation  # ← Muss unique sein
  alias: "Batterie Optimierung: Tägliche Planung"
  ...
```

### 4.2 Keep-Alive & ESS-Modus Automationen

Importiere die drei Automations aus `automations/`:

1. `speicher_manuell_laden.yaml` - Keep-Alive (30s)
2. `manuelle_speicherbeladung_aktivieren.yaml` - ESS → REMOTE
3. `manuelle_speicherbeladung_deaktivieren.yaml` - ESS → INTERNAL

---

## 5. Dashboard installieren

### Empfohlen: Sections Dashboard (Standard)

1. Settings → Dashboards → "+ ADD DASHBOARD"
2. Name: "Batterie Optimierung"
3. Icon: `mdi:battery-charging`
4. "⋮" → "Edit Dashboard" → "Raw configuration editor"
5. Kopiere Inhalt von `dashboards/battery_optimizer_sections_standard.yaml`

### Alternative Dashboards

- **Compact**: `battery_optimizer_sections_compact.yaml`
- **Minimal**: `battery_optimizer_sections_minimal.yaml`

### Erforderliche Custom Cards (HACS)

```
HACS → Frontend → Explore & Download Repositories:
- Mushroom Cards
- Bubble Card
- Plotly Graph Card
- Power Flow Card Plus
- Stack-in-Card
```

---

## 6. Erste Inbetriebnahme

### 6.1 PyScript neu laden

```
Developer Tools → Services
Service: pyscript.reload
```

### 6.2 Optimizer aktivieren

```
Developer Tools → States
Suche: input_boolean.battery_optimizer_enabled
Set State: on
```

### 6.3 Ersten Plan erstellen

```
Developer Tools → Services
Service: pyscript.calculate_charging_schedule
```

Prüfe die Logs:

```
Settings → System → Logs
Filter: "battery"
```

---

## 7. Verifizierung

### 7.1 Schedule prüfen

```
Developer Tools → States
Entity: pyscript.battery_charging_schedule
```

Attributes sollten enthalten:
- `schedule`: Array mit Stunden
- `num_charges`: Anzahl Ladestunden
- `last_update`: Timestamp

### 7.2 Preis-Sensor prüfen

```
Developer Tools → States
Entity: sensor.hastrom_flex_pro_ext
```

Attributes:
- `prices_today`: Array mit 24 Preisen
- `datetime_today`: Array mit Timestamps
- `tomorrow_available`: true/false
- `prices_tomorrow`: Array (ab 14:00)

### 7.3 Modbus-Verbindung prüfen

```
Developer Tools → States
Entity: sensor.esssoc
```

Sollte aktuellen SOC anzeigen (z.B. 65%).

### 7.4 Test-Ladung

**Vorsicht: Startet echte Batterieladung!**

```yaml
Developer Tools → Services

# 1. Ladeleistung setzen
Service: input_number.set_value
Target: input_number.charge_power_battery
Data:
  value: -3000  # Negativ = Laden mit 3000W

# 2. Manuellen Modus aktivieren
Service: input_boolean.turn_on
Target: input_boolean.goodwe_manual_control
```

Prüfe:
- OpenEMS sollte "REMOTE" Modus zeigen
- Batterie sollte mit ~3000W laden
- Nach 30s wieder stoppen:

```yaml
Service: input_boolean.turn_off
Target: input_boolean.goodwe_manual_control
```

---

## Troubleshooting

### PyScript startet nicht

```bash
# Prüfe Syntax-Fehler
cd /config/pyscript
python3 battery_charging_optimizer.py
```

### Keine Strompreise

- Prüfe Internet-Verbindung
- URL testen: `http://eex.stwhas.de/api/spotprices/flexpro?start_date=20250126&end_date=20250127`
- Log prüfen: `grep -i hastrom /config/home-assistant.log`

### Modbus Fehler

```yaml
# Test Modbus Verbindung
Developer Tools → Services
Service: modbus.write_register
Data:
  hub: openEMS
  slave: 1
  address: 706
  value: [0, 0]  # 0W (Test)
```

### Batterie lädt nicht

1. Prüfe `input_boolean.goodwe_manual_control` ist ON
2. Prüfe OpenEMS ESS Mode (sollte REMOTE sein)
3. Prüfe Keep-Alive Automation läuft
4. Prüfe OpenEMS Logs: `tail -f /var/log/openems/openems.log`

---

## Nächste Schritte

Nach erfolgreicher Installation:

1. **Monitoring**: Beobachte den ersten Ladezyklus
2. **Feintuning**: Passe `min_soc`, `max_charge_power` an
3. **Dashboard**: Experimentiere mit verschiedenen Dashboard-Varianten
4. **Automationen**: Erweitere mit eigenen Automationen

---

## Support

Bei Problemen:

1. Prüfe [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
2. Schaue in die [Issues](https://gitea.ges4.net/felix/openems-battery-optimizer/issues)
3. Erstelle ein Issue mit:
   - Home Assistant Version
   - OpenEMS Version
   - Relevante Logs
   - Konfiguration (ohne Passwörter!)