# pvnode mit Home Assistant verbinden

Diese Anleitung zeigt, wie Sie die pvnode Forecast API über den eingebauten
[RESTful Sensor](https://www.home-assistant.io/integrations/rest/) in
Home Assistant einbinden — ganz ohne Custom Component.

:::note
Die nachfolgende Anleitung verwendet derzeit noch die V1 API. Wir werden diese aktualisieren, sobald die Migration auf
V2 erfolgt ist.
:::

## Voraussetzungen

- Eine laufende Home Assistant Installation
- Ein pvnode API-Key ([hier einen Key erstellen](https://pvnode.com/settings/api-keys))
- Zugriff auf `configuration.yaml` (Datei-Editor Add-on oder SSH)

## 1. API-Key sicher ablegen

Öffnen Sie `secrets.yaml` im `config/` Verzeichnis (anlegen falls nicht vorhanden):

```yaml
pvnode_api_key: "Bearer IHR_API_KEY"
```

## 2. REST-Sensor in `configuration.yaml`

Fügen Sie folgenden Block in Ihre `configuration.yaml` ein und passen Sie
Standort und PV-Konfiguration an:

```yaml
rest:
  - resource: https://api.pvnode.com/v1/forecast/
    method: GET
    headers:
      Authorization: !secret pvnode_api_key
    params:
      latitude: 48.27564
      longitude: 11.83972
      slope: 30
      orientation: 180
      pv_power_kw: 10
      forecast_days: 2                 # Anzahl Tage Vorhersage
      required_data: "pv_watts,temp"   # Leistung und Temperatur werden ausgegeben
    scan_interval: 3600                # Update alle 60 Minuten
    sensor:
      - name: "pvnode Power Now"
        unique_id: pvnode_power_now
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
        value_template: >
          {% set rounded = now().replace(second=0, microsecond=0, minute=(now().minute // 15) * 15) %}
          {% set target = rounded.astimezone(timezone('UTC')).strftime('%Y-%m-%d %H:%M:%S') %}
          {% set match = value_json.values | selectattr('dtm', 'eq', target) | list %}
          {{ match[0].pv_watts | round(0) if match else 0 }}
        json_attributes:
          - values
          - latitude
          - longitude
          - slope
          - orientation
          - elevation
```

### Parameter im Überblick

| Parameter                | Beschreibung                                                                                              |
|--------------------------|-----------------------------------------------------------------------------------------------------------|
| `latitude` / `longitude` | Standort der PV-Anlage                                                                                    |
| `slope`                  | Neigung der Module in Grad (0 = flach, 90 = vertikal)                                                     |
| `orientation`            | Ausrichtung in Grad (0 = Nord, 90 = Ost, 180 = Süd, 270 = West)                                           |
| `pv_power_kw`            | Installierte Leistung in kWp                                                                              |
| `forecast_days`          | Anzahl Tage Vorhersage (0–7)                                                                              |
| `required_data`          | Welche Felder die API zurückgeben soll - alle Datenfelder finden Sie [hier](/docs/de/guides/data-columns) |

Eine vollständige Übersicht aller Parameter und Datenfelder finden Sie in
der [Forecast API Dokumentation](/docs/api/v1-endpoints#forecast).

## 3. Konfiguration neu laden

Nach dem Speichern in Home Assistant: **Entwicklerwerkzeuge → YAML →
Alle YAML-Konfigurationen neu laden**. Bei der ersten Einrichtung ist
ein Neustart erforderlich.

Unter **Entwicklerwerkzeuge → Zustände** den Sensor `sensor.pvnode_power_now`
suchen — der Zustand zeigt die aktuelle Leistung in Watt, in den Attributen
finden Sie die komplette 15-Minuten-Vorhersage.

## 4. Vorhersage als Diagramm visualisieren

Mit der [ApexCharts Card](https://github.com/RomRider/apexcharts-card) (über
HACS installierbar) können Sie die komplette Forecast-Reihe als Kurve plotten:

```yaml
type: custom:apexcharts-card
header:
  show: true
  title: PV Forecast
graph_span: 48h
span:
  start: day
series:
  - entity: sensor.pvnode_power_now
    name: pvnode Forecast
    type: line
    stroke_width: 2
    extend_to: false
    data_generator: |
      return entity.attributes.values.map(point => {
        const utcTime = new Date(point.dtm + 'Z').getTime();
        return [utcTime, point.pv_watts];
      });
```

## Anwendungsfälle

Mit der pvnode-Vorhersage in Home Assistant können Sie zum Beispiel:

- **Wallbox steuern:** EV laden, wenn ausreichend Solarproduktion erwartet wird
- **Wärmepumpe planen:** Brauchwasser-Aufbereitung in Zeiten mit Überschuss legen
- **Batterie optimieren:** Vor erwarteten Schlechtwetterperioden voll laden
- **Lastverschiebung:** Waschmaschine, Trockner oder Spülmaschine zu Spitzenzeiten starten

## Tipps

- **Höhere Auflösung mit Nowcasting:** Mit dem Nowcasting Add-on aktualisiert
  die Vorhersage alle 10 Minuten basierend auf Live-Satellitendaten. Setzen
  Sie dann `scan_interval: 600`.
- **Mehrere Anlagen:** Für Ost/West-Aufdachungen oder mehrere Strings legen
  Sie einfach mehrere REST-Sensoren mit unterschiedlichen `unique_id` an.