Repository files navigation

This repository contains the documentation and all files necessary to build a Grafana dashboard forKostal Plenticore inverters using the toolsinvafetch andinvaps running in a Docker environment.

This description is not affiliated with Kostal and is no offical product of KOSTAL Solar Electric GmbH or any subsidiary company of Kostal Gruppe.

A running Docker installation on a Linux system is required. In addition,Prometheus andGrafana should already be installed and set up. If not, examples of Docker compose files for Prometheus and Grafana can be found below. However, a detailed explanation is omitted.

To get started, the repository must first be downloaded and some parameters adjusted. All steps are commented and illustrated in the example below.

git clone https://github.com/geschke/grkopv-dashboardcd grkopv-dashboard

The downloaded directory contains the following content:

• Solar_Inverter_Dashboard-XXXXXXXXXXXX.json: Definition file of the Grafana dashboard. This file can be imported straight into Grafana under "Dashboards" -> "Import". Afterwards, it is available in Grafana under the name "Solar Inverter Dashboard".

• kopv-dashboard.yml: Docker compose file example for the invafetch and invaps components and the MariaDB database. This file needs to be modified, seeDocker-Compose-File for more information.

• invafetch/: This directory contains the fileprocessdata.json, which is needed to start invafetch. It contains the definitions of the modules and their processdata IDs, which invafetch should fetch and save from the Kostal inverter. By default all processdata values are saved, except for the modulesscb:export andscb:update. If not all values are to be read and saved, individual processdata IDs, but also complete module IDs can be removed from theprocessdata.json file.

• sql/: This contains the definition of thesolardata table, which is necessary for operation. On the first invocation ofdocker compose up, MariaDB creates the database which is defined in the Docker compose file. Furthermore, the contents of this directory are imported due to its mount directive. No adjustment is necessary for thesolardata.sql file.

The following Docker compose file defines the services for collecting and storing the inverter's processdata values and providing the metrics to Prometheus.

version:'3.7'services:mariadb:image:mariadb:10.8restart:alwaysvolumes:      -./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:latestrestart:alwaysvolumes:      -./invafetch/processdata.json:/app/processdata.jsonenvironment: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:1invaps:image:ghcr.io/geschke/invaps:latestrestart:alwaysenvironment:DBHOST:"mariadb"DBUSER:"solardbuser"DBNAME:"solardb"DBPASSWORD:"<DATABASE PASSWORD>"#DBPORT: 3307PORT:"8080"GIN_MODE:"release"ports:      -"8090:8080"

For the configuration, the adjustment of some environment variables within the individual services is necessary. The variables for which placeholders (in capital letters) are used in the example file must be modified. Modification is optional for all other environment variables.

The officialDocker image of MariaDB is used for the database service named "mariadb". All data to be stored persistently is located in the./mariadb_solar/data directory. Mapping the./sql directory to/docker-entrypoint-initdb.d ensures that the solardata table, if not already present, is created when MariaDB starts for the first time.

MARIADB_ROOT_PASSWORD is used to set the password for the MariaDB superuser account named "root". In practice, the use of this account is hardly needed, but it is still recommended to choose a sufficiently secure password.

The entries underMARIADB_DATABASE andMARIADB_USER can be taken from the example, in which case the database name "solardb" and the database user "solardbuser" are selected. If these specifications should be changed, a change is likewise necessary with the following services invafetch and invaps. In most cases a change is not necessary, because the MariaDB instance used is a stand-alone service exclusively for the use of the tools described here. Likewise, no access from outside is required, so the MariaDB port is not shared externally, i.e., no "ports:" option is necessary.

In the variableMARIADB_PASSWORD the password for the userMARIADB_USER is defined. When MariaDB is started for the first time, the databaseMARIADB_DATABASE and the userMARIADB_USER are thus created with the passwordMARIADB_PASSWORD, whereby the user receives the appropriate rights (GRANT ALL) for the database MARIADB_DATABASE.

The invafetch tool reads the processdata values at regular intervals from the Inverter API and stores the results in JSON format in a MariaDB table. More information can be found in theinvafetch GitHub repository.

First, theprocessdata.json file is mapped into the container so that it is available to invafetch at startup. Further configuration takes place using environment variables.

InDBHOST the hostname is configured. This can be a full hostname (FQDN), but here it is sufficient to specify the service name ("mariadb"), since Docker provides this to the containers in the service-internal network as hostname.

