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, Energie-Dashboard.

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

---

Übersicht

Komponente	Beschreibung	Status
ShineBridge Add-on	HAOS Add-on: Modbus TCP / UDP → MQTT Discovery	✅ v1.8.18
ShineLAN-X Firmware	NuttX auf STM32F103: Modbus RTU ↔ TCP + OTA	✅ 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]  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, Flash-Wizard

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
• Setup-Wizard — Geführte Ersteinrichtung (MQTT + erster Wechselrichter)
• Flash-Wizard — ShineLAN-X Firmware direkt aus dem Add-on flashen (OTA oder ST-Link-Anleitung)
• Überschuss-Geräte — Zigbee2MQTT-Geräte bei PV-Überschuss automatisch einschalten
• Konfig-Export/Import — JSON im Einstellungen-Tab
• 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 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 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

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

Schritt 2 — ShineLAN-X flashen

Beim ersten Start erscheint der Setup-Wizard automatisch. Der Tab Flash im Web UI führt durch beide Szenarien:

• OTA-Modus (Stick bereits geflasht): IP eingeben → Firmware auswählen → Flashen. Die aktuelle Firmware ist im Add-on integriert.
• Erstflash via ST-Link (Stick noch ungeflasht): Schritt-für-Schritt-Anleitung mit Pinout und st-flash-Befehl.

Für den manuellen Erstflash:

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

st-flash --reset write nuttx-mbusd-shinelanx.bin 0x08000000

Schritt 3 — Gerät konfigurieren

Im Web UI → „＋ Gerät hinzufügen" (oder Setup-Wizard beim ersten Start):

• 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 mit OTA-Update-Funktion.

Firmware basiert auf mwalle (Martin Walle) Lizenzen: Board-Support Apache 2.0 · mbusd BSD 3-Clause · Gateway-App BSD 2-Clause. Quellcode: github.com/mwalle/shinelanx-modbus

Flash-Layout

0x08000000  dapboot   (8 KB)   ← Bootloader, nicht überschrieben
0x08002000  NuttX    (93 KB)   ← Modbus RTU ↔ TCP, Port 502 + OTA HTTP, Port 80
              ↕
0x08020000  Staging  (≤124 KB) ← OTA: Neue Firmware temporär hier

OTA-Update

Ab der DFU-Variante (nuttx-mbusd-shinelanx-dfu.bin) ist OTA ohne ST-Link möglich. Der Stick hostet einen HTTP-Server auf Port 80:

Endpunkt	Beschreibung
GET /	Status-JSON: {"ota":true,"app_base":"0x08002000",...}
POST /update	Firmware-Binary empfangen, in Staging schreiben, anwenden, Reset
POST /reboot	Software-Reset

Der OTA-Prozess läuft zweistufig (Single-Bank STM32 Einschränkung):

1. Stage 1 — Firmware in die obere Flash-Hälfte (Staging) schreiben, TCP-Stack läuft noch
2. Stage 2 — Aus SRAM heraus: Staging → App-Bereich kopieren, Reset

Das Add-on steuert OTA über den Flash-Tab im Web UI.

Hardware

Komponente	Details
MCU	STM32F103RC — 256 kB Flash, 48 kB SRAM
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
│   ├── firmware/                # Integrierte ShineLAN-X Binaries
│   │   ├── nuttx-mbusd-shinelanx.bin       # Direktflash (0x08000000)
│   │   └── nuttx-mbusd-shinelanx-dfu.bin   # OTA-fähig  (0x08002000)
│   └── src/
│       ├── main.py              # Flask, Poll-Threads, REST API, Flash-Proxy
│       ├── 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, Flash)
├── ShineLAN-X/
│   └── releases/
│       ├── nuttx-mbusd-shinelanx.bin
│       └── nuttx-mbusd-shinelanx-dfu.bin
├── shinelanx-modbus/            ← NuttX Firmware Quellcode
│   └── apps/shinelanx-modbus-gw/
│       ├── main.c               # Startup: MAC, DHCP, OTA-Thread, mbusd
│       ├── ota_http.c           # OTA HTTP-Server (Zwei-Phasen Flash)
│       └── ota_http.h
├── 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.