From e342fff539953c7fa2aeab394886c0c1b95df0e2 Mon Sep 17 00:00:00 2001 From: retr0 <42kdesigners@gmail.com> Date: Tue, 25 Aug 2026 13:20:57 +0200 Subject: [PATCH] README: auf reines Energiemanagement-Repo aktualisiert, Verweis auf growatt-diagnose-tool Co-Authored-By: Claude Sonnet 5 --- README.md | 211 +++++++++++------------------------------------------- 1 file changed, 40 insertions(+), 171 deletions(-) diff --git a/README.md b/README.md index 2083c9c..0c81d3b 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,19 @@ # 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. +Lokales Energiemanagement für Growatt/Goodwe-Wechselrichter in Home Assistant — ohne Cloud, ohne Hersteller-App. Modbus TCP / UDP, MQTT Discovery, persistente History, PV-Überschussladen, Energie-Dashboard. > **Repository:** `https://gitea.bitfire.work/retr0/shinebridge` +> +> Firmware, Hardware-Diagnose und Flash-Tools für ShineLAN-X/ShineWifi-X liegen seit v1.9.0 in einem eigenen, privaten Repo (`growatt-diagnose-tool`) — dieses Repo ist reines Energiemanagement. --- -## Ü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 +## Architektur ``` Wechselrichter / Energiezähler │ Modbus RTU (RS485 / USB) -[ShineLAN-X] ← STM32F103, NuttX, Modbus RTU ↔ TCP +[ShineLAN-X] ← STM32F103, NuttX, Modbus RTU ↔ TCP (Firmware: growatt-diagnose-tool) │ Modbus TCP Port 502 (LAN) │ │ UDP/8899 (Goodwe) @@ -38,10 +27,10 @@ Wechselrichter / Energiezähler ├── 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 + └── Web UI: Live-Daten, Geräte, Einstellungen ``` -### Features +## Features - **Multi-Gerät** — beliebig viele Wechselrichter + Zähler + Wallbox, jeder als eigenes HA-Gerät - **MQTT Discovery** — Sensoren erscheinen automatisch in HA @@ -51,15 +40,13 @@ Wechselrichter / Energiezähler - **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) +- **EMS-Controller** — PV-Überschussladen der Kathrein Wallbox, Zwangsladen-Fallback mit konfigurierbarem Max-Ladestrom - **Ü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 +## Unterstützte Geräte | Gerät | Typ | Sensoren | Protokoll | |---|---|---|---| @@ -70,13 +57,14 @@ Wechselrichter / Energiezähler | 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) +## 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) +3. **Zwangsladen** — Nach Timeout ohne PV (Standard: 4 h): Laden mit konfiguriertem Max-Ladestrom bis zur Zielzeit (Standard: 06:00 Uhr), Strom wird bei jedem Poll erneut gesetzt (kein Einmal-Write) +4. **Unbekannte Ladezustände** (z. B. Fahrzeug-Störung) pausieren den Strom, ohne den Zwangslade-Timer zurückzusetzen Konfigurierbar pro Gerät im Web UI: @@ -86,10 +74,13 @@ Konfigurierbar pro Gerät im Web UI: | Timeout ohne PV | Stunden bis Zwangsladen | 4 h | | Vollladung bis | Zielzeit für Zwangsladen | 06:00 | | Anzahl Phasen | 1 / 2 / 3-phasig | 3 | +| **Max. Ladestrom** | Obergrenze fürs Zwangsladen — auf die tatsächliche Wallbox-/Zuleitungs-Absicherung setzen | 32 A | -> **Hinweis:** Die EMS-Funktion muss in der Kathrein easyOperate-App aktiviert sein. +> **Wichtig:** Max. Ladestrom niemals höher als die real installierte Wallbox stellen (z. B. 16 A bei einer 11-kW-Wallbox) — sonst fordert das Zwangsladen mehr an, als die Hardware liefern kann, was bei manchen Fahrzeugen zu Ladefehlern führt. +> +> Die EMS-Funktion muss zusätzlich in der Kathrein easyOperate-App aktiviert sein. -### Netzleistung (grid_power) +## Netzleistung (grid_power) Der Sensor `grid_power` zeigt die Netzleistung intuitiv: - **Positiv** = Netzbezug (Strom vom Netz) @@ -97,37 +88,27 @@ Der Sensor `grid_power` zeigt die Netzleistung intuitiv: Bei reinen Growatt-Anlagen (ohne Goodwe) wird `power_to_grid` als Proxy verwendet. -### Installation +## Installation -**Schritt 1 — Add-on in Home Assistant installieren** +**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** +**ShineLAN-X flashen** -Beim ersten Start erscheint der **Setup-Wizard** automatisch. Der Tab **Flash** im Web UI führt durch beide Szenarien: +Das Flashen des ShineLAN-X-Sticks (OTA oder ST-Link-Erstflash) läuft über das separate [growatt-diagnose-tool](https://gitea.bitfire.work/retr0/growatt-diagnose-tool) — dort auch die Firmware-Quelle und Doku. -- **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. +**Gerät konfigurieren** -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): +Im Web UI → „＋ Gerät hinzufügen": - Name, Modell, IP, Port, Modbus-Adresse, MQTT Topic-Präfix, Abfrageintervall -- Bei Kathrein Wallbox: EMS-Parameter konfigurieren +- Bei Kathrein Wallbox: EMS-Parameter konfigurieren (inkl. Max. Ladestrom!) Sensoren erscheinen danach unter **Einstellungen → Geräte & Dienste → MQTT**. -### Aggregat-Sensoren (Energie-Dashboard) +## Aggregat-Sensoren (Energie-Dashboard) Das Aggregat-Gerät „ShineBridge Gesamt" stellt folgende Sensoren bereit: @@ -139,7 +120,7 @@ Das Aggregat-Gerät „ShineBridge Gesamt" stellt folgende Sensoren bereit: | Batterie Ladezustand Ø | Durchschnitt aller Batterien (%) | | Batterie Lade-/Entladeleistung | Summe (W) | -### History API +## History API ``` GET /api/history?inv_id=&sensor_id=&hours=<1-168> @@ -147,138 +128,26 @@ GET /api/history?inv_id=&sensor_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 +└── haos-addon/ ← HAOS Add-on (einziger Inhalt dieses Repos) + ├── config.yaml + ├── Dockerfile + └── src/ + ├── main.py # Flask, Poll-Threads, REST API + ├── 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, Einstellungen) ``` ---- +Firmware (ShineLAN-X, ShineWifi-X) und das Vor-Ort-Diagnose-Tool (ShineDiag) liegen im separaten, privaten Repo [`growatt-diagnose-tool`](https://gitea.bitfire.work/retr0/growatt-diagnose-tool). ## Lizenz