🔧 Erreur Zigbee Herdsman : Guide Complet de Dépannage avec ESP32/Arduino (2026)
Qu'est-ce que l'Erreur Zigbee Herdsman ?
Zigbee Herdsman est la bibliothèque centrale qui gère la communication entre votre adaptateur Zigbee (CC2531, ConBee 2, Sonoff, etc.) et votre système de domotique (Zigbee2MQTT, Home Assistant, Node-RED). L'erreur "Error While Starting Zigbee Herdsman" indique généralement un problème de communication matérielle ou de configuration logicielle.
Symptômes courants :
- "Failed to connect to the adapter" - Échec de connexion à l'adaptateur
- "SRSP - SYS - ping after 6000ms" - Timeout de communication
- "USB adapter discovery error" - Adaptateur non détecté
- "Firmware revision mismatch" - Incompatibilité de firmware
🔍 Causes Principales de l'Erreur
Problèmes Matériels (Hardware) :
- Adaptateur non détecté : Le système d'exploitation ne reconnaît pas l'adaptateur USB Zigbee
- Problème de port USB : Port défectueux ou manque d'alimentation
- Câblage incorrect : Pour les adaptateurs CC2531 avec ESP32/Arduino
- Firmware obsolète : Firmware incompatible sur l'adaptateur Zigbee
Problèmes Logiciels (Software) :
- Configuration incorrecte : Mauvais port série dans configuration.yaml
- Conflit de permissions : L'utilisateur n'a pas les droits d'accès au port série
- Bibliothèques manquantes : Dependencies Node.js non installées
- Version incompatible : Version de Zigbee2MQTT incompatible avec le firmware
️ Méthode 1 : Vérification Matérielle de l'Adaptateur
Étape 1 : Tester la Détection USB
Sur Linux (Raspberry Pi) :
# Lister tous les périphériques USB
lsusb
# Identifier les ports série disponibles
ls -la /dev/tty*
# Vérifier les logs système
dmesg | grep tty
dmesg | grep -i zigbee
Sur Windows :
# Ouvrir le Gestionnaire de périphériques (Win + X > Device Manager)
# Vérifier dans "Ports (COM & LPT)"
# L'adaptateur doit apparaître comme "USB Serial Device (COMx)"
Étape 2 : Tester l'Adaptateur CC2531 avec ESP32
Si vous utilisez un CC2531 avec un ESP32 comme coordinateur Zigbee DIY, voici le schéma de câblage :
CC2531 ESP32 ────── ───── P2.0 (RX) ──→ GPIO 16 (TX2) P2.1 (TX) ──→ GPIO 17 (RX2) GND ──→ GND VCC (3.3V) ──→ 3.3V (ou alimentation externe)
💻 Méthode 2 : Configuration Logicielle
Configuration Zigbee2MQTT (configuration.yaml)
# Configuration pour adaptateur CC2531
serial:
port: /dev/ttyACM0 # Linux Raspberry Pi
# port: COM3 # Windows
# port: /dev/ttyUSB0 # Alternative Linux
adapter: zstack # Pour CC2531
# Pour ConBee II / RaspBee
# serial:
# port: /dev/ttyACM0
# adapter: deconz
# Pour Sonoff Zigbee USB
# serial:
# port: /dev/ttyUSB0
# adapter: zstack
# Configuration avancée
advanced:
log_level: debug # Mettre en 'debug' pour le dépannage
channel: 11
pan_id: 0x1a62
ext_pan_id: [0xDD, 0xDD, ...]
mqtt:
base_topic: zigbee2mqtt
server: 'mqtt://localhost:1883'
Vérification des Permissions (Linux)
# Ajouter l'utilisateur au groupe dialout
sudo usermod -a -G dialout $USER
# Redémarrer la session ou exécuter
newgrp dialout
# Vérifier les permissions du port
ls -l /dev/ttyACM0
# Doit afficher : crw-rw---- 1 root dialout ...
🔄 Méthode 3 : Mise à Jour du Firmware
Pour CC2531 avec ESP32 :
# Télécharger le firmware Z-Stack (pour CC2531)
# Utiliser CC Debugger ou ESP32 pour flasher
# Firmware recommandé pour CC2531 :
# - coordinator_znp.hex (Z-Stack 3.0.x)
# - CC2531ZNP-Prod.hex (version stable)
# Vérifier la version du firmware dans les logs Zigbee2MQTT
# Chercher : "zigbee-herdsman" dans le journal
Pour ConBee II / RaspBee :
# Mettre à jour le firmware via GCFFlasher
sudo GCFFlasher_internal -t 60 -f deCONZ_RaspBeeII_0x26720700.bin.GCF
# Ou via Phoscon App (interface web)
# Aller dans Settings > Gateway > Firmware Update
🐛 Méthode 4 : Dépannage Avancé
Activer le Mode Debug
# Dans configuration.yaml de Zigbee2MQTT
advanced:
log_level: debug
log_output:
- console
- file
# Redémarrer Zigbee2MQTT
cd /opt/zigbee2mqtt
npm start
# Ou avec systemd
sudo systemctl restart zigbee2mqtt
sudo journalctl -u zigbee2mqtt -f
Tester la Communication Série
# Installer minicom pour tester le port série
sudo apt-get install minicom
# Tester la communication
minicom -D /dev/ttyACM0 -b 115200
# Envoyer une commande AT pour tester
# (pour les modules XBee/CC2530)
AT
# Doit répondre "OK"
Vérifier les Conflits de Port
# Vérifier quel processus utilise le port
sudo lsof /dev/ttyACM0
# Arrêter les services conflictuels
sudo systemctl stop modemmanager
sudo systemctl disable modemmanager
# Pour Home Assistant, vérifier que ZHA n'est pas actif
# si vous utilisez Zigbee2MQTT
📊 Tableau de Dépannage Rapide
| Erreur | Cause Probable | Solution |
|---|---|---|
| "Adapter not found" | Port incorrect ou adaptateur non branché | Vérifier lsusb et modifier le port dans config |
| "SRSP - SYS - ping timeout" | Firmware incompatible ou corrompu | Flasher le firmware Z-Stack latest |
| "Permission denied" | Problème de permissions Linux | Ajouter utilisateur au groupe dialout |
| "USB error -121" | Problème de câble ou port USB | Changer de câble USB ou de port |
️ Erreurs Courantes Spécifiques
Erreur avec ConBee II :
Solution :
- Désactiver ModemManager :
sudo systemctl stop ModemManager - Vérifier le firmware :
GCFFlasher_internal -l - Mettre à jour via Phoscon App
Erreur avec CC2531 :
Solution :
- Vérifier le câblage ESP32-CC2531
- Flasher le firmware Z-Stack 3.0.x
- Vérifier l'alimentation 3.3V stable
🔧 Projet DIY : Coordinateur Zigbee ESP32
Si vous rencontrez trop de problèmes avec les adaptateurs USB commerciaux, vous pouvez construire votre propre coordinateur Zigbee avec un ESP32 et un module CC2530/CC2531.
Composants requis :
- ESP32 DevKit V1
- Module CC2530 ou CC2531 (sans boîtier USB)
- Câbles Dupont
- Alimentation 3.3V stable
FAQ (Foire Aux Questions)
Q1 : Quelle est la différence entre Z-Stack et ZNP pour CC2531 ?
Z-Stack est le firmware complet Texas Instruments pour CC2531. ZNP (Zigbee Network Processor) est une version allégée où le coordinateur (ESP32/Raspberry Pi) gère la logique réseau. Zigbee2MQTT recommande ZNP pour de meilleures performances.
Q2 : Comment choisir entre ConBee II et CC2531 pour un projet DIY ?
Le CC2531 est moins cher (~10€) mais nécessite un flashage manuel et a une portée limitée. Le ConBee II (~40€) est plug-and-play, plus stable et a une meilleure portée. Pour un projet DIY avec ESP32, le CC2531 est idéal pour apprendre.
Q3 : Puis-je utiliser un ESP32 comme coordinateur Zigbee natif ?
Non, l'ESP32 n'a pas de radio Zigbee intégrée. Vous devez utiliser un module radio dédié comme le CC2530/CC2531 connecté via UART, ou utiliser un ESP32-C6/H2 qui supporte Thread/Zigbee nativement (mais nécessite un firmware spécifique).
Q4 : Comment déboguer une erreur Herdsman sur Raspberry Pi ?
Activez le mode debug dans configuration.yaml, puis consultez les logs avec 'journalctl -u zigbee2mqtt -f'. Vérifiez les permissions du port avec 'ls -l /dev/ttyACM0' et assurez-vous que l'utilisateur est dans le groupe 'dialout'.
Conclusion
L'erreur "Error While Starting Zigbee Herdsman" peut sembler complexe, mais elle est généralement liée à des problèmes de configuration matérielle ou logicielle simples. En suivant méthodiquement ce guide - vérification du matériel, configuration des permissions, mise à jour du firmware - vous résoudrez 95% des cas.
Prochaines étapes recommandées :
- Commencez par vérifier la détection USB (lsusb)
- Vérifiez les permissions Linux (groupe dialout)
- Activez le mode debug pour identifier l'erreur précise
- Mettez à jour le firmware de l'adaptateur
- Consultez les logs Zigbee2MQTT pour l'erreur exacte
%20.jpg){kind=tracking}
