epaper-dashboard/plugins/NETATMO.md

Netatmo Weather Station Plugin

Zeigt die Live-Daten deiner heimischen Netatmo Wetterstation auf dem 7.3″ ACeP Dashboard: Indoor-Temperatur, CO₂, Luftfeuchte, Luftdruck, Outdoor-Werte, Wind (Stärke + Böen + Richtung mit Windrose) und Regenmengen.

Funktioniert mit jeder Netatmo-Konfiguration (Hauptmodul + beliebige Zusatzmodule). Module, die du nicht hast, werden automatisch weggelassen.

---

1. Netatmo-App registrieren

Damit das Plugin Daten abrufen darf, brauchst du eine App-Registrierung bei Netatmo. Das ist einmalig und kostenlos.

1. Gehe zu https://dev.netatmo.com/apps/ und logge dich mit deinem Netatmo-Account ein.
2. Klicke Create an App.
3. Fülle das Formular aus:
   • Name: z. B. „epaper-dashboard"
   • Description: z. B. „Wetterdaten auf meinem ePaper-Display"
   • Data Protection Officer: nicht erforderlich für eine persönliche App
4. Bei den Scopes wähle mindestens read_station aus (Standard-Scope der Weather API). Mehr brauchst du für dieses Plugin nicht.
5. Speichern. Du bekommst Client-ID und Client-Secret angezeigt — die brauchst du gleich.

Hinweis: Netatmo verwendet OAuth2 mit Password-Grant für die Weather API (kein Browser-Redirect nötig). Dein Passwort wird nur lokal für den initialen Token verwendet — es wird nie auf der Festplatte persistiert, sondern liegt nur im RAM des laufenden Dashboard-Prozesses.

---

2. Plugin konfigurieren

Option A — über die Admin-Weboberfläche (empfohlen)

http://<pi>:8080/ öffnen, in der Sidebar das Widget Netatmo auswählen und die Werte eintragen:

Feld	Wert
Client-ID	von dev.netatmo.com/apps
Client-Secret	von dev.netatmo.com/apps
Username	deine Netatmo-Login-E-Mail
Password	dein Netatmo-Passwort
Station (Filter)	leer lassen, wenn du nur eine Station hast

Speichern. Klicke Refresh Now — wenn alles passt, sollten nach ~30s die ersten Daten erscheinen.

Option B — direkt in config.json

Unter plugin_configs.netatmo eintragen (Beispiel siehe config.netatmo.example.json):

{
  "plugin_configs": {
    "netatmo": {
      "client_id":     "abc123...",
      "client_secret": "def456...",
      "username":      "du@example.com",
      "password":      "GEHEIM",
      "station_filter": "",
      "show_indoor":   true,
      "show_outdoor":  true,
      "show_wind":     true,
      "show_rain":     true,
      "show_compass":  true,
      "show_secondary": true,
      "co2_thresholds": "ok@600,warn@1000,alert@1500",
      "bar_gradient":   true,
      "temp_unit":      "C",
      "wind_unit":      "kmh"
    }
  }
}

⚠️ Secrets in config.json sind auf dem Pi persistent (lokal in /home/<user>/.hermes/projects/pi/config.json). Wenn du das vermeiden willst, nimm die Admin-UI — die legt sie genauso ab, aber du siehst die Werte nie im Klartext-Editor.

---

3. Layout zuweisen

In der Admin-UI ein Netatmo-Widget auf das Grid ziehen. Das Plugin ist responsive: dieselbe Konfiguration sieht auf jedem Slot gut aus.

Slot	Was du siehst
1×1	Große Außen-Temperatur, Mini-CO₂/Feuchte-Status
2×1	Outdoor-Temperatur + Wind-Geschwindigkeit kompakt
4×1	Indoor · Outdoor · Wind/Regen — drei Spalten
1×4	Vertikale Liste aller Module
2×2	Indoor-Card (mit CO₂-Bar) + Outdoor-Card + Wind/Regen-Bereich
4×4	Volle Ansicht mit allen Modulen, Min/Max, Windrose

