Comment implémenter Zigbee2MQTT en 2026

Introduction

Zigbee est un protocole sans fil low-power essentiel pour l'IoT en 2026, particulièrement dans les maisons intelligentes. Contrairement au Wi-Fi énergivore, Zigbee forme un réseau maillé où chaque appareil relaie les signaux, couvrant jusqu'à 100+ nœuds avec une portée étendue. Zigbee2MQTT est l'outil open-source leader qui traduit les messages Zigbee en MQTT, facilitant l'intégration avec Home Assistant, Node-RED ou applications custom.

Ce tutoriel intermediate vous guide pas à pas : de l'installation Docker à l'automatisation via code JavaScript. Pourquoi c'est crucial ? En 2026, avec l'essor des Matter/Zigbee hybrides, maîtriser Zigbee2MQTT optimise la batterie des capteurs (jusqu'à 2 ans d'autonomie) et réduit la latence à <100ms. Résultat : un setup scalable, sécurisé et économique. Prêt à transformer votre Raspberry Pi en coordinator Zigbee ? (128 mots)

Prérequis

Raspberry Pi 4+ (ou PC Linux) avec Docker et Docker Compose installés
Dongle Zigbee compatible (ex: Sonoff Zigbee 3.0 USB Dongle Plus, ID: /dev/ttyUSB0)
Broker MQTT (Mosquitto) ou intégré
Node.js 20+ pour les scripts clients
Un appareil Zigbee à tester (ex: IKEA Tradfri ou Tuya bulb)
Connaissances de base en Docker, YAML et MQTT

Créer le docker-compose.yml

docker-compose.yml

version: '3.8'

services:
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt:2.0.6
    restart: unless-stopped
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - '8080:8080'
    environment:
      - TZ=Europe/Paris
    depends_on:
      - mqtt

  mqtt:
    image: eclipse-mosquitto:2.0
    restart: unless-stopped
    command: mosquitto -c /mosquitto/config/mosquitto.conf
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - '1883:1883'
      - '9001:9001'

networks:
  default:
    name: zigbee-network

Ce docker-compose déploie Zigbee2MQTT et Mosquitto en un réseau isolé. Il monte le dongle USB, persiste les données et expose MQTT sur 1883. Créez les dossiers ./data, ./mosquitto/config/data/log avant lancement pour éviter les erreurs de volume.

Configurer Mosquitto

Créez le fichier de config Mosquitto pour activer les connexions anonymes (à sécuriser en prod). Cela permet à Zigbee2MQTT de publier directement sur les topics MQTT comme zigbee2mqtt/bridge/log.

mosquitto.conf

mosquitto/config/mosquitto.conf

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883
allow_anonymous true
listener 9001
protocol websockets
allow_anonymous true

Configuration minimale : persistance des sessions, logs activés, anonymous pour dev. En prod, ajoutez password_file et certificats TLS. Le port 9001 est pour WebSockets, utile pour dashboards comme Node-RED.

Lancer le stack

Exécutez docker compose up -d dans le dossier du docker-compose. Vérifiez les logs avec docker compose logs zigbee2mqtt. L'UI Zigbee2MQTT sera sur http://localhost:8080.

Démarrer et vérifier

terminal

#!/bin/bash
mkdir -p data mosquitto/{config,data,log}
docker compose up -d

echo "Attendre 30s pour init..."
sleep 30
docker compose logs zigbee2mqtt | tail -10
docker compose ps

Script bash complet pour bootstrap : crée les volumes, lance en detached, affiche les 10 dernières logs et status. Si erreur 'serialport', vérifiez ls -l /dev/ttyUSB0 et permissions udev (99-zigbee.rules).

Configurer Zigbee2MQTT

Éditez data/configuration.yaml pour définir le port série et MQTT. Activez permit_join: true via l'UI pour ajouter des devices.

configuration.yaml

data/configuration.yaml

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mqtt:1883
serial:
  port: /dev/ttyUSB0
  adapter: ezsp
advanced:
  network_key: !secret network_key
  pan_id: 0x1a62
  channel: 11
frontend:
  port: 8080
availability: true

Config complète : lien HA auto-discovery, MQTT local, adapter EZSP pour Sonoff dongle. network_key en secret pour sécurité (générez avec openssl rand -hex 16). Changez channel si interférences Wi-Fi.

Activer le pairing via API

pair-device.sh

#!/bin/bash
curl -X POST -H "Content-Type: application/json" \
  -d '{"value": true}' \
  http://localhost:8080/api/state/permit_join

echo "Pairing activé 255s. Appuyez sur reset de votre device Zigbee."
sleep 260
curl -X POST -H "Content-Type: application/json" \
  -d '{"value": false}' \
  http://localhost:8080/api/state/permit_join
echo "Pairing désactivé."

Script pour toggle permit_join via REST API de Z2M. Lancez-le pour ajouter un device : il attend 255s max. Vérifiez l'UI ou MQTT pour le nouveau device (ex: topic zigbee2mqtt/LumiereSalon).

Client MQTT en JavaScript

Créez un script Node.js pour souscrire aux événements Zigbee via MQTT. Utile pour automatisations custom sans Home Assistant.

mqtt-client.js

const mqtt = require('mqtt');
const client = mqtt.connect('mqtt://localhost:1883');

client.on('connect', () => {
  console.log('Connecté MQTT');
  client.subscribe('zigbee2mqtt/#', (err) => {
    if (!err) console.log('Souscrit à zigbee2mqtt/#');
  });
});

client.on('message', (topic, message) => {
  const payload = JSON.parse(message.toString());
  console.log(`${topic}:`, payload);
  if (topic.endsWith('/state') && payload.state?.brightness) {
    console.log('Luminosité changée:', payload.state.brightness);
  }
});

process.on('SIGINT', () => {
  client.end();
  process.exit();
});

Client MQTT complet avec mqtt.js : souscrit à tous topics Zigbee2MQTT, parse JSON, log événements. Exemple : réagit aux changements de brightness. Installez npm i mqtt, lancez node mqtt-client.js. Scalable pour webhooks.

Bonnes pratiques

Sécurisez MQTT : Activez TLS et auth en prod (require_certificate true dans mosquitto.conf).
Choisissez le bon channel : Utilisez un analyseur Zigbee (ex: zigbee-channelz) pour éviter les interférences 2.4GHz.
Backup régulier : Copiez ./data hebdo ; restaurez via database.sqlite.
Mesh optimisé : Placez 3+ routers (prises Philips Hue) pour >90% coverage.
Monitoring : Intégrez Prometheus via exporter Z2M pour alerter sur dead devices.

Erreurs courantes à éviter

Dongle non détecté : Vérifiez dmesg | grep ttyUSB et ajoutez udev rule (SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", GROUP="dialout").
'No response from device' : Channel mismatch ; forcez channel: 15 et reset network_key.
MQTT déconnecté : Vérifiez firewall (ufw allow 1883) et availability: true dans config.
Pairing échoue : Battery <20% ou distance >10m ; utilisez un repeater proche.

Pour aller plus loin

Intégrez avec Home Assistant via discovery auto. Explorez Zigbee2MQTT docs. Pour du custom firmware, voir Tasmota Zigbee. Découvrez nos formations IoT Learni sur MQTT et réseaux maillés avancés.