tomtom14z
Homebridge Blinds Zigbee MQTT Relay
Plugin Homebridge pour piloter des volets roulants via relais Zigbee et MQTT (eWeLink, MHCOZY) avec gestion intelligente des commandes.
🎯 Fonctionnalités
- Pilotage MQTT : Communication avec votre serveur MQTT (zigbee2mqtt)
- Gestion intelligente des relais : Support des relais eWeLink 2CH et MHCOZY 4CH
- File d'attente des commandes : Évite les superpositions RF en espacant les impulsions
- Logique intelligente : Gestion différenciée selon l'état du volet (fermé/ouvert/intermédiaire)
- Commandes spéciales : Gestion automatique des commandes UP→UP puis DOWN et DOWN→DOWN puis UP
- Mouvement virtuel : Initialisation immédiate du mouvement dans HomeKit dès le premier clic
- Détection des doubles impulsions : Surveillance des états des relais pour corriger les erreurs
- Détection des impulsions externes : Surveillance MQTT pour détecter les commandes 433MHz/télécommandes
- Synchronisation automatique : Mise à jour de l'état virtuel lors d'impulsions externes
- Connexion MQTT globale : Une seule connexion partagée entre tous les accessoires (optimisation des ressources)
- Intégration HomeKit native : Contrôle via l'app Maison d'Apple
🔧 Prérequis
- Homebridge ou HOOBS installé
- Serveur MQTT (Mosquitto, etc.)
- zigbee2mqtt configuré
- Relais Zigbee compatibles (eWeLink ZB-SW02, MHCOZY TYWB 4ch-RF)
📦 Installation
Installation du plugin :
npm install -g homebridge-blinds-zigbee-mqtt-relayRedémarrage de Homebridge :
sudo systemctl restart homebridge # ou via l'interface HOOBS
⚙️ Configuration
Configuration de base
Ajoutez la configuration suivante dans votre config.json :
{
"accessories": [
{
"accessory": "BlindsZigbeeMqttRelay",
"name": "Volet Salon",
"mqtt": {
"host": "192.168.1.100",
"port": 1883,
"username": "mqtt_user",
"password": "mqtt_password"
},
"relayName": "relay_salon",
"relayType": "eweLink-2CH",
"channels": {
"up": "1",
"down": "2"
},
"mqttTopic": "zigbee2mqtt",
"openDuration": 25,
"queueDelay": 2,
"settlingTime": 3,
"movementTime": 22,
"enableSpecialCommands": true
}
]
}Paramètres de configuration
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
name |
string | ✅ | Nom unique du volet |
mqtt.host |
string | ✅ | Adresse IP du serveur MQTT |
mqtt.port |
number | ✅ | Port du serveur MQTT |
mqtt.username |
string | ❌ | Nom d'utilisateur MQTT |
mqtt.password |
string | ❌ | Mot de passe MQTT |
relayName |
string | ✅ | Nom du relais dans zigbee2mqtt |
relayType |
string | ❌ | Type de relais (eweLink-2CH ou mhcozy-4CH) |
channels.up |
string | ✅ | Canal pour monter le volet |
channels.down |
string | ✅ | Canal pour descendre le volet |
mqttTopic |
string | ❌ | Topic MQTT de base (défaut: zigbee2mqtt) |
openDuration |
number | ❌ | Durée d'ouverture en secondes (défaut: 30) |
queueDelay |
number | ❌ | Délai entre commandes en secondes (défaut: 2) |
settlingTime |
number | ❌ | Temps de tassement/détassement en secondes (défaut: 3) |
movementTime |
number | ❌ | Temps de mouvement principal en secondes (défaut: 27) |
enableSpecialCommands |
boolean | ❌ | Activer les commandes spéciales (défaut: true) |
🧠 Logique intelligente
Gestion des états
Le plugin implémente une logique intelligente pour éviter les problèmes de synchronisation :
- Volet fermé (0%) → Commande UP : Envoie d'abord DOWN puis UP
- Volet ouvert (100%) → Commande DOWN : Envoie d'abord UP puis DOWN
- États intermédiaires → Commande directe UP ou DOWN
Commandes spéciales
Les commandes spéciales permettent de gérer les volets qui nécessitent une impulsion de préparation :
- Phase de préparation : Impulsion courte pour "réveiller" le volet
- Phase de mouvement : Impulsion longue pour le mouvement réel
- Temps de préparation : Calculé automatiquement =
queueDelay+globalQueueDelay+ temps MQTT + temps relais - Calcul intelligent des positions : Prise en compte du détassement/tassement (5% =
settlingTime) - Timer global : Temps total = temps de préparation + temps de mouvement calculé
- Mouvement virtuel : HomeKit affiche immédiatement le mouvement en cours
- Synchronisation parfaite : État HomeKit synchronisé avec le mouvement réel
Calcul intelligent des positions intermédiaires
Le plugin calcule automatiquement le temps nécessaire pour atteindre une position donnée :
Ouverture (0% → 50%) :
- 0-5% : Détassement (
settlingTime= 3s) - 5-50% : Mouvement principal (45% de
movementTime= 27s) - Total : 3s + 12.2s = 15.2s + temps de préparation
Fermeture (100% → 50%) :
- 100-95% : Mouvement principal (5% de
movementTime= 27s) - 95-50% : Tassement (
settlingTime= 3s) - Total : 1.4s + 3s = 4.4s + temps de préparation
File d'attente des commandes
- Les commandes sont mises en file d'attente
- Espacement configurable entre les impulsions
- Évite les superpositions RF des télécommandes
Détection des erreurs
- Surveillance des états des relais via MQTT
- Détection des doubles impulsions accidentelles
- Possibilité de correction automatique
🔌 Types de relais supportés
eWeLink ZB-SW02 (2CH)
- 2 canaux indépendants
- Configuration :
"relayType": "eweLink-2CH" - Canaux typiques :
"up": "1","down": "2"
MHCOZY TYWB 4ch-RF (4CH)
- 4 canaux indépendants
- Configuration :
"relayType": "mhcozy-4CH" - Canaux typiques :
"up": "3","down": "4"
🔗 Connexion MQTT globale
Le plugin utilise une connexion MQTT unique partagée entre tous les accessoires pour optimiser les ressources :
Avantages
- Performance optimisée : 8 volets = 1 connexion MQTT au lieu de 8
- Ressources économisées : Réduction de la charge réseau et de la consommation mémoire
- Stabilité améliorée : Évite les déconnexions multiples et les conflits
- Gestion intelligente : Abonnements multiples sur le même topic gérés efficacement
Architecture
- Pattern Singleton : Une seule instance de connexion MQTT
- Surveillance centralisée : Un seul abonnement par topic avec distribution des messages
- Nettoyage automatique : Gestion automatique des abonnements inactifs
🔍 Détection des impulsions externes
Le plugin surveille automatiquement les changements d'état des relais via MQTT pour détecter les impulsions externes :
Fonctionnement
- Surveillance MQTT : Le plugin s'abonne aux topics des relais
- Détection automatique : Les transitions
OFF → ONsont détectées - Mise à jour virtuelle : L'état du volet virtuel est mis à jour automatiquement
- Synchronisation HomeKit : Les changements sont reflétés dans l'interface
Types d'impulsions détectées
- Télécommandes 433MHz : Commandes d'ouverture/fermeture
- Commandes manuelles : Boutons physiques sur les relais
- Automatisations externes : Scripts ou autres systèmes
Comportement
- Impulsion UP : Incrémente la position de 10% (ouverture)
- Impulsion DOWN : Décrémente la position de 10% (fermeture)
- Simulation de mouvement : Animation de 2 secondes pour le feedback visuel
- Persistance : Les nouvelles positions sont sauvegardées
Logs
🔍 Surveillance MQTT activée pour bureau - Topic: zigbee2mqtt/4chCC
🔴 Impulsion externe détectée sur bureau - Canal 3 (state_l3: ON)
🎯 Commande externe détectée: bureau → UP
✅ État mis à jour: bureau = 60% (commande externe UP)
⏹️ Mouvement externe terminé: bureau = 60%📱 Utilisation dans HomeKit
Une fois configuré, vos volets apparaîtront dans l'app Maison :
- Contrôle de position : 0% (fermé) à 100% (ouvert)
- Commandes vocales : "Hey Siri, ouvre le volet du salon à 50%"
- Automatisations : Ouverture automatique au lever du soleil
- Scènes : "Tous les volets fermés" pour la nuit
- Synchronisation : Les commandes externes sont automatiquement reflétées
🚨 Dépannage
Problèmes courants
Connexion MQTT échoue
- Vérifiez l'adresse IP et le port
- Contrôlez les identifiants de connexion
- Testez la connectivité réseau
Volets ne répondent pas
- Vérifiez les noms des relais dans zigbee2mqtt
- Contrôlez la configuration des canaux
- Vérifiez les logs Homebridge
Mouvements erratiques
- Ajustez le
queueDelaypour plus d'espacement - Vérifiez la durée d'ouverture (
openDuration) - Contrôlez la logique des télécommandes
- Ajustez le
Logs
Activez le mode debug dans Homebridge pour voir les logs détaillés :
{
"bridge": {
"debug": true
}
}🔄 Mise à jour
npm update -g homebridge-blinds-zigbee-mqtt-relay🤝 Contribution
Les contributions sont les bienvenues ! N'hésitez pas à :
- Signaler des bugs
- Proposer des améliorations
- Soumettre des pull requests
👨💻 Auteur
📄 Licence
MIT License - voir le fichier LICENSE pour plus de détails.
🙏 Remerciements
- Basé sur le plugin homebridge-blinds
- Communauté Homebridge pour l'inspiration
- zigbee2mqtt pour l'intégration Zigbee
- Merci à tous les contributeurs de la communauté Homebridge
Note : Ce plugin est conçu pour fonctionner avec des relais en mode impulsion ponctuelle. Assurez-vous que vos relais sont configurés correctement dans zigbee2mqtt.