Zum Hauptinhalt springen

invafetch (inverter value fetcher)

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.