Aller au contenu principal

Intégration domotique UniFi Network, gratuite et open source

Intégration UniFi Network pour Gladys Assistant

Intégration Ubiquiti UniFi pour UCG, UDM, Switches, APs et détection de présence.

Voir sur GitHubToutes les intégrations

Cette intégration permet de connecter votre console Ubiquiti UniFi OS (UCG Fiber, Dream Machine UDM/UDM-SE, UniFi Express, Cloud Key ou contrôleur UniFi hébergé) à Gladys Assistant.

Fonctionnalités​

  • Détection de présence (Device Tracker) : Suivi en temps réel des smartphones et appareils connectés à votre réseau Wi-Fi / Ethernet pour déclencher des scènes de présence / absence dans Gladys.
  • Contrôle d'accès Internet : Bouton interrupteur pour bloquer ou autoriser l'accès web de n'importe quel appareil connecté.
  • Contrôle des ports PoE : Allumer ou éteindre l'alimentation PoE d'un port de switch (pratique pour redémarrer une caméra IP ou un point d'accès).
  • Wi-Fi Invités & SSID : Interrupteurs pour activer ou désactiver facilement des réseaux Wi-Fi (ex: Wi-Fi Invités).
  • Serveur VPN WireGuard : l'état du serveur WireGuard de la passerelle (UCG, UDM…), le nombre de clients VPN connectés, et des déclencheurs de scène « Client VPN connecté » / « Client VPN déconnecté » (présence à distance). Le couper depuis Gladys reste désactivé tant que vous ne cochez pas Autoriser la commande du serveur VPN dans la configuration ; après l'avoir coché, mettez l'appareil à jour depuis l'onglet Découverte pour que son interrupteur devienne commandable.
  • Supervision WAN & Santé : Remontée des débits montant et descendant (Mbps) et de l'état de votre Gateway.

Guide d'Authentification​

L'intégration prend en charge 2 modes au choix :

Mode 1 : Clé API Locale (Recommandé)​

  1. Rendez-vous sur votre console UniFi dans le menu Integrations (ex: https://192.168.1.1/network/default/integrations ou UniFi Network > Control Plane / Settings > Integrations).
  2. Cliquez sur Create New API Key.
  3. Nommez la clé (ex: Gladys) et copiez la clé générée.
  4. Dans Gladys, choisissez le mode Clé API Locale et collez la clé.

Mode 2 : Compte Administrateur Local (Nom d'utilisateur & Mot de passe)​

  1. Connectez-vous à votre console UniFi OS (https://192.168.1.1).
  2. Allez dans Admins / Utilisateurs (👥) (ou dans Control Plane / Identity > Admins).
  3. Cliquez sur + Create New et cochez Restrict to Local Access Only.
  4. Définissez un nom d'utilisateur (ex: gladys) et un mot de passe fort.
  5. Attribuez-lui le rôle Admin.
  6. Dans Gladys, choisissez le mode Nom d'utilisateur & Mot de passe local et entrez ces identifiants.

Utilisation​

  1. Une fois la configuration enregistrée dans Gladys, cliquez sur le bouton Tester la connexion UniFi pour valider la communication.
  2. Allez dans l'onglet Découverte de Gladys pour ajouter votre Gateway, vos clients réseau (smartphones), vos ports PoE et vos réseaux Wi-Fi.
  3. Si vous aviez ajouté l'appareil « Switch PoE : … » de la version 1.5.2, il garde les ports PoE de son équipement (mêmes fonctionnalités, historique et tableaux de bord conservés) et l'équipement lui-même se met à jour sans eux. Supprimez cet appareil si vous préférez les ports sur l'équipement : ils y reviennent à la découverte suivante, avec un nouvel historique.
  4. Republier la présence chaque minute (activé par défaut) : un client à la maison est renvoyé à Gladys comme « présent » chaque minute, ce dont l'action de scène Vérifier la présence a besoin (elle lit quand l'appareil a été vu pour la dernière fois). Chacun de ces états est gardé dans l'historique et affiché dans le fil d'activité : désactivez l'option pour garder le fil propre si vous n'utilisez pas cette action ; seuls les changements sont alors envoyés.

Widgets du tableau de bord​

Depuis Gladys 5.1, l'intégration propose quatre widgets dans l'éditeur de tableau de bord. Ils lisent le dernier relevé de l'intégration (toutes les 30 secondes) et n'interrogent jamais la console en plus. Aucun widget n'affiche d'adresse MAC ni d'adresse IP (les fragments d'adresse qu'un client sans nom reçoit dans son nom Gladys sont retirés) : un tableau de bord peut être public.

  • Réseau : le réseau en un coup d'œil. Deux tuiles « Descendant » et « Montant » et un graphique suivent les fonctionnalités de débit WAN de la passerelle, en direct ; les tuiles « Clients » (clients actifs) et « Équipements » (équipements UniFi en ligne / total) viennent du dernier relevé ; la liste d'état donne l'état d'Internet (sous-système WAN de la console), les clients Wi-Fi, filaires et invités, et les équipements hors ligne.

    • Réglages : Passerelle (la passerelle ajoutée à Gladys ; vide = la première passerelle connue) et Période du graphique (dernière heure, dernier jour, dernière semaine).
    • Limites : le débit et le graphique demandent que la passerelle soit ajoutée à Gladys depuis la Découverte (ce sont ses fonctionnalités qui alimentent les tuiles et l'historique). Sans passerelle UniFi (console sans routage), seuls les compteurs et la liste d'état s'affichent.

  • Présence : qui est à la maison, d'après les clients réseau ajoutés à Gladys, avec leurs noms Gladys. Une tuile « Présents » (n / N) et une ligne par appareil (présents d'abord, puis par nom) ; au-delà de dix lignes, une mention « + n autres ». Le widget se rafraîchit de lui-même dès qu'une présence change.

    • Réglage : Afficher (présents et absents, ou présents seulement).
    • Limites : un appareil non ajouté à Gladys n'apparaît pas ; renommez les appareils dans Gladys pour avoir des noms lisibles.

  • Wi-Fi : un réseau Wi-Fi (SSID) : son état, ses clients connectés, s'il s'agit d'un réseau invités, sa bande et sa sécurité quand la console les donne, et deux boutons Activer / Désactiver. Le cas d'usage : le Wi-Fi invités, qu'on ouvre le temps d'une visite depuis une tablette murale.

    • Réglage : Réseau Wi-Fi (le SSID ajouté à Gladys ; vide = le premier SSID connu).
    • Limites : les boutons passent par la fonctionnalité « État Wi-Fi » du SSID, qui doit donc être ajouté à Gladys depuis la Découverte. Le nombre de clients compte les clients Wi-Fi dont le SSID est celui-ci au dernier relevé.

  • VPN WireGuard : le serveur WireGuard de la passerelle : son état, le nombre de clients connectés, et une ligne par client (son nom et les données échangées, ↓ reçu · ↑ envoyé, quand la console les donne). Les boutons Activer / Désactiver n'apparaissent que si Autoriser la commande du serveur VPN est coché dans la configuration (un accès à distance coupé par erreur se rétablit mal).

    • Réglage : Serveur VPN (un appareil « VPN WireGuard » ; vide = le premier connu). Si l'appareil choisi n'est pas un serveur VPN (la passerelle, par exemple), le widget le dit.
    • Les clients connectés sont les clients WireGuard du serveur : téléphones, ordinateurs, ou une autre passerelle UniFi connectée en client WireGuard. Si le nombre reste à 0 alors qu'un client est connecté, lancez l'action Diagnostic VPN et collez son résultat sur le forum : il ne contient que des noms de champs, des nombres et des codes HTTP.
    • Chaque appareil « VPN WireGuard » est un serveur WireGuard de votre passerelle (une entrée de Paramètres → VPN → Serveur VPN) : avec un serveur par site distant, il y a un appareil par site, et ses clients connectés sont ce site.
    • Limites : les clients connectés viennent des connexions VPN actives de la console, nommés d'après les clients déclarés sur le serveur (vérifié sur un UDR7 dont les clients sont deux passerelles UniFi distantes).

Déclencheurs de scène​

  • Client VPN connecté / Client VPN déconnecté : un client rejoint ou quitte le serveur WireGuard de la passerelle (vu au relevé suivant, toutes les 30 secondes ; rien au démarrage de l'intégration). Filtre : un serveur VPN, ou n'importe lequel. Variables : nom du client, nom du serveur VPN.

Dépannage​

En cas de problème, consultez les journaux (logs) du conteneur Docker dans l'interface Gladys ou avec docker logs gladys-integration-unifi.

Paramètres de configuration​

Voici les paramètres demandés par UniFi Network dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Connexion Locale UniFi OSsectionNonSélectionnez le mode d'authentification et entrez vos identifiants locaux UniFi ou votre clé API locale.
Adresse IP / HôtestringOuiAdresse IP de votre console UniFi OS (ex: 192.168.1.1).
PortnumberOui
Mode d'authentificationselectOui
Clé API LocalesecretNonClé API générée dans UniFi Network > Intégrations.
Nom d'utilisateur localstringNonNom d'admin local créé dans Console > Utilisateurs & Admins (requis si mode Identifiants).
Mot de passe localsecretNon
ID du SitestringOui
Délai de déconnexion présence (s)numberNonDélai d'inactivité avant d'indiquer un appareil absent (évite les faux positifs en veille).
Republier la présence chaque minutebooleanNonNécessaire à l'action de scène « Vérifier la présence ». Désactivez-le pour garder le fil d'activité propre : seuls les changements sont envoyés.
Filtres de découverte des appareilssectionNonConfigurez quels appareils doivent être découverts et envoyés à Gladys.
Découvrir l'infrastructure (Console, APs, Switches)booleanNon
Autoriser la commande du serveur VPNbooleanNonDésactivé : le serveur WireGuard est seulement affiché, il ne peut pas être coupé depuis Gladys (un accès à distance coupé par erreur se rétablit mal).
Découvrir les clients du réseaubooleanNon
Clients connectés uniquement (Ignorer les anciens clients)booleanNonImporter uniquement les clients actuellement connectés pour éviter d'importer des centaines d'anciens appareils hors-ligne.
Type de connexion des clientsselectNon
SSIDs Wi-Fi autorisésstringNonFiltrer les clients Wi-Fi par noms de SSID (séparés par des virgules, ex: Maison, IoT). Laissez vide pour autoriser tous les SSIDs.

Comment installer UniFi Network dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : UniFi Network apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/guim31/gladys-integration-unifi:1.9.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-integration-unifi.

UniFi Network nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes​

UniFi Network est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par guim31, et non par l'équipe cœur de Gladys.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂
Dernière mise à jour le