Intégration communautaire Nuki, gratuite et open source
Serrures Nuki, Opener et Smart Door : via Bridge, MQTT ou Nuki Web.
Publiée par gboulvin
- Appareils
- Version 1.0.1
- Nécessite Gladys >=5.1.0
- ★ 0
Pilotez vos appareils Nuki depuis Gladys : Smart Lock (toutes générations, 3.0 Pro, 4e génération, Ultra), Smart Door et Opener — verrouiller, déverrouiller, ouvrir la porte, suivre les batteries, le capteur de porte et le clavier, et réagir à chaque opération dans vos scènes.
Choisir comment Gladys parle à vos appareils Nuki
L'intégration propose trois canaux. Configurez-en au moins un ; vous pouvez les combiner.
| Canal | Type | Appareils | Ce qu'il apporte |
|---|---|---|---|
| Nuki Bridge | Local (HTTP) | Toutes les Smart Lock, Smart Door et Opener | Fonctionne sans internet, détection de sonnerie de l'Opener |
| MQTT | Local (temps réel) | Smart Lock 3.0 Pro, 4e génération, Ultra | Mises à jour instantanées sans interrogation, qui/comment (bouton, clavier…) |
| Nuki Web | Cloud | Tous les appareils liés à votre compte Nuki Web | Qui a actionné la serrure (nom, clavier, empreinte), journal d'activité |
Quand plusieurs canaux atteignent un appareil, Gladys utilise d'abord le local (MQTT, puis le Bridge) et bascule sur l'autre en cas d'échec. Désactivez Préférer la connexion locale dans l'écran de configuration pour passer d'abord par Nuki Web. Le badge de chaque appareil indique le canal utilisé : Locale, Cloud ou Injoignable ; un point orange signale un mode de secours (par exemple : Bridge hors ligne, Nuki Web utilisé à la place).
Installation
Nuki Bridge (local)
- Dans l'app Nuki, ouvrez Gérer le Bridge et activez l'API HTTP.
- Dans Gladys, ouvrez la configuration de l'intégration Nuki et cliquez sur Trouver mon Bridge : l'adresse IP est remplie pour vous (ou saisissez-la, elle est affichée dans l'app Nuki).
- Cliquez sur Appairer le Bridge, puis appuyez sur le bouton du Bridge dans les 30 secondes : le jeton d'API est enregistré automatiquement. Vous pouvez aussi recopier le jeton affiché dans l'app.
- Laissez Envoyer le jeton haché (sécurisé) activé (firmware du Bridge 1.13 ou plus) : le jeton ne circule jamais en clair sur votre réseau.
Donnez une adresse IP fixe au Bridge dans votre box : si elle change, relancez Trouver mon Bridge.
MQTT (local, Smart Lock 3.0 Pro / 4.0 / Ultra)
- Il vous faut un broker MQTT (Mosquitto…). Celui de l'intégration MQTT de Gladys convient.
- Dans l'app Nuki, ouvrez les réglages de la serrure → Fonctionnalités et configuration → MQTT, activez-le et indiquez l'adresse IP du broker, le port, l'utilisateur et le mot de passe.
- Dans Gladys, renseignez URL du broker MQTT (ex.
mqtt://192.168.1.10:1883), l'utilisateur et le mot de passe. Les serrures apparaissent en quelques secondes.
Nuki Web (cloud)
- Activez Nuki Web pour vos appareils dans l'app Nuki.
- Sur web.nuki.io, ouvrez API et générez un jeton d'API avec au moins les droits Smartlock, Smartlock action et Smartlock log.
- Collez-le dans Jeton d'API Nuki Web.
Créer les appareils
Ouvrez l'onglet Découverte de l'intégration et créez les appareils souhaités. Si vous ajoutez plus tard un capteur de porte ou un clavier, l'onglet Découverte propose de mettre l'appareil à jour.
Options
- Intervalle de rafraîchissement : fréquence de lecture du Bridge (10 s minimum, 30 s par défaut). Nuki Web est lu au plus toutes les 30 secondes, et seulement si nécessaire. MQTT n'a pas besoin d'interrogation.
- Quand Gladys déverrouille : Déverrouiller seulement (par défaut) ou Déverrouiller et ouvrir la porte.
- Quand Gladys verrouille : Verrouiller (par défaut) ou Verrouillage complet (deux tours, Smart Lock 3.0 et plus ; verrouillage simple sur les modèles plus anciens).
Appareils et fonctionnalités
Smart Lock / Smart Door
| Fonctionnalité | Description |
|---|---|
| Serrure | Interrupteur : 1 = verrouillée, 0 = déverrouillée (pilotable) |
| État de la serrure | Verrouillée / déverrouillée / en mouvement / erreur |
| Batterie | Niveau de charge en % |
| Batterie faible | Alerte batterie critique |
| En charge | Charge du Power Pack (3.0 et plus) |
| Porte | Ouverte / fermée (si un capteur de porte est appairé) |
| Pile du capteur de porte | (si un capteur de porte est appairé) |
| Pile du clavier | (si un clavier est appairé) |
Opener : interrupteurs Ring to Open et Mode continu, Batterie faible, et Sonnette (détection de sonnerie, via le Bridge).
Scènes
Déclencheurs
- Serrure Nuki actionnée — une serrure a été verrouillée, déverrouillée, ouverte ou a
utilisé Lock 'n' Go. Filtrez sur la serrure, l'opération, comment elle a été actionnée
(app, à la main, bouton, clavier, empreinte, verrouillage auto, Nuki Web, HomeKit, MQTT,
Gladys…) et l'utilisateur Nuki (avec Nuki Web). Variables :
action,trigger,user,device_name. Exemple : « quand Alice déverrouille la porte d'entrée avec le clavier, couper l'alarme ». - Nuki Opener : on a sonné — quelqu'un a sonné à l'interphone (Opener avec Bridge).
- Problème de serrure Nuki — moteur bloqué, serrure non calibrée ou commande refusée.
- Batterie Nuki critique — la batterie d'une serrure, d'un Opener, d'un clavier ou d'un capteur de porte est faible.
Les opérations lancées par Gladys elle-même sont signalées avec le déclencheur gladys :
excluez-le dans le filtre pour qu'une scène ne réagisse pas à ses propres actions.
Actions
- Actionner une serrure Nuki — verrouiller, déverrouiller, ouvrir la porte, Lock 'n' Go,
verrouillage complet. Sortie :
success. - Actionner un Nuki Opener — ouvrir la gâche, activer/désactiver Ring to Open ou le mode
continu. Sortie :
success. - Lire un appareil Nuki — sorties
locked,state,door_open,battery,battery_critical,reachable, utilisables dans les actions suivantes (ex. envoyer « la porte est toujours déverrouillée »). - Verrouiller toutes les serrures Nuki — sorties
locked_countetfailed_count.
Le déclencheur standard « état d'un appareil » de Gladys fonctionne aussi sur chaque fonctionnalité (porte ouverte, batterie sous 20 %…).
Widgets du tableau de bord
- Serrure Nuki — une serrure ou un Opener : état, batterie en direct, porte, accessoires, canal, dernière activité, et boutons Verrouiller / Déverrouiller / Ouvrir la porte (l'ouverture demande confirmation). Pour un Opener : Ouvrir et Ring to Open.
- Vue d'ensemble Nuki — tous les appareils Nuki d'un coup d'œil et un bouton Tout verrouiller.
- Activité Nuki — les dernières opérations : qui, comment et quand (depuis Nuki Web si configuré, sinon depuis ce que l'intégration a observé).
Dépannage
- « The Nuki Bridge refused the API token » : appairez de nouveau le Bridge, ou désactivez Envoyer le jeton haché (sécurisé) si le firmware de votre Bridge est antérieur à 1.13.
- « Nuki Bridge unreachable » : vérifiez l'adresse IP et que l'API HTTP est activée. Le Bridge traite une requête à la fois : évitez qu'un autre logiciel l'interroge trop souvent.
- MQTT : aucune serrure n'apparaît : vérifiez dans l'app Nuki que MQTT est connecté, que la serrure utilise l'adresse IP du broker, et que Gladys utilise le même broker.
- Pas de nom d'utilisateur dans les déclencheurs : les noms viennent de Nuki Web ; ajoutez un jeton d'API.
- Le bouton Tester la connexion vérifie chaque canal configuré et indique ce qui fonctionne.
Confidentialité et sécurité
Les jetons et mots de passe sont stockés par Gladys comme secrets et jamais écrits dans les logs. Le jeton du Bridge est envoyé haché par défaut. Nuki Web n'est contacté que si vous configurez un jeton d'API. L'historique d'activité est conservé dans le volume de données propre à l'intégration.
Paramètres de configuration
Voici les paramètres demandés par Nuki dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Connectez vos appareils Nuki | section | Non | Renseignez au moins un des trois canaux ci-dessous. Le Bridge et MQTT sont locaux (rapides, fonctionnent sans internet) ; Nuki Web passe par le cloud et indique aussi qui a actionné la serrure. Vous pouvez les combiner : Gladys utilise d’abord le local et bascule sur l’autre en secours (voir « Préférer la connexion locale »). |
| Nuki Bridge (local) | section | Non | Dans l’app Nuki, ouvrez les réglages du Bridge et activez l’API HTTP. Utilisez ensuite « Trouver mon Bridge » puis « Appairer le Bridge » ci-dessous (appuyez sur le bouton du Bridge quand demandé), ou recopiez l’adresse IP et le jeton d’API affichés par l’app. |
| Adresse IP du Bridge | string | Non | |
| Port du Bridge | number | Non | |
| Jeton d’API du Bridge | secret | Non | Rempli automatiquement par « Appairer le Bridge ». |
| Envoyer le jeton haché (sécurisé) | boolean | Non | Recommandé : le jeton ne circule jamais en clair sur votre réseau. À désactiver uniquement pour un firmware de Bridge antérieur à 1.13. |
| MQTT (local, temps réel) | section | Non | Pour les Smart Lock 3.0 Pro, 4e génération et Ultra : dans l’app Nuki, activez MQTT et indiquez votre broker à la serrure (avec son adresse IP). Saisissez le même broker ici. Les changements arrivent instantanément, sans interrogation. |
| URL du broker MQTT | string | Non | |
| Utilisateur MQTT | string | Non | |
| Mot de passe MQTT | secret | Non | |
| Nuki Web (cloud) | section | Non | Activez Nuki Web dans l’app Nuki, puis sur web.nuki.io ouvrez « API » et générez un jeton d’API avec les droits smartlock, smartlock action et log. Nuki Web indique aussi qui a verrouillé ou déverrouillé (utilisateur, clavier, empreinte...). |
| Jeton d’API Nuki Web | secret | Non | |
| Options | section | Non | Fréquence de lecture du Bridge et de Nuki Web (MQTT n’a pas besoin d’interrogation), et comportement de l’interrupteur de serrure de Gladys. |
| Intervalle de rafraîchissement (s) | number | Non | Secondes entre deux lectures du Bridge (10 minimum). Nuki Web n’est jamais lu plus d’une fois toutes les 30 secondes. |
| Quand Gladys déverrouille | select | Non | |
| Quand Gladys verrouille | select | Non |
Comment installer Nuki dans Gladys
- Dans Gladys, ouvrez Intégrations : Nuki 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/gboulvin/gladys-nuki: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/gboulvin/Gladys-Nuki.
Nuki 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
Nuki 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 gboulvin, 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