The environment variablesDBUSER,DBNAME andDBPASSWORD contain the corresponding information from the MariaDB configuration.DBUSER corresponds to the user name fromMARIADB_USER,DBNAME to the database fromMARIADB_DATABASE, andDBPASSWORD to the password defined inMARIADB_PASSWORD.

The specification ofDBPORT is not necessary, since here the default port 3306 is selected. Again, access is only in the Docker service internal network.

In the variablesINV_SERVER,INV_PASSWORD andINV_SCHEME the access to the inverter is configured. It is not necessary to specify the user, since the fixed username of the plant owner is automatically used.

UnderINV_SERVER the host name or the IP address of the inverter (without "http://" or "https://") is entered (example: "192.168.0.100"). The inverter must be on the same network or accessible to the server running Docker services.

The password of the system operator must be entered inINV_PASSWORD. This can be changed in the web UI of the inverter.

TheINV_SCHEME specification is optional and can only contain the values "http" or "https", with unencrypted access via http being used as the default.

InTIME_REQUEST_DURATION_SECONDS the time span between two requests to the inverter is defined. Invafetch thus fetches the process data values from the inverter at intervals ofTIME_REQUEST_DURATION_SECONDS seconds and stores them in the MariaDB database. The default setting ofTIME_REQUEST_DURATION_SECONDS is three (3) seconds. The lower the time span, the more accurate the later evaluation can be. The value of three seconds has proven itself in practice, but a too low or too high value is not recommended, because on the one hand the components should not be overloaded, on the other hand a too high resolution leads to less accurate metrics.

The variableTIME_NEW_LOGIN_MINUTES specifies after how many minutes a new session should be established towards the inverter and the database. The default value here is ten (10) minutes. Since invafetch is based on the (undocumented) REST API of the Kostal inverter, it is hardly possible to make a recommendation here. In practice, the specification of ten minutes has proven to be stable and functional.

The invaps tool reads the inverter's processdata values from the MariaDB database and makes them available in a format suitable for Prometheus. More information about invaps can be found in theinvaps GitHub repository.

For the database configuration variables, the same notes apply as for invafetch. These specifications can simply be taken over.

By means ofPORT it is specified under which port the server is made available for the metrics of invaps. The specification is optional, by default the port8080 is set. Since invaps is started as a Docker container, the port must be shared externally with the "ports:" definition, and a different port can also be selected that differs from the internal port. In the example, the external port8090 is mapped to the internal port8080 so that the inverter metrics are made available at the URLhttp://[server][:8090]/metrics.

Invaps relies on theGin HTTP web framework. Gin uses theGIN_MODE environment variable to set up debug mode, which contains additional output not required for operation. IfGIN_MODE is not set, debug mode is enabled; for operation and to disable debug mode, setGIN_MODE=release.

Services are started usingdocker compose for newer Docker versions or the standalone binarydocker-compose when using older variants:

docker compose -f kopv-dashboard.yml up -d

To terminate all services,docker compose (ordocker-compose) is also used:

docker compose -f kopv-dashboard.yml down

The following Docker compose file shows an example of one way to get Prometheus running using Docker:

version:'3.2'services:prometheus:image:prom/prometheus:latestcontainer_name:prometheusports:      -9090:9090command:      ---config.file=/etc/prometheus/prometheus.ymlvolumes:      -./prometheus.yml:/etc/prometheus/prometheus.yml:ro      -./data:/prometheus

Prometheus is then available under port9090 on the corresponding server.

The configuration of Prometheus is mapped in the fileprometheus.yml, the following excerpt shows this for the job called "solardata", where the server is queried every 20 seconds, which returns the metrics of the inverter:

scrape_configs:[...]  -job_name:solardatascrape_interval:20sstatic_configs:    -targets:      -metrics.example.com:8090[...]

Prometheus provides a web UI that can be used, among other things, to query the status of the jobs defined in this way. Under "Status" -> "Targets" you can find a list of the so-called endpoints that the Prometheus server queries. The current status, the labels, the time of the last query and its duration are also displayed.For further information please refer to thePrometheus documentation.

Grafana can also be run as a Docker container, below is a corresponding Docker compose file for it:

version:'3.8'services:grafana:image:grafana/grafana-oss:latestcontainer_name:monitoring_grafanarestart:unless-stoppedvolumes:      -./data:/var/lib/grafanauser:"1000"environment:      -GF_SERVER_DOMAIN=example.comports:      -"3000:3000"

Grafana is started on port 3000, which is shared with the outside world. Further information about the installation using Docker can be found in theGrafana documentation.

This repository as well as the tools invafetch and invaps are licensed under the MIT License. You can read the full terms here:LICENSE.