Pour comprendre ce qu’est Zigbee2MQTT, je vous présente dans ce tutoriel ce que sont Zigbee, MQTT et Zigbee2MQTT. Je vais vous montrer comment installer cela sur un Synology avec Container Manager (Docker).
Nous allons utiliser Mosquitto en tant que courtier (broker) MQTT. Après avoir installé quelques accessoires Zigbee, nous utiliserons ce système pour piloter indépendamment les mêmes accessoires depuis Homebridge (et Apple Maison), la box Homey Pro et Home Assistant !
Ce tutoriel étant assez long, il est découpé en trois parties :
- Partie 1 : Présentation rapide de Zigbee et MQTT, installation de Mosquitto et de Zigbee2MQTT
- Partie 2 : Ajout d’accessoires Zigbee à Zigbee2MQTT et présentation de l’application
- Partie 3 : Utilisation de Zigbee2MQTT dans Homebridge (Maison), Homey Pro et Home Assistant
La vidéo YouTube reprend les 3 parties.
Newsletter Pomme-Kit
Abonnez-vous à la newsletter pour rester informé des dernières actualités HomeKit et Matter ainsi que des nouvelles vidéos de la chaine
Qu’est-ce que Zigbee ?
Zigbee est un protocole largement répandu dans les objets connectés et utilisé par de nombreux fabricants. C’est par exemple le cas des ampoules Philips Hue ou des capteurs de température ou d’ouverture portes et fenêtres Aqara, pour ne citer qu’eux.

Zigbbe crée un réseau maillé (mesh) avec en son centre un contrôleur. Autour de ce dernier, nous allons trouver des routeurs. Ce sont en général des objets alimentés en permanence, tels que les prises électriques connectées. Et tout autour de cet ensemble, nous allons avoir les dispositifs terminaux. En général, il s’agit d’accessoires alimentés par pile ou batterie, par exemple des capteurs de température ou d’ouverture porte/fenêtre.
Qu’est-ce que MQTT ?
MQTT est un protocole de messagerie standard pour l’internet des objets (IoT).
On a au centre de ce système un courtier (broker) qui va servir de point d’échange avec des clients. Les clients peuvent publier des informations concernant un sujet (topic) et s’abonner à des sujets spécifiques.

Par exemple, on aura un client « thermomètre » qui va publier une information de température sur le sujet « Température ». Et nous aurons deux clients qui se sont abonnés à ce sujet, qui recevront l’information à chaque changement de valeur.
Les outils de ce tutoriel
Pour pouvoir réaliser ce tutoriel, nous allons installer plusieurs outils. Pour simplifier, nous allons installer tout cela avec Container Manager sur un NAS Synology. Mais ce sont des outils open source et vous pourrez les installer d’une autre façon si vous le souhaitez.

Pour le courtier, nous allons utiliser Mosquitto, qui est un des plus utilisés. Les clients seront Homebridge, Homey Pro et Home Assistant, auquel nous allons ajouter Zigbee2MQTT.
Et pour faire le lien entre les accessoires Zigbee et Zigbee2MQTT, nous allons utiliser un contrôleur SMLight SLZB06-M. Cet appareil à l’avantage de se connecter notamment en PoE, ce qui sera plus simple à brancher sur le Synology qu’une clé USB.
Enfin, pour tester la solution, notamment la partie MQTT, nous allons installer un client. Dans le cadre de ce tutoriel, j’ai utilisé le logiciel gratuit MQTTx.
Installation de Mosquitto
Installation du conteneur
Nous allons tout d’abord créer un dossier mosquitto dans le dossier docker, puis, dans ce dossier, nous allons créer 3 autres dossiers : config, data et log.

