Skip to main content

UniFi Network smart home integration, free and open source

UniFi Network integration for Gladys Assistant

Ubiquiti UniFi integration for UCG, UDM, Switches, APs and network presence tracking.

View on GitHubAll integrations

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:​

  1. Log into your UniFi OS console (https://192.168.1.1).
  2. In the left navigation bar, click Admins / Users (👥) (or under Control Plane / Identity > Admins).
  3. Click Add Admin.
  4. Select Local Access Only.
  5. Set a username (e.g. gladys) and password.
  6. Grant Admin role (required to block internet or toggle PoE ports) or Read Only.
  7. In Gladys, enter your console IP address, username gladys, and local password.

Usage​

  1. Save configuration in Gladys and click Test UniFi Connection to verify.
  2. Go to the Discovery tab in Gladys to import your Gateway, network clients, PoE ports, and Wi-Fi networks.
  3. 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.
  4. 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.

Configuration settings​

These are the settings UniFi Network asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Local UniFi ConnectionsectionNoSelect your authentication mode and enter your local UniFi credentials or local API key.
IP Address / HostnamestringYesIP address of your UniFi OS console (e.g. 192.168.1.1).
PortnumberYes
Authentication ModeselectYes
Local API KeysecretNoAPI Key generated in UniFi Network > Integrations.
Local UsernamestringNoLocal admin username created in Console > Users & Admins (required if Credentials mode selected).
Local PasswordsecretNo
Site IDstringYes
Presence Offline Delay (s)numberNoInactivity delay before marking a device as absent (prevents deep sleep toggling).
Republish presence every minutebooleanNoNeeded by the "Check user presence" scene action. Turn it off to keep the activity feed clean: only changes are sent.
Device Discovery & FilteringsectionNoConfigure which devices should be discovered and published to Gladys.
Discover Infrastructure (Console, APs, Switches)booleanNo
Allow the VPN server controlbooleanNoOff: the WireGuard server is shown only, it cannot be turned off from Gladys (a remote access cut by mistake is hard to restore).
Discover Network ClientsbooleanNo
Only Connected Clients (Ignore historical known clients)booleanNoOnly import currently connected clients to prevent importing hundreds of offline historical devices.
Client Connection TypeselectNo
Allowed Wi-Fi SSIDsstringNoFilter Wi-Fi clients by SSID names (comma separated, e.g. Home, IoT). Leave empty to allow all SSIDs.

How to install UniFi Network in Gladys​

  1. In Gladys, open Integrations: UniFi Network appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-integration-unifi:1.9.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-integration-unifi.

UniFi Network requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

UniFi Network is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on