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. In der Konfiguration steht dann nur noch die ID dieser Site als PVNODE_SITE_ID. Die Variablen für Standort, Dachflächen und PVNODE_EXTRA_PARAMS sind damit wirkungslos.
v1 (Plane-basiert): Standort und Dachflächen stehen vollständig in den Umgebungsvariablen des Collectors. Das ist das bisherige Verhalten.

Vollständiges Beispiel

# Anbieter
FORECAST_PROVIDER=pvnode

# Zeitzone
TZ=Europe/Berlin

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

# Site-ID aktiviert die API v2
PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx

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

# 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

Ohne PVNODE_SITE_ID läuft der Collector über die API v1. Standort und Dachflächen kommen dann aus den Variablen weiter unten:

# 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. Verfügbar ab Version 0.10.0 des Forecast-Collectors.

Die Site trägt den Standort und alle PV-Strings. Deshalb sind mit einer Site-ID sämtliche Variablen für Standort und Dachflächen wirkungslos, ebenso PVNODE_EXTRA_PARAMS. Ohne die Variable bleibt es bei der API v1, die pvnode Ende 2026 abschaltet.

PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx

`PVNODE_PAID`

Tarif des pvnode-Kontos. 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.

Der Collector erkennt 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.

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. Der Collector bestimmt die Abrufzeitpunkte selbst, nach den Update-Zeiten von pvnode und dem Monatskontingent des Tarifs.

Im Tarif Free ist das unter der API v2 ein Abruf pro Tag. Eine einzige Abfrage genügt dort, unabhängig von der Anzahl der PV-Strings.

Unter der API v1 richtet sich der Collector 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.

Nur bei API v1

Alles Weitere auf dieser Seite gilt nur ohne PVNODE_SITE_ID, 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 keine PVNODE_SITE_ID gesetzt ist.

FORECAST_LATITUDE=50.12345

`FORECAST_LONGITUDE`

Längengrad des Standorts der PV-Anlage, -180 (West) bis 180 (Ost). Dezimaltrennzeichen ist der Punkt. Pflicht, solange keine PVNODE_SITE_ID gesetzt ist.

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