Konfiguration für pvnode

Diese Seite beschreibt die Umgebungsvariablen für den Anbieter pvnode. Der Forecast-Collector unterstützt den kostenlosen wie den kostenpflichtigen pvnode-Tarif.

Dazu kommen die allgemeinen Einstellungen, allen voran FORECAST_PROVIDER=pvnode.

Zwei API-Varianten

Der Forecast-Collector kann pvnode auf zwei Arten ansprechen:

v2 (Site-basiert): Standort und PV-Strings liegen als Site in der pvnode-Web-App. Sie wird dort einmalig von Hand angelegt, der Collector kann das nicht übernehmen. Die Variablen für Standort, Dachflächen und PVNODE_EXTRA_PARAMS sind damit wirkungslos, ebenso PVNODE_PAID.
v1 (Plane-basiert): Standort und Dachflächen stehen vollständig in den Umgebungsvariablen des Collectors. Das ist das bisherige Verhalten.

Welche der beiden gilt, entscheidet der Collector beim Start selbst. Er fragt dazu mit dem API-Key die Sites des Kontos ab:

Genau eine aktive Site: Der Collector nimmt sie und spricht die API v2 an. Mehr als der API-Key ist nicht zu konfigurieren.
Mehrere aktive Sites: Der Collector zählt sie im Protokoll auf und beendet sich. Welche gemeint ist, sagt ihm dann PVNODE_SITE_ID.
Keine Site: Der Collector fällt auf die API v1 zurück und meldet das als Warnung.

Auf v1 fällt er nur in diesem letzten Fall zurück. Lässt sich die Liste der Sites gar nicht abrufen, etwa weil pvnode nicht antwortet oder den API-Key ablehnt, beendet sich der Collector ebenfalls. Denn nach einem solchen Fehler weiß er nichts über das Konto, und eine Prognose aus den FORECAST_*-Variablen würde womöglich zu einer Anlage gehören, die es so nicht gibt. Docker startet den Container anschließend neu, und der Collector versucht es erneut.

Das gilt auch für ein Konto, dessen Sites alle inaktiv oder zur Löschung vorgemerkt sind: Auch dann bricht der Collector ab, statt auf v1 zurückzufallen.

Vollständiges Beispiel

# Anbieter
FORECAST_PROVIDER=pvnode

# Zeitzone
TZ=Europe/Berlin

# pvnode-Zugangsdaten
PVNODE_APIKEY=pvn_my-secret-api-key

# Optional: Site-ID, nötig bei mehreren Sites im Konto
# PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx

# Optional: Selbst gesetztes Monatslimit für Abfragen
# PVNODE_REQUEST_LIMIT=500

# InfluxDB
INFLUX_HOST=influxdb
INFLUX_SCHEMA=http
INFLUX_PORT=8086
INFLUX_TOKEN=my-super-secret-write-token
INFLUX_ORG=solectrus
INFLUX_BUCKET=solectrus
INFLUX_MEASUREMENT=Forecast

Hat das pvnode-Konto keine Site, läuft der Collector über die API v1. Standort und Dachflächen kommen dann aus den Variablen weiter unten:

# Optional: Tarif des kostenpflichtigen pvnode-Kontos
# PVNODE_PAID=nowcast

# Standort
FORECAST_LATITUDE=50.12345
FORECAST_LONGITUDE=6.12345

# Anzahl der Dachflächen
FORECAST_CONFIGURATIONS=2

# Erste Dachfläche (nach Süden)
FORECAST_0_DECLINATION=30
FORECAST_0_AZIMUTH=180
FORECAST_0_KWP=5.5

# Zweite Dachfläche (nach Westen)
FORECAST_1_DECLINATION=30
FORECAST_1_AZIMUTH=270
FORECAST_1_KWP=3.9

# Optional: Zusätzliche API-Parameter
# PVNODE_EXTRA_PARAMS=diffuse_radiation_model=perez

# Optional: Zusätzliche API-Parameter je Dachfläche
# PVNODE_0_EXTRA_PARAMS=snow_slide_coefficient=0.5
# PVNODE_1_EXTRA_PARAMS=snow_slide_coefficient=0.3

Zugangsdaten

`PVNODE_APIKEY`

API-Key des pvnode-Kontos. Er wird zuvor bei pvnode erstellt:
https://pvnode.com/settings/api-keys

Der Collector schickt ihn bei jeder Abfrage mit, unter beiden API-Varianten. Ohne gültigen Key weist pvnode die Abfrage ab, und im Dashboard bleibt die Prognosekurve leer.

PVNODE_APIKEY=pvn_my-secret-api-key

`PVNODE_SITE_ID`

ID der Site im pvnode-Konto. Ist sie gesetzt, spricht der Collector die API v2 an, ohne die Sites des Kontos abzufragen. Verfügbar ab Version 0.10.0 des Forecast-Collectors.

