README: auf reines Energiemanagement-Repo aktualisiert, Verweis auf growatt-diagnose-tool

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-25 13:20:57 +02:00
parent ee404065ce
commit e342fff539
1 changed files with 40 additions and 171 deletions
@@ -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=<id>&sensor_id=<id>&hours=<1-168>
@@ -147,138 +128,26 @@ 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
+└── 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