Guide d'installation de Zigbee2MQTT : du coordinateur au tableau de bord

Une installation Zigbee2MQTT vous permet d'utiliser dans votre maison connectée des capteurs, ampoules et interrupteurs Zigbee de nombreuses marques sans leurs passerelles ni leurs clouds, et expose chaque appareil sous forme de simples topics MQTT. Dans ce guide, vous allez choisir un coordinateur, lancer Zigbee2MQTT dans Docker, le connecter à un broker, appairer et renommer des appareils, les piloter en ligne de commande et suivre leurs états sur un tableau de bord. Tout est d'abord testé sur le serveur MQTT public gratuit, réservé aux tests, avec un topic de base unique.

Comment s'articule Zigbee2MQTT

Zigbee2MQTT est une passerelle. D'un côté, il pilote un coordinateur Zigbee (une clé USB ou un adaptateur réseau) qui forme votre réseau maillé Zigbee. De l'autre, c'est un client MQTT qui publie l'état de chaque appareil en JSON et écoute les commandes. Tout ce qui parle MQTT, comme Home Assistant, Node-RED, un script Python ou une application mobile, peut alors utiliser ces appareils. Jeedom et Domoticz savent aussi communiquer en MQTT.

[Zigbee devices] ~~radio~~ [Coordinator] --USB/TCP-- [Zigbee2MQTT] --MQTT-- [Broker] -- [Dashboards, automations]

Le broker se trouve au milieu et c'est le seul élément auquel tous les consommateurs se connectent. Si vous souhaitez un rappel sur ce que fait un broker MQTT, une lecture rapide avant de commencer en vaut la peine.

Choisir un coordinateur

Le coordinateur détermine la valeur du paramètre adapter. Voici des choix populaires et bien pris en charge :

Deux conseils pratiques font une grande différence. Utilisez une rallonge USB d'environ un demi-mètre pour éloigner la clé des ports USB 3 et des SSD, dont les interférences peuvent fortement réduire la portée Zigbee. Et ajoutez tôt quelques routeurs alimentés sur secteur (prises ou ampoules connectées), car les appareils sur batterie ne routent pas et un réseau maillé composé uniquement d'appareils terminaux est fragile.

Installer Zigbee2MQTT avec Docker

Trouvez le chemin stable de votre adaptateur, qui ne change pas entre les redémarrages :

ls -l /dev/serial/by-id/

Créez un dossier avec un fichier docker-compose.yml :

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXX-if00-port0:/dev/ttyACM0

Remplacez le chemin du périphérique par celui de votre système et indiquez votre fuseau horaire. Pour une installation durable, figez l'image sur un tag de version précis plutôt que latest, afin que les mises à jour se fassent quand vous le décidez.

La configuration de l'installation Zigbee2MQTT

Créez data/configuration.yaml avant le premier démarrage. Choisissez un segment aléatoire pour le topic de base, car le serveur MQTT public gratuit est partagé et lisible par tous :

homeassistant:
  enabled: false
frontend:
  enabled: true
  port: 8080
mqtt:
  base_topic: connectmq/demo/z7q4/z2m
  server: mqtt://broker.connectmq.com:1883
  client_id: z2m-z7q4-bridge
serial:
  port: /dev/ttyACM0
  adapter: zstack
availability:
  enabled: true
advanced:
  log_level: info
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Points clés :

• base_topic est le préfixe de tout ce que publie Zigbee2MQTT. Ici, il comporte quatre niveaux, ce qui laisse de la marge sous la limite de 8 niveaux de topic du serveur MQTT public gratuit.
• client_id doit être unique et non vide sur le broker.
• channel ne peut pas être modifié ultérieurement sans réappairer tous les appareils. Les canaux 15, 20 et 25 évitent les chevauchements Wi-Fi les plus fréquents ; vérifiez quels canaux Wi-Fi sont encombrés autour de vous.
• GENERATE indique à Zigbee2MQTT de créer une clé réseau et des identifiants aléatoires au premier démarrage, puis de les réécrire dans le fichier. Sauvegardez ensuite configuration.yaml et coordinator_backup.json depuis le dossier de données.
• availability publie {"state":"online"} ou offline pour chaque appareil, ce qui est très utile sur les tableaux de bord.

Démarrez-le et suivez le journal :

docker compose up -d
docker compose logs -f zigbee2mqtt

Vous devriez voir la version du firmware du coordinateur, puis une ligne confirmant la connexion au broker MQTT. Si vous démarrez sans fichier de configuration, les versions récentes ouvrent une page d'accueil sur le port 8080 où vous pouvez saisir les mêmes valeurs dans un formulaire.

Appairer et nommer les appareils

Ouvrez l'interface sur http://<host>:8080 et cliquez sur Permit join (All), ou activez l'appairage via MQTT pour 254 secondes au maximum :

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/permit_join" -m '{"time": 254}'

Mettez l'appareil en mode appairage (généralement un appui long sur son bouton, ou une séquence de mises sous tension pour les ampoules). Il apparaît avec une adresse IEEE comme 0x00158d0001abcd12. Renommez-le immédiatement avec un nom parlant, car ce nom devient son topic :

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/device/rename" \
  -m '{"from": "0x00158d0001abcd12", "to": "living_room_lamp"}'