Nötig ist die Variable nur, wenn das Konto mehr als eine aktive Site hat. Bei einer einzelnen findet der Collector sie selbst, siehe Zwei API-Varianten.

Die Site trägt den Standort und alle PV-Strings. Deshalb sind mit einer Site sämtliche Variablen für Standort und Dachflächen wirkungslos, ebenso PVNODE_EXTRA_PARAMS und PVNODE_PAID.

PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx

`PVNODE_PAID`

Tarif des pvnode-Kontos, ausgewertet nur unter der API v1. Erlaubt sind false für den Tarif Free, true für Light und nowcast für Plus. Groß- und Kleinschreibung spielt keine Rolle, jeder andere Wert gilt als false. Standardwert ist false.

Unter v1 erkennt der Collector den Tarif nicht selbst, er richtet seinen Abrufplan nach dem eingetragenen. Steht hier ein höherer Tarif als der tatsächlich abonnierte, fragt der Collector häufiger ab, als das Konto erlaubt. Die Folge sind Fehlermeldungen oder ein vorzeitig aufgebrauchtes Monatskontingent.

Unter der API v2 ist die Variable wirkungslos, denn dort nennt pvnode dem Collector das Kontingent bei jeder Antwort. Ist sie trotzdem gesetzt, weist der Collector beim Start im Protokoll darauf hin.

PVNODE_PAID=nowcast

Die Tarife unterscheiden sich in der Reichweite der Prognose:

Free (false): Vorhersage für den morgigen Tag
Light (true): Vorhersage für sieben Tage, stündlich aktualisiert
Plus (nowcast): Vorhersage für sieben Tage, tagsüber alle 10 Minuten aktualisiert, nachts stündlich

Wie viele Anfragen pro Monat ein Tarif umfasst, legt pvnode fest: Preise und Tarife.

Abfrageintervall

Ein Abfrageintervall gibt es bei pvnode nicht zu konfigurieren. FORECAST_INTERVAL wird ignoriert, und HELIOS setzt die Variable bei pvnode gar nicht erst.

Unter der API v2 kommt der Abrufplan von pvnode: Jede Antwort nennt den nächsten sinnvollen Zeitpunkt und das verbleibende Kontingent des Abrechnungszeitraums. Der Collector hält sich daran und protokolliert beides. Den nächsten Zeitpunkt merkt er sich über einen Neustart hinweg, ein Neustart des Containers kostet also keine Abfrage. Der Merker liegt im temporären Verzeichnis des Containers und gilt je Site: Ein neuer Container, etwa nach einem Update des Images, startet ohne ihn und kostet eine Abfrage. Eine einzige Abfrage deckt dabei die gesamte Anlage ab, unabhängig von der Anzahl der PV-Strings.

Unter der API v1 bestimmt der Collector die Abrufzeitpunkte selbst, nach den Update-Zeiten des eingetragenen Tarifs und dem monatlichen Kontingent. Er richtet sich zusätzlich nach der Anzahl der Dachflächen und den zusätzlichen Parametern. Er fasst gleiche Parameter zusammen und deckt, wenn möglich, mit einer Abfrage zwei Dachflächen ab. Das Kontingent teilt sich dabei auf die Abfragen auf: Braucht eine Vorhersage zwei getrennte Abfragen, bleibt im Tarif Free nur jeder zweite Tag übrig.

`PVNODE_REQUEST_LIMIT`

Selbst gesetztes Monatslimit für die Anzahl der Abfragen, als positive ganze Zahl. Ohne die Variable rechnet der Collector mit dem vollen Kontingent, das die API meldet (v2) oder das der eingetragene Tarif hergibt (v1). Die Variable gilt für beide API-Varianten.

Nützlich ist das Limit, wenn dasselbe pvnode-Konto noch andere Anwendungen bedient, etwa evcc oder Home Assistant. Der Collector bestimmt seine Abrufzeitpunkte weiterhin selbst, legt dabei aber das kleinere Kontingent zugrunde und fragt entsprechend seltener ab. Ein Wert oberhalb des Tarifkontingents bleibt wirkungslos. Der Collector meldet ihn beim Start als Warnung im Log.

PVNODE_REQUEST_LIMIT=500

Nur bei API v1

Alles Weitere auf dieser Seite gilt nur für ein pvnode-Konto ohne Site, also für die klassische API v1. Mit einer Site liegen Standort und Dachflächen bei pvnode, der Collector holt sie dort ab.

Standort

pvnode arbeitet mit einem monatlichen Standort-Limit (Site-Limit), das vom Tarif abhängt. Einen Standort speichert pvnode automatisch, sobald eine Abfrage mit Koordinaten eintrifft.

