retr0/Shinebridge
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: README komplett aktualisiert

Browse Source 
Spiegelt aktuellen Stand: ShineBridge v1.3.0, SDM-630, Aggregat-Gerät,
persistente History, ShineDiag, neuer Repo-Name.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
retr0
2026-04-27 12:00:37 +02:00
parent aac95c2eef
commit ffcf5ca7b1
1 changed files with 140 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+140 -115
View File
@@ -1,185 +1,210 @@
# Growatt Wechselrichter → Home Assistant (ohne Cloud)
# ShineBridge
Lokale Integration von Growatt Wechselrichtern in Home Assistant OS — vollständig ohne Growatt-App oder Cloud. Dieses Repository enthält zwei unabhängige Lösungen je nach Hardware:
Lokale Solar-Wechselrichter-Integration für Home Assistant — ohne Cloud, ohne Hersteller-App. Modbus TCP via ShineLAN-X, MQTT Discovery, persistente History.
| Hardware | Lösung | Status |
|---|---|---|
| **Growatt ShineLAN-X** (LAN-Stick, STM32) | NuttX-Firmware + ShineBridge Add-on | ✅ Produktiv |
| **Growatt ShineWifi-X** (WLAN-Stick, ESP8266) | ESPHome-Konfigurationen | ✅ Getestet |
> **Repository:** `https://gitea.bitfire.work/retr0/shinebridge`
---
## Lösung 1: ShineLAN-X + ShineBridge Add-on (empfohlen)
## Übersicht
Der **Growatt ShineLAN-X** ist ein LAN-Monitoring-Stick mit einem STM32F103-Mikrocontroller. Er steckt im USB-Port des Wechselrichters und kommuniziert via Modbus RTU.
| 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 |
### Wie es funktioniert
---
## ShineBridge Add-on
### Architektur
```
Growatt Wechselrichter
│ USB (Modbus RTU)
[ShineLAN-X] ← STM32F103 mit NuttX-Firmware
│ Modbus TCP Port 502 (Ethernet)
[HAOS Add-on]
├── liest Sensordaten per Modbus TCP
├── publiziert via MQTT Discovery → Home Assistant Sensoren
└── Web UI (Wechselrichter verwalten, Live-Daten, Verlaufsgraphen)
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
- **Mehrere Wechselrichter** — beliebig viele, jeder mit eigenem HA-Gerät
- **MQTT Discovery** — Sensoren erscheinen automatisch in HA (kein manuelles Anlegen)
- **Web UI** — Wechselrichter hinzufügen/bearbeiten, Live-Daten mit Sparklines (5 Min)
- **OTA-Updates** — NuttX-Firmware via USB DFU aktualisierbar (kein ST-Link nötig)
- **Kein Cloud-Zwang** — alles lokal im Heimnetz
- **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 Wechselrichter-Modelle
### Unterstützte Geräte
| Modell | Typ | Sensoren |
|---|---|---|
| Growatt MIC 1500/2000 TL-X | 1-phasig | 10 |
| Growatt SPH 5000 TL3-BH-UP | 3-phasig + Batterie | 28 |
| Growatt MOD 6000 TL3-XH | 3-phasig | 17 |
| 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 (HAOS Add-on)
### Installation
**Schritt 1 — NuttX auf den ShineLAN-X flashen** *(einmalig, ST-Link nötig)*
```bash
# dapboot Bootloader (0x08000000)
~/.platformio/packages/tool-stm32duino/stlink/st-flash write \
ShineLAN-X/releases/dapboot.bin 0x08000000
# dapboot Bootloader
st-flash write ShineLAN-X/releases/dapboot.bin 0x08000000
# NuttX Firmware (0x08002000)
~/.platformio/packages/tool-stm32duino/stlink/st-flash write \
ShineLAN-X/releases/nuttx-mbusd-shinelanx-dfu.bin 0x08002000
# NuttX Firmware
st-flash write ShineLAN-X/releases/nuttx-mbusd-shinelanx-dfu.bin 0x08002000
```
SWD-Pinbelegung: PA13=SWDIO, PA14=SWCLK, GND, 3.3V
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 eintragen: `https://gitea.bitfire.work/retr0/shinebridge`
3. „ShineBridge" → Installieren
2. URL: `https://gitea.bitfire.work/retr0/shinebridge`
3. „ShineBridge" → Installieren → Starten
4. MQTT-Zugangsdaten in der Add-on-Konfiguration eintragen
5. Starten → Web UI öffnen → Wechselrichter hinzufügen
5. Web UI öffnen → Gerät hinzufügen
**Schritt 3 — Wechselrichter im Web UI konfigurieren**
**Schritt 3 — Gerät konfigurieren**
Im Tab „Wechselrichter" → „＋ Wechselrichter hinzufügen":
- Name (z.B. „Dach Süd")
- Modell auswählen
- IP-Adresse des ShineLAN-X
- MQTT Topic-Präfix (z.B. `growatt/dach`)
Im Web UI → „＋ Gerät hinzufügen":
- Name, Modell, IP des ShineLAN-X, MQTT Topic-Präfix
Sensoren erscheinen danach automatisch in HA unter **Einstellungen → Geräte & Dienste → MQTT**.
Sensoren erscheinen danach unter **Einstellungen → Geräte & Dienste → MQTT**.
### Flash-Layout NuttX
### Aggregat-Sensoren (Energie-Dashboard)
```
0x08000000 dapboot (7 KB) ← Bootloader, ermöglicht OTA via USB DFU
0x08002000 NuttX (93 KB) ← Modbus RTU ↔ TCP Gateway auf Port 502
```
Das Aggregat-Gerät „ShineBridge Gesamt" stellt folgende Sensoren bereit:
### Hardware ShineLAN-X
| Komponente | Details |
| Sensor | Beschreibung |
|---|---|
| MCU | STM32F103RC (256 kB Flash, 64 kB RAM) |
| Ethernet | ENC28J60 (SPI2) |
| USB | PA11=D−, PA12=D+, PA8=Pullup |
| Debug UART | USART1, PA9=TX, PA10=RX, 115200 Baud |
| SWD | PA13=SWDIO, PA14=SWCLK |
| LEDs | PC7 (blau intern), PB1 (rot), PB0 (grün), PC5 (blau RGB) |
| 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).
---
## Lösung 2: ShineWifi-X (ESPHome)
## ShineLAN-X Firmware
Der **Growatt ShineWifi-X** ist ein WLAN-Monitoring-Stick mit ESP8266. Er steckt im RS485-Port des Wechselrichters. ESPHome liest die Register direkt aus und meldet sie an Home Assistant.
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.
### Flash-Layout
```
Growatt Wechselrichter
│ RS485 / Modbus RTU
[ShineWifi-X] ← ESP8266 mit ESPHome-Firmware
│ WLAN
[Home Assistant OS] ← native ESPHome-Integration
0x08000000 dapboot (7 KB) ← Bootloader für USB DFU OTA
0x08002000 NuttX (93 KB) ← Modbus RTU ↔ TCP, Port 502
```
### Unterstützte Modelle (ShineWifi-X)
### Hardware
| Modell | YAML |
| 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):
```bash
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/` |
### ShineWifi-X flashen
---
> Erstinstallation benötigt einen USB-zu-Serial-Adapter (3,3 V). Danach OTA über WLAN möglich.
## ShineDiag — Vor-Ort-Diagnose
1. YAML aus dem passenden Modell-Ordner kopieren
2. WLAN-Zugangsdaten und API-Key eintragen
3. Erstinstallation via seriell:
```bash
esphome run ShineWifi-X/Growatt\ MIC\ 1500\ TL-X/*.yaml
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
```
UART-Pinbelegung ShineWifi-X: TX→GPIO1, RX→GPIO3, Baud 115200
**Einmalig einrichten:**
```bash
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
```
.
├── README.md
├── haos-addon/ ← HAOS Add-on (ShineLAN-X)
│ ├── config.yaml # Add-on Manifest
shinebridge/
├── haos-addon/ ← HAOS Add-on
│ ├── config.yaml
│ ├── Dockerfile
│ ├── build.yaml
│ └── src/
│ ├── main.py # Flask + Poll-Threads
│ ├── modbus_client.py # pymodbus Modbus TCP
│ ├── mqtt_publisher.py # MQTT Discovery
│ ├── inverters.py # Register-Definitionen
│ └── web/index.html # Web UI
│ ├── 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/
│ ├── firmware/ # Arduino-Stack (aufgegeben, rx=0)
│ └── releases/
│ ├── nuttx-mbusd-shinelanx.bin # NuttX ohne DFU
│ └── nuttx-mbusd-shinelanx-dfu.bin # NuttX mit dapboot (empfohlen)
├── ShineWifi-X/ ← ESPHome Configs
│ ├── Growatt MIC 1500 TL-X/
│ ├── Growatt MIC 2000 TL-X/
│ ├── Growatt SPH 5000 TL3/
│ └── Growatt MOD 6000 TL3-XH/
└── shinelanx-modbus/ ← mwalle NuttX Board-Support
└── contrib/dapboot/dapboot.bin
│ ├── 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
```
---
## Modbus-Registerübersicht (Growatt, FC04)
| Register | Sensor | Modelle | Scale |
|---|---|---|---|
| 3 | PV Spannung | alle | ×0.1 V |
| 4 | PV Strom | alle | ×0.1 A |
| 5–6 | PV Leistung | alle | ×0.1 W |
| 37 | Netz-Frequenz | alle | ×0.01 Hz |
| 38 | Netz-Spannung | alle | ×0.1 V |
| 40–41 | AC Ausgangsleistung | alle | ×0.1 W |
| 53–54 | Energie Heute | alle | ×0.1 kWh |
| 55–56 | Energie Gesamt | alle | ×0.1 kWh |
| 93 | Temperatur | alle | ×0.1 °C |
| 1009–1058 | Batterie + Netz | SPH | ×0.1 |
---
## Lizenz
Frei verwendbar und anpassbar. Keine Garantie für Richtigkeit der Modbus-Register — immer gegen das offizielle Growatt-Datenblatt des jeweiligen Modells prüfen.
Frei verwendbar und anpassbar. Keine Garantie für Richtigkeit der Modbus-Register — immer gegen das offizielle Datenblatt des jeweiligen Modells prüfen.