Matter на ESP32: умная лампа с Alexa, Apple Home и Home Assistant из Arduino IDE

Перевод статьи ESP32 Matter: Control On/Off Light (Arduino) – Works with Alexa, Apple Home, Google — Rui Santos, Random Nerd Tutorials.

В этом руководстве мы сделаем из ESP32 совместимое с Matter устройство — лампу вкл/выкл, которая управляет GPIO платы и прошивается из Arduino IDE. Устройство добавляется (проходит «комиссионинг») в Apple Home, Google Home, Amazon Alexa, Home Assistant и любой другой Matter-контроллер. Из приятного: локальное управление физической кнопкой, восстановление состояния лампы после перезагрузки и сброс к заводским настройкам (декомиссионинг) долгим нажатием.

Что нужно знать заранее#

Перед началом убедитесь, что в вашу Arduino IDE установлена поддержка плат ESP32 — если ещё нет, начните с этого руководства:

• Установка платы ESP32 в Arduino IDE 2 (Windows, macOS, Linux)

Кроме того, понадобится любая отладочная плата ESP32 и контроллер умного дома — например, Amazon Echo Dot Max (Alexa).

Что такое протокол Matter#

Matter (раньше — Project CHIP, «Connected Home over IP») — открытый отраслевой стандарт подключения для устройств умного дома. Протокол развивает Connectivity Standards Alliance (CSA), а вклад в него внесли Apple, Google, Amazon, Samsung и другие крупные компании. Matter призван решить проблему фрагментации, когда каждая компания изобретает собственный закрытый протокол для своих устройств.

Ключевые особенности протокола Matter:

• Совместимость: устройства разных производителей работают вместе в одной экосистеме (Apple Home, Google Home, Amazon Alexa, Home Assistant, Samsung SmartThings и т.д.).
• Локальное управление: общение идёт в первую очередь по локальной сети (Wi-Fi, Thread или Ethernet); облачное подключение опционально.
• Безопасность: шифрование встроено в протокол, комиссионинг защищён.
• Простая настройка: устройства добавляются по QR-коду или вручному коду сопряжения.
• Несколько администраторов: одним устройством могут одновременно управлять несколько контроллеров умного дома.
• Работает поверх IP: Matter использует стандартные IP-сети.

Пара понятий, которые стоит знать прежде, чем читать дальше:

• Узел (node) — одно устройство Matter (в этом руководстве узел — ESP32).
• Эндпоинт (endpoint) — функциональная единица внутри узла. Один узел может предоставлять несколько эндпоинтов (например, управление лампой и датчик температуры).
• Кластер (cluster) — группа связанных атрибутов и команд, относящихся к одной функции (например, у кластера On/Off есть атрибут OnOff и команды On/Off/Toggle).
• Fabric — логическая сеть, которая создаётся, когда контроллер (Apple Home, Google Home, Alexa, Home Assistant и т.д.) добавляет устройство к себе через комиссионинг. Один узел может одновременно состоять в нескольких фабриках.
• Комиссионинг (commissioning) — процесс подключения устройства Matter (узла) к фабрике по QR-коду или 11-значному ручному коду сопряжения. Обычно идёт через BLE или Wi-Fi.
• Wi-Fi: Matter работает поверх IP, и узлы (например, платы ESP32) могут входить в сеть Matter по Wi-Fi.

В Arduino Core для ESP32 библиотека Matter входит начиная с версии 3.1.0, так что ничего дополнительно в Arduino IDE устанавливать не нужно.

Жизненный цикл устройства Matter#

Схема ниже показывает полный путь устройства Matter: от некомиссионированного состояния до штатной работы и (опционально) общего доступа из нескольких экосистем умного дома.

1. Некомиссионированное устройство (узел)

   • первое включение (или сброс);
   • показывает QR-код и ручной код сопряжения;
   • пользователь сканирует QR-код или вводит код в контроллер умного дома (фабрику): Alexa, Apple Home, Google Home, Home Assistant и т.д.

2. Комиссионинг

   • начинается защищённая сессия сопряжения (PASE);
   • контроллер убеждается, что это устройство Matter;
   • устройству передаются учётные данные Wi-Fi (обычно по BLE);
   • устройство вступает в фабрику Matter (например, Alexa на Echo Dot Max).

3. Вход в сеть

   • подключается к Wi-Fi;
   • становится доступным по IPv6 + mDNS.

4. Штатная работа

   • контроллеры находят устройство Matter и управляют им;
   • весь трафик шифруется;
   • всё работает локально, даже без интернета.

5. Несколько администраторов (опционально)

   • исходный QR-код и код сопряжения повторно использовать нельзя;
   • откройте режим сопряжения в приложении первого контроллера, чтобы сгенерировать новый временный ручной код и поделиться устройством;
   • добавьте устройство в другую экосистему по новому коду: Apple Home, Google Home, Home Assistant и т.д.;
   • одно устройство Matter состоит в нескольких фабриках сразу, и управлять им могут несколько экосистем одновременно.

Какие чипы ESP32 поддерживают Matter#

В таблице — чипы ESP32 с поддержкой Matter и сведения о CHIPoBLE. Для чипов без CHIPoBLE учётные данные Wi-Fi придётся вписать прямо в скетч; в остальных случаях их передаёт контроллер по BLE.

* CHIPoBLE — это CHIP (Connected Home over IP), первоначальное название протокола Matter, поверх BLE (Bluetooth Low Energy).

Скетч: устройство Matter On/Off Light на ESP32#

Пример ниже основан на официальной библиотеке Matter из Arduino Core для ESP32. Он превращает плату в полноценное устройство Matter (узел) — лампу вкл/выкл, управляющую выводом GPIO. Устройство можно добавить в любую крупную Matter-экосистему, а ещё — управлять им локально тактовой кнопкой.

/*
  Rui Santos & Sara Santos - Random Nerd Tutorials
  Complete project details at https://RandomNerdTutorials.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 <Arduino.h>
#include <Matter.h>
#include <Preferences.h>

// 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();
    }
  }
}

Исходник кода на GitHub

Дополнительные библиотеки не нужны. В зависимости от платы может понадобиться вписать учётные данные сети в строках кода ниже. Также выберите в меню Tools → Partition Scheme вариант «Huge APP (3MB No OTA/1MB SPIFFS)» — и код заработает сразу.

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

Как работает код#

Ниже — разбор по частям; если детали не нужны, листайте сразу к разделу «Демонстрация».

Подключение библиотек#

#include <Arduino.h>
#include <Matter.h>
#include <Preferences.h>

• Matter.h — основная библиотека Matter (весь стек протокола);
• Preferences.h — сохранение последнего состояния вкл/выкл в энергонезависимой памяти (плата помнит его после перезагрузки).

Подробнее о работе с Preferences — в руководстве ESP32 Save Data Permanently using Preferences Library.

Учётные данные сети#

Эти учётные данные Wi-Fi нужны только если плата не умеет комиссионинг по BLE (Arduino-сборка для ESP32 или ESP32-S2) — тогда скетч подключается к сети сам. Когда Matter использует комиссионинг по BLE (CHIPoBLE), SSID и пароль передаёт хаб, так что плейсхолдеры можно оставить как есть.

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

Эндпоинт Matter#

OnOffLight — эндпоинт Matter, который реализует на ESP32 стандартный кластер On/Off Light.

MatterOnOffLight OnOffLight;

Хранение состояния#

matterPref и onOffPrefKey хранят последнее состояние лампы, чтобы восстановить его после перезагрузки.

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

Вывод светодиода#

Используется встроенный светодиод платы, если он есть, иначе 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

Кнопка BOOT#

Штатная кнопка BOOT на плате ESP32 (обычно GPIO 0) служит для локального управления и заводского сброса (декомиссионинга).

const uint8_t buttonPin = BOOT_PIN;
MatterButton button;

Колбэк setLightOnOff()#

Функция-колбэк setLightOnOff() включает или выключает физический светодиод в соответствии с запрошенным состоянием Matter. Заодно она сохраняет текущее состояние в энергонезависимой памяти — плата вспомнит его и после перезагрузки.

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;
}

setup()#

В setup() инициализируются кнопка и светодиод, запускается последовательный порт.

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

  Serial.begin(115200);

Далее — в зависимости от платы — выполняется подключение к Wi-Fi по учётным данным из скетча, если CHIPoBLE отключён.

// 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

Следующий фрагмент инициализирует хранилище Preferences, читает последнее сохранённое состояние (вкл/выкл), запускает эндпоинт OnOffLight с этим состоянием и регистрирует колбэк setLightOnOff — чтобы физический светодиод обновлялся при изменении состояния из Matter.

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

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

Первая строка ниже запускает стек Matter и дожидается его полной готовности. Затем в монитор последовательного порта выводится начальное состояние лампы, а физическое «устройство» (светодиод) приводится в соответствие с ним.

Matter.begin();
matterWaitUntilReady();

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

OnOffLight.updateAccessory();

loop()#

loop() начинается с вызова matterRestartIfNoFabric(). Это помощник, который проверяет, состоит ли устройство ещё в какой-нибудь фабрике Matter (не удалено ли оно из контроллера вроде Apple Home, Google Home или Alexa). Если фабрики нет (устройство декомиссионировано), стек Matter перезапускается, чтобы устройство снова могло обнаружить себя и пройти комиссионинг.

matterRestartIfNoFabric();

Переменная ev типа matterButtonEvent_t хранит события кнопки (короткое или длинное нажатие).

matterButtonEvent_t ev;

button.poll() — неблокирующая проверка, не нажата ли физическая кнопка BOOT.

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

Короткое нажатие BOOT переключает лампу: была включена — выключится, и наоборот. Новое состояние рассылается всем Matter-контроллерам.

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

Если удерживать BOOT дольше 5 секунд, лампа выключается, а устройство удаляется из всех фабрик Matter — это заводской сброс. После него потребуется новый комиссионинг.

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

Загрузка кода на плату#

После ввода учётных данных сети выполните следующие шаги.

Сначала выберите плату: Tools → Board → ESP32 Arduino → ваша плата (например, ESP32S3 Dev Module).

Затем в меню Tools выберите Partition Scheme: «Huge APP (3MB No OTA/1MB SPIFFS)».

Важно: перед первой загрузкой рекомендуется стереть всю флеш-память. В меню Tools включите опцию Erase All Flash Before Sketch Upload: Enabled — это сотрёт прежние учётные данные Wi-Fi и данные фабрик Matter. Сделайте это хотя бы для первой прошивки или если комиссионинг не удаётся.

Наконец, подключив плату к компьютеру и выбрав правильный последовательный порт, нажмите кнопку загрузки в Arduino IDE.

Комиссионинг: добавление лампы в приложение#

При первой загрузке ESP32 (или после стирания флеша) откройте монитор последовательного порта Arduino IDE и нажмите на плате кнопку RST/EN.

В мониторе появится примерно следующее:

Можно воспользоваться 11-значным ручным кодом или открыть ссылку в браузере — получите QR-код для сканирования в приложении умного дома.

Добавление в Amazon Alexa#

В примере используем приложение Amazon Alexa; шаги для других контроллеров — в следующем разделе.

Откройте приложение Alexa и нажмите значок «+»:

Выберите «Add Device»:

На вопрос, есть ли на устройстве логотип, ответьте «YES», затем отсканируйте QR-код или введите ручной код сопряжения.

Держите телефон рядом с устройством и нажмите «Connect»:

ESP32 не имеет сертификации Matter, но смело подтверждайте добавление кнопкой «Yes».

После успешного комиссионинга в мониторе порта появится строка «Matter Node is commissioned…», а светодиод отразит текущее состояние.

Лампа появится в списке устройств:

Добавление в Apple Home, Google Home, Home Assistant или SmartThings#

Короткие инструкции для других контроллеров. Контроллер — приложение Apple Home, Google Home, Home Assistant или SmartThings — должен уже работать у вас дома.

Apple Home:

• откройте приложение «Дом» на iPhone;
• значок «+» в правом верхнем углу;
• «Добавить аксессуар»;
• отсканируйте QR-код или нажмите «Дополнительные параметры» и введите ручной код сопряжения.

Google Home:

• откройте приложение Google Home;
• значок «+»;
• «Настроить устройство»;
• «Новое устройство»;
• «Устройство Matter»;
• отсканируйте QR-код или введите ручной код.

Home Assistant:

• откройте Home Assistant;
• «Настройки»;
• «Устройства и службы»;
• «Добавить интеграцию»;
• Matter;
• введите ручной код или отсканируйте QR-код.

SmartThings:

• откройте приложение SmartThings;
• значок «+»;
• «Устройства партнёров»: Matter;
• отсканируйте QR-код или введите ручной код.

Важно: после добавления устройства Matter в один контроллер исходный QR-код и ручной код повторно использовать нельзя. Чтобы добавить устройство в другой контроллер, откройте новое окно сопряжения из приложения первого («Поделиться» / «Включить режим сопряжения» / «Ссылка на другую платформу») — получите временный код и используйте его.

Учтите: некоторые приложения предупреждают, что устройство не официальное и не сертифицировано, — всё равно подтверждайте добавление.

Демонстрация#

Из Matter-приложения (например, Alexa) или голосового хаба лампу можно включать и выключать. GPIO меняется по команде, а состояние сохраняется даже после перезагрузки платы.

GPIO ESP32 можно переключать и физической кнопкой BOOT на плате: короткое нажатие меняет состояние вкл/выкл (и обновляет его во всех Matter-контроллерах).

Важно: удержание BOOT дольше 5 секунд выполняет декомиссионинг — заводской сброс устройства. После этого устройство придётся добавлять заново по новому QR-коду или ручному коду.

Если плата перезагрузится, она вспомнит последнее состояние лампы — оно хранится в NVS (Preferences).

Видео с демонстрацией (на английском) — в оригинале статьи.

Если что-то не работает#

Таблица типичных ошибок этого туториала и способов их устранения.

Учтите: в мониторе порта Arduino IDE со временем может накопиться много логов — «sending failed», «transient send error», «request on unknown cluster» и похожие. Обычно они безобидны, и их можно игнорировать — пока устройство остаётся доступным.

Итоги#

В этом руководстве мы превратили ESP32 в устройство Matter — лампу вкл/выкл, прошитую из Arduino IDE, — разобрались с основами протокола и добавили устройство в разные контроллеры: Alexa, Apple Home, Google Home, Home Assistant и SmartThings.

Если хочется других способов управлять GPIO ESP32, загляните в веб-сервер на asynchronous-библиотеках и управление выходами через веб-сервер на ESP-IDF — а для связи плат между собой без роутера есть ESP-NOW.

Спасибо за чтение!