Depuis le lancement de Matter en 2022, l'ajout d'un appareil au protocole posait un problème récurrent aux utilisateurs de Home Assistant : le commissioning nécessitait impérativement un smartphone à proximité physique de l'appareil. Pour ceux qui hébergent Home Assistant sur une machine virtuelle Proxmox reléguée dans un placard technique, ou pour les installations où le serveur n'a pas de dongle Bluetooth accessible, l'opération se transformait en acrobatie logistique.

Home Assistant 2026.6, sorti le 4 juin 2026, change la donne. Le commissioning Matter via proxy Bluetooth est désormais intégré nativement : un ESP32 flashé sous ESPHome peut servir de passerelle Bluetooth pour appairer un appareil Matter directement depuis Home Assistant, sans téléphone, sans dongle USB Bluetooth, sans contrainte de proximité physique avec le serveur.

Ce guide couvre la mise en place complète : prérequis logiciels, configuration ESPHome, activation dans le Matter Server add-on, et dépannage.

Pourquoi le commissioning Matter posait problème avant Home Assistant 2026.6

Pour comprendre l'apport de cette nouveauté, il faut rappeler comment fonctionne le commissioning Matter. Contrairement à Zigbee ou Z-Wave qui utilisent un coordinateur réseau centralisé, Matter est un protocole IP. L'étape d'ajout d'un appareil (le commissioning) repose sur une procédure Bluetooth Low Energy (BLE) : l'appareil diffuse un signal BLE contenant son code d'appairage, le contrôleur se connecte en BLE pour lui transmettre les credentials WiFi ou Thread, puis l'appareil rejoint le réseau IP et est découvert par Home Assistant.

Le problème structurel : cette étape BLE exige que le contrôleur Matter dispose d'un accès Bluetooth actif. Or, dans la majorité des déploiements Home Assistant non-officiels :

  • Les installations sur Proxmox ou Docker n'ont pas de Bluetooth passthrough configuré — le passthrough USB d'un dongle BLE est techniquement complexe et souvent instable sous VM.
  • Les machines mini-PC (Intel NUC, Beelink, Minisforum) ont certes un module Bluetooth intégré, mais ce module est souvent inaccessible depuis une VM sans configuration spécifique.
  • Le serveur peut être physiquement éloigné des appareils à appairer — un tableau électrique en sous-sol n'est pas à portée BLE du salon.

La solution contournement habituelle était d'utiliser l'application mobile Home Assistant Companion sur un smartphone. Pratique au départ, cette méthode devenait contraignante : il fallait avoir l'app à jour, être sur le même réseau, et le commissioning depuis l'app n'était pas toujours stable selon les releases.

D'après les retours de la communauté sur le forum Home Assistant, c'est l'un des points de friction les plus fréquemment cités autour de Matter depuis 2023.

Ce qui change avec Home Assistant 2026.6 : le proxy Bluetooth comme passerelle

Home Assistant dispose depuis 2022 du composant ESPHome bluetooth_proxy, qui permet à un ESP32 de relayer les trames BLE vers Home Assistant via le réseau WiFi. Cette fonctionnalité était jusqu'ici utilisée pour la détection de capteurs BLE passifs (thermomètres Xiaomi, capteurs de présence Bluetooth, etc.).

Avec la version 2026.6 et le Matter Server add-on 8.5.0 (basé sur python-matter-server), ce même mécanisme de proxy BLE est désormais exploité pour le commissioning Matter. Le endpoint /ble WebSocket exposé par python-matter-server via le flag --ble-proxy permet au Matter Server de déléguer les opérations Bluetooth à n'importe quel proxy BLE disponible sur le réseau local, porté par un ESP32 sous ESPHome.

Selon les notes de version de Home Assistant 2026.6 bêta publiées le 27 mai 2026, la fonctionnalité est considérée comme stable pour un usage en production. Elle n'est plus en bêta comme lors des premières itérations de Matter Server 8.x. Quelques limites subsistent, détaillées plus loin, mais le flux principal d'ajout d'un appareil Matter via proxy BLE fonctionne de manière fiable d'après les retours de la communauté sur la semaine bêta 2026.6.

