Tuto Modifier une association via un scénario

Pour faire suite à mon article sur l’application de paramètres via des scénarios, je vais ici vous montrer comment on peut aussi gérer des associations directes via des scénarios.

Les cas d’utilisation seront moins fréquents, mais je trouve tout de même intéressant de vous le faire partager.

Le plugin ZWave met à disposition un serveur REST avec une API afin d’interagir avec le moteur openzwave.

Un serveur REST, pour rester simple est un serveur WEB sur lequel nous pouvons faire des actions ou récupérer des états en exécutant des requêtes via des routes définies. Je ne vais pas trop vous embrouiller avec les détails, je prévois un article complet sur le sujet selon l’intérêt porté, n’hésitez pas à vous manifester dans les commentaires.

Nous allons donc exploiter des routes du serveur REST ZWave pour gérer nos associations comme le fait en réalité le UI via l’onglet Associations, mais ces actions pourront être lancées par d’autres scénarios selon des conditions que vous aurez définies.

Prérequis

Alors il faut déjà bien être familiarisé avec les associations directes. Vous pouvez faire un petit rappel de vaccin en consultant l’article sur le sujet.

Il faut aussi avoir des connaissances minimum sur la programmation de script avec jeedom. Nous ne pourrons pas nous baser sur des ajouts de commandes via l’équipement cette fois.

On peut considérer ce tutoriel pour les utilisateurs plus avancés.

Mise en place

Depuis la version 3.0, jeedom a renforcé le niveau de sécurité afin que chaque plugin ait sa propre clé API afin de discuter avec le demon du plugin. Il vous faudra donc récupérer cette clé via l’écran d’administration de jeedom.

Nous allons laisser de côté, le qui et comment seront déclenchés les scénarios pour se concentrer que sur le contenu.

Ajouter une association directe

On va donc créer un nouveau scénario, en mode avancé avec comme nom AddAssociation.

J’aime bien trier mes scénarios par groupe, je vais donc lui associer un groupe pour le retrouver plus facilement.

Le scénario sera vraiment simple, on ajoute  seulement un bloc Code. L’idée ici est que ce scénario soit éventuellement déclenché par un Mode, un autre Scénario ou un Calendrier. Libre à vous d’ajouter des conditions mais ce n’est pas le but de ce tutoriel.

Maintenant le vif du sujet, la syntaxe de l’url pour discuter avec notre serveur REST.

Il n’y a pas de documentation de l’API, c’est malheureux mais c’est faute de temps.

Une façon simple de connaître l’url avec la bonne syntaxe est simplement de lancer le daemon avec le niveau de log en Info.

Lorsqu’on lance une action via l’onglet Actions une trace de la route exécutée est alors affichée dans le log openzwave.

Exemple pour le noeud 180 je souhaite ajouter au groupe 2 le noeud Id 196

Votre serveur REST tourne par défaut à cette adresse:

http://127.0.0.1:8083/

Cette partie n’est pas directement remontée dans les traces.

Je vais vous donner l’ensemble du code, il n’y a que 2 lignes… J’ai bien averti que c’est du niveau avancé.

$url = ‘http://127.0.0.1:8083/node?node_id=180&type=association&action=add&group=2&target_id=196&apikey=votreCleApi’;
file_get_contents($url);

Dans la première ligne on construit l’url, elle est constituée de l’adresse du serveur REST ZWave, puis de la route récupérée via la trace Info dans la vue log, enfin une partie.

Il faudra remplacer le node_id sur lequel on souhaite ajouter une association, spécifier le numéro du groupe d’association, l’id du nœud destination et votre clé API spécifique au plugin ZWave.

On retrouve notre nœud source, avec l’ID 180 le groupe no 2 et l’Id du nœud destination 196, c’est ce que vous devrez adapter selon votre besoin.

La deuxième l’exécute, nous n’analyserons pas le contenu du retour.

On sauvegarde, puis on exécute le scénario afin de valider le bon fonctionnement.

Pour un module secteur c’est quasi instantané, pour un module sur pile il faudra attendre le prochain réveil, pour que le changement soit appliqué.

A noter que sur un module sur piles nous pourrons voir dans l’onglet association qu’un changement est en attente.

Il sera possible de doubler les 2 lignes de code ou de faire des nouveaux blocs Code pour gérer plusieurs associations avec le même scénario.

Ajouter une association directe sur une instance spécifique

Pour certains modules comme un double relais on souhaite spécifier quelle instance de destination sera déclenchée via une association.  Il faudra préalablement que le module source, supporte les associations multi-instances.

Pour gérer l’ajout d’une association directe pour une instance spécifique on créé un nouveau scénario, cette fois avec le nom AddAssociationInstance.

Je passe directement à la route, qui est pratiquement la même mais l’argument de l’instance_id en plus.

$url = ‘http://127.0.0.1:8083/node?node_id=180&type=association&action=add&group=2&target_id=196&instance_id=2&apikey=votreCleApi’;
$contents = file_get_contents($url);

Ce n’est pas plus compliqué que ça.

On sauvegarde et exécute pour valider le bon fonctionnement.

Supprimer une association directe

Passons au pendant inverse, la suppression d’une association, si l’on souhaite l’ajouter dynamiquement il nous faudra la contre mesure.

Création d’un nouveau scénario, avec pour nom RemoveAssociation.

Toujours très proche de notre première URL, mais cette fois avec une action en remove au lieu de add:

$url = ‘http://127.0.0.1:8083/node?node_id=180&type=association&action=remove&group=2&target_id=196&apikey=votreCleApi’;
file_get_contents($url);

L’association sera supprimée suite à l’exécution ou au prochain réveil s’il s’agit de module sur piles.

Supprimer une association directe avec une instance spécifique

Le dernier cas pour fermer la boucle, une suppression d’association directe pour une instance spécifique.

Créé de notre dernier scénario, avec le nom RemoveAssociationInstance

$url = ‘http://127.0.0.1:8083/node?node_id=180&type=association&action=remove&group=2&target_id=196&instance_id=2&apikey=votreCleApi’;
file_get_contents($url);

Sans grande surprise c’est une action remove avec en plus l’argument de l’instance_id afin d’identifier sur quelle instance du module on veut agir.

Où utiliser cette approche

Les associations directes sont exécutées quasi instantanément, en comparaison à un événement qui doit arriver sur ??? au contrôleur zwave, remonter à jeedom, être interprété dans un scénario pour enfin lancer une commande à un module. Rien de plus pénible qu’attendre 2 secondes qu’une lumière s’allume lorsqu’on rentre dans une pièce. D’où la raison de choisir une association directe en lieu et place d’un scénario d’allumage sur changement d’état, d’autant plus que les modules auront en général une notion interne de maintien à On sur une durée paramétrable, donc pas de timeout à gérer dans jeedom non plus et moins de ressource consommée coté jeedom.

La faiblesse des associations directes est qu’on ne peut pas ajouter de logique externe pour ne pas faire d’association dans des moments donnés. En utilisant l’approche décrite ici vous pouvez ajouter des associations directes en fin de journée pour les retirer le matin. Il faudra encore tenir compte d’un temps d’application des changements si les déclencheurs d’associations sont des modules sur piles.

Donc si on souhaite qu’une lumière s’allume via une association directe mais dans une certaine plage horaire ou que certain jour de la semaine, il vous suffira de lancer le scénario d’ajout d’association quelques heures avant à l’aide un bloc A. Et toujours avec un autre bloc A à la fin de la période pour lancer la suppression de cette même association.

Chez moi j’ai des anciens capteurs de mouvements EzMotion qui sont alimentés sur secteur, donc en écoute permanente, les ajouts et suppressions d’associations sont donc instantanés, c’est vraiment pratique. Les capteurs 4in1 et 6in1 de chez Aeotec peuvent aussi être utilisés sur secteur.

Conclusion

Ce tutorial n’est pas là pour révolutionner votre domotique, mais cette utilisation dérivée des associations est tout de même très intéressante à mettre en place.

Elle pourrait vous éviter des remarques comme « pourquoi cette lumière s’allume en plein jour? » des bons points pour vous!

Bonne suite et n’hésitez pas à donner des commentaires sur ce sujet et pensez utiliser le formulaire si vous avez des vœux de sujets à me demander.