Désactivez l'appairage avec {"time": 0} une fois terminé. Laisser le réseau ouvert invite les appareils des voisins à s'y joindre par accident.

Utilisez des underscores plutôt que des barres obliques dans les noms conviviaux pendant vos tests sur le serveur public. Un nom comme living_room/lamp est autorisé et crée de jolies hiérarchies, mais chaque barre oblique ajoute un niveau de topic, et bridge/request/device/rename utilise déjà les 8 niveaux avec ce topic de base.

Lire et piloter les appareils via MQTT

Abonnez-vous à tout ce qui se trouve sous le topic de base :

mosquitto_sub -h broker.connectmq.com -p 1883 -i z2m-watch-z7q4 -t "connectmq/demo/z7q4/z2m/#" -v

Un capteur de température publie sur connectmq/demo/z7q4/z2m/hallway_sensor :

{"battery": 97, "humidity": 48.2, "linkquality": 116, "temperature": 21.4, "voltage": 2995}

Pilotez une ampoule en publiant sur son topic set :

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/living_room_lamp/set" \
  -m '{"state": "ON", "brightness": 180, "color_temp": 370, "transition": 2}'

Pour demander son état actuel à un appareil, publiez {"state": ""} sur son topic get. Les topics des appareils transportent l'état complet ; un tableau de bord n'a donc besoin que d'un abonnement par appareil.

De MQTT au tableau de bord

Comme Zigbee2MQTT parle un MQTT standard, plusieurs options de tableau de bord s'offrent à vous :

1. L'interface Zigbee2MQTT pour l'administration : liste des appareils, carte du réseau, mises à jour OTA et journaux.
2. Home Assistant via son intégration MQTT. Réglez homeassistant.enabled: true et Zigbee2MQTT publie des messages de découverte pour que les entités apparaissent automatiquement ; le guide Home Assistant MQTT couvre cette partie.
3. Node-RED Dashboard, en s'abonnant aux topics des appareils avec un nœud mqtt in et un nœud JSON.
4. Un tableau de bord web utilisant MQTT sur WebSocket, connecté à wss://broker.connectmq.com:8084/mqtt.

Pour des vérifications rapides sans rien construire, l'explorateur de topics en direct du portail ConnectMQ affiche chaque topic Zigbee2MQTT au fil de ses mises à jour, ce qui est pratique pendant l'appairage et le renommage.

Dépannage de l'installation Zigbee2MQTT

Le serveur MQTT public gratuit limite aussi chaque client à 10 messages par seconde, ce qu'un petit réseau de test respecte largement mais qu'un grand réseau peut dépasser au démarrage. C'est une raison de plus pour réserver l'espace public aux essais ; l'article qui lui est consacré, cité plus haut, en liste toutes les limites.

Passer à un broker privé

Zigbee2MQTT pilote des serrures, des lumières et des alarmes ; la production exige donc des identifiants et TLS. Avec un broker MQTT managé comme ConnectMQ, vous créez un broker dans le portail, copiez le nom d'utilisateur, le mot de passe et le client ID générés, et ne modifiez que le bloc mqtt :

mqtt:
  base_topic: zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: YOUR_USERNAME
  password: YOUR_PASSWORD
  client_id: YOUR_CLIENT_ID
  version: 5

Le certificat Let's Encrypt est validé par le magasin d'autorités de certification système du conteneur ; aucun fichier de certificat supplémentaire n'est donc nécessaire. Le plan Serverless gratuit autorise des messages jusqu'à 256 Ko, ce qui suffit largement pour les payloads habituels de la passerelle, et les plans payants portent cette limite à 1 Mo. Le guide Zigbee2MQTT avec un broker cloud approfondit l'accès à distance et les installations multisites, et le guide de l'automatisation IoT montre la place de Zigbee dans un système domestique ou de bâtiment plus large.

Faites tourner Zigbee2MQTT sur ConnectMQ

ConnectMQ offre à votre passerelle Zigbee2MQTT un broker MQTT privé avec TLS, une WebSocket sécurisée pour les tableaux de bord web et un portail pour suivre en direct chaque topic d'appareil. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire, et faites pointer votre mqtt.server vers lui.

Questions fréquentes

Quel coordinateur choisir pour une nouvelle installation Zigbee2MQTT ?

Une clé basée sur le Texas Instruments CC2652P avec l'adaptateur zstack, ou une clé Silicon Labs EFR32MG21 avec l'adaptateur ember, sont les choix les plus courants et les mieux pris en charge. Les adaptateurs réseau sont utiles lorsque le serveur est éloigné des appareils.

Puis-je changer le canal Zigbee plus tard ?

Techniquement oui, mais la plupart des appareils devront alors être réappairés. Choisissez le canal avec soin avant d'appairer quoi que ce soit.

Zigbee2MQTT a-t-il besoin de Home Assistant ?

Non. Zigbee2MQTT n'a besoin que d'un broker MQTT. Home Assistant n'est qu'un consommateur optionnel parmi d'autres, aux côtés de Node-RED, de scripts et de tableaux de bord.

Est-il sûr de faire tourner Zigbee2MQTT sur le serveur MQTT public gratuit ?

Uniquement pour des tests. N'importe qui peut lire et publier sur les topics publics, y compris vos topics set ; utilisez donc un broker privé avec identifiants et TLS pour de vrais appareils.