diff --git a/referenz/forecast-collector/index.md b/referenz/forecast-collector/index.md index e440d0b..29d3873 100644 --- a/referenz/forecast-collector/index.md +++ b/referenz/forecast-collector/index.md @@ -5,5 +5,54 @@ parent: Referenz nav_order: 5 --- -Quelltext im GitHub-Repository: \ +# Forecast-Collector + +Der **Forecast-Collector** ermittelt den erwarteten Photovoltaik-Ertrag einer PV-Anlage über die Anbieter [forecast.solar](https:/forecast.solar) oder [solcast.com](https://solcast.com) und schreibt diesen in die InfluxDB. + +Die Ermittlung des Ertrags erfolgt auf Basis von Wetterdaten und der Anlagenkonfiguration. Folgende Parameter sind erforderlich: + +- Standort der Anlage (Längen- und Breitengrad) +- Anzahl, Ausrichtung, Neigung und maximale Leistung (in kWp) der Dachflächen + +Die beiden Anbieter arbeiten mit unterschiedlichen Modellen zur Prognose des Ertrags, die sich in der Genauigkeit der Vorhersage unterscheiden. + +Zur Nutzung ist bei `solcast.com` eine (kostenfreie) Registrierung erforderlich, die Daten der Anlagen werden dann dort hinterlegt. Bei `forecast.solar` ist keine Registrierung erforderlich, die Daten werden direkt im Collector konfiguriert. Beide Anbieter bieten auch eine kostenpflichtige Variante an. + +## Ermittelte Werte + +Der Collector schreibt die folgenden Werte als _Field_ in das angegebene _Measurement_ der InfluxDB: + +- `watt`: Erwarteter Ertrag, in Watt + +## Protokollierung + +Der Collector schreibt ein Protokoll ins Docker-Log, das im Normalfall so aussieht: + +```plaintext +Forecast collector for SOLECTRUS, Version 0.5.3, built at 2024-08-30T23:27:59.224Z +https://github.com/solectrus/forecast-collector +Copyright (c) 2020-2024 Georg Ledermann, released under the MIT License + +Using Ruby 3.3.5 on platform x86_64-linux-musl +Pulling from api.solcast.com.au every 1800 seconds +Pushing to InfluxDB at http://influxdb:8086, bucket SENEC, measurement Forecast + +#1 Fetching forecast at 2024-10-02T06:53:49+02:00 + 0: https://api.solcast.com.au/rooftop_sites/1234-4567-89012-3456/forecasts?format=json&api_key=xxxx ... OK + Pushing forecast to InfluxDB ... OK + Sleeping for 1800 seconds (until 2024-10-02 07:23:51 +0200) ... +... +``` + +Das Protokoll kann über folgenden Befehl abgerufen werden: + +```bash +docker logs [container-name] +``` + +Bei Problemen oder Fehlern (z.B. wenn der Anbieter erreichbar ist oder der API-Key nicht akzeptiert wird) wird dies ebenfalls protokolliert. Es empfiehlt sich daher, im Zweifelsfall zuerst das Protokoll zu prüfen. + +## Quelltext + +Der Forecast-Collector ist in Ruby implementiert, der Quelltext ist auf GitHub verfügbar: \ [github.com/solectrus/forecast-collector](https://github.com/solectrus/forecast-collector) diff --git a/referenz/forecast-collector/konfiguration.md b/referenz/forecast-collector/konfiguration.md index aef8d9a..55cd2d3 100644 --- a/referenz/forecast-collector/konfiguration.md +++ b/referenz/forecast-collector/konfiguration.md @@ -4,4 +4,267 @@ layout: page parent: Forecast-Collector --- -todo +# Konfigurieren des Forecast-Collectors + +Der Forecast-Collector wird üblicherweise in die Gesamtkonfiguration von SOLECTRUS integriert, d.h. die bestehenden Dateien `compose.yaml` und `.env` sind zu erweitern. + +## compose.yaml + +```yaml +services: + forecast-collector: + image: ghcr.io/solectrus/forecast-collector:latest + environment: + - TZ + - FORECAST_PROVIDER + - FORECAST_LATITUDE + - FORECAST_LONGITUDE + - FORECAST_DECLINATION + - FORECAST_AZIMUTH + - FORECAST_KWP + - FORECAST_DAMPING_MORNING + - FORECAST_DAMPING_EVENING + - FORECAST_HORIZON + - FORECAST_INVERTER + - FORECAST_CONFIGURATIONS + - FORECAST_0_DECLINATION + - FORECAST_0_AZIMUTH + - FORECAST_0_KWP + - FORECAST_1_DECLINATION + - FORECAST_1_AZIMUTH + - FORECAST_1_KWP + - FORECAST_2_DECLINATION + - FORECAST_2_AZIMUTH + - FORECAST_2_KWP + - FORECAST_3_DECLINATION + - FORECAST_3_AZIMUTH + - FORECAST_3_KWP + - FORECAST_INTERVAL + - FORECAST_SOLAR_APIKEY + - SOLCAST_APIKEY + - SOLCAST_SITE + - SOLCAST_0_SITE + - SOLCAST_1_SITE + - INFLUX_HOST + - INFLUX_PORT + - INFLUX_SCHEMA + - INFLUX_TOKEN=${INFLUX_TOKEN_WRITE} + - INFLUX_ORG + - INFLUX_BUCKET + - INFLUX_MEASUREMENT=${FORECAST_INFLUX_MEASUREMENT} + restart: unless-stopped + logging: + options: + max-size: 10m + max-file: '3' + depends_on: + influxdb: + condition: service_healthy + links: + - influxdb + labels: + - com.centurylinklabs.watchtower.scope=solectrus + + influxdb: + # ... + + watchtower: + # ... +``` + +{:.note} + +Die beiden Variablen `INFLUX_TOKEN` und `INFLUX_MEASUREMENT` werden anders lautenden Umgebungsvariablen entnommen. Dies ermöglicht eine Nutzung von Variablen für verschiedene Container und vermeidet Redundanzen. + +## Umgebungsvariablen + +### `FORECAST_PROVIDER` + +Anbieter für die Ertragsprognose. + +Mögliche Werte: `forecast.solar`, `solcast` + +### `FORECAST_LATITUDE` + +Breitengrad des Standorts der PV-Anlage + +-90 (Süd) ... 90 (Nord) + +### `FORECAST_LONGITUDE` + +Längengrad des Standorts der PV-Anlage + +-180 (West) ... 180 (Ost) + +### `FORECAST_DECLINATION` + +Dachneigung in Grad + +0 (horizontal) ... 90 (vertikal) + +### `FORECAST_AZIMUTH` + +Ausrichtung des Dachs in Grad + +- -180 = Nord +- -90 = Ost +- 0 = Süd +- 90 = West +- 180 = Nord + +### `FORECAST_KWP` + +Maximale Leistung der PV-Anlage in kWp + +### `FORECAST_CONFIGURATIONS` + +Falls mehrere Dachflächen konfiguriert sind, kann hier die Anzahl hier angegeben werden. Anschließend müssen die folgenden Variablen für jede Dachfläche angegeben werden. + +### `FORECAST_0_DECLINATION` + +Erstes Dach: Dachneigung in Grad + +### `FORECAST_0_AZIMUTH` + +Erste Dach: Ausrichtung des Dachs in Grad + +### `FORECAST_0_KWP` + +Erstes Dach: Maximale Leistung der Module in kWp + +### `FORECAST_1_DECLINATION` + +Zweites Dach: Dachneigung in Grad + +### `FORECAST_1_AZIMUTH` + +Zweites Dach: Ausrichtung des Dachs in Grad + +### `FORECAST_1_KWP` + +Zweites Dach: Maximale Leistung der Module in kWp + +### `FORECAST_2_DECLINATION` + +Drittes Dach: Dachneigung in Grad + +### `FORECAST_2_AZIMUTH` + +Drittes Dach: Ausrichtung des Dachs in Grad + +### `FORECAST_2_KWP` + +Drittes Dach: Maximale Leistung der Module in kWp + +### `FORECAST_3_DECLINATION` + +Viertes Dach: Dachneigung in Grad + +### `FORECAST_3_AZIMUTH` + +Viertes Dach: Ausrichtung des Dachs in Grad + +### `FORECAST_3_KWP` + +Viertes Dach: Maximale Leistung der Module in kWp + +### `FORECAST_INTERVAL` + +Intervall in Sekunden, in dem die Ertragsprognose abgerufen wird. Hierbei ist zu beachten, dass die Anbieter unterschiedliche Limits erfordern. + +### `FORECAST_SOLAR_APIKEY` + +Optionaler API-Key für den Zugriff auf die kostenpflichtigen Variante von `forecast.solar`. + +### `SOLCAST_APIKEY` + +API-Key für die Nutzung von `solcast.com`. + +### `SOLCAST_SITE` + +ID des Standorts bei `solcast.com`. + +### `SOLCAST_0_SITE` + +Falls mehrere Dachflächen bei `solcast.com` konfiguriert sind, kann hier die ID der ersten Dachfläche angegeben werden. + +### `SOLCAST_1_SITE` + +Falls mehrere Dachflächen bei `solcast.com` konfiguriert sind, kann hier die ID der zweiten Dachfläche angegeben werden. + +### `INFLUX_HOST` + +Hostname des InfluxDB-Servers. Im Normalfall, wenn InfluxDB im gleichen Docker-Netzwerk läuft, ist das der Name des Containers (z.B. `influxdb`). Es kann aber auch ein externer InfluxDB-Server sein, z.B. `influxdb.example.com`. + +### `INFLUX_SCHEMA` + +Schema für die Verbindung zu InfluxDB. Bei Verwendung einer externen InfluxDB, die über TLS abgesichert ist, muss dieser Wert auf `https` gesetzt werden. + +Standardwert: `http` + +### `INFLUX_PORT` + +Port für die Verbindung zu InfluxDB. + +Optional, Standard ist `8086` + +Bei Verwendung einer externen, per TLS abgesicherten InfluxDB kann z.B. `443` eingestellt werden. + +### `INFLUX_TOKEN` + +Token für den Zugriff auf InfluxDB. Dieser Token muss in InfluxDB erstellt werden und die Berechtigung haben, Daten in den angegebenen Bucket zu **schreiben**. + +### `INFLUX_ORG` + +Organisation in InfluxDB, in der die Messwerte gespeichert werden sollen. + +### `INFLUX_BUCKET` + +Bucket in InfluxDB, in der die Messwerte gespeichert werden sollen. + +### `INFLUX_MEASUREMENT` + +Name des Measurements in InfluxDB, das die Messwerte aufnehmen soll. + +## Beispielhafte .env für forecast.solar + +```properties +FORECAST_PROVIDER=forecast.solar +FORECAST_CONFIGURATIONS=2 +FORECAST_INTERVAL=1800 +FORECAST_INFLUX_MEASUREMENT=forecast +FORECAST_LATITUDE=51.312801 +FORECAST_LONGITUDE=9.481544 +FORECAST_0_DECLINATION=27 +FORECAST_0_AZIMUTH=10 +FORECAST_0_KWP=3.9 +FORECAST_1_DECLINATION=30 +FORECAST_1_AZIMUTH=170 +FORECAST_1_KWP=5.5 + +INFLUX_HOST=influxdb +INFLUX_SCHEMA=http +INFLUX_PORT=8086 +INFLUX_TOKEN_WRITE=my-super-secret-admin-token +INFLUX_ORG=solectrus +INFLUX_BUCKET=solectrus +``` + +## Beispielhafte .env für solcast.com + +```properties +FORECAST_PROVIDER=solcast +FORECAST_CONFIGURATIONS=2 +FORECAST_INTERVAL=17280 +FORECAST_INFLUX_MEASUREMENT=forecast +SOLCAST_APIKEY=my-solcast-api-key +SOLCAST_0_SITE=1234-5678-9012-3123 +SOLCAST_1_SITE=1231-2334-3453-4534 + +INFLUX_HOST=influxdb +INFLUX_SCHEMA=http +INFLUX_PORT=8086 +INFLUX_TOKEN_WRITE=my-super-secret-admin-token +INFLUX_ORG=solectrus +INFLUX_BUCKET=solectrus +```