Skip to content

Commit 2440c13

Browse files
SuGliderSuGlider
committed
feat(matter): adds Matter Status example and documentation
1 parent b305fb9 commit 2440c13

File tree

3 files changed

+327
-0
lines changed

3 files changed

+327
-0
lines changed

‎libraries/Matter/examples/MatterStatus/MatterStatus.ino‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// Matter Status Example
16+
// This example demonstrates how to check enabled Matter features and connectivity status
17+
// It implements a basic on/off light and reports capability and connection status
18+
19+
#include <Matter.h>
20+
// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
21+
#if !CONFIG_ENABLE_CHIPOBLE // ESP32 and ESP32-S2 do not support BLE commissioning
22+
// if the device can be commissioned using BLE, WiFi is not used - save flash space
23+
#include <WiFi.h>
24+
// WiFi is manually set and started
25+
const char *ssid = "your-ssid"; // Change this to your WiFi SSID
26+
const char *password = "your-password"; // Change this to your WiFi password
27+
#endif
28+
29+
// List of Matter Endpoints for this Node
30+
// On/Off Light Endpoint
31+
MatterOnOffLight OnOffLight;
32+
33+
// set your board LED pin here
34+
#ifdef LED_BUILTIN
35+
const uint8_t ledPin = LED_BUILTIN;
36+
#else
37+
const uint8_t ledPin = 2; // Set your pin here if your board has not defined LED_BUILTIN
38+
#warning "Do not forget to set the LED pin"
39+
#endif
40+
41+
// Matter Protocol Endpoint Callback
42+
bool setLightOnOff(bool state) {
43+
Serial.printf("User Callback :: New Light State = %s\r\n", state ? "ON" : "OFF");
44+
if (state) {
45+
digitalWrite(ledPin, HIGH);
46+
} else {
47+
digitalWrite(ledPin, LOW);
48+
}
49+
// This callback must return the success state to Matter core
50+
return true;
51+
}
52+
53+
void setup() {
54+
// Initialize the LED (light) GPIO
55+
pinMode(ledPin, OUTPUT);
56+
digitalWrite(ledPin, LOW); // Start with light OFF
57+
58+
Serial.begin(115200);
59+
delay(1000);
60+
Serial.println("\n========================================");
61+
Serial.println("Matter Status Example");
62+
Serial.println("========================================\n");
63+
64+
// Report enabled features
65+
Serial.println("=== Enabled Features ===");
66+
Serial.printf("WiFi Station Enabled: %s\r\n", Matter.isWiFiStationEnabled() ? "YES" : "NO");
67+
Serial.printf("WiFi Access Point Enabled: %s\r\n", Matter.isWiFiAccessPointEnabled() ? "YES" : "NO");
68+
Serial.printf("Thread Enabled: %s\r\n", Matter.isThreadEnabled() ? "YES" : "NO");
69+
Serial.printf("BLE Commissioning Enabled: %s\r\n", Matter.isBLECommissioningEnabled() ? "YES" : "NO");
70+
Serial.println();
71+
72+
// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
73+
#if !CONFIG_ENABLE_CHIPOBLE
74+
// We start by connecting to a WiFi network
75+
if (Matter.isWiFiStationEnabled()) {
76+
Serial.print("Connecting to ");
77+
Serial.println(ssid);
78+
WiFi.mode(WIFI_STA);
79+
WiFi.begin(ssid, password);
80+
while (WiFi.status() != WL_CONNECTED) {
81+
delay(500);
82+
Serial.print(".");
83+
}
84+
Serial.println("");
85+
Serial.println("WiFi connected");
86+
Serial.print("IP address: ");
87+
Serial.println(WiFi.localIP());
88+
}
89+
#endif
90+
91+
// Initialize On/Off Light endpoint
92+
OnOffLight.begin(false); // Start with light OFF
93+
OnOffLight.onChange(setLightOnOff);
94+
95+
// Start Matter
96+
Matter.begin();
97+
Serial.println("Matter started");
98+
Serial.println();
99+
100+
// Print commissioning information
101+
Serial.println("========================================");
102+
Serial.println("Matter Node is not commissioned yet.");
103+
Serial.println("Initiate the device discovery in your Matter environment.");
104+
Serial.println("Commission it to your Matter hub with the manual pairing code or QR code");
105+
Serial.printf("Manual pairing code: %s\r\n", Matter.getManualPairingCode().c_str());
106+
Serial.printf("QR code URL: %s\r\n", Matter.getOnboardingQRCodeUrl().c_str());
107+
Serial.println("========================================\n");
108+
}
109+
110+
void loop() {
111+
// Report connection status every 10 seconds
112+
Serial.println("=== Connection Status ===");
113+
Serial.printf("WiFi Connected: %s\r\n", Matter.isWiFiConnected() ? "YES" : "NO");
114+
Serial.printf("Thread Connected: %s\r\n", Matter.isThreadConnected() ? "YES" : "NO");
115+
Serial.printf("Device Connected: %s\r\n", Matter.isDeviceConnected() ? "YES" : "NO");
116+
Serial.printf("Device Commissioned: %s\r\n", Matter.isDeviceCommissioned() ? "YES" : "NO");
117+
Serial.println();
118+
delay(10000);
119+
}

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

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Matter Status Example
2+
3+
This example demonstrates how to check enabled Matter features and connectivity status using the Matter library's capability query functions. It implements a basic on/off light device and periodically reports the status of enabled features and network connections.
4+
5+
## Supported Targets
6+
7+
| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status |
8+
| --- | ---- | ------ | ----------------- | --- | ------ |
9+
| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported |
10+
| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported |
11+
| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported |
12+
| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported |
13+
| ESP32-C5 | ✅ | ❌ | ✅ | 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 Wi-Fi 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 precompiled 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.
21+
- **ESP32-C5** Although it has Thread support, the ESP32 Arduino Matter Library has been precompiled 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+
23+
## Features
24+
25+
- Matter protocol implementation for an on/off light device
26+
- **Capability reporting**: Checks and reports enabled Matter features at startup
27+
- `isWiFiStationEnabled()`: Checks if WiFi Station mode is supported and enabled
28+
- `isWiFiAccessPointEnabled()`: Checks if WiFi AP mode is supported and enabled
29+
- `isThreadEnabled()`: Checks if Thread network is supported and enabled
30+
- `isBLECommissioningEnabled()`: Checks if BLE commissioning is supported and enabled
31+
- **Connection status monitoring**: Reports connection status every 10 seconds
32+
- `isWiFiConnected()`: Checks WiFi connection status (if WiFi Station is enabled)
33+
- `isThreadConnected()`: Checks Thread connection status (if Thread is enabled)
34+
- `isDeviceConnected()`: Checks overall device connectivity (WiFi or Thread)
35+
- `isDeviceCommissioned()`: Checks if the device is commissioned to a Matter fabric
36+
- Simple on/off light control
37+
- Matter commissioning via QR code or manual pairing code
38+
- Integration with Apple HomeKit, Amazon Alexa, and Google Home
39+
40+
## Hardware Requirements
41+
42+
- ESP32 compatible development board (see supported targets table)
43+
- LED connected to GPIO pin (or using built-in LED) for visual feedback
44+
45+
## Pin Configuration
46+
47+
- **LED**: Uses `LED_BUILTIN` if defined, otherwise pin 2
48+
49+
## Software Setup
50+
51+
### Prerequisites
52+
53+
1. Install the Arduino IDE (2.0 or newer recommended)
54+
2. Install ESP32 Arduino Core with Matter support
55+
3. ESP32 Arduino libraries:
56+
- `Matter`
57+
- `Wi-Fi` (only for ESP32 and ESP32-S2)
58+
59+
### Configuration
60+
61+
Before uploading the sketch, configure the following:
62+
63+
1. **Wi-Fi Credentials** (for ESP32 and ESP32-S2 only):
64+
```cpp
65+
const char *ssid = "your-ssid";
66+
const char *password = "your-password";
67+
```
68+
69+
2. **LED pin configuration** (if not using built-in LED):
70+
```cpp
71+
const uint8_t ledPin = 2; // Set your LED pin here
72+
```
73+
74+
## Building and Flashing
75+
76+
1. Open the `MatterStatus.ino` sketch in the Arduino IDE.
77+
2. Select your ESP32 board from the **Tools > Board** menu.
78+
3. Select **"Huge APP (3MB No OTA/1MB SPIFFS)"** from **Tools > Partition Scheme** menu.
79+
4. Enable **"Erase All Flash Before Sketch Upload"** option from **Tools** menu.
80+
5. Connect your ESP32 board to your computer via USB.
81+
6. Click the **Upload** button to compile and flash the sketch.
82+
83+
## Expected Output
84+
85+
Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following:
86+
87+
```
88+
========================================
89+
Matter Status Example
90+
========================================
91+
92+
=== Enabled Features ===
93+
WiFi Station Enabled: YES
94+
WiFi Access Point Enabled: NO
95+
Thread Enabled: NO
96+
BLE Commissioning Enabled: NO
97+
98+
Connecting to your-ssid
99+
.......
100+
WiFi connected
101+
IP address: 192.168.1.100
102+
Matter started
103+
104+
========================================
105+
Matter Node is not commissioned yet.
106+
Initiate the device discovery in your Matter environment.
107+
Commission it to your Matter hub with the manual pairing code or QR code
108+
Manual pairing code: 34970112332
109+
QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT:Y.K9042C00KA0648G00
110+
========================================
111+
112+
=== Connection Status ===
113+
WiFi Connected: YES
114+
Thread Connected: NO
115+
Device Connected: YES
116+
Device Commissioned: NO
117+
118+
=== Connection Status ===
119+
WiFi Connected: YES
120+
Thread Connected: NO
121+
Device Connected: YES
122+
Device Commissioned: NO
123+
124+
... (reports every 10 seconds)
125+
126+
User Callback :: New Light State = ON
127+
=== Connection Status ===
128+
WiFi Connected: YES
129+
Thread Connected: NO
130+
Device Connected: YES
131+
Device Commissioned: YES
132+
133+
... (reports every 10 seconds)
134+
```
135+
136+
## Usage
137+
138+
### Capability Queries
139+
140+
The example demonstrates the use of capability query functions that check both hardware support (SOC capabilities) and Matter configuration:
141+
142+
- **`Matter.isWiFiStationEnabled()`**: Returns `true` if the device supports WiFi Station mode and it's enabled in Matter configuration
143+
- **`Matter.isWiFiAccessPointEnabled()`**: Returns `true` if the device supports WiFi AP mode and it's enabled in Matter configuration
144+
- **`Matter.isThreadEnabled()`**: Returns `true` if the device supports Thread networking and it's enabled in Matter configuration
145+
- **`Matter.isBLECommissioningEnabled()`**: Returns `true` if the device supports BLE and BLE commissioning is enabled
146+
147+
These functions are useful for:
148+
- Determining which features are available on the current device
149+
- Adapting application behavior based on available capabilities
150+
- Debugging configuration issues
151+
152+
### Connection Status Monitoring
153+
154+
The example periodically reports connection status every 10 seconds:
155+
156+
- **`Matter.isWiFiConnected()`**: Returns `true` if WiFi Station is connected (only available if WiFi Station is enabled)
157+
- **`Matter.isThreadConnected()`**: Returns `true` if Thread is attached to a network (only available if Thread is enabled)
158+
- **`Matter.isDeviceConnected()`**: Returns `true` if the device is connected via WiFi or Thread (overall connectivity status)
159+
- **`Matter.isDeviceCommissioned()`**: Returns `true` if the device has been commissioned to a Matter fabric
160+
161+
### Smart Home Integration
162+
163+
Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. Once commissioned, you can control the light from your smart home app.
164+
165+
## Code Structure
166+
167+
- **`setup()`**:
168+
- Initializes hardware (LED)
169+
- Reports enabled features using capability query functions
170+
- Connects to WiFi (if needed and enabled)
171+
- Initializes On/Off Light endpoint
172+
- Starts Matter stack
173+
- Prints commissioning information
174+
175+
- **`loop()`**:
176+
- Reports connection status every 10 seconds
177+
- All light control is handled via Matter callbacks
178+
179+
- **Callbacks**:
180+
- `setLightOnOff()`: Controls the physical LED based on the on/off state and prints the state change to Serial Monitor
181+
182+
## Troubleshooting
183+
184+
1. **Device not discoverable**: Ensure Wi-Fi is connected (for ESP32/ESP32-S2) or BLE is enabled (for other chips).
185+
186+
2. **Capability queries return unexpected values**: These functions check both hardware support and Matter configuration. Verify that the features are enabled in your Matter build configuration.
187+
188+
3. **Connection status not updating**: The status is reported every 10 seconds. Check Serial Monitor output to see the periodic reports.
189+
190+
4. **LED not responding**: Verify pin configurations and connections.
191+
192+
5. **Failed to commission**: Try factory resetting the device by calling `Matter.decommission()`. 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`
193+
194+
## Related Documentation
195+
196+
- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html)
197+
- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html)
198+
- [Matter On/Off Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_on_off_light.html)
199+
200+
## License
201+
202+
This example is licensed under the Apache License, Version 2.0.
203+

‎libraries/Matter/examples/MatterStatus/ci.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
fqbn_append: PartitionScheme=huge_app
2+
3+
requires:
4+
- CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y
5+

0 commit comments

Comments
 (0)