Shinebridge/README.md

ShineBridge

Lokales Energiemanagement für Growatt/Goodwe-Wechselrichter in Home Assistant — ohne Cloud, ohne Hersteller-App. Modbus TCP / UDP, MQTT Discovery, persistente History, PV-Überschussladen, Energie-Dashboard.

Repository: https://gitea.bitfire.work/retr0/shinebridge

Firmware, Hardware-Diagnose und Flash-Tools für ShineLAN-X/ShineWifi-X liegen seit v1.9.0 in einem eigenen, privaten Repo (growatt-diagnose-tool) — dieses Repo ist reines Energiemanagement.

---

Architektur

Wechselrichter / Energiezähler
    │  Modbus RTU (RS485 / USB)
[ShineLAN-X]  ← STM32F103, NuttX, Modbus RTU ↔ TCP  (Firmware: growatt-diagnose-tool)
    │  Modbus TCP Port 502 (LAN)
    │
    │  UDP/8899 (Goodwe)
    │  Modbus TCP Port 502 (Kathrein Wallbox)
    │
[ShineBridge Add-on]  Port 8099 (HAOS Ingress)
    ├── Modbus TCP / Goodwe UDP / Kathrein Wallbox lesen
    ├── EMS-Controller: PV-Überschussladen + Zwangsladen
    ├── MQTT Discovery → Home Assistant Sensoren
    ├── Aggregat-Gerät „ShineBridge Gesamt"
    ├── Persistente History (SQLite, 7 Tage)
    ├── Energie-Dashboard (SVG-Flussdiagramm, EPEX Spot)
    ├── Finanzen-Tab (Abschlags-Tracker, Eigenversorgung)
    └── Web UI: Live-Daten, Geräte, Einstellungen

Features

• Multi-Gerät — beliebig viele Wechselrichter + Zähler + Wallbox, jeder als eigenes HA-Gerät
• MQTT Discovery — Sensoren erscheinen automatisch in HA
• Aggregat-Gerät — summiert alle Geräte für das HA Energie-Dashboard
• Persistente History — Messwerte überleben Add-on-Neustarts (SQLite, 7 Tage)
• Energie-Dashboard — HA-Style SVG-Flussdiagramm mit animierten Dots; EPEX-Spot-Chart
• Finanzen-Tab — kWh-Kosten, Eigenversorgung, Abschlags-Tracker (monatliche Rate + Grundpreis)
• Flexibler Tarif — Festpreis oder EPEX Spot (aWATTar DE/AT) mit Aufschlag
• Sparklines — Live-Graphen der letzten 5 Minuten pro Sensor
• EMS-Controller — PV-Überschussladen der Kathrein Wallbox, Zwangsladen-Fallback mit konfigurierbarem Max-Ladestrom
• Überschuss-Geräte — Zigbee2MQTT-Geräte bei PV-Überschuss automatisch einschalten
• Konfig-Export/Import — JSON im Einstellungen-Tab, zusätzlich automatisches tägliches Backup nach /share/shinebridge-backups/ (übersteht auch Add-on-Uninstall+Reinstall, 14 Tage Aufbewahrung)
• Port-Sicherheit — /api/* nur über HAOS-Ingress erreichbar, kein Direktzugriff von außen
• Kein Cloud-Zwang — vollständig lokal

Unterstützte Geräte

Gerät	Typ	Sensoren	Protokoll
Growatt MIC 1500/2000 TL-X	PV 1-phasig	10	Modbus FC04
Growatt SPH 5000 TL3-BH-UP	Hybrid 3-phasig + Batterie	28	Modbus FC04
Growatt MOD 6000 TL3-XH	PV 3-phasig	17	Modbus FC04
Eastron SDM-630	Drehstromzähler	16	Modbus FC03, Float32
Goodwe GW10KN-ET	Hybrid 3-phasig + Batterie	39	UDP/8899 (goodwe lib)
Kathrein Wallbox	EVSE + Meter + EMS	18	Modbus FC03, TCP/502

EMS — PV-Überschussladen (Kathrein Wallbox)

Der EMS-Controller regelt den Ladestrom der Kathrein Wallbox anhand des PV-Überschusses:

1. PV-Laden — Überschuss ≥ Mindestleistung (Standard: 1400 W = 6 A × 230 V): Ladestrom = verfügbare PV-Leistung / Phasen
2. Warten — Kein ausreichender Überschuss: Laden pausiert, Timer läuft
3. Zwangsladen — Nach Timeout ohne PV (Standard: 4 h): Laden mit konfiguriertem Max-Ladestrom bis zur Zielzeit (Standard: 06:00 Uhr), Strom wird bei jedem Poll erneut gesetzt (kein Einmal-Write)
4. Unbekannte Ladezustände (z. B. Fahrzeug-Störung) pausieren den Strom, ohne den Zwangslade-Timer zurückzusetzen

Konfigurierbar pro Gerät im Web UI:

Parameter	Beschreibung	Standard
Mindest-PV-Überschuss	Untergrenze für PV-Laden	1400 W
Timeout ohne PV	Stunden bis Zwangsladen	4 h
Vollladung bis	Zielzeit für Zwangsladen	06:00
Anzahl Phasen	1 / 2 / 3-phasig	3
Max. Ladestrom	Obergrenze fürs Zwangsladen — auf die tatsächliche Wallbox-/Zuleitungs-Absicherung setzen	32 A

Wichtig: Max. Ladestrom niemals höher als die real installierte Wallbox stellen (z. B. 16 A bei einer 11-kW-Wallbox) — sonst fordert das Zwangsladen mehr an, als die Hardware liefern kann, was bei manchen Fahrzeugen zu Ladefehlern führt.

Die EMS-Funktion muss zusätzlich in der Kathrein easyOperate-App aktiviert sein.

Prognosebasierter Zwangslade-Timeout (optional): Mit Standort (Breitengrad/Längengrad, Einstellungen-Tab) passt sich der Zwangslade-Timeout an die Solarstrahlungs-Prognose (Open-Meteo, kostenlos) an — bei bald zu erwartender Sonne wird länger gewartet (gedeckelt), bei aussichtsloser Prognose eher vom Netz geladen statt sinnlos den vollen Timeout abzuwarten. Ohne Standort unverändertes Verhalten (fester Timeout).

Batterie-Schutz beim PV-Überschussladen: Bei Anlagen mit Hausbatterie (z. B. Goodwe) wird die aktuelle Batterie-Entladeleistung vom berechneten PV-Überschuss abgezogen — ein Netzexport, der eigentlich aus dem Speicher kommt (z. B. bei bewölktem Wetter), wird so nicht fälschlich als PV-Überschuss fürs Auto verwendet. Betrifft nur PV-Überschussladen, Zwangsladen bleibt unverändert netzbasiert.

Netzleistung (grid_power)

Der Sensor grid_power zeigt die Netzleistung intuitiv:

• Positiv = Netzbezug (Strom vom Netz)
• Negativ = Einspeisung (Strom ins Netz)

Bei reinen Growatt-Anlagen (ohne Goodwe) wird power_to_grid als Proxy verwendet.

Installation

Add-on in Home Assistant installieren

1. Einstellungen → Add-ons → Add-on-Store → ⋮ → Repositories
2. URL: https://gitea.bitfire.work/retr0/shinebridge
3. „ShineBridge" → Installieren → Starten

ShineLAN-X flashen

Das Flashen des ShineLAN-X-Sticks (OTA oder ST-Link-Erstflash) läuft über das separate growatt-diagnose-tool — dort auch die Firmware-Quelle und Doku.

Gerät konfigurieren

Im Web UI → „＋ Gerät hinzufügen":

• Name, Modell, IP, Port, Modbus-Adresse, MQTT Topic-Präfix, Abfrageintervall
• Bei Kathrein Wallbox: EMS-Parameter konfigurieren (inkl. Max. Ladestrom!)

Sensoren erscheinen danach unter Einstellungen → Geräte & Dienste → MQTT.

Aggregat-Sensoren (Energie-Dashboard)

Das Aggregat-Gerät „ShineBridge Gesamt" stellt folgende Sensoren bereit:

Sensor	Beschreibung
PV Gesamtleistung	Summe aller PV-Eingänge (W)
Netzleistung	Netzbezug (+) / Einspeisung (−) am Hausanschluss (W)
Netzbezug / Einspeisung Gesamt	kWh-Zähler für Energie-Dashboard
Batterie Ladezustand Ø	Durchschnitt aller Batterien (%)
Batterie Lade-/Entladeleistung	Summe (W)

History API

GET /api/history?inv_id=<id>&sensor_id=<id>&hours=<1-168>

Gibt alle Messpunkte des gewählten Zeitfensters zurück (max. 7 Tage).

Repository-Struktur

shinebridge/
└── haos-addon/                  ← HAOS Add-on (einziger Inhalt dieses Repos)
    ├── config.yaml
    ├── Dockerfile
    └── src/
        ├── main.py              # Flask, Poll-Threads, REST API
        ├── modbus_client.py     # Modbus TCP, Float32-Dekodierung
        ├── goodwe_client.py     # Goodwe UDP/8899 via goodwe-Bibliothek
        ├── wallbox_client.py    # Kathrein Wallbox Modbus TCP
        ├── ems_controller.py    # PV-Überschussladen + Zwangsladen
        ├── mqtt_publisher.py    # MQTT Discovery + Aggregat
        ├── inverters.py         # Register-Maps aller Geräte
        ├── history.py           # SQLite Persistenz
        └── web/index.html       # Web UI (Energie, Finanzen, Live, Geräte, Einstellungen)

Firmware (ShineLAN-X, ShineWifi-X) und das Vor-Ort-Diagnose-Tool (ShineDiag) liegen im separaten, privaten Repo growatt-diagnose-tool.

Lizenz

Frei verwendbar und anpassbar. Keine Garantie für Richtigkeit der Modbus-Register — immer gegen das offizielle Datenblatt des jeweiligen Modells prüfen.