À
allow_anonymous true
listener 1883
listener 9001
protocol websockets
persistence true
#password_file /mosquitto/config/pwfile
persistence_file mosquitto.db
persistence_location /mosquitto/data/
log_type information
log_dest file /mosquitto/log/mosquitto.1dy
Dans cette configuration, on autorise dans un premier temps les accès anonymes et la ligne de déclaration du fichier de mot de passe est en commentaire (#). On enregistre ce fichier sous le nom mosquitto.conf dans le dossier mosquitto/conf/.
Pour pouvoir enregistrer le journal (log), nous allons juste créer un fichier vide à l’aide de l’éditeur de texte, et l’enregistrer sous le nom mosquitto.log dans le dossier mosquitto/log.
On peut maintenant installe l’image docker dans Container Manager. Depuis l’onglet « Registre », on recherche « eclipse-mosquitto » et on télécharge l’image correspondant et on choisit la dernière version (latest).

Lorsque le téléchargement est terminé, on peut aller dans l’onglet « Image », sélectionner l’image eclipse-mosquitto et cliquer sur « Exécuter » ce qui va lancer l’assistant de création du conteneur.

Sur le premier écran, on nomme le conteneur « mosquitto », on coche éventuellement la case « Activer le redémarrage automatique » et on clique sur « Suivant ».


Nous avons alors plusieurs choses à renseigner :
- Paramètres des ports :
- On va ajouter les ports 1883 et 9001 avec les mêmes valeurs dans le conteneur et en TCP
- Paramètres de volumes :
- On sélectionne le dossier /docker/mosquitto/config et l’affecte à /mosquitto/config
- On sélectionne le fichier /docker/mosquitto/config/mosquitto.conf et on l’affecte à /mosquitto.conf
- On sélectionne le fichier /docker/mosquitto/log/mosquitto.log et on l’affecte à /mosquitto/log/mosquitto.log
- Environnement :
- On ajoute la timezone avec la clé TZ et la valeur Europe/Paris (ou celle de votre région)
- Réseau :
- On laisse le réseau en mode bridge
On peut alors cliquer sur « Suivant ». Le résumé est affiché, on peut cliquer sur « Effectué » pour créer le conteneur et le démarrer, si la case « Exécuter ce conteneur lorsque l’assistant a terminé » est cochée.
On peut aller vérifier dans le fichier mosquitto.log que le service est bien démarré.
Test du courtier MQTT Mosquitto
Nous allons pouvoir vérifier que le courtier est bien en service à l’aide du client MQQTx que nous avons installé.
On crée une connexion en indiquant un nom, par exemple « Mosquitto ». Pour le test, on laisse mqtt:// et on indique l’adresse sur NAS. Enfin, on précise le port qui est 1883 par défaut. On peut alors cliquer sur « Connect » et la connexion devrait être établie.

Nous allons maintenant un abonnement, en cliquant sur « New Subscription ». On peut appeler le sujet (topic), par exemple, testtopic/#. En cliquant sur la flèche en bas à droite, cela va envoyer le message prérenseigné dans l’application. Et comme on est abonné au même sujet, on va avoir le message envoyé et le message reçu qui vont s’afficher, ce qui va confirmer que notre courtier MQTT est opérationnel.

Sécurisation du courtier MQTT Mosquitto
On retourne dans Container Manager, on sélectionne le conteneur mosquitto et dans le menu en haut à droite, on sélectionne « Ouvrir le terminal ». Dans la nouvelle fenêtre, on clique sur la flèche à droite de « Créer », puis sur « Lancer avec une commande ». On ajoute la commande ash et on clique sur « Ok ».

La commande ash s’affiche à gauche, on la sélectionne et le terminal devrait afficher une invite / #. On tape cd mosquitto pour se déplacer dans le dossier, on peut vérifier que nouis 3 dossiers config, data et log s’affichent en tapant la commande ls. On tape cd config pour se placer dans ce dossier et exécuter la commande de création d’un utilisateur / mot de passe.
La commande suivante va créer un utilisateur z2m avec un mot de passe crypté. et stocker le résultat dans le fichier pwfile dans le dossier config.
mosquitt_passwd -c pwfile z2m
Après la validation de la commande, il faudra saisir le mot de passe une première fois, puis une seconde fois pour valider. On peut fermer le terminal et aller vérifier que le fichier a bien été créé.

Il est temps de mettre à jour le fichier de configuration mosquitto.conf en désactivant les connexions anonymes et en précisant le fichier de mots de passe. Le fichier final ressemble à celui-ci :
allow_anonymous false
listener 1883
listener 9001
protocol websockets
persistence true
password_file /mosquitto/config/pwfile
persistence_file mosquitto.db
persistence_location /mosquitto/data/
log_type information
log_dest file /mosquitto/log/mosquitto.1dy
On peut redémarrer le conteneur pour prendre en compte le nouveau fichier de configuration. On va vérifier que tout fonctionne correctement en retournant sur MQTTx. Une tentative de connexion affiche un message d’erreur « Not authorized ». On peut aller modifier la connexion en faisant un clic droit sur son nom, puis « Edit » et indiquant le nom et le mot de passe que l’on vient de créer. Cette fois-ci, en cliquant de nouveau sur « Connect » la connexion devrait s’établir de nouveau.
Installation de Zigbee2MQTT
Installation du contrôleur
La première étape consiste à installer un contrôleur Zigbee pour pouvoir ajouter nos accessoires. Pour simplifier les choses, j’ai préféré utiliser un contrôleur Ethernet, ce qui le rend indépendant de la connexion à un serveur.
J’ai utilisé le contrôleur SMLight SLZB-06M, que j’ai installé et connecté en Ethernet sur un switch PoE. Cet appareil nous donne également accès à une interface web pour le configurer ou pour récupérer ses informations. Je vous proposerai ultérieurement un tutoriel sur cet appareil.
Installation du conteneur
Nous allons tout d’abord créer un dossier zigbee2mqtt dans le dossier docker, puis, dans ce dossier, nous allons créer un dossier : data.

On va commencer par créer un fichier de configuration. Pour cela on se rend sur le site Zigbee2MQTT, on clique sur « Get Started » et plus bas dans la page on va trouver un fichier config d’exemple. On le colle dans le presse-papier, puis on ouvre une fenêtre avec l’éditeur de texte du Synology, et on colle le texte.
# Let new devices join our zigbee network
permit_join: true
# Docker Compose makes the MQTT-Server available using "mqtt" hostname
mqtt:
base_topic: zigbee2mqtt
server: mqtt://mqtt
# Zigbee Adapter path
serial:
port: /dev/ttyUSB0
# Enable the Zigbee2MQTT frontend
frontend:
port: 8080
# Let Zigbee2MQTT generate a new network key on first start
advanced:
network_key: GENERATE
Nous allons maintenant l’adapter à notre environnement.
On va commencer par ajouter une ligne pour indiquer que l’on souhaite utiliser l’interface. Pour cela, nous ajoutons une ligne frontend: true.
Ensuite, dans la partie mqtt, nous changeons le nom du serveur puisque nous avons appeler le notre mosquitto. Comme nous avons forcé la connexion avec un identifiant et un mot de passe, on les ajoute également les lignes user: z2m et password: z2m (oui, je n’ai pas été original pour le mot de passe de ce tutoriel).
Il va maintenant falloir préciser les informations sur l’adaptateur. On va donc remplacer les lignes de la partie serial par les valeurs pour le contrôleur SMLight. Dans le navigateur, on se connecte à l’adresse http://slzb-06m.local (qui est normalement l’adresse par défaut du contrôleur). Dans l’interface de gestion, on sélectionne l’onglet « Z2M and ZHA » et copier dans le presse-papier les paramètres proposés, puis les coller dans le fichier de configuration.

Il faut cependant faire quelques modifications. On commence par modifier le port et en remplaçant slzb-06m.local par l’adresse IP du contrôleur (il est conseillé de lui avoir attribué une adresse IP fixe sur le réseau). On peut trouver cette adresse dans l’interface de gestion du contrôleur.
Nous allons également modifier la partie « adapter » qui a pour valeur ezsp qui est dépréciée. Nous la remplaçons par ember, sous réserve de bien avoir mis à jour le firmware du SLZB06 pour ce type d’adaptateur.

Au final, le fichier de configuration devrait ressembler à celui-ci :
# Let new devices join our zigbee network
permit_join: false
frontend: true
# Docker Compose makes the MQTT-Server available using "mqtt" hostname
mqtt:
base_topic: zigbee2mqtt
server: mqtt://mosquitto
user: z2m
password: z2m
# Zigbee Adapter path
serial:
port: tcp://192.168.1.162:6638
baudrate: 115200
adapter: ember
# Disable green led?
disable_led: false
# Set output power to max 20
advanced:
transmit_power: 20
On peut enfin enregistrer notre fichier dans le dossier zigbee2mqtt/data sous le nom configuration.yaml.
Il est temps de passer à l’installation et à la configuration du conteneur Zigbee2MQTT. Dans Container Manager, on va sur l’onglet « Registre » et on recherche « zigbee2mqtt ». L’image koenkk/zigbee2mqtt est proposée. On la sélectionne et on clique sur « Télécharger ». On valide que l’on souhaite la dernière version (latest) pour démarrer le télécjargement.

Dans l’onglet « Image », on sélectionne l’image que l’on vient de télécharger et on clique sur « Exécuter » pour lancer l’assistant.

Sur le premier écran, on nomme le conteneur « zigbee2mqtt », on coche éventuellement la case « Activer le redémarrage automatique » et on clique sur « Suivant ».



Nous avons alors plusieurs choses à renseigner :
- Paramètres des ports :
- On va ajouter le port 8080 avec les mêmes valeurs dans le conteneur et en TCP
- Paramètres de volumes :
- On sélectionne le dossier /docker/zigbee2mqtt/data et l’affecte à /app/data
- Environnement :
- On ajoute la timezone avec la clé TZ et la valeur Europe/Paris (ou celle de votre région)
- Réseau :
- On laisse le réseau en mode bridge
- Liens :
- On ajoute un lien vers le serveur mosquitto on précisant la valeur mosquitto
On peut alors cliquer sur « Suivant ». Le résumé est affiché, on peut cliquer sur « Effectué » pour créer le conteneur et le démarrer, si la case « Exécuter ce conteneur lorsque l’assistant a terminé » est cochée.

On peut vérifier que le service fonctionne correctement à l’aide du client MQQTx. Pour cela, on ajoute un abonnement au sujet zigbee2mqtt et on devrait voir les messages qui ont déjà été échangés sur le sujet.
Nous allons maintenant ajouter quelques accessoires, ce sera le sujet de la seconde partie de ce tutoriel.