Zigbee2MQTT et Raspberry Pi 4 : Comment installer la passerelle Zigbee 3.0 DIY avec CC2531 ?

Je vous propose un nouveau guide domotique Do It Yourself basé autour de 3 éléments incontournables en domotique en 2021. Il s’agit du Raspberry Pi, qui sait vraiment tout faire. Le Zigbee, qui est sans conteste le protocole de l’année pour la maison connectée. Et enfin, MQTT qui n’est pas nouveau, mais qui se démocratise auprès du grand public. 3 ingrédients qui constituent une recette savoureuse pour la maison connectée avec la box domotique Zigbee2MQTT.

Zigbee2MQTT, c’est quoi ?

Zigbee2MQTT, c’est un concept vraiment très intéressant. Il s’agit d’un serveur passerelle pour votre protocole Zigbee. En d’autres termes, un serveur Zigbee2MQTT va collecter les données de vos périphériques à l’aide d’un sniffer Zigbee. Ce dernier va ensuite publier et lire, les différents états et actions dans des topics MQTT. Enfin, ces topics pourront ensuite être consultés et/ou modifiés depuis n’importe quel système domotique. Et c’est vraiment là que le concept Zigbee2MQTT prend tout son sens !

Que vous soyez dans une installation hybride entre Jeedom et Home Assistant par exemple, que vous vous essayez à plusieurs systèmes ou simplement que vous désirez fiabiliser votre moteur domotique. Zigbee2MQTT est fait pour vous. Vous aurez de façon synchrone la mise à jour des états dans tous les systèmes au même moment et pourrez également agir sur les périphériques depuis n’importe quel système.

Quel matériel pour assembler une passerelle Zigbee2MQTT

Le projet Zigbee2Mqtt est basé sur un sniffer Zigbee qui s’appuie sur une puce CC2531 de Texas Instrument. Ce dongle Zigbee dispose d’une antenne externe qui lui confère une grande portée, mais surtout, il est constitué de composants très économiques. C’est pourquoi la version prête à brancher ne coûte que 19€.

On peut également imaginer se procurer les composants en Chine à moindre coût pour les assembler. Si vous faites ce second choix, il faudra toutefois disposer du matériel nécessaire pour effectuer le flash et la programmation des composants. Un peu plus technique et au tarif du dongle “ready to use” je vous encourage à faire comme moi. Vous économisez ainsi le matériel requis pour flasher le CC2530 ou CC2531 ainsi que le temps nécessaire pour effectuer cette tâche.

Voyez Zigbee2MQTT comme un super hub pour vos différents périphériques Zigbee quelqu’en soit la marque. Finalement la passerelle Zigbee2MQTT remplace toutes les passerelles Zigbee en un seul et même point. Le projet permet donc de s’affranchir des ponts HUE, Osram, Ikea, Aqara, etc et surtout s’appuyer sur la puissance de MQTT.

Qu’est-ce que MQTT ?

Nous avons un guide complet pour démystifier MQTT et proposer un guide simple pour installer votre broker MQTT à la maison. Je vous invite donc à consulter ce guide si vous ne connaissez pas encore MQTT.

---

Le projet est donc libre et s’appuie sur du matériel à bas coût. Un dongle Zigbee ne coûte que quelques euros, et si pour ce guide je vous explique comment faire avec un Raspberry Pi 4, sachez qu’une version inférieure est amplement suffisante étant donné la faible consommation en performance de la passerelle. Un Raspberry Pi 3 ou de première génération, voire même même un Pi zéro W pourrait faire l’affaire. Ce qui propose un tarif très bas pour assembler ce projet.

Comment installer et mettre en service la passerelle Zigbee2MQTT DIY

1 Pour commencer, il faut installer Raspberry Pi OS Lite sur le Raspberry Pi. Pour ce faire, je vous invite à consulter notre guide pas à pas.

---

2 Insérez le dongle Zigbee CC2531 dans un port USB du Raspberry Pi avant de le démarrer.

3 Démarrez le Raspberry Pi et patientez quelques secondes que le système opère son premier boot.

4 Identifiez l’adresse Ip du raspberry pi sur votre réseau. Si vous avez utilisé les options avancées de Rapberry pi OS Imager, vous avez renommé votre rpi donc vous le trouverez très simplement. Sinon, vous pouvez toujours utiliser notre méthode d’audit rapide du réseau local pour trouver l’adresse IP.

5 A ce stade, je vous recommande de fixer cette adresse dans votre routeur. Cela vous évitera un changement une fois le bail expiré et une perte de votre serveur Zigbee2mqtt.

6 Maintenant, tout est prêt, lancez une connexion et vérifiez le port du dongle Zigbee CC2531 avec la commande ci-dessous.

ls -l /dev/ttyACM0

Si tout est OK, vous recevez le message suivant dans le terminal.

Installation de Node.js

1 À présent, passons à l’installation de Node.js. Pour ce faire, lancez la commande ci-dessous.

sudo curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -

Patientez le temps du téléchargement.

2 Lancez ensuite l’installation des fichiers précédemment téléchargés avec la commande suivante.

sudo apt-get install -y nodejs git make g++ gcc

L’installation déroule et vous voyez un écran similaire à celui-ci.

Vérification de node.js et npm

D’après les écrans précédents, tout doit être OK, mais il convient toutefois de s’en assurer avant de continuer. Pour ce faire, exécuter les deux commandes suivantes.

node --version
npm --version

Vous obtenez les versions de node et npm. c’est parfait, Node.js est correctement installé sur le Raspberry Pi.

Installation de Zigbee2MQTT

1 Maintenant que nous avons nos prérequis installés, passons à l’installation de Zigbee2Mqtt. Pour ce faire, commencez par lancer le clone du repository sur le Raspberry Pi depuis Github.

sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

Patientez le temps du clone.

sudo chown -R pi:pi /opt/zigbee2mqtt

2 Placez-vous à present dans le répertoire zigbee2mqtt

cd /opt/zigbee2mqtt

3 Il faut ensuite lancer l’installation des dépendances avec les deux commandes suivantes.

npm ci --production

Tout s’est bien passé si en fin de procédure, vous avez un message avec un nombre de packages approchant la valeur de 350 packages (ce chiffre peut varier mais doit toujours être assez proche).

Notez que la procédure affiche des erreurs mais ces dernières peuvent être ignorées, elles sont considérées comme “normales”.

Configuration de Zigbee2MQTT

1 Pour cela les habitués de Home Assistant vont retrouver un grand classique, il s’agit du fichier configuration.yaml. Editez ce dernier avec la commande suivante :

nano /opt/zigbee2mqtt/data/configuration.yaml

2 Insérez l’adresse Ip de votre serveur MQTT puis enregistrez via CTRL X.

Notez qu’il est tout à fait possible d’installer le rôle MQTT sur le même serveur (raspberry pi). Dans ce cas, il faudra simplement indiquer localhost en lieu et place de l’adresse IP.

Démarrer Zigbee2MQTT

Zigbee2MQTT est à présent prêt à démarrer. Pour faire cela, placez-vous dans son répertoire et lancez-le avec start.

cd /opt/zigbee2mqtt
npm start

Appairage d’un périphérique Zigbee

1 Passez la ligne permit_join: à true et lancez l’interpréteur npm. Plus simplement, il faut rejouer l’étape 2 de la configuration pour éditer le fichier configuration.yaml et démarrer à nouveau le process avec la commande précédente une fois le permint join actif.

2 Votre passerelle est en mode écoute à présent, lancez la séquence d’appairage sur le device Zigbee. Vous verrez passer plusieurs lignes dans l’interpréteur pour vous indiquer ce qu’il se passe. Voici le détail:

Découverte du périphérique :

 2021-03-24 13:44:27: Successfully interviewed '0x5c0272fffe2c6029', device has successfully been paired

Audit et infos du périphérique :

 2021-03-24 13:44:27: Device '0x5c0272fffe2c6029' is supported, identified as: Lidl Silvercrest smart plug (EU, CH, FR, BS, DK) (HG06337)

Configuration en cours :

 2021-03-24 13:44:27: Configuring '0x5c0272fffe2c6029'

Publication du topic MQTT :

 2021-03-24 13:44:27: MQTT publish: topic 'zigbee2mqtt/bridge/log', payload '{"message":"interview_successful","meta":{"description":"Silvercrest smart plug (EU, CH, FR, BS, DK)","friendly_name":"0x5c0272fffe2c6029","model":"HG06337","supported":true,"vendor":"Lidl"},"type":"pairing"}'

Confirmation :

 2021-03-24 13:44:27: Successfully configured '0x5c0272fffe2c6029'

3 Vous pouvez quitter l’interpréteur et ouvrir à nouveau le fichier de configuration, vous verrez des nouvelles lignes “devices” avec l’adresse du péripheriques. A cette étape, je vous conseille d’éditer la ligne friendly_name: qui prend automatiquement l’adresse Zigbee du périphérique comme valeur. Moins pratique pour savoir de quel périphérique il s’agit. Donnez alors une description et si possible évitez les espaces pour ne pas perturber les topics MQTT par la suite.

Comment ajouter simplement Zigbee2Mqtt à Home Assistant?

Avant de demarrer la configuration côté Home Assistant, il est necessaire de passer le parametre homeassistant: false à true dans le fichier de configuration de Zigbee2MQTT.

homeassistant: true

