Wer UniFi im Einsatz hat (UDM, USG, Cloud Key & Co.) und FHEM nutzt, kommt früher oder später auf die Idee:
Warum nicht Netzwerkzustände direkt in FHEM ziehen und dort weiterverarbeiten?

Genau das geht ziemlich gut über die UniFi Network API – man muss nur wissen, wo die Fallstricke liegen. Der größte davon: Authentifizierung und Session-Handling.

Grundprinzip

Die UniFi Network Application stellt intern eine REST-API bereit. Darüber lassen sich u. a. abrufen:

• Gateway-Status
• WAN-Traffic
• WAN-Failover
• AP-Status
• Client-Infos
• DPI / Traffic-Stats
• Port-Status

Der klassische Endpoint für Geräte:

/proxy/network/api/s/default/stat/device

Auf einer UDM z. B.:

https://<UDM-IP>/proxy/network/api/s/default/stat/device

In FHEM pollt man diesen Endpoint typischerweise per at oder InternalTimer und schreibt die Daten in Readings.

Die größte Hürde: Authentifizierung

Ohne Login geht nichts. Und genau hier wird’s interessant, weil UniFi OS nicht nur ein simples Cookie erwartet.

Was wirklich passiert

Beim Login:

POST /api/auth/login

mit JSON:

{
  "username": "user",
  "password": "pass"
}

liefert UniFi:

1. Ein Cookie (TOKEN)
2. Ein JWT-Token
3. Darin eingebettet: ein CSRF-Token

Und genau diese Kombination brauchst du später:

• Cookie: TOKEN=...
• Header: X-CSRF-Token: ...

Wenn du nur das Cookie sendest, funktioniert es oft:

• Minuten
• manchmal Stunden
• …und friert dann plötzlich ein

Du bekommst dann zwar noch HTTP 200, aber die Daten sind stale (z. B. last_seen bleibt stehen).

Darum:

Für stabile API-Abfragen brauchst du immer TOKEN + CSRF.

Wichtig: Im Unifi muss natürlich ein entsprechender User im Vorfeld angelegt werden. Sonst wird das natürlich nichts. 😉

---

Typische Auth-Abhängigkeiten / Stolperfallen

Darauf solltest du achten:

• Session-Timeout: UniFi killt Sessions nach einiger Zeit
• CSRF Pflicht: je nach Firmware zwingend
• Cookie-Rotation: TOKEN kann sich ändern
• Site-Kontext: falsche Site → scheinbar “statische” Daten
• Proxy-Pfad: /proxy/network/... bei UniFi OS nötig

Praxis-Lösung:

• Bei jedem Poll neu einloggen oder
• HTTP-Code prüfen und bei 401/403 neu einloggen
• TOKEN + CSRF sauber extrahieren

---

Beispiel: Sinnvolle Daten für FHEM

Sobald die API stabil läuft, wird’s spannend. Ein paar typische Use-Cases:

---

WAN-Status überwachen

Reading-Ideen:

• WAN_state → UP/DOWN
• WAN1_state
• WAN2_state
• WAN_active

Automationen

• Push bei Internet-Ausfall
• LED / Hue rot blinken lassen
• Sprachansage über Alexa / TTS

---

WAN-Failover in FHEM signalisieren

Gerade bei Dual-WAN extrem nützlich.

Beispiel:

• WAN1 = Glasfaser
• WAN2 = LTE Backup

Automation:

if WAN_active wechselt auf WAN2
→ Telegram Push
→ Dashboard Warnung
→ Traffic drosseln

Oder visuell:

• WLED Streifen orange
• Homematic Sirene kurz piepen
• TabletUI Icon wechseln

---

Bandbreite loggen

Readings:

• WAN_rx_mbit
• WAN_tx_mbit

Nutzen:

• Graphen in FHEM
• Traffic-Spitzen erkennen
• Backup-Traffic sehen
• Streaming / Uploads nachvollziehen

Mit Counter-Delta sogar sehr genau.

---

AP-Monitoring

API liefert:

• Online / Offline
• AP-Name
• Last Seen

FHEM kann daraus:

• Offline-Alarm
• Reboot-Reminder
• PoE-Switch Trigger

Beispiel:

Wenn AP Garage offline > 5min
→ Steckdose Switch neu starten

---

Client-Presence (optional)

Über /stat/sta:

• Geräte online
• MAC / Hostname
• WLAN / LAN

Use-Cases:

• Anwesenheit
• Gäste-Erkennung
• Alarmanlagen-Freigabe

---

FHEM Poll-Intervall – realistischer Wert

UniFi aktualisiert viele Stats nicht sekündlich.

Bewährt:

• 15–30 Sekunden → guter Kompromiss
• <10s → unnötige Last
• 60s → träge Failover-Erkennung

---

Freeze erkennen (wichtig)

Ein extrem nützliches Debug-Reading:

last_seen

Wenn das stehen bleibt:

• Controller bekommt keine Informs
• Network App hängt
• Session hängt

Dann hilft kein Code-Fix → nur Re-Login oder App-Restart.

---

Fazit

UniFi-API in FHEM ist mächtig – aber nur, wenn Auth sauber läuft.

Die drei Erfolgsfaktoren:

1. TOKEN + CSRF korrekt setzen
2. HTTP-Code überwachen
3. last_seen als Lebensindikator nutzen

Wenn das passt, bekommst du stabile Live-Netzwerkdaten ins Smarthome und kannst darauf reagieren wie auf jeden anderen Sensor auch.

Bei Interesse am fertigen Script in Form einer perl Funktion?

Kein Problem – einfach über die Kommentarfunktion melden.

Siehe auch:

• LTE Backup