Skip to content

Commit 21ddb09

Browse files
SuGliderCopilotpre-commit-ci-lite[bot]lucasssvaz
authored
feat(matter): examples documentation (#11983)
* feat(matter): Adds README.md file for each example * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): missing information Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * feat(matter): adds ESP32-C5 to supported list and fixes typos * feat(matter): fixes MatterSmartButton.ino name * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): typo * fix(matter): removes bad example * ci(pre-commit): Apply automatic fixes * fix(pre-commit): Fix spelling --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com>
1 parent 57f03ed commit 21ddb09

File tree

24 files changed

+4062
-1
lines changed

24 files changed

+4062
-1
lines changed

‎libraries/Matter/examples/MatterColorLight/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Matter Color Light Example
2+
3+
This example demonstrates how to create a Matter-compatible color light device using an ESP32 SoC microcontroller.\
4+
The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button.
5+
6+
## Supported Targets
7+
8+
| SoC | Wi-Fi | Thread | BLE Commissioning | RGB LED | Status |
9+
| --- | ---- | ------ | ----------------- | ------- | ------ |
10+
| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported |
11+
| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported |
12+
| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported |
13+
| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported |
14+
| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported |
15+
| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported |
16+
| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) |
17+
18+
### Note on Commissioning:
19+
20+
- **ESP32 & ESP32-S2** do not support commissioning over Bluetooth LE. For these chips, you must provide Wi-Fi credentials directly in the sketch code so they can connect to your network manually.
21+
- **ESP32-C6** Although it has Thread support, the ESP32 Arduino Matter Library has been pre compiled using Wi-Fi only. In order to configure it for Thread-only operation it is necessary to build the project as an ESP-IDF component and to disable the Matter Wi-Fi station feature.
22+
- **ESP32-C5** Although it has Thread support, the ESP32 Arduino Matter Library has been pre compiled using Wi-Fi only. In order to configure it for Thread-only operation it is necessary to build the project as an ESP-IDF component and to disable the Matter Wi-Fi station feature.
23+
24+
## Features
25+
26+
- Matter protocol implementation for a color light device
27+
- Support for both Wi-Fi and Thread(*) connectivity
28+
- RGB color control with HSV color model
29+
- State persistence using `Preferences` library
30+
- Button control for toggling light and factory reset
31+
- Matter commissioning via QR code or manual pairing code
32+
- Integration with Apple HomeKit, Amazon Alexa, and Google Home
33+
(*) It is necessary to compile the project using Arduino as IDF Component.
34+
35+
## Hardware Requirements
36+
37+
- ESP32 compatible development board (see supported targets table)
38+
- RGB LED connected to GPIO pins (or using built-in RGB LED)
39+
- User button for manual control (uses BOOT button by default)
40+
41+
## Pin Configuration
42+
43+
- **RGB LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2
44+
- **Button**: Uses `BOOT_PIN` by default
45+
46+
## Software Setup
47+
48+
### Prerequisites
49+
50+
1. Install the Arduino IDE (2.0 or newer recommended)
51+
2. Install ESP32 Arduino Core with Matter support
52+
3. ESP32 Arduino libraries:
53+
- `Matter`
54+
- `Preferences`
55+
- `Wi-Fi` (only for ESP32 and ESP32-S2)
56+
57+
### Configuration
58+
59+
Before uploading the sketch, configure the following:
60+
61+
1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2):
62+
```cpp
63+
const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID
64+
const char *password = "your-password"; // Change to your Wi-Fi password
65+
```
66+
67+
2. **LED pin configuration** (if not using built-in RGB LED):
68+
``` cpp
69+
const uint8_t ledPin = 2; // Set your RGB LED pin here
70+
```
71+
3. **Button pin configuration** (optional):
72+
By default, the `BOOT` button (GPIO 0) is used for the Light On/Off manual control. You can change this to a different pin if needed.
73+
```cpp
74+
const uint8_t buttonPin = 0; // Set your button pin here
75+
```
76+
77+
## Building and Flashing
78+
79+
1. Open the `MatterColorLight.ino` sketch in the Arduino IDE.
80+
2. Select your ESP32 board from the **Tools > Board** menu.
81+
3. Connect your ESP32 board to your computer via USB.
82+
4. Click the **Upload** button to compile and flash the sketch.
83+
84+
## Expected Output
85+
86+
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:
87+
88+
```
89+
Connecting to your-wifi-ssid
90+
.......
91+
Wi-Fi connected
92+
IP address: 192.168.1.100
93+
94+
Matter Node is not commissioned yet.
95+
Initiate the device discovery in your Matter environment.
96+
Commission it to your Matter hub with the manual pairing code or QR code
97+
Manual pairing code: 34970112332
98+
QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00
99+
Matter Node not commissioned yet. Waiting for commissioning.
100+
Matter Node not commissioned yet. Waiting for commissioning.
101+
...
102+
Initial state: ON | RGB Color: (0,0,255)
103+
Matter Node is commissioned and connected to the network. Ready for use.
104+
```
105+
106+
## Using the Device
107+
108+
### Manual Control
109+
110+
The user button (BOOT button by default) provides manual control:
111+
112+
- **Short press of the button**: Toggle light on/off
113+
- **Long press (>5 seconds)**: Factory reset the device (decommission)
114+
115+
### Smart Home Integration
116+
117+
Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device.
118+
119+
#### Apple Home
120+
121+
1. Open the Home app on your iOS device
122+
2. Tap the "+" button > Add Accessory
123+
3. Scan the QR code displayed in the Serial Monitor, or
124+
4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code
125+
5. Follow the prompts to complete setup
126+
6. The device will appear as a color light in your Home app
127+
128+
#### Amazon Alexa
129+
130+
1. Open the Alexa app
131+
2. Tap More > Add Device > Matter
132+
3. Select "Scan QR code" or "Enter code manually"
133+
4. Complete the setup process
134+
5. The light will appear in your Alexa app
135+
136+
#### Google Home
137+
138+
1. Open the Google Home app
139+
2. Tap "+" > Set up device > New device
140+
3. Choose "Matter device"
141+
4. Scan the QR code or enter the manual pairing code
142+
5. Follow the prompts to complete setup
143+
144+
## Code Structure
145+
146+
The MatterColorLight example consists of the following main components:
147+
148+
1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter endpoint, restores the last known state from `Preferences`, and registers callbacks for state changes.
149+
2. **`loop()`**: Checks the Matter commissioning state, handles button input for toggling the light and factory reset, and allows the Matter stack to process events.
150+
3. **Callbacks**:
151+
- `setLightState()`: Controls the physical RGB LED.
152+
- `onChangeOnOff()`: Handles on/off state changes.
153+
- `onChangeColorHSV()`: Handles color changes.
154+
155+
## Troubleshooting
156+
157+
- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured
158+
- **RGB LED not responding**: Verify pin configurations and connections
159+
- **Failed to commission**: Try factory resetting the device by long-pressing the button. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port <PORT> erase_flash`
160+
- **No serial output**: Check baudrate (115200) and USB connection
161+
162+
## License
163+
164+
This example is licensed under the Apache License, Version 2.0.

‎libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,5 +77,5 @@ void loop() {
7777
Serial.println("====> Decommissioning in 30 seconds. <====");
7878
delay(30000);
7979
Matter.decommission();
80-
Serial.println("Matter Node is decommissioned. Commsssioning widget shall start over.");
80+
Serial.println("Matter Node is decommissioned. Commissioning widget shall start over.");
8181
}

‎libraries/Matter/examples/MatterCommissionTest/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Matter Commission Test Example
2+
3+
This example demonstrates how to test Matter commissioning functionality using an ESP32 SoC microcontroller.\
4+
The application showcases Matter commissioning, device connection to smart home ecosystems, and automatic decommissioning after a 30-second delay for continuous testing cycles.
5+
6+
## Supported Targets
7+
8+
| SoC | Wi-Fi | Thread | BLE Commissioning | Status |
9+
| --- | ---- | ------ | ----------------- | ------ |
10+
| ESP32 | ✅ | ❌ | ❌ | Fully supported |
11+
| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported |
12+
| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported |
13+
| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported |
14+
| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported |
15+
| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported |
16+
| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) |
17+
18+
### Note on Commissioning:
19+
20+
- **ESP32 & ESP32-S2** do not support commissioning over Bluetooth LE. For these chips, you must provide Wi-Fi credentials directly in the sketch code so they can connect to your network manually.
21+
- **ESP32-C6** Although it has Thread support, the ESP32 Arduino Matter Library has been pre compiled using Wi-Fi only. In order to configure it for Thread-only operation it is necessary to build the project as an ESP-IDF component and to disable the Matter Wi-Fi station feature.
22+
- **ESP32-C5** Although it has Thread support, the ESP32 Arduino Matter Library has been pre compiled using Wi-Fi only. In order to configure it for Thread-only operation it is necessary to build the project as an ESP-IDF component and to disable the Matter Wi-Fi station feature.
23+
24+
## Features
25+
26+
- Matter protocol implementation for an on/off light device
27+
- Support for both Wi-Fi and Thread(*) connectivity
28+
- Matter commissioning via QR code or manual pairing code
29+
- Automatic decommissioning after 30 seconds for continuous testing
30+
- Integration with Apple HomeKit, Amazon Alexa, and Google Home
31+
- Simple test tool for validating Matter commissioning workflows
32+
(*) It is necessary to compile the project using Arduino as IDF Component.
33+
34+
## Hardware Requirements
35+
36+
- ESP32 compatible development board (see supported targets table)
37+
38+
## Software Setup
39+
40+
### Prerequisites
41+
42+
1. Install the Arduino IDE (2.0 or newer recommended)
43+
2. Install ESP32 Arduino Core with Matter support
44+
3. ESP32 Arduino libraries:
45+
- `Matter`
46+
- `Wi-Fi` (only for ESP32 and ESP32-S2)
47+
48+
### Configuration
49+
50+
Before uploading the sketch, configure the following:
51+
52+
1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2):
53+
```cpp
54+
const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID
55+
const char *password = "your-password"; // Change to your Wi-Fi password
56+
```
57+
58+
## Building and Flashing
59+
60+
1. Open the `MatterCommissionTest.ino` sketch in the Arduino IDE.
61+
2. Select your ESP32 board from the **Tools > Board** menu.
62+
3. Connect your ESP32 board to your computer via USB.
63+
4. Click the **Upload** button to compile and flash the sketch.
64+
65+
## Expected Output
66+
67+
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:
68+
69+
```
70+
Connecting to your-wifi-ssid
71+
.......
72+
Wi-Fi connected
73+
IP address: 192.168.1.100
74+
75+
Matter Node is not commissioned yet.
76+
Initiate the device discovery in your Matter environment.
77+
Commission it to your Matter hub with the manual pairing code or QR code
78+
Manual pairing code: 34970112332
79+
QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00
80+
Matter Fabric not commissioned yet. Waiting for commissioning.
81+
Matter Fabric not commissioned yet. Waiting for commissioning.
82+
...
83+
Matter Node is commissioned and connected to the network.
84+
====> Decommissioning in 30 seconds. <====
85+
Matter Node is decommissioned. Commissioning widget shall start over.
86+
87+
Matter Node is not commissioned yet.
88+
Initiate the device discovery in your Matter environment.
89+
...
90+
```
91+
92+
## Using the Device
93+
94+
### Test Cycle
95+
96+
The device operates in a continuous test cycle:
97+
98+
1. **Commissioning Phase**: The device waits for Matter commissioning. It displays the manual pairing code and QR code URL in the Serial Monitor.
99+
2. **Commissioned Phase**: Once commissioned, the device is connected to the Matter network and ready for use.
100+
3. **Automatic Decommissioning**: After 30 seconds, the device automatically decommissions itself.
101+
4. **Repeat**: The cycle repeats, allowing you to test the commissioning process multiple times.
102+
103+
### Smart Home Integration
104+
105+
Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device during each test cycle.
106+
107+
#### Apple Home
108+
109+
1. Open the Home app on your iOS device
110+
2. Tap the "+" button > Add Accessory
111+
3. Scan the QR code displayed in the Serial Monitor, or
112+
4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code
113+
5. Follow the prompts to complete setup
114+
6. The device will appear as an on/off light in your Home app
115+
7. After 30 seconds, the device will automatically decommission and the cycle will repeat
116+
117+
#### Amazon Alexa
118+
119+
1. Open the Alexa app
120+
2. Tap More > Add Device > Matter
121+
3. Select "Scan QR code" or "Enter code manually"
122+
4. Complete the setup process
123+
5. The light will appear in your Alexa app
124+
6. After 30 seconds, the device will automatically decommission and the cycle will repeat
125+
126+
#### Google Home
127+
128+
1. Open the Google Home app
129+
2. Tap "+" > Set up device > New device
130+
3. Choose "Matter device"
131+
4. Scan the QR code or enter the manual pairing code
132+
5. Follow the prompts to complete setup
133+
6. After 30 seconds, the device will automatically decommission and the cycle will repeat
134+
135+
## Code Structure
136+
137+
The MatterCommissionTest example consists of the following main components:
138+
139+
1. **`setup()`**: Configures Wi-Fi (if needed), initializes the Matter On/Off Light endpoint, and starts the Matter stack.
140+
2. **`loop()`**: Checks the Matter commissioning state, displays pairing information when not commissioned, waits for commissioning, and then automatically decommissions after 30 seconds to repeat the cycle.
141+
142+
## Troubleshooting
143+
144+
- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured
145+
- **Failed to commission**: Try waiting for the next cycle after decommissioning. Other option would be to erase the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port <PORT> erase_flash`
146+
- **No serial output**: Check baudrate (115200) and USB connection
147+
- **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 30 seconds to allow continuous testing
148+
149+
## License
150+
151+
This example is licensed under the Apache License, Version 2.0.

0 commit comments

Comments
 (0)