Zigbee2MQTT : connecter vos appareils Zigbee à n'importe quel broker MQTT

Zigbee2MQTT transforme un coordinateur Zigbee USB en passerelle MQTT : chaque capteur, ampoule et interrupteur appairé apparaît comme un message JSON sur un topic, et chaque topic se terminant par /set devient une commande. Il n'embarque pas de broker : vous en indiquez un dans configuration.yaml, et n'importe quel broker MQTT conforme au standard convient : un Mosquitto local, l'add-on Home Assistant ou un broker managé dans le cloud.

Ce tutoriel configure Zigbee2MQTT (2.x) avec un broker externe, explique l'organisation des topics et montre comment vérifier la connexion et piloter un appareil en ligne de commande.

Comment les briques s'assemblent

Zigbee device ──radio──▶ Coordinator (USB) ──serial──▶ Zigbee2MQTT ──MQTT──▶ Broker ──▶ Home Assistant / Node-RED / your app

Zigbee2MQTT n'est qu'un client MQTT parmi d'autres. Deux conséquences pratiques : le broker peut se trouver n'importe où sur le réseau, et tout ce qui parle MQTT — un dashboard, un script, le client en ligne — voit exactement les mêmes messages que votre logiciel domotique.

Configuration minimale

Zigbee2MQTT lit data/configuration.yaml. C'est la section MQTT qui le relie à votre broker :

mqtt:
  base_topic: testmqtt/z2m          # par défaut "zigbee2mqtt"
  server: mqtts://broker.connectmq.com:8883
  user: '!secret user'
  password: '!secret password'
  client_id: z2m-living-room
  keepalive: 60
  version: 5                        # 3, 4 (3.1.1) ou 5

serial:
  port: /dev/ttyACM0
  adapter: ember                    # zstack, ember, deconz, zigate, zboss

frontend:
  enabled: true
  port: 8080

homeassistant:
  enabled: false                    # true si Home Assistant doit découvrir les appareils

advanced:
  log_level: info

user: username
password: password

Remarques sur les clés importantes :

• server : mqtt://host:1883 pour du TCP en clair, mqtts://host:8883 pour TLS. Les URL WebSocket (wss://host:8084/mqtt) fonctionnent aussi puisque Zigbee2MQTT s'appuie sur MQTT.js, mais TCP reste le choix habituel pour une passerelle.
• base_topic : la racine de tout ce que publie Zigbee2MQTT. Gardez la valeur par défaut zigbee2mqtt sur un broker privé ; sur un broker de test partagé, utilisez une racine unique comme ci-dessus pour ne pas entrer en collision avec d'autres utilisateurs.
• client_id : doit être unique sur le broker. Deux instances avec le même ID s'éjectent mutuellement en boucle ; voir bonnes pratiques pour le client ID.
• ca, key, cert : nécessaires uniquement pour une CA privée ou du TLS mutuel. Un broker avec un certificat reconnu publiquement fonctionne avec mqtts:// seul. Ne « corrigez » jamais des erreurs de certificat avec reject_unauthorized: false en production.
• !secret : place les identifiants dans secret.yaml pour pouvoir partager ou versionner configuration.yaml en toute sécurité.

Chaque option peut aussi être définie par variable d'environnement, ce qui est pratique en conteneur : ZIGBEE2MQTT_CONFIG_MQTT_SERVER, ZIGBEE2MQTT_CONFIG_MQTT_USER, ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD, etc.

Lancer Zigbee2MQTT avec Docker

services:
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    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-if00-port0:/dev/ttyACM0

Mappez le coordinateur via son chemin /dev/serial/by-id/... : /dev/ttyUSB0 peut changer après un redémarrage ou le branchement d'un autre périphérique USB. Si un broker local tourne dans le même fichier Compose, désignez-le par le nom du service (mqtt://mosquitto:1883) et non par localhost : dans un conteneur, localhost est le conteneur lui-même. Le guide de la stack Docker Compose couvre cette configuration.

