Shinebridge/README.md

# Growatt Wechselrichter → Home Assistant (ohne Cloud)

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:

| Hardware | Lösung | Status |
|---|---|---|
| **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)

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.

### Wie es funktioniert

```
Growatt Wechselrichter
    │  USB (Modbus RTU)
[ShineLAN-X]  ← STM32F103 mit NuttX-Firmware
    │  Modbus TCP Port 502 (Ethernet)
[HAOS Add-on]
    ├── liest Sensordaten per Modbus TCP
    ├── publiziert via MQTT Discovery → Home Assistant Sensoren
    └── Web UI (Wechselrichter verwalten, Live-Daten, Verlaufsgraphen)
```

### Features

- **Mehrere Wechselrichter** — beliebig viele, jeder mit eigenem HA-Gerät
- **MQTT Discovery** — Sensoren erscheinen automatisch in HA (kein manuelles Anlegen)
- **Web UI** — Wechselrichter hinzufügen/bearbeiten, Live-Daten mit Sparklines (5 Min)
- **OTA-Updates** — NuttX-Firmware via USB DFU aktualisierbar (kein ST-Link nötig)
- **Kein Cloud-Zwang** — alles lokal im Heimnetz

### Unterstützte Wechselrichter-Modelle

| Modell | Typ | Sensoren |
|---|---|---|
| Growatt MIC 1500/2000 TL-X | 1-phasig | 10 |
| Growatt SPH 5000 TL3-BH-UP | 3-phasig + Batterie | 28 |
| Growatt MOD 6000 TL3-XH | 3-phasig | 17 |

### Installation (HAOS Add-on)

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

```bash
# dapboot Bootloader (0x08000000)
~/.platformio/packages/tool-stm32duino/stlink/st-flash write \
  ShineLAN-X/releases/dapboot.bin 0x08000000

# NuttX Firmware (0x08002000)
~/.platformio/packages/tool-stm32duino/stlink/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 eintragen: `https://gitea.bitfire.work/retr0/shinebridge`
3. „ShineBridge" → Installieren
4. MQTT-Zugangsdaten in der Add-on-Konfiguration eintragen
5. Starten → Web UI öffnen → Wechselrichter hinzufügen

**Schritt 3 — Wechselrichter im Web UI konfigurieren**

Im Tab „Wechselrichter" → „＋ Wechselrichter hinzufügen":
- Name (z.B. „Dach Süd")
- 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**.

### Flash-Layout NuttX

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

| Komponente | Details |
|---|---|
| MCU | STM32F103RC (256 kB Flash, 64 kB RAM) |
| Ethernet | ENC28J60 (SPI2) |
| USB | PA11=D−, PA12=D+, PA8=Pullup |
| Debug UART | USART1, PA9=TX, PA10=RX, 115200 Baud |
| SWD | PA13=SWDIO, PA14=SWCLK |
| LEDs | PC7 (blau intern), PB1 (rot), PB0 (grün), PC5 (blau RGB) |

---

## Lösung 2: ShineWifi-X (ESPHome)

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.

```
Growatt Wechselrichter
    │  RS485 / Modbus RTU
[ShineWifi-X]  ← ESP8266 mit ESPHome-Firmware
    │  WLAN
[Home Assistant OS]  ← native ESPHome-Integration
```

### Unterstützte Modelle (ShineWifi-X)

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

### ShineWifi-X flashen

> Erstinstallation benötigt einen USB-zu-Serial-Adapter (3,3 V). Danach OTA über WLAN möglich.

1. YAML aus dem passenden Modell-Ordner kopieren
2. WLAN-Zugangsdaten und API-Key eintragen
3. Erstinstallation via seriell:
```bash
esphome run ShineWifi-X/Growatt\ MIC\ 1500\ TL-X/*.yaml
```

UART-Pinbelegung ShineWifi-X: TX→GPIO1, RX→GPIO3, Baud 115200

---

## Repository-Struktur

```
.
├── README.md
├── haos-addon/                        ← HAOS Add-on (ShineLAN-X)
│   ├── config.yaml                    # Add-on Manifest
│   ├── Dockerfile
│   ├── build.yaml
│   └── src/
│       ├── main.py                    # Flask + Poll-Threads
│       ├── modbus_client.py           # pymodbus Modbus TCP
│       ├── mqtt_publisher.py          # MQTT Discovery
│       ├── inverters.py               # Register-Definitionen
│       └── web/index.html             # Web UI
├── ShineLAN-X/
│   ├── firmware/                      # Arduino-Stack (aufgegeben, rx=0)
│   └── releases/
│       ├── nuttx-mbusd-shinelanx.bin      # NuttX ohne DFU
│       └── nuttx-mbusd-shinelanx-dfu.bin  # NuttX mit dapboot (empfohlen)
├── ShineWifi-X/                       ← ESPHome Configs
│   ├── Growatt MIC 1500 TL-X/
│   ├── Growatt MIC 2000 TL-X/
│   ├── Growatt SPH 5000 TL3/
│   └── Growatt MOD 6000 TL3-XH/
└── shinelanx-modbus/                  ← mwalle NuttX Board-Support
    └── contrib/dapboot/dapboot.bin
```

---

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

Frei verwendbar und anpassbar. Keine Garantie für Richtigkeit der Modbus-Register — immer gegen das offizielle Growatt-Datenblatt des jeweiligen Modells prüfen.