Zigbee2MQTT¶

Configuration et gestion du réseau Zigbee via Zigbee2MQTT.

Vue d'ensemble¶

Élément	Valeur
Add-on	Zigbee2MQTT
Version	1.x
Coordinateur	Sonoff ZBDongle-P (CC2652P)
Appareils	~50
Broker MQTT	Mosquitto (intégré)

Architecture¶

graph LR
    subgraph "Appareils Zigbee"
        A1[Ampoules]
        A2[Capteurs]
        A3[Interrupteurs]
        A4[Prises]
    end

    subgraph "Home Assistant"
        Z2M[Zigbee2MQTT]
        MQTT[Mosquitto]
        HA[HA Core]
    end

    A1 --> Z2M
    A2 --> Z2M
    A3 --> Z2M
    A4 --> Z2M
    Z2M --> MQTT
    MQTT --> HA

Accès interface¶

URL : http://192.168.1.152:8080 (via Ingress)
Ou : Paramètres → Add-ons → Zigbee2MQTT → Ouvrir l'interface web

Configuration¶

Fichier principal¶

# /config/zigbee2mqtt/configuration.yaml
homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
serial:
  port: /dev/ttyUSB0
  adapter: zstack
frontend:
  port: 8080
advanced:
  network_key: GENERATE
  pan_id: GENERATE
  channel: 15
  last_seen: ISO_8601

Paramètres importants¶

Paramètre	Valeur	Description
`channel`	15	Canal Zigbee (éviter interférences WiFi)
`permit_join`	false	Désactivé par défaut (sécurité)
`last_seen`	ISO_8601	Format timestamp dernière vue

Appareils par catégorie¶

Éclairage¶

Appareil	Modèle	Pièce
Ampoule E27	Philips Hue	Salon
Ampoule E27	IKEA TRÅDFRI	Chambre
Bandeau LED	Gledopto	Cuisine

Capteurs¶

Appareil	Modèle	Mesures
Température	Aqara WSDCGQ11LM	Temp, Humidité
Porte/Fenêtre	Aqara MCCGQ11LM	Ouverture
Mouvement	Philips SML001	Présence, Luminosité

Interrupteurs¶

Appareil	Modèle	Fonctions
Double	Aqara WXKG02LM	2 boutons
Simple	IKEA E1743	On/Off, Dim
Scène	Philips RWL022	4 boutons

Prises¶

Appareil	Modèle	Fonctions
Prise	OSRAM Smart+	On/Off, Mesure
Prise	IKEA E1603	On/Off

Appairage d'un nouvel appareil¶

Procédure¶

Activer le mode appairage :
Interface Z2M → Permit join (Enable)
Ou via HA : zigbee2mqtt/bridge/request/permit_join → {"value": true}
Reset de l'appareil :
Suivre la procédure constructeur (généralement appui long)
L'appareil clignote pour indiquer le mode appairage
Attente de détection :
L'appareil apparaît dans l'interface Z2M
Délai : 30s à 2 min
Configuration :
Renommer l'appareil (friendly_name)
Assigner une pièce
Configurer les options spécifiques
Désactiver le mode appairage :
Important pour la sécurité !

Reset d'appareils courants¶

Marque	Procédure
Aqara	Appui 5s sur bouton reset
IKEA	6x on/off rapides
Philips Hue	App Hue ou 6x on/off
Sonoff	Appui 5s sur bouton

Réseau maillé¶

Routeurs (alimentés secteur)¶

Les appareils alimentés secteur servent de routeurs : - Ampoules - Prises connectées - Répéteurs dédiés

End devices (batterie)¶

Les appareils sur batterie sont des "end devices" : - Capteurs - Télécommandes - Boutons

Optimisation du maillage¶

Placer des routeurs régulièrement
Éviter les zones sans routeur
Carte réseau : Interface Z2M → Map

Dépannage¶

Appareil non répondant¶

Vérifier la batterie
Vérifier last_seen dans Z2M
Essayer de ré-appairer

Latence élevée¶

Vérifier la qualité du lien (LQI)
Ajouter des routeurs
Vérifier les interférences WiFi

Appareil qui se déconnecte¶

Vérifier le canal (interférences)
Rapprocher d'un routeur
Mettre à jour le firmware appareil

Logs et debug¶

Activer les logs debug¶

# configuration.yaml
advanced:
  log_level: debug

Consulter les logs¶

Interface Z2M → Logs
Ou : Paramètres → Add-ons → Zigbee2MQTT → Logs

MQTT Topics¶

Structure¶

zigbee2mqtt/
├── bridge/
│   ├── state          # online/offline
│   ├── info           # infos coordinateur
│   ├── devices        # liste appareils
│   └── event          # événements
└── <device_name>/
    ├── (état)         # état actuel
    └── set            # commandes

Exemples¶

# Lire état d'un appareil
mosquitto_sub -t "zigbee2mqtt/salon_lampe" -v

# Commander un appareil
mosquitto_pub -t "zigbee2mqtt/salon_lampe/set" -m '{"state":"ON"}'

Mise à jour¶

Zigbee2MQTT¶

Paramètres → Add-ons → Zigbee2MQTT
Vérifier les mises à jour
Lire les release notes
Mettre à jour

Firmware coordinateur¶

Télécharger le firmware (Koenkk/Z-Stack-firmware)
Flasher via cc2538-bsl ou Texas Instruments tools
Redémarrer Z2M

Sauvegarde¶

Fichiers à sauvegarder : - /config/zigbee2mqtt/configuration.yaml - /config/zigbee2mqtt/coordinator_backup.json - /config/zigbee2mqtt/database.db

Inclus dans les snapshots Home Assistant.