Mit invafetch werden Processdata-Werte von Kostal Plenticore Wechselrichtern ausgelesen und zur Weiterverarbeitung in einer Datenbank gespeichert.
Dieses Tool steht in keiner Verbindung zum Unternehmen KOSTAL Solar Electric GmbH und ist kein offizielles Produkt der KOSTAL Solar Electric GmbH oder anderer Tochterunternehmen der Kostal Gruppe.
Übersicht
Invafetch ist einer von mehreren Bausteinen zur Erzeugung eines Grafana-Dashboards für Kostal Plenticore-Wechselrichter. Invafetch liest die Processdata-Werte in regelmäßigen Abständen von der Inverter-API und speichert die Ergebnisse im JSON-Format in einer MariaDB-Tabelle. Das Tool invaps nutzt diese Werte, d.h. liest sie aus und stellt sie Prometheus auf Anfrage zur Verfügung. Grafana wiederum nutzt Prometheus als Datenquelle zur Erstellung eines Dashboards für den Kostal Plenticore Wechselrichter. Hierbei wurde ein modulares Konzept umgesetzt, so dass jeweils eine möglichst kleine Anwendung für eine einzige Aufgabe zuständig ist. Die MariaDB-Datenbank dient dabei als Schnittstelle der Tools invafetch und invaps und damit als Pufferspeicher für die Processdata-Werte. Für eine nähere Beschreibung von invaps siehe im invaps-GitHub-Repository, ein vollständiges Beispiel inkl. Definition des Grafana-Dashboards und eines Docker-Compose-Files, mit dem alle Komponenten in einer Docker-Umgebung gestartet werden können, findet sich ebenfalls bei GitHub im grkopv-dashboard-Repository.
Installation
Die empfohlene Installationsmethode ist die Nutzung des Docker-Images. Daneben kann invafetch aus dem Quellcode wie jedes andere in Go geschriebene Programm installiert werden:
$ git clone https://github.com/geschke/invafetch $ cd invafetch/ $ go build $ go install
Mit diesen Kommandos wird die ausführbare Datei „invafetch“ erzeugt und in die entsprechenden Verzeichnisse kopiert, d.h. nach $HOME/go/bin/invafetch (oder unter Windows %USERPROFILE%\go\bin\invafetch.exe).
Daraufhin kann invafetch einfach in der Kommandozeile gestartet werden.
Konfiguration
Alle auslesbaren Processdata-Werte finden sich in der Datei processdata.json. Dabei handelt es sich um nahezu alle Processdata-Werte, die vom Kostal-Wechselrichter bereitgestellt werden (bis auf die Module scb:export und scb:update). Falls nicht alle Werte ausgelesen und gespeichert werden sollen, können einzelne Processdata-Ids, aber auch vollständige Modul-IDs aus der Datei processdata.json entfernt werden. Beim Start von invafetch wird die Datei einmalig ausgelesen und als Konfigurationsparameter übernommen.
Invafetch nutzt den JSON-Datentyp von MariaDB und setzt eine lauffähige MariaDB-Installation voraus. Die entsprechende Definition der Tabellenstruktur findet sich im Verzeichnis sql/ in der Datei solardata.sql.
Alle Konfigurationsoptionen können entweder in einer Konfigurationsdatei (Standard-Dateiname: ~/.env), als Environment-Variablen oder als Kommandozeilen-Parameter übergeben werden.
Dabei existieren folgende Optionen:
| Environment-Variable | CLI-Parameter | Default-Wert | Beispiel | Hinweis |
|---|---|---|---|---|
| DBHOST | –dbhost | (leer) | „MARIADB DATABASE SERVER“ | Datenbank-Server-Adresse |
| DBUSER | –dbuser | (leer) | „DATABASE USERNAME“ | Datenbank-User |
| DBNAME | –dbname | (leer) | „DATABASE NAME“ | Name der Datenbank |
| DBPASSWORD | –dbpassword | (leer) | „DATABASE PASSWORD“ | Passwort des Datenbank-Users |
| DBPORT | –dbport | „3306“ | „3306“ | Datenbank-Port (optional) |
| INV_SERVER | –server | (leer) | „INVERTER ADDRESS“ | Adresse (FQDN oder IP) des Wechselrichters |
| INV_SCHEME | –scheme | „http“ | „http“ | Schema, mögliche Angaben: http oder https (optional) |
| INV_PASSWORD | –password | (leer) | „INVERTER PASSWORD“ | Passwort des Anlagenbetreibers |
| TIME_REQUEST_DURATION_SECONDS | –time-request | 3 | 20 | Zeitspanne zwischen zwei Requests in Sekunden, d.h. Werte werden alle n Sekunden gelesen |
| TIME_NEW_LOGIN_MINUTES | –time-new-login | 10 | 60 | Dauer einer Session in Minuten. Dabei erfolgt ein Logout und anschließendes Login nach n Minuten, so dass eine neue Session erzeugt wird |
CLI
Wird invafetch ohne Parameter oder mit dem Flag --help bzw. -h aufgerufen, erscheint eine Übersicht der verfügbaren Kommandos:
~$ invafetch A tool for retrieving values from Kostal Plenticore inverters Usage: invafetch [command] Available Commands: completion Generate the autocompletion script for the specified shell help Help about any command info Returns miscellaneous information start Start collecting and storing values from inverter Flags: --config string config file (default is ~/.env) --dbhost string Database host --dbname string Database name --dbpassword string Database password --dbport string Database port (default "3306") --dbuser string Database user -h, --help help for invafetch -p, --password string Password (required) -m, --scheme string Scheme (http or https, default http) -s, --server string Server (e.g. inverter IP address) (required) --time-new-login int Duration in minutes between two logins to inverter and database (default 10) --time-request int Request new processdata every n seconds (default 3) Use "invafetch [command] --help" for more information about a command.
Quick Start
Auf die Installation und Einrichtung der MariaDB-Datenbank wird hier nicht weiter eingegangen. Sollte ein vorhandener MariaDB-Datenbank-Server genutzt werden, muss zunächst eine Datenbank angelegt werden, in der die Tabelle ‚solardata‚ aus der Datei sql/solardata.sql erzeugt wird.
Um die Verbindung zum Wechselrichter zu testen, kann das Kommando „info“ verwendet werden. Wenn die Verbindung erfolgreich hergestellt werden kann, werden Informationen über die API ausgegeben:
$ invafetch info version -s 192.168.X.Y -p "MYPASSWORD" hostname: _Inverter Hostname_ sw_version: 01.23.07734 api_version: 0.2.0 name: PUCK RESTful API
Diese Angaben entsprechen einem Request auf den Wechselrichter mit der URL http://192.168.X.Y/api/v1/info/version . Zwar ist dieser Request auch ohne Authentifizierung möglich, invafetch nutzt jedoch standardmäßig den Zugang als Anlagenbesitzer, der eine Authentifizierung benötigt. Fehlt der Password-Parameter, wird dies mit einer Fehlermeldung quittiert:
~$ invafetch info version -s 192.168.X.Y password parameter / INV_PASSWORD variable missing. Please use --password options or add INV_PASSWORD to the config file or to ENV variables
Alle Flags können entweder als CLI-Parameter, in einem Config-File oder als Environment-Variable übergeben werden. Dabei gilt, dass die CLI-Parameter die höchste Priorität besitzen, gefolgt von den Environment-Variablen, gefolgt von den Angaben im Config-File. Fehlen benötigte Parameter vollständig, wird eine entsprechende Fehlermeldung ausgegeben.
Der Prozess zur Sammlung und Speicherung der Daten wird mit dem Kommando „start“ gestartet. Dabei muss sich die Datei processdata.json im aktuellen Verzeichnis befinden.
$ invafetch start Alloc = 0 MiB TotalAlloc = 0 MiB Sys = 8 MiB NumGC = 0 [...]
In der aktuellen Version werden einige Parameter zum Speicherverbrauch und zum aktuellen Zustand ausgegeben, dies wird in zukünftigen Versionen unter Umständen entfallen oder als Option angeboten. Nach dem Start sollten neue Inhalte in der solardata-Tabelle vorzufinden sein. Es sei noch einmal erwähnt, dass die Nutzung mittels Docker empfohlen wird. Beim Autor läuft die Kombination aus invafetch und invaps in einer Docker-Umgebung seit mehreren Monaten stabil.
Lizenz
Invafetch ist Open Source Software und steht unter der MIT Lizenz. Die vollständigen Lizenzbedingungen befinden sich in der Datei LICENSE im invafetch-Repository.