`FORECAST_LATITUDE`

Breitengrad des Standorts der PV-Anlage, -90 (Süd) bis 90 (Nord). Dezimaltrennzeichen ist der Punkt. Pflicht, solange das pvnode-Konto keine Site hat.

FORECAST_LATITUDE=50.12345

`FORECAST_LONGITUDE`

Längengrad des Standorts der PV-Anlage, -180 (West) bis 180 (Ost). Dezimaltrennzeichen ist der Punkt. Pflicht, solange das pvnode-Konto keine Site hat.

FORECAST_LONGITUDE=6.12345

Dachflächen

Neigung, Ausrichtung und Leistung gibt es zweimal: ohne Index als globalen Wert und mit Index je Dachfläche. Der indizierte Wert gewinnt, der globale springt für jede Dachfläche ein, die keinen eigenen hat. Bei einer einzelnen Dachfläche genügen deshalb die globalen Variablen.

`FORECAST_CONFIGURATIONS`

Anzahl der Dachflächen. Standardwert ist 1. Steht hier eine zu kleine Zahl, bleiben die Angaben der übrigen Dachflächen unbeachtet — FORECAST_1_KWP etwa wirkt erst ab FORECAST_CONFIGURATIONS=2.

pvnode nimmt bis zu zwei Dachflächen pro Abfrage entgegen. Der Collector fasst sie zusammen, sofern ihre zusätzlichen Parameter übereinstimmen. Sonst kostet jede Dachfläche eine eigene Abfrage aus dem Monatskontingent.

FORECAST_CONFIGURATIONS=2

`FORECAST_DECLINATION`

Neigung des Dachs in Grad, 0 (waagerecht) bis 90 (senkrecht). Der Wert gilt für jede Dachfläche, die keine eigene FORECAST_X_DECLINATION hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

FORECAST_DECLINATION=30

`FORECAST_AZIMUTH`

Ausrichtung des Dachs in Grad, von Norden gezählt: 0 ist Nord, 90 Ost, 180 Süd, 270 West. Der Wert gilt für jede Dachfläche, die keine eigene FORECAST_X_AZIMUTH hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

Forecast.Solar zählt anders, nämlich von Süden (-180 bis 180). Wer von dort kommt, muss die Ausrichtung umrechnen: Aus 0 (Süd) wird 180. Bei Solcast wiederum spielt die Ausrichtung im Collector keine Rolle, sie steht in der Anlagenkonfiguration im Solcast-Portal.

FORECAST_AZIMUTH=207

`FORECAST_KWP`

Installierte Modulleistung in Kilowatt-Peak (kWp). Der Wert gilt für jede Dachfläche, die keine eigene FORECAST_X_KWP hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

FORECAST_KWP=9.24

`FORECAST_X_DECLINATION`

Neigung der Dachfläche X, gezählt ab 0. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert aus FORECAST_DECLINATION.

FORECAST_0_DECLINATION=27
FORECAST_1_DECLINATION=30

`FORECAST_X_AZIMUTH`

Ausrichtung der Dachfläche X, gezählt ab 0. Wertebereich wie bei FORECAST_AZIMUTH, also von Norden gezählt. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert.

FORECAST_0_AZIMUTH=180
FORECAST_1_AZIMUTH=270

`FORECAST_X_KWP`

Modulleistung der Dachfläche X in kWp, gezählt ab 0. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert aus FORECAST_KWP — beide Dachflächen bekämen dann dieselbe Leistung.

FORECAST_0_KWP=5.5
FORECAST_1_KWP=3.9

`PVNODE_EXTRA_PARAMS`

Zusätzliche Query-Parameter für die pvnode-API, im Format key1=value1&key2=value2, ohne führendes ? oder &. Der Collector hängt sie an jede Abfrage an. Welche Parameter es gibt, steht in der pvnode-Dokumentation.

Die Parameter gelten für die gesamte Abfrage, nicht für eine einzelne Dachfläche. Deshalb landen zwei Dachflächen nur dann in einer gemeinsamen Abfrage, wenn ihre Parameter übereinstimmen.

PVNODE_EXTRA_PARAMS=diffuse_radiation_model=perez&snow_slide_coefficient=0.5

`PVNODE_X_EXTRA_PARAMS`

Zusätzliche Query-Parameter für die Dachfläche X, gezählt ab 0. Sie ersetzen PVNODE_EXTRA_PARAMS für diese Dachfläche, sie ergänzen es nicht.

Nötig ist das nur, wenn sich die Dachflächen in den Parametern unterscheiden — was sie zugleich daran hindert, sich eine Abfrage zu teilen.

PVNODE_0_EXTRA_PARAMS=diffuse_radiation_model=perez
PVNODE_1_EXTRA_PARAMS=snow_slide_coefficient=0.3