Das Plugin priorisiert bei der Layout-Wahl wide/tall vor small, damit 4×1- und 1×4-Slots nicht in die Mini-Ansicht fallen.

---

4. Optionen im Detail

Option	Typ	Default	Bedeutung
client_id	secret	—	Netatmo App Client-ID
client_secret	secret	—	Netatmo App Client-Secret
username	secret	—	Netatmo Login (E-Mail)
password	secret	—	Netatmo Passwort (nur RAM)
station_filter	string	""	Substring-Filter auf Stations-/Modulname
show_indoor	bool	true	Hauptmodul + zusätzliche Indoor-Sensoren anzeigen
show_outdoor	bool	true	NAModule1 (Außen) anzeigen
show_wind	bool	true	NAModule2 (Wind) anzeigen
show_rain	bool	true	NAModule3 (Regen) anzeigen
show_compass	bool	true	Windrose in der Wind-Card zeichnen
show_secondary	bool	true	Min/Max + letzte Aktualisierung
co2_thresholds	string	ok@600,warn@1000,alert@1500	CO₂-Bar Schwellen (ppm)
bar_gradient	bool	true	Verlaufsmodus der Bar
temp_unit	select	C	C oder F
wind_unit	select	kmh	kmh oder ms

CO₂-Schwellen anpassen

co2_thresholds ist ein String im Format farbe@ppm_in_ppm. Mehrere Stufen durch Komma trennen:

• ok@600,warn@1000,alert@1500 — Netatmo-Default-Empfehlungen
• ok@800,warn@1200 — nur 2 Stufen (kompakt)
• ok@1000,warn@1500,alert@2000 — strenger (z. B. für Schlafzimmer)

Station-Filter

Wenn du mehrere Stationen hast (z. B. „Home" und „Office"), kannst du über station_filter einen Substring matchen. Erst wird der Stationsname geprüft, dann die Modulnamen. Leer = erste Station.

---

5. Fehlerdiagnose

Auth-Fehler (HTTP 401)

• Stimmen Client-ID/Secret mit dem Eintrag auf dev.netatmo.com/apps überein?
• Stimmt das Passwort (case-sensitive)?
• Wurde deine App bei Netatmo evtl. deaktiviert?

→ Plugin setzt den Token-Cache automatisch zurück, beim nächsten Render wird ein neuer Token geholt.

"Keine Station gefunden"

• Hat deine Station in den letzten 4h Daten an Netatmo geschickt? (Netatmo markiert sie sonst als offline.)
• Stimmt der station_filter? Wenn du dort z. B. „Home" eingibst, aber die Station heißt „Home Office", passt es trotzdem (Substring-Match). Leer = erste Station.

"API nicht erreichbar"

• Pi hat Internet? (ping api.netatmo.net)
• DNS? (nslookup api.netatmo.net)

Werte fehlen / sind 0

• Manche Datenpunkte sind nur in der Paid-Subscription verfügbar (z. B. Historische Daten > 1h). Aktuelle Werte sind immer frei.

---

6. Technische Details

Aspekt	Wert
API-Version	Netatmo Connect OAuth2
Endpoints	POST /oauth2/token, GET /api/getstationsdata
Token-Lebensdauer	10800s (3h), Refresh on the fly
Cache	In-Memory, kein Disk-IO pro Render
Datenquelle	Netatmo Cloud (Update alle ~10 Min)
Modul-Typen	NAMain, NAModule1..4
reachable-Feld	„true" wenn das Modul in den letzten 4h gesehen wurde

Was wird pro Refresh gemacht?

1. Prüfe Token-Cache (RAM). Wenn abgelaufen oder fehlend → hole neuen Token via Password-Grant (initial) oder Refresh-Grant.
2. GET /api/getstationsdata?get_favorites=false mit Bearer-Token.
3. Parse Antwort, filtere nach station_filter und sichtbaren Modulen.
4. Rendere je nach Slot-Größe (small / wide / tall / standard).

Bei 401 wird der Token-Cache geleert und einmal neu authentifiziert. Wenn das auch fehlschlägt → roter Error-Banner mit der genauen HTTP-Meldung.