Intégration domotique UniFi Access, gratuite et open source
Portes UniFi Access : verrou, capteur d'ouverture, sonnette, accès autorisés ou refusés, alarmes.
Publiée par guim31
- Appareils
- Version 1.0.1
- Nécessite Gladys >=5.1.0
- ★ 0
Amène dans Gladys les portes de UniFi Access (le contrôle d'accès d'Ubiquiti : lecteurs G2 et G3, Intercom, UA Hub, UA Hub Door Mini, UA Ultra), sur votre réseau local : l'état de chaque verrou et de chaque porte, la sonnette, qui est entré et comment, les alarmes de porte. Sans lien avec Ubiquiti.
Développée sans le matériel : vos retours sont les bienvenus. L'intégration a été écrite d'après l'API officielle, l'intégration Home Assistant et des captures réelles publiées par d'autres projets, mais n'a jamais tourné sur une vraie installation UniFi Access. Dites-nous ce qui marche et ce qui ne marche pas sur GitHub.
Présentation
- Un appareil Gladys par porte UniFi Access, en lecture seule : rien sur le tableau de bord ne peut ouvrir une porte.
- Temps réel : l'intégration garde une connexion ouverte vers le WebSocket de notifications d'UniFi Access, et relit tout toutes les 5 minutes (chaque minute si le WebSocket est coupé).
- Déclencheurs de scène : sonnette, accès autorisé, accès refusé, alarme de porte, porte hors ligne puis de retour.
- Actions de scène : garder une porte verrouillée, la remettre sur son planning normal et — seulement si vous l'activez — déverrouiller une porte.
- Un widget de tableau de bord : les portes et les derniers accès.
Prérequis
- UniFi Access sur une console UniFi OS (UDM, UCG, UNVR, Cloud Key Gen2+…), assez récent pour proposer l'API développeur (Settings, General, Advanced, API Token).
- Gladys 5.1 ou plus récent, sur le même réseau que la console (port 12445 joignable).
- Un jeton d'API : dans UniFi Access, Settings → General → Advanced → API Token → Create. Donnez-lui les permissions Space (portes) et Device, en lecture et écriture si vous voulez les actions de scène. Copiez-le : il n'est affiché qu'une fois.
Configuration
Dans Gladys : Intégrations → UniFi Access → Configuration.
| Champ | Quoi saisir |
|---|---|
| Adresse de la console | Adresse IP ou nom de la console, ex. 192.168.1.1. L'API répond sur le port 12445 : ajoutez :port seulement s'il diffère. |
| Jeton d'API | Le jeton créé ci-dessus. Il reste dans Gladys et n'est jamais écrit dans les logs. |
| Accepter le certificat auto-signé | Les consoles UniFi servent un certificat auto-signé sur le port 12445 : à cocher, sauf si vous avez installé un certificat reconnu. |
| Autoriser le déverrouillage par les scènes | Désactivé par défaut. Lisez « Actions de scène » ci-dessous avant de l'activer. |
| Langue des noms de fonctionnalités | Noms des fonctionnalités à l'ajout d'une porte, et textes des états et des événements de scène (français par défaut). |
Puis Tester la connexion : elle lit la console tout de suite et indique combien de portes et d'appareils elle a trouvés, et si les notifications en temps réel sont connectées. Les portes apparaissent ensuite dans l'onglet Découverte : ajoutez celles que vous voulez.
Appareils
Chaque porte d'UniFi Access devient un appareil, nommé comme la porte. Ses fonctionnalités sont toutes en lecture seule ; certaines n'existent que si le matériel les a.
| Fonctionnalité | Type Gladys | Valeurs |
|---|---|---|
| Verrou | verrou / état | verrouillé ou déverrouillé |
| Position de la porte | capteur d'ouverture | ouverte ou fermée — seulement sur une porte dont le capteur de position (DPS) est câblé |
| Sonnette | sonnette / sonnerie | sonne quelques secondes à chaque appel — sur une porte avec lecteur Pro, interphone ou entrée sonnette du hub |
| Règle de verrouillage | texte | Normal, Toujours verrouillée, Toujours déverrouillée, Déverrouillée un moment jusqu'à 18:30, Déverrouillage planifié… |
| Dernier accès | texte | ex. Alice Martin · Badge NFC · Entrée, Refusé · Inconnu · Code PIN |
La pastille de l'appareil indique si sa porte est en ligne (son concentrateur répond à UniFi Access), et passe à l'orange quand les notifications en temps réel sont coupées.
Une porte qui sonne pour la première fois alors qu'elle n'avait pas de fonctionnalité sonnette en reçoit une : utilisez Mettre à jour dans l'onglet Découverte pour l'ajouter à l'appareil.
Widget
Portes UniFi Access : une ligne par porte (verrouillée ou non, ouverte ou fermée, alarme, hors ligne) et les derniers accès (qui, comment, autorisé ou refusé). Choisissez une porte dans les réglages du widget pour n'afficher qu'elle : le widget propose alors deux boutons, qui demandent chacun une confirmation :
- Toujours verrouiller : la porte reste verrouillée quel que soit son planning (marqué d'un ✓ tant que c'est actif) ;
- Planning normal : met fin à la règle temporaire. Quitter « toujours verrouillée » peut déverrouiller la porte : ce bouton n'apparaît alors que si le déverrouillage à distance est activé.
Il n'y a jamais de bouton de déverrouillage.
Déclencheurs de scène
| Déclencheur | Quand | Filtres | Variables |
|---|---|---|---|
| Sonnette actionnée | quelqu'un a sonné à un lecteur ou à un interphone | porte | nom de la porte, appareil sonné |
| Accès autorisé | une porte a été ouverte par badge, code, visage, appli… | porte, méthode, utilisateur | nom de la porte, nom de l'utilisateur, méthode (nfc, pin, face…), méthode en toutes lettres, sens (entry, exit) |
| Accès refusé | un badge, un code ou un visage a été refusé | porte, méthode | les mêmes |
| Alarme de porte | porte forcée ou restée ouverte trop longtemps | porte, alarme | nom de la porte, alarme (forced_open, held_open, other), alarme en toutes lettres, type envoyé par UniFi Access |
| Porte hors ligne | le concentrateur d'une porte ne répond plus | porte | nom de la porte |
| Porte de nouveau en ligne | le concentrateur d'une porte répond de nouveau | porte | nom de la porte, minutes hors ligne |
UniFi Access signale chaque accès deux fois (un « insight » et une ligne de journal, à quelques millisecondes d'écart) : l'intégration ne déclenche qu'une fois.
Actions de scène
| Action | Effet |
|---|---|
| Garder une porte verrouillée | La porte reste verrouillée quel que soit son planning. Toujours permis. |
| Remettre une porte sur son planning normal | Met fin à « toujours verrouillée » ou « toujours déverrouillée ». Quitter « toujours verrouillée » exige le déverrouillage à distance activé. |
| Déverrouiller une porte | Un déverrouillage à distance ; la porte se reverrouille seule après son délai habituel. Refusé si le déverrouillage à distance n'est pas activé. |
Attention — déverrouillage à distance. Il est désactivé par défaut. Une fois activé, toute scène qui utilise « Déverrouiller une porte » ouvre la porte quand elle s'exécute : un mauvais déclencheur, un tableau de bord partagé, un compte Gladys compromis signifient alors une porte ouverte. Il n'existe jamais comme interrupteur, commande vocale ou bouton du tableau de bord. Chaque déverrouillage est signé « Gladys » dans le journal système d'UniFi Access.
Exemples de scènes
- Quelqu'un à la porte : déclencheur « Sonnette actionnée » sur la porte d'entrée → envoyer le message « On sonne à {{triggerEvent.data.door_name}} » et afficher la caméra de l'entrée.
- Les enfants sont rentrés : déclencheur « Accès autorisé » avec l'utilisateur « Léa » → envoyer « Léa est rentrée ({{triggerEvent.data.method_label}}) ».
- Départ de la maison : quand l'alarme est armée → « Garder une porte verrouillée » sur chaque porte.
- Effraction : déclencheur « Alarme de porte » avec l'alarme « Porte forcée » → sirène et notification.
- Badge refusé : déclencheur « Accès refusé » → notification avec {{triggerEvent.data.door_name}} et {{triggerEvent.data.method_label}}.
Rafraîchissement et limites de l'API
- Temps réel par le WebSocket de notifications d'UniFi Access (une connexion sortante du conteneur vers le port 12445), rouverte après 1 s, 2 s, 4 s… jusqu'à 1 minute quand elle tombe.
- Une lecture complète (portes, appareils, une règle de verrouillage par porte) toutes les 5 minutes, chaque minute tant que le WebSocket est coupé ; un état inchangé est renvoyé à Gladys toutes les 6 heures.
- L'API locale ne publie pas de quota ; l'intégration reste très en dessous de ce qu'une console refuserait (quelques requêtes par minute au plus). Si la console répond « trop de requêtes », l'intégration le signale et réessaie simplement à la lecture suivante.
Dépannage
| Message | Que faire |
|---|---|
| La console ne répond pas | Vérifiez l'adresse, et que Gladys atteint le port 12445 de la console (pare-feu, VLAN). |
| Certificat non reconnu | Cochez « Accepter le certificat auto-signé ». |
| Jeton d'API refusé | Le jeton a été supprimé ou mal copié : créez-en un nouveau dans UniFi Access et collez-le de nouveau. |
| Il manque une permission au jeton d'API | Modifiez le jeton dans UniFi Access : donnez-lui les permissions Space et Device. |
| Cette version d'UniFi Access n'a pas l'API développeur | Mettez UniFi Access à jour. |
| Notifications en temps réel indisponibles | Les portes sont tout de même relues chaque minute ; vérifiez que rien entre Gladys et la console ne bloque les WebSockets. |
Pour plus de détails, réglez LOG_LEVEL=debug sur l'intégration : chaque notification et chaque
lecture apparaissent dans les logs (jamais le jeton).
Limites
- Développée sans le matériel : le vocabulaire des alarmes (seul
force_unlocka été vu dans des captures), des méthodes d'accès et de certains interphones peut différer sur votre installation. Les valeurs brutes sont gardées dans les variables des déclencheurs. - Pas de gestion des visiteurs, des utilisateurs, des codes PIN ni des badges NFC ; pas de commande d'évacuation ni de confinement.
- Les réponses à la sonnette (décrocher, ouvrir depuis l'interphone) restent dans les applis UniFi.
- L'historique du widget commence au démarrage de l'intégration (les 20 derniers accès sont gardés).
- Sans lien avec Ubiquiti. UniFi et UniFi Access sont des marques d'Ubiquiti Inc.
Paramètres de configuration
Voici les paramètres demandés par UniFi Access dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre console UniFi | section | Non | UniFi Access sur une console UniFi OS (UDM, UCG, UNVR, Cloud Key…). Dans UniFi Access, créez un jeton d'API : Settings, General, Advanced, API Token, avec les permissions Space et Device. |
| Adresse de la console | string | Oui | Adresse IP ou nom de la console. L'API répond sur le port 12445 : ajoutez :port seulement s'il diffère. |
| Jeton d'API | secret | Oui | Créé dans UniFi Access, affiché une seule fois. Gardé dans Gladys, jamais écrit dans les logs. |
| Accepter le certificat auto-signé | boolean | Non | Les consoles UniFi servent un certificat auto-signé sur le port 12445 : à cocher, sauf si vous en avez installé un reconnu. |
| Déverrouillage à distance | section | Non | Désactivé par défaut. Activé, il permet l'action de scène « Déverrouiller une porte » et la sortie de « toujours verrouillée » — jamais un interrupteur ni un bouton. Une scène qui se trompe ouvre alors votre porte : activez-le en connaissance de cause. |
| Autoriser le déverrouillage par les scènes | boolean | Non | Chaque déverrouillage est signé « Gladys » dans le journal système d'UniFi Access. |
| Langue des noms de fonctionnalités | select | Non | Noms donnés aux fonctionnalités à l'ajout d'une porte, et textes des états et des événements de scène. |
Comment installer UniFi Access dans Gladys
- Dans Gladys, ouvrez Intégrations : UniFi Access apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/guim31/gladys-unifi-access:1.0.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). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-unifi-access.
UniFi Access 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 Access 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.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation