UniFi Network Smart-Home-Integration, kostenlos und Open Source
Ubiquiti-UniFi-Integration für UCG, UDM, Switches, APs und Anwesenheitserkennung im Netzwerk.
Veröffentlicht von guim31
- Geräte
- Version 1.9.1
- Erfordert Gladys >=5.1.0
- ★ 1
Info
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
Connect your Ubiquiti UniFi OS console (UCG Fiber, Dream Machine UDM/UDM-SE, UniFi Express, Cloud Key, or self-hosted UniFi Controller) to Gladys Assistant.
Features
- Network Presence Tracking (Device Tracker): Real-time tracking of smartphones and connected network devices for Gladys presence/absence scenes.
- Internet Access Control: Switch button to block or unblock internet access for any connected client device.
- Switch PoE Port Control: Turn PoE power ON/OFF on switch ports (useful for power cycling IP cameras or Access Points).
- Wi-Fi SSID Control: Enable or disable Wi-Fi networks (e.g., Guest Wi-Fi) from Gladys dashboards or scenes.
- WireGuard VPN server: the state of the gateway's WireGuard server (UCG, UDM…), the number of connected VPN clients, and the "VPN client connected" / "VPN client disconnected" scene triggers (remote presence). Turning it off from Gladys stays disabled until you tick Allow the VPN server control in the configuration; then update the device from the Discovery tab so its switch becomes controllable.
- WAN & Gateway Health Metrics: Real-time Upload/Download throughput (Mbps) and Gateway online status.
Local Authentication Guide (100% Local First)
The integration connects directly to your local UniFi console using a local admin account:
Create a dedicated local admin account in UniFi OS:
- Log into your UniFi OS console (
https://192.168.1.1). - In the left navigation bar, click Admins / Users (👥) (or under Control Plane / Identity > Admins).
- Click Add Admin.
- Select Local Access Only.
- Set a username (e.g.
gladys) and password. - Grant Admin role (required to block internet or toggle PoE ports) or Read Only.
- In Gladys, enter your console IP address, username
gladys, and local password.
Usage
- Save configuration in Gladys and click Test UniFi Connection to verify.
- Go to the Discovery tab in Gladys to import your Gateway, network clients, PoE ports, and Wi-Fi networks.
- If you added the "Switch PoE: …" device of version 1.5.2, it keeps the PoE ports of its hardware (same features, history and dashboards kept) and the hardware device updates without them. Delete that device if you prefer the ports on the hardware device: they come back there at the next discovery, with a new history.
- Republish presence every minute (on by default): a client at home is sent to Gladys as "present" again every minute, which the Check user presence scene action needs (it reads when the device was last seen). Each of these states is stored in the history and shown in the activity feed: turn the option off to keep the feed clean if you do not use that action; only the changes are sent then.
Dashboard widgets
Since Gladys 5.1, the integration offers four widgets in the dashboard editor. They read the integration's last poll (every 30 seconds) and never query the console on their own. No widget shows a MAC or an IP address (the address fragments a nameless client gets in its Gladys name are removed): a dashboard can be public.
- Network: the network at a glance. Two tiles, "Download" and "Upload", and a chart follow the gateway's WAN throughput features, live; the "Clients" (active clients) and "Devices" (UniFi hardware online / total) tiles come from the last poll; the status list gives the Internet state (the console's WAN subsystem), the Wi-Fi, wired and guest clients, and the hardware offline.
- Settings: Gateway (the gateway added to Gladys; empty = the first known gateway) and Chart period (last hour, last day, last week).
- Limits: the throughput and the chart need the gateway to be added to Gladys from the Discovery tab (its features feed the tiles and the history). Without a UniFi gateway (a console that does not route), only the counters and the status list show.
- Presence: who is home, from the network clients added to Gladys, with their Gladys names. A "Present" tile (
n / N) and one row per device (present first, then by name); beyond ten rows, a "+ n more" note. The widget refreshes itself as soon as a presence changes.- Setting: Show (present and absent, or present only).
- Limits: a device not added to Gladys does not appear; rename the devices in Gladys for readable names.
- Wi-Fi: one Wi-Fi network (SSID): its state, its connected clients, whether it is a guest network, its band and security when the console gives them, and two buttons, Enable / Disable. The use case: the guest Wi-Fi, opened for the time of a visit from a wall tablet.
- Setting: Wi-Fi network (the SSID added to Gladys; empty = the first known SSID).
- Limits: the buttons go through the SSID's "Wi-Fi state" feature, so the SSID must be added to Gladys from the Discovery tab. The client count is the Wi-Fi clients whose SSID is this one at the last poll.
- WireGuard VPN: the gateway's WireGuard server: its state, the number of connected clients, and one row per client (its name and the data exchanged, ↓ received · ↑ sent, when the console gives them). The Enable / Disable buttons only show when Allow the VPN server control is ticked in the configuration (a remote access cut by mistake is hard to restore).
- Setting: VPN server (a "VPN WireGuard" device; empty = the first known one). If the device chosen is not a VPN server (the gateway, for example), the widget says so.
- The connected clients are the WireGuard clients of the server: phones, computers, or another UniFi gateway connected as a WireGuard client. If the count stays at 0 while a client is connected, run the VPN diagnostic action and paste its result on the forum: it only holds field names, counts and HTTP codes.
- Each "VPN WireGuard" device is a WireGuard server of your gateway (one entry of Settings → VPN → VPN Server): with one server per remote site, there is one device per site, and its connected clients are that site.
- Limits: the connected clients come from the active VPN connections of the console, named after the clients declared on the server (checked on a UDR7 whose clients are two remote UniFi gateways).
Scene triggers
- VPN client connected / VPN client disconnected: a client joins or leaves the gateway's WireGuard server (seen at the next poll, every 30 seconds; nothing when the integration starts). Filter: one VPN server, or any. Variables: client name, VPN server name.
Konfigurationseinstellungen
Diese Einstellungen fragt UniFi Network in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Lokale UniFi-Verbindung | section | Nein | Wähle die Authentifizierungsart und gib deine lokalen UniFi-Zugangsdaten oder deinen lokalen API-Schlüssel ein. |
| IP-Adresse / Hostname | string | Ja | IP-Adresse deiner UniFi-OS-Konsole (z. B. 192.168.1.1). |
| Port | number | Ja | |
| Authentifizierung | select | Ja | |
| Lokaler API-Schlüssel | secret | Nein | In UniFi Network > Integrationen erzeugter API-Schlüssel. |
| Lokaler Benutzername | string | Nein | Lokaler Admin-Benutzer, angelegt unter Konsole > Benutzer & Admins (nötig im Modus Benutzername & Passwort). |
| Lokales Passwort | secret | Nein | |
| Site-ID | string | Ja | |
| Abwesenheitsverzögerung (s) | number | Nein | Inaktivitätsdauer, bevor ein Gerät als abwesend gilt (verhindert Fehlalarme im Ruhemodus). |
| Anwesenheit jede Minute erneut senden | boolean | Nein | Nötig für die Szenenaktion „Anwesenheit von Benutzern überprüfen“. Schalte es aus, um den Aktivitätsverlauf sauber zu halten: Nur Änderungen werden gesendet. |
| Geräteerkennung & Filter | section | Nein | Lege fest, welche Geräte erkannt und an Gladys übermittelt werden. |
| Infrastruktur erkennen (Konsole, APs, Switches) | boolean | Nein | |
| Steuerung des VPN-Servers erlauben | boolean | Nein | Aus: Der WireGuard-Server wird nur angezeigt und kann in Gladys nicht abgeschaltet werden (ein versehentlich getrennter Fernzugang ist schwer wiederherzustellen). |
| Netzwerk-Clients erkennen | boolean | Nein | |
| Nur verbundene Clients (früher bekannte Clients ignorieren) | boolean | Nein | Nur aktuell verbundene Clients importieren, statt Hunderte früherer Geräte, die offline sind. |
| Verbindungsart der Clients | select | Nein | |
| Erlaubte WLAN-SSIDs | string | Nein | WLAN-Clients nach SSID filtern (durch Kommas getrennt, z. B. Zuhause, IoT). Leer lassen, um alle SSIDs zuzulassen. |
So installierst du UniFi Network in Gladys
- Öffne in Gladys Integrationen: UniFi Network erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-integration-unifi:1.9.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-integration-unifi.
UniFi Network 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 Network 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