Il faut noter un point important pour bien comprendre l'architecture : Matter supporte deux méthodes de commissioning selon le type de connectivité de l'appareil — Thread (via un border router Thread) pour les appareils Thread, et Bluetooth LE pour les appareils WiFi Matter. Le proxy ESPHome couvre uniquement la phase BLE du commissioning. Une fois l'appareil commissionné, la communication quotidienne passe par le réseau WiFi ou Thread, pas par le proxy Bluetooth.

Prérequis techniques : Matter Server 8.5, python-matter-server, HA 2026.6

Avant de configurer quoi que ce soit, vérifier que l'environnement remplit les conditions suivantes.

Home Assistant 2026.6 ou supérieur

La fonctionnalité nécessite Home Assistant Core 2026.6.0 minimum. Vérifier dans Paramètres > Infos. Si une mise à jour est disponible, l'appliquer avant de continuer.

Matter Server add-on version 8.5.0

Le Matter Server add-on doit être en version 8.5.0 ou supérieure. Pour vérifier :

  1. Aller dans Paramètres > Modules complémentaires > Matter Server
  2. Vérifier le numéro de version affiché
  3. Si une mise à jour est disponible, l'appliquer et redémarrer l'add-on

La version 8.5.0 est basée sur python-matter-server (dépôt home-assistant-libs/python-matter-server), qui expose le endpoint WebSocket /ble via le flag --ble-proxy. Les versions antérieures (8.4.x et inférieures) ne supportent pas cette fonctionnalité.

Intégration Matter activée

L'intégration Matter doit être configurée et fonctionnelle dans Home Assistant. Si ce n'est pas encore le cas, l'ajouter via Paramètres > Appareils et services > Ajouter une intégration > Matter (BETA). L'intégration s'appuie sur le Matter Server add-on — les deux doivent tourner simultanément.

Au moins un proxy Bluetooth ESPHome disponible

Il faut disposer d'un ESP32 flashé sous ESPHome avec le composant bluetooth_proxy activé en mode actif (méthode détaillée ci-dessous), accessible sur le réseau WiFi local.

À noter : les appareils Shelly Gen 2 ne sont pas compatibles avec le commissioning Matter. Bien qu'ils disposent d'un module Bluetooth, ils ne supportent pas les connexions GATT actives requises par le commissioning (le contrôleur doit initier une connexion BLE vers l'appareil pour lui transmettre les credentials réseau). Les Shelly Gen 2 peuvent uniquement relayer des advertisements BLE passifs — ils sont donc utilisables pour détecter des capteurs BLE passifs, mais pas pour le commissioning Matter.

Configurer un ESP32 sous ESPHome comme proxy Bluetooth Matter (YAML complet)

C'est la méthode la plus flexible et la plus économique. Un ESP32-C3 mini se trouve autour de 4 à 6 euros et peut être flashé en moins de dix minutes.

Boards ESP32 compatibles

Selon la documentation officielle ESPHome pour les composants Bluetooth, les boards suivants sont validés pour le rôle de proxy BLE :

  • ESP32-C3 (recommandé pour un proxy dédié : petit, économique, Bluetooth 5.0)
  • ESP32-S3 (si vous avez besoin d'un proxy avec d'autres capacités — plus puissant)
  • ESP32 original (dual-core, Bluetooth 4.2 — fonctionne mais moins performant que C3/S3)
  • ESP32-C6 (WiFi 6 — compatible mais un peu surdimensionné pour ce rôle)

Les modules basés sur ESP8266 ne sont pas compatibles : ils n'ont pas de Bluetooth.

Pour un proxy dédié, l'ESP32-C3 Super Mini est le format le plus pratique : encombrement réduit, alimentation USB-C, et Bluetooth 5.0 largement suffisant pour la phase de commissioning. C'est ce board qui sert de référence dans la configuration YAML ci-dessous.

Meilleur choix
ESP32-C3 Super Mini

ESP32-C3 Super Mini

RISC-V 160 MHz · 22×18 mm · Wi-Fi 4 + BT 5.0 · USB-C · Compatible ESPHome

Voir sur Amazon Lot de 2 · Livraison Prime · Retours gratuits

Configuration YAML ESPHome complète

Créer un nouveau fichier de configuration dans ESPHome. Le composant bluetooth_proxy avec active: true est la clé : le mode actif permet les connexions GATT initiées depuis Home Assistant (nécessaire pour le commissioning), alors que le mode passif se contente d'écouter les diffusions BLE.

esphome:
  name: matter-ble-proxy
  friendly_name: "Proxy Bluetooth Matter"

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf        # esp-idf fortement recommandé pour bluetooth_proxy
    version: recommended

# Logger minimal — réduire le bruit dans les logs HA
logger:
  level: INFO

# API Home Assistant — obligatoire pour que HA détecte le proxy
api:
  encryption:
    key: "VOTRE_CLE_API_32_OCTETS_BASE64"

ota:
  - platform: esphome
    password: "VOTRE_MOT_DE_PASSE_OTA"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  # IP fixe recommandée pour un proxy dédié
  manual_ip:
    static_ip: 192.168.1.150
    gateway: 192.168.1.1
    subnet: 255.255.255.0

  ap:
    ssid: "Matter BLE Proxy Fallback"
    password: "fallback_password"

captive_portal:

# Composant Bluetooth proxy — coeur de la configuration
bluetooth_proxy:
  active: true     # OBLIGATOIRE pour le commissioning Matter
  # cache_services: false  # Laisser la valeur par défaut (true)

# Optionnel : LED de statut pour visualiser l'activité BLE
light:
  - platform: status_led
    name: "Status LED"
    pin: GPIO8    # Pin LED intégrée sur ESP32-C3-DevKitM-1

Quelques points importants sur ce fichier de configuration :

  • framework esp-idf est fortement recommandé pour le composant bluetooth_proxy. Le framework Arduino peut également être utilisé, y compris en mode actif, mais esp-idf offre de meilleures performances Bluetooth et une stabilité supérieure pour les connexions longue durée, selon la documentation officielle ESPHome.
  • active: true est le paramètre critique. En mode passif (active: false), le proxy se contente de transmettre les advertisements BLE — il ne peut pas établir une connexion GATT sortante vers un appareil Matter, ce qui est nécessaire lors du commissioning.
  • La clé API est nécessaire pour que Home Assistant découvre automatiquement le proxy et puisse le piloter via l'intégration ESPHome. Sans clé API définie, le proxy sera découvert mais la communication sera non chiffrée — ce qui est fortement déconseillé sur un réseau local.

Flasher et adopter l'appareil

Une fois le YAML prêt, compiler et flasher depuis l'interface web ESPHome add-on. Après redémarrage du module :

  1. Home Assistant devrait découvrir automatiquement le nouveau proxy (Paramètres > Notifications)
  2. L'accepter dans Paramètres > Appareils et services > ESPHome
  3. Vérifier ensuite dans Paramètres > Appareils et services > Bluetooth : le proxy doit apparaître avec le statut "Connecté"

Activer le proxy BLE dans le Matter Server add-on

Une fois qu'au moins un proxy Bluetooth est disponible et visible dans Home Assistant, il faut activer son utilisation dans le Matter Server add-on.

Procédure d'activation pas-à-pas

  1. Aller dans Paramètres > Modules complémentaires > Matter Server

  2. Cliquer sur Ouvrir l'interface web (ou accéder directement à l'interface de configuration du Matter Server add-on)

  3. Dans la page de configuration du Matter Server, repérer la section Bluetooth ou BLE Proxy. Avec Matter Server 8.5.0, cette section affiche la liste des proxies Bluetooth détectés sur le réseau.

  4. Activer l'option Enable BLE proxy for commissioning (ou son équivalent selon la version de l'interface). Cette option active le endpoint WebSocket /ble de python-matter-server qui permet la délégation des opérations Bluetooth aux proxies disponibles.

  5. Sauvegarder et redémarrer le Matter Server add-on.

Vérifier que le proxy est actif

Après redémarrage, dans les logs du Matter Server add-on (onglet Journal), des lignes similaires à celles-ci doivent apparaître :

INFO  [BLE Proxy] Connected to proxy: matter-ble-proxy (192.168.1.150)
INFO  [BLE Proxy] BLE endpoint active, ready for commissioning

Ces lignes sont indicatives — le format exact des logs de python-matter-server peut différer selon la version. L'absence de toute mention du proxy dans les logs indique que le proxy n'est pas encore détecté — vérifier que l'appareil ESPHome est bien en ligne et que l'intégration ESPHome est active dans Home Assistant.

Ajouter un appareil Matter via le proxy

Le flux d'ajout est désormais identique à l'ajout habituel d'un appareil Matter :

  1. Dans Home Assistant, aller dans Paramètres > Appareils et services > Ajouter une intégration > Matter
  2. Choisir Ajouter un appareil
  3. Saisir le code de commissioning (QR code ou code numérique à 11 chiffres imprimé sur l'appareil)
  4. Home Assistant utilise automatiquement le proxy BLE disponible pour établir la connexion Bluetooth avec l'appareil
  5. Suivre les étapes de l'assistant — l'appairage complet prend généralement entre 30 secondes et 2 minutes selon l'appareil

Il n'est plus nécessaire d'avoir le smartphone à proximité. Le proxy Bluetooth, quelle que soit sa localisation sur le réseau, gère la partie BLE de la procédure.

Limites : exclusivité mutuelle, portée, et appareils compatibles

Cette fonctionnalité, bien que stable en production, comporte des contraintes importantes à connaître avant de l'adopter.

Exclusivité mutuelle : dongle USB Bluetooth versus proxy BLE

C'est la contrainte la plus significative. Selon les notes de version de Matter Server 8.5, le dongle USB Bluetooth et le proxy BLE ne peuvent pas être utilisés simultanément pour le commissioning Matter. Les flags --ble-proxy et --bluetooth-adapter sont mutuellement exclusifs dans python-matter-server.

Si votre installation dispose d'un dongle USB Bluetooth (par exemple un dongle Silicon Labs EFR32MG21 pour Thread/Matter), et que vous activez le proxy BLE, Matter Server basculera sur le proxy et ignorera le dongle pour les opérations de commissioning. Il est donc recommandé de choisir une approche et de s'y tenir : proxy BLE ou dongle USB, pas les deux.

Pour les installations Proxmox où le passthrough USB du dongle est problématique, le proxy BLE est clairement la meilleure option.

Portée Bluetooth et placement du proxy

La portée BLE effective d'un ESP32 est de l'ordre de 10 à 20 mètres en espace ouvert, significativement réduite par les murs, les plafonds et les interférences WiFi. Pour le commissioning, l'appareil Matter doit se trouver dans un rayon d'environ 5 à 10 mètres du proxy BLE.

Pour un logement de taille standard (T3-T4), un seul proxy bien placé (couloir central, salon) suffit généralement. Pour des configurations plus étendues (maison multi-étages, garage distant, dépendance), plusieurs proxies peuvent être déployés simultanément — Matter Server 8.5 gère plusieurs proxies BLE.

Appareils Matter et phase de commissioning BLE

Il est important de distinguer deux catégories d'appareils Matter :

  • Appareils Matter over WiFi : utilisent BLE uniquement pour le commissioning, puis rejoignent le réseau WiFi. Le proxy BLE couvre intégralement leur ajout.
  • Appareils Matter over Thread : utilisent également BLE pour le commissioning, puis rejoignent le réseau Thread via un border router. Le proxy BLE couvre la phase BLE, mais l'appareil nécessite ensuite un border router Thread actif pour fonctionner.

En pratique, la quasi-totalité des appareils Matter grand public en 2026 (prises connectées, ampoules, capteurs) supportent le commissioning via BLE, qu'ils soient WiFi ou Thread.

Cas d'usage concret : appairer un appareil Matter en garage depuis un serveur en armoire

Ce scénario illustre parfaitement l'intérêt de la fonctionnalité pour les installations réelles.

Contexte : Home Assistant tourne sur une VM Proxmox dans une armoire réseau au sous-sol. Une nouvelle prise connectée Matter vient d'être installée dans le garage, à 15 mètres de l'armoire et séparée par deux murs porteurs. Aucun dongle Bluetooth n'est configuré sur la VM Proxmox — le passthrough USB n'a jamais été mis en place car il n'avait pas été nécessaire jusque-là.

Sans le proxy BLE, les options seraient : configurer le passthrough USB Bluetooth sur Proxmox (procédure documentée dans le guide d'installation HA sur Proxmox 9, mais qui nécessite un redémarrage de la VM et des droits d'administration), ou utiliser le smartphone pour le commissioning.

Avec le proxy BLE :

  1. Un ESP32-C3 mini a été flashé sous ESPHome avec la configuration proxy détaillée ci-dessus, et posé sur une prise USB dans le couloir entre le sous-sol et le garage.
  2. Il apparaît dans Home Assistant comme proxy Bluetooth, à portée de la prise Matter dans le garage.
  3. Le Matter Server add-on est configuré avec le proxy BLE activé.
  4. L'ajout de la prise se fait entièrement depuis l'interface Home Assistant, sans déplacer quoi que ce soit, en saisissant simplement le code de commissioning imprimé sur l'appareil.

D'après les retours de la communauté sur plusieurs fils du forum Home Assistant consacrés à cette fonctionnalité, ce type de scénario — serveur en VM sans BLE accessible, appareils distribués dans le logement — représente le cas d'usage principal des utilisateurs qui adoptent le proxy BLE en 2026.

Dépannage fréquent : proxy non détecté, commissioning qui échoue, logs à vérifier

Le proxy n'apparaît pas dans Matter Server

Vérification 1 : L'appareil ESPHome doit être visible dans Paramètres > Appareils et services > Bluetooth avec le statut "Connecté". S'il n'y apparaît pas, le problème est en amont de Matter Server.

Vérification 2 : Pour les proxies ESPHome, s'assurer que l'intégration ESPHome est bien configurée avec une clé API. Un proxy ESPHome non authentifié peut être détecté par Home Assistant sans être opérationnel pour les fonctions avancées comme le commissioning Matter.

Vérification 3 : S'assurer que la version de Matter Server est bien 8.5.0 ou supérieure. Les versions antérieures ne lisent pas la liste des proxies BLE depuis l'intégration Bluetooth de HA.

Le commissioning échoue après la saisie du code

Cause fréquente 1 — Distance trop grande : L'appareil Matter est hors de portée BLE du proxy. Vérifier en rapprochant temporairement le proxy de l'appareil pendant le commissioning. La portée effective BLE dépend fortement de l'environnement.

Cause fréquente 2 — Appareil déjà partiellement commissionné : Si un précédent commissioning a échoué à mi-parcours, l'appareil peut se trouver dans un état intermédiaire. Sur la plupart des appareils Matter, une réinitialisation d'usine (reset) est nécessaire avant de recommencer. La procédure de reset est spécifique à chaque fabricant — consulter la documentation de l'appareil.

Cause fréquente 3 — Mode actif désactivé : Vérifier que le YAML ESPHome contient bien active: true dans la section bluetooth_proxy. Sans ce paramètre, le proxy ne peut pas initier de connexion GATT vers l'appareil.

Logs à vérifier pour diagnostiquer

Deux sources de logs sont pertinentes pour diagnostiquer un problème de commissioning via proxy :

Logs du Matter Server add-on (Paramètres > Modules complémentaires > Matter Server > Journal) : chercher les lignes contenant BLE, commissioning, ou proxy. Un message BLE Proxy disconnected pendant le commissioning indique un problème de connectivité avec le proxy.

Logs de l'appareil ESPHome (via l'interface ESPHome add-on ou les logs de l'intégration ESPHome dans HA) : chercher les lignes bluetooth_proxy. Un message BLE connection failed indique que l'ESP32 a tenté de se connecter à l'appareil Matter mais n'a pas pu établir la connexion BLE — probablement un problème de portée ou de code de commissioning incorrect.

Plusieurs proxies simultanément : si plusieurs proxies ESPHome sont actifs, Matter Server 8.5 peut en sélectionner un qui n'est pas le plus proche de l'appareil cible. Pour forcer l'utilisation d'un proxy spécifique, désactiver temporairement les autres dans Paramètres > Appareils et services > Bluetooth pendant le commissioning, puis les réactiver ensuite.