libraries/Matter/examples/MatterMinimum/README.md
This example demonstrates the smallest code required to create a Matter-compatible device using an ESP32 SoC microcontroller.
The application showcases the minimal implementation for Matter commissioning and device control via smart home ecosystems. This is an ideal starting point for understanding Matter basics and building more complex devices.
| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status |
|---|---|---|---|---|---|
| ESP32 | ✅ | ❌ | ❌ | Optional | Fully supported |
| ESP32-S2 | ✅ | ❌ | ❌ | Optional | Fully supported |
| ESP32-S3 | ✅ | ❌ | ✅ | Optional | Fully supported |
| ESP32-C3 | ✅ | ❌ | ✅ | Optional | Fully supported |
| ESP32-C5 | ❌ | ✅ | ✅ | Optional | Supported (Thread only) |
| ESP32-C6 | ✅ | ❌ | ✅ | Optional | Fully supported |
| ESP32-H2 | ❌ | ✅ | ✅ | Optional | Supported (Thread only) |
LED_BUILTIN if defined, otherwise pin 2BOOT_PIN by default (only for factory reset)MatterWi-Fi (only for ESP32 and ESP32-S2)Before uploading the sketch, configure the following:
Wi-Fi credentials (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2):
const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID
const char *password = "your-password"; // Change to your Wi-Fi password
LED pin configuration (if not using built-in LED):
const uint8_t ledPin = 2; // Set your LED pin here
Button pin configuration (optional):
By default, the BOOT button (GPIO 0) is used for factory reset. You can change this to a different pin if needed.
const uint8_t buttonPin = BOOT_PIN; // Set your button pin here
MatterMinimum.ino sketch in the Arduino IDE.Once the sketch is running, open the Serial Monitor at a baud rate of 115200. The Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning:
Connecting to your-wifi-ssid
.......
Wi-Fi connected
Matter Node is not commissioned yet.
Initiate the device discovery in your Matter environment.
Commission it to your Matter hub with the manual pairing code or QR code
Manual pairing code: 34970112332
QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00
After commissioning, the device will be ready for control via Matter apps. No additional status messages are printed in this minimal example.
The user button (BOOT button by default) provides factory reset functionality:
Note: This minimal example does not include button toggle functionality. To add manual toggle control, you can extend the code with additional button handling logic.
Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device.
The MatterMinimum example consists of the following main components:
setup(): Initializes hardware (button, LED), configures Wi-Fi (if needed), initializes the Matter on/off light endpoint, registers the callback function, and starts the Matter stack. Displays commissioning information if not yet commissioned.
loop(): Handles button input for factory reset (long press >5 seconds) and allows the Matter stack to process events. This minimal example does not include commissioning state checking in the loop - it only checks once in setup.
onOffLightCallback(): Simple callback function that controls the LED based on the on/off state received from the Matter controller. This is the minimal callback implementation.
This minimal example can be extended with additional features:
Preferences library to save the last known stateArduino IDE Menu -> Tools -> Erase All Flash Before Sketch Upload: "Enabled" or directly with esptool.py --port <PORT> erase_flashThis example is licensed under the Apache License, Version 2.0.