# Konfiguration für Forecast.Solar

> Umgebungsvariablen des Forecast-Collectors für den Anbieter Forecast.Solar – Standort, Dachflächen, Abfrageintervall und API-Key.

Diese Seite beschreibt die Umgebungsvariablen für den Anbieter [Forecast.Solar](https://forecast.solar). Standort und Dachflächen stehen hier in der Konfiguration des Collectors, nicht beim Anbieter.

Dazu kommen die [allgemeinen Einstellungen](/docs/referenz/forecast-collector/allgemeine-konfiguration/), allen voran `FORECAST_PROVIDER=forecast.solar`.

## Vollständiges Beispiel

```properties title=".env"
# Anbieter
FORECAST_PROVIDER=forecast.solar

# Zeitzone
TZ=Europe/Berlin

# Standort
FORECAST_LATITUDE=50.12345
FORECAST_LONGITUDE=6.12345

# Dachflächen
FORECAST_CONFIGURATIONS=2

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

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

# Abfrageintervall
FORECAST_INTERVAL=900

# Optional: API-Key für kostenpflichtiges Abo
# FORECAST_SOLAR_APIKEY=abc123def456

# Optional: Dämpfungsfaktoren (0 bis 1)
# FORECAST_DAMPING_MORNING=0.5
# FORECAST_DAMPING_EVENING=0.5

# Optional: Horizontprofil
# FORECAST_HORIZON=5,10,15,20,25,30

# Optional: Wechselrichter-Begrenzung in Kilowatt
# FORECAST_INVERTER=8

# 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
```

## Standort

### `FORECAST_LATITUDE`<span class="badge required"></span>

Breitengrad des Standorts der PV-Anlage, `-90` (Süd) bis `90` (Nord). Dezimaltrennzeichen ist der Punkt.

```properties title="Beispiel"
FORECAST_LATITUDE=50.12345
```

> **HELIOS**
>
>
> HELIOS fragt den Breitengrad unter _Konfiguration → Datenquellen → Forecast-Collector_ ab und setzt ihn immer.
>

### `FORECAST_LONGITUDE`<span class="badge required"></span>

Längengrad des Standorts der PV-Anlage, `-180` (West) bis `180` (Ost). Dezimaltrennzeichen ist der Punkt.

```properties title="Beispiel"
FORECAST_LONGITUDE=6.12345
```

> **HELIOS**
>
>
> HELIOS fragt den Längengrad unter _Konfiguration → Datenquellen → Forecast-Collector_ ab und setzt ihn immer.
>

## 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`<span class="badge optional"></span>

Anzahl der Dachflächen. Standardwert ist `1`.

Für jede Dachfläche fragt der Collector Forecast.Solar einzeln ab und addiert die Prognosen. Steht hier eine zu kleine Zahl, bleiben die Angaben der übrigen Dachflächen unbeachtet — `FORECAST_1_KWP` etwa wirkt erst ab `FORECAST_CONFIGURATIONS=2`.

```properties title="Beispiel"
FORECAST_CONFIGURATIONS=2
```

> **HELIOS**
>
>
> HELIOS fragt die Anzahl der Dachflächen unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, höchstens vier. Bei einer einzelnen Dachfläche lässt HELIOS die Variable weg. Der Collector selbst kennt keine Obergrenze.
>

### `FORECAST_DECLINATION`<span class="badge optional"></span>

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

```properties title="Beispiel"
FORECAST_DECLINATION=30
```

> **HELIOS**
>
>
> HELIOS fragt die Neigung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bei mehreren Dachflächen setzt HELIOS stattdessen die indizierten Varianten.
>

### `FORECAST_AZIMUTH`<span class="badge optional"></span>

Ausrichtung des Dachs in Grad, von Süden gezählt: `-180` ist Nord, `-90` Ost, `0` Süd, `90` West, `180` wieder Nord. Der Wert gilt für jede Dachfläche, die keine eigene [`FORECAST_X_AZIMUTH`](#forecast_x_azimuth) hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

pvnode zählt anders, nämlich von Norden (`0` bis `360`). Wer den Anbieter wechselt, muss die Ausrichtung umrechnen.

```properties title="Beispiel"
FORECAST_AZIMUTH=10
```

> **HELIOS**
>
>
> HELIOS fragt die Ausrichtung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, in derselben Zählweise. Den Wert für pvnode hält HELIOS getrennt davon.
>

### `FORECAST_KWP`<span class="badge optional"></span>

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

```properties title="Beispiel"
FORECAST_KWP=9.24
```

> **HELIOS**
>
>
> HELIOS fragt die Leistung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bei mehreren Dachflächen setzt HELIOS stattdessen die indizierten Varianten.
>

### `FORECAST_X_DECLINATION`<span class="badge optional"></span>

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_declination).

```properties title="Beispiel"
FORECAST_0_DECLINATION=27
FORECAST_1_DECLINATION=30
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### `FORECAST_X_AZIMUTH`<span class="badge optional"></span>

Ausrichtung der Dachfläche `X`, gezählt ab `0`. Wertebereich wie bei [`FORECAST_AZIMUTH`](#forecast_azimuth), also von Süden gezählt. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert.

```properties title="Beispiel"
FORECAST_0_AZIMUTH=0
FORECAST_1_AZIMUTH=90
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### `FORECAST_X_KWP`<span class="badge optional"></span>

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`](#forecast_kwp) — beide Dachflächen bekämen dann dieselbe Leistung.

```properties title="Beispiel"
FORECAST_0_KWP=5.5
FORECAST_1_KWP=3.9
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### Weitere Variablen je Dachfläche

Auch die übrigen Angaben lassen sich je Dachfläche setzen. Fehlt eine davon, greift der globale Wert ohne Index.

| Variable                     | Entspricht                                              |
| ---------------------------- | ------------------------------------------------------- |
| `FORECAST_X_LATITUDE`        | [`FORECAST_LATITUDE`](#forecast_latitude)               |
| `FORECAST_X_LONGITUDE`       | [`FORECAST_LONGITUDE`](#forecast_longitude)             |
| `FORECAST_X_DAMPING_MORNING` | [`FORECAST_DAMPING_MORNING`](#forecast_damping_morning) |
| `FORECAST_X_DAMPING_EVENING` | [`FORECAST_DAMPING_EVENING`](#forecast_damping_evening) |
| `FORECAST_X_INVERTER`        | [`FORECAST_INVERTER`](#forecast_inverter)               |
| `FORECAST_X_HORIZON`         | [`FORECAST_HORIZON`](#forecast_horizon)                 |

Nützlich ist das etwa, wenn eine Dachfläche verschattet ist (`HORIZON`) oder an einem eigenen Wechselrichter hängt (`INVERTER`). HELIOS setzt diese Variablen nicht, sie müssen von Hand eingetragen werden.

## Abfrageintervall

### `FORECAST_INTERVAL`<span class="badge required"></span>

Abstand zwischen zwei Abfragen in Sekunden, eine positive Ganzzahl. Fehlt die Variable oder steht dort keine positive Zahl, bricht der Collector beim Start ab.

Forecast.Solar begrenzt die Abfragen: kostenlos sind es 12 pro Stunde, also frühestens alle 300 Sekunden, mit Personal-Abo 60 pro Stunde und damit alle 60 Sekunden. Der Collector fragt jede Dachfläche einzeln ab, das Limit teilt sich also auf: Bei zwei Dachflächen und kostenlosem Zugang sind mindestens 600 Sekunden nötig.

```properties title="Beispiel"
FORECAST_INTERVAL=900
```

> **HELIOS**
>
>
> HELIOS fragt das Intervall unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS `900`.
>

## Weitere Einstellungen

### `FORECAST_DAMPING_MORNING`<span class="badge optional"></span>

Dämpft die Prognose für die Morgenstunden, `0` (keine Dämpfung) bis `1`. Standardwert ist `0`. Der Collector reicht den Wert unverändert an Forecast.Solar weiter.

Nützlich, wenn die Anlage morgens verschattet ist und die Prognose regelmäßig zu hoch liegt. Was der Faktor genau bewirkt, beschreibt [Forecast.Solar](https://doc.forecast.solar/damping).

```properties title="Beispiel"
FORECAST_DAMPING_MORNING=0.5
```

> **HELIOS**
>
>
> HELIOS fragt den Faktor unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>

### `FORECAST_DAMPING_EVENING`<span class="badge optional"></span>

Dämpft die Prognose für die Abendstunden, `0` (keine Dämpfung) bis `1`. Standardwert ist `0`. Ansonsten gilt dasselbe wie für [`FORECAST_DAMPING_MORNING`](#forecast_damping_morning).

```properties title="Beispiel"
FORECAST_DAMPING_EVENING=0.5
```

> **HELIOS**
>
>
> HELIOS fragt den Faktor unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>

### `FORECAST_HORIZON`<span class="badge optional"></span>

Horizontprofil als komma-getrennte Liste von Höhenwinkeln in Grad. Die Werte verteilen sich gleichmäßig über die 360 Grad des Horizonts. Der Collector reicht sie unverändert an Forecast.Solar weiter, dessen [Dokumentation](https://doc.forecast.solar/api#horizon) das Format beschreibt.

Ohne die Variable schickt der Collector kein Profil mit. Dann gilt, was Forecast.Solar von sich aus über den Horizont annimmt.

```properties title="Beispiel"
FORECAST_HORIZON=0,0,0,0,0,0,10,20,20,20,20,20
```

> **HELIOS**
>
>
> HELIOS fragt das Horizontprofil unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>

### `FORECAST_INVERTER`<span class="badge optional"></span>

Maximale Wechselrichterleistung in **Kilowatt** (kW), so erwartet es Forecast.Solar. Ein Wechselrichter mit 8 kW Ausgangsleistung bekommt also `8`, nicht `8000`.

Forecast.Solar deckelt die Prognose bei diesem Wert. Ohne die Variable deckelt es nichts, und die Prognose kann über der Wechselrichterleistung liegen.

```properties title="Beispiel"
FORECAST_INVERTER=8
```

> **HELIOS**
>
>
> HELIOS fragt die Wechselrichterleistung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, in Kilowatt. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>

### `FORECAST_SOLAR_APIKEY`<span class="badge optional"></span>

API-Key eines kostenpflichtigen Kontos bei Forecast.Solar. Ist er gesetzt, laufen die Abfragen über das Konto und damit unter dessen höherem Limit.

Ohne die Variable nutzt der Collector den kostenlosen Zugang, der auf 12 Abfragen pro Stunde begrenzt ist.

```properties title="Beispiel"
FORECAST_SOLAR_APIKEY=abc123def456
```

> **HELIOS**
>
>
> HELIOS fragt den API-Key unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>