Initial SolarEdge Optimizer Home Assistant App

2026-08-10 09:04:35 +02:00
commit f2887a0ab4
38 changed files with 4253 additions and 0 deletions
@@ -0,0 +1,132 @@
+# SolarEdge Optimizer Data App
+
+Diese Home Assistant App stellt die Optimierer-Daten einer SolarEdge-Anlage als
+lokale, gecachte HTTP-API bereit. Sie läuft unabhängig von einem Browser und
+aktualisiert die Daten standardmäßig alle zehn Minuten.
+
+> Die verwendeten Optimierer-Endpunkte sind interne, nicht offiziell
+> dokumentierte SolarEdge-Portal-Endpunkte. SolarEdge kann sie jederzeit ändern.
+> Verwende die App nur für Anlagen, auf die du zugreifen darfst.
+
+## Konfiguration
+
+```yaml
+username: owner@example.com
+password: dein-portal-passwort
+site_id: "4886699"
+poll_interval_minutes: 10
+```
+
+- `username`: Benutzername des SolarEdge Monitoring Portals.
+- `password`: Portal-Passwort; wird weder geloggt noch von der API ausgegeben.
+- `site_id`: numerische SolarEdge Site-ID.
+- `poll_interval_minutes`: Aktualisierungsintervall, mindestens zehn Minuten.
+
+Die Zeitzone liest die App automatisch aus Home Assistant über die
+Supervisor-API. Dadurch wird der Tageswechsel passend zur Home-Assistant-Zeit
+berechnet.
+
+## HTTP API
+
+### `GET /api/optimizers`
+
+Liefert den letzten gecachten Datensatz:
+
+```json
+{
+  "status": "ok",
+  "siteId": "4886699",
+  "date": "2026-08-10",
+  "timeZone": "Europe/Berlin",
+  "fetchedAt": "2026-08-10T08:00:00.000Z",
+  "nextRefreshAt": "2026-08-10T08:10:00.000Z",
+  "optimizerCount": 34,
+  "successfulOptimizerCount": 34,
+  "failedOptimizerCount": 0,
+  "totalDailyEnergyWh": 12345,
+  "totalCurrentPowerW": 4567,
+  "optimizers": [
+    {
+      "serial": "OPTIMIZER_SERIAL",
+      "inverterId": "1",
+      "stringId": "1.1",
+      "optimizerId": "1.1.1",
+      "dailyEnergyWh": 321.5,
+      "currentPowerW": 123.4,
+      "lastMeasurement": "2026-08-10T07:59:00Z"
+    }
+  ]
+}
+```
+
+`status` ist:
+
+- `ok`: alle Tagesenergie-Werte wurden gelesen.
+- `partial`: einzelne Optimierer-Abfragen sind fehlgeschlagen.
+- `stale`: der letzte vollständige Abruf ist fehlgeschlagen; die vorherigen
+  Daten bleiben verfügbar.
+
+Der API-Aufruf selbst löst keinen SolarEdge-Abruf aus. Er liefert immer den
+Cache und kann daher auch häufiger als alle zehn Minuten gelesen werden.
+
+### `GET /health`
+
+Kompakter Status für Überwachung und Docker Healthchecks. Während des ersten
+Abrufs antworten `/health` und `/api/optimizers` mit HTTP 503. Danach liefern sie
+HTTP 200, solange mindestens ein gecachter Datensatz vorhanden ist.
+
+### `GET /`
+
+Liefert dieselben Daten wie `/api/optimizers` und ist über Home Assistant Ingress
+im App-Panel erreichbar.
+
+## Zugriff aus Home Assistant
+
+Die App veröffentlicht standardmäßig keinen ungeschützten Port im lokalen
+Netz. Home Assistant und andere Apps können sie über das interne App-Netzwerk
+erreichen. Bei einer lokalen Installation lautet der Hostname typischerweise
+`local-solaredge-optimizer-data`:
+
+```text
+http://local-solaredge-optimizer-data:8099/api/optimizers
+```
+
+Bei Installation aus einem App-Repository ersetzt dessen Repository-ID den
+Präfix `local`. Die JSON-Ansicht für Menschen ist unabhängig davon über Ingress
+im Home-Assistant-Seitenpanel verfügbar.
+
+## Installation als App-Repository
+
+Füge im Home-Assistant-App-Store unter **⋮ → Repositories** diese URL hinzu:
+
+```text
+https://git.jensneuber.de/jens/solaredge-optimizers
+```
+
+Installiere anschließend **SolarEdge Optimizer Data**, pflege Benutzername,
+Passwort und Site-ID im Tab **Konfiguration** und starte die App. Der Supervisor
+lädt das zur App-Version passende Multi-Arch-Image aus der Registry.
+
+## Lokale Installation
+
+Der Ordner ist ein eigenständig baubares Home-Assistant-App-Paket. Kopiere ihn
+für eine lokale Installation nach:
+
+```text
+/addons/solaredge-optimizer-data
+```
+
+Lade anschließend den App Store neu, installiere **SolarEdge Optimizer Data**,
+pflege Benutzername, Passwort und Site-ID im Tab **Konfiguration** und starte
+die App. Der Supervisor lädt dabei das zur App-Version passende Multi-Arch-Image
+`git.jensneuber.de/jens/solaredgeoptimizers:0.1.0`.
+
+## Sicherheit und Betrieb
+
+- Anmeldedaten werden ausschließlich aus `/data/options.json` gelesen.
+- Tokens, Cookies und Passwörter werden nicht persistiert oder geloggt.
+- SolarEdge-Sitzung und Cookies existieren nur im Arbeitsspeicher.
+- Gleichzeitige Energie-Abfragen sind auf drei begrenzt.
+- Das Mindestintervall von zehn Minuten reduziert die Last auf den internen,
+  nicht dokumentierten SolarEdge-Endpunkten.
+- MFA-/OTP-Anmeldungen werden derzeit nicht unterstützt.