Plugin Jeedom : « MatterBridge »(Documentation)

MrGreen

Présentation

Le plugin MatterBridge permet d’installer, piloter et superviser facilement MatterBridge depuis Jeedom.

MatterBridge est une passerelle permettant d’exposer des équipements domotiques Jeedom, somfy, zigbee2mqtt, shelly, zwavejs, et plus généralement tout ce qui est diffusé par MQTT, vers l’écosystème Matter, afin de les rendre disponibles dans des applications compatibles comme Amazon Alexa, Apple Maison, Google Home ou SmartThings.

Le plugin s’appuie sur le plugin officiel Docker Manager de Jeedom pour créer et gérer le conteneur MatterBridge. Il permet notamment de :

  • créer automatiquement le conteneur Docker MatterBridge
  • démarrer, arrêter et redémarrer le conteneur
  • suivre l’état du conteneur directement depuis Jeedom
  • ouvrir l’interface web MatterBridge
  • conserver les données MatterBridge dans un dossier persistant (sauvegardé par Jeedom)
  • choisir automatiquement l’image Docker adaptée à l’architecture du système
  • utiliser une image spécifique pour les systèmes 32 bits si nécessaire

Le plugin ne remplace pas l’interface officielle MatterBridge. Il sert principalement à simplifier son installation, sa supervision et son accès depuis Jeedom.

Après installation il se trouvera dans le menu « Passerelle Domotique » :

Installation

Prérequis

Avant d’utiliser le plugin MatterBridge 2, assurez-vous que votre installation Jeedom dispose des éléments suivants :

Plugin Docker Manager

Le plugin Docker Manager officiel de Jeedom doit être installé et activé.

Le plugin MatterBridge 2 utilise Docker Manager pour créer, supprimer, démarrer et arrêter le conteneur MatterBridge.

Docker fonctionnel

Docker doit être correctement installé et fonctionnel sur la machine Jeedom.

Vous pouvez vérifier Docker en SSH avec :

sudo docker ps

Si la commande retourne une liste de conteneurs, même vide, Docker est bien accessible.

Réseau

MatterBridge utilise par défaut le port :

8283

L’interface web sera donc accessible à l’adresse :

http://IP_JEEDOM:8283/

Exemple :

http://192.168.1.50:8283/

Assurez-vous que ce port n’est pas déjà utilisé par un autre service.

Guide d’installation

1. Installer le plugin

Installez le plugin MatterBridge 2 dans Jeedom, puis activez-le.

Une fois le plugin activé, ouvrez sa page de configuration.

2. Vérifier la configuration

Dans la configuration du plugin, vérifiez les paramètres suivants :

Nom du conteneur
Par défaut :

matterbridge2

Il est conseillé de conserver ce nom afin d’éviter les conflits avec une autre installation MatterBridge.

Numéro Docker hôte
Par défaut :

1

Ce numéro correspond au Docker hôte configuré dans Docker Manager. Dans la majorité des installations Jeedom, la valeur 1 est correcte.

Dossier des données
Par défaut :

/var/www/html/plugins/matterbridge2/data/matterbridge

Ce dossier contient les données persistantes de MatterBridge :

Matterbridge
.matterbridge
.mattercert

Ces données sont conservées même si le conteneur Docker est supprimé ou recréé.

IP / hôte interface
Si ce champ est vide, le plugin utilise automatiquement l’adresse IP interne de Jeedom.
Vous pouvez aussi renseigner manuellement l’adresse IP de Jeedom, par exemple :

192.168.1.50

Port frontend
Par défaut :

8283

Ce port permet d’accéder à l’interface web MatterBridge.

Image Docker
Le mode recommandé est :

Auto selon architecture

Le plugin choisira automatiquement l’image Docker adaptée :

luligu/matterbridge:latest

ou, pour certains systèmes 32 bits :

luligu/matterbridge:s6-rc-legacy

3. Installer le conteneur Docker

Cliquez sur le bouton :

Installer / recréer le Docker

Le plugin affiche alors un journal de progression.

Les étapes principales sont :

