Le plugin Matter permet d'ajouter, de piloter et de superviser des appareils compatibles Matter directement depuis Jeedom.
Il s'appuie sur Matter Server (JS) (projet Home Assistant) pour communiquer avec les appareils Matter via le protocole Matter, et expose une interface que Jeedom utilise pour contrôler les équipements.
Relancez toujours l'installation des dépendances après une mise à jour du plugin Matter.
👉 Plugins → Matter → Configuration → Installer les dépendances
Puis redémarrez le démon. Ne pas le faire peut provoquer des erreurs de démarrage ou des dysfonctionnements.
✨ Principe de fonctionnement
Le plugin repose sur trois composants :
- Matter Server (JS) — serveur Matter gérant les connexions avec les appareils
- Démon nodejs (matterd) — pont entre Jeedom et Matter Server (JS)
- Jeedom — interface utilisateur, gestion des équipements et des commandes
Le flux de données est le suivant :
- Le démon interroge Matter Server (JS) 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 Matter Server (JS) automatiquement
- Externe : le plugin se connecte à une instance Matter Server (JS) 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).
Mode BLE Proxy (Bluetooth distant)
Si votre Jeedom n'a pas de Bluetooth mais qu'une autre machine sur votre réseau en dispose (PC Windows, Raspberry Pi, Home Assistant…), vous pouvez utiliser le mode BLE Proxy.
Dans ce mode, le serveur Matter expose un endpoint WebSocket ws://<ip-jeedom>:5580/ble sur lequel un client distant se connecte et proxy toutes les opérations Bluetooth (scan, connexion GATT, BTP).
Activation :
- Dans Plugins → Matter → Configuration, section Commissioning, cochez BLE Proxy (distant)
- Sauvegardez et redémarrez le démon
- Sur la machine distante, lancez un client BLE Proxy compatible, par exemple le script Python disponible ici : https://github.com/Zyg0m4t1k/ble-proxy-client
# Python (Windows / Linux / macOS) — nécessite : pip install websockets bleak
python ble_proxy_client.py ws://192.168.1.x:5580/ble
Le mode BLE Proxy et l'adaptateur Bluetooth local sont mutuellement exclusifs. Activez l'un ou l'autre.
🔑 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 Matter Server (JS) et les modules nécessaires au fonctionnement du démon.
L'installation peut prendre 2 à 5 minutes selon votre machine.
- Allez dans Plugins → Matter → Configuration
- Cliquez sur Installer les dépendances
- Attendez que le statut passe à OK avant de continuer
⚠️ Cette étape installe automatiquement :
- Node.js (si nécessaire)
- Les dépendances npm (
matter-server,ws, etc.)
⚠️ Ne redémarrez pas la page pendant l'installation. Vous pouvez suivre la progression dans les logs
É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 Matter Server (JS) 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 du 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 (Node.js) |
| 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).
Niveau de log
Le niveau de log du plugin fonctionne sur un principe simple :
- Le niveau configuré dans Jeedom est la référence (sélecteur natif Jeedom dans la Configuration, ou boutons Debug/Info/…/Error de la section Niveau de log). C'est la valeur persistante — elle est relue à chaque démarrage du démon.
- Les logs démon (
matterd) et PHP (matter) utilisent ce niveau au démarrage.
La page de configuration affiche le niveau actif pour chaque composant sous forme de badges colorés :
| Badge | Composant |
|---|---|
| Wrapper | Niveau actif dans le script rpc-wrapper.mjs |
| Daemon | Niveau actif dans le processus daemon.js |
| Server | Niveau de log du serveur Matter (Python Matter Server) |
Les boutons Debug / Info / Notice / Warning / Error changent le niveau à chaud et le sauvegardent. Le bouton du niveau actif est mis en évidence en bleu.
Indicateur visuel
Lorsque les logs sont en mode verbose (Debug, Info ou Notice), un bandeau orange apparaît sur la page principale du plugin et une alerte s'affiche dans la Configuration pour rappeler de remettre le niveau en production.
Tout disparaît automatiquement dès que le niveau est remis sur Warning ou Error.
Contrôle fin par composant (page Santé)
La page Santé permet de régler le niveau de chaque composant indépendamment :
| Cible | Persistant | Usage |
|---|---|---|
| Jeedom + Wrapper | Oui — sauvegardé | Niveau de référence pour le prochain démarrage |
| Daemon | Non — live uniquement | Debug temporaire du processus daemon.js |
| Server | Non — live uniquement | Debug temporaire du serveur Matter |
Pour un debug rapide sans modifier le niveau de référence, utilisez les boutons Daemon ou Server de la page Santé (persist=non). Le niveau revient à la référence au prochain redémarrage du démon.
En production, utilisez Warning ou Error pour réduire le volume de logs.
➕ Ajouter un appareil Matter
Étape 1 — Récupérer le code de jumelage
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 Commissioning, collez le code Matter (numérique ou
MT:…) - Cochez Réseau uniquement si vous ne voulez pas utiliser le Bluetooth
- Cliquez sur Commissionner
- 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
Section Debug
L'onglet Équipement contient une section Debug avec deux boutons :
| Bouton | Description |
|---|---|
| Infos avancées du nœud | Affiche une vue structurée des clusters, attributs et endpoints du nœud Matter |
| Dump node brut | Récupère et affiche la structure JSON complète du nœud Matter (clusters, attributs, endpoints) |
La modal Infos avancées présente les données de façon lisible par cluster et endpoint. Le Dump node brut affiche le JSON complet avec un bouton Copier pour faciliter le partage lors d'un ticket de support.
La version firmware et les éventuelles mises à jour OTA disponibles sont visibles dans la Page Santé (tableau centralisé de tous les équipements).
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 |
is_locked | Info binaire | Verrouillée (1) / Déverrouillée (0) |
lock_state_text | Info texte | État lisible (Verrouillé / Déverrouillé / Bloqué) |
lock_state_raw | Info numérique | Valeur brute Matter (0/1/2/3) |
set_lock_mode | Action | Mode de la serrure |
lock_last_action | Info | Dernière action (Verrouillage, Déverrouillage…) |
lock_last_source | Info | Source (Manuel, Clavier, Distant, Biométrique…) |
lock_last_credential | Info | Type de credential (Code PIN, RFID, Empreinte…) |
lock_last_date | Info | Horodatage de la dernière action |
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) |
Mise à jour firmware (OTA)
Créées automatiquement si l'appareil le supporte.
| Commande | Description |
|---|---|
ota_update_state | État de la mise à jour (valeur numérique, voir tableau ci-dessous) |
ota_update_progress | Progression en % (-1 si non applicable) |
| Valeur | Signification |
|---|---|
| 0 | Unknown |
| 1 | Idle — pas de mise à jour en cours |
| 2 | Querying — interrogation du serveur OTA |
| 3 | DelayedOnQuery — nouvel essai différé |
| 4 | Downloading — téléchargement en cours |
| 5 | Applying — installation en cours |
| 6 | DelayedOnApply — application différée |
| 7 | RollingBack — retour arrière |
| 8 | DelayedOnUserConsent — attente confirmation utilisateur |
❤️ Page Santé
La page Santé (bouton Santé sur la page principale du plugin) affiche un tableau centralisé de tous vos équipements Matter avec leur état en temps réel.
Colonnes du tableau
| Colonne | Description |
|---|---|
| ID | Numéro de nœud Matter |
| Nom | Nom de l'équipement Jeedom |
| Actif | L'équipement est activé dans Jeedom |
| Visible | L'équipement est visible dans Jeedom |
| Disponible | 🟢 Joignable / 🔴 Non joignable (temps réel) |
| Produit | Fabricant et nom du produit |
| Firmware actuel | Version installée sur l'appareil |
| MAJ disponible | Version disponible via OTA (badge jaune si mise à jour) |
| Dernière vérif. | Date de la dernière vérification firmware |
| Types Matter | Types de device Matter détectés |
Actions disponibles
- Actualiser : recharge le tableau
- Vérifier tous les firmware : lance une vérification OTA sur tous les équipements
- Mettre à jour (bouton par ligne) : déclenche la mise à jour firmware directement depuis le tableau, sur les équipements pour lesquels une version plus récente est disponible (badge jaune)
L'indicateur Disponible (🟢/🔴) reflète la valeur de la commande available de chaque équipement, mise à jour en temps réel par le démon.
Indicateur de disponibilité sur la page principale
Un point vert ou rouge apparaît également sur chaque carte d'équipement de la page principale du plugin, permettant de voir en un coup d'œil quels appareils sont joignables.
🔍 Page Diagnostic
La page Diagnostic (bouton Diagnostic sur la page principale) affiche un rapport de vérification complet de l'état du plugin.
Vérifications effectuées
| Vérification | Description |
|---|---|
| Node.js | Version installée et compatible |
| npm | Gestionnaire de paquets Node.js disponible |
| Matter Server (JS) | Installation du module matter-server |
| Démon | Statut du processus matterd (Node.js) |
| RPC démon | Disponibilité de l'API RPC locale |
| 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) |
| Docker / OTBR | Statut du conteneur et du réseau Thread (si activé) |
Actions disponibles
- Diagnostiquer : rafraîchit le rapport
- Réparation auto : tente de corriger automatiquement les problèmes détectés
- Mode jumelage : active le mode commissioning Bluetooth
Diagnostic IPv6 / Thread
La page Santé intègre des contrôles avancés pour identifier les problèmes de commissionnement Thread, particulièrement utiles sur les VM et environnements virtualisés.
Vérifications IPv6 effectuées
| Vérification | Description |
|---|---|
ipv6_kernel | IPv6 activé au niveau noyau (/proc/sys/.../all/disable_ipv6) |
ipv6_iface | IPv6 activé sur l'interface réseau Matter (route par défaut) |
ipv6_linklocal | Présence d'une adresse fe80:: (minimum requis) |
ipv6_global | Présence d'une adresse globale/ULA — bloquant si absente (commissioning Thread impossible) |
ipv6_forwarding | Forwarding IPv6 actif = warning (mode routeur non recommandé) |
ipv6_accept_ra | Warning uniquement si accept_ra=0 ET aucune adresse globale/ULA |
ipv6_nmcli | NetworkManager présent et interface gérée (bloquant si absent) |
ipv6_thread_routes | Routes ULA Thread (fdxx::/64) détectées via les Route Information Options |
Détection des routes Thread
Le plugin vérifie la présence de routes Thread de la forme fdxx::/64 :
fd54:cc13:a99f::/64 via ...
fde3:c292:b227:1::/64 via ...
Leur présence confirme que les annonces du Border Router (HomePod, OTBR…) sont correctement prises en compte. L'absence de ces routes est souvent la cause réelle d'un commissionnement Thread impossible, même quand IPv6 semble actif.
Correction automatique
Si aucune route Thread n'est détectée, un bouton Corriger permet d'appliquer automatiquement :
net.ipv6.conf.<interface>.accept_ra_rt_info_max_plen=64
Ce paramètre autorise Linux à accepter les routes annoncées via les Route Information Options (RIO) des Border Routers Thread. Il est persistant (ajouté dans /etc/sysctl.d/).
Cas typique sur VM
Sur une VM avec IPv6 actif et HomePod/OTBR fonctionnel, le commissionnement Thread peut échouer silencieusement si :
accept_ra_rt_info_max_plen = 0 ← valeur par défaut Linux
Après correction via la page Santé :
Routes Thread fdxx:: détectées → commissionnement Thread fonctionnel
Bonnes pratiques VM / Docker
- Utiliser un réseau bridge (éviter le NAT)
- Vérifier IPv6 directement dans la VM (pas seulement sur l'hôte)
- Appliquer les paramètres IPv6 dans la VM elle-même
- Utiliser
--network=hostpour Docker si Matter Server est conteneurisé - Éviter les réflecteurs mDNS / Avahi qui peuvent interférer
Diagnostic rapide en CLI
# Vérifier les routes Thread
ip -6 route | grep "^fd"
Si aucune route fdxx::/64 n'apparaît alors que vous avez un Border Router actif, utilisez le bouton Corriger de la page Santé.
🔁 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 utilisez déjà Home Assistant avec Matter Server (JS) 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 puis redémarrez le démon
⚠️ En mode externe, le fabric Matter est partagé.
Les appareils déjà appairés dans Home Assistant seront visibles dans Jeedom,
mais chaque contrôleur conserve ses propres commandes et états.
🔧 OTBR / Thread (mode avancé)
Cette section est destinée aux utilisateurs souhaitant utiliser Thread localement avec Jeedom via un dongle OTBR.
📡 Principe
Le plugin Matter peut fonctionner avec :
- 🌐 Un serveur Matter externe (Home Assistant, etc.)
- 🔌 Un réseau Thread local via OTBR (Docker + dongle)
👉 Dans ce mode, Jeedom devient autonome pour :
- le commissioning Thread
- la gestion du réseau Thread
- la communication avec les devices
🧱 Prérequis OTBR
- Docker installé et fonctionnel
- Utilisateur
www-datadans le groupedocker - Un dongle ou hub Thread compatible (voir ci-dessous)
🔌 Modes de connexion du dongle Thread
Le plugin supporte trois façons de connecter votre dongle Thread, selon votre matériel.
Mode OTBR
Choisissez d’abord comment OTBR fonctionne :
| Mode | Quand l’utiliser |
|---|---|
| Local (USB + Docker) | Le dongle est branché directement sur le serveur Jeedom |
| Distant | OTBR tourne sur un hub réseau séparé (ex : SLZB-06xU avec OTBR intégré) |
1. USB — Dongle branché directement
C’est le cas le plus courant : votre clé Thread est branchée sur un port USB du serveur Jeedom.
- Le plugin détecte automatiquement les dongles disponibles
- Choisissez de préférence le chemin
/dev/serial/by-id/...(stable, ne change pas au redémarrage)
Matériels compatibles : Sonoff Zigbee Dongle Plus (Thread), SkyConnect, Slaesh CC2652RB, tout stick Thread USB
Paramètres UART : la plupart des dongles fonctionnent sans configuration supplémentaire. Si votre clé ne se connecte pas, utilisez un préréglage :
| Préréglage | Matériel |
|---|---|
| Slaesh CC2652RB | Slaesh CC2652RB |
| SLZB Thread RCP (EFR32) | SLZB-06x en USB |
2. TCP via socat — Clé Thread sur le réseau (recommandé pour SLZB)
Votre clé Thread est connectée à un appareil réseau qui expose son port série via TCP (Serial-over-IP). Le plugin crée automatiquement un pont local via socat.
- Saisir l’adresse de votre appareil au format
ip:port(port 6638 par défaut) - Exemple :
192.168.1.10:6638
Matériels compatibles : SLZB-06x, SLZB-MR4U et tout adaptateur Serial-over-IP
Mode à activer sur le dongle : Thread to remote OTBR
Paramètre UART recommandé pour ces appareils : utiliser le préréglage TCP via socat (EFR32/SLZB-MR4U)
Ce mode est plus fiable que le TCP direct pour les appareils SLZB car socat gère la conversion du protocole série.
En mode Thread to remote OTBR, l’API REST du dongle (port 8080) est désactivée sur le dongle lui-même. Un curl http://ip-du-dongle:8080 qui échoue est normal et attendu dans cette configuration. Seul le port série TCP (6638) est utilisé.
Configuration Jeedom (exemple SLZB sur 192.168.1.147) :
| Paramètre | Valeur |
|---|---|
| Mode plugin | Local (USB + Docker) |
| Type connexion RCP | TCP réseau via socat |
| Adresse TCP RCP | 192.168.1.147:6638 |
| Docker OTBR | Actif sur Jeedom |
Vérifications :
# Connexion TCP au dongle — doit répondre
nc -vz 192.168.1.147 6638
# État Thread dans le conteneur OTBR — doit afficher leader, router ou child
docker exec -it otbr ot-ctl state
3. TCP direct — Connexion réseau native (avancé)
Connexion directe en protocole spinel sur TCP, sans intermédiaire. Réservé aux appareils compatibles avec le protocole spinel+hdlc+uart+tcp://.
Deux sous-modes :
- Auto : saisir
ip:port, le plugin construit l’URL automatiquement - URL complète : saisir l’URL spinel complète (ex :
spinel+hdlc+uart+tcp://192.168.1.10:6638)
4. Distant — OTBR sur un hub réseau (expérimental)
OTBR tourne sur un appareil externe (ex : SLZB-06xU avec "Thread + OTBR on device" activé). Jeedom se connecte à son API REST via l’adresse HTTP.
Mode à activer sur le dongle : Thread + OTBR running on device
- Sélectionner le mode Distant dans la configuration
- Saisir l’URL de l’API REST de votre hub :
http://192.168.1.x:8080 - Le plugin lit et écrit le dataset Thread directement sur le hub
Configuration Jeedom (exemple SLZB sur 192.168.1.147) :
| Paramètre | Valeur |
|---|---|
| Mode plugin | Distant |
| URL OTBR | http://192.168.1.147:8080 |
| Docker OTBR | Arrêté sur Jeedom |
Vérification :
# L’API REST du dongle doit répondre
curl http://192.168.1.147:8080
Important en mode distant :
- Le conteneur Docker local n’est pas utilisé
- Le watchdog local ne tourne pas (inutile)
- Les boutons Lancer/Arrêter/Redémarrer OTBR sont désactivés
- La gestion du réseau Thread se fait depuis Jeedom, mais c’est le hub qui l’exécute
Tableau récapitulatif
| Mode | Mode dongle | Docker Jeedom | Port utilisé | Watchdog |
|---|---|---|---|---|
| USB | — | Oui | /dev/ttyUSB* | Oui |
| TCP socat | Thread to remote OTBR | Oui | TCP 6638 | Oui |
| TCP direct | Thread to remote OTBR | Oui | TCP 6638 | Oui |
| Distant | Thread + OTBR on device | Non | HTTP 8080 | Non |
⚙️ Installation
Depuis la page Configuration → OTBR :
-
Cliquer sur Installer le support Thread
-
Attendre la fin de l’installation (quelques minutes)
-
Vérifier l’état :
- Docker : OK
- www-data dans docker : OK
-
Si Docker n’est pas accessible ou droits
www-dataincorrects : 👉 Cliquer sur Redémarrer Apache ⚠️ À faire une seule fois après installation -
Cliquer sur Lancer OTBR
🌐 Configuration du réseau Thread
Deux cas de figure :
🆕 Nouveau réseau Thread
- Cliquer sur Créer / Réinitialiser le réseau Thread
👉 Le plugin initialise automatiquement un nouveau dataset
🔁 Réseau existant (recommandé)
-
Récupérer un dataset Thread existant :
- Home Assistant
- Sauvegarde d’une ancienne clé
-
Ouvrir la fenêtre Gestion Matter & Thread
-
Coller le dataset dans le champ prévu
-
Cliquer sur Injecter le dataset
👉 Permet de :
- conserver les appareils existants
- éviter de devoir tout réappairer
🔗 Commissionnement, multi-admin et dataset
La fenêtre Gestion Matter & Thread regroupe trois fonctions principales :
➕ Commissionnement Matter
Permet d’ajouter un nouvel équipement Matter à Jeedom.
-
Saisir le code Matter (recommandé en manuel)
👉 Utiliser de préférence le code manuel (plus fiable que le QR code) -
Option possible : forcer la configuration réseau (avancé)
-
Cliquer sur Commissionner
👉 Utilisé pour :
- ajouter un nouvel appareil
- connecter un device neuf ou réinitialisé
🔄 Partage multi-admin
Permet d’ajouter dans un autre contrôleur Matter un équipement déjà présent dans Jeedom
(ex : Apple Home, Home Assistant)
Étapes :
- Sélectionner l’équipement dans Jeedom
- Cliquer sur Générer un code
- Utiliser ce code dans l’autre écosystème
👉 Permet :
- d’éviter un reset
- de partager un appareil entre plusieurs systèmes
👉 Nécessite que les contrôleurs soient sur le même réseau Thread
🧠 Différence importante
- Commissionnement → ajout initial d’un appareil
- Multi-admin → partage d’un appareil existant
👉 Les deux méthodes sont complémentaires et peuvent être utilisées ensemble
📋 Dataset Thread
Le dataset contient :
- les clés réseau
- le nom du réseau
- la configuration Thread
👉 Le dataset est l’élément central du réseau Thread : tous les contrôleurs doivent partager le même
Fonctions disponibles :
- 📥 Récupérer le dataset actuel
- 📋 Copier
- 📤 Injecter un dataset
📡 Canal Thread
Le canal Thread est le canal radio utilisé par tous les appareils de votre réseau. Il est stocké dans le dataset actif et doit être identique sur tous les nœuds.
Changer le canal affecte tous les appareils Thread du réseau. L’opération est réversible via la restauration du backup, mais peut temporairement déconnecter certains équipements.
Lire le canal actuel
Depuis Configuration → OTBR, cliquez sur l’icône 🔄 à côté du champ Canal Thread pour lire le canal actuellement actif.
Changer le canal
- Saisissez le nouveau canal (valeurs autorisées : 11 à 26)
- Cliquez sur Changer
- Confirmez l’avertissement
Le comportement dépend du rôle OTBR dans le réseau Thread :
| Rôle OTBR | Mécanisme | Délai |
|---|---|---|
| Leader | dataset commit pending — propagé directement | ~30 secondes |
| Router | dataset updater start — soumis au Leader du réseau | ~5 minutes |
Si un autre border router (HomePod, Apple TV 4K, Google Nest Hub…) est Leader de votre réseau Thread, OTBR est en mode Router. Le changement de canal est soumis au Leader via MGMT_PENDING_SET.req — le basculement prend ~5 minutes si le Leader l’accepte.
Sauvegarde et restauration
Avant toute modification, le plugin sauvegarde automatiquement le dataset actif en configuration Jeedom.
| Action | Description |
|---|---|
| Sauvegarder le dataset | Ouvre la fenêtre Gestion Matter & Thread pour copier le dataset manuellement |
| Restaurer le backup | Réinjecte le dataset sauvegardé avant le dernier changement de canal |
Utilisez le bouton Sauvegarder le dataset avant tout changement de canal. En cas de problème, Restaurer le backup permet de revenir à l’état précédent en quelques secondes.
Le changement de canal Thread depuis l'interface fonctionne maintenant que votre OTBR soit Leader ou Router. En mode Router, le basculement prend ~5 minutes (délai de propagation au réseau). Vérifiez le canal avec Lire le canal après ce délai.
💡 Conseil
👉 Privilégier l’utilisation d’un dataset existant si vous avez déjà un réseau Thread 👉 Cela garantit une continuité et évite toute perte d’équipements
🧠 Bonnes pratiques
- Toujours utiliser un seul réseau Thread
- Faire une sauvegarde du dataset
- Réutiliser le dataset lors d’un changement de clé
⚠️ Important
- Le Bluetooth est utilisé uniquement pour le commissioning
- Une fois ajouté, le device communique en Thread (réseau IP)
- Si le dongle est remplacé → réinjecter le dataset
- Si le dataset est perdu → les appareils devront être réappairés
🔄 Synchronisation des équipements
- Les devices sont automatiquement détectés après commissioning
- Une synchronisation peut être lancée manuellement si nécessaire
🛡️ Surveillance automatique (Watchdog)
Le plugin inclut un système de surveillance qui tourne en arrière-plan dès qu'OTBR est démarré. Il vérifie toutes les 30 secondes que tout fonctionne correctement.
Ce qu'il surveille
| Situation détectée | Action automatique |
|---|---|
| Le conteneur OTBR s'est arrêté | Redémarrage du conteneur (après 60s) |
| Le conteneur a disparu ou est irrécupérable | Recréation complète du conteneur |
Le réseau Thread est perdu (detached) | Redémarrage de la couche Thread |
| Le réseau Thread est désactivé | Relance du réseau Thread |
Rôle du cron Jeedom
La tâche planifiée de Jeedom (exécutée chaque minute) vérifie uniquement que le watchdog lui-même tourne. Si le watchdog s'est arrêté pour une raison quelconque, Jeedom le relance automatiquement.
Jeedom (cron 1 min)
└─ Watchdog actif ? Non → relance le watchdog
└─ Watchdog (toutes les 30s)
└─ OTBR OK ? Non → redémarre OTBR
Après une recréation complète
Si le conteneur OTBR a dû être entièrement recréé (cas rare), le réseau Thread redémarre sans votre dataset. Vos appareils Thread risquent de ne pas se reconnecter.
Solution : Allez dans Gestion Matter & Thread → Injecter le dataset et collez votre dataset de sauvegarde.
Pensez à copier votre dataset Thread régulièrement depuis Gestion Matter & Thread → Récupérer le dataset actuel. C'est votre "clé" pour retrouver vos appareils Thread en cas de problème.
🐛 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
Si des commandes attendues ne sont pas créées après synchronisation, utilisez les boutons de la section Debug (onglet Équipement) :
- Infos nœud : vue structurée des clusters et attributs détectés
- Dump node brut : JSON complet du nœud avec bouton Copier
Joignez le contenu du dump à votre ticket de support pour permettre l'analyse.
OTBR ne démarre pas (dongle USB non détecté)
- Vérifiez que le dongle est bien branché : allez dans Configuration → OTBR et cliquez sur Rafraîchir les ports
- Préférez le chemin
/dev/serial/by-id/...s'il est disponible (plus stable) - Si le dongle ne répond pas, essayez un Préréglage UART (Slaesh CC2652RB ou SLZB Thread RCP)
- Consultez les logs matter_otbr pour voir l'erreur exacte
OTBR ne se connecte pas (mode TCP socat ou TCP direct)
- Vérifiez que l'adresse
ip:portest correcte (port 6638 par défaut pour SLZB) - Testez que l'appareil est joignable sur le réseau
- Pour les SLZB : vérifiez que le mode "Serial-over-IP" ou "Thread RCP" est activé dans l'interface de l'appareil
- En cas d'échec de connexion, essayez le préréglage UART
TCP via socat (EFR32/SLZB-MR4U) - Consultez les logs matter_otbr
Le hub distant (mode Distant) n'est pas joignable
- Vérifiez l'URL de l'API REST :
http://ip-du-hub:8080 - Vérifiez que votre hub a bien le mode OTBR activé
- Testez l'URL dans un navigateur : vous devez voir une réponse JSON
- Vérifiez qu'il n'y a pas de pare-feu entre Jeedom et le hub
OTBR s'est arrêté et ne redémarre pas
Le watchdog gère normalement ce cas automatiquement. Si OTBR reste arrêté :
- Consultez les logs matter_otbr pour voir ce qui s'est passé
- Vérifiez que Docker fonctionne sur la machine
- Allez dans Configuration → OTBR et cliquez sur Lancer OTBR manuellement
- Si le watchdog lui-même est arrêté, attendez jusqu'à 1 minute que Jeedom le relance automatiquement
Les appareils Thread ne répondent plus après un redémarrage d'OTBR
Si OTBR a dû être recréé entièrement (cas rare), le dataset Thread a été perdu :
- Allez dans Gestion Matter & Thread → Injecter le dataset
- Collez votre dataset de sauvegarde
- Cliquez sur Injecter le dataset
- Attendez quelques secondes que les appareils se reconnectent
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.