Plugin ZigbeeLinker (Jeedom) : Documentation

Introduction

Gérez vos équipements Zigbee dans Jeedom grâce à une connexion avec MQTT et Zigbee2MQTT.

Le plugin vous aide à installer une solution complète pour gérer et intégrer facilement vos équipements compatibles avec l’outil gratuit Zigbee2MQTT. Plusieurs possibilité d’installations. Les équipements sont intégrés avec leurs photos et commandes.
Zigbee2MQTT est disponible gratuitement ici : https://github.com/Koenkk/zigbee2mqtt.io
MQTT est disponible ici : https://mqtt.org/
Mosquitto-PHP est disponible ici : https://mosquitto-php.readthedocs.io/en/latest/overview.html

Installation

Vidéo de présentation

Merci à la chaîne Usine a Gaz Domotique pour cette vidéo de présentation.
Présentation des principales options pour bien démarrer avec le plugin.
Visionnage ici : Le plugin pour Zigbee to mqtt

Installation du plugin et de ses dépendances

Sur le Market Jeedom recherchez « zigbeelinker » :

Lorsque le plugin est installé, allez sur l’écran de configuration du plugin.
Deux options sont obligatoires avant l’installation des dépendances :

  • Dans la liste déroulante, sélectionnez le type d’installation :
  • Si Zigbee2MQTT est installé sur votre box, sélectionnez le type d’adaptateur :

Sauvegardez avec le bouton en face de Configuration (attention à ne pas vous tromper de bouton).

  • Maintenant, lancez l’installation des dépendances :
    Remarque importante : Effectuez l’installation en local et sans passer par le dns de Jeedom par exemple. Le service apache va redémarrer, et votre box risquerait de devenir indisponible temporairement.
  • C’est terminé, vérifiez que le statut du démon est bien sur OK (Laissez lui du temps, cela peut prendre 5mn pour une nouvelle installation) :

Explications sur les options d’installation

Plusieurs options sont possibles :

  • Solution complète locale : Tout pour démarrer sur votre Jeedom.
    L’adaptateur Zigbee est installé sur cette machine, et les équipements seront créés dans votre Jeedom.
  • Zigbee2mqtt + Client MQTT :
    Idem à la solution en dessus, mais le serveur MQTT sera géré par un autre plugin ou par vos soins.
  • Zigbee2mqtt + Serveur MQTT : Mode « Antenne »
    Permet de déporter l’adaptateur Zigbee (Ex : clé usb) sur une autre machine. Sur votre Jeedom principal, vous installez ce plugin avec l’option « Client MQTT » pour intégrer les équipements.
  • Client MQTT : Client seulement
    Zigbee2mqtt + MQTT sont sur une autre machine (pas d’installation sur cette machine). Ici vont remonter les équipements grâce au Client MQTT.
  • Zigbee2mqtt : Seulement Zigbee2mqtt
    Installer Zigbee2mqtt sur cette machine.

Ajout d’un Client MQTT

Pour que les équipements remontent dans votre Jeedom, il faut obligatoirement ajouter un Client MQTT.
Important : Un Client est automatiquement ajouté à votre installation si vous avez sélectionné l’option « Solution complète » ou une autre solution avec MQTT Server.
Dans d’autres cas, Client MQTT seulement par exemple, allez dans Plugins -> Protocole domotique -> ZigbeeLinker, et cliquez sur « Ajouter un client MQTT ».

Renseignez au minimum l’IP de la machine où est hébergé le serveur MQTT (si c’est sur la machine locale, ne renseignez rien, ce sera automatique).

Les équipements

Présentation

Les équipements se créent automatiquement et se gèrent comme tout équipement dans Jeedom.

Remarque : Il faut qu’un équipement se réveille pour remonter dans Jeedom. Pour réveiller une prise, actionnez là. Pour remonter un capteur, cliquez sur le petit bouton de réveil s’il en a un.

Onglet général

On retrouve la partie Général qui contient le nom de l’équipement, l’objet parent et les autres options des équipements Jeedom.

La partie Informations contient les éléments au sujet de l’appareil et un lien vers la documentation sur le site de Zigbee2MQTT.

Onglet Envoi d’ordre

Introduction

Permet d’effectuer une « action » lors du changement de valeur d’une commande info de votre équipement ou à chaque fois (répétition de valeur) si la commande info correspond à un bouton ou interrupteur.

On peut tout imaginer : Un interrupteur qui pilote une ampoule. Un interrupteur qui exécute un scénario. Une ouverture de porte qui déclenche une alerte sms/télégram. L’allumage d’une ampoule qui provoque l’allumage d’autres ampoules.

Nous allons prendre l’exemple d’un interrupteur pour piloter des ampoules. J’ai donc un interrupteur IKEA, et des ampoules lowcost avec variation de luminosité et de température.

Mes ampoules sont dans un groupe « Ampoules séjour » Zigbee2MQTT pour la communication en direct (gain de temps durant les actions)

C’est mon interrupteur qui va piloter mes ampoules : On entre dans l’équipement Interrupteur, onglet « Envoi d’ordre ».

Bouton Ajouter une liaison

Permet d’ajouter une règle de type : « pour tel action, je fais … ».
L’évènement est provoquée par une commande Info de l’équipement dans lequel on est. Cliquez sur le bouton « Ajouter une liaison » en face de la commande Info.

Condition de déclenchement

  • La valeur de la commande : Lors du changement de valeur de la commande de l’équipement, le test sélectionné définit par les deux listes déroulantes va être vérifier. Si le test est vrai, les « Actions à faire » (en dessous) seront lancées.
  • Et (si la condition est vrai) : Vous permet de définir une condition supplémentaire. Exemple d’utilisation : Si je clique sur l’interrupteur (toggle=bouton du milieu) « ET qu’il fait jour », j’allume mes lampes à 100% de luminosité. Puis j’ajoute une nouvelle liaison avec le test « ET il fait nuit », pour allumer mes lampes à 50% de luminosité.
    Le test doit renvoyer 1 (ou vrai) pour que les « Actions à faire » (en dessous) soient lancées.

Actions à faire

  • Pilotage direct par commande Info : Généralement utilisé pour piloter d’autres équipements Zigbee, mais aussi des équipements d’autres plugins.
    Ce pilotage est direct ! On discute de commande à commande, ce qui permet un gain réel en rapidité d’exécution.

    Cliquez sur « Ajouter une commande Info », et sélectionnez la commande Info d’un équipement à piloter.
    Voici quelques exemples :

Toggle : La commande de mon interrupteur est toggle, et je veux envoyer à mon groupe d’ampoules la même commande :

Luminosité : La commande de mon interrupteur est le bouton du haut « augmenter la luminosité », je vais renseigner :

J’ai sélectionné = Autre pour spécifier ma valeur :

((#[Séjour][Ampoules Séjour][Luminosité (Valeur)]#+30>254) ? 254 : #value#+30)

Cette ligne me permet d’augmenter la luminosité par palier de 30 jusqu’à la valeur maximale de 254. Pour diminuer vous allez le bouton du bas « baisser la luminosité » et utiliser :

((#[Séjour][Ampoules Séjour][Luminosité (Valeur)]#-30<10) ? 10 : #value#-30)

Température : Les commandes de mon interrupteur seront les boutons droite et gauche je vais renseigner :

((#[Séjour][Ampoules Séjour][Température couleur (Valeur)]#-50<150) ? 150 : #value#-50)
((#[Séjour][Ampoules Séjour][Température couleur (Valeur)]#+50>370) ? 370 : #value#+50)

Fonctionnement avec les équipements d’autres plugins

Le Toggle pour tous : Si vous avez bien paramétrer les valeurs de types génériques des commandes infos/action ainsi que les liaisons commandes actions -> commande info. Cela fonctionnera. Voici un exemple pour un équipement zwave :
Pour paramétrer les liaisons commandes actions -> commande info, rendez-vous dans le menu commandes de votre équipement :

Pour paramétrer les types génériques, cliquez sur la roue crantée en face de la commande. Il faut le faire pour les 3 commandes :
La commande Info :

La commande Action On :

La commande Action Off :

La luminosité (entres autres) pour tous : Certains plugins vont utiliser des valeurs min et valeur max de 0 à 100 et ZigbeeLinker prend des valeurs de 0 à 254. Ce n’est pas un soucis. Renseignez bien les valeurs min et max dans vos commandes, et le plugin ZigbeeLinker se charge de la conversion ! Voici un exemple dans un autre plugin :

Exemple de bouton On Off avec condition

Ce qui est au dessus ne fonctionne pas ? Ce n’est pas grave, voici un exemple qui permet de faire du Toggle, en deux lignes :

En résumé, lors de l’appuie sur le bouton Toggle, je teste si la lampe est allumée ou non, et en fonction de son état je vais l’éteindre ou l’allumer.

Actions à faire

Permet de lister des actions à faire. Exécuter des commandes action, des scénarios, etc… Si l’on reprend notre exemple précédent, on pourrait directement agir sur les commandes actions :

On fait la même chose que l’exemple plus haut, mais cette fois-ci en passant par les commandes actions. J’ai ajouté un petit message Alexa (par scenario) pour donner un exemple de plus.

Réception d’ordre

Introduction

Permet de piloter un équipement ZigbeeLinker avec un autre équipement ZigbeeLinker, ou un équipement d’un autre plugin. Par exemple piloter une ampoule ZigbeeLinker et avec l’interrupteur d’un autre plugin.

La liaison est directe, et donc vous obtiendrez un gain en rapidité.

Pour l’exemple, je vais utiliser un interrupteur zwave qui me donne des informations dans une commande scene (1001=On, 2001=Off). Avec cet interrupteur je veux piloter mon groupe d’ampoules.

Ajouter une liaison

Ajouter un groupe permettant de créer une règle qui va lier deux états : L’état de la commande du bouton avec l’état de la commande du groupe d’ampoules. Je vais cliquer deux fois sur le bouton Ajouter une liaison, car je vais utiliser deux états du bouton (1001, 2001) :

Délencheur

C’est la commande info à surveiller sur l’interrupteur. On va tester sa valeur et effectuer une action en fonction de sa valeur.

Action à faire sur la commande

C’est la valeur que l’on va donner à la commande de l’équipement ZigbeeLinker (le groupe d’ampoules).

Onglet commandes

Dans l’onglet commandes, nous avons accès aux commandes de l’équipement. Ces commandes sont automatiquement créées lorsque l’équipement est intégré dans Jeedom.

Il est possible d’ajouter d’autres commandes manuellement :

  • Valeur reçue : Si une valeur est reçue par Jeedom (via le Payload MQTT), mais n’est pas créée automatiquement. Il est possible de l’ajouter en spécifiant la clé (le nom) à écouter :
  • Envoyer un ordre : Permet d’envoyer un ordre de type {« clé » : « valeur »} à l’équipement. Par défaut la commande est /set, mais il est possible de la personnaliser.
  • Envoyer un ordre par payload : La même chose qu’au dessus mais cette option permet d’ajouter un ordre au format Payload.

Equipements en erreur

Si un équipement est souligné en rouge, c’est qu’il n’est pas intégré complètement. Cliquez sur l’équipement souligné en rouge.
Un carré rouge apparaît en haut de l’équipement :

Copiez le message avec le bouton « Copier le message », puis cliquez sur « Envoyer les informations … ».
Vous allez êtres redirigé vers Community de Jeedom.
Cliquez sur « Message direct » pour envoyer le message au Développeur.

Lorsque le développeur vous dira que l’équipement est corrigé. Attendez la prochaine mise à jour (et lancez là), puis retournez sur le plugin pour lancer une Synchronisation :

Il est aussi possible de synchroniser qu’un seul équipement, pour cela entrez dans l’équipement et cliquez sur Synchroniser en haut à droite :

Les groupes

Groupes Zigbee2MQTT

Zigbee2MQTT permet de créer des groupes. Cette option est intéressante, car native.
Pour créer un groupe, allez dans l’interface Zigbee2MQTT, cliquez sur l’onglet Groups, et remplissez la première ligne :

Entrez un nom de groupe (il est modifiable par la suite). Il n’est pas nécessaire de renseigner un id de groupe (il sera automatiquement générer). Pour terminer cliquez sur Create group.

Votre groupe apparaîtra en bas, vous pouvez y ajouter vos équipements :

Cliquez sur Select device, puis sur Add to group.

Les groupes Zigbee2MQTT sont automatiquement synchronisés dans ZigbeeLinker :

L’onglet Commandes sera aussi automatiquement renseigné :

Les groupes sont en lecture seulement dans ZigbeeLinker. Toute modification est à faire directement dans Zigbee2MQTT.

Groupes ZigbeeLinker

Pour ajouter un groupe, cliquez sur

Dans un groupe ZigbeeLinker, est vous pouvez ajouter des équipements d’autres plugins (il faut quand même au minimum un équipement ZigbeeLinker).

Un exemple, dans mon séjour, j’ai mes ampoules du groupe Zigbee2MQTT créé juste au dessus, mais j’ai aussi une ampoule LIFX. Voici la configuration du groupe :

Cela fonctionnera, car mon ampoule LIFX est bien paramétrée (voir le paramétrage des commandes à respecter).

L’onglet des commandes sera automatiquement complété :

La force de ce type de groupe est qu’il exécute les commandes en direct (comme pour les groupes Zigbee2MQTT), ce qui permet d’avoir une rapidité d’exécution sans égal.

ZigbeeLinker + MQTT Manager

Récupérer les informations d’identification MQTT Manager

Allez dans la configuration du plugin MQTT Manager

Dans la partie Authentification, vous y trouverez le nom d’utilisateur et le mot de passe sur la même ligne, et séparé par « : ». Ceux sont des informations que nous allons donner à ZigbeeLinker.

Configurer ZigbeeLinker

Allez dans la configuration du plugin ZigbeeLinker.
Dans la partie Installation, mettre l’option sans « Serveur MQTT » (car il sera géré par MQTT Manager)

Dans la partie Zigbee2MQTT <-> Serveur MQTT, cochez Sécuriser la connexion et reportez le nom d’utilisateur et le mot de passe récupéré de MQTT Manager.

Configuration du client MQTT de ZigbeeLinker

Allez dans le menu Jeedom Plugins -> Protocole domotique -> ZigbeeLinker, et cliquez sur votre Client MQTT, exemple :

Dans la partie Client MQTT, cochez sécuriser la connexion, et reportez le nom d’utilisateur et mot de passe récupérés de MQTT Manager :

Redémarrer le démon ZigbeeLinker

Il ne reste plus qu’a retourner dans la configuration du plugin ZigbeeLinker et à redémarrer le Démon :

FAQ

La FAQ répertorie un grand nombre de tests à faire en cas de disfonctionnement du plugin ZigbeeLinker. Ne tardez pas à la consulter !

Consultez la FAQ ici