UniFi API: Gerätestatus per PHP auf dem Raspberry Pi abfragen

Wer eine Ubiquiti Dream Machine Pro (UDM Pro) betreibt, sitzt auf einem echten Datenschatz. Die UniFi-Plattform bietet eine vollwertige API, über die sich mit wenigen Zeilen PHP live abfragen lässt, ob ein bestimmtes Gerät gerade im Heimnetz eingebucht ist oder nicht. Das ist die Basis für smarte Anwesenheitserkennung – etwa zum automatischen Schalten von Lichtern, Heizungen oder Alarmanlagen.

Dieser Artikel zeigt Schritt für Schritt, wie du auf einem Raspberry Pi ein PHP-Skript einrichtest, das per API genau diese Frage beantwortet: "Ist Gerät X gerade zuhause?"

Was du brauchst

Bevor es losgeht, eine kurze Checkliste der Voraussetzungen:

• Ubiquiti Dream Machine Pro mit aktueller Firmware (UniFi OS)
• Raspberry Pi mit installiertem Raspberry Pi OS (Lite genügt)
• Einen lokalen Admin-Nutzer in der UniFi-Konsole
• Einen erstellten API-Key in der UniFi-Konsole (unter Settings -> Control Plane -> Integrations bzw. in neueren Systemversionen unter dem eigenständigen "Integrations" Unterpunkt)
• PHP 8.x und die cURL-Erweiterung auf dem Pi
• Die MAC-Adresse des Zielgeräts (z. B. dein Smartphone)

Info: Um einen API-Key erstellen zu können, müsst ihr zunächst einen lokalen Admin-Nutzer in der UniFi-Oberfläche anlegen, danach wechselt ihr das "Integrations" Untermenü (/network/default/integrations) und klickt dort auf "Create New API Key".

PHP und cURL installierst du auf dem Pi mit einem einzigen Befehl:

sudo apt update && sudo apt install php-cli php-curl -y

Die UniFi-API: Kurzer technischer Hintergrund

Die UDM Pro bietet seit UniFi OS drei verschiedene API-Schichten. Für lokale Heimnetz-Automatisierung ist die offizielle Network Application API die beste Wahl: Sie ist vollständig dokumentiert, arbeitet mit sicherem API-Key-Login (kein Passwort im Skript) und ist direkt auf dem Gerät erreichbar.

Ein wichtiger Punkt, der viele Einsteiger anfangs stolpert: Die UDM Pro kapselt den Network-Controller hinter einem Proxy-Pfad. Klassische Pfade wie /api/s/default/stat/sta, die noch bei alten CloudKey-Installationen funktionierten, liefern auf der UDM Pro einen HTTP 404. Der korrekte Pfad auf allen UniFi-OS-Geräten lautet stattdessen:

/proxy/network/api/s/{site}/stat/sta

Der Endpunkt /stat/sta (kurz für stations) enthält ausschließlich aktuell aktiv verbundene Clients – sowohl per WLAN als auch per LAN-Kabel. Verlässt ein Gerät das Netzwerk, verschwindet es nach wenigen Minuten aus dieser Liste. Genau das nutzen wir zur Anwesenheitserkennung.

Authentifizierung: API-Key vs. Passwort-Login

Für neue Projekte sollte man ausschließlich API-Keys verwenden. Der ältere Ansatz mit Benutzername und Passwort erfordert Session-Management, CSRF-Token-Handling und bricht seit Juli 2024 bei Cloud-Accounts wegen erzwungenem MFA zuverlässig zusammen.

Mit einem lokal generierten API-Key reicht dagegen ein einzelner HTTP-Header:

X-API-KEY: dein_api_key_hier

Damit entfällt auch das Session-Handling, man vermeidet Cookie-Chaos und ist somit deutlich robuster für automatisierte Abfragen geeignet.

Das vollständige PHP-Skript

Erstelle auf deinem Raspberry Pi eine Datei namens check_device.php und füge folgenden Code ein. Die vier Variablen ganz oben sind die einzigen Stellen, die du anpassen musst.

<?php

// --- KONFIGURATION ---
$udm_url      = 'https://192.168.1.1'; // IP-Adresse deiner UDM Pro
$api_token    = 'DEIN_ERSTELLTER_API_KEY'; // Dein UniFi API-Key / Token
$target_mac   = 'aa:bb:cc:dd:ee:ff'; // Die MAC-Adresse des gesuchten Geräts (Kleinbuchstaben!)
$site_name    = 'default'; // In der Regel 'default'
// ---------------------

// MAC-Adresse zur Sicherheit in Kleinbuchstaben umwandeln
$target_mac = strtolower($target_mac);

// HTTP-Header für die Authentifizierung vorbereiten
// UniFi nutzt für API-Keys standardmäßig den "X-API-KEY" Header
$headers = [
    "X-API-KEY: $api_token",
    "Accept: application/json",
    "Content-Type: application/json"
];

