Skip to content

Commit 27c4a9c

Browse files
SuGliderSuGlider
committed
feat(matter): Adds README.md file for each example
1 parent 8cb2659 commit 27c4a9c

File tree

20 files changed

+3590
-0
lines changed

20 files changed

+3590
-0
lines changed

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

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

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

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

0 commit comments

Comments
 (0)