Saltar al contenido principal

Integración domótica UniFi Network, gratuita y de código abierto

Integración UniFi Network para Gladys Assistant

Integración de Ubiquiti UniFi para UCG, UDM, switches, APs y detección de presencia en la red.

Ver en GitHubTodas las integraciones
info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

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.

Parámetros de configuración​

Estos son los parámetros que UniFi Network te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Conexión local a UniFi OSsectionNoElija el modo de autenticación e introduzca sus credenciales locales de UniFi o su clave de API local.
Dirección IP / Nombre de hoststringSíDirección IP de su consola UniFi OS (p. ej., 192.168.1.1).
PuertonumberSí
Modo de autenticaciónselectSí
Clave de API localsecretNoClave de API generada en UniFi Network > Integraciones.
Nombre de usuario localstringNoUsuario administrador local creado en Consola > Usuarios y administradores (obligatorio en el modo usuario y contraseña).
Contraseña localsecretNo
ID del sitiostringSí
Retardo de ausencia (s)numberNoTiempo de inactividad antes de marcar un dispositivo como ausente (evita falsos cambios en reposo).
Reenviar la presencia cada minutobooleanNoNecesario para la acción de escena «Comprobar presencia del usuario». Desactívelo para mantener limpio el registro de actividad: solo se envían los cambios.
Detección y filtrado de dispositivossectionNoConfigure qué dispositivos se detectan y se envían a Gladys.
Detectar la infraestructura (consola, APs, switches)booleanNo
Permitir el control del servidor VPNbooleanNoDesactivado: el servidor WireGuard solo se muestra y no puede apagarse desde Gladys (un acceso remoto cortado por error es difícil de restablecer).
Detectar los clientes de la redbooleanNo
Solo clientes conectados (ignorar los clientes antiguos)booleanNoImportar solo los clientes conectados ahora, para no importar cientos de dispositivos antiguos desconectados.
Tipo de conexión de los clientesselectNo
SSID Wi-Fi permitidosstringNoFiltrar los clientes Wi-Fi por SSID (separados por comas, p. ej., Casa, IoT). Déjelo vacío para permitir todos los SSID.

Cómo instalar UniFi Network en Gladys​

  1. En Gladys, abre Integraciones: UniFi Network aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/guim31/gladys-integration-unifi:1.9.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-integration-unifi.

UniFi Network requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas​

UniFi Network es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en