Démarrez et suivez le log :

docker compose up -d
docker compose logs -f zigbee2mqtt

Un démarrage sain affiche Connecting to MQTT server at mqtts://broker.connectmq.com:8883 puis Connected to MQTT server. Si vous voyez MQTT error: Connection refused: Not authorized ou MQTT failed to connect, exiting..., vérifiez d'abord les identifiants et le couple port/schéma ; le guide des erreurs Zigbee2MQTT détaille chaque message.

L'organisation des topics

Les nouveaux appareils portent leur adresse IEEE comme nom (0x00158d0001a2b3c4). Renommez-les de façon parlante ; une barre oblique dans le nom crée une hiérarchie, donc living_room/ceiling devient testmqtt/z2m/living_room/ceiling. C'est le moyen le plus simple d'obtenir une arborescence de topics propre pour la maison connectée.

bridge/state, bridge/info et bridge/devices sont des messages retenus : tout client qui s'abonne plus tard sait immédiatement si le bridge est actif et quels appareils existent.

Tester chaque étape en ligne de commande

1. Le bridge est-il connecté ? Abonnez-vous à l'état du bridge ; la valeur retenue arrive immédiatement :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/state' -v
# testmqtt/z2m/bridge/state {"state":"online"}

2. Observez tout le trafic pendant que vous appuyez sur un bouton ou ouvrez un capteur de porte :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/#' -v

3. Appairez un appareil en ouvrant le réseau pour une durée limitée (Zigbee2MQTT 2.x exige time ; 0 le referme) :

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/z2m/bridge/request/permit_join' -m '{"time": 120}'

La réponse arrive sur bridge/response/permit_join, et bridge/event signale device_joined et device_interview pendant l'appairage.

4. Renommez-le et pilotez-le :

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/request/device/rename' \
  -m '{"from": "0x00158d0001a2b3c4", "to": "living_room/ceiling"}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/living_room/ceiling/set' \
  -m '{"state": "TOGGLE", "brightness": 180, "transition": 1}'

Le nouvel état de l'ampoule apparaît sur testmqtt/z2m/living_room/ceiling en moins d'une seconde. Si une commande reste sans effet, consultez bridge/logging : Zigbee2MQTT y consigne les payloads rejetés.

Vous pouvez réaliser les mêmes étapes dans le navigateur : ouvrez le client MQTT en ligne, abonnez-vous à testmqtt/z2m/# et publiez sur les topics /set depuis le panneau de publication.

Observer vos topics Zigbee2MQTT en direct

Intégration avec Home Assistant

Réglez homeassistant: enabled: true et Zigbee2MQTT publie des messages de discovery sous homeassistant/.... L'intégration MQTT de Home Assistant doit pointer vers le même broker ; les appareils apparaissent alors automatiquement avec toutes leurs entités. Si vous avez changé base_topic, rien d'autre à modifier : les payloads de discovery contiennent les bons topics d'état et de commande. Pour le côté broker, voir Home Assistant et MQTT.

Checklist de production

1. Donnez à Zigbee2MQTT son propre utilisateur sur le broker, limité à <base>/#, plus homeassistant/# si la discovery est activée.
2. Utilisez TLS (mqtts://) dès que le broker n'est pas sur la même machine.
3. Activez availability pour que les appareils hors ligne soient signalés au lieu de rester silencieusement obsolètes.
4. Gardez permit_join fermé sauf pendant l'appairage.
5. Sauvegardez tout le répertoire data/ : il contient la clé réseau et la sauvegarde du coordinateur, pas seulement la configuration.

Zigbee2MQTT est le moyen le plus simple de libérer vos appareils Zigbee des hubs constructeurs : un bloc YAML le relie à n'importe quel broker, et dès lors chaque appareil n'est plus qu'un topic. Vérifiez d'abord l'état du bridge, observez le trafic pendant l'appairage et pilotez les appareils avec un simple mosquitto_pub avant de bâtir vos automatisations.

Questions fréquentes