Das grkopf-Dashboard-Repository beinhaltet die Dokumentation sowie alle Dateien, die zum Aufbau eines Grafana-Dashboards für Kostal Plenticore Wechselrichter mit Hilfe der Tools invafetch und invaps unter Nutzung der Docker-Images notwendig sind.
Diese Beschreibung 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.
Voraussetzungen
Eine lauffähige Docker-Installation auf einem Linux-System wird vorausgesetzt. Daneben sollten Prometheus und Grafana bereits installiert und eingerichtet sein. Falls nicht, finden sich weiter unten Beispiele für Docker-Compose-Files für Prometheus und Grafana, auf eine ausführliche Erläuterung wird jedoch verzichtet.
Übersicht und erste Schritte
Für den Start müssen zunächst das Repository heruntergeladen und einige Parameter angepasst werden. Alle Schritte werden im Folgenden kommentiert und im Beispiel dargestellt.
$ git clone https://github.com/geschke/grkopv-dashboard
$ cd grkopv-dashboard
Im heruntergeladenen Verzeichnis befinden sich folgende Inhalte:
- *
Solar_Inverter_Dashboard-XXXXXXXXXXXX.json*: Definitionsdatei des Grafana-Dashboards. Diese Datei kann einfach in Grafana unter “Dashboards” -> “Import” importiert werden. Danach steht es in Grafana unter dem Namen “Solar Inverter Dashboard” zur Verfügung. - *
kopv-dashboard.yml*: Docker-Compose-File für die Komponenten invafetch und invaps sowie die MariaDB-Datenbank. Diese Datei muss angepasst werden, mehr dazu siehe unten. - *
invafetch/*: In diesem Verzeichnis befindet sich die Dateiprocessdata.json, die zum Start von invafetch benötigt wird. Darin enthalten sind die Definitionen der Module und deren Processdata-IDs, die invafetch vom Kostal-Wechselrichter abholen und speichern soll. Per Default werden alle Processdata-Werte gesichert, abgsehen von den Modulenscb:exportundscb:update. Falls nicht alle Werte ausgelesen und gespeichert werden sollen, können einzelne Processdata-IDs, aber auch vollständige Modul-IDs aus der Dateiprocessdata.jsonentfernt werden. - *
sql/*: Darin befindet sich die Definition der Tabellesolardata, die für den Betrieb notwendig ist. Beim ersten Start mittelsdocker composelegt MariaDB die im Docker-Compose-File definierte Datenbank an und importiert die Inhalte dieses Verzeichnisses. Innerhalb der Dateisolardata.sqlist keine Anpassung notwendig.
Docker-Compose-File
Das folgende Docker-Compose-File definiert die Services zur Sammlung und Speicherung der Processdata-Werte des Inverters sowie der Bereitstellung der Metriken für Prometheus.
version: '3.7' services: mariadb: image: mariadb:10.8 restart: always volumes: - ./mariadb_solar/data:/var/lib/mysql - ./sql:/docker-entrypoint-initdb.d #ports: # - "3307:3306" environment: MARIADB_ROOT_PASSWORD: "<ROOT PASSWORD>" MARIADB_DATABASE: "solardb" MARIADB_USER: "solardbuser" MARIADB_PASSWORD: "<DATABASE PASSWORD>" invafetch: image: ghcr.io/geschke/invafetch:latest restart: always volumes: - ./invafetch/processdata.json:/app/processdata.json environment: DBHOST: "mariadb" DBUSER: "solardbuser" DBNAME: "solardb" DBPASSWORD: "<DATABASE PASSWORD>" #DBPORT:"3307" INV_SERVER: "<INVERTER IP ADDRESS>" INV_PASSWORD: "<INVERTER PASSWORD>" #INV_SCHEME: "http" #TIME_REQUEST_DURATION_SECONDS:2 #TIME_NEW_LOGIN_MINUTES:1 invaps: image: ghcr.io/geschke/invaps:latest restart: always environment: DBHOST: "mariadb" DBUSER: "solardbuser" DBNAME: "solardb" DBPASSWORD: "<DATABASE PASSWORD>" #DBPORT: 3307 PORT: "8080" GIN_MODE: "release" ports: - "8090:8080"
Konfiguration der Services
Zur Konfiguration ist die Anpassung einiger Umgebungsvariablen innerhalb der einzelnen Services notwendig. Dabei müssen die Variablen, bei denen in der Beispiel-Datei Platzhalter (in Großbuchstaben) eingesetzt sind, zwingend angepasst werden, bei allen anderen Umgebungsvariablen ist eine Anpassung optional.
MariaDB
Für den Datenbank-Service namens “mariadb” wird das offizielle Docker-Image von MariaDB genutzt. Alle persistent zu speichernden Daten liegen dabei im Verzeichnis ./mariadb_solar/data. Das Mapping des Verzeichnisses ./sql auf /docker-entrypoint-initdb.d sorgt dafür, dass die Tabelle solardata, falls noch nicht vorhanden, beim Start von MariaDB angelegt wird.
Mittels MARIADB_ROOT_PASSWORD wird das Passwort für den MariaDB-Superuser-Account mit dem Namen “root” festgelegt. In der Praxis wird die Nutzung dieses Accounts zwar kaum benötigt, aber es empfiehlt sich dennoch die Wahl eines ausreichend sicheren Passworts.
Die Angaben unter MARIADB_DATABASE und MARIADB_USER können aus dem Beispiel übernommen werden, in dem Fall werden als Datenbank-Name “solardb” und für den Datenbank-Nutzer die Bezeichnung “solardbuser” gewählt. Sollten diese Angaben geändert werden, ist ebenfalls eine Änderung bei den nachfolgenden Services invafetch und invaps notwendig. In den meisten Fällen ist eine Änderung nicht notwendig, da die verwendete MariaDB-Instanz als eigenständiger Dienst ausschließlich für die Nutzung der hier beschriebenen Tools vorgesehen ist. Ebenfalls ist kein Zugriff von außerhalb erforderlich, weshalb der MariaDB-Port nicht nach außen freigegeben wird, d.h. es ist keine Option “ports:” notwendig.
In der Variablen MARIADB_PASSWORD wird das Passwort für den User MARIADB_USER festgelegt. Beim ersten Start von MariaDB werden somit die Datenbank MARIADB_DATABASE und der User MARIADB_USER mit dem Passwort MARIADB_PASSWORD angelegt, wobei der User die entsprechenden Rechte (GRANT ALL) für die Datenbank MARIADB_DATABASE erhält.
invafetch
Das Tool 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. Weitere Informationen finden sich im invafetch-GitHub-Repository. []()
Zunächst wird die Datei processdata.json so in den Container gemappt, dass sie invafetch beim Start zur Verfügung steht. Die weitere Konfiguration findet mittels Umgebungsvariablen statt.
In DBHOST wird der Hostname konfiguriert. Dies kann ein vollständiger Hostname (FQDN) sein, hier genügt jedoch die Angabe des Service-Namens (“mariadb“), da Docker diesen den Containern im Service-internen Netzwerk als Hostnamen zur Verfügung stellt.
In die Umgebungsvariablen DBUSER, DBNAME und DBPASSWORD werden die korrespondierenden Angaben aus der MariaDB-Konfiguration eingesetzt, dabei entspricht DBUSER dem Usernamen aus MARIADB_USER, DBNAME der Datenbank aus MARIADB_DATABASE, sowie DBPASSWORD dem in MARIADB_PASSWORD definierten Passwort.
Die Angabe von DBPORT ist nicht notwendig, da hierbei der Default-Port 3306 gewählt wird. Auch hier erfolgt der Zugriff nur im Docker-Service internen Netzwerk.
In den Variablen INV_SERVER, INV_PASSWORD und INV_SCHEME wird der Zugriff auf den Wechselrichter konfiguriert. Eine Angabe des Users ist nicht notwendig, da automatisch der fest eingestellte Username des Anlagenbetreibers zum Einsatz kommt.
Unter INV_SERVER wird der Hostname oder die IP-Adresse des Wechselrichters (ohne “http://” bzw. “https://”) eingetragen (Beispiel: “192.168.0.100“) angegeben. Der Wechselrichter muss sich im selben Netzwerk befinden bzw. für den Server, auf dem die Docker-Services laufen, zugänglich sein.
In INV_PASSWORD ist das Passwort des Anlagenbetreibers einzutragen. Dieses kann in der Web-UI des Wechselrichters geändert werden.
Die Angabe INV_SCHEME ist optional und kann ausschließlich die Werte “http” oder “https” beinhalten, wobei als Default der unverschlüsselte Zugriff mittels http zum Einsatz kommt.
In TIME_REQUEST_DURATION_SECONDS wird die Zeitspanne zwischen zwei Requests auf den Wechselrichters definiert. Invafetch holt somit im Abstand von TIME_REQUEST_DURATION_SECONDS Sekunden die Processdata-Werte vom Wechselrichter und speichert diese in der MariaDB-Datenbank. Die Default-Einstellung von TIME_REQUEST_DURATION_SECONDS beträgt drei (3) Sekunden. Dabei gilt, je niedriger die Zeitspanne, desto genauer kann die spätere Auswertung gestaltet werden. Der Wert von drei Sekunden hat sich in der Praxis bewährt, ein zu niedriger oder zu hoher Wert empfiehlt sich hingegen nicht, da einerseits die Komponenten nicht überlastet werden sollen, andererseits eine zu hohe Auflösung zu weniger genauen Metriken führt.
Die Variable TIME_NEW_LOGIN_MINUTES gibt an, nach wieviel Minuten eine neue Session zum Wechselrichter und zur Datenbank hin aufgebaut werden soll. Der Standardwert liegt hier bei zehn (10) Minuten. Da invafetch auf der (undokumentierten) REST-API des Kostal-Wechselrichters basiert, ist eine Empfehlung hier kaum möglich, in der Praxis hat sich die Angabe von zehn Minuten als stabil und funktionsfähig herausgestellt.
invaps
Das Tool invaps liest die Processdata-Werte des Wechselrichters aus der MariaDB-Datenbank und stellt diese in einem für Prometheus geeigneten Format zur Verfügung. Weitere Informationen zu invaps finden sich im invaps-GitHub-Repository.
Bei den Variablen zur Datenbank-Konfiguration gelten die gleichen Hinweise wie für invafetch. Diese Angaben können einfach übernommen werden.
Mittels PORT wird angegeben, unter welchem Port der Server für die Metriken von invaps zur Verfügung gestellt werden. Die Angabe ist optional, per Default ist der Port 8080 eingestellt. Da invaps als Docker-Container gestartet wird, muss der Port mit der “ports:“-Definition nach außen hin freigegeben werden, dabei kann auch ein anderer Port gewählt werden, der sich vom internen Port unterscheidet. Im Beispiel wird der externe Port 8090 auf den internen Port 8080 gemappt, so dass die Inverter-Metriken unter der URL http://[server][:8090]/metrics zur Verfügung gestellt werden.
Invaps setzt auf dem Gin HTTP web framework auf. Gin nutzt die Umgebungsvariable GIN_MODE zur Einrichtung des Debug-Modus, der zusätzliche, für den Betrieb nicht notwendige Ausgaben enthält. Falls GIN_MODE nicht gesetzt ist, wird der Debug-Modus aktiviert, für den Betrieb und zur Deaktivierung des Debug-Modus ist GIN_MODE=release zu setzen.
Betrieb
Der Start der Services erfolgt mit docker compose bei neueren Docker-Versionen bzw. bei älteren Varianten durch das eigenständige Binary docker-compose:
$ docker compose -f kopv-dashboard.yml up -d
Zum Beenden aller Services wird ebenfalls docker compose (bzw. docker-compose) verwendet:
$ docker compose -f kopv-dashboard.yml down
Prometheus
Das folgende Docker-Compose-File zeigt beispielhaft eine Möglichkeit, Prometheus mittels Docker zum Laufen zu bringen:
version: '3.2' services: prometheus: image: prom/prometheus:latest container_name: prometheus ports: - 9090:9090 command: - --config.file=/etc/prometheus/prometheus.yml volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro - ./data:/prometheus
Prometheus steht daraufhin unter dem Port 9090 auf dem entsprechenden Server zur Verfügung.
Die Konfiguration von Prometheus wird in der Datei “prometheus.yml” abgebildet, der folgende Ausschnitt zeigt dies für den “solardata” genannten Job, bei dem im Abstand von 20 Sekunden der Server abgefragt wird, der die Metriken des Wechselrichters zurückgibt:
scrape_configs: [...] - job_name: solardata scrape_interval: 20s static_configs: - targets: - metrics.example.com:8090 [...]
Prometheus stellt eine Web-UI zur Verfügung, mit der sich unter anderem der Status der so definierten Jobs abfragen lässt. Unter “Status” -> “Targets” findet sich eine Liste der so genannten Endpoints, die der Prometheus-Server abfragt. Dabei werden auch der aktuelle Zustand, die Labels, die Zeit der letzten Abfrage und deren Dauer angegeben.
Für weitere Informationen wird an dieser Stelle auf die Dokumentation von Prometheus verwiesen.
Grafana
Grafana kann ebenfalls als Docker-Container betrieben werden, im Folgenden ein entsprechendes Docker-Compose-File dazu:
version: '3.8' services: grafana: image: grafana/grafana-oss:latest container_name: monitoring_grafana restart: unless-stopped volumes: - ./data:/var/lib/grafana user: "1000" environment: - GF_SERVER_DOMAIN=example.com ports: - "3000:3000"
Grafana wird hierbei auf dem nach außen hin freigegebenen Port 3000 gestartet, weitere Hinweise zur Installation mittels Docker sind in der Dokumentation zu Grafana zu finden.
Nach dem Import des Dashboard-Definitionsfiles und der Wahl der Datenquelle “Prometheus” sollte sich nach kurzer Zeit ein Bild ähnlich wie folgendem zeigen:
Das Dashboard kann entsprechend den eigenen Anforderungen angepasst werden, etwa falls bei kleineren Anlagen nur ein Gleichstrom-Eingang zur Verfügung steht oder ähnliches.