// cURL-Verbindung initialisieren (Endpunkt für aktive Clients)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$udm_url/proxy/network/api/s/$site_name/stat/sta");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// WICHTIG: SSL-Verifizierung für selbstsignierte Zertifikate deaktivieren
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

// API abfragen
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    die("Fehler bei der Verbindung zur UDM Pro: " . curl_error($ch) . "n");
}

curl_close($ch);

// Prüfen, ob der Aufruf erfolgreich war (200 OK)
if ($http_code !== 200) {
    die("UniFi API lieferte den HTTP-Code $http_code. Überprüfe API-Key und IP-Adresse.n");
}

// JSON-Antwort dekodieren
$data = json_decode($response, true);

if (!isset($data['data']) || !is_array($data['data'])) {
    die("Unerwartetes Antwortformat von der API.n");
}

$device_online = false;
$device_info = null;

// Alle aktiven Clients durchlaufen
foreach ($data['data'] as $client) {
    if (isset($client['mac']) && strtolower($client['mac']) === $target_mac) {
        $device_online = true;
        $device_info = $client;
        break; // Gefunden, Schleife abbrechen
    }
}

// --- ERGEBNIS AUSGEBEN ---
if ($device_online) {
    echo "STATUS: Das Gerät ($target_mac) ist ONLINE.n";
    
    // Optional: Zusätzliche Infos anzeigen, wenn es im WLAN ist
    if (isset($device_info['is_wired']) && !$device_info['is_wired']) {
        $essid = $device_info['essid'] ?? 'Unbekannt';
        $signal = $device_info['signal'] ?? 'Unbekannt';
        echo "Verbunden mit WLAN: $essid (Signalstärke: $signal dBm)n";
    } else {
        echo "Verbunden via LAN.n";
    }
} else {
    echo "STATUS: Das Gerät ($target_mac) ist OFFLINE (nicht im Haus).n";
}

?>

Skript ausführen

Zum testen könnt ihr nun die lokale Webadresse zu der PHP-Datei in eurem Webbrowser aufrufen und überprüfen ob ihr eine entsprechende Ausgabe erhaltet.

Erscheint STATUS: Gerät ... ist ONLINE., funktioniert alles. Bei HTTP 404 ist der Proxy-Pfad falsch oder der Sitename stimmt nicht. Bei einem HTTP 401 Fehler ist hingegen der API-Key ungültig oder abgelaufen.

Automatisierung per Cron

Das Skript einmalig manuell starten ist nett, aber der eigentliche Nutzen entsteht oftmals erst durch regelmäßige automatisierte Abfragen. Mit Cron kannst du das Ergebnis z. B. alle 2 Minuten in eine Datei schreiben, die dann wiederum andere Skripte auslesen:

crontab -e

Eintrag hinzufügen:

*/2 * * * * /usr/bin/php /home/pi/check_device.php > /tmp/device_status.txt 2>&1

Andere Skripte (etwa ein Bash- oder Python-Automatisierungsskript) können dann /tmp/device_status.txt prüfen und entsprechend reagieren.

Wichtig: Private MAC-Adressen bei Smartphones

Moderne Smartphones (iOS ab 14, Android ab 10) nutzen per Standard sogenannte randomisierte MAC-Adressen für jedes WLAN-Netzwerk. Das bedeutet: Die MAC-Adresse deines Handys ändert sich regelmäßig – das Skript kann das Gerät allerdings dann auch nicht mehr finden.

Lösung: Für dein privates Heimnetz deaktivierst du einfach die private MAC-Adresse.

• iPhone: Einstellungen -> WLAN -> Netzwerkname -> Private WLAN-Adresse -> deaktivieren
• Android: Einstellungen -> WLAN -> Netzwerkname -> MAC-Adresse -> Geräte-MAC verwenden

Alternativ kannst du in der UniFi-Konsole unter Client-Einstellungen die bekannte MAC fest einem Geräteprofil zuordnen.

Mögliche Erweiterungen

Ist die Grundlage einmal stabil, eröffnen sich viele Möglichkeiten:

• Mehrere Geräte überwachen: Schleife über ein PHP-Array mit mehreren MAC-Adressen
• Webhook bei Statuswechsel: Vorherigen Status in einer Datei speichern, bei Änderung eine HTTP-Anfrage an Home Assistant, Telegram-Bot o.ä. senden
• Offiziellen Integration API-Endpunkt nutzen: Unter /integration/v1/sites/{id}/clients bietet Ubiquiti einen neueren, offiziell dokumentierten Endpunkt mit Authorization: Bearer-Header – zukunftssicherer, aber erfordert eine Site-UUID-Auflösung als Vorschritt
• Cronjob durch systemd-Timer ersetzen: Präzisere Steuerung und besseres Logging

Schreibt uns auch gerne in den Kommentarbereich für welchen Zweck ihr die Gerätepräsenz-Erkennung im Zusammenspiel mit der UniFi-API und eurem Smart-Home-Server nutzt.