Vérification de Docker Manager
Préparation des dossiers MatterBridge
Création ou mise à jour de l’équipement Docker Manager
Création du conteneur Docker
Attente du démarrage
Vérification de l’état final

Lorsque l’installation est terminée, l’état doit passer à :

Démarré

4. Démarrage après les autres plugins

Dans Surveillance des dépendances :

  1. Laissez MQTT Manager sélectionné : il est obligatoire.
  2. Cochez les plugins dont les équipements doivent être prêts avant MatterBridge, par exemple Zigbee2MQTT, Z-Wave JS ou tout autre plugin possédant un démon.
  3. Réglez le Délai de boucle. La valeur par défaut est de 30 secondes ; la valeur minimale est de 10 secondes.
  4. Enregistrez la configuration.

MatterBridge reste arrêté tant qu’une dépendance sélectionnée n’est pas prête. Après le démarrage de toutes les dépendances, le plugin attend encore 30 secondes avant de démarrer ou redémarrer MatterBridge. Si l’un de ces démons est relancé plus tard, le changement est détecté et MatterBridge est redémarré lorsque l’ensemble est de nouveau prêt.

5. Ouvrir l’interface MatterBridge

Une fois le conteneur démarré, cliquez sur :

Ouvrir MatterBridge

L’interface MatterBridge s’ouvre dans un nouvel onglet.

L’adresse est généralement de la forme :

http://IP_JEEDOM:8283/

6. Sécuriser l’interface

Lors du premier accès à MatterBridge, il est recommandé de modifier le mot de passe depuis l’interface MatterBridge :

Settings → Change password

7. Appairer avec Alexa ou un contrôleur Matter

Dans l’application Alexa ou dans un autre contrôleur Matter compatible :

Ajouter un appareil
Autre
Matter
Scanner le QR Code affiché dans MatterBridge

Les équipements exposés par MatterBridge seront ensuite disponibles dans l’écosystème Matter.

Aide à l’utilisation de Matter Bridge

Cette section présente un exemple simple d’utilisation de MatterBridge avec le plugin Shelly.

L’objectif est d’installer le plugin Shelly dans MatterBridge, puis d’exposer uniquement un équipement nommé Chauffe eau grâce à la liste blanche.

Ouvrir l’interface MatterBridge

Depuis Jeedom, ouvrez le plugin MatterBridge 2, puis cliquez sur :

Ouvrir MatterBridge

L’interface MatterBridge s’ouvre dans un nouvel onglet de votre navigateur.

En haut vous trouverez les menus :
HOME : Page d’état, avec une partie Install plugins pour installer les plugins. Dessous la liste des plugins installés et encore dessous la liste des équipements.

DEVICES : Uniquement la liste des équipements.

LOGS : Logs Matter Bridge avec filtre possible.

SETTINGS : Divers paramétrages.

A savoir : Toute modification nécessite un redémarrage de MatterBridge. Pour cela cliquez sur cette icône de l’interface :

Installer le plugin

Pour l’exemple, nous allons prendre le plugin Shelly.

Pour savoir si Matter Bridge est compatible avec un plugin que vous recherchez, allez sur le site https://matterbridge.io/ menu Plugins, parcourez la liste et cliquez sur « Learn more », vous arriverez sur la page du plugin et généralement le nom du plugin est placé ici :

Dans l’interface MatterBridgen Menu Home, partie « Install Plugins » :

Mettre le nom du plugin dans « Plugin name or plugin path » et cliquez sur le bouton INSTALL.

Paramètres du plugin

Avant tout : Allez dans vos équipements Shelly et donnez leurs un nom dans l’interface Shelly (nom compatible avec une phrase : Alexa, allume le chauffe eau)

Chaque plugin a son paramétrage différent. Pour Zigbee2mqtt, on va donner des informations comme la connexion au serveur mqtt (ip / port / utilisateur et mot de passe), et le Topic de base.
Pour le plugin Shelly, il faut que tous les appareils Shelly ait le même nom d’utilisateur et mot de passe admin. Nous allons renseigner cette information dans les paramètres du plugin.

Pour cela, dans la section Plugins, cliquez sur la roue crantée en face du plugin.

