Shinebridge/README.md

# 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.

> **Repository:** `https://gitea.bitfire.work/retr0/shinebridge`

---

## Übersicht

| Komponente | Beschreibung | Status |
|---|---|---|
| **ShineBridge Add-on** | HAOS Add-on: Modbus TCP / UDP → MQTT Discovery | ✅ v1.5.3 |
| **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 |

---

## 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]
    ├── 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)
    └── Web UI: Geräte verwalten, Live-Daten, Sparklines, EMS-Konfig
```

### 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)
- **Sparklines** — Live-Graphen der letzten 5 Minuten pro Sensor
- **EMS-Controller** — PV-Überschussladen der Kathrein Wallbox, Zwangsladen-Fallback
- **Konfig-Export/Import** — JSON im Einstellungen-Tab
- **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` (Goodwe) 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 (nur Einspeisung bekannt).

### Installation

**Schritt 1 — NuttX auf den ShineLAN-X flashen** *(einmalig, ST-Link nötig)*

```bash
# dapboot Bootloader
st-flash write ShineLAN-X/releases/dapboot.bin 0x08000000

# NuttX Firmware
st-flash write ShineLAN-X/releases/nuttx-mbusd-shinelanx-dfu.bin 0x08002000
```

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: `https://gitea.bitfire.work/retr0/shinebridge`
3. „ShineBridge" → Installieren → Starten
4. MQTT-Zugangsdaten in der Add-on-Konfiguration eintragen
5. Web UI öffnen → Gerät hinzufügen

**Schritt 3 — Gerät konfigurieren**

Im Web UI → „＋ Gerät hinzufügen":
- 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.

> **Firmware von [mwalle (Martin Walle)](https://github.com/mwalle/shinelanx-modbus)**
> Das Binary `nuttx-mbusd-shinelanx-dfu.bin` ist das Werk von Martin Walle und wird hier unverändert weitergegeben.
> Lizenzen: Board-Support Apache 2.0 · mbusd BSD 3-Clause · Gateway-App BSD 2-Clause.
> Quellcode und Kompilieranleitung: [github.com/mwalle/shinelanx-modbus](https://github.com/mwalle/shinelanx-modbus)

### Flash-Layout

```
0x08000000  dapboot  (7 KB)   ← Bootloader für USB DFU OTA
0x08002000  NuttX    (93 KB)  ← Modbus RTU ↔ TCP, Port 502
```

### Hardware

| 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/` |

---

## 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
│   └── src/
│       ├── main.py              # Flask, Poll-Threads, REST API, Aggregation
│       ├── 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
├── ShineLAN-X/
│   └── releases/
│       ├── dapboot.bin
│       └── nuttx-mbusd-shinelanx-dfu.bin
├── 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.