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 | > **Repository:** `https://gitea.bitfire.work/retr0/shinebridge`
|---|---|---|
| **Growatt ShineLAN-X** (LAN-Stick, STM32) | NuttX-Firmware + ShineBridge Add-on | ✅ Produktiv |
| **Growatt ShineWifi-X** (WLAN-Stick, ESP8266) | ESPHome-Konfigurationen | ✅ Getestet |
--- ---
## 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 Wechselrichter / Energiezähler
│ USB (Modbus RTU) │ USB oder RS485 (Modbus RTU)
[ShineLAN-X] ← STM32F103 mit NuttX-Firmware [ShineLAN-X] ← STM32F103, NuttX, Modbus RTU ↔ TCP
│ Modbus TCP Port 502 (Ethernet) │ Modbus TCP Port 502 (LAN)
[HAOS Add-on] [ShineBridge Add-on]
├── liest Sensordaten per Modbus TCP ├── Modbus TCP lesen (pymodbus)
├── publiziert via MQTT Discovery → Home Assistant Sensoren ├── MQTT Discovery → Home Assistant Sensoren
└── Web UI (Wechselrichter verwalten, Live-Daten, Verlaufsgraphen) ├── Aggregat-Gerät „ShineBridge Gesamt"
├── Persistente History (SQLite, 7 Tage)
└── Web UI: Geräte verwalten, Live-Daten, Sparklines
``` ```
### Features ### Features
- **Mehrere Wechselrichter** — beliebig viele, jeder mit eigenem HA-Gerät - **Multi-Gerät** — beliebig viele Wechselrichter + Zähler, jeder als eigenes HA-Gerät
- **MQTT Discovery** — Sensoren erscheinen automatisch in HA (kein manuelles Anlegen) - **MQTT Discovery** — Sensoren erscheinen automatisch in HA
- **Web UI** — Wechselrichter hinzufügen/bearbeiten, Live-Daten mit Sparklines (5 Min) - **Aggregat-Gerät** — summiert alle Geräte für das HA Energie-Dashboard
- **OTA-Updates** — NuttX-Firmware via USB DFU aktualisierbar (kein ST-Link nötig) - **Persistente History** — Messwerte überleben Add-on-Neustarts (SQLite, 7 Tage)
- **Kein Cloud-Zwang** — alles lokal im Heimnetz - **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 | | Gerät | Typ | Sensoren | Protokoll |
|---|---|---| |---|---|---|---|
| Growatt MIC 1500/2000 TL-X | 1-phasig | 10 | | Growatt MIC 1500/2000 TL-X | PV 1-phasig | 10 | Modbus FC04 |
| Growatt SPH 5000 TL3-BH-UP | 3-phasig + Batterie | 28 | | Growatt SPH 5000 TL3-BH-UP | Hybrid 3-phasig + Batterie | 28 | Modbus FC04 |
| Growatt MOD 6000 TL3-XH | 3-phasig | 17 | | 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)* **Schritt 1 — NuttX auf den ShineLAN-X flashen** *(einmalig, ST-Link nötig)*
```bash ```bash
# dapboot Bootloader (0x08000000) # dapboot Bootloader
~/.platformio/packages/tool-stm32duino/stlink/st-flash write \ st-flash write ShineLAN-X/releases/dapboot.bin 0x08000000
ShineLAN-X/releases/dapboot.bin 0x08000000
# NuttX Firmware (0x08002000) # NuttX Firmware
~/.platformio/packages/tool-stm32duino/stlink/st-flash write \ st-flash write ShineLAN-X/releases/nuttx-mbusd-shinelanx-dfu.bin 0x08002000
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** **Schritt 2 — Add-on in Home Assistant installieren**
1. **Einstellungen → Add-ons → Add-on-Store → ⋮ → Repositories** 1. **Einstellungen → Add-ons → Add-on-Store → ⋮ → Repositories**
2. URL eintragen: `https://gitea.bitfire.work/retr0/shinebridge` 2. URL: `https://gitea.bitfire.work/retr0/shinebridge`
3. „ShineBridge" → Installieren 3. „ShineBridge" → Installieren → Starten
4. MQTT-Zugangsdaten in der Add-on-Konfiguration eintragen 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": Im Web UI → „＋ Gerät hinzufügen":
- Name (z.B. „Dach Süd") - Name, Modell, IP des ShineLAN-X, MQTT Topic-Präfix
- Modell auswählen
- IP-Adresse des ShineLAN-X
- MQTT Topic-Präfix (z.B. `growatt/dach`)
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)
``` Das Aggregat-Gerät „ShineBridge Gesamt" stellt folgende Sensoren bereit:
0x08000000 dapboot (7 KB) ← Bootloader, ermöglicht OTA via USB DFU
0x08002000 NuttX (93 KB) ← Modbus RTU ↔ TCP Gateway auf Port 502
```
### Hardware ShineLAN-X | Sensor | Beschreibung |
| Komponente | Details |
|---|---| |---|---|
| MCU | STM32F103RC (256 kB Flash, 64 kB RAM) | | PV Gesamtleistung | Summe aller PV-Eingänge (W) |
| Ethernet | ENC28J60 (SPI2) | | AC Gesamtleistung | Summe aller AC-Ausgänge (W) |
| USB | PA11=D−, PA12=D+, PA8=Pullup | | Netzleistung | Netzbezug/Einspeisung via SDM-630 (W) |
| Debug UART | USART1, PA9=TX, PA10=RX, 115200 Baud | | Netzbezug / Einspeisung Gesamt | kWh-Zähler für Energie-Dashboard |
| SWD | PA13=SWDIO, PA14=SWCLK | | Batterie Ladezustand Ø | Durchschnitt aller Batterien (%) |
| LEDs | PC7 (blau intern), PB1 (rot), PB0 (grün), PC5 (blau RGB) |
### 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 0x08000000 dapboot (7 KB) ← Bootloader für USB DFU OTA
│ RS485 / Modbus RTU 0x08002000 NuttX (93 KB) ← Modbus RTU ↔ TCP, Port 502
[ShineWifi-X] ← ESP8266 mit ESPHome-Firmware
│ WLAN
[Home Assistant OS] ← native ESPHome-Integration
``` ```
### 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 1500 TL-X | `ShineWifi-X/Growatt MIC 1500 TL-X/` |
| Growatt MIC 2000 TL-X | `ShineWifi-X/Growatt MIC 2000 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 SPH 5000 TL3-BH-UP | `ShineWifi-X/Growatt SPH 5000 TL3/` |
| Growatt MOD 6000 TL3-XH | `ShineWifi-X/Growatt MOD 6000 TL3-XH/` | | 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 Portables Diagnose-Tool für Techniker. Raspberry Pi 3B als Gateway: LAN zum ShineLAN-X, WiFi-Hotspot für MacBook/Tablet.
2. WLAN-Zugangsdaten und API-Key eintragen
3. Erstinstallation via seriell: ```
```bash [Wechselrichter] →USB→ [ShineLAN-X] →LAN→ [Pi 3B] →WiFi→ [MacBook/Tablet]
esphome run ShineWifi-X/Growatt\ MIC\ 1500\ TL-X/*.yaml 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 ## Repository-Struktur
``` ```
. shinebridge/
├── README.md ├── haos-addon/ ← HAOS Add-on
├── haos-addon/ ← HAOS Add-on (ShineLAN-X) │ ├── config.yaml
│ ├── config.yaml # Add-on Manifest
│ ├── Dockerfile │ ├── Dockerfile
│ ├── build.yaml
│ └── src/ │ └── src/
│ ├── main.py # Flask + Poll-Threads │ ├── main.py # Flask, Poll-Threads, REST API
│ ├── modbus_client.py # pymodbus Modbus TCP │ ├── modbus_client.py # Modbus TCP, Float32-Dekodierung
│ ├── mqtt_publisher.py # MQTT Discovery │ ├── mqtt_publisher.py # MQTT Discovery + Aggregat
│ ├── inverters.py # Register-Definitionen │ ├── inverters.py # Register-Maps aller Geräte
│ └── web/index.html # Web UI │ ├── history.py # SQLite Persistenz
│ └── web/index.html # Web UI
├── ShineLAN-X/ ├── ShineLAN-X/
│ ├── firmware/ # Arduino-Stack (aufgegeben, rx=0)
│ └── releases/ │ └── releases/
│ ├── nuttx-mbusd-shinelanx.bin # NuttX ohne DFU │ ├── dapboot.bin
│ └── nuttx-mbusd-shinelanx-dfu.bin # NuttX mit dapboot (empfohlen) │ └── nuttx-mbusd-shinelanx-dfu.bin
├── ShineWifi-X/ ← ESPHome Configs ├── ShineWifi-X/ ← ESPHome Configs
│ ├── Growatt MIC 1500 TL-X/ ├── tools/
│ ├── Growatt MIC 2000 TL-X/ │ └── shinediag/ ← Vor-Ort-Diagnose-Tool
│ ├── Growatt SPH 5000 TL3/ │ ├── diagnose.py
│ └── Growatt MOD 6000 TL3-XH/ │ ├── web/index.html
└── shinelanx-modbus/ ← mwalle NuttX Board-Support │ └── setup/ # Pi-Konfiguration + install.sh
└── contrib/dapboot/dapboot.bin ├── 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 ## 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.