Zum Hauptinhalt springen

UniFi Protect Smart-Home-Integration, kostenlos und Open Source

UniFi Protect-Integration für Gladys Assistant

UniFi-Protect-Kameras, Türklingeln, Flutlichter und Sensoren lokal: Erkennungen, Bilder, Klingeln.

Auf GitHub ansehenAlle externen Integrationen

Bringt die Kameras, Türklingeln, Flutlichter und Sensoren einer UniFi-Protect- Konsole (UDM, UCG, UNVR, Cloud Key) lokal in Gladys: Bewegung und intelligente Erkennungen (Person, Fahrzeug, Tier, Paket), Kamerabilder, Klingeln, Steuerung der Flutlichter, Tür- und Fenstersensoren, Temperatur, Luftfeuchtigkeit, Helligkeit, Wasserlecks, Batterien. Alles läuft über die offizielle Integration-API von Protect auf deiner Konsole: kein Ubiquiti-Cloud-Konto, nichts verlässt dein Netzwerk.

Ohne die Hardware entwickelt: Rückmeldungen sind willkommen. Diese Integration wurde nach der offiziellen API-Spezifikation und echten Antworten geschrieben, ohne eine Protect-Konsole zur Hand. Wenn etwas nicht wie beschrieben funktioniert, eröffne bitte ein Ticket auf github.com/guim31/gladys-unifi-protect/issues mit den Protokollen der Integration (LOG_LEVEL=debug).

Diese Integration ist nicht mit Ubiquiti verbunden. UniFi und UniFi Protect sind Marken von Ubiquiti Inc.

Was du brauchst​

  • Eine UniFi-Konsole mit UniFi Protect 6 oder neuer (die Integration-API; 7.x empfohlen): Dream Machine, Cloud Gateway, UNVR, Cloud Key Gen2+…
  • Einen API-Schlüssel, in der Konsole erstellt (siehe unten). Ein Benutzer ohne Administratorrechte in Protect bekommt womöglich einen Schlüssel, der nichts sieht.
  • Gladys 5.1 oder neuer, das die Konsole in deinem Netzwerk per HTTPS erreicht (standardmäßig Port 443).

Einrichtung​

