ESP32 Matter : Contrôler la lumière marche/arrêt (Arduino) – Alexa, Apple Home, Google

Ce guide vous montre comment créer un dispositif d’éclairage marche/arrêt compatible Matter qui contrôle un GPIO ESP32 programmé à l’aide de l’IDE Arduino. L’appareil peut être mis en service dans Apple Home, Google Home, Amazon Alexa, Home Assistant ou d’autres contrôleurs Matter. Il prend en charge le contrôle des boutons locaux, la persistance de l’état de l’éclairage après un redémarrage et la réinitialisation d’usine (mise hors service).

Conditions préalables

Avant de poursuivre ce tutoriel, vous devez avoir installé les cartes ESP32 dans votre IDE Arduino :

Vous aurez également besoin d’un modèle de carte de développement ESP32 de votre choix et d’un contrôleur domotique comme Amazon Echo Dot Max (Alexa).

Introduction au protocole de matière

Matter, anciennement connu sous le nom de Project CHIP (Connected Home over IP), est un protocole de connectivité open source et standard de l’industrie pour les appareils domestiques intelligents. Le protocole Matter a été développé par la Connectivity Standards Alliance (CSA) avec la contribution de grandes entreprises, notamment Apple, Google, Amazon, Samsung et d’autres. Matter vise à résoudre le problème de fragmentation où chaque entreprise construit son propre protocole propriétaire pour interagir avec ses appareils.

Principales fonctionnalités du protocole Matter :

• Interopérabilité : les appareils de différents fabricants fonctionnent ensemble de manière transparente dans le même écosystème (Apple Home, Google Home, Amazon Alexa, Home Assistant, Samsung SmartThings, etc…).
• Contrôle local : la communication s’effectue principalement sur le réseau local (Wi-Fi, Thread ou Ethernet). La connectivité cloud est facultative.
• Sécurité : communication cryptée intégrée et mise en service sécurisée.
• Configuration simple : les appareils sont mis en service à l’aide d’un code QR ou d’un code d’appairage manuel.
• Prise en charge multi-administrateur : un seul appareil peut être contrôlé simultanément par plusieurs contrôleurs de maison intelligente.
• Basé sur IP : fonctionne sur des réseaux IP standard.

Quelques concepts à connaître avant de vous plonger dans ce guide :

• Nœud : un seul appareil Matter (exemple : dans ce guide, l’ESP32 est un nœud).
• Endpoint : une unité fonctionnelle à l’intérieur d’un nœud. Un seul nœud (appareil Matter) peut exposer plusieurs points de terminaison (exemple : contrôle de la lumière et un capteur de température).
• Cluster : un groupe d’attributs et de commandes associés liés à une fonction (exemple : le cluster On/Off possède un attribut OnOff et des commandes On/Off/Toggle).
• Fabric : le réseau logique créé lorsqu’un contrôleur (Apple Home, Google Home, Alexa, Home Assistant, etc…) met en service votre appareil. Un nœud peut appartenir à plusieurs structures à la fois.
• Mise en service : le processus d’attribution d’un appareil Matter (nœud) sur une structure, à l’aide d’un code QR ou d’un code d’appairage manuel à 11 chiffres. Cela se fait généralement via BLE ou Wi-Fi.
• Wi-Fi : Matter fonctionne sur IP et les nœuds (exemple : appareils ESP32) peuvent rejoindre un réseau Matter via Wi-Fi.

L’ESP32 Arduino Core depuis la version 3.1.0 est livré avec la bibliothèque Matter, vous n’avez donc pas besoin d’installer de bibliothèques supplémentaires dans votre IDE Arduino.

Flux de travail typique du périphérique de matière

Ce diagramme ci-dessous illustre le flux de travail complet d’un appareil Matter, car il n’est pas mis en service pour un fonctionnement normal et un partage facultatif sur plusieurs écosystèmes de contrôleurs de maison intelligente.

1. Appareil/nœud non mis en service

• Première utilisation de l’appareil (ou après réinitialisation)
• Affiche le code QR + le code d’appairage manuel
• L’utilisateur scanne le code QR ou saisit le code d’appairage manuel dans un contrôleur de maison intelligente (tissu) : Alexa, Apple Home, Google Home, Home Assistant, etc…

2. Mise en service

• La session d’appairage sécurisée démarre (PASE)
• Confirme qu’il s’agit d’un appareil Matter
• Les informations d’identification Wi-Fi sont fournies (généralement via BLE)
• L’appareil rejoint le tissu Matter (exemple : Alexa – Echo Dot Max)

3. Rejoint le réseau

• Se connecte au Wi-Fi
• Devient accessible via IPv6 + mDNS

4. Fonctionnement normal

• Les contrôleurs découvrent et contrôlent l’appareil Matter
• Toutes les communications sont cryptées
• Fonctionne localement même sans Internet

5. Multi-administrateur (facultatif)

• Le code QR/de couplage d’origine ne peut pas être réutilisé
• Ouvrez le mode de couplage depuis la première application connectée pour générer/partager un appareil en créant un nouveau code de couplage manuel temporaire.
• Utilisez le nouveau code généré pour ajouter l’appareil à un autre écosystème : Apple Home, Google Home, Home Assistant, etc…
• Le dispositif Same Matter appartient à plusieurs tissus et peut être contrôlé par plusieurs écosystèmes en même temps

Puces ESP32 prises en charge

Les puces ESP32 suivantes prennent en charge le protocole Matter. De plus, il montre également lesquels prennent en charge CHIPoBLE. Pour les puces qui ne le prennent pas en charge, les informations d’identification doivent être insérées dans le croquis. Dans les autres scénarios, ils sont transférés via BLE depuis le contrôleur.

* CHIPoBLE signifie CHIP (Connected Home over IP), le nom original du protocole Matter, sur BLE (Bluetooth Low Energy).

Arduino Sketch – Dispositif ESP32 Matter : contrôle de la lumière marche/arrêt

L’exemple suivant est basé sur la bibliothèque officielle Espressif Arduino ESP32 Matter. Il transforme votre ESP32 en un appareil Matter (nœud) entièrement fonctionnel avec lumière marche/arrêt qui contrôle une broche GPIO. L’appareil peut être mis en service dans n’importe quel écosystème Matter majeur et également contrôlé localement à l’aide d’un bouton-poussoir.

/*
  Rui Santos & Sara Santos - Raspberryme.com
  Complete project details at https://Raspberryme.com/esp32-matter-on-off-light/

  Copyright 2025 Espressif Systems (Shanghai) PTE LTD. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
*/
#include 
#include 
#include 

// Wi-Fi credentials for this sketch. Fill these in when the board cannot commission over BLE (Arduino prebuild on ESP32 / ESP32-S2): the sketch
// joins the AP itself. When Matter commissions over BLE (CHIPoBLE), the hub sends SSID and password — leave the placeholders; they are unused.
#define WIFI_SSID     "your-ssid"
#define WIFI_PASSWORD "your-password"

// List of Matter Endpoints for this Node
// On/Off Light Endpoint
MatterOnOffLight OnOffLight;

// it will keep last OnOff state stored, using Preferences
Preferences matterPref;
const char *onOffPrefKey = "OnOff";

// set your board LED pin here
#ifdef LED_BUILTIN
  const uint8_t ledPin = LED_BUILTIN;
#else
  const uint8_t ledPin = 2;  // Set your pin here if your board has not defined LED_BUILTIN
  #warning "Do not forget to set the LED pin"
#endif

// set your board USER BUTTON pin here
const uint8_t buttonPin = BOOT_PIN;  // Set your pin here. Using BOOT Button.
MatterButton button;

// Matter Protocol Endpoint Callback
bool setLightOnOff(bool state) {
  Serial.printf("User Callback :: New Light State = %s\r\n", state ? "ON" : "OFF");
  if (state) {
    digitalWrite(ledPin, HIGH);
  } else {
    digitalWrite(ledPin, LOW);
  }
  // store last OnOff state for when the Light is restarted / power goes off
  matterPref.putBool(onOffPrefKey, state);
  // This callback must return the success state to Matter core
  return true;
}

void setup() {
  // Initialize the USER BUTTON (Boot button) GPIO that will act as a toggle switch
  button.begin(buttonPin);
  // Initialize the LED (light) GPIO and Matter End Point
  pinMode(ledPin, OUTPUT);

  Serial.begin(115200);

// CONFIG_ENABLE_CHIPOBLE=n: sketch starts Wi-Fi here; with CHIPoBLE the hub delivers credentials.
#if !CONFIG_ENABLE_CHIPOBLE
  matterConnectWiFi(WIFI_SSID, WIFI_PASSWORD);
#endif

  // Initialize Matter EndPoint
  matterPref.begin("MatterPrefs", false);
  bool lastOnOffState = matterPref.getBool(onOffPrefKey, true);
  OnOffLight.begin(lastOnOffState);
  OnOffLight.onChange(setLightOnOff);

  // Matter beginning - Last step, after all EndPoints are initialized
  Matter.begin();
  matterWaitUntilReady();
  Serial.printf("Initial state: %s\r\n", OnOffLight.getOnOff() ? "ON" : "OFF");
  OnOffLight.updateAccessory();
}

void loop() {
  matterRestartIfNoFabric();

  matterButtonEvent_t ev;
  while ((ev = button.poll()) != MATTER_BUTTON_NONE) {
    if (ev == MATTER_BUTTON_CLICK) {
      Serial.println("User button released. Toggling Light!");
      OnOffLight.toggle();
    } else if (ev == MATTER_BUTTON_LONG_HOLD) {
      Serial.println("Decommissioning the Light Matter Accessory. It shall be commissioned again.");
      OnOffLight.setOnOff(false);
      Matter.decommission();
    }
  }
}

Afficher le code brut

Vous n’avez pas besoin d’installer de bibliothèques supplémentaires, en fonction de votre carte, vous devrez peut-être insérer vos informations d’identification réseau dans les lignes suivantes du code. Vous devez également sélectionner dans Outils – Schéma de partition : « Huge APP (3MB No OT /1MB SPIFFS) » et le code fonctionnera immédiatement.

#define WIFI_SSID "REPLACE_WITH_YOUR_SSID";
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD";

Comment fonctionne le code

Continuez à lire pour découvrir comment fonctionne le code ou passez à la section Démonstration.

Y compris les bibliothèques

Commencez par inclure les bibliothèques suivantes :

#include 
#include 
#include 

• Matter.h – Bibliothèque Main Matter (gère la pile de protocoles)
• Preferences.h – Utilisé pour enregistrer le dernier état marche/arrêt dans la mémoire non volatile (se souvient du dernier état après le redémarrage de la carte)

Apprenez-en plus sur les préférences avec notre guide : ESP32 Enregistrer les données de manière permanente à l’aide de la bibliothèque de préférences.

Informations d’identification réseau

Ces informations d’identification Wi-Fi ne sont nécessaires que si la carte ne peut pas être mise en service via BLE (préconstruction Arduino sur ESP32 ou ESP32-S2), auquel cas le croquis rejoint le réseau lui-même. Lorsque Matter utilise la mise en service BLE (CHIPoBLE), le hub fournit le SSID et le mot de passe, vous pouvez donc laisser les espaces réservés SSID/Mot de passe par défaut.

#define WIFI_SSID "REPLACE_WITH_YOUR_SSID";
#define WIFI_PASSWORD "REPLACE_WITH_YOUR_PASSWORD";

Point de terminaison du sujet

OnOffLight est le point de terminaison Matter qui implémente le cluster On/Off Light standard sur l’ESP32.

MatterOnOffLight OnOffLight;

Préférences

MatterPref et onOffPrefKey stockent le dernier état d’éclairage afin qu’il soit restauré après un redémarrage.

Preferences matterPref;
const char *onOffPrefKey = "OnOff";

Broche LED

Utilise la LED intégrée de la carte si disponible, sinon GPIO 2.

#ifdef LED_BUILTIN
const uint8_t ledPin = LED_BUILTIN;
#else
const uint8_t ledPin = 2;
#warning "Do not forget to set the LED pin"
#endif

Bouton DE DÉMARRAGE

Utilise le bouton BOOT intégré ESP32 (généralement GPIO 0) pour le contrôle GPIO local et la réinitialisation d’usine (mise hors service).

const uint8_t buttonPin = BOOT_PIN;
MatterButton button;

setLightOnOff()

La fonction de rappel setLightOnOff() allume ou éteint la LED physique en fonction de l’état du Matter demandé. Il enregistre également l’état actuel dans un stockage non volatile afin de mémoriser le dernier état après un redémarrage de la carte.

bool setLightOnOff(bool state) {
  Serial.printf("User Callback :: New Light State = %s\r\n", state ? "ON" : "OFF");
  if (state) {
    digitalWrite(ledPin, HIGH);
  } else {
    digitalWrite(ledPin, LOW);
  }
  matterPref.putBool(onOffPrefKey, state);
  return true;
}

installation()

La fonction setup() commence par initialiser le boutonPin et le ledPin. Il démarre également la communication série.

void setup() {
  button.begin(buttonPin);
  pinMode(ledPin, OUTPUT);

  Serial.begin(115200);

En fonction de votre carte, il se connecte au Wi-Fi à l’aide des informations d’identification du réseau si CHIPoBLE est désactivé.

// CONFIG_ENABLE_CHIPOBLE=n: sketch starts Wi-Fi here; with CHIPoBLE the hub delivers credentials.
#if !CONFIG_ENABLE_CHIPOBLE
  matterConnectWiFi(WIFI_SSID, WIFI_PASSWORD);
#endif

Cet extrait de code suivant initialise le stockage des préférences Matter et récupère le dernier état enregistré (activé/désactivé). Il démarre le point de terminaison OnOffLight avec cet état et enregistre le rappel setLightOnOff afin que le voyant physique se mette à jour lorsque l’état du sujet change.

matterPref.begin("MatterPrefs", false);
bool lastOnOffState = matterPref.getBool(onOffPrefKey, true);

OnOffLight.begin(lastOnOffState);
OnOffLight.onChange(setLightOnOff);

La première ligne commence la pile Matter et attend qu’elle soit complètement prête. Ensuite, il imprime l’état marche/arrêt initial de la lumière dans le moniteur série et met à jour l’accessoire physique (LED) pour qu’il corresponde à cet état.

Matter.begin();
matterWaitUntilReady();

Serial.printf("Initial state: %s\r\n", OnOffLight.getOnOff() ? "ON" : "OFF");

OnOffLight.updateAccessory();

boucle()

La boucle() commence par appeler la fonction MatterRestartIfNoFabric(). Il s’agit d’une aide qui vérifie si l’appareil fait toujours partie d’une structure Matter (il est toujours commandé à un contrôleur comme Apple Home, Google Home, Alexa, etc…). Si l’appareil n’a pas de structure (il est actuellement mis hors service), il redémarre la pile Matter afin qu’elle puisse être découverte et mise en service.

matterRestartIfNoFabric();

Déclare une variable ev de type MatterButtonEvent_t qui représente différents événements de bouton (appui court ou appui long).

matterButtonEvent_t ev;

Le bouton.poll() est un moyen non bloquant de vérifier si le bouton physique BOOT a été enfoncé.

while ((ev = button.poll()) != MATTER_BUTTON_NONE) {

Si vous cliquez sur BOOT intégré avec un appui court, la lumière s’allume (si elle était allumée, elle s’éteint, ou si elle était déjà éteinte, la lumière s’allume). Il met également à jour l’état actuel de tous les contrôleurs Matter.

if (ev == MATTER_BUTTON_CLICK) {
  Serial.println("User button released. Toggling Light!");
  OnOffLight.toggle();
}

Enfin, si le bouton BOOT intégré est enfoncé pendant plus de 5 secondes, il éteint la lumière et supprime l’appareil de tous les tissus Matter (réinitialisation d’usine). L’appareil devra être à nouveau mis en service.

else if (ev == MATTER_BUTTON_LONG_HOLD) {
  Serial.println("Decommissioning the Light Matter Accessory. It shall be commissioned again.");
  OnOffLight.setOnOff(false);
  Matter.decommission();
}

Téléchargez le code sur votre tableau

Après avoir inséré vos informations d’identification réseau, suivez ces étapes suivantes pour télécharger le code sur la carte ESP32.

Tout d’abord, sélectionnez votre carte : Outils – Carte – ESP32 Arduino – sélectionnez votre carte (par exemple ESP32S3 Dev Module).

Ensuite, allez dans Outils et sélectionnez le schéma de partition : « Huge APP (3MB No OT /1MB SPIFFS) »

Important : avant le premier téléchargement, nous vous recommandons d’effacer toute la mémoire flash. Accédez à Outils et activez l’option Effacer tout le flash avant le téléchargement de l’esquisse : activé. Cela efface les informations d’identification Wi-Fi précédentes et les données de structure Matter. Faites-le au moins lors du premier téléchargement ou en cas d’échec de la mise en service.

Enfin, après avoir branché votre carte sur votre ordinateur et sélectionné le bon port série, cliquez sur le bouton Arduino IDE Upload.

Mise en service de votre appareil ESP32 Matter

Au premier démarrage de l’ESP32 (ou après avoir effacé toute la mémoire flash), ouvrez votre moniteur série Arduino IDE, appuyez sur le bouton RST/EN intégré de l’ESP32.

Il devrait imprimer quelque chose comme ceci :

Vous pouvez soit utiliser le code de couplage manuel à 11 chiffres, soit ouvrir l’URL dans votre navigateur pour obtenir un code QR afin de le scanner dans votre application pour maison intelligente.

Ajouter un appareil Matter à Amazon Alexa

Pour cet exemple, nous utiliserons l’application Amazon Alexa, mais dans la section suivante, nous montrerons les étapes à ajouter à d’autres applications de contrôleur.

Tout d’abord, ouvrez l’application Amazon Alexa et appuyez sur l’icône + :

Choisissez l’option Ajouter un appareil :

Sélectionnez Logo Matter ou Autre.

Lorsqu’on vous demande si l’appareil a un logo, sélectionnez l’option « OUI ». Ensuite, scannez le code QR ou saisissez le code d’appairage manuel :

Ayant votre appareil assez proche de l’appareil concerné, cliquez sur « Connecter ».

L’ESP32 n’est pas certifié Matter, mais ajoutez l’appareil en appuyant sur Oui.

Votre appareil ESP32 Matter sera trouvé et connecté, cliquez sur Suivant.

Après une mise en service réussie, le moniteur série Arduino IDE imprime « Matter Node is commissioned… » et la LED reflète l’état actuel.

Votre lumière sera ajoutée à votre liste d’appareils comme indiqué dans l’image suivante :

Ajouter un appareil Matter à Apple Home, Google Home, Home Assistant ou SmartThings

Voici les instructions rapides sur la façon d’ajouter un appareil Matter à différentes applications de contrôleur. Le contrôleur doit fonctionner dans votre maison comme Apple Home, Google Home, Home Assistant ou SmartThings.

• Accueil Apple :
  • Ouvrez l’application iPhone Accueil
  • Appuyez sur l’icône + dans le coin supérieur droit
  • Ajouter un accessoire
  • Scannez le code QR ou appuyez sur le lien « Plus d’options » pour saisir le code d’appairage manuel
• Accueil Google :
  • Ouvrez l’application Google Home
  • Appuyez sur l’icône +
  • Configurer l’appareil
  • Nouvel appareil
  • Appareil matière
  • Scannez le code QR ou entrez le code d’appairage manuel
• Assistante à domicile :
  • Assistant à domicile ouvert
  • Allez dans Paramètres
  • Appareils et services
  • Ajouter une intégration
  • Matière
  • Entrez le code d’appairage manuel ou scannez le code QR
• Objets intelligents Samsung :
  • Ouvrez l’application SmartThings
  • Appuyez sur l’icône +
  • Sélectionnez les appareils partenaires : Matter
  • Scannez le code QR ou entrez le code d’appairage manuel

Important : après avoir mis en service un appareil Matter sur un contrôleur, vous ne pouvez pas réutiliser le code QR d’origine ou le code d’appairage manuel pour l’ajouter à un autre contrôleur. Au lieu de cela, vous devez ouvrir une nouvelle fenêtre de mise en service à partir de l’application du premier contrôleur (Partager / Activer le mode d’appairage / Lien vers une autre plate-forme) pour générer un nouveau code temporaire, puis utiliser ce code pour partager l’appareil sur la nouvelle plate-forme.

Remarque : certaines applications peuvent avertir qu’il ne s’agit pas d’un appareil officiel ou certifié, mais vous devez sélectionner l’option pour l’ajouter.

Démonstration

À partir d’une application Matter (comme Alexa) ou d’un hub vocal, vous pouvez allumer/éteindre la lumière. Le GPIO change en fonction de la commande et l’état est enregistré même si votre carte redémarre.

Vous pouvez également contrôler le GPIO ESP32 à l’aide du bouton physique BOOT intégré. Appuyez brièvement sur le bouton BOOT : il active/désactive (l’état actuel est également mis à jour sur tous les contrôleurs Matter)

IMPORTANT : vous pouvez maintenir le bouton BOOT enfoncé pendant plus de 5 secondes pour mettre hors service l’appareil Matter (réinitialisation d’usine). L’appareil doit ensuite être remis en service avec un nouveau code QR ou en saisissant le code d’appairage manuel.

Remarque : si votre carte redémarre, elle mémorise le dernier état marche/arrêt, car il est restauré depuis NVS (Préférences).

Vous pouvez regarder la démonstration vidéo ci-dessous :

Dépannage

Le tableau suivant présente les erreurs les plus courantes lorsque vous suivez ce didacticiel et les solutions possibles.

Remarque : sur le moniteur Arduino IDE Serial, vous pouvez voir de nombreux messages de journal imprimés au fil du temps et juste après la configuration. Vous pouvez voir des messages tels que « échec de l’envoi », « erreur d’envoi transitoire », « demande sur un cluster inconnu » ou similaire. Ils sont généralement inoffensifs et vous pouvez les ignorer à moins que l’appareil ne reste inaccessible.

Conclusion

Dans ce guide, vous avez appris à transformer votre ESP32 en un appareil Matter pour une lumière marche/arrêt programmée avec l’IDE Arduino. Vous avez également appris les bases du protocole Matter et comment mettre l’appareil en service sur différents contrôleurs, tels qu’Alexa, Apple Home, Google Home, Home Assistant et SmartThings.

Si vous avez aimé ce projet, vous aimerez peut-être également ces autres tutoriels :

Merci d’avoir lu.

Cette vidéo vous emmène dans l’histoire de Raspberry Pi :