diff --git a/referenz/senec-collector/index.md b/referenz/senec-collector/index.md index 6b91439..6b2f657 100644 --- a/referenz/senec-collector/index.md +++ b/referenz/senec-collector/index.md @@ -5,17 +5,96 @@ parent: Referenz nav_order: 2 --- -Der **SENEC-Collector** ist eine Komponente, die Daten von einem SENEC-Stromspeicher ausliest und in eine InfluxDB schreibt. +Der **SENEC-Collector** sammelt die Messwerte, die von einem SENEC Stromspeicher gemeldet werden und schreibt diese in die InfluxDB. -Grundsätzlich sind zwei verschiedene Betriebsmodi (Adapter) möglich: +Erfolgreich getestet wurde der Collector mit folgenden Stromspeichern: -- **Lokal:** Direkter Zugriff auf den SENEC-Stromspeicher über dessen lokale IP-Adresse. Die Daten werden über die lala.cgi-Schnittstelle ausgelesen. Möglich ist das für den V2.1 und V3, nicht aber beim Home 4 (dieser hat diese Schnittstelle nicht). Ein Auslesen der Messwerte ist in einem kurzen Intervall möglich, vorgegeben sind 5 Sekunden. +- SENEC.Home V2.1 +- SENEC.Home V3 +- SENEC.Home 4 -- **Cloud:** Der SENEC-Collector liest die Daten aus der SENEC-Cloud aus und verwendet dazu die Schnittstelle, die von SENEC für die App bereitgestellt wird, d.h. es sind die SENEC-Zugangsdaten anzugeben (E-Mail und Passwort). Möglich ist das auch für den Home 4. Das Auslesen der Messwerte ist nur einem einem längeren Intervall erlaubt, das vom Gerät abhängt. Beim Home 4 ist eine Abfrage im 1m-Takt möglich, beim V2.1 und V3 im 5-Minuten-Takt. +{:.note} -Beim Home 4 ist es also nicht möglich, den SENEC-Collector im lokalen Modus zu betreiben. Dort ist nur der Cloud-Modus möglich. +Wer den Collector mit einen anderen SENEC-Stromspeicher erfolgreich getestet hat, kann die Liste gerne ergänzen. -Beim V2.1 und V3 ist es möglich, sich für einen der beiden Adapter frei zu entscheiden. Dies eröffnet die Möglichkeit, SOLECTRUS rein in der Cloud zu betreiben, also ohne einen Raspberry o.ä. im lokalen Netzwerk. Diesem Vorteil steht der Nachteil gegenüber, dass die Daten nicht so häufig aktualisiert werden (einmal alle 5min, statt alle 5s). +## Betriebsmodi -Quelltext im GitHub-Repository: \ +Grundsätzlich kann der Collector in zwei verschiedenen **Betriebsmodi** eingesetzt werden: + +- **Lokal:** Direkter Zugriff auf den SENEC-Stromspeicher über dessen lokale IP-Adresse. Die Daten werden über die `lala.cgi`-Schnittstelle ausgelesen. Möglich ist das beim V2.1 und V3, nicht aber beim Home 4, denn dieser hat keine lokale Schnittstelle. Ein Auslesen der Messwerte ist in einem kurzen Intervall möglich, standardmäßig sind es 5 Sekunden. + +- **Cloud:** Abholen der Messwerte aus der SENEC-Cloud aus unter Verwendung der Schnittstelle, die von SENEC für die Mobil-Apps bereitgestellt wird. Für den Zugriff sind SENEC-Zugangsdaten anzugeben (E-Mail und Passwort). Möglich ist das auch für den Home 4. Das Auslesen der Messwerte ist nur einem einem längeren Intervall erlaubt, das vom Gerät abhängt. Beim Home 4 ist eine Abfrage im 1-Minuten-Takt möglich, beim V2.1 und V3 im 5-Minuten-Takt. + +### Vergleich der Betriebsmodi + +| | Lokal | Cloud | +| :-------------- | :-------- | :-------- | +| SENEC.Home V2.1 | Ja (5sec) | Ja (5min) | +| SENEC.Home V3 | Ja (5sec) | Ja (5min) | +| SENEC.Home 4 | Nein | Ja (1min) | + +Beim V2.1 und V3 ist es also möglich, sich für einen der beiden Adapter zu entscheiden. Dies eröffnet die Möglichkeit, SOLECTRUS vollständig auf einem Cloud-Server zu betreiben, also ohne einen Raspberry o.ä. im lokalen Netzwerk. Diesem Vorteil steht der Nachteil gegenüber, dass die Daten nicht so häufig aktualisiert werden (nur alle 5 Minuten, statt alle 5 Sekunden). + +## Überwachte Messwerte + +Der Collector schreibt die folgenden Messwerte als _Field_ in das angegebene _Measurement_ der InfluxDB. Einige Messwerte sind nur im lokalen Betrieb verfügbar. + +- `application_version`: Version der Firmware +- `bat_charge_current`: Batterie-Ladestrom, in A +- `bat_fuel_charge`: Batterie-Ladestand, in % +- `bat_power_minus`: Batterie-Entladeleistung, in W +- `bat_power_plus`: Batterie-Ladeleistung, in W +- `bat_voltage`: Batterie-Spannung, in V +- `case_temp`: Gehäuse-Temperatur, in °C +- `current_state_code`: Aktueller Betriebszustand, als Zahl (nur Lokal) +- `current_state_ok`: Aktueller Betriebszustand gilt als OK, Ja/Nein +- `current_state`: Aktueller Betriebszustand, als Text +- `ev_connected`: Elektroauto verbunden, Ja/Nein +- `grid_power_minus`: Netzeinspeisung, in W +- `grid_power_plus`: Netzbezug, in W +- `house_power`: Hausverbrauch, in W +- `inverter_power`: Erzeugte Leistung des Wechselrichters, in W +- `mpp1_power`: Leistung des MPP1, in W (nur Lokal) +- `mpp2_power`: Leistung des MPP2, in W (nur Lokal) +- `mpp3_power`: Leistung des MPP3, in W (nur Lokal) +- `power_ratio`: Leistungsbegrenzung, in % (nur Lokal) +- `response_duration`: Dauer der Antwort, in ms (nur Lokal) +- `wallbox_charge_power`: Wallbox-Ladeleistung, in W +- `wallbox_charge_power0`: Wallbox-Ladeleistung für erste Wallbox, in W (nur Lokal) +- `wallbox_charge_power1`: Wallbox-Ladeleistung für zweite Wallbox, in W (nur Lokal) +- `wallbox_charge_power2`: Wallbox-Ladeleistung für dritte Wallbox, in W (nur Lokal) +- `wallbox_charge_power3`: Wallbox-Ladeleistung für vierte Wallbox, in W (nur Lokal) + +## Protokollierung + +Der Collector schreibt ein Protokoll in der Docker-Log, das im Normalfall so aussieht: + +```plaintext +SENEC collector for SOLECTRUS, Version 0.16.1, built at 2024-09-03T23:21:53.925Z +https://github.com/solectrus/senec-collector +Copyright (c) 2020-2024 Georg Ledermann, released under the MIT License + +Using Ruby 3.3.5 on platform x86_64-linux-musl +Pushing to InfluxDB at http://influxdb, bucket solectrus, measurement SENEC +Pulling from your local SENEC at https://192.168.178.29 every 5 seconds + +Getting state names (language: de) from SENEC by parsing source code... +OK, got 99 state names + +Got record #1 at 2024-10-02 10:00:42 +0200 within 7 ms, LADEN, Inverter 766 W, House 413 W, Wallbox 0 W +Successfully pushed record #1 to InfluxDB +... +``` + +Das Protokoll kann über folgenden Befehl abgerufen werden: + +```bash +docker logs [container-name] +``` + +Bei Problemen oder Fehlern (z.B. wenn der Stromspeicher oder die InfluxDB nicht erreichbar ist) wird dies ebenfalls protokolliert. Es empfiehlt sich daher, im Zweifelsfall zuerst das Protokoll zu prüfen. + +## Quelltext + +Der SENEC-Collector ist in Ruby implementiert, der Quelltext ist auf GitHub verfügbar: \ [github.com/solectrus/senec-collector](https://github.com/solectrus/senec-collector) diff --git a/referenz/senec-collector/konfiguration.md b/referenz/senec-collector/konfiguration.md index c3a480e..5caed64 100644 --- a/referenz/senec-collector/konfiguration.md +++ b/referenz/senec-collector/konfiguration.md @@ -4,9 +4,9 @@ layout: page parent: SENEC-Collector --- -Der SENEC-Collector wird in das Gesamt-Setup von SOLECTRUS integriert, d.h. die bestehenden Dateien `compose.yaml` und `.env` müssen erweitert werden. Hier nur die relevanten Teile: +# Konfigurieren des SENEC-Collectors -Erforderlich ist eine Schreibberechtigung auf InfluxDB, um dorthin Messwerte schreiben zu können. +Der Shelly-Collector wird üblicherweise in die Gesamtkonfiguration von SOLECTRUS integriert, d.h. die bestehenden Dateien `compose.yaml` und `.env` sind zu erweitern. ## compose.yaml @@ -50,58 +50,132 @@ services: # ... ``` -## .env +{:.note} + +Die beiden Variablen `INFLUX_TOKEN` und `INFLUX_MEASUREMENT` werden anders lautenden Umgebungsvariablen entnommen. Dies ermöglicht eine Nutzung von Variablen für verschiedene Container und vermeidet Redundanzen. + +## Umgebungsvariablen + +### `SENEC_ADAPTER` + +Betriebsmodus des Collectors + +Erlaubte Werte: `local` oder `cloud` \ +Standard: `local` + +### `SENEC_HOST` + +Hostname des SENEC Stromspeichers. Dies ist üblicherweise eine IP-Adresse, kann aber auch eine lokale Domain sein. Es darf **kein** `http://` oder `https://` enthalten sein! + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `local` gesetzt ist. + +### `SENEC_SCHEMA` + +Das zu verwendende Potokoll für die Verbindung zum SENEC-Stromspeicher. + +Erlaubte Werte: `http`, `https` \ +Standard: `https` + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `local` gesetzt ist. + +### `SENEC_LANGUAGE` + +Die Sprache, die für Status-Texte verwendet werden soll. + +Erlaubte Werte: `de` (Deutsch), `en` (Englisch), `it` (Italienisch) \ +Standard: `de` + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `local` gesetzt ist. + +### `SENEC_USERNAME` + +E-Mail-Adresse für die Anmeldung bei `mein-senec.de`. + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `cloud` gesetzt ist. + +### `SENEC_PASSWORD` + +Passwort für die Anmeldung bei `mein-senec.de`. + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `cloud` gesetzt ist. + +### `SENEC_SYSTEM_ID` + +Die System-ID des SENEC-Geräts. Kann leer bleiben, wenn es nur ein System gibt. Der Collector ermittelt dann die verfügbaren IDs, listet sie im Protokoll auf und verwendet die **erste**. + +Um eine andere als die erste ID zu verwenden, sollte die Angabe nächst leer bleiben, der Collector gestartet und die ID aus dem Protokoll entnommen werden. Die gewünschte ID kann dann in die Umgebungsvariablen eingetragen werden und wird beim nächsten Start verwendet. + +Wird nur verwendet, wenn `SENEC_ADAPTER` auf `cloud` gesetzt ist. + +### `SENEC_INTERVAL` + +Das Intervall in Sekunden für die Häufigkeit der Datenabfrage + +Wenn `SENEC_ADAPTER` auf `cloud` gesetzt ist, ist das Minimum 30 Sekunden, Standard ist 60 Sekunden. +Wenn `SENEC_ADAPTER` auf `local` gesetzt ist, ist das Minimum 5 Sekunden, Standard ist 5 Sekunden. + +### `SENEC_IGNORE` + +Deaktivieren bestimmter Messwerte, die nicht an InfluxDB gesendet werden sollen. +Dies ist nützlich, wenn einzelne Messwerte (z.B. der Wallbox) aus einer anderen Quelle entnommen werden sollen. + +Komma-getrennte Liste von Feldern, keine Leerzeichen. Beispiel: ```properties -# Welcher Adapter soll verwendet werden? -# Werte: local, cloud (Standard: local) -SENEC_ADAPTER=local +SENEC_IGNORE=wallbox_charge_power,grid_power_minus +``` -# Die IP-Adresse oder der Hostname Ihres SENEC-Geräts -# Wird nur bei Verwendung des lokalen Adapters genutzt -SENEC_HOST=192.168.178.12 - -# Das zu verwendende Potokoll -# Werte: http, https (Standard: https) -# Wird nur bei Verwendung des lokalen Adapters genutzt -SENEC_SCHEMA=https - -# Die Sprache, die für Status-Texte verwendet werden soll. -# Werte: de, en, it (Standard: de) -# Wird nur bei Verwendung des lokalen Adapters genutzt -SENEC_LANGUAGE=de - -# Anmeldedaten für mein-senec.de -# Wird nur bei Verwendung des Cloud-Adapters genutzt -SENEC_USERNAME=me@example.com -SENEC_PASSWORD=my-senec-password - -# Die System-ID des SENEC-Geräts -# Wird nur bei Verwendung des Cloud-Adapters genutzt -# Kann leer bleiben, wenn es nur ein System gibt. Der Collector ermittelt -# dann die verfügbaren IDs, listet sie im Protokoll auf und verwendet die erste. -SENEC_SYSTEM_ID=123456 - -# Das Intervall in Sekunden für die Häufigkeit der Datenabfrage -# Minimum für den lokalen Adapter ist 5 Sekunden. -# Minimum für den Cloud-Adapter ist 30 Sekunden. -SENEC_INTERVAL=5 +Optional, Standard ist leer (d.h. alle Messwerte werden gesendet) -# Speicherort ("Measurement") für InfluxDB -SENEC_INFLUX_MEASUREMENT=SENEC +### `INFLUX_HOST` -# Optional: Deaktivieren bestimmter Messwerte, die nicht an InfluxDB gesendet werden sollen. -# Dies ist nützlich, wenn einzelne Daten (z.B. Wallbox) aus einer anderen Quelle entnommen werden sollen. -# Komma-getrennte Liste von Feldern, keine Leerzeichen. Beispiel: -# SENEC_IGNORE=wallbox_charge_power,grid_power_minus +Hostname des InfluxDB-Servers. Im Normalfall, wenn InfluxDB im gleichen Docker-Netzwerk läuft, ist das der Name des Containers (z.B. `influxdb`). Es kann aber auch ein externer InfluxDB-Server sein, z.B. `influxdb.example.com`. -# Zugangsdaten für InfluxDB -INFLUX_HOST=influxdb.example.com -INFLUX_SCHEMA=https -INFLUX_PORT=443 -INFLUX_TOKEN=my-super-secret-write-token -INFLUX_ORG=solectrus +### `INFLUX_SCHEMA` + +Schema für die Verbindung zu InfluxDB. Bei Verwendung einer externen InfluxDB, die über TLS abgesichert ist, muss dieser Wert auf `https` gesetzt werden. + +Optional, Standard ist `http` + +### `INFLUX_PORT` + +Port für die Verbindung zu InfluxDB. + +Optional, Standard ist `8086` + +Bei Verwendung einer externen, per TLS abgesicherten InfluxDB kann z.B. `443` eingestellt werden. + +### `INFLUX_TOKEN` + +Token für den Zugriff auf InfluxDB. Dieser Token muss in InfluxDB erstellt werden und die Berechtigung haben, Daten in den angegebenen Bucket zu **schreiben**. -# Der Name des Buckets in InfluxDB +### `INFLUX_ORG` + +Organisation in InfluxDB, in der die Messwerte gespeichert werden sollen. + +### `INFLUX_BUCKET` + +Bucket in InfluxDB, in der die Messwerte gespeichert werden sollen. + +### `INFLUX_MEASUREMENT` + +Name des Measurements in InfluxDB, das die Messwerte aufnehmen soll. + +Optional, Standard ist `SENEC` + +## Beispielhafte .env + +```properties +SENEC_ADAPTER=local +SENEC_HOST=192.168.178.29 +SENEC_INTERVAL=5 +SENEC_IGNORE=wallbox_charge_power +SENEC_INFLUX_MEASUREMENT=SENEC + +INFLUX_HOST=influxdb +INFLUX_SCHEMA=http +INFLUX_PORT=8086 +INFLUX_TOKEN_WRITE=my-super-secret-admin-token +INFLUX_ORG=solectrus INFLUX_BUCKET=solectrus ```