ShineBridge

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

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

---

Übersicht

Komponente	Beschreibung	Status
ShineBridge Add-on	HAOS Add-on: Modbus TCP → MQTT Discovery	✅ v1.3.0
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
    │  USB oder RS485 (Modbus RTU)
[ShineLAN-X]  ← STM32F103, NuttX, Modbus RTU ↔ TCP
    │  Modbus TCP Port 502 (LAN)
[ShineBridge Add-on]
    ├── Modbus TCP lesen (pymodbus)
    ├── MQTT Discovery → Home Assistant Sensoren
    ├── Aggregat-Gerät „ShineBridge Gesamt"
    ├── Persistente History (SQLite, 7 Tage)
    └── Web UI: Geräte verwalten, Live-Daten, Sparklines

Features

• Multi-Gerät — beliebig viele Wechselrichter + Zähler, 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
• 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 FC04, Float32

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 des ShineLAN-X, MQTT Topic-Präfix

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)
AC Gesamtleistung	Summe aller AC-Ausgänge (W)
Netzleistung	Netzbezug/Einspeisung via SDM-630 (W)
Netzbezug / Einspeisung Gesamt	kWh-Zähler für Energie-Dashboard
Batterie Ladezustand Ø	Durchschnitt aller Batterien (%)

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
│       ├── modbus_client.py     # Modbus TCP, Float32-Dekodierung
│       ├── 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
│       ├── diagnose.py
│       ├── web/index.html
│       └── setup/               # Pi-Konfiguration + install.sh
├── ROADMAP.md
└── 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.