Renseignez les champs « username » et « password » qui sont les noms d’utilisateur (généralement admin) et mot de passe de vos Shelly.

Cliquez sur CONFIRM (en bas de la page)

Et redémarrez Matter Bridge avec le bouton vu plus haut :

Découverte des équipements Shelly

Le plugin Shelly va découvrir automatiquement les équipements Shelly présents sur le réseau local.

Une fois les équipements découverts, vous devriez voir vos modules Shelly dans l’interface MatterBridge, dans la liste « Devices ».

Dans l’état actuel, tous les équipements seront envoyés à Alexa.

Dans notre exemple, nous voulons uniquement exposer à Alexa Chauffe eau, Télévision et couloir bas.
Deux solutions, soit vous décochez les cases des équipements à ne pas envoyer à Alexa, soit vous allez dans la roue crantée en face du plugin Shelly et vous renseignez la Whitelist ou la Blacklist.

Personnellement, je préfère utiliser la Whitelist pour éviter que tout nouvel équipement soit automatiquement exposé à Alexa. Pour cela, cliquez sur la roue crantée en face du plugin et renseignez la Whitelist. Pour valider cliquez sur CONFIRM en bas et pensez à redémarrer Matter Bridge.

Pour ajouter un élément à la Whitelist, cliquez sur les 3 barres

Le résultat sera le suivant :

Associer Amazon Alexa à la passerelle (bridge) Matter Bridge

Dans l’interface MatterBridge, dans HOME, affichez le QR Code.

Dans l’application Alexa, par exemple :

  • + en haut à droite → Ajouter un Appareil → Autre (tout en bas de la liste) → Matter → Scanner le QR Code (répondez positivement aux questions)

Une fois l’appairage terminé, les équipements devraient apparaître dans Alexa, mais vous pouvez toujours demander « Alexa, découvre les nouveaux équipements » pour qu’elle lance une recherche.

Notes importantes pour les équipements Shelly

Pour un fonctionnement fiable, il est recommandé d’avoir une adresse IP stable pour les modules Shelly. La documentation du plugin Shelly conseille de réserver l’adresse IP dans le routeur ou de configurer une IP statique dans l’interface Shelly. C’est particulièrement important pour les modules sur batterie.

Pour les modules Shelly Gen 1, la communication peut nécessiter l’activation de CoIoT dans les paramètres du module Shelly. Pour les modules Gen 2 ou Gen 3 sur batterie, la documentation indique que l’Outbound WebSocket peut être nécessaire avec une adresse du type ws://IP_MATTERBRIDGE:8485.

Dans la majorité des cas simples, les modules Shelly alimentés sur secteur sont découverts automatiquement si MatterBridge, Jeedom et les Shelly sont sur le même réseau local.

Aussi je vous conseille, d’ajouter 1 à 1 vos Shelly, car particularité de Shelly : Cela va créer deux équipements. Un avec le nom de l’équipement Matter, et un autre nommé Première Prise (qu’il faudra renommer en Chauffe eau par exemple)…
Pensez aussi à sélectionner le Type d’équipement (Prise ou Lumière) dans le même écran où vous allez modifier le nom.

Intégrer les équipements Jeedom dans MatterBridge

Cette fonctionnalité permet d’exposer directement dans MatterBridge des équipements déjà présents dans Jeedom. Les états et les commandes transitent par le courtier MQTT de MQTT Manager et par le plugin matterbridge-mqtt.

Principe de fonctionnement

Équipement Jeedom
        ↕
Plugin MatterBridge pour Jeedom
        ↕
MQTT Manager et son courtier MQTT
        ↕
Plugin matterbridge-mqtt
        ↕
MatterBridge → Alexa, Google Home, Apple Maison, etc.

Le plugin Jeedom publie la description et l’état de chaque équipement. MatterBridge renvoie ensuite les actions de l’écosystème Matter vers Jeedom par le même canal MQTT.

Prérequis

  • Le plugin MQTT Manager (mqtt2) doit être installé, activé et démarré.
  • Jeedom et MatterBridge doivent utiliser le même courtier MQTT.
  • Le plugin matterbridge-mqtt doit être installé et activé dans MatterBridge.

Important — Les identifiants demandés dans MatterBridge sont ceux du Plugin MQTT Manager.

1. Préparer MQTT Manager dans Jeedom

  1. Ouvrez Plugins → Gestion des plugins → MQTT Manager.
  2. Vérifiez que le plugin est activé et que son démon est démarré.
  3. Ouvrez sa configuration et relevez les informations du courtier utilisé :
  • l’adresse ou l’hôte ;
  • le port, généralement 1883 sans TLS ;
  • le nom d’utilisateur MQTT ;
  • le mot de passe MQTT.
  • Si MQTT Manager utilise le mosquitto local de Jeedom, aucune nouvelle installation de mosquitto n’est nécessaire.

Conservez ces informations : elles seront saisies dans la configuration de matterbridge-mqtt.

2. Installer et configurer matterbridge-mqtt

Ouvrir MatterBridge

  1. Ouvrez le plugin MatterBridge dans Jeedom.
  2. Vérifiez que le conteneur est indiqué comme Démarré.
  3. Cliquez sur Ouvrir MatterBridge.

Installer le plugin MQTT

Dans l’interface MatterBridge :

  1. Dans Install plugins.
  2. Tapez mqtt.
  3. Cliquez sur Install.
  4. Ouvrez sa configuration.

L’installation depuis l’interface est la méthode recommandée par MatterBridge. Le nom exact du paquet est matterbridge-mqtt.

Renseigner la connexion MQTT

Utilisez les valeurs suivantes comme modèle :

Champ MatterBridgeValeur à renseigner
Hostmqtt://127.0.0.1 si le courtier MQTT est installé sur le même Jeedom
PortLe port de MQTT Manager, généralement 1883
Protocol version5
Client IDFacultatif, par exemple matterbridge-jeedom
UsernameLe nom d’utilisateur de MQTT Manager
PasswordLe mot de passe de MQTT Manager
MQTT Topicmatterbridge, ou exactement la valeur définie dans le plugin Jeedom

Le conteneur créé par le plugin Jeedom utilise le réseau de l’hôte. Avec le mosquitto local de MQTT Manager, mqtt://127.0.0.1 est donc normalement la bonne adresse. Si le courtier se trouve sur une autre machine, utilisez mqtt://ADRESSE_IP_DU_COURTIER.

Exemple sans TLS :

{
  "host": "mqtt://127.0.0.1",
  "port": 1883,
  "protocolVersion": 5,
  "clientId": "matterbridge-jeedom",
  "username": "utilisateur_mqtt",
  "password": "mot_de_passe_mqtt",
  "topic": "matterbridge"
}

N’utilisez pas cet exemple tel quel : remplacez toujours les identifiants fictifs par ceux configurés dans MQTT Manager.

Pour un courtier TLS, utilisez mqtts://, le port adapté — souvent 8883 — et renseignez les certificats demandés par matterbridge-mqtt.

Appliquer la configuration

  1. Enregistrez la configuration de matterbridge-mqtt.
  2. Redémarrez le plugin MQTT ou MatterBridge si l’interface le demande.
  3. Consultez le Log MatterBridge et vérifiez que la connexion au courtier MQTT est établie sans erreur d’authentification.

3. Ajouter un équipement Jeedom

  1. Ouvrez la page du plugin MatterBridge dans Jeedom.
  2. Dans Équipements Jeedom exposés à MatterBridge, cliquez sur Ajouter un équipement Jeedom.
  3. Sélectionnez l’équipement dans l’arborescence Jeedom.
  4. Choisissez le Type MatterBridge correspondant à son usage réel.
  5. Modifiez si nécessaire le nom qui sera présenté dans MatterBridge.
  6. Affectez les commandes Jeedom aux fonctions Matter proposées.
  7. Cliquez sur Enregistrer.

L’enregistrement publie immédiatement la configuration de cet équipement vers MatterBridge.

Exemples d’affectation

ÉquipementType MatterBridgeCommandes à affecter
Lampe simpleLumière ON/OFFÉtat ON/OFF, Allumer, Éteindre
Lampe variableLumière variableON/OFF, luminosité actuelle, réglage de luminosité
Lampe blanc variableLumière température de couleurON/OFF, luminosité, température actuelle et réglage de température
Lampe RGB/RGBWLumière couleurON/OFF, luminosité, couleur actuelle et réglage de couleur ; température de couleur si disponible
Prise commandéePrise ON/OFFÉtat ON/OFF, Allumer, Éteindre
CapteurType de capteur correspondantSa commande d’information principale

Pour les fonctions binaires, cochez Inversion seulement si la commande Jeedom utilise une logique inversée. Une même fonction Matter ne peut être affectée qu’à une seule commande Jeedom.

Température de couleur

Pour rendre accessibles les choix blanc chaud et blanc froid :

  • utilisez Lumière température de couleur ou Lumière couleur ;
  • affectez Température couleur actuelle à la commande d’information Jeedom ;
  • affectez Régler température couleur à la commande d’action Jeedom ;
  • vérifiez que la commande Jeedom exprime correctement sa plage en kelvins ou en mireds.

Le plugin convertit les kelvins en mireds lorsque nécessaire et limite la valeur Matter à la plage valide 147..500 mireds.

4. Republier les équipements

Utilisez Republier vers MatterBridge après :

  • une modification de type ou d’affectation ;
  • un changement du topic MQTT ;
  • une mise à jour de matterbridge-mqtt ;
  • la suppression puis la réinstallation du plugin MQTT dans MatterBridge ;
  • une incohérence entre les équipements affichés dans Jeedom et ceux affichés dans MatterBridge.

Le plugin republie les messages conservés de configuration, d’état et d’abonnement. MatterBridge peut être redémarré automatiquement si les abonnements doivent être reconstruits.

Vérifications et dépannage

Aucun équipement n’apparaît dans MatterBridge

  1. Vérifiez que matterbridge-mqtt est installé, activé et connecté.
  2. Vérifiez que le MQTT Topic est identique des deux côtés.
  3. Vérifiez les identifiants MQTT et l’absence d’erreur d’authentification.
  4. Cliquez sur Republier vers MatterBridge.
  5. Consultez les journaux matterbridge2 et matterbridge2_MQTT dans Jeedom, ainsi que le journal MatterBridge.

L’état remonte mais les commandes ne fonctionnent pas

  • Vérifiez l’affectation des commandes d’action : Allumer, Éteindre, Régler le niveau, Régler la couleur ou Régler température couleur.
  • Dépliez l’équipement et utilisez Tester sur les commandes d’action.
  • Activez temporairement le niveau de journal Debug du plugin Jeedom pour voir les échanges MQTT détaillés.

Le blanc chaud ou le blanc froid ne fonctionne pas

  • Vérifiez que le type choisi prend en charge la température de couleur.
  • Vérifiez que les deux fonctions de température — état et action — sont affectées.
  • Republiez l’équipement, puis redémarrez MatterBridge si nécessaire.
  • Vérifiez dans le journal MatterBridge qu’une commande moveToColorTemperature produit bien un message MQTT write avec colorTemperatureMireds.

Alexa indique UnsupportedEndpoint

Cette erreur signale généralement que le point de terminaison connu d’Alexa ne correspond plus à celui actuellement exposé par MatterBridge. Procédez dans cet ordre :

  1. vérifiez que l’équipement existe et fonctionne dans MatterBridge ;
  2. republiez les équipements depuis Jeedom ;
  3. redémarrez MatterBridge ;
  4. relancez la détection des appareils dans Alexa ;
  5. supprimez uniquement l’ancien appareil Alexa en doublon si nécessaire.

Une réinitialisation complète de l’association Matter ne doit être envisagée qu’en dernier recours.

Bonnes pratiques de sécurité

  • N’utilisez jamais le compte administrateur Jeedom pour MQTT.
  • Créez ou conservez un compte MQTT dédié avec un mot de passe robuste.
  • Ne publiez pas de capture contenant le mot de passe MQTT.
  • Utilisez MQTT sur TLS lorsque le courtier est accessible au-delà du réseau local.
  • Sauvegardez la configuration Jeedom et les données persistantes MatterBridge avant une réinstallation importante.

Références

Non classé