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

1. Installation du plugin :

   npm install -g homebridge-blinds-zigbee-mqtt-relay

2. Redé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 :

1. Volet fermé (0%) → Commande UP : Envoie d'abord DOWN puis UP
2. Volet ouvert (100%) → Commande DOWN : Envoie d'abord UP puis DOWN
3. É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 → ON sont 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

1. Connexion MQTT échoue

   • Vérifiez l'adresse IP et le port
   • Contrôlez les identifiants de connexion
   • Testez la connectivité réseau

2. Volets ne répondent pas

   • Vérifiez les noms des relais dans zigbee2mqtt
   • Contrôlez la configuration des canaux
   • Vérifiez les logs Homebridge

3. Mouvements erratiques

   • Ajustez le queueDelay pour plus d'espacement
   • Vérifiez la durée d'ouverture (openDuration)
   • Contrôlez la logique des télécommandes

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

tomtom14z - GitHub | npm

📄 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.