UniFi Access Smart-Home-Integration, kostenlos und Open Source
UniFi-Access-Türen: Schloss, Türsensor, Klingel, erlaubte oder verweigerte Zutritte, Alarme.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Bringt die Türen von UniFi Access (die Zutrittskontrolle von Ubiquiti: Leser G2 und G3, Intercom, UA Hub, UA Hub Door Mini, UA Ultra) in dein Gladys, im lokalen Netz: den Zustand jedes Schlosses und jeder Tür, die Klingel, wer wie hereinkam, die Türalarme. Keine Verbindung zu Ubiquiti.
Ohne die Hardware entwickelt: Rückmeldungen willkommen. Die Integration wurde anhand der offiziellen API, der Home-Assistant-Integration und echter, von anderen Projekten veröffentlichter Mitschnitte geschrieben, lief aber nie auf einer echten UniFi-Access-Anlage. Sag uns auf GitHub, was funktioniert und was nicht.
Vorstellung
- Ein Gladys-Gerät pro UniFi-Access-Tür, nur lesend: Nichts auf dem Dashboard kann eine Tür öffnen.
- Echtzeit: Die Integration hält eine Verbindung zum Benachrichtigungs-WebSocket von UniFi Access offen und liest alle 5 Minuten alles neu (jede Minute, wenn der WebSocket getrennt ist).
- Szenen-Auslöser: Klingel, Zutritt erlaubt, Zutritt verweigert, Türalarm, Tür offline und wieder online.
- Szenen-Aktionen: eine Tür verriegelt halten, zu ihrem normalen Plan zurückbringen und — nur wenn du es aktivierst — eine Tür entriegeln.
- Ein Dashboard-Widget: die Türen und die letzten Zutritte.
Voraussetzungen
- UniFi Access auf einer UniFi-OS-Konsole (UDM, UCG, UNVR, Cloud Key Gen2+…), aktuell genug für die Entwickler-API (Settings, General, Advanced, API Token).
- Gladys 5.1 oder neuer, im selben Netz wie die Konsole (Port 12445 erreichbar).
- Ein API-Token: in UniFi Access Settings → General → Advanced → API Token → Create. Gib ihm die Rechte Space (Türen) und Device, lesend und schreibend, wenn du die Szenen-Aktionen willst. Kopiere es: Es wird nur einmal angezeigt.
Konfiguration
In Gladys: Integrationen → UniFi Access → Konfiguration.
| Feld | Was eintragen |
|---|---|
| Adresse der Konsole | IP-Adresse oder Name der Konsole, z. B. 192.168.1.1. Die API antwortet auf Port 12445: Gib :Port nur an, wenn er abweicht. |
| API-Token | Das oben erstellte Token. Es bleibt in Gladys und wird nie in die Protokolle geschrieben. |
| Selbstsigniertes Zertifikat akzeptieren | UniFi-Konsolen liefern auf Port 12445 ein selbstsigniertes Zertifikat: Aktiviere das, außer du hast ein vertrauenswürdiges installiert. |
| Fernentriegelung durch Szenen erlauben | Standardmäßig aus. Lies vor dem Aktivieren „Szenen-Aktionen“ weiter unten. |
| Sprache der Funktionsnamen | Namen der Funktionen beim Hinzufügen einer Tür und Texte der Zustände und Szenen-Ereignisse (standardmäßig Französisch). |
Dann Verbindung testen: Das liest die Konsole sofort und sagt, wie viele Türen und Geräte gefunden wurden und ob die Echtzeit-Benachrichtigungen verbunden sind. Die Türen erscheinen dann im Tab Entdecken: Füge die gewünschten hinzu.
Geräte
Jede Tür von UniFi Access wird zu einem Gerät, benannt wie die Tür. Alle Funktionen sind nur lesend; manche gibt es nur, wenn die Hardware sie hat.
| Funktion | Gladys-Typ | Werte |
|---|---|---|
| Schloss | Schloss / Zustand | verriegelt oder entriegelt |
| Türposition | Öffnungssensor | offen oder geschlossen — nur bei einer Tür mit angeschlossenem Positionssensor (DPS) |
| Türklingel | Klingel / Läuten | klingelt bei jedem Läuten einige Sekunden — bei einer Tür mit Leser Pro, Intercom oder Klingeleingang am Hub |
| Verriegelungsregel | Text | Normal, Immer verriegelt, Immer entriegelt, Eine Weile entriegelt bis 18:30, Entriegelungsplan… |
| Letzter Zutritt | Text | z. B. Alice Martin · NFC-Karte · Eintritt, Verweigert · Unbekannt · PIN-Code |
Das Abzeichen des Geräts zeigt, ob seine Tür online ist (ihr Hub antwortet UniFi Access), und wird orange, wenn die Echtzeit-Benachrichtigungen getrennt sind.
Eine Tür, die zum ersten Mal klingelt, ohne eine Klingel-Funktion zu haben, bekommt eine: Nutze Aktualisieren im Tab Entdecken, um sie dem Gerät hinzuzufügen.
Widget
UniFi-Access-Türen: eine Zeile pro Tür (verriegelt oder nicht, offen oder geschlossen, Alarm, offline) und die letzten Zutritte (wer, wie, erlaubt oder verweigert). Wähle in den Widget-Einstellungen eine Tür, um nur sie zu zeigen: Das Widget bietet dann zwei Tasten, die jeweils eine Bestätigung verlangen:
- Immer verriegeln: Die Tür bleibt unabhängig von ihrem Plan verriegelt (mit ✓ markiert, solange aktiv);
- Normaler Plan: beendet die vorübergehende Regel. „Immer verriegelt“ zu beenden kann die Tür entriegeln: Diese Taste erscheint dafür nur bei aktivierter Fernentriegelung.
Es gibt nie eine Entriegelungstaste.
Szenen-Auslöser
| Auslöser | Wann | Filter | Variablen |
|---|---|---|---|
| Türklingel betätigt | jemand hat an einem Leser oder einer Gegensprechanlage geklingelt | Tür | Name der Tür, Klingelgerät |
| Zutritt erlaubt | eine Tür wurde per Karte, Code, Gesicht, App… geöffnet | Tür, Methode, Person | Name der Tür, Name der Person, Methode (nfc, pin, face…), Methode ausgeschrieben, Richtung (entry, exit) |
| Zutritt verweigert | eine Karte, ein Code oder ein Gesicht wurde abgelehnt | Tür, Methode | dieselben |
| Türalarm | Tür aufgebrochen oder zu lange offen | Tür, Alarm | Name der Tür, Alarm (forced_open, held_open, other), Alarm ausgeschrieben, von UniFi Access gesendeter Typ |
| Tür offline | der Hub einer Tür antwortet nicht mehr | Tür | Name der Tür |
| Tür wieder online | der Hub einer Tür antwortet wieder | Tür | Name der Tür, Minuten offline |
UniFi Access meldet jeden Zutritt zweimal (ein „Insight“ und eine Protokollzeile, wenige Millisekunden auseinander): Die Integration löst nur einmal aus.
Szenen-Aktionen
| Aktion | Wirkung |
|---|---|
| Eine Tür verriegelt halten | Die Tür bleibt unabhängig von ihrem Plan verriegelt. Immer erlaubt. |
| Tür zum normalen Plan zurückbringen | Beendet „immer verriegelt“ oder „immer entriegelt“. „Immer verriegelt“ zu beenden erfordert die aktivierte Fernentriegelung. |
| Eine Tür entriegeln | Eine Fernentriegelung; die Tür verriegelt nach ihrer üblichen Zeit von selbst. Abgelehnt, solange die Fernentriegelung aus ist. |
Achtung — Fernentriegelung. Standardmäßig ist die Fernentriegelung aus. Einmal aktiviert, öffnet jede Szene mit „Eine Tür entriegeln“ die Tür, wenn sie läuft: ein falscher Auslöser, ein geteiltes Dashboard, ein kompromittiertes Gladys-Konto bedeuten dann eine offene Tür. Es gibt sie nie als Schalter, Sprachbefehl oder Dashboard-Taste. Jede Entriegelung erscheint als „Gladys“ im Systemprotokoll von UniFi Access.
Beispielszenen
- Jemand an der Tür: Auslöser „Türklingel betätigt“ an der Haustür → Nachricht „Es klingelt an {{triggerEvent.data.door_name}}“ senden und die Kamera am Eingang zeigen.
- Die Kinder sind zu Hause: Auslöser „Zutritt erlaubt“ mit Person „Léa“ → „Léa ist zu Hause ({{triggerEvent.data.method_label}})“ senden.
- Das Haus verlassen: wenn die Alarmanlage scharf ist → „Eine Tür verriegelt halten“ für jede Tür.
- Einbruch: Auslöser „Türalarm“ mit Alarm „Tür aufgebrochen“ → Sirene und Benachrichtigung.
- Abgelehnte Karte: Auslöser „Zutritt verweigert“ → Benachrichtigung mit {{triggerEvent.data.door_name}} und {{triggerEvent.data.method_label}}.
Aktualisierung und Grenzen der API
- Echtzeit über den Benachrichtigungs-WebSocket von UniFi Access (eine ausgehende Verbindung des Containers zu Port 12445), nach einem Abbruch nach 1 s, 2 s, 4 s… bis 1 Minute neu geöffnet.
- Ein vollständiges Lesen (Türen, Geräte, eine Verriegelungsregel pro Tür) alle 5 Minuten, jede Minute, solange der WebSocket getrennt ist; ein unveränderter Zustand wird alle 6 Stunden erneut an Gladys gesendet.
- Die lokale API nennt kein Kontingent; die Integration bleibt weit unter dem, was eine Konsole ablehnen würde (höchstens einige Anfragen pro Minute). Antwortet die Konsole „zu viele Anfragen“, meldet die Integration das und versucht es beim nächsten Lesen einfach erneut.
Fehlerbehebung
| Meldung | Was tun |
|---|---|
| Die Konsole antwortet nicht | Prüfe die Adresse und ob Gladys den Port 12445 der Konsole erreicht (Firewall, VLAN). |
| Zertifikat nicht vertrauenswürdig | Aktiviere „Selbstsigniertes Zertifikat akzeptieren“. |
| API-Token abgelehnt | Das Token wurde gelöscht oder falsch kopiert: Erstelle in UniFi Access ein neues und füge es erneut ein. |
| Dem API-Token fehlt eine Berechtigung | Bearbeite das Token in UniFi Access: Gib ihm die Rechte Space und Device. |
| Dieser UniFi-Access-Version fehlt die Entwickler-API | Aktualisiere UniFi Access. |
| Echtzeit-Benachrichtigungen nicht verfügbar | Die Türen werden trotzdem jede Minute gelesen; prüfe, dass nichts zwischen Gladys und der Konsole WebSockets blockiert. |
Für mehr Details setze LOG_LEVEL=debug für die Integration: Jede Benachrichtigung und jedes
Lesen erscheint in den Protokollen (nie das Token).
Grenzen
- Ohne die Hardware entwickelt: Das Vokabular der Alarme (nur
force_unlockwurde in Mitschnitten gesehen), der Zutrittsmethoden und mancher Gegensprechanlagen kann bei deiner Anlage abweichen. Die Rohwerte bleiben in den Variablen der Auslöser erhalten. - Keine Verwaltung von Besuchern, Personen, PIN-Codes oder NFC-Karten; keine Steuerung von Evakuierung oder Lockdown.
- Das Annehmen der Klingel (abheben, an der Gegensprechanlage öffnen) bleibt in den UniFi-Apps.
- Der Verlauf des Widgets beginnt beim Start der Integration (die 20 letzten Zutritte werden behalten).
- Keine Verbindung zu Ubiquiti. UniFi und UniFi Access sind Marken von Ubiquiti Inc.
Konfigurationseinstellungen
Diese Einstellungen fragt UniFi Access in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Deine UniFi-Konsole | section | Nein | UniFi Access auf einer UniFi-OS-Konsole (UDM, UCG, UNVR, Cloud Key…). Erstelle in UniFi Access ein API-Token: Settings, General, Advanced, API Token, mit den Rechten Space und Device. |
| Adresse der Konsole | string | Ja | IP-Adresse oder Name der Konsole. Die API antwortet auf Port 12445: Gib :Port nur an, wenn er abweicht. |
| API-Token | secret | Ja | In UniFi Access erstellt, nur einmal angezeigt. In Gladys gespeichert, nie in den Protokollen. |
| Selbstsigniertes Zertifikat akzeptieren | boolean | Nein | UniFi-Konsolen liefern auf Port 12445 ein selbstsigniertes Zertifikat: Aktiviere das, außer du hast ein vertrauenswürdiges installiert. |
| Fernentriegelung | section | Nein | Standardmäßig aus. Aktiviert erlaubt sie die Szenen-Aktion „Eine Tür entriegeln“ und das Beenden von „immer verriegelt“ — nie als Schalter oder Taste. Eine fehlerhafte Szene öffnet dann deine Tür: Aktiviere sie bewusst. |
| Fernentriegelung durch Szenen erlauben | boolean | Nein | Jede Entriegelung erscheint als „Gladys“ im Systemprotokoll von UniFi Access. |
| Sprache der Funktionsnamen | select | Nein | Namen der Funktionen beim Hinzufügen einer Tür und Texte der Zustände und Szenen-Ereignisse. |
So installierst du UniFi Access in Gladys
- Öffne in Gladys Integrationen: UniFi Access erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-unifi-access:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-unifi-access.
UniFi Access 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 Access 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.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation