ShineBridge

Lokale Solar-Wechselrichter-Integration für Home Assistant — ohne Cloud, ohne Hersteller-App. Modbus TCP via ShineLAN-X, MQTT Discovery, persistente History, PV-Überschussladen.

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

---

Übersicht

Komponente	Beschreibung	Status
ShineBridge Add-on	HAOS Add-on: Modbus TCP / UDP → MQTT Discovery	✅ v1.5.3
ShineLAN-X Firmware	NuttX auf STM32F103: Modbus RTU ↔ TCP	✅ Produktiv
ShineWifi-X ESPHome	ESPHome-Configs für ESP8266-Stick	✅ Getestet
ShineDiag	Portables Vor-Ort-Diagnose-Tool (Pi 3B)	✅ Bereit

---

ShineBridge Add-on

Architektur

Wechselrichter / Energiezähler
    │  Modbus RTU (RS485 / USB)
[ShineLAN-X]  ← STM32F103, NuttX, Modbus RTU ↔ TCP
    │  Modbus TCP Port 502 (LAN)
    │
    │  UDP/8899 (Goodwe)
    │  Modbus TCP Port 502 (Kathrein Wallbox)
    │
[ShineBridge Add-on]
    ├── 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)
    └── Web UI: Geräte verwalten, Live-Daten, Sparklines, EMS-Konfig

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)
• Sparklines — Live-Graphen der letzten 5 Minuten pro Sensor
• EMS-Controller — PV-Überschussladen der Kathrein Wallbox, Zwangsladen-Fallback
• Konfig-Export/Import — JSON im Einstellungen-Tab
• 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 Maximalstrom bis zur Zielzeit (Standard: 06:00 Uhr)

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

Hinweis: Die EMS-Funktion muss in der Kathrein easyOperate-App aktiviert sein.

Netzleistung (grid_power)

Der Sensor grid_power (Goodwe) 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 (nur Einspeisung bekannt).

Installation

Schritt 1 — NuttX auf den ShineLAN-X flashen (einmalig, ST-Link nötig)

# dapboot Bootloader
st-flash write ShineLAN-X/releases/dapboot.bin 0x08000000

# NuttX Firmware
st-flash write ShineLAN-X/releases/nuttx-mbusd-shinelanx-dfu.bin 0x08002000

SWD-Pinbelegung: PA13=SWDIO PA14=SWCLK GND 3.3V

Schritt 2 — 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
4. MQTT-Zugangsdaten in der Add-on-Konfiguration eintragen
5. Web UI öffnen → Gerät hinzufügen

Schritt 3 — 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

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).

---

ShineLAN-X Firmware

Der Growatt ShineLAN-X ist ein LAN-Monitoring-Stick (STM32F103RC + ENC28J60) der im USB-Port des Wechselrichters steckt. Die Custom-Firmware (NuttX + mbusd) macht ihn zum Modbus TCP Gateway.

Firmware von mwalle (Martin Walle) Das Binary nuttx-mbusd-shinelanx-dfu.bin ist das Werk von Martin Walle und wird hier unverändert weitergegeben. Lizenzen: Board-Support Apache 2.0 · mbusd BSD 3-Clause · Gateway-App BSD 2-Clause. Quellcode und Kompilieranleitung: github.com/mwalle/shinelanx-modbus

Flash-Layout

0x08000000  dapboot  (7 KB)   ← Bootloader für USB DFU OTA
0x08002000  NuttX    (93 KB)  ← Modbus RTU ↔ TCP, Port 502

Hardware

Komponente	Details
MCU	STM32F103RC — 256 kB Flash, 64 kB RAM
Ethernet	ENC28J60 (SPI2)
USB	PA11=D−, PA12=D+, PA8=Pullup
SWD	PA13=SWDIO, PA14=SWCLK
Debug UART	USART1 — PA9=TX, PA10=RX, 115200 Baud
LEDs	PC7 blau, PB1 rot, PB0 grün, PC5 blau RGB

---

ShineWifi-X (ESPHome)

Der Growatt ShineWifi-X ist ein WLAN-Stick (ESP8266) der im RS485-Port des Wechselrichters steckt. ESPHome liest die Register direkt aus.

Wechselrichter  →RS485→  [ShineWifi-X ESP8266]  →WLAN→  [Home Assistant]

Erstinstallation (USB-zu-Serial-Adapter, 3,3 V):

esphome run "ShineWifi-X/Growatt MIC 1500 TL-X/Growatt MIC 1500 TL-X.yaml"

Modell	Ordner
Growatt MIC 1500 TL-X	ShineWifi-X/Growatt MIC 1500 TL-X/
Growatt MIC 2000 TL-X	ShineWifi-X/Growatt MIC 2000 TL-X/
Growatt SPH 5000 TL3-BH-UP	ShineWifi-X/Growatt SPH 5000 TL3/
Growatt MOD 6000 TL3-XH	ShineWifi-X/Growatt MOD 6000 TL3-XH/

---

ShineDiag — Vor-Ort-Diagnose

Portables Diagnose-Tool für Techniker. Raspberry Pi 3B als Gateway: LAN zum ShineLAN-X, WiFi-Hotspot für MacBook/Tablet.

[Wechselrichter] →USB→ [ShineLAN-X] →LAN→ [Pi 3B] →WiFi→ [MacBook/Tablet]
                                             http://10.0.1.1

Einmalig einrichten:

git clone https://gitea.bitfire.work/retr0/shinebridge
cd shinebridge/tools/shinediag
sudo bash setup/install.sh
sudo reboot

Vor Ort:

1. LAN-Kabel: Pi ↔ ShineLAN-X
2. WiFi verbinden: ShineDiag | Passwort: shinelanx
3. Browser: http://10.0.1.1 → Modell wählen → Auslesen → Export JSON

Features: Alle Sensoren, Rohdaten-Register-Dump (Adresse, Hex, Dezimal), JSON-Export.

---

Repository-Struktur

shinebridge/
├── haos-addon/                  ← HAOS Add-on
│   ├── config.yaml
│   ├── Dockerfile
│   └── src/
│       ├── main.py              # Flask, Poll-Threads, REST API, Aggregation
│       ├── 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
├── ShineLAN-X/
│   └── releases/
│       ├── dapboot.bin
│       └── nuttx-mbusd-shinelanx-dfu.bin
├── ShineWifi-X/                 ← ESPHome Configs
├── tools/
│   └── shinediag/               ← Vor-Ort-Diagnose-Tool
└── repository.yaml

---

Lizenz

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