Einen API-Schlüssel erstellen​

  1. Öffne deine UniFi-Konsole lokal im Browser (zum Beispiel https://192.168.1.1).
  2. Gehe zu Settings, Control Plane, Integrations.
  3. Erstelle einen API-Schlüssel, gib ihm einen Namen (zum Beispiel „Gladys“) und kopiere ihn: Die Konsole zeigt ihn nur einmal.

Einstellungen​

Öffne in Gladys die Integration und dann den Tab Konfiguration:

  • Adresse der Konsole: die IP-Adresse oder der Name der Konsole, mit :Port, falls nicht 443. Eine aus dem Browser kopierte URL geht auch.
  • API-Schlüssel: der gerade erstellte Schlüssel. Er geht nur an deine Konsole.
  • Selbstsigniertes Zertifikat akzeptieren: UniFi-Konsolen nutzen ein selbstsigniertes Zertifikat, vor dem ein Browser warnt. Aktiviere diese Option, um es zu akzeptieren, außer deine Konsole hat ein Zertifikat, dem dein Netzwerk vertraut. Standardmäßig ist sie aus: Ein nicht prüfbares Zertifikat zu akzeptieren, muss deine Entscheidung sein.
  • Kamerabilder: wie oft das Bild jeder zu Gladys hinzugefügten Kamera erneuert wird (standardmäßig alle 5 Minuten, oder nur bei Erkennung). Erkennungen, Klingeln und die Live-Ansicht fordern immer ein neues Bild an.
  • Sprache der Namen: die Sprache der Funktionsnamen und der Texte für die Szenen (standardmäßig Französisch). Die Namen werden beim Hinzufügen eines Geräts zu Gladys festgelegt.

Speichere: Der Status unter dem Namen der Integration wechselt auf verbunden, und die Geräte erscheinen im Tab Entdecken. Füge die gewünschten hinzu.

Aktionen der Konfiguration​

  • Verbindung testen: liest die Konsole sofort und zeigt ihre Protect-Version, wie viele Kameras, Flutlichter und Sensoren sie hat, und den SHA-256-Fingerabdruck des akzeptierten Zertifikats (vergleiche ihn mit dem, den dein Browser für die Konsole zeigt).
  • Adresse des Videostreams anzeigen: Wähle eine Kamera, und die RTSP-Adresse ihres Videostreams erscheint unter der Schaltfläche, bereit für die Integration „RTSP-Kamera“ von Gladys (siehe Live-Video).

Die Geräte​

Kameras​

Ein Gerät pro Kamera, benannt wie in Protect:

  • Bild: das Kamerabild, erneuert im gewählten Abstand, bei jeder Erkennung und jedem Klingeln, und immer wenn du es im Dashboard öffnest;
  • Online: an, solange die Kamera mit der Konsole verbunden ist;
  • Bewegung: an, solange Protect Bewegung sieht;
  • Person, Fahrzeug, Tier, Paket: an während einer intelligenten Erkennung dieser Art — nur die Arten, die deine Kamera erkennen kann. Ein Paket meldet Protect nur einmal: Die Funktion ist dann 10 Sekunden an.

Türklingeln​

Eine Türklingel ist eine Kamera mit einer Funktion mehr, Türklingel: Diese geht bei jedem Klingeln 10 Sekunden an, und Gladys zeigt, wann zuletzt geklingelt wurde. Eine Türklingel, die die Konsole nicht als solche benennt (ältere Firmware), bekommt diese Funktion beim ersten Klingeln: Klicke dann im Tab Entdecken bei ihr auf Aktualisieren.

Flutlichter​

  • Licht: Einschalten erzwingt das Licht; Ausschalten gibt es an seinen eigenen Lichtmodus zurück (Bewegung, Zeitplan…) — es kann bis zum Ende seines Timers an bleiben. Der angezeigte Zustand ist der echte Zustand des Lichts, egal was es eingeschaltet hat.
  • Bewegung: der Bewegungsmelder des Flutlichts.
  • Online.

Sensoren​

UP-Sense-Sensoren bekommen die Funktionen, die ihre Montage erlaubt:

  • Öffnung: offen oder geschlossen, für einen Sensor an einer Tür, einem Fenster oder einem Garagentor;
  • Temperatur (°C), Luftfeuchtigkeit (%), Helligkeit (Lux), Bewegung;
  • Wasserleck, für einen Sensor als Leckmelder;
  • Batterie (%);
  • Online.

Dashboard​

Das Widget UniFi Protect zeigt auf einen Blick:

  • die Kameras online (3/4) und die Erkennungen der letzten 24 Stunden;
  • die letzten Erkennungen und Klingeln, die neuesten zuerst, jeweils mit dem Bild aus diesem Moment;
  • den Zustand jeder Kamera, und die Flutlichter und Sensoren offline, falls vorhanden.

Wähle in seinen Einstellungen eine Kamera, um nur diese zu zeigen. Die Erkennungen werden im Speicher gehalten: Die Liste beginnt nach einem Neustart der Integration leer.

Szenen​

Auslöser​

  • Objekt von einer Kamera erkannt: eine intelligente Erkennung von Protect. Filter: die Kamera und was erkannt wurde (Person, Fahrzeug, Tier, Paket, Kennzeichen, Gesicht); leer gelassen passt alles. Eine Erkennung, die erst eine Person und dann ein Fahrzeug sieht, startet die Szene für jedes einmal. Die Aktionen können den Namen der Kamera und den Objekttyp nutzen (Code person oder sein Name in der Sprache der Integration). Beim Start der Szene ist das Kamerabild in Gladys schon das der Erkennung.
  • Jemand klingelt an der Tür: Eine Türklingel wurde gedrückt. Filter: die Türklingel. Die Aktionen können ihren Namen nutzen. Das Bild der Türklingel in Gladys ist schon das des Klingelns.

Die Zustände der Geräte (Bewegung, Person, Öffnung, Temperatur…) stehen auch dem üblichen Auslöser „Gerätezustand“ von Gladys zur Verfügung.

Aktionen​

  • Kamerabild aktualisieren: nimmt ein neues Bild einer Kamera für Gladys auf, damit die nächste Aktion („Kamerabild senden“ in einer Nachricht) sendet, was die Kamera jetzt sieht.
  • Nachricht auf der Türklingel anzeigen: ändert die Nachricht auf dem Bildschirm der Türklingel: bitte nicht stören, Paket vor der Tür abstellen, eigener Text (höchstens 30 Zeichen), oder löscht sie — für eine Anzahl Minuten oder bis zur nächsten Änderung (0).

Keine Aktion schärft, entschärft, stummschaltet oder stoppt die Aufnahme von irgendetwas: Die Integration-API von Protect bietet weder den Aufnahmemodus noch die Benachrichtigungen, und nichts in Gladys soll die Sicherheit des Hauses aus Versehen senken können.

Szenen-Ideen​

  • Es klingelt: Auslöser „Jemand klingelt an der Tür“, dann „Kamerabild senden“ der Türklingel auf dein Handy mit der Nachricht „Jemand an der Tür“.
  • Eine Person in der Einfahrt bei Nacht: Auslöser „Objekt von einer Kamera erkannt“ (Kamera Einfahrt, Person), eine Bedingung auf die Uhrzeit, dann das Gartenlicht 5 Minuten einschalten.
  • Ein Paket wurde geliefert: Auslöser „Objekt von einer Kamera erkannt“ (Paket), dann eine Nachricht „Ein Paket wurde geliefert“ mit dem Bild.
  • Nicht zu Hause: Wenn das Haus leer wird, „Nachricht auf der Türklingel anzeigen“ (Paket vor der Tür abstellen, Dauer 0); wenn du zurückkommst, sie löschen.
  • Wasserleck: Auslöser „Gerätezustand“ auf der Funktion Wasserleck, dann eine Warnung an alle Handys.

Live-Video​

Die Funktion Bild zeigt Standbilder. Für Live-Video nutze die Integration „RTSP-Kamera“ von Gladys:

  1. Öffne in Protect die Kameraeinstellungen, Erweitert, und aktiviere einen RTSP-Stream (hohe, mittlere oder niedrige Qualität).
  2. Starte in Gladys Adresse des Videostreams anzeigen mit dieser Kamera.
  3. Füge die Kamera in der Integration „RTSP-Kamera“ mit dieser Adresse hinzu (rtsp://<Konsole>:7447/…).

Die Adresse wirkt wie ein Passwort des Streams: Teile sie mit niemandem.

Aktualisierung und Grenzen der API​

Gladys fragt diese Geräte nie ab: Die Integration folgt der Konsole live über zwei WebSockets der Integration-API (Geräte und Ereignisse) und liest den vollständigen Zustand alle 5 Minuten neu (jede Minute, solange die Live-Verbindung unterbrochen ist). Die Werte gehen nur an Gladys, wenn sie sich ändern, und sonst alle 6 Stunden erneut.

Bilder: höchstens ein Bild alle 6 Sekunden pro Kamera (Gladys nimmt 12 pro Minute an), eine Kamera nach der anderen gelesen. Die Konsole begrenzt die API auf etwa 10 Anfragen pro Sekunde; die Integration bleibt weit darunter.

Fehlerbehebung​

  • „Die Konsole antwortet nicht“: Prüfe die Adresse, ob die Konsole an ist und ob Gladys sie erreicht (gleiches Netzwerk, Firewall).
  • „selbstsigniertes Zertifikat“: Aktiviere Selbstsigniertes Zertifikat akzeptieren.
  • „API-Schlüssel abgelehnt“: Der Schlüssel wurde gelöscht oder falsch abgeschrieben. Erstelle einen neuen und füge ihn erneut ein.
  • „Keine UniFi-Protect-Integration-API unter dieser Adresse“: Protect ist auf dieser Konsole nicht installiert oder älter als Version 6. Aktualisiere es.
  • „die Live-Ereignisse sind unterbrochen“: Die Zustände folgen weiter, jede Minute; Erkennungen und Klingeln warten auf die Rückkehr der Verbindung. Die Verbindung baut sich von selbst neu auf.
  • Kein Bild: Die Integration verkleinert Bilder bis 4K; ein progressives JPEG größer als 1080p lässt sich im Speicher des Containers nicht verkleinern. Die Protokolle sagen es einmal.
  • Eine Türklingel ohne ihre Klingelfunktion: Klingle einmal und klicke dann im Tab Entdecken bei ihr auf Aktualisieren.
  • Für mehr Details setze LOG_LEVEL=debug für die Integration und lies ihre Protokolle. Dein API-Schlüssel steht nie darin.

Grenzen​

  • Ohne Konsole entwickelt: getestet mit den Antworten der API, nicht mit echten Geräten.
  • Keine Steuerung von Aufnahme, Benachrichtigungen, Alarm, Gongs oder Sirenen: Die Integration-API stellt sie nicht sauber bereit, oder ein Fehler würde die Sicherheit des Hauses senken.
  • Akustische Erkennungen (Rauchmelderton, Glasbruch…), der Text von Kennzeichen und die Identität von Gesichtern werden nicht genutzt.
  • Die Liste der Erkennungen im Widget beginnt bei jedem Neustart leer: Die Integration-API speichert keinen Verlauf der Ereignisse.
  • Bilder werden auf höchstens 960 Pixel Breite verkleinert (Gladys erlaubt 150 KB pro Bild).

Konfigurationseinstellungen​

Diese Einstellungen fragt UniFi Protect in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Deine UniFi-KonsolesectionNeinUniFi Protect 6 oder neuer. Erstelle in der Konsole einen API-Schlüssel: Settings, Control Plane, Integrations. Alles bleibt in deinem Netzwerk.
Adresse der KonsolestringJaIP-Adresse oder Name der Konsole (UDM, UCG, UNVR, Cloud Key), mit :Port, falls nicht 443.
API-SchlüsselsecretJaDer in der Konsole erstellte Schlüssel. Er geht nur an die Konsole, nie an eine Cloud.
Selbstsigniertes Zertifikat akzeptierenbooleanNeinUniFi-Konsolen nutzen ein selbstsigniertes Zertifikat: Aktiviere dies, außer deine hat ein anerkanntes Zertifikat.
KamerabilderselectNeinWie oft das Bild jeder hinzugefügten Kamera erneuert wird. Erkennungen und Klingeln senden immer ein neues.
Sprache der NamenselectNeinSprache der Funktionsnamen und der Texte für Szenen. Die Namen werden beim Hinzufügen festgelegt.

So installierst du UniFi Protect in Gladys​

  1. Öffne in Gladys Integrationen: UniFi Protect erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-unifi-protect:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-unifi-protect.

UniFi Protect benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

UniFi Protect ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am