1 L’implémentation de Zigbee2mqtt à HA est on ne peut plus simple. Vous n’avez qu’à simplement indiquer l’adresse de votre bloker MQTT et passer le mode découverte à true. Pour ce faire, ajoutez les lignes suivantes à votre fichier configuration.yaml.

mqtt:
  discovery: true
  broker: 192.168.1.137

2 Comme à chaque modification du fichier de configuration de Home Assistant, il faut redémarrer HA

3 Il suffit ensuite de se rendre dans outil de développement et recherchez votre device Zigbee. Magie, il est à présent sous Home Assistant ! Sans aucune action supplémentaire! Merci le mode découverte.

4 Pour l’ajouter au tableau de bord Lovelace, rien de plus simple, créez simplement une nouvelle carte. Ici, il s’agit d’une prise Lidl, je fais donc le choix d’un bouton.

5 Je configure mon bouton puis enregistre.

6 Et c’est terminé. Si je clique sur mon bouton. J’ai un retour d’état et surtout ma prise s’enclenche ou se coupe instantanément, comme si le protocole Zigbee était géré directement depuis HA.

7 Si vous avez toujours l’interpréteur de zigbee2mqtt sous les yeux, vous voyez les trames passer au fil de vos actions.

L’ajout des devices Zigbee2mqtt à Jeedom

Je vous le disais en intro, le projet zigbee2mqtt a pour avantage d’être multiplateformes. Par conséquent, il est à la fois possible de lire et piloter vos devices Zigbee à la fois sous Home Assistant et Jeedom en même temps. Pratique, si vous avez un peu de tout chez vous !

1 Côté Jeedom, je vous recommande d’utiliser le plugin jMQTT. Pour intégrer vos péripheriques Zigbee pilotés par Zigbee2Mqtt à Jeedom, ouvrez le plugin et lancez le mode inclusion.

2 Très rapidement, la découverte ne tarde pas à créer les périphériques.

3 Un nouveau device Zigbee2Mqtt est alors créé dans Jeedom. Ce device regroupe tout les péripheriques connus par le serveur zigbee2mqtt.

4 Il faudra donc, pour une gestion plus pratique, créer un nouvel équipement jMQTT et copier/coller les valeurs remontées automatiquement dans de nouvelles commandes. Par exemple ici, il s’agit d’une prise, j’ai donc 2 états ON et OFF.

Configurer le démarrage automatique du deamon Zigbee2mqtt sur le Raspberry pi

1 On crée un nouveau fichier de configuration qui va nous servir à démarrer Zigbee2Mqtt au boot du Raspberry Pi comme un service.

sudo nano /etc/systemd/system/zigbee2mqtt.service

2 On colle les lignes de configuration ci-dessous dans le fichier :

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

3 Et on enregistre puis quitte le fichier via CTRL + X puis confirmation avec Y et enfin Entrée

4 A présent, on vérifie que notre configuration fonctionne correctement avec une exécution manuelle depuis la commande :

sudo systemctl start zigbee2mqtt

5 Et on affiche le statut avec la commande :

systemctl status zigbee2mqtt.service

Si vous avez des lignes comme ci-dessous dans votre fenêtre SSH, c’est plutôt bon signe !

6 On interrompt le service avec la combinaison CTRL + C pour retrouver le prompt.

7 Enfin, maintenant que nous nous sommes assurés que tout est fonctionnel, on peut configurer le démarrage automatique avec la ligne :

sudo systemctl enable zigbee2mqtt.service

La console informe de la création du lien symbolique, c’est gagné !

8 Pour finir et confirmer le bon fonctionnement de notre configuration du démarrage automatique, il convient de lancer un redémarrage du raspberry Pi. Pour cela rien de compliqué, on joue simplement la commande de reboot.

sudo reboot

Patientez une à deux minutes et rendez-vous dans le système domotique (Home Assistant ou Jeedom) et essayez d’actionner un périphérique. Vous constaterez que ça fonctionne. Cela confirme que le service se lance correctement au démarrage du raspberry PI.

Zigbee2Mqtt, les commandes de maintenance

A présent, le système est automatisé. À des fins de maintenance vous pouvez agir sur le service avec les commandes suivantes :

# Stopping Zigbee2MQTT
sudo systemctl stop zigbee2mqtt

# Starting Zigbee2MQTT
sudo systemctl start zigbee2mqtt

# View the log of Zigbee2MQTT
sudo journalctl -u zigbee2mqtt.service -f

Conclusion

Nous venons de voir ensemble un guide pas à pas pour déployer une passerelle Zigbee2MQTT chez vous. Si comme moi vous possédez à la fois du Jeedom et du Home Assistant à la maison, Zigbee2MQTT simplifie grandement le système. C’est à présent à vous de jouer pour faire un pas de plus dans la domotique DIY.

Pour aller encore plus loin avec Zigbee2MQTT

---