Intégration domotique UniFi Protect, gratuite et open source
Caméras, sonnettes, projecteurs et capteurs UniFi Protect en local : détections, images, sonnerie.
Publiée par guim31
- Appareils
- Version 1.0.1
- Nécessite Gladys >=5.1.0
- ★ 0
Amène dans Gladys les caméras, sonnettes, projecteurs et capteurs d'une console UniFi Protect (UDM, UCG, UNVR, Cloud Key), en local : mouvement et détections intelligentes (personne, véhicule, animal, colis), images des caméras, appuis sur la sonnette, commande des projecteurs, détecteurs d'ouverture, température, humidité, luminosité, fuites d'eau, batteries. Tout passe par l'API officielle « Integration » de Protect, sur votre console : aucun compte cloud Ubiquiti, rien ne sort de votre réseau.
Développée sans le matériel : vos retours sont les bienvenus. Cette intégration a été écrite d'après la spécification officielle de l'API et des réponses réelles, sans console Protect sous la main. Si quelque chose ne marche pas comme décrit, ouvrez un ticket sur github.com/guim31/gladys-unifi-protect/issues avec les logs de l'intégration (
LOG_LEVEL=debug).Cette intégration n'est pas affiliée à Ubiquiti. UniFi et UniFi Protect sont des marques d'Ubiquiti Inc.
Ce qu'il vous faut
- Une console UniFi avec UniFi Protect 6 ou plus (l'API Integration ; 7.x conseillé) : Dream Machine, Cloud Gateway, UNVR, Cloud Key Gen2+…
- Une clé d'API créée dans la console (voir plus bas). Un utilisateur sans droits d'administration sur Protect peut obtenir une clé qui ne voit rien.
- Gladys 5.1 ou plus, capable de joindre la console en HTTPS (port 443 par défaut) sur votre réseau.
Mise en place
Créer une clé d'API
- Ouvrez votre console UniFi en local dans un navigateur (par exemple
https://192.168.1.1). - Allez dans Settings, Control Plane, Integrations.
- Créez une clé d'API, donnez-lui un nom (par exemple « Gladys ») et copiez-la : la console ne l'affiche qu'une fois.
Réglages
Dans Gladys, ouvrez l'intégration, puis son onglet Configuration :
- Adresse de la console : l'adresse IP ou le nom de la console, avec
:portsi ce n'est pas 443. Une URL copiée depuis le navigateur convient aussi. - Clé d'API : la clé que vous venez de créer. Elle n'est envoyée qu'à votre console.
- Accepter le certificat auto-signé : les consoles UniFi présentent un certificat auto-signé, ce dont un navigateur avertit. Cochez cette case pour l'accepter, sauf si votre console a un certificat reconnu par votre réseau. La case est décochée par défaut : accepter un certificat invérifiable doit être votre choix.
- Images des caméras : fréquence de rafraîchissement de l'image de chaque caméra ajoutée à Gladys (toutes les 5 minutes par défaut, ou seulement à la détection). Détections, sonnerie et vue en direct demandent toujours une image neuve.
- Langue des noms : la langue des noms de fonctionnalités et des textes envoyés aux scènes (français par défaut). Les noms sont fixés à l'ajout d'un appareil dans Gladys.
Enregistrez : l'état sous le nom de l'intégration passe à connecté, et les appareils apparaissent dans l'onglet Découverte. Ajoutez ceux que vous voulez.
Actions de la configuration
- Tester la connexion : lit la console tout de suite et affiche sa version de Protect, son nombre de caméras, projecteurs et capteurs, et l'empreinte SHA-256 du certificat accepté (comparez-la avec celle que votre navigateur montre pour la console).
- Afficher l'adresse du flux vidéo : choisissez une caméra, et l'adresse RTSP de son flux vidéo s'affiche sous le bouton, prête pour l'intégration « Caméra RTSP » de Gladys (voir Vidéo en direct).
Les appareils
Caméras
Un appareil par caméra, nommé comme dans Protect :
- Image : l'image de la caméra, rafraîchie à l'intervalle choisi, à chaque détection et sonnerie, et chaque fois que vous l'ouvrez au tableau de bord ;
- En ligne : allumé tant que la caméra est connectée à la console ;
- Mouvement : allumé tant que Protect voit du mouvement ;
- Personne, Véhicule, Animal, Colis : allumés pendant une détection intelligente de ce type — seulement les types que votre caméra sait détecter. Un colis est signalé une seule fois par Protect : la fonctionnalité s'allume 10 secondes.
Sonnettes
Une sonnette est une caméra avec une fonctionnalité de plus, Sonnette : elle s'allume 10 secondes à chaque appui, et Gladys affiche quand on a sonné pour la dernière fois. Une sonnette que la console ne nomme pas comme telle (ancien firmware) reçoit cette fonctionnalité à son premier appui : cliquez sur Mettre à jour sur elle dans l'onglet Découverte.
Projecteurs
- Éclairage : l'allumer force la lumière ; l'éteindre la rend à son propre mode d'éclairage (mouvement, horaire…) — elle peut rester allumée jusqu'à la fin de sa minuterie. L'état affiché est l'état réel de la lumière, quoi qui l'ait allumée.
- Mouvement : le détecteur de mouvement du projecteur.
- En ligne.
Capteurs
Les capteurs UP-Sense reçoivent les fonctionnalités que permet leur pose :
- Ouverture : ouvert ou fermé, pour un capteur posé sur une porte, une fenêtre ou une porte de garage ;
- Température (°C), Humidité (%), Luminosité (lux), Mouvement ;
- Fuite d'eau, pour un capteur posé en détecteur de fuite ;
- Batterie (%) ;
- En ligne.
Tableau de bord
Le widget UniFi Protect montre d'un coup d'œil :
- les caméras en ligne (3/4) et les détections des dernières 24 heures ;
- les dernières détections et sonneries, de la plus récente à la plus ancienne, chacune avec l'image prise à ce moment-là ;
- l'état de chaque caméra, et les projecteurs et capteurs hors ligne, s'il y en a.
Dans ses réglages, choisissez une caméra pour n'afficher qu'elle. Les détections sont gardées en mémoire : la liste repart vide après un redémarrage de l'intégration.
Scènes
Déclencheurs
- Objet détecté par une caméra : une détection intelligente de Protect.
Filtres : la caméra, et ce qui est détecté (personne, véhicule, animal,
colis, plaque d'immatriculation, visage) ; laissés vides, tout correspond.
Une détection qui voit une personne, puis un véhicule, lance la scène une
fois pour chacun. Les actions peuvent utiliser le nom de la caméra et le
type d'objet (code
person, ou son nom dans la langue de l'intégration). Quand la scène démarre, l'image de la caméra dans Gladys est déjà celle de la détection. - Quelqu'un sonne à la porte : on a appuyé sur une sonnette. Filtre : la sonnette. Les actions peuvent utiliser son nom. L'image de la sonnette dans Gladys est déjà celle de l'appui.
Les états des appareils (mouvement, personne, ouverture, température…) servent aussi au déclencheur habituel « changement d'état d'un appareil » de Gladys.
Actions
- Rafraîchir l'image d'une caméra : prend une image neuve d'une caméra pour Gladys, pour que l'action suivante (« envoyer une image de caméra » dans un message) envoie ce que la caméra voit maintenant.
- Afficher un message sur la sonnette : change le message de l'écran de la sonnette : ne pas déranger, laisser le colis devant la porte, votre propre texte (30 caractères au plus), ou l'efface — pour un nombre de minutes, ou jusqu'au prochain changement (0).
Aucune action n'arme, ne désarme, ne coupe ni n'arrête l'enregistrement de quoi que ce soit : l'API Integration de Protect ne donne accès ni au mode d'enregistrement ni aux notifications, et rien dans Gladys ne doit pouvoir baisser la sécurité de la maison par erreur.
Idées de scènes
- On sonne : déclencheur « Quelqu'un sonne à la porte », puis « envoyer une image de caméra » de la sonnette sur votre téléphone avec le message « Quelqu'un à la porte ».
- Une personne dans l'allée la nuit : déclencheur « Objet détecté par une caméra » (caméra Allée, Personne), une condition sur l'heure, puis allumer l'éclairage du jardin 5 minutes.
- Un colis a été livré : déclencheur « Objet détecté par une caméra » (Colis), puis un message « Un colis a été livré » avec l'image.
- Absent de la maison : quand la maison se vide, « Afficher un message sur la sonnette » (laisser le colis devant la porte, durée 0) ; à votre retour, l'effacer.
- Fuite d'eau : déclencheur « changement d'état » sur la fonctionnalité Fuite d'eau, puis une alerte sur tous les téléphones.
Vidéo en direct
La fonctionnalité Image montre des images fixes. Pour la vidéo en direct, utilisez l'intégration « Caméra RTSP » de Gladys :
- Dans Protect, ouvrez les réglages de la caméra, Avancé, et activez un flux RTSP (haute, moyenne ou basse qualité).
- Dans Gladys, lancez Afficher l'adresse du flux vidéo avec cette caméra.
- Ajoutez la caméra dans l'intégration « Caméra RTSP » avec cette adresse
(
rtsp://<console>:7447/…).
L'adresse vaut mot de passe du flux : ne la partagez avec personne.
Rafraîchissement et limites de l'API
Gladys n'interroge jamais ces appareils : l'intégration suit la console en direct par deux WebSockets de l'API Integration (appareils et événements), et relit l'état complet toutes les 5 minutes (chaque minute tant que le lien en direct est coupé). Les valeurs ne sont envoyées à Gladys que quand elles changent, et de nouveau toutes les 6 heures sinon.
Images : au plus une image toutes les 6 secondes par caméra (Gladys en accepte 12 par minute), lues une caméra après l'autre. La console limite l'API à environ 10 requêtes par seconde ; l'intégration en reste très loin.
Dépannage
- « La console ne répond pas » : vérifiez l'adresse, que la console est allumée, et que Gladys peut la joindre (même réseau, pare-feu).
- « certificat auto-signé » : cochez Accepter le certificat auto-signé.
- « Clé d'API refusée » : la clé a été supprimée ou mal recopiée. Créez-en une nouvelle, collez-la à nouveau.
- « Pas d'API Integration UniFi Protect à cette adresse » : Protect n'est pas installé sur cette console, ou date d'avant la version 6. Mettez-le à jour.
- « les événements en direct sont coupés » : les états suivent toujours, chaque minute ; les détections et la sonnerie attendent le retour du lien. Il se reconnecte tout seul.
- Pas d'image : l'intégration redimensionne les images jusqu'à la 4K ; un JPEG progressif plus grand que du 1080p ne peut pas l'être dans la mémoire du conteneur. Les logs le disent une fois.
- Une sonnette sans sa fonctionnalité de sonnerie : sonnez une fois, puis cliquez sur Mettre à jour sur elle dans l'onglet Découverte.
- Pour plus de détail, réglez
LOG_LEVEL=debugsur l'intégration et lisez ses logs. Ils ne contiennent jamais votre clé d'API.
Limites
- Développée sans console : testée sur les réponses de l'API, pas sur de vrais appareils.
- Pas de commande de l'enregistrement, des notifications, de l'alarme, des carillons ni des sirènes : l'API Integration ne les expose pas proprement, ou une erreur baisserait la sécurité de la maison.
- Les détections sonores (alarme de fumée, bris de vitre…), le texte des plaques et l'identité des visages ne sont pas utilisés.
- La liste des détections du widget repart vide à chaque redémarrage : l'API Integration ne garde pas d'historique des événements.
- Les images sont réduites à 960 pixels de large au plus (la limite de Gladys est de 150 Ko par image).
Paramètres de configuration
Voici les paramètres demandés par UniFi Protect dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre console UniFi | section | Non | UniFi Protect 6 ou plus. Dans la console, créez une clé d'API : Settings, Control Plane, Integrations. Tout reste sur votre réseau. |
| Adresse de la console | string | Oui | Adresse IP ou nom de la console (UDM, UCG, UNVR, Cloud Key), avec :port si ce n'est pas 443. |
| Clé d'API | secret | Oui | La clé créée dans la console. Elle n'est envoyée qu'à la console, jamais à un cloud. |
| Accepter le certificat auto-signé | boolean | Non | Les consoles UniFi présentent un certificat auto-signé : cochez cette case, sauf si la vôtre a un certificat reconnu. |
| Images des caméras | select | Non | Fréquence de rafraîchissement de l'image des caméras ajoutées. Détections et sonnerie en envoient toujours une neuve. |
| Langue des noms | select | Non | Langue des noms de fonctionnalités et des textes envoyés aux scènes. Les noms sont fixés à l'ajout d'un appareil. |
Comment installer UniFi Protect dans Gladys
- Dans Gladys, ouvrez Intégrations : UniFi Protect 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-protect: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-protect.
UniFi Protect 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 Protect 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 externes
- Découvrir les intégrations natives intégrées à Gladys
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation