Aller au contenu principal

Intégration domotique 2N IP Intercom, gratuite et open source

Intégration 2N IP Intercom pour Gladys Assistant

Interphones 2N IP, en local par HTTPS : sonnette, relais de porte, entrées, accès.

Intégration externe de Gladys Assistant (5.1.0 ou plus récent) pour les interphones et unités d'accès 2N IP (Verso, Force, Safety, Solo, Style, Base, Access Unit…) de votre réseau local, par leur API HTTP officielle en HTTPS, sans aucun cloud. Non officielle, sans lien avec 2N. Jamais testé avec un vrai appareil : elle est écrite d'après le manuel « 2N IP HTTP API » (version 3.3, firmware 2.50) et testée sur un interphone simulé. Vos retours sont bienvenus.

Ce que vous obtenez​

Pour chaque interphone :

  • Sonnette (lecture seule) : 1 tant qu'un visiteur sonne (l'interphone lance un appel sortant), 0 sinon ;
  • Relais n (état) (lecture seule), pour chaque relais (« switch » 1 à 4) activé dans l'interphone : 0 activé (gâche ouverte), 1 au repos ;
  • Activer le relais n : un bouton, désactivé par défaut (voir plus bas) ;
  • Entrée … (lecture seule) : l'état de chaque entrée numérique (contact de porte, bouton de sortie…) ;
  • des déclencheurs de scène : « Sonnette 2N » (une fois par appel), « Relais 2N activé » (avec le numéro et l'origine dite par l'interphone : auth, ap, dtmf, automation…), « Accès 2N accordé » et « Accès 2N refusé » (avec le nom de l'utilisateur de l'annuaire, le sens entry ou exit, et le motif du refus).

Les codes saisis, les numéros de badge et les identifiants d'utilisateur ne sont jamais publiés ni gardés.

Préparer l'interphone​

  1. Dans la page web de l'interphone, Services > API HTTP : activez les services Système, Commutateur (Switch), E/S (I/O), Téléphone/Appel et Journal (Logging), chacun en HTTPS avec l'authentification Digest (le réglage conseillé par 2N).
  2. Sur le même onglet, créez un compte (5 au plus) pour Gladys, avec les droits : surveillance et contrôle des commutateurs, surveillance des E/S, surveillance des appels, et, pour les accès, la surveillance des badges/UID. Un droit absent n'est pas une erreur : la partie correspondante est simplement « non autorisée » dans le statut, le reste fonctionne.
  3. Donnez à l'interphone une adresse IP fixe dans votre box.

Configurer l'intégration​

  • Adresses des interphones : leurs adresses IP séparées par des virgules (8 au plus), avec :port si le port HTTPS n'est pas 443.
  • Authentification, utilisateur, mot de passe : ceux du compte créé ci-dessus (le même sur tous les interphones). Le mot de passe est gardé par Gladys dans sa base, jamais réaffiché, et envoyé seulement aux interphones listés, une fois leur certificat approuvé ; avec Digest, seule une preuve en circule.
  • Intervalle de lecture (5 à 300 s, 10 par défaut) : la relecture des relais, des entrées et des appels. Les événements arrivent, eux, tout de suite (canal d'événements de l'interphone).

Approuver le certificat (obligatoire)​

L'interphone présente un certificat à lui, qu'aucune autorité ne garantit. Rien n'est envoyé à un interphone tant que son certificat n'est pas approuvé : le statut montre alors l'empreinte SHA-256 vue. Pour l'approuver :

  • cliquez sur Approuver les certificats : l'intégration lit le certificat de chaque interphone non encore approuvé et affiche son empreinte (rien d'autre n'est envoyé) ; comparez-la à celle que montre votre navigateur sur la page web de l'interphone (cadenas, certificat, empreinte SHA-256) ; puis cliquez à nouveau dans les 2 minutes : chaque interphone qui présente encore la même empreinte est approuvé, et l'approbation est gardée dans /data (si /data ne peut pas être écrit, rien n'est approuvé) ;
  • ou collez les empreintes dans le champ Empreintes des certificats, séparées par des virgules.

Si un interphone présente plus tard un autre certificat, rien ne lui est envoyé (ni mot de passe, ni commande), le statut affiche l'empreinte vue, et l'intégration ne l'apprend jamais d'elle-même : approuvez-le à nouveau (deux clics) s'il a été remplacé volontairement (nouveau certificat, remise à zéro).

Activer un relais (ouvrir une porte)​

Toute personne pouvant piloter les appareils dans Gladys (tableau de bord, scènes, application) peut ouvrir les portes une fois l'option Autoriser l'activation des relais depuis Gladys cochée : ne la cochez que si votre Gladys est bien protégé.

  • L'activation est un bouton, jamais un interrupteur : un « tout éteindre » n'ouvre jamais une porte.
  • Juste avant chaque activation, l'intégration relit l'identité de l'interphone (son numéro de série doit être celui de l'appareil du bouton) et les réglages du relais, puis vérifie l'option une dernière fois avant d'envoyer.
  • Seuls les relais monostables sont activés, et seulement si leur durée d'activation (réglée dans l'interphone) est de 60 s au plus : le relais se coupe de lui-même après cette durée, quoi qu'il arrive à Gladys. Il n'y a donc pas de commande « fermer ».
  • Une activation n'est jamais renvoyée par l'intégration, ni après un redémarrage.
  • La réponse indique : « confirmé » (le relais est relu activé, ou l'interphone signale l'activation par l'API), « accepté, pas encore relu », « envoyée, sans réponse (peut-être activé) », « refusée par l'interphone » (relais verrouillé ou désactivé), ou « rien envoyé » avec la raison.

Une activation est refusée, sans rien envoyer, quand : l'option est décochée ; le certificat n'est pas approuvé ou a changé ; les identifiants ont été refusés ; l'interphone n'a pas encore été lu, est injoignable ou ne répond pas à temps ; un autre interphone répond à l'adresse ; le relais est absent, désactivé, bistable, de mode ou de durée illisible, ou activé plus de 60 s ; le compte n'a pas le droit de contrôle des relais ; plus de 4 commandes attendent déjà ; l'intégration s'arrête ou est reconfigurée ; le délai de 3,3 s est dépassé avant l'envoi.

Le déclencheur « Relais 2N activé » ignore l'activation faite par Gladys elle-même (une scène qui ouvrirait la porte sur ce déclencheur ne boucle pas).

Bon à savoir​

  • Identifiants refusés (401 sur la lecture de l'identité, confirmé par une seconde lecture faite seule) : l'interphone n'est plus sollicité, même après un redémarrage, tant que vous ne changez pas les identifiants, n'enregistrez pas la configuration ou ne cliquez pas sur Tester la connexion. Un refus sur une autre fonction (droit absent) n'est pas un refus d'identifiants : cette fonction est redemandée après 1 min, puis en doublant jusqu'à 1 h.
  • Un mauvais mot de passe est essayé 2 fois (une preuve Digest, ou l'en-tête Basic, par lecture de l'identité) avant d'être retenu, 3 fois au plus si le mot de passe change sur l'interphone pendant que l'intégration tourne ; ensuite, plus aucun essai automatique. Chaque clic sur Tester la connexion coûte de nouveau 2 essais (un clic toutes les 5 s au plus). La documentation 2N cite un événement LoginBlocked après 3 essais ratés sur l'interface web ; elle ne dit pas si les échecs de l'API comptent aussi. Si l'interphone bloque l'adresse de Gladys, attendez la fin du blocage avant de tester de nouveaux identifiants.
  • Avec Digest, une seule demande à la fois répond à un nouveau défi de l'interphone ; les autres attendent sa réponse, au plus 0,5 s après son envoi (3,5 s si la connexion à l'interphone tarde), même quand c'est une lecture du canal d'événements que l'interphone garde ouverte jusqu'à 20 s.
  • Une ouverture n'est « confirmée » que si l'état du relais a pu être lu juste avant elle. Au-delà d'environ 650 ms par réponse de l'interphone, cette lecture est sautée pour laisser le temps à l'ouverture : elle part quand même, mais n'est qu'« acceptée ».
  • Le canal d'événements est réouvert après une coupure ; les événements survenus pendant la coupure sont perdus, et une lecture du canal arrivée après un long silence (plus de 90 s) est ignorée pour ne pas publier d'anciens événements. Les états sont corrigés par la lecture suivante.
  • /data ne garde que les certificats approuvés (leur empreinte, une valeur publique) et une marque de 8 bits des identifiants refusés, jamais un mot de passe.

Pour aller plus loin​

Code et suivi : https://github.com/LM1LC3N7/gladys-2n-intercom. Manuel de l'API : https://wiki.2n.com/hip/hapi/latest/en.

Paramètres de configuration​

Voici les paramètres demandés par 2N IP Intercom dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Vos interphones 2NsectionNonPour les interphones et unités d'accès 2N IP (Verso, Force, Safety, Solo, Style, Base, Access Unit…) de votre réseau, par leur API HTTP officielle en HTTPS, sans cloud : une sonnette, l'état des relais (gâches) et des entrées, un bouton d'activation par relais (désactivé par défaut), et des déclencheurs de scène (sonnette, relais activé, accès accordé ou refusé). Créez d'abord un compte API HTTP dans la page web de chaque interphone (voir le guide). Jamais testé avec un vrai appareil. Non officiel, sans lien avec 2N.
Adresses des interphonesstringOuiL'adresse IP de chaque interphone, séparées par des virgules (8 au plus), avec « :port » si son port HTTPS n'est pas 443. Donnez à chaque interphone une adresse fixe dans votre box.
Authentification de l'API HTTPselectNonComme réglée pour les services dans la page Services > API HTTP des interphones. Digest (le réglage d'usine) n'envoie jamais le mot de passe ; Basic l'envoie dans la connexion HTTPS ; Aucune n'envoie rien.
Utilisateur du compte API HTTPstringNonLe même sur tous les interphones listés ci-dessus.
Mot de passe du compte API HTTPsecretNonGardé par Gladys dans sa base, jamais réaffiché, envoyé seulement aux interphones listés ci-dessus, et seulement une fois leur certificat approuvé (avec Digest, seule une preuve en circule). Un interphone qui le refuse n'est plus sollicité tant que vous ne le changez pas ou ne cliquez pas sur « Tester la connexion ».
Empreintes des certificats (facultatif)stringNonLes interphones présentent un certificat à eux, qu'aucune autorité ne garantit : rien n'est envoyé à un interphone avant que son certificat soit approuvé. Cliquez deux fois sur « Approuver les certificats » (le premier clic montre ce que présente chaque interphone), ou collez ici l'empreinte SHA-256 de chaque certificat, séparées par des virgules.
Intervalle de lecture (secondes)numberNonTous les combien les relais, les entrées et les appels sont relus (5 à 300). Les événements (sonnette, relais, entrées, accès) arrivent tout de suite quand le compte a le droit de les lire.
Activation des relais (portes)sectionNonToute personne pouvant piloter les appareils dans Gladys (tableau de bord, scènes, application Gladys) peut ouvrir les portes une fois cette option cochée : ne l'autorisez que si votre Gladys est bien protégé. Une activation est un bouton, jamais un interrupteur : un « tout éteindre » n'ouvre jamais une porte. Seuls les relais monostables sont activés (ils se coupent d'eux-mêmes après leur durée, 60 s au plus) ; l'intégration ne la renvoie jamais, ni après un redémarrage. Chaque activation est écrite dans les journaux de l'intégration, jamais le mot de passe.
Autoriser l'activation des relais depuis GladysbooleanNonUne fois cochée, tout utilisateur de Gladys, toute scène et l'application mobile Gladys peuvent activer les relais de porte.
Langue des nomsselectNonSert aux noms des appareils et fonctionnalités ajoutés désormais.

Comment installer 2N IP Intercom dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : 2N IP Intercom 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/lm1lc3n7/gladys-2n-intercom:0.1.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/LM1LC3N7/gladys-2n-intercom.

2N IP Intercom 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​

2N IP Intercom 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 LM1LC3N7, 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 🙂