retr0
e72ad2db19
Flash-Wizard, OTA-Abschnitt (Zwei-Phasen), Setup-Wizard, Finanzen-Tab, Abschlags-Tracker, Port-Sicherheit, Überschuss-Geräte, repo-Struktur. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
286 lines
11 KiB
Markdown
286 lines
11 KiB
Markdown
# 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:
|
||
```bash
|
||
# 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)](https://github.com/mwalle/shinelanx-modbus)**
|
||
> Lizenzen: Board-Support Apache 2.0 · mbusd BSD 3-Clause · Gateway-App BSD 2-Clause.
|
||
> Quellcode: [github.com/mwalle/shinelanx-modbus](https://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):
|
||
```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/` |
|
||
|
||
---
|
||
|
||
## 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:**
|
||
```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
|
||
|
||
```
|
||
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.
|