Le plugin Matter permet d'ajouter, de piloter et de superviser des appareils compatibles Matter directement depuis Jeedom.
Il s'appuie sur python-matter-server (projet Home Assistant) pour communiquer avec les appareils Matter via le protocole CHIP/Matter, et expose une interface que Jeedom utilise pour contrôler les équipements.
✨ Principe de fonctionnement
Le plugin repose sur trois composants :
- python-matter-server — serveur Matter gérant les connexions avec les appareils
- Démon Python (matterd) — pont entre Jeedom et python-matter-server
- Jeedom — interface utilisateur, gestion des équipements et des commandes
Le flux de données est le suivant :
- Le démon interroge python-matter-server en continu (polling + souscriptions WebSocket)
- Chaque changement d'état est transmis à Jeedom via l'API REST du plugin
- Les commandes Jeedom sont relayées au démon qui les exécute sur le serveur Matter
Le plugin prend en charge deux modes de serveur :
- Embarqué : le plugin démarre et gère python-matter-server automatiquement
- Externe : le plugin se connecte à une instance python-matter-server existante (ex. Home Assistant)
🔧 Prérequis
Avant d'installer le plugin et d'ajouter un appareil Matter, assurez-vous d'avoir :
🌐 1️⃣ Un réseau local stable
- Jeedom doit être connecté au même réseau que vos appareils
- Wi‑Fi fonctionnel et stable
- Pas d'isolation réseau entre les équipements
- IPv6 est requis pour la découverte mDNS des appareils Matter (vérifiable sur la page Santé)
📡 2️⃣ Un contrôleur Matter
Matter nécessite un contrôleur pour gérer les appareils.
Le plugin Matter peut jouer ce rôle et devenir votre contrôleur principal.
⚠️ Il est recommandé de ne pas utiliser plusieurs contrôleurs principaux en parallèle si vous débutez.
🧵 3️⃣ Un Border Router (si appareil Thread)
Certains appareils Matter utilisent la technologie Thread.
Dans ce cas, vous devez disposer d'un Thread Border Router.
Exemples compatibles :
- Apple HomePod (2e génération)
- Apple TV 4K récente
- Amazon Echo compatible Thread
- Google Nest Hub (2e génération)
- Dongle OTBR (OpenThread Border Router)
⚠️ Les appareils Matter en Wi‑Fi ou Ethernet n'ont pas besoin de Border Router.
🍎🤖 4️⃣ Appareils déjà configurés dans Apple, Amazon ou Google
Si votre appareil est déjà ajouté dans :
- Apple Home
- Amazon Alexa
- Google Home
Deux possibilités :
- Soit Jeedom devient le contrôleur principal
- Soit vous partagez l'appareil vers Jeedom (si supporté)
Il est conseillé d'éviter les configurations multiples si vous débutez.
🔵 5️⃣ Clé Bluetooth (pour le jumelage Wi‑Fi)
Le Bluetooth est utilisé uniquement lors du jumelage des appareils Matter Wi‑Fi pour leur transmettre les informations réseau. Il n'est pas nécessaire pour le fonctionnement quotidien ni pour les appareils Thread ou Ethernet.
Si votre Jeedom ne dispose pas de Bluetooth intégré, vous pouvez utiliser une clé USB Bluetooth (adaptateur BT 4.0 ou 5.0).
Sans Bluetooth disponible, cochez l'option Réseau uniquement lors du jumelage. Cela fonctionne si l'appareil est déjà accessible sur le réseau local (appareils Thread via Border Router, ou appareils Wi‑Fi déjà provisionnés).
🔑 6️⃣ Code Matter obligatoire
Pour l'inclusion, vous aurez besoin du code à 11 chiffres de votre appareil.
Récupérer le code depuis Apple Maison
- Ouvrez l'application Maison sur votre iPhone ou iPad
- Maintenez le doigt appuyé sur l'accessoire Matter à partager
- Appuyez sur Réglages de l'accessoire (icône d'engrenage en bas à droite)
- Faites défiler vers le bas et appuyez sur Activer le mode de jumelage
- L'application génère un code numérique à 11 chiffres (et parfois un QR code)
- Appuyez sur Copier le code
Récupérer le code depuis Google Home
- Ouvrez l'application Google Home
- Maintenez le doigt sur la tuile de votre appareil Matter
- Appuyez sur l'icône Paramètres (roue crantée) en haut à droite
- Appuyez sur Applications et services Matter associés
- Appuyez sur Associer des applications et des services
- Sélectionnez Utiliser un code d'association (ou "Partager avec un code QR")
- Un code numérique à 11 chiffres s'affiche
Récupérer le code depuis Amazon Alexa
- Ouvrez l'application Amazon Alexa
- Appuyez sur l'onglet Appareils en bas de l'écran
- Sélectionnez l'accessoire Matter à partager
- Appuyez sur l'icône Paramètres (roue crantée) en haut à droite
- Sélectionnez Autres assistants et applications
- Appuyez sur Ajouter un autre
- Un code numérique à 11 chiffres s'affiche
🚀 Installation
Étape 1 — Installer le plugin depuis le Market
- Allez dans Plugins → Gestion des plugins → Market
- Recherchez Matter
- Cliquez sur Installer
- Activez le plugin
Étape 2 — Installer les dépendances
Les dépendances incluent python-matter-server, ses dépendances CHIP/Matter et les bibliothèques Python nécessaires. L'installation peut prendre 5 à 15 minutes selon votre machine.
- Allez dans Plugins → Matter → Configuration
- Cliquez sur Installer les dépendances
- Attendez que le statut passe à OK avant de continuer
⚠️ Ne redémarrez pas la page pendant l'installation. Vous pouvez suivre la progression dans les logs (
log/matter).
Étape 3 — Démarrer le démon
- Toujours dans la configuration, cliquez sur Démarrer (section Démon)
- Attendez que le statut passe au vert ✅
Quand les deux voyants Démon et Serveur Matter sont verts, le plugin est opérationnel.
⚙️ Configuration
Mode serveur
| Mode | Description |
|---|---|
| Auto (défaut) | Le plugin détecte si un serveur Matter est déjà actif. Sinon, il le démarre. |
| Embarqué | Le plugin démarre et gère python-matter-server lui-même. |
| Externe | Le plugin se connecte à une instance existante (ex. Home Assistant). |
Paramètres disponibles
| Paramètre | Valeur par défaut | Description |
|---|---|---|
| Mode serveur | auto | Voir tableau ci-dessus |
| Port serveur | 5580 | Port TCP de python-matter-server (WebSocket) |
| URL serveur Matter | http://127.0.0.1:5580/ws | URL WebSocket (mode externe uniquement) |
| Token Matter | (vide) | Token d'authentification (si requis) |
| Port démon | 55123 | Port RPC HTTP du démon Jeedom |
| Adaptateur Bluetooth | auto | Sélection de l'adaptateur BT pour le jumelage |
En mode externe, renseignez l'URL WebSocket de votre serveur Matter (ex.
ws://192.168.1.50:5580/ws).
➕ Ajouter un appareil Matter
Étape 1 — Récupérer le code de jumelage
Le code se trouve généralement :
- Imprimé sur une étiquette sous l'appareil
- Dans l'application du fabricant (format QR code ou code numérique)
- Sous la forme
MT:XXXXXXXXXX(QR code scannable)
Si l'appareil est déjà appairé avec un autre écosystème, selon votre configuration :
- Partagez-le depuis l'application d'origine (si la fonctionnalité est disponible)
- Ou réinitialisez l'appareil en usine pour le réappaire depuis zéro
Étape 2 — Jumelage dans Jeedom
- Allez dans Plugins → Matter → Configuration
- Dans la section Jumelage, collez le code Matter (numérique ou
MT:…) - Cochez Réseau uniquement si vous ne voulez pas utiliser le Bluetooth
- Cliquez sur Jumeler
- L'opération peut prendre jusqu'à 3 minutes
Le Bluetooth n'est nécessaire que pour les appareils Wi-Fi lors de la phase de provisioning réseau. Les appareils Thread ou déjà sur le réseau peuvent être appairés en mode réseau uniquement.
Étape 3 — Synchronisation automatique
Après un jumelage réussi, le plugin synchronise automatiquement le nœud Matter et crée l'équipement Jeedom correspondant.
Vous pouvez aussi déclencher une synchronisation manuelle via le bouton Synchroniser sur la page de configuration.
🖥️ Page Équipement
Chaque appareil Matter apparaît comme un équipement Jeedom avec deux onglets.
Onglet Équipement
Contient les informations générales et les métadonnées Matter (en lecture seule) :
- Fabricant / Produit : informations récupérées depuis l'appareil
- Types de device : types Matter détectés (ex.
OnOff Light,Door Lock) - Clusters : liste des clusters Matter présents sur l'appareil
Onglet Commandes
Liste des commandes créées automatiquement selon les clusters détectés.
📊 Commandes par type d'appareil
Les commandes sont créées automatiquement en fonction des clusters Matter présents sur l'appareil.
Ampoules et prises On/Off
| Commande | Type | Description |
|---|---|---|
on | Action | Allumer |
off | Action | Éteindre |
state | Info | État (0/1) |
Ampoules dimmables
| Commande | Type | Description |
|---|---|---|
on / off | Action | Allumer / Éteindre |
state | Info | État (0/1) |
setLevel | Action (slider) | Niveau de luminosité (0–100 %) |
level | Info | Niveau actuel |
Ampoules couleur (Extended Color Light)
Toutes les commandes dimmables, plus :
| Commande | Type | Description |
|---|---|---|
setColor | Action | Définir la couleur RGB |
color | Info | Couleur actuelle (hex) |
setColorTemperature | Action (slider) | Température de couleur (en mireds) |
colorTemperature | Info | Température actuelle |
ct_cool | Action | Preset froid (~4000 K) |
ct_neutral | Action | Preset neutre (~3000 K) |
ct_warm | Action | Preset chaud (~2700 K) |
Serrures connectées
| Commande | Type | Description |
|---|---|---|
lock | Action | Verrouiller |
unlock | Action | Déverrouiller |
lock_state | Info | État (Locked / Unlocked / Jammed) |
set_lock_mode | Action | Mode de la serrure |
Modes disponibles pour set_lock_mode :
Normal— fonctionnement standardVacation— verrouillage renforcéPrivacy— ne pas dérangerNoRemoteLockUnlock— blocage des commandes distantes
Capteurs d'environnement
| Capteur | Commande | Type |
|---|---|---|
| Température | temperature | Info (°C) |
| Humidité | humidity | Info (%) |
| Luminosité | illuminance | Info (lux) |
| Présence/Occupation | occupancy | Info (0/1) |
| Contact (porte/fenêtre) | contact | Info (0/1) |
Thermostats
| Commande | Type | Description |
|---|---|---|
local_temperature | Info | Température mesurée |
occupied_heating_setpoint | Info/Action | Consigne chauffage |
occupied_cooling_setpoint | Info/Action | Consigne refroidissement |
system_mode | Info | Mode actuel |
Boutons et télécommandes
Les boutons génèrent des commandes événementielles selon les pressions détectées :
| Commande | Description |
|---|---|
shortPress | Appui court |
longPress | Appui long |
doublePress | Double appui |
Les boutons multi-touches créent des commandes par touche (ex.
button1_shortPress,button2_longPress).
Volets et stores
| Commande | Type | Description |
|---|---|---|
open | Action | Ouvrir |
close | Action | Fermer |
stop | Action | Arrêter |
position | Info | Position actuelle (%) |
Capteurs d'énergie
| Commande | Description |
|---|---|
activePower | Puissance active (W) |
voltage | Tension (V) |
current | Courant (A) |
energy | Énergie consommée (kWh) |
Batterie
| Commande | Description |
|---|---|
battery | Niveau de batterie (%) |
batteryVoltage | Tension batterie (V) |
❤️ Page Santé
La page Santé (accessible via le bouton Santé sur la page du plugin) affiche un rapport de diagnostic complet.
Vérifications effectuées
| Vérification | Description |
|---|---|
| Version Python | Doit être ≥ 3.10 |
| Environnement virtuel | Présence et intégrité du venv Python |
| Démon | Statut du processus matterd |
| RPC démon | Disponibilité de l'API RPC locale |
| Mode serveur | Configuration du mode serveur |
| Serveur Matter (systemd) | Statut du service python-matter-server |
| Connexion Matter server | Connectivité WebSocket vers le serveur |
| Répertoire de données | Présence et accessibilité du stockage |
| Bluetooth | Disponibilité de l'adaptateur BT système |
| IPv6 | Configuration réseau IPv6 (requis pour mDNS) |
Actions disponibles
- Diagnostiquer : rafraîchit le rapport de santé
- Réparation auto : tente de corriger automatiquement les problèmes détectés
- Mode jumelage : active le mode commissioning Bluetooth
🔁 Synchronisation
Synchronisation complète
Lance une resynchronisation de tous les nœuds Matter connus. Utile après une mise à jour du firmware d'un appareil ou en cas de dérive des commandes.
Via la configuration :
- Allez dans Plugins → Matter → Configuration
- Cliquez sur Synchroniser
Synchronisation d'un nœud spécifique
Disponible directement sur la fiche équipement si un nœud doit être resynchronisé individuellement.
🛠️ Utilisation dans les scénarios
Les commandes Matter s'utilisent comme n'importe quelle commande Jeedom dans vos scénarios.
Exemples d'usage :
# Allumer une lampe
[Salon][Ampoule Matter][on]
# Régler à 50 % de luminosité
[Salon][Ampoule Matter][setLevel] = 50
# Vérifier si la porte est verrouillée
SI [Entrée][Serrure Matter][lock_state] = Locked ALORS ...
# Déclencher sur présence
SI [Couloir][Capteur Matter][occupancy] = 1 ALORS ...
🧩 Mode Serveur Externe (Home Assistant)
Si vous avez déjà Home Assistant avec python-matter-server actif, vous pouvez partager la même instance :
- Dans la configuration, sélectionnez Mode : Externe
- Renseignez l'URL WebSocket :
ws://<ip-home-assistant>:5580/ws - Ajoutez le token si nécessaire
- Sauvegardez et redémarrez le démon
⚠️ En mode externe, le fabric Matter est partagé. Les appareils appairés dans HA seront également visibles dans Jeedom, mais chaque écosystème maintient sa propre liste de commandes.
🐛 Dépannage
Le démon ne démarre pas
- Vérifiez que les dépendances sont bien installées (statut OK)
- Consultez les logs
log/matterdpour identifier l'erreur - Vérifiez que le port
55123(démon RPC) n'est pas occupé - Utilisez Réparation auto sur la page Santé
Le jumelage échoue
- Vérifiez que le code Matter est correct (11 chiffres ou format
MT:…) - Assurez-vous que l'appareil est en mode commissioning (LED clignotante)
- Essayez avec l'option Réseau uniquement décochée (pour activer le Bluetooth)
- Augmentez le délai si l'appareil est lent à répondre (timeout 180 s par défaut)
- Vérifiez que IPv6 est actif sur votre réseau (page Santé)
L'appareil est créé mais ne répond pas
- Vérifiez que l'appareil est alimenté et sur le même réseau
- Lancez une Synchronisation manuelle
- Consultez les logs
log/matterpour les erreurs RPC - Vérifiez la connectivité avec le serveur Matter depuis la page Santé
Les commandes ne se créent pas
- Vérifiez les clusters détectés dans l'onglet Équipement
- Relancez une synchronisation complète
- Si le problème persiste, supprimez l'équipement et re-synchronisez le nœud
Après mise à jour des dépendances
Après chaque mise à jour majeure des dépendances :
- Arrêtez le démon
- Relancez l'installation des dépendances
- Redémarrez le démon
- Vérifiez la page Santé
📋 Appareils compatibles
Le plugin supporte tout appareil certifié Matter 1.x, notamment :
- Ampoules et spots (on/off, variateur, couleur)
- Prises connectées
- Serrures connectées
- Capteurs de température et d'humidité
- Capteurs de luminosité
- Détecteurs de présence / mouvement
- Capteurs d'ouverture (porte, fenêtre)
- Thermostats
- Volets et stores
- Boutons et télécommandes
- Compteurs d'énergie
🎉 Conclusion
Le plugin Matter offre une intégration complète du protocole Matter dans Jeedom :
- Découverte automatique des capacités de chaque appareil via les clusters
- Commandes générées automatiquement selon les fonctionnalités détectées
- Supervision intégrée avec la page Santé et les logs
- Compatible avec les installations existantes (mode serveur externe)
Installation → Jumelage → Utilisation dans vos scénarios et votre dashboard Jeedom.