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