From 27c4a9c9d297db53e858ce90d35b2b988890bcb3 Mon Sep 17 00:00:00 2001 From: SuGlider Date: Wed, 5 Nov 2025 05:00:18 -0300 Subject: [PATCH 01/10] feat(matter): Adds README.md file for each example --- .../examples/MatterColorLight/README.md | 162 +++++++++++ .../examples/MatterCommissionTest/README.md | 150 ++++++++++ .../examples/MatterComposedLights/README.md | 174 ++++++++++++ .../examples/MatterContactSensor/README.md | 171 +++++++++++ .../examples/MatterDimmableLight/README.md | 169 +++++++++++ .../MatterEnhancedColorLight/README.md | 176 ++++++++++++ .../Matter/examples/MatterEvents/README.md | 180 ++++++++++++ libraries/Matter/examples/MatterFan/README.md | 193 +++++++++++++ .../examples/MatterHumiditySensor/README.md | 188 +++++++++++++ .../README.md | 204 ++++++++++++++ .../Matter/examples/MatterMinimum/README.md | 170 +++++++++++ .../examples/MatterOccupancySensor/README.md | 266 ++++++++++++++++++ .../examples/MatterOnIdentify/README.md | 212 ++++++++++++++ .../examples/MatterOnOffLight/README.md | 180 ++++++++++++ .../examples/MatterOnOffPlugin/README.md | 197 +++++++++++++ .../examples/MatterPressureSensor/README.md | 190 +++++++++++++ .../examples/MatterSmartButon/README.md | 174 ++++++++++++ .../examples/MatterTemperatureLight/README.md | 0 .../MatterTemperatureSensor/README.md | 205 ++++++++++++++ .../examples/MatterThermostat/README.md | 229 +++++++++++++++ 20 files changed, 3590 insertions(+) create mode 100644 libraries/Matter/examples/MatterColorLight/README.md create mode 100644 libraries/Matter/examples/MatterCommissionTest/README.md create mode 100644 libraries/Matter/examples/MatterComposedLights/README.md create mode 100644 libraries/Matter/examples/MatterContactSensor/README.md create mode 100644 libraries/Matter/examples/MatterDimmableLight/README.md create mode 100644 libraries/Matter/examples/MatterEnhancedColorLight/README.md create mode 100644 libraries/Matter/examples/MatterEvents/README.md create mode 100644 libraries/Matter/examples/MatterFan/README.md create mode 100644 libraries/Matter/examples/MatterHumiditySensor/README.md create mode 100644 libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md create mode 100644 libraries/Matter/examples/MatterMinimum/README.md create mode 100644 libraries/Matter/examples/MatterOccupancySensor/README.md create mode 100644 libraries/Matter/examples/MatterOnIdentify/README.md create mode 100644 libraries/Matter/examples/MatterOnOffLight/README.md create mode 100644 libraries/Matter/examples/MatterOnOffPlugin/README.md create mode 100644 libraries/Matter/examples/MatterPressureSensor/README.md create mode 100644 libraries/Matter/examples/MatterSmartButon/README.md create mode 100644 libraries/Matter/examples/MatterTemperatureLight/README.md create mode 100644 libraries/Matter/examples/MatterTemperatureSensor/README.md create mode 100644 libraries/Matter/examples/MatterThermostat/README.md diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md new file mode 100644 index 00000000000..75e9de65b9b --- /dev/null +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -0,0 +1,162 @@ +# Matter Color Light Example + +This example demonstrates how to create a Matter-compatible color light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| --- | ---- | ------ | ----------------- | ------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a color light device +- Support for both WiFi and Thread(*) connectivity +- RGB color control with HSV color model +- State persistence using `Preferences` library +- Button control for toggling light and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- RGB LED connected to GPIO pins (or using built-in RGB LED) +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **RGB LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. Install required libraries: + - `Matter` + - `Preferences` + - `WiFi` + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in RGB LED): + ``` cpp + const uint8_t ledPin = 2; // Set your RGB LED pin here + ``` +3. **Button pin configuration** (optional): + 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. + ```cpp + const uint8_t buttonPin = 0; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterColorLight.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: ON | RGB Color: (0,0,255) +Matter Node is commissioned and connected to the network. Ready for use. +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle light on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a color light in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup + +## Code Structure + +The MatterColorLight example consists of the following main components: + +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. +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. +3. **Callbacks**: + - `setLightState()`: Controls the physical RGB LED. + - `onChangeOnOff()`: Handles on/off state changes. + - `onChangeColorHSV()`: Handles color changes. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **RGB LED not responding**: Verify pin configurations and connections +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. \ No newline at end of file diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md new file mode 100644 index 00000000000..ba438fdf0b7 --- /dev/null +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -0,0 +1,150 @@ +# Matter Commission Test Example + +This example demonstrates how to test Matter commissioning functionality using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device connection to smart home ecosystems, and automatic decommissioning after a 30-second delay for continuous testing cycles. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an on/off light device +- Support for both WiFi and Thread(*) connectivity +- Matter commissioning via QR code or manual pairing code +- Automatic decommissioning after 30 seconds for continuous testing +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +- Simple test tool for validating Matter commissioning workflows +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +## Building and Flashing + +1. Open the `MatterCommissionTest.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Fabric not commissioned yet. Waiting for commissioning. +Matter Fabric not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. +====> Decommissioning in 30 seconds. <==== +Matter Node is decommissioned. Commsssioning widget shall start over. + +Matter Node is not commissioned yet. +Initiate the device discovery in your Matter environment. +... +``` + +## Using the Device + +### Test Cycle + +The device operates in a continuous test cycle: + +1. **Commissioning Phase**: The device waits for Matter commissioning. It displays the manual pairing code and QR code URL in the Serial Monitor. +2. **Commissioned Phase**: Once commissioned, the device is connected to the Matter network and ready for use. +3. **Automatic Decommissioning**: After 30 seconds, the device automatically decommissions itself. +4. **Repeat**: The cycle repeats, allowing you to test the commissioning process multiple times. + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device during each test cycle. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off light in your Home app +7. After 30 seconds, the device will automatically decommission and the cycle will repeat + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app +6. After 30 seconds, the device will automatically decommission and the cycle will repeat + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. After 30 seconds, the device will automatically decommission and the cycle will repeat + +## Code Structure + +The MatterCommissionTest example consists of the following main components: + +1. **`setup()`**: Configures WiFi (if needed), initializes the Matter On/Off Light endpoint, and starts the Matter stack. +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. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection +- **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 30 seconds to allow continuous testing + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterComposedLights/README.md b/libraries/Matter/examples/MatterComposedLights/README.md new file mode 100644 index 00000000000..751b26572b2 --- /dev/null +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -0,0 +1,174 @@ +# Matter Composed Lights Example + +This example demonstrates how to create a Matter node with multiple light endpoints using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, a single Matter node containing three different light types (On/Off Light, Dimmable Light, and Color Light), and factory reset using a physical button. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a composed device with multiple light endpoints +- Three light endpoints in a single Matter node: + - Light #1: Simple On/Off Light + - Light #2: Dimmable Light (on/off with brightness control) + - Light #3: Color Light (RGB color control) +- Support for both WiFi and Thread(*) connectivity +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +- Periodic state display of all three lights +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default for factory reset (long press >5 seconds) + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterComposedLights.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +====================== +Matter Light #1 is OFF +Matter Light #2 is OFF +Matter Light #3 is OFF +====================== +Light1 changed state to: ON +Light2 changed state to: ON +Light3 changed state to: ON +====================== +Matter Light #1 is ON +Matter Light #2 is ON +Matter Light #3 is ON +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. After commissioning, you will see three separate light devices in your smart home app: + +- **Light #1**: Simple on/off light +- **Light #2**: Dimmable light with brightness control +- **Light #3**: Color light with RGB color control + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as three separate lights in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The three lights will appear in your Alexa app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. The three lights will appear in your Google Home app + +## Code Structure + +The MatterComposedLights example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up three Matter endpoints (OnOffLight, DimmableLight, ColorLight), and registers callbacks for state changes. +2. **`loop()`**: Checks the Matter commissioning state, displays the state of all three lights every 5 seconds, handles button input for factory reset, and allows the Matter stack to process events. +3. **Callbacks**: + - `setLightOnOff1()`: Handles on/off state changes for Light #1. + - `setLightOnOff2()`: Handles on/off state changes for Light #2. + - `setLightOnOff3()`: Handles on/off state changes for Light #3. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Only one or two lights appear**: Some smart home platforms may group or display lights differently. Check your app's device list +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterContactSensor/README.md b/libraries/Matter/examples/MatterContactSensor/README.md new file mode 100644 index 00000000000..3047bcd2e4f --- /dev/null +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -0,0 +1,171 @@ +# Matter Contact Sensor Example + +This example demonstrates how to create a Matter-compatible contact sensor device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, manual control using a physical button, and automatic simulation of contact state changes. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| --- | ---- | ------ | ----------------- | --- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a contact sensor device +- Support for both WiFi and Thread(*) connectivity +- Contact state indication using LED (ON = Closed, OFF = Open) +- Automatic simulation of contact state changes every 20 seconds +- Button control for toggling contact state and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- LED connected to GPIO pins (or using built-in LED) to indicate contact state +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in LED): + ```cpp + const uint8_t ledPin = 2; // Set your LED pin here + ``` + +3. **Button pin configuration** (optional): + By default, the `BOOT` button (GPIO 0) is used for the Contact Sensor state toggle and factory reset. You can change this to a different pin if needed. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterContactSensor.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +User button released. Setting the Contact Sensor to Closed. +User button released. Setting the Contact Sensor to Open. +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle contact sensor state (Open/Closed) +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Automatic Simulation + +The contact sensor state automatically toggles every 20 seconds to simulate a real contact sensor (such as a door or window sensor). The LED will reflect the current state: +- **LED ON**: Contact sensor is Closed +- **LED OFF**: Contact sensor is Open + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a contact sensor in your Home app +7. You can monitor the contact state (Open/Closed) and receive notifications when the state changes + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The contact sensor will appear in your Alexa app +6. You can monitor the contact state and set up routines based on state changes + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. The contact sensor will appear in your Google Home app + +## Code Structure + +The MatterContactSensor example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter Contact Sensor endpoint with initial state (Open), and waits for Matter commissioning. +2. **`loop()`**: Handles button input for toggling contact state and factory reset, and automatically simulates contact state changes every 20 seconds. +3. **`simulatedHWContactSensor()`**: Simulates a hardware contact sensor by toggling the contact state every 20 seconds. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **LED not responding**: Verify pin configurations and connections +- **Contact sensor state not updating**: Check Serial Monitor output to verify state changes are being processed +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterDimmableLight/README.md b/libraries/Matter/examples/MatterDimmableLight/README.md new file mode 100644 index 00000000000..44521385708 --- /dev/null +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -0,0 +1,169 @@ +# Matter Dimmable Light Example + +This example demonstrates how to create a Matter-compatible dimmable light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| --- | ---- | ------ | ----------------- | --- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a dimmable light device +- Support for both WiFi and Thread(*) connectivity +- Brightness control (0-255 levels) +- State persistence using `Preferences` library +- Button control for toggling light and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- LED connected to GPIO pins (or using built-in LED/RGB LED) +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 (supports both RGB LED and regular LED with PWM brightness control) +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in LED): + ```cpp + const uint8_t ledPin = 2; // Set your LED pin here + ``` + +3. **Button pin configuration** (optional): + 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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterDimmableLight.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: ON | brightness: 15 +Matter Node is commissioned and connected to the network. Ready for use. +Light OnOff changed to ON +Light Brightness changed to 128 +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle light on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a dimmable light in your Home app +7. You can control both the on/off state and brightness level (0-100%) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The dimmable light will appear in your Alexa app +6. You can control brightness using voice commands like "Alexa, set light to 50 percent" + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control brightness using voice commands or the slider in the app + +## Code Structure + +The MatterDimmableLight example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter endpoint, restores the last known state (on/off and brightness) from `Preferences`, and registers callbacks for state changes. +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. +3. **Callbacks**: + - `setLightState()`: Controls the physical LED with brightness level (supports both RGB LED and regular LED with PWM). + - `onChangeOnOff()`: Handles on/off state changes. + - `onChangeBrightness()`: Handles brightness level changes (0-255). + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **LED not responding or brightness not working**: Verify pin configurations and connections. For non-RGB LEDs, ensure the pin supports PWM (analogWrite) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterEnhancedColorLight/README.md b/libraries/Matter/examples/MatterEnhancedColorLight/README.md new file mode 100644 index 00000000000..b37adc6a55a --- /dev/null +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -0,0 +1,176 @@ +# Matter Enhanced Color Light Example + +This example demonstrates how to create a Matter-compatible enhanced color light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button. The enhanced color light provides additional features including color temperature control and brightness adjustment. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| --- | ---- | ------ | ----------------- | ------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an enhanced color light device +- Support for both WiFi and Thread(*) connectivity +- RGB color control with HSV color model +- Color temperature control (warm to cool white) +- Brightness control (0-255 levels) +- State persistence using `Preferences` library +- Button control for toggling light and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- RGB LED connected to GPIO pins (or using built-in RGB LED) +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **RGB LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in RGB LED): + ```cpp + const uint8_t ledPin = 2; // Set your RGB LED pin here + ``` + +3. **Button pin configuration** (optional): + 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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterEnhancedColorLight.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: ON | RGB Color: (255,255,255) +Matter Node is commissioned and connected to the network. Ready for use. +Light OnOff changed to ON +Light Color Temperature changed to 370 +Light brightness changed to 128 +Light HSV Color changed to (120,255,255) +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle light on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an enhanced color light in your Home app +7. You can control RGB color, color temperature (warm/cool white), and brightness + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The enhanced color light will appear in your Alexa app +6. You can control color, color temperature, and brightness using voice commands or the app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control color, color temperature, and brightness using voice commands or the app controls + +## Code Structure + +The MatterEnhancedColorLight example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter endpoint, restores the last known state (on/off and HSV color) from `Preferences`, and registers callbacks for state changes. +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. +3. **Callbacks**: + - `setLightState()`: Controls the physical RGB LED with state, HSV color, brightness, and color temperature parameters. + - `onChangeOnOff()`: Handles on/off state changes. + - `onChangeColorHSV()`: Handles HSV color changes (Hue and Saturation). + - `onChangeBrightness()`: Handles brightness level changes (0-255, maps to HSV Value). + - `onChangeColorTemperature()`: Handles color temperature changes (warm to cool white). + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **RGB LED not responding**: Verify pin configurations and connections +- **Color temperature not working**: Verify that the color temperature callback is properly handling HSV conversion +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterEvents/README.md b/libraries/Matter/examples/MatterEvents/README.md new file mode 100644 index 00000000000..061e8ecb1bd --- /dev/null +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -0,0 +1,180 @@ +# Matter Events Example + +This example demonstrates how to monitor and handle Matter events using an ESP32 SoC microcontroller.\ +The application showcases Matter event handling, commissioning, and automatic decommissioning. It provides a comprehensive view of all Matter events that occur during device operation, making it useful for debugging and understanding the Matter protocol behavior. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation with comprehensive event monitoring +- Support for both WiFi and Thread(*) connectivity +- Event callback handler that displays all Matter events to Serial Monitor +- Monitors connectivity changes (WiFi, Thread, Internet, IPv4/IPv6) +- Tracks commissioning lifecycle events +- Monitors fabric management events +- Tracks BLE/CHIPoBLE events +- Automatic decommissioning after 60 seconds for continuous testing +- Matter commissioning via QR code or manual pairing code +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +## Building and Flashing + +1. Open the `MatterEvents.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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 and displays Matter events: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +Starting Matter Commission Test... + +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 +===> Got a Matter Event: CHIPoBLE Advertising Change +===> Got a Matter Event: Commissioning Window Opened +===> Got a Matter Event: Commissioning Session Started +===> Got a Matter Event: Commissioning Complete +===> Got a Matter Event: Operational Network Started +===> Got a Matter Event: Operational Network Enabled +===> Got a Matter Event: Internet Connectivity Change :: IPv4 Connectivity: Established - IP Address: 192.168.1.100 +===> Got a Matter Event: IPv4 Address Assigned +===> Got a Matter Event: Server Ready +===> Got a Matter Event: DNS-SD Initialized +Matter Fabric not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to Wi-Fi. +====> Decommissioning in 60 seconds. <==== +===> Got a Matter Event: Fabric Will Be Removed +===> Got a Matter Event: Fabric Removed +===> Got a Matter Event: Commissioning Window Opened +Matter Node is decommissioned. Commissioning widget shall start over. +``` + +## Using the Device + +### Event Monitoring + +The example continuously monitors and displays Matter events to the Serial Monitor. This includes: + +- **Connectivity Events**: WiFi, Thread, Internet connectivity changes, IP address assignments +- **Commissioning Events**: Commissioning session start/stop, commissioning window open/close, commissioning complete +- **Fabric Events**: Fabric committed, updated, removed +- **BLE Events**: CHIPoBLE connection established/closed, advertising changes +- **Network Events**: Operational network started/enabled, interface IP address changes +- **Service Events**: Service connectivity changes, provisioning changes, DNS-SD events +- **System Events**: Server ready, OTA state changes, time sync changes, fail-safe timer expiration + +### Test Cycle + +The device operates in a continuous test cycle: + +1. **Commissioning Phase**: The device waits for Matter commissioning and displays all related events. +2. **Commissioned Phase**: Once commissioned, the device is connected to the Matter network and ready for use. All network and service events are displayed. +3. **Automatic Decommissioning**: After 60 seconds, the device automatically decommissions itself. +4. **Repeat**: The cycle repeats, allowing you to test the commissioning process multiple times and observe all events. + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device during each test cycle. Monitor the Serial Monitor to see all events that occur during the commissioning process. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. Monitor the Serial Monitor to see all Matter events during commissioning +7. The device will appear as an on/off light in your Home app +8. After 60 seconds, the device will automatically decommission and the cycle will repeat + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. Monitor the Serial Monitor to see all Matter events during commissioning +6. The light will appear in your Alexa app +7. After 60 seconds, the device will automatically decommission and the cycle will repeat + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. Monitor the Serial Monitor to see all Matter events during commissioning +7. After 60 seconds, the device will automatically decommission and the cycle will repeat + +## Code Structure + +The MatterEvents example consists of the following main components: + +1. **`setup()`**: Initializes Serial communication, configures WiFi (if needed), sets up the Matter On/Off Light endpoint, registers the Matter event callback handler, and starts the Matter stack. +2. **`loop()`**: Checks the Matter commissioning state, displays pairing information when not commissioned, waits for commissioning, and then automatically decommissions after 60 seconds to repeat the cycle. +3. **`onMatterEvent()`**: Comprehensive event callback handler that processes and displays all Matter events, including connectivity changes, commissioning events, fabric management, BLE events, and system events. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **No events displayed**: Verify that the event callback is properly registered using `Matter.onEvent()` +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection +- **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 60 seconds to allow continuous testing and event monitoring + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterFan/README.md b/libraries/Matter/examples/MatterFan/README.md new file mode 100644 index 00000000000..b896d69f50a --- /dev/null +++ b/libraries/Matter/examples/MatterFan/README.md @@ -0,0 +1,193 @@ +# Matter Fan Example + +This example demonstrates how to create a Matter-compatible fan device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, manual control using a physical button, and analog input for speed control. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | PWM Pin | Status | +| --- | ---- | ------ | ----------------- | ------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a fan device +- Support for both WiFi and Thread(*) connectivity +- On/Off control +- Speed control (0-100% in steps of 10%) +- Fan modes (OFF, ON, SMART, HIGH) +- Analog input for manual speed adjustment +- PWM output for DC motor control (simulated with RGB LED brightness) +- Button control for toggling fan and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- PWM-capable pin for DC motor control (uses RGB_BUILTIN or pin 2 by default) +- Analog input pin (A0) for speed control via potentiometer or similar +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **DC Motor PWM Pin**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 (for controlling fan speed) +- **Analog Input Pin**: A0 (for reading speed control input, 0-1023 mapped to 10-100% speed) +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **DC Motor PWM pin configuration** (if not using built-in RGB LED): + ```cpp + const uint8_t dcMotorPin = 2; // Set your PWM pin here + ``` + +3. **Analog input pin configuration** (optional): + By default, analog pin A0 is used for speed control. You can change this if needed. + ```cpp + const uint8_t analogPin = A0; // Set your analog pin here + ``` + +4. **Button pin configuration** (optional): + By default, the `BOOT` button (GPIO 0) is used for the Fan On/Off manual control and factory reset. You can change this to a different pin if needed. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterFan.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +Fan State: Mode OFF | 0% speed. +User button released. Setting the Fan ON. +Fan State: Mode ON | 50% speed. +Fan set to SMART mode -- speed percentage will go to 50% +Fan State: Mode SMART | 50% speed. +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle fan on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Analog Speed Control + +The analog input pin (A0) allows manual speed adjustment: + +- Connect a potentiometer or similar analog input to pin A0 +- Analog values (0-1023) are mapped to speed percentages (10-100%) in steps of 10% +- The speed automatically updates when the analog input changes +- Speed changes are synchronized with the Matter controller + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a fan in your Home app +7. You can control on/off, speed (0-100%), and fan modes (OFF, ON, SMART, HIGH) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The fan will appear in your Alexa app +6. You can control speed and modes using voice commands like "Alexa, set fan to 50 percent" or "Alexa, set fan to high" + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control speed and modes using voice commands or the app controls + +## Code Structure + +The MatterFan example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, analog input, PWM output), configures WiFi (if needed), sets up the Matter Fan endpoint with initial state (OFF, 0% speed), and registers callbacks for state changes. +2. **`loop()`**: Checks the Matter commissioning state, handles button input for toggling the fan and factory reset, reads analog input to adjust fan speed, and allows the Matter stack to process events. +3. **Callbacks**: + - `onChangeSpeedPercent()`: Handles speed percent changes (0-100%). Automatically turns fan on/off based on speed. + - `onChangeMode()`: Handles fan mode changes (OFF, ON, SMART, HIGH). Automatically sets speed to 50% when switching from OFF to another mode. + - `onChange()`: Generic callback that controls the DC motor via PWM and reports the current state. + - `fanDCMotorDrive()`: Drives the DC motor (or simulates it with RGB LED brightness) based on fan state and speed. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Fan speed not responding**: Verify PWM pin configuration and connections. For DC motor control, ensure the pin supports PWM output +- **Analog input not working**: Verify analog pin configuration and that the input voltage is within the ESP32's ADC range (0-3.3V typically) +- **Speed changes not synchronized**: The analog input is read continuously, and speed updates only when the value changes by a step (0-9 steps mapped to 10-100%) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterHumiditySensor/README.md b/libraries/Matter/examples/MatterHumiditySensor/README.md new file mode 100644 index 00000000000..789a636095a --- /dev/null +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -0,0 +1,188 @@ +# Matter Humidity Sensor Example + +This example demonstrates how to create a Matter-compatible humidity sensor device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, sensor data reporting to smart home ecosystems, and automatic simulation of humidity readings. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a humidity sensor device +- Support for both WiFi and Thread(*) connectivity +- Humidity measurement reporting (0-100%) +- Automatic simulation of humidity readings (10% to 30% range) +- Periodic sensor updates every 5 seconds +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) +- Optional: Connect a real humidity sensor (DHT11, DHT22, SHT31, etc.) and replace the simulation function + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +3. **Real sensor integration** (optional): + To use a real humidity sensor, replace the `getSimulatedHumidity()` function with your sensor reading code. The function should return a float value representing humidity percentage (0-100%). + +## Building and Flashing + +1. Open the `MatterHumiditySensor.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +Current Humidity is 95.00% +Current Humidity is 10.50% +Current Humidity is 11.00% +Current Humidity is 11.50% +... +Current Humidity is 30.00% +Current Humidity is 10.00% +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Sensor Simulation + +The example includes a simulated humidity sensor that: + +- Starts at 95% humidity (initial value) +- Cycles through 10% to 30% humidity range +- Increases in 0.5% steps +- Updates every 5 seconds +- Resets to 10% when reaching 30% + +To use a real humidity sensor, replace the `getSimulatedHumidity()` function with your sensor library code. For example, with a DHT22: + +```cpp +#include +DHT dht(DHT_PIN, DHT22); + +float getSimulatedHumidity() { + return dht.readHumidity(); +} +``` + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a humidity sensor in your Home app +7. You can monitor the humidity readings and set up automations based on humidity levels + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The humidity sensor will appear in your Alexa app +6. You can monitor humidity readings and create routines based on humidity levels + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can monitor humidity readings and create automations based on humidity levels + +## Code Structure + +The MatterHumiditySensor example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Humidity Sensor endpoint with initial value (95%), and waits for Matter commissioning. +2. **`loop()`**: Displays the current humidity value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. +3. **`getSimulatedHumidity()`**: Simulates a hardware humidity sensor by cycling through values from 10% to 30% in 0.5% steps. Replace this function with your actual sensor reading code. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Humidity readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization +- **Humidity values out of range**: Ensure humidity values are between 0-100%. The Matter protocol stores values as 1/100th of a percent internally +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md new file mode 100644 index 00000000000..7da92e44174 --- /dev/null +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -0,0 +1,204 @@ +# Matter Lambda Single Callback Many Endpoints Example + +This example demonstrates how to create multiple Matter endpoints in a single node using a shared lambda function callback with capture in an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, multiple endpoint management, and efficient callback handling using C++ lambda functions with capture variables. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | GPIO Pins | Status | +| --- | ---- | ------ | ----------------- | --------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation with multiple endpoints in a single node +- Six on/off light endpoints sharing a single callback function +- Lambda function with capture variable for efficient endpoint identification +- Support for both WiFi and Thread(*) connectivity +- Each endpoint has a unique GPIO pin and friendly name +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- Optional: Six LEDs connected to GPIO pins (2, 4, 6, 8, 10, 12) for visual feedback + +## Pin Configuration + +By default, the example uses six GPIO pins for the on/off lights: +- **Light 1 (Room 1)**: GPIO 2 +- **Light 2 (Room 2)**: GPIO 4 +- **Light 3 (Room 3)**: GPIO 6 +- **Light 4 (Room 4)**: GPIO 8 +- **Light 5 (Room 5)**: GPIO 10 +- **Light 6 (Room 6)**: GPIO 12 + +You can modify the `lightPins` array to match your hardware configuration: + +```cpp +uint8_t lightPins[MAX_LIGHT_NUMBER] = {2, 4, 6, 8, 10, 12}; +``` + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **GPIO pin configuration** (optional): + Modify the `lightPins` array to match your hardware: + ```cpp + uint8_t lightPins[MAX_LIGHT_NUMBER] = {2, 4, 6, 8, 10, 12}; + ``` + +3. **Light names** (optional): + Modify the `lightName` array to customize the friendly names: + ```cpp + const char *lightName[MAX_LIGHT_NUMBER] = { + "Room 1", "Room 2", "Room 3", "Room 4", "Room 5", "Room 6", + }; + ``` + +4. **Number of endpoints** (optional): + Change `MAX_LIGHT_NUMBER` to create more or fewer endpoints: + ```cpp + const uint8_t MAX_LIGHT_NUMBER = 6; + ``` + +## Building and Flashing + +1. Open the `MatterLambdaSingleCallbackManyEPs.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +Matter App Control: 'Room 1' (OnOffLight[0], Endpoint 1, GPIO 2) changed to: OFF +Matter App Control: 'Room 1' (OnOffLight[0], Endpoint 1, GPIO 2) changed to: ON +Matter App Control: 'Room 5' (OnOffLight[4], Endpoint 5, GPIO 10) changed to: ON +Matter App Control: 'Room 2' (OnOffLight[1], Endpoint 2, GPIO 4) changed to: ON +``` + +## Using the Device + +### Lambda Function with Capture + +This example demonstrates how to use C++ lambda functions with capture variables to efficiently handle multiple endpoints with a single callback function. The lambda capture `[i]` allows the callback to identify which endpoint triggered the event: + +```cpp +OnOffLight[i].onChangeOnOff([i](bool state) -> bool { + Serial.printf( + "Matter App Control: '%s' (OnOffLight[%d], Endpoint %d, GPIO %d) changed to: %s\r\n", + lightName[i], i, OnOffLight[i].getEndPointId(), lightPins[i], state ? "ON" : "OFF" + ); + return true; +}); +``` + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. After commissioning, you will see six separate on/off light devices in your smart home app, each representing a different room. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as six separate on/off lights in your Home app (Room 1 through Room 6) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The six lights will appear in your Alexa app +6. You can control each room independently + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. The six lights will appear in your Google Home app + +## Code Structure + +The MatterLambdaSingleCallbackManyEPs example consists of the following main components: + +1. **Arrays and Configuration**: + - `OnOffLight[MAX_LIGHT_NUMBER]`: Array of Matter on/off light endpoints + - `lightPins[]`: Array of GPIO pins for each light + - `lightName[]`: Array of friendly names for each light + +2. **`setup()`**: Configures WiFi (if needed), initializes all GPIO pins, initializes all Matter endpoints, registers lambda callbacks with capture variables for each endpoint, and starts the Matter stack. + +3. **`loop()`**: Checks the Matter commissioning state and connection status, displays appropriate messages, and allows the Matter stack to process events. + +4. **Lambda Callback**: + - Uses capture variable `[i]` to identify which endpoint triggered the callback + - Displays detailed information including friendly name, array index, endpoint ID, GPIO pin, and state + - Demonstrates efficient callback handling for multiple endpoints + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Only some endpoints appear**: Some smart home platforms may group or display endpoints differently. Check your app's device list +- **GPIO pins not responding**: Verify pin configurations match your hardware. Ensure pins are not used by other peripherals +- **Failed to commission**: Try erasing the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection +- **Compilation errors with lambda functions**: Ensure you're using a C++11 compatible compiler (ESP32 Arduino Core 2.0+ supports this) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterMinimum/README.md b/libraries/Matter/examples/MatterMinimum/README.md new file mode 100644 index 00000000000..1f6ef0194e6 --- /dev/null +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -0,0 +1,170 @@ +# Matter Minimum Example + +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. + +## Supported Targets + +| SoC | WiFi | 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-C6 | ✅ | ❌ | ✅ | Optional | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Optional | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Minimal Matter protocol implementation for an on/off light device +- Support for both WiFi and Thread(*) connectivity +- Simple on/off control via Matter app +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +- Minimal code footprint - ideal for learning Matter basics +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- Optional: LED connected to GPIO pin (or using built-in LED) for visual feedback +- Optional: User button for factory reset (uses BOOT button by default) + +## Pin Configuration + +- **LED**: Uses `LED_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default (only for factory reset) + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in LED): + ```cpp + const uint8_t ledPin = 2; // Set your LED pin here + ``` + +3. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterMinimum.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi 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. + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +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. + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off light in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup + +## Code Structure + +The MatterMinimum example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (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. + +2. **`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. + +3. **`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. + +## Extending the Example + +This minimal example can be extended with additional features: + +- **State persistence**: Add `Preferences` library to save the last known state +- **Button toggle**: Add button press detection to toggle the light manually +- **Commissioning status check**: Add periodic checking of commissioning state in the loop +- **Multiple endpoints**: Add more Matter endpoints to the same node +- **Enhanced callbacks**: Add more detailed callback functions for better control + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **LED not responding**: Verify pin configurations and connections. The LED will only respond to Matter app commands after commissioning +- **Failed to commission**: Try erasing the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection +- **LED not turning on/off**: Ensure the device is commissioned and you're controlling it via a Matter app. The minimal example only responds to Matter controller commands, not local button presses + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterOccupancySensor/README.md b/libraries/Matter/examples/MatterOccupancySensor/README.md new file mode 100644 index 00000000000..c163ac33e91 --- /dev/null +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -0,0 +1,266 @@ +# Matter Occupancy Sensor Example + +This example demonstrates how to create a Matter-compatible occupancy sensor device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, sensor data reporting to smart home ecosystems, and automatic simulation of occupancy state changes. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an occupancy sensor device +- Support for both WiFi and Thread(*) connectivity +- Occupancy state reporting (Occupied/Unoccupied) +- Automatic simulation of occupancy state changes every 2 minutes +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) +- Optional: PIR (Passive Infrared) motion sensor (e.g., HC-SR501, AM312) for real occupancy detection + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default +- **PIR Sensor** (optional): Connect to any available GPIO pin (e.g., GPIO 4) when using a real sensor + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +3. **PIR sensor pin configuration** (optional, if using a real PIR sensor): + ```cpp + const uint8_t pirPin = 4; // Set your PIR sensor pin here + ``` + See the "PIR Sensor Integration Example" section below for complete integration instructions. + +## Building and Flashing + +1. Open the `MatterOccupancySensor.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +``` + +After commissioning, the occupancy sensor will automatically toggle between occupied and unoccupied states every 2 minutes, and the Matter controller will receive these state updates. + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Sensor Simulation + +The example includes a simulated occupancy sensor that: + +- Starts in the unoccupied state (false) +- Toggles between occupied (true) and unoccupied (false) every 2 minutes +- Updates the Matter attribute automatically + +To use a real occupancy sensor, replace the `simulatedHWOccupancySensor()` function with your sensor library code. + +### PIR Sensor Integration Example + +Here's a complete example for integrating a simple PIR (Passive Infrared) motion sensor: + +#### Hardware Connections + +Connect the PIR sensor to your ESP32: +- **PIR VCC** → ESP32 3.3V or 5V (check your PIR sensor specifications) +- **PIR GND** → ESP32 GND +- **PIR OUT** → ESP32 GPIO pin (e.g., GPIO 4) + +Common PIR sensors (HC-SR501, AM312, etc.) typically have three pins: VCC, GND, and OUT (digital output). + +#### Code Modifications + +1. **Add PIR pin definition** at the top of the sketch (after the button pin definition): + +```cpp +// PIR sensor pin +const uint8_t pirPin = 4; // Change this to your PIR sensor pin +``` + +2. **Initialize PIR pin in setup()** (after button initialization): + +```cpp +void setup() { + // ... existing code ... + pinMode(buttonPin, INPUT_PULLUP); + + // Initialize PIR sensor pin + pinMode(pirPin, INPUT); + + // ... rest of setup code ... +} +``` + +3. **Replace the simulated function** with the real PIR reading function: + +```cpp +bool simulatedHWOccupancySensor() { + // Read PIR sensor digital input + // HIGH = motion detected (occupied), LOW = no motion (unoccupied) + return digitalRead(pirPin) == HIGH; +} +``` + +#### Complete Modified Function Example + +Here's the complete modified function with debouncing for more reliable readings: + +```cpp +bool simulatedHWOccupancySensor() { + // Read PIR sensor with debouncing + static bool lastState = false; + static uint32_t lastChangeTime = 0; + const uint32_t debounceTime = 100; // 100ms debounce + + bool currentState = digitalRead(pirPin) == HIGH; + + // Only update if state has changed and debounce time has passed + if (currentState != lastState) { + if (millis() - lastChangeTime > debounceTime) { + lastState = currentState; + lastChangeTime = millis(); + Serial.printf("Occupancy state changed: %s\r\n", currentState ? "OCCUPIED" : "UNOCCUPIED"); + } + } + + return lastState; +} +``` + +#### Testing the PIR Sensor + +After making these changes: +1. Upload the modified sketch to your ESP32 +2. Open the Serial Monitor at 115200 baud +3. Move in front of the PIR sensor - you should see "OCCUPIED" messages +4. Stay still for a few seconds - you should see "UNOCCUPIED" messages +5. The Matter controller will automatically receive these occupancy state updates + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an occupancy sensor in your Home app +7. You can monitor the occupancy state and set up automations based on occupancy (e.g., turn on lights when occupied) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The occupancy sensor will appear in your Alexa app +6. You can monitor occupancy readings and create routines based on occupancy state changes + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can monitor occupancy readings and create automations based on occupancy state changes + +## Code Structure + +The MatterOccupancySensor example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Occupancy Sensor endpoint with initial state (unoccupied), and waits for Matter commissioning. + +2. **`loop()`**: Handles button input for factory reset, continuously checks the simulated occupancy sensor and updates the Matter attribute, and allows the Matter stack to process events. + +3. **`simulatedHWOccupancySensor()`**: Simulates a hardware occupancy sensor by toggling the occupancy state every 2 minutes. Replace this function with your actual sensor reading code. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Occupancy readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization +- **State not changing**: The simulated sensor toggles every 2 minutes (120000 ms). If you're using a real sensor, ensure it's properly connected and reading correctly +- **PIR sensor not detecting motion**: + - Verify PIR sensor wiring (VCC, GND, OUT connections) + - Check if PIR sensor requires 5V or 3.3V power (some PIR sensors need 5V) + - Allow 30-60 seconds for PIR sensor to stabilize after power-on + - Adjust PIR sensor sensitivity and time delay potentiometers (if available on your sensor) + - Ensure the PIR sensor has a clear view of the detection area + - Test the PIR sensor directly by reading the GPIO pin value in Serial Monitor +- **PIR sensor false triggers**: Add debouncing to the sensor reading function (see the "Complete Modified Function Example" above) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterOnIdentify/README.md b/libraries/Matter/examples/MatterOnIdentify/README.md new file mode 100644 index 00000000000..84696ed63d2 --- /dev/null +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -0,0 +1,212 @@ +# Matter On Identify Example + +This example demonstrates how to implement the Matter Identify cluster callback for an on/off light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and the Identify feature that makes the LED blink when the device is identified from a Matter app. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| --- | ---- | ------ | ----------------- | --- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an on/off light device +- Support for both WiFi and Thread(*) connectivity +- On Identify callback implementation - LED blinks when device is identified +- Visual identification feedback (red blinking for RGB LED, toggling for regular LED) +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- LED connected to GPIO pin (or using built-in LED) for visual feedback +- Optional: RGB LED for red blinking identification (uses RGB_BUILTIN if available) +- User button for factory reset (uses BOOT button by default) + +## Pin Configuration + +- **LED**: Uses `LED_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in LED): + ```cpp + const uint8_t ledPin = 2; // Set your LED pin here + ``` + +3. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterOnIdentify.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi 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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +``` + +When you trigger the Identify command from a Matter app, you should see: +``` +Identify Cluster is Active +Identify Cluster is Inactive +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Identify Feature + +The Identify feature allows you to visually identify a specific device from your Matter app. When you trigger the Identify command: + +1. **For RGB LED (RGB_BUILTIN)**: The LED will blink in red color +2. **For regular LED**: The LED will toggle on/off + +The blinking continues while the Identify cluster is active (typically 3-15 seconds depending on the app). When the Identify period ends, the LED automatically returns to its previous state (on or off). + +### How to Trigger Identify + +#### Apple Home + +1. Open the Home app on your iOS device +2. Find your device in the device list +3. Long press on the device +4. Tap "Identify" or look for the identify option in device settings +5. The LED will start blinking + +#### Amazon Alexa + +1. Open the Alexa app +2. Navigate to your device +3. Look for "Identify" or "Find Device" option in device settings +4. The LED will start blinking + +#### Google Home + +1. Open the Google Home app +2. Select your device +3. Look for "Identify" or "Find Device" option +4. The LED will start blinking + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off light in your Home app +7. Use the Identify feature to visually locate the device + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app +6. Use the Identify feature to visually locate the device + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. Use the Identify feature to visually locate the device + +## Code Structure + +The MatterOnIdentify example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), initializes the Matter on/off light endpoint, registers the on/off callback and the Identify callback, and starts the Matter stack. + +2. **`loop()`**: Handles the Identify blinking logic (if identify flag is active, blinks the LED every 500ms), handles button input for factory reset, and allows the Matter stack to process events. + +3. **Callbacks**: + - `onOffLightCallback()`: Controls the physical LED based on on/off state from Matter controller. + - `onIdentifyLightCallback()`: Handles the Identify cluster activation/deactivation. When active, sets the identify flag to start blinking. When inactive, stops blinking and restores the original light state. + +4. **Identify Blinking Logic**: + - For RGB LEDs: Blinks in red color (brightness 32) when identify is active + - For regular LEDs: Toggles on/off when identify is active + - Blinking rate: Every 500ms (determined by the delay in loop) + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **LED not responding**: Verify pin configurations and connections +- **Identify feature not working**: Ensure the device is commissioned and you're using a Matter app that supports the Identify cluster. Some apps may not have a visible Identify button +- **LED not blinking during identify**: Check Serial Monitor for "Identify Cluster is Active" message. If you don't see it, the Identify command may not be reaching the device +- **LED state not restored after identify**: The code uses a double-toggle to restore state. If this doesn't work, ensure the light state is properly tracked +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterOnOffLight/README.md b/libraries/Matter/examples/MatterOnOffLight/README.md new file mode 100644 index 00000000000..e7b6fb4f3ba --- /dev/null +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -0,0 +1,180 @@ +# Matter On/Off Light Example + +This example demonstrates how to create a Matter-compatible on/off light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button with state persistence. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| --- | ---- | ------ | ----------------- | --- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an on/off light device +- Support for both WiFi and Thread(*) connectivity +- Simple on/off control +- State persistence using `Preferences` library +- Button control for toggling light and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- LED connected to GPIO pin (or using built-in LED) for visual feedback +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **LED**: Uses `LED_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in LED): + ```cpp + const uint8_t ledPin = 2; // Set your LED pin here + ``` + +3. **Button pin configuration** (optional): + By default, the `BOOT` button (GPIO 0) is used for the Light On/Off manual control and factory reset. You can change this to a different pin if needed. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterOnOffLight.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: ON +Matter Node is commissioned and connected to the network. Ready for use. +User Callback :: New Light State = ON +User Callback :: New Light State = OFF +User button released. Toggling Light! +User Callback :: New Light State = ON +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle light on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### State Persistence + +The device saves the last known on/off state using the `Preferences` library. After a power cycle or restart: + +- The device will restore to the last saved state (ON or OFF) +- The Matter controller will be notified of the restored state +- The LED will reflect the restored state + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off light in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app +6. You can control it using voice commands like "Alexa, turn on the light" or "Alexa, turn off the light" + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control it using voice commands or the app controls + +## Code Structure + +The MatterOnOffLight example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), initializes `Preferences` library, sets up the Matter endpoint with the last saved state (defaults to ON if not previously saved), registers the callback function, and starts the Matter stack. + +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. + +3. **Callbacks**: + - `setLightOnOff()`: Controls the physical LED based on the on/off state, saves the state to `Preferences` for persistence, and prints the state change to Serial Monitor. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **LED not responding**: Verify pin configurations and connections +- **State not persisting**: Check that the `Preferences` library is properly initialized and that flash memory is not corrupted +- **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 erase_flash` +- **Button not toggling light**: Ensure the button is properly connected and the debounce time is appropriate. Check Serial Monitor for "User button released" messages +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterOnOffPlugin/README.md b/libraries/Matter/examples/MatterOnOffPlugin/README.md new file mode 100644 index 00000000000..b5217301c4b --- /dev/null +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -0,0 +1,197 @@ +# Matter On/Off Plugin Example + +This example demonstrates how to create a Matter-compatible on/off plugin unit (power relay) device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and state persistence for power control applications. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Relay/LED | Status | +| --- | ---- | ------ | ----------------- | --------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for an on/off plugin unit (power relay) device +- Support for both WiFi and Thread(*) connectivity +- Simple on/off control for power management +- State persistence using `Preferences` library +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- Power relay module or LED for visualization (for testing, uses built-in LED) +- User button for factory reset (uses BOOT button by default) + +## Pin Configuration + +- **Power Relay/Plugin Pin**: Uses `LED_BUILTIN` if defined (for testing), otherwise pin 2. For production use, connect this to your relay control pin. +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **Power relay pin configuration** (if not using built-in LED): + For production use, change this to the GPIO pin connected to your relay control module: + ```cpp + const uint8_t onoffPin = 2; // Set your relay control pin here + ``` + +3. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterOnOffPlugin.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: OFF +Matter Node is commissioned and connected to the network. Ready for use. +User Callback :: New Plugin State = ON +User Callback :: New Plugin State = OFF +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +Note: This example does not include button toggle functionality. The plugin is controlled exclusively via Matter app commands. + +### State Persistence + +The device saves the last known on/off state using the `Preferences` library. After a power cycle or restart: + +- The device will restore to the last saved state (ON or OFF) +- Default state is OFF if no previous state was saved +- The Matter controller will be notified of the restored state +- The relay/LED will reflect the restored state + +### Power Relay Integration + +For production use with a power relay module: + +1. **Connect the relay module** to your ESP32: + - Relay VCC → ESP32 3.3V or 5V (check relay module specifications) + - Relay GND → ESP32 GND + - Relay IN → ESP32 GPIO pin (configured as `onoffPin`) + +2. **Update the pin configuration** in the sketch: + ```cpp + const uint8_t onoffPin = 2; // Your relay control pin + ``` + +3. **Test the relay** by controlling it via Matter app - the relay should turn on/off accordingly + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off switch/outlet in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The plugin will appear in your Alexa app +6. You can control it using voice commands like "Alexa, turn on the plugin" or "Alexa, turn off the plugin" + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control it using voice commands or the app controls + +## Code Structure + +The MatterOnOffPlugin example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, relay/LED pin), configures WiFi (if needed), initializes `Preferences` library, sets up the Matter plugin endpoint with the last saved state (defaults to OFF if not previously saved), registers the callback function, and starts the Matter stack. + +2. **`loop()`**: Checks the Matter commissioning state, handles button input for factory reset, and allows the Matter stack to process events. + +3. **Callbacks**: + - `setPluginOnOff()`: Controls the physical relay/LED based on the on/off state, saves the state to `Preferences` for persistence, and prints the state change to Serial Monitor. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Relay/LED not responding**: Verify pin configurations and connections. For relay modules, ensure proper power supply and wiring +- **State not persisting**: Check that the `Preferences` library is properly initialized and that flash memory is not corrupted +- **Relay not switching**: For relay modules, verify the control signal voltage levels match your relay module requirements (some relays need 5V, others work with 3.3V) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterPressureSensor/README.md b/libraries/Matter/examples/MatterPressureSensor/README.md new file mode 100644 index 00000000000..7bf5b1418aa --- /dev/null +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -0,0 +1,190 @@ +# Matter Pressure Sensor Example + +This example demonstrates how to create a Matter-compatible pressure sensor device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, sensor data reporting to smart home ecosystems, and automatic simulation of pressure readings. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a pressure sensor device +- Support for both WiFi and Thread(*) connectivity +- Pressure measurement reporting in hectopascals (hPa) +- Automatic simulation of pressure readings (950-1100 hPa range) +- Periodic sensor updates every 5 seconds +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) +- Optional: Connect a real pressure sensor (BMP280, BME280, BMP388, etc.) and replace the simulation function + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +3. **Real sensor integration** (optional): + To use a real pressure sensor, replace the `getSimulatedPressure()` function with your sensor reading code. The function should return a float value representing pressure in hectopascals (hPa). + +## Building and Flashing + +1. Open the `MatterPressureSensor.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +Current Pressure is 900.00hPa +Current Pressure is 950.00hPa +Current Pressure is 960.00hPa +... +Current Pressure is 1100.00hPa +Current Pressure is 950.00hPa +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Sensor Simulation + +The example includes a simulated pressure sensor that: + +- Starts at 900 hPa (initial value) +- Cycles through 950 to 1100 hPa range +- Increases in 10 hPa steps +- Updates every 5 seconds +- Resets to 950 hPa when reaching 1100 hPa + +To use a real pressure sensor, replace the `getSimulatedPressure()` function with your sensor library code. For example, with a BMP280: + +```cpp +#include +Adafruit_BMP280 bmp; + +float getSimulatedPressure() { + return bmp.readPressure() / 100.0; // Convert Pa to hPa +} +``` + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a pressure sensor in your Home app +7. You can monitor the pressure readings and set up automations based on pressure levels (e.g., weather monitoring) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The pressure sensor will appear in your Alexa app +6. You can monitor pressure readings and create routines based on pressure changes + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can monitor pressure readings and create automations based on pressure changes + +## Code Structure + +The MatterPressureSensor example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Pressure Sensor endpoint with initial value (900 hPa), and waits for Matter commissioning. + +2. **`loop()`**: Displays the current pressure value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. + +3. **`getSimulatedPressure()`**: Simulates a hardware pressure sensor by cycling through values from 950 to 1100 hPa in 10 hPa steps. Replace this function with your actual sensor reading code. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Pressure readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization +- **Pressure values out of range**: Ensure pressure values are in hectopascals (hPa). The Matter protocol stores values as uint16_t internally. Typical atmospheric pressure ranges from 950-1050 hPa at sea level +- **State not changing**: The simulated sensor increases by 10 hPa every 5 seconds. If you're using a real sensor, ensure it's properly connected and reading correctly +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterSmartButon/README.md b/libraries/Matter/examples/MatterSmartButon/README.md new file mode 100644 index 00000000000..e0368605803 --- /dev/null +++ b/libraries/Matter/examples/MatterSmartButon/README.md @@ -0,0 +1,174 @@ +# Matter Smart Button Example + +This example demonstrates how to create a Matter-compatible smart button (generic switch) device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, sending button click events to smart home ecosystems, and triggering automations based on button presses. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a smart button (generic switch) device +- Support for both WiFi and Thread(*) connectivity +- Button click event reporting to Matter controller +- Button control for triggering events and factory reset +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +- Automation trigger support - button presses can trigger actions in smart home apps +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for triggering events (uses BOOT button by default) + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **Button pin configuration** (optional): + By default, the `BOOT` button (GPIO 0) is used for triggering click events and factory reset. You can change this to a different pin if needed. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterSmartButon.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +User button released. Sending Click to the Matter Controller! +User button released. Sending Click to the Matter Controller! +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides the following functionality: + +- **Short press and release**: Sends a click event to the Matter controller (triggers automations) +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Button Click Events + +When you press and release the button: + +1. The button press is detected and debounced +2. A click event is sent to the Matter controller via the Generic Switch cluster +3. The Matter controller receives the event and can trigger programmed automations +4. The event is logged to Serial Monitor for debugging + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. After commissioning, you can set up automations that trigger when the button is pressed. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a switch/button in your Home app +7. Set up automations: Go to Automation tab > Create Automation > When an accessory is controlled > Select the smart button > Choose the action (e.g., turn on lights, activate scene) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The smart button will appear in your Alexa app +6. Create routines: Tap More > Routines > Create Routine > When this happens > Select the smart button > Add action (e.g., turn on lights, control other devices) + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. Create automations: Tap Automations > Create Automation > When button is pressed > Choose action + +## Code Structure + +The MatterSmartButton example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), initializes the Matter Generic Switch endpoint, and starts the Matter stack. + +2. **`loop()`**: Checks the Matter commissioning state, handles button input for sending click events and factory reset, and allows the Matter stack to process events. + +3. **Button Event Handling**: + - Detects button press and release with debouncing (250ms) + - Sends click event to Matter controller using `SmartButton.click()` when button is released + - Handles long press (>5 seconds) for factory reset + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Button clicks not registering**: Check Serial Monitor for "User button released" messages. Verify button wiring and that debounce time is appropriate +- **Automations not triggering**: Ensure the device is commissioned and that automations are properly configured in your Matter app. The button sends events, but automations must be set up in the app +- **Button not responding**: Verify button pin configuration and connections. Check that the button is properly connected with pull-up resistor (INPUT_PULLUP mode) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection +- **Multiple clicks registered for single press**: Increase the debounce time in the code if needed + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterTemperatureLight/README.md b/libraries/Matter/examples/MatterTemperatureLight/README.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/libraries/Matter/examples/MatterTemperatureSensor/README.md b/libraries/Matter/examples/MatterTemperatureSensor/README.md new file mode 100644 index 00000000000..210fde16d30 --- /dev/null +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -0,0 +1,205 @@ +# Matter Temperature Sensor Example + +This example demonstrates how to create a Matter-compatible temperature sensor device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, sensor data reporting to smart home ecosystems, and automatic simulation of temperature readings. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a temperature sensor device +- Support for both WiFi and Thread(*) connectivity +- Temperature measurement reporting in Celsius +- Automatic simulation of temperature readings (-10°C to 10°C range) +- Periodic sensor updates every 5 seconds +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) +- Optional: Connect a real temperature sensor (DS18B20, DHT22, BMP280, BME280, etc.) and replace the simulation function + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +3. **Real sensor integration** (optional): + To use a real temperature sensor, replace the `getSimulatedTemperature()` function with your sensor reading code. The function should return a float value representing temperature in Celsius. + +## Building and Flashing + +1. Open the `MatterTemperatureSensor.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. +Current Temperature is -25.00C +Current Temperature is -10.00C +Current Temperature is -9.50C +... +Current Temperature is 10.00C +Current Temperature is -10.00C +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Sensor Simulation + +The example includes a simulated temperature sensor that: + +- Starts at -25°C (initial value) +- Cycles through -10°C to 10°C range +- Increases in 0.5°C steps +- Updates every 5 seconds +- Resets to -10°C when reaching 10°C + +To use a real temperature sensor, replace the `getSimulatedTemperature()` function with your sensor library code. For example, with a DS18B20: + +```cpp +#include +#include + +OneWire oneWire(4); // GPIO pin connected to DS18B20 +DallasTemperature sensors(&oneWire); + +float getSimulatedTemperature() { + sensors.requestTemperatures(); + return sensors.getTempCByIndex(0); +} +``` + +Or with a DHT22: + +```cpp +#include +DHT dht(DHT_PIN, DHT22); + +float getSimulatedTemperature() { + return dht.readTemperature(); +} +``` + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a temperature sensor in your Home app +7. You can monitor the temperature readings and set up automations based on temperature levels (e.g., turn on AC when temperature exceeds threshold) + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The temperature sensor will appear in your Alexa app +6. You can monitor temperature readings and create routines based on temperature changes + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can monitor temperature readings and create automations based on temperature changes + +## Code Structure + +The MatterTemperatureSensor example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Temperature Sensor endpoint with initial value (-25°C), and waits for Matter commissioning. + +2. **`loop()`**: Displays the current temperature value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. + +3. **`getSimulatedTemperature()`**: Simulates a hardware temperature sensor by cycling through values from -10°C to 10°C in 0.5°C steps. Replace this function with your actual sensor reading code. + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Temperature readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization +- **Temperature values out of range**: Ensure temperature values are in Celsius. The Matter protocol stores values as int16_t internally (1/100th of a degree Celsius), so -273.15°C (absolute zero) to 327.67°C is the valid range +- **State not changing**: The simulated sensor increases by 0.5°C every 5 seconds. If you're using a real sensor, ensure it's properly connected and reading correctly +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterThermostat/README.md b/libraries/Matter/examples/MatterThermostat/README.md new file mode 100644 index 00000000000..c1f45b1961a --- /dev/null +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -0,0 +1,229 @@ +# Matter Thermostat Example + +This example demonstrates how to create a Matter-compatible thermostat device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, thermostat control via smart home ecosystems, temperature setpoint management, and simulated heating/cooling systems with automatic temperature regulation. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. + +## Features + +- Matter protocol implementation for a thermostat device +- Support for both WiFi and Thread(*) connectivity +- Multiple thermostat modes: OFF, HEAT, COOL, AUTO +- Heating and cooling setpoint control +- Automatic temperature regulation in AUTO mode +- Simulated heating/cooling systems with temperature changes +- Serial input for manual temperature setting +- Button control for factory reset (decommission) +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- User button for factory reset (uses BOOT button by default) +- Optional: Connect a real temperature sensor and replace the simulation function + +## Pin Configuration + +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +3. **Real sensor integration** (optional): + To use a real temperature sensor, replace the `getSimulatedTemperature()` function with your sensor reading code. The function should return a float value representing temperature in Celsius. + +## Building and Flashing + +1. Open the `MatterThermostat.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Matter Node is commissioned and connected to the network. Ready for use. + +Initial Setpoints are 23.0C to 20.0C with a minimum 2.5C difference +Auto mode is ON. Initial Temperature of 12.5C +Local Temperature Sensor will be simulated every 10 seconds and changed by a simulated heater and cooler to move in between setpoints. +Current Local Temperature is 12.5C + Thermostat Mode: AUTO >>> Heater is ON -- Cooler is OFF +Current Local Temperature is 13.0C + Thermostat Mode: AUTO >>> Heater is ON -- Cooler is OFF +... +Current Local Temperature is 20.0C + Thermostat Mode: AUTO >>> Heater is OFF -- Cooler is OFF +Current Local Temperature is 23.0C + Thermostat Mode: AUTO >>> Heater is OFF -- Cooler is ON +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides factory reset functionality: + +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Serial Input + +You can manually set the temperature by typing a value in the Serial Monitor: + +1. Open Serial Monitor at 115200 baud +2. Type a temperature value between -50°C and 50°C +3. Press Enter +4. The thermostat will update the local temperature reading + +Example: +``` +15.5 +New Temperature is 15.5C +``` + +### Thermostat Modes + +The thermostat supports four operating modes: + +- **OFF**: Heating and cooling systems are turned off +- **HEAT**: Only heating system is active. Turns off when temperature exceeds heating setpoint +- **COOL**: Only cooling system is active. Turns off when temperature falls below cooling setpoint +- **AUTO**: Automatically switches between heating and cooling to maintain temperature between setpoints + +### Setpoints + +- **Heating Setpoint**: Target temperature for heating (default: 23.0°C) +- **Cooling Setpoint**: Target temperature for cooling (default: 20.0°C) +- **Deadband**: Minimum difference between heating and cooling setpoints (2.5°C required in AUTO mode) + +### Temperature Simulation + +The example includes a simulated heating/cooling system: + +- **Heating**: Temperature increases by 0.5°C every 10 seconds when heating is active +- **Cooling**: Temperature decreases by 0.5°C every 10 seconds when cooling is active +- **No heating/cooling**: Temperature remains stable + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a thermostat in your Home app +7. You can control the mode (OFF, HEAT, COOL, AUTO) and adjust heating/cooling setpoints +8. Monitor the current temperature and set up automations based on temperature + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The thermostat will appear in your Alexa app +6. You can control the mode and setpoints using voice commands or the app +7. Create routines based on temperature changes + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can control the mode and setpoints using voice commands or the app +7. Create automations based on temperature + +## Code Structure + +The MatterThermostat example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Thermostat endpoint with cooling/heating sequence of operation and AUTO mode enabled, sets initial setpoints (heating: 23.0°C, cooling: 20.0°C) and initial temperature (12.5°C), and waits for Matter commissioning. + +2. **`loop()`**: Reads serial input for manual temperature setting, simulates heating/cooling systems and temperature changes every 10 seconds, controls heating/cooling based on thermostat mode and setpoints, handles button input for factory reset, and allows the Matter stack to process events. + +3. **`getSimulatedTemperature()`**: Simulates temperature changes based on heating/cooling state. Temperature increases when heating is active, decreases when cooling is active. Replace this function with your actual sensor reading code. + +4. **`readSerialForNewTemperature()`**: Reads temperature values from Serial Monitor input, validates the range (-50°C to 50°C), and updates the thermostat's local temperature. + +5. **Thermostat Control Logic**: + - **OFF mode**: Both heating and cooling are disabled + - **AUTO mode**: Automatically switches between heating and cooling to maintain temperature between setpoints + - **HEAT mode**: Activates heating until temperature exceeds heating setpoint + - **COOL mode**: Activates cooling until temperature falls below cooling setpoint + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Temperature not updating**: Check that the simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization +- **Heating/cooling not responding**: Verify that the thermostat mode is set correctly and that setpoints are properly configured +- **Setpoints not working**: Ensure cooling setpoint is at least 2.5°C lower than heating setpoint in AUTO mode +- **Serial input not working**: Make sure Serial Monitor is set to 115200 baud and "No line ending" or "Newline" is selected +- **Invalid temperature values**: Temperature must be between -50°C and 50°C. The Matter protocol stores values as int16_t internally (1/100th of a degree Celsius) +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + From 0757e8a533dbd2e68babd43e77aa9e029ef55d9b Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Wed, 5 Nov 2025 05:29:30 -0300 Subject: [PATCH 02/10] fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- libraries/Matter/examples/MatterColorLight/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 75e9de65b9b..02e2922a7df 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -17,7 +17,7 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: - **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. -- **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. +- **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. ## Features From b8f0b5eca62ddf267e6fc38367d30ce6f254a0ce Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Wed, 5 Nov 2025 05:31:46 -0300 Subject: [PATCH 03/10] fix(matter): missing information Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- libraries/Matter/examples/MatterColorLight/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 02e2922a7df..70cd000b770 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -50,7 +50,7 @@ The application showcases Matter commissioning, device control via smart home ec 3. Install required libraries: - `Matter` - `Preferences` - - `WiFi` + - `WiFi` (only for ESP32 and ESP32-S2) ### Configuration From 3d18b8606d5f49aa62bb2dc5118333b1c58714d1 Mon Sep 17 00:00:00 2001 From: SuGlider Date: Wed, 5 Nov 2025 06:21:24 -0300 Subject: [PATCH 04/10] feat(matter): adds ESP32-C5 to supported list and fixes typos --- .../examples/MatterColorLight/README.md | 6 +- .../MatterCommissionTest.ino | 2 +- .../examples/MatterCommissionTest/README.md | 4 +- .../examples/MatterComposedLights/README.md | 2 + .../examples/MatterContactSensor/README.md | 2 + .../examples/MatterDimmableLight/README.md | 2 + .../MatterEnhancedColorLight/README.md | 2 + .../Matter/examples/MatterEvents/README.md | 2 + libraries/Matter/examples/MatterFan/README.md | 2 + .../examples/MatterHumiditySensor/README.md | 2 + .../README.md | 2 + .../Matter/examples/MatterMinimum/README.md | 2 + .../MatterNetworkCommissioning.ino | 370 ++++++++++++++++++ .../MatterNetworkCommissioning/README.md | 215 ++++++++++ .../examples/MatterOccupancySensor/README.md | 2 + .../examples/MatterOnIdentify/README.md | 2 + .../examples/MatterOnOffLight/README.md | 2 + .../examples/MatterOnOffPlugin/README.md | 2 + .../examples/MatterPressureSensor/README.md | 2 + .../MatterSmartButon.ino | 0 .../README.md | 4 +- .../ci.yml | 0 .../examples/MatterTemperatureLight/README.md | 208 ++++++++++ .../MatterTemperatureSensor/README.md | 2 + .../examples/MatterThermostat/README.md | 2 + .../examples/MatterThreadLight/README.md | 242 ++++++++++++ 26 files changed, 1078 insertions(+), 5 deletions(-) create mode 100644 libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino create mode 100644 libraries/Matter/examples/MatterNetworkCommissioning/README.md rename libraries/Matter/examples/{MatterSmartButon => MatterSmartButton}/MatterSmartButon.ino (100%) rename libraries/Matter/examples/{MatterSmartButon => MatterSmartButton}/README.md (95%) rename libraries/Matter/examples/{MatterSmartButon => MatterSmartButton}/ci.yml (100%) create mode 100644 libraries/Matter/examples/MatterThreadLight/README.md diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 70cd000b770..2a860a58c11 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features @@ -47,7 +49,7 @@ The application showcases Matter commissioning, device control via smart home ec 1. Install the Arduino IDE (2.0 or newer recommended) 2. Install ESP32 Arduino Core with Matter support -3. Install required libraries: +3. ESP32 Arduino libraries: - `Matter` - `Preferences` - `WiFi` (only for ESP32 and ESP32-S2) @@ -81,7 +83,7 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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: ``` Connecting to your-wifi-ssid diff --git a/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino b/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino index aa593758548..4410d96dba1 100644 --- a/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino +++ b/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino @@ -77,5 +77,5 @@ void loop() { Serial.println("====> Decommissioning in 30 seconds. <===="); delay(30000); Matter.decommission(); - Serial.println("Matter Node is decommissioned. Commsssioning widget shall start over."); + Serial.println("Matter Node is decommissioned. Commisssioning widget shall start over."); } diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md index ba438fdf0b7..4fc2c70287a 100644 --- a/libraries/Matter/examples/MatterCommissionTest/README.md +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device connection to smart home | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device connection to smart home - **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. - **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. +- **ESP32-C5** 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. ## Features @@ -80,7 +82,7 @@ Matter Fabric not commissioned yet. Waiting for commissioning. ... Matter Node is commissioned and connected to the network. ====> Decommissioning in 30 seconds. <==== -Matter Node is decommissioned. Commsssioning widget shall start over. +Matter Node is decommissioned. Commisssioning widget shall start over. Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. diff --git a/libraries/Matter/examples/MatterComposedLights/README.md b/libraries/Matter/examples/MatterComposedLights/README.md index 751b26572b2..d1a6d218307 100644 --- a/libraries/Matter/examples/MatterComposedLights/README.md +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, a single Matter node containing | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, a single Matter node containing - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterContactSensor/README.md b/libraries/Matter/examples/MatterContactSensor/README.md index 3047bcd2e4f..b17bd95e63c 100644 --- a/libraries/Matter/examples/MatterContactSensor/README.md +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterDimmableLight/README.md b/libraries/Matter/examples/MatterDimmableLight/README.md index 44521385708..a4511d62b37 100644 --- a/libraries/Matter/examples/MatterDimmableLight/README.md +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterEnhancedColorLight/README.md b/libraries/Matter/examples/MatterEnhancedColorLight/README.md index b37adc6a55a..557eac162d4 100644 --- a/libraries/Matter/examples/MatterEnhancedColorLight/README.md +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterEvents/README.md b/libraries/Matter/examples/MatterEvents/README.md index 061e8ecb1bd..b4aeaac6854 100644 --- a/libraries/Matter/examples/MatterEvents/README.md +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -11,6 +11,7 @@ The application showcases Matter event handling, commissioning, and automatic de | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter event handling, commissioning, and automatic de - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterFan/README.md b/libraries/Matter/examples/MatterFan/README.md index b896d69f50a..c431d8ecb01 100644 --- a/libraries/Matter/examples/MatterFan/README.md +++ b/libraries/Matter/examples/MatterFan/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterHumiditySensor/README.md b/libraries/Matter/examples/MatterHumiditySensor/README.md index 789a636095a..865339121b3 100644 --- a/libraries/Matter/examples/MatterHumiditySensor/README.md +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md index 7da92e44174..21013d89efc 100644 --- a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, multiple endpoint management, an | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, multiple endpoint management, an - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterMinimum/README.md b/libraries/Matter/examples/MatterMinimum/README.md index 1f6ef0194e6..e1e74905363 100644 --- a/libraries/Matter/examples/MatterMinimum/README.md +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -11,6 +11,7 @@ The application showcases the minimal implementation for Matter commissioning an | ESP32-S2 | ✅ | ❌ | ❌ | Optional | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Optional | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Optional | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Optional | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Optional | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Optional | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases the minimal implementation for Matter commissioning an - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino b/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino new file mode 100644 index 00000000000..546064c4ed5 --- /dev/null +++ b/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino @@ -0,0 +1,370 @@ +/* + Matter Network Commissioning Control Example + + This example demonstrates how to control which networks (WiFi/Thread) are available + for commissioning when using CHIPoBLE (Chip over Bluetooth Low Energy). + + The sketch shows how to: + 1. Enable/disable WiFi network commissioning + 2. Enable/disable Thread network commissioning + 3. Set specific network commissioning modes + 4. Monitor commissioning events + + Instructions: + 1. Use a Matter commissioner app (like CHIPTool) to start commissioning + 2. Connect via BLE and commission the device to your desired network + 3. Use the serial commands to control which networks are available + + Serial Commands: + - 'w' : Toggle WiFi commissioning + - 't' : Toggle Thread commissioning + - 'r' : Reset to factory defaults + - 's' : Show current network status + - '1' : WiFi only mode + - '2' : Thread only mode + - '3' : Both networks mode + - '0' : No networks mode + + Author: ESP32 Arduino Team + Date: 2024 +*/ + +#include +#include + +// Matter Light Endpoint +MatterOnOffLight OnOffLight; + +// Network commissioning states +bool wifiCommissioningEnabled = true; +bool threadCommissioningEnabled = false; + +void setup() { + Serial.begin(115200); + + // Register Matter event callback + Matter.onEvent(onMatterEvent); + + // Initialize Matter endpoint + OnOffLight.begin(); + + // Set initial network commissioning mode BEFORE Matter.begin() + // Start with WiFi only by default + if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { + Serial.println("Initial network commissioning mode set successfully"); + } else { + Serial.println("Warning: Failed to set initial network commissioning mode"); + } + + // Start Matter stack + Matter.begin(); + + // Synchronize our state variables with actual API state + syncNetworkStates(); + + Serial.println("Matter Network Commissioning Control Example"); + Serial.println("==========================================="); + printNetworkStatus(); + printCommands(); +} + +void loop() { + // Handle serial commands + if (Serial.available()) { + char cmd = Serial.read(); + handleSerialCommand(cmd); + } + + // Update Matter + delay(100); +} + +void handleSerialCommand(char cmd) { + switch (cmd) { + case 'w': + case 'W': + toggleWiFiCommissioning(); + break; + + case 't': + case 'T': + toggleThreadCommissioning(); + break; + + case 'r': + case 'R': + resetToFactory(); + break; + + case 's': + case 'S': + printNetworkStatus(); + break; + + case '1': + setWiFiOnlyMode(); + break; + + case '2': + setThreadOnlyMode(); + break; + + case '3': + setBothNetworksMode(); + break; + + case '0': + setNoNetworksMode(); + break; + + case 'h': + case 'H': + case '?': + printCommands(); + break; + + default: + if (cmd != '\n' && cmd != '\r') { + Serial.println("Unknown command. Type 'h' for help."); + } + break; + } +} + +void toggleWiFiCommissioning() { +#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION + wifiCommissioningEnabled = !wifiCommissioningEnabled; + + if (wifiCommissioningEnabled) { + if (Matter.enableWiFiNetworkCommissioning()) { + Serial.println("✓ WiFi commissioning enabled"); + } else { + Serial.println("✗ Failed to enable WiFi commissioning"); + wifiCommissioningEnabled = false; // Revert state + } + } else { + if (Matter.disableWiFiNetworkCommissioning()) { + Serial.println("✓ WiFi commissioning disabled"); + } else { + Serial.println("✗ Failed to disable WiFi commissioning"); + wifiCommissioningEnabled = true; // Revert state + } + } + + // Verify actual state matches our intended state + bool actualState = Matter.isWiFiNetworkCommissioningEnabled(); + if (actualState != wifiCommissioningEnabled) { + Serial.printf("⚠️ Warning: State mismatch - intended: %s, actual: %s\n", + wifiCommissioningEnabled ? "enabled" : "disabled", + actualState ? "enabled" : "disabled"); + wifiCommissioningEnabled = actualState; // Sync to actual state + } +#else + Serial.println("WiFi commissioning not supported (not compiled in)"); +#endif + printNetworkStatus(); +} + +void toggleThreadCommissioning() { +#if CHIP_DEVICE_CONFIG_ENABLE_THREAD + threadCommissioningEnabled = !threadCommissioningEnabled; + + if (threadCommissioningEnabled) { + if (Matter.enableThreadNetworkCommissioning()) { + Serial.println("✓ Thread commissioning enabled"); + } else { + Serial.println("✗ Failed to enable Thread commissioning"); + threadCommissioningEnabled = false; // Revert state + } + } else { + if (Matter.disableThreadNetworkCommissioning()) { + Serial.println("✓ Thread commissioning disabled"); + } else { + Serial.println("✗ Failed to disable Thread commissioning"); + threadCommissioningEnabled = true; // Revert state + } + } + + // Verify actual state matches our intended state + bool actualState = Matter.isThreadNetworkCommissioningEnabled(); + if (actualState != threadCommissioningEnabled) { + Serial.printf("⚠️ Warning: State mismatch - intended: %s, actual: %s\n", + threadCommissioningEnabled ? "enabled" : "disabled", + actualState ? "enabled" : "disabled"); + threadCommissioningEnabled = actualState; // Sync to actual state + } +#else + Serial.println("Thread commissioning not supported (not compiled in)"); +#endif + printNetworkStatus(); +} + +void setWiFiOnlyMode() { + Serial.println("Setting WiFi-only commissioning mode..."); + wifiCommissioningEnabled = true; + threadCommissioningEnabled = false; + + if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { + Serial.println("✓ WiFi-only mode set successfully"); + } else { + Serial.println("✗ Failed to set WiFi-only mode"); + // Sync our state with actual API state + syncNetworkStates(); + } + printNetworkStatus(); +} + +void setThreadOnlyMode() { + Serial.println("Setting Thread-only commissioning mode..."); + wifiCommissioningEnabled = false; + threadCommissioningEnabled = true; + + if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { + Serial.println("✓ Thread-only mode set successfully"); + } else { + Serial.println("✗ Failed to set Thread-only mode"); + // Sync our state with actual API state + syncNetworkStates(); + } + printNetworkStatus(); +} + +void setBothNetworksMode() { + Serial.println("Setting both networks commissioning mode..."); + wifiCommissioningEnabled = true; + threadCommissioningEnabled = true; + + if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { + Serial.println("✓ Both networks mode set successfully"); + } else { + Serial.println("✗ Failed to set both networks mode"); + // Sync our state with actual API state + syncNetworkStates(); + } + printNetworkStatus(); +} + +void setNoNetworksMode() { + Serial.println("Disabling all network commissioning..."); + wifiCommissioningEnabled = false; + threadCommissioningEnabled = false; + + if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { + Serial.println("✓ All networks disabled successfully"); + } else { + Serial.println("✗ Failed to disable all networks"); + // Sync our state with actual API state + syncNetworkStates(); + } + printNetworkStatus(); +} + +void resetToFactory() { + Serial.println("Resetting to factory defaults..."); + Matter.decommission(); + Serial.println("✓ Factory reset completed. Device will restart."); + delay(1000); + ESP.restart(); +} + +void syncNetworkStates() { + // Synchronize our local state variables with the actual API state +#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION + wifiCommissioningEnabled = Matter.isWiFiNetworkCommissioningEnabled(); +#else + wifiCommissioningEnabled = false; +#endif + +#if CHIP_DEVICE_CONFIG_ENABLE_THREAD + threadCommissioningEnabled = Matter.isThreadNetworkCommissioningEnabled(); +#else + threadCommissioningEnabled = false; +#endif + + Serial.println("🔄 Network states synchronized with API"); +} + +void printNetworkStatus() { + Serial.println("\n--- Network Commissioning Status ---"); + +#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION + bool wifiEnabled = Matter.isWiFiNetworkCommissioningEnabled(); + bool wifiConnected = Matter.isWiFiConnected(); + Serial.printf("WiFi Commissioning: %s", wifiEnabled ? "ENABLED" : "DISABLED"); + if (wifiEnabled && wifiConnected) { + Serial.print(" (Connected)"); + } + Serial.println(); +#else + Serial.println("WiFi Commissioning: NOT SUPPORTED"); +#endif + +#if CHIP_DEVICE_CONFIG_ENABLE_THREAD + bool threadEnabled = Matter.isThreadNetworkCommissioningEnabled(); + bool threadConnected = Matter.isThreadConnected(); + Serial.printf("Thread Commissioning: %s", threadEnabled ? "ENABLED" : "DISABLED"); + if (threadEnabled && threadConnected) { + Serial.print(" (Connected)"); + } + Serial.println(); +#else + Serial.println("Thread Commissioning: NOT SUPPORTED"); +#endif + + Serial.printf("Device Commissioned: %s\n", Matter.isDeviceCommissioned() ? "YES" : "NO"); + Serial.printf("Device Connected: %s\n", Matter.isDeviceConnected() ? "YES" : "NO"); + Serial.println("----------------------------------\n"); +} + +void printCommands() { + Serial.println("\n--- Available Commands ---"); + Serial.println("w/W : Toggle WiFi commissioning"); + Serial.println("t/T : Toggle Thread commissioning"); + Serial.println("r/R : Reset to factory defaults"); + Serial.println("s/S : Show network status"); + Serial.println("1 : WiFi-only mode"); + Serial.println("2 : Thread-only mode"); + Serial.println("3 : Both networks mode"); + Serial.println("0 : No networks mode"); + Serial.println("h/H/? : Show this help"); + Serial.println("-------------------------\n"); +} + +// Matter event callback +void onMatterEvent(matterEvent_t event, const ChipDeviceEvent *eventData) { + switch (event) { + case MATTER_COMMISSIONING_COMPLETE: + Serial.println("🎉 Matter commissioning completed!"); + printNetworkStatus(); + break; + + case MATTER_COMMISSIONING_SESSION_STARTED: + Serial.println("🔗 Matter commissioning session started"); + break; + + case MATTER_COMMISSIONING_SESSION_STOPPED: + Serial.println("🔌 Matter commissioning session stopped"); + break; + + case MATTER_WIFI_CONNECTIVITY_CHANGE: + Serial.println("📶 WiFi connectivity changed"); + printNetworkStatus(); + break; + + case MATTER_THREAD_CONNECTIVITY_CHANGE: + Serial.println("🕸️ Thread connectivity changed"); + printNetworkStatus(); + break; + + case MATTER_CHIPOBLE_CONNECTION_ESTABLISHED: + Serial.println("📱 CHIPoBLE connection established"); + break; + + case MATTER_CHIPOBLE_CONNECTION_CLOSED: + Serial.println("📱 CHIPoBLE connection closed"); + break; + + default: + break; + } +} diff --git a/libraries/Matter/examples/MatterNetworkCommissioning/README.md b/libraries/Matter/examples/MatterNetworkCommissioning/README.md new file mode 100644 index 00000000000..7439a0b679b --- /dev/null +++ b/libraries/Matter/examples/MatterNetworkCommissioning/README.md @@ -0,0 +1,215 @@ +# Matter Network Commissioning Example + +This example demonstrates how to control which networks (WiFi/Thread) are available for commissioning when using CHIPoBLE (Chip over Bluetooth Low Energy) with an ESP32 SoC microcontroller.\ +The application showcases Matter network commissioning control, enabling/disabling WiFi and Thread commissioning modes, and monitoring commissioning events via serial commands. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Limited (WiFi only, no BLE) | +| ESP32-S2 | ✅ | ❌ | ❌ | Limited (WiFi only, no BLE) | +| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C6 | ✅ | ✅ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ✅ | ✅ | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Fully supported (Thread only) | + +### Note on Commissioning: + +- **ESP32 & ESP32-S2** do not support commissioning over Bluetooth LE. For these chips, network commissioning control is limited. This example is primarily designed for chips that support BLE commissioning (ESP32-S3, ESP32-C3, ESP32-C6, ESP32-C5, ESP32-H2). +- **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. +- **ESP32-C5** 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. + +## Features + +- Matter protocol implementation with network commissioning control +- Enable/disable WiFi network commissioning dynamically +- Enable/disable Thread network commissioning dynamically +- Set specific network commissioning modes (WiFi-only, Thread-only, both, or none) +- Serial command interface for controlling network commissioning +- Real-time network status monitoring +- Matter event callback for commissioning events +- Support for both WiFi and Thread(*) connectivity +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- USB connection for serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `WiFi` + +## Building and Flashing + +1. Open the `MatterNetworkCommissioning.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Matter Network Commissioning Control Example +=========================================== + +--- Network Commissioning Status --- +WiFi Commissioning: ENABLED +Thread Commissioning: DISABLED +Device Commissioned: NO +Device Connected: NO +---------------------------------- + +--- Available Commands --- +w/W : Toggle WiFi commissioning +t/T : Toggle Thread commissioning +r/R : Reset to factory defaults +s/S : Show network status +1 : WiFi-only mode +2 : Thread-only mode +3 : Both networks mode +0 : No networks mode +h/H/? : Show this help +------------------------- +``` + +## Using the Device + +### Serial Commands + +The example provides a serial command interface to control network commissioning modes. Type the following commands in the Serial Monitor: + +#### Individual Network Control + +- **`w` or `W`**: Toggle WiFi commissioning on/off +- **`t` or `T`**: Toggle Thread commissioning on/off + +#### Predefined Modes + +- **`1`**: Set WiFi-only commissioning mode +- **`2`**: Set Thread-only commissioning mode +- **`3`**: Set both networks commissioning mode (WiFi and Thread) +- **`0`**: Disable all network commissioning + +#### Utility Commands + +- **`s` or `S`**: Show current network status +- **`r` or `R`**: Reset to factory defaults (decommission and restart) +- **`h`, `H`, or `?`**: Show help (available commands) + +### Example Usage + +1. **Start with WiFi-only mode**: + ``` + Type '1' in Serial Monitor + Output: ✓ WiFi-only mode set successfully + ``` + +2. **Enable Thread commissioning**: + ``` + Type 't' in Serial Monitor + Output: ✓ Thread commissioning enabled + ``` + +3. **Check current status**: + ``` + Type 's' in Serial Monitor + Output: Shows current network commissioning status + ``` + +4. **Set both networks mode**: + ``` + Type '3' in Serial Monitor + Output: ✓ Both networks mode set successfully + ``` + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. The network commissioning mode determines which networks are available during the commissioning process. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as an on/off light in your Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup + +## Code Structure + +The MatterNetworkCommissioning example consists of the following main components: + +1. **`setup()`**: Initializes Serial communication, registers Matter event callback, initializes the Matter on/off light endpoint, sets initial network commissioning mode (WiFi-only by default), starts the Matter stack, synchronizes network states, and displays initial status. + +2. **`loop()`**: Handles serial commands from the user and allows the Matter stack to process events. + +3. **Serial Command Handlers**: + - `handleSerialCommand()`: Routes commands to appropriate handlers + - `toggleWiFiCommissioning()`: Enables/disables WiFi commissioning + - `toggleThreadCommissioning()`: Enables/disables Thread commissioning + - `setWiFiOnlyMode()`: Sets WiFi-only commissioning mode + - `setThreadOnlyMode()`: Sets Thread-only commissioning mode + - `setBothNetworksMode()`: Enables both WiFi and Thread commissioning + - `setNoNetworksMode()`: Disables all network commissioning + - `resetToFactory()`: Performs factory reset (decommission and restart) + +4. **Utility Functions**: + - `syncNetworkStates()`: Synchronizes local state variables with actual API state + - `printNetworkStatus()`: Displays current network commissioning status + - `printCommands()`: Displays available serial commands + +5. **Event Callback**: + - `onMatterEvent()`: Handles Matter events such as commissioning completion, session start/stop, WiFi/Thread connectivity changes, and CHIPoBLE connection events + +## Network Commissioning Modes + +The example supports the following network commissioning modes: + +- **WiFi-only**: Only WiFi networks are available for commissioning +- **Thread-only**: Only Thread networks are available for commissioning +- **Both networks**: Both WiFi and Thread networks are available for commissioning +- **No networks**: All network commissioning is disabled (device cannot be commissioned via networks) + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure network commissioning is enabled for the desired network type (WiFi or Thread). Check the network status using the 's' command +- **WiFi commissioning not supported**: This message appears if WiFi station support is not compiled into the Matter library for your board +- **Thread commissioning not supported**: This message appears if Thread support is not compiled into the Matter library for your board +- **Commands not working**: Ensure you're typing commands in the Serial Monitor (not Serial Plotter) and that the baud rate is set to 115200 +- **State mismatch warnings**: If you see state mismatch warnings, the API has been synchronized to match the actual state. This is normal and handled automatically +- **Failed to commission**: Try changing the network commissioning mode (e.g., switch from Thread-only to WiFi-only) and attempt commissioning again. You can also use the 'r' command to factory reset +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterOccupancySensor/README.md b/libraries/Matter/examples/MatterOccupancySensor/README.md index c163ac33e91..8e54ac261e5 100644 --- a/libraries/Matter/examples/MatterOccupancySensor/README.md +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterOnIdentify/README.md b/libraries/Matter/examples/MatterOnIdentify/README.md index 84696ed63d2..4122b07d268 100644 --- a/libraries/Matter/examples/MatterOnIdentify/README.md +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterOnOffLight/README.md b/libraries/Matter/examples/MatterOnOffLight/README.md index e7b6fb4f3ba..998fd10d708 100644 --- a/libraries/Matter/examples/MatterOnOffLight/README.md +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterOnOffPlugin/README.md b/libraries/Matter/examples/MatterOnOffPlugin/README.md index b5217301c4b..94757495c97 100644 --- a/libraries/Matter/examples/MatterOnOffPlugin/README.md +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, device control via smart home ec | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, device control via smart home ec - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterPressureSensor/README.md b/libraries/Matter/examples/MatterPressureSensor/README.md index 7bf5b1418aa..32c9ac1d727 100644 --- a/libraries/Matter/examples/MatterPressureSensor/README.md +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterSmartButon/MatterSmartButon.ino b/libraries/Matter/examples/MatterSmartButton/MatterSmartButon.ino similarity index 100% rename from libraries/Matter/examples/MatterSmartButon/MatterSmartButon.ino rename to libraries/Matter/examples/MatterSmartButton/MatterSmartButon.ino diff --git a/libraries/Matter/examples/MatterSmartButon/README.md b/libraries/Matter/examples/MatterSmartButton/README.md similarity index 95% rename from libraries/Matter/examples/MatterSmartButon/README.md rename to libraries/Matter/examples/MatterSmartButton/README.md index e0368605803..6a08e04f819 100644 --- a/libraries/Matter/examples/MatterSmartButon/README.md +++ b/libraries/Matter/examples/MatterSmartButton/README.md @@ -12,12 +12,14 @@ The application showcases Matter commissioning, sending button click events to s | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | ### Note on Commissioning: - **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. - **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. +- **ESP32-C5** 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. ## Features @@ -67,7 +69,7 @@ Before uploading the sketch, configure the following: ## Building and Flashing -1. Open the `MatterSmartButon.ino` sketch in the Arduino IDE. +1. Open the `MatterSmartButton.ino` sketch in the Arduino IDE. 2. Select your ESP32 board from the **Tools > Board** menu. 3. Connect your ESP32 board to your computer via USB. 4. Click the **Upload** button to compile and flash the sketch. diff --git a/libraries/Matter/examples/MatterSmartButon/ci.yml b/libraries/Matter/examples/MatterSmartButton/ci.yml similarity index 100% rename from libraries/Matter/examples/MatterSmartButon/ci.yml rename to libraries/Matter/examples/MatterSmartButton/ci.yml diff --git a/libraries/Matter/examples/MatterTemperatureLight/README.md b/libraries/Matter/examples/MatterTemperatureLight/README.md index e69de29bb2d..0cc2f6b8007 100644 --- a/libraries/Matter/examples/MatterTemperatureLight/README.md +++ b/libraries/Matter/examples/MatterTemperatureLight/README.md @@ -0,0 +1,208 @@ +# Matter Color Temperature Light Example + +This example demonstrates how to create a Matter-compatible color temperature light device using an ESP32 SoC microcontroller.\ +The application showcases Matter commissioning, device control via smart home ecosystems, and manual control using a physical button. The color temperature light provides warm white to cool white control with adjustable brightness. + +## Supported Targets + +| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| --- | ---- | ------ | ----------------- | ------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | ❌ | ✅ | Required | Fully supported | +| ESP32-H2 | ❌ | ✅ | ✅ | Required | Supported (Thread only) | + +### Note on Commissioning: + +- **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. +- **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. +- **ESP32-C5** 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. + +## Features + +- Matter protocol implementation for a color temperature light device +- Support for both WiFi and Thread(*) connectivity +- Color temperature control (warm white to cool white, 100-500 mireds) +- Brightness level control (0-255) +- State persistence using `Preferences` library +- Button control for toggling light and factory reset +- RGB LED support with color temperature to RGB conversion +- Regular LED support with PWM brightness control +- Matter commissioning via QR code or manual pairing code +- Integration with Apple HomeKit, Amazon Alexa, and Google Home +(*) It is necessary to compile the project using Arduino as IDF Component. + +## Hardware Requirements + +- ESP32 compatible development board (see supported targets table) +- RGB LED connected to GPIO pins (or using built-in RGB LED), or regular LED for PWM brightness control +- User button for manual control (uses BOOT button by default) + +## Pin Configuration + +- **RGB LED**: Uses `RGB_BUILTIN` if defined, otherwise pin 2 +- **Button**: Uses `BOOT_PIN` by default + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with Matter support +3. ESP32 Arduino libraries: + - `Matter` + - `Preferences` + - `WiFi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + const char *ssid = "your-ssid"; // Change to your WiFi SSID + const char *password = "your-password"; // Change to your WiFi password + ``` + +2. **LED pin configuration** (if not using built-in RGB LED): + ```cpp + const uint8_t ledPin = 2; // Set your RGB LED pin here + ``` + +3. **Button pin configuration** (optional): + 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. + ```cpp + const uint8_t buttonPin = BOOT_PIN; // Set your button pin here + ``` + +## Building and Flashing + +1. Open the `MatterTemperatureLight.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu. +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +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: + +``` +Connecting to your-wifi-ssid +....... +WiFi connected +IP address: 192.168.1.100 + +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 +Matter Node not commissioned yet. Waiting for commissioning. +Matter Node not commissioned yet. Waiting for commissioning. +... +Initial state: ON | brightness: 15 | Color Temperature: 454 mireds +Matter Node is commissioned and connected to the network. Ready for use. +Light OnOff changed to ON +Light Brightness changed to 128 +Light Color Temperature changed to 370 +``` + +## Using the Device + +### Manual Control + +The user button (BOOT button by default) provides manual control: + +- **Short press of the button**: Toggle light on/off +- **Long press (>5 seconds)**: Factory reset the device (decommission) + +### Color Temperature Control + +The light supports color temperature adjustment from warm white to cool white: + +- **Warm White**: Higher mired values (400-500 mireds) - warmer, more yellow light +- **Cool White**: Lower mired values (100-200 mireds) - cooler, more blue light +- **Default**: 454 mireds (Warm White) + +The color temperature is stored in `Preferences` and restored after power cycles. + +### Brightness Control + +The light supports brightness adjustment from 0 to 255: + +- **0**: Light is off +- **1-254**: Various brightness levels +- **255**: Maximum brightness +- **Default**: 15 (~6% brightness) + +The brightness level is stored in `Preferences` and restored after power cycles. + +### Smart Home Integration + +Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. + +#### Apple Home + +1. Open the Home app on your iOS device +2. Tap the "+" button > Add Accessory +3. Scan the QR code displayed in the Serial Monitor, or +4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code +5. Follow the prompts to complete setup +6. The device will appear as a color temperature light in your Home app +7. You can adjust the color temperature (warm/cool) and brightness from the Home app + +#### Amazon Alexa + +1. Open the Alexa app +2. Tap More > Add Device > Matter +3. Select "Scan QR code" or "Enter code manually" +4. Complete the setup process +5. The light will appear in your Alexa app +6. You can control color temperature and brightness using voice commands or the app + +#### Google Home + +1. Open the Google Home app +2. Tap "+" > Set up device > New device +3. Choose "Matter device" +4. Scan the QR code or enter the manual pairing code +5. Follow the prompts to complete setup +6. You can adjust color temperature and brightness from the Google Home app + +## Code Structure + +The MatterTemperatureLight example consists of the following main components: + +1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter Color Temperature Light endpoint, restores the last known state from `Preferences` (on/off, brightness, color temperature), and registers callbacks for state changes. + +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. + +3. **Callbacks**: + - `setLightState()`: Controls the physical LED. For RGB LEDs, converts color temperature (mireds) to RGB color and applies brightness. For regular LEDs, uses PWM brightness control. + - `onChangeOnOff()`: Handles on/off state changes and logs to Serial Monitor. + - `onChangeBrightness()`: Handles brightness changes and logs to Serial Monitor. + - `onChangeColorTemperature()`: Handles color temperature changes and logs to Serial Monitor. + +4. **State Persistence**: Uses `Preferences` library to store and restore: + - On/off state (default: ON if not previously stored) + - Brightness level (default: 15 if not previously stored) + - Color temperature in mireds (default: 454 mireds - Warm White if not previously stored) + +## Troubleshooting + +- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **RGB LED not responding**: Verify pin configurations and connections. For RGB LEDs, ensure the board defines `RGB_BUILTIN` or set the pin manually +- **LED not showing color temperature correctly**: RGB LED conversion uses `espCTToRgbColor()` function. For regular LEDs, only brightness is controlled via PWM +- **Color temperature not changing**: Verify that color temperature is within valid range (100-500 mireds). Check Serial Monitor for callback messages +- **Brightness not responding**: Ensure LED pin supports PWM output. Check Serial Monitor for brightness change messages +- **State not persisting**: Verify `Preferences` library is working correctly. Check that flash memory is not full +- **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 erase_flash` +- **No serial output**: Check baudrate (115200) and USB connection + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/Matter/examples/MatterTemperatureSensor/README.md b/libraries/Matter/examples/MatterTemperatureSensor/README.md index 210fde16d30..f2fd82b985c 100644 --- a/libraries/Matter/examples/MatterTemperatureSensor/README.md +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterThermostat/README.md b/libraries/Matter/examples/MatterThermostat/README.md index c1f45b1961a..57f33130411 100644 --- a/libraries/Matter/examples/MatterThermostat/README.md +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -11,6 +11,7 @@ The application showcases Matter commissioning, thermostat control via smart hom | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Fully supported | | ESP32-C6 | ✅ | ❌ | ✅ | Fully supported | | ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) | @@ -18,6 +19,7 @@ The application showcases Matter commissioning, thermostat control via smart hom - **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. - **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. +- **ESP32-C5** 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. ## Features diff --git a/libraries/Matter/examples/MatterThreadLight/README.md b/libraries/Matter/examples/MatterThreadLight/README.md new file mode 100644 index 00000000000..9dea8e7a4c3 --- /dev/null +++ b/libraries/Matter/examples/MatterThreadLight/README.md @@ -0,0 +1,242 @@ +# Matter Thread Light Example + +This example demonstrates a Matter Light device that uses Thread network commissioning exclusively. Thread is a low-power, mesh networking protocol that's ideal for Matter smart home devices. + +## Features + +- **Thread-only commissioning**: Device can only be commissioned over Thread network +- **On/Off Light control**: Simple light that can be controlled via Matter +- **Automatic fallback**: On non-Thread capable devices, falls back to WiFi +- **Status monitoring**: Displays network and commissioning status +- **Decommissioning support**: Long-press boot button to decommission + +## Hardware Requirements + +### Thread-Capable ESP32 Variants +- **ESP32-H2**: Native Thread support +- **ESP32-C6**: Native Thread support +- **ESP32-C5**: Native Thread support + +### Other ESP32 Variants +- **ESP32, ESP32-S2, ESP32-S3, ESP32-C3**: Will automatically fall back to WiFi commissioning + +## Hardware Setup + +### Basic Setup +``` +ESP32-H2/C6/C5 Board +├── LED (GPIO 2 or LED_BUILTIN) - Visual feedback +└── Boot Button (GPIO 0) - Decommissioning +``` + +### Pin Configuration +- **LED Pin**: Uses `LED_BUILTIN` if available, otherwise GPIO 2 +- **Button Pin**: Uses `BOOT_PIN` (typically GPIO 0) + +## Network Requirements + +### Thread Border Router +To use Thread commissioning, you need a Thread Border Router in your network: + +**Apple HomePod/Apple TV (tvOS 15+)** +``` +- Supports Thread Border Router functionality +- Automatically discovered by Matter controllers +``` + +**Google Nest Hub Max (2nd gen)** +``` +- Built-in Thread Border Router +- Works with Google Home ecosystem +``` + +**OpenThread Border Router** +``` +- Raspberry Pi with Thread radio +- Custom Thread Border Router setup +``` + +## Usage + +### 1. Upload and Monitor +```bash +# Upload the sketch to your ESP32-H2/C6 +# Open Serial Monitor at 115200 baud +``` + +### 2. Check Thread Status +The device will display: +``` +=== Matter Thread Light Status === +Device commissioned: No +Device connected: No +Thread connected: No +Thread commissioning: Enabled +WiFi commissioning: Disabled +Light state: OFF +================================ +``` + +### 3. Commission the Device +Use a Matter controller that supports Thread: + +**Apple Home** +1. Open Home app on iPhone/iPad +2. Tap "Add Accessory" +3. Scan QR code or enter manual pairing code +4. Follow commissioning steps + +**Google Home** +1. Open Google Home app +2. Tap "Add" → "Set up device" +3. Choose "Works with Google" +4. Scan QR code or enter pairing code + +### 4. Control the Light +Once commissioned, you can: +- Turn the light on/off from your Matter controller +- Monitor status in Serial Monitor +- See LED respond to commands + +### 5. Decommission (if needed) +1. Hold the boot button for 5+ seconds +2. Device will reset and become available for commissioning again + +## Serial Output + +### Successful Thread Commissioning +``` +Starting Thread-only Matter Light... +✓ Thread-only commissioning mode enabled +Matter Node is not commissioned yet. +Manual pairing code: 12345678901 +QR code URL: https://... + +This device is configured for Thread commissioning only. +Make sure your Matter controller supports Thread commissioning. + +Waiting for Matter commissioning... +Looking for Thread Border Router... +Thread connected: Yes +Device commissioned: Yes +Light ON +``` + +### Non-Thread Device Fallback +``` +Starting Thread-only Matter Light... +⚠ Thread support not compiled in, using WiFi commissioning +Matter Node is not commissioned yet. +WiFi commissioning: Enabled +``` + +## Troubleshooting + +### Device Not Commissioning +**Problem**: Device stuck on "Waiting for Matter commissioning..." + +**Solutions**: +1. **Check Thread Border Router**: + - Ensure Thread Border Router is online + - Verify controller supports Thread commissioning + +2. **Verify Network**: + - Check Thread network is operational + - Ensure Matter controller is on same network as Border Router + +3. **Reset and Retry**: + - Hold boot button for 5+ seconds to decommission + - Try commissioning again + +### Thread Connection Issues +**Problem**: "Thread connected: No" in status + +**Solutions**: +1. **Border Router Setup**: + - Verify Thread Border Router is functioning + - Check Border Router connectivity + +2. **Device Placement**: + - Move device closer to Thread Border Router + - Ensure no interference with Thread radio + +3. **Thread Network**: + - Verify Thread network credentials + - Check Thread network topology + +### Compilation Issues +**Problem**: Compilation errors related to Thread + +**Solutions**: +1. **ESP-IDF Version**: + ```bash + # Ensure ESP-IDF supports Thread for your board + # Update to latest ESP-IDF if needed + ``` + +2. **Board Configuration**: + ```bash + # Make sure you've selected the correct board + # ESP32-H2/C6/C5 for Thread support + ``` + +## API Reference + +### Network Commissioning Control +```cpp +// Enable Thread-only commissioning +Matter.setNetworkCommissioningMode(false, true); + +// Check Thread commissioning status +bool enabled = Matter.isThreadNetworkCommissioningEnabled(); + +// Check Thread connection +bool connected = Matter.isThreadConnected(); +``` + +### Device Status +```cpp +// Check if device is commissioned +bool commissioned = Matter.isDeviceCommissioned(); + +// Check if device has network connectivity +bool connected = Matter.isDeviceConnected(); +``` + +### Light Control +```cpp +// Set light state +OnOffLight.setOnOff(true); // Turn on +OnOffLight.setOnOff(false); // Turn off + +// Get current state +bool isOn = OnOffLight.getOnOff(); + +// Toggle light +OnOffLight.toggle(); +``` + +## Thread vs WiFi Comparison + +| Feature | Thread | WiFi | +|---------|--------|------| +| **Power Consumption** | Low | Higher | +| **Range** | Mesh network, self-healing | Single point to router | +| **Setup** | Requires Border Router | Direct to WiFi router | +| **Reliability** | High (mesh redundancy) | Depends on WiFi quality | +| **Device Limit** | 250+ devices per network | Limited by router | +| **Security** | Built-in mesh security | WPA2/WPA3 | + +## Related Examples + +- **[SimpleNetworkCommissioning](../SimpleNetworkCommissioning/)**: Basic WiFi/Thread selection +- **[MatterNetworkCommissioning](../MatterNetworkCommissioning/)**: Interactive commissioning control +- **[MatterMinimum](../MatterMinimum/)**: Simplest WiFi-only setup +- **[MatterOnOffLight](../MatterOnOffLight/)**: WiFi-based light with persistence + +## Further Reading + +- [Thread Group Specification](https://www.threadgroup.org/) +- [OpenThread Documentation](https://openthread.io/) +- [Matter Thread Integration Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/thread_primer.md) +- [ESP32 Thread Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/thread.html) From 6c01cef6aae798ff79d4933cb119bbc3c859516d Mon Sep 17 00:00:00 2001 From: SuGlider Date: Wed, 5 Nov 2025 06:31:43 -0300 Subject: [PATCH 05/10] feat(matter): fixes MatterSmartButton.ino name --- .../{MatterSmartButon.ino => MatterSmartButton.ino} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename libraries/Matter/examples/MatterSmartButton/{MatterSmartButon.ino => MatterSmartButton.ino} (100%) diff --git a/libraries/Matter/examples/MatterSmartButton/MatterSmartButon.ino b/libraries/Matter/examples/MatterSmartButton/MatterSmartButton.ino similarity index 100% rename from libraries/Matter/examples/MatterSmartButton/MatterSmartButon.ino rename to libraries/Matter/examples/MatterSmartButton/MatterSmartButton.ino From 81690e8bb03029d876f114290de9575cec0e1f53 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Wed, 5 Nov 2025 06:33:21 -0300 Subject: [PATCH 06/10] fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../examples/MatterCommissionTest/MatterCommissionTest.ino | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino b/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino index 4410d96dba1..81e7e6d45f8 100644 --- a/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino +++ b/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino @@ -77,5 +77,5 @@ void loop() { Serial.println("====> Decommissioning in 30 seconds. <===="); delay(30000); Matter.decommission(); - Serial.println("Matter Node is decommissioned. Commisssioning widget shall start over."); + Serial.println("Matter Node is decommissioned. Commissioning widget shall start over."); } From c8b10898d5489a56544644fc05949898e40e5023 Mon Sep 17 00:00:00 2001 From: Sugar Glider Date: Wed, 5 Nov 2025 06:35:21 -0300 Subject: [PATCH 07/10] fix(matter): typo --- libraries/Matter/examples/MatterCommissionTest/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md index 4fc2c70287a..0d3dc9ae0e2 100644 --- a/libraries/Matter/examples/MatterCommissionTest/README.md +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -82,7 +82,7 @@ Matter Fabric not commissioned yet. Waiting for commissioning. ... Matter Node is commissioned and connected to the network. ====> Decommissioning in 30 seconds. <==== -Matter Node is decommissioned. Commisssioning widget shall start over. +Matter Node is decommissioned. Commissioning widget shall start over. Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. From fcdee8b35cb3e923a070e17a0c30239830b638f5 Mon Sep 17 00:00:00 2001 From: SuGlider Date: Wed, 5 Nov 2025 07:57:46 -0300 Subject: [PATCH 08/10] fix(matter): removes bad example --- .../MatterNetworkCommissioning.ino | 370 ------------------ .../MatterNetworkCommissioning/README.md | 215 ---------- 2 files changed, 585 deletions(-) delete mode 100644 libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino delete mode 100644 libraries/Matter/examples/MatterNetworkCommissioning/README.md diff --git a/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino b/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino deleted file mode 100644 index 546064c4ed5..00000000000 --- a/libraries/Matter/examples/MatterNetworkCommissioning/MatterNetworkCommissioning.ino +++ /dev/null @@ -1,370 +0,0 @@ -/* - Matter Network Commissioning Control Example - - This example demonstrates how to control which networks (WiFi/Thread) are available - for commissioning when using CHIPoBLE (Chip over Bluetooth Low Energy). - - The sketch shows how to: - 1. Enable/disable WiFi network commissioning - 2. Enable/disable Thread network commissioning - 3. Set specific network commissioning modes - 4. Monitor commissioning events - - Instructions: - 1. Use a Matter commissioner app (like CHIPTool) to start commissioning - 2. Connect via BLE and commission the device to your desired network - 3. Use the serial commands to control which networks are available - - Serial Commands: - - 'w' : Toggle WiFi commissioning - - 't' : Toggle Thread commissioning - - 'r' : Reset to factory defaults - - 's' : Show current network status - - '1' : WiFi only mode - - '2' : Thread only mode - - '3' : Both networks mode - - '0' : No networks mode - - Author: ESP32 Arduino Team - Date: 2024 -*/ - -#include -#include - -// Matter Light Endpoint -MatterOnOffLight OnOffLight; - -// Network commissioning states -bool wifiCommissioningEnabled = true; -bool threadCommissioningEnabled = false; - -void setup() { - Serial.begin(115200); - - // Register Matter event callback - Matter.onEvent(onMatterEvent); - - // Initialize Matter endpoint - OnOffLight.begin(); - - // Set initial network commissioning mode BEFORE Matter.begin() - // Start with WiFi only by default - if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { - Serial.println("Initial network commissioning mode set successfully"); - } else { - Serial.println("Warning: Failed to set initial network commissioning mode"); - } - - // Start Matter stack - Matter.begin(); - - // Synchronize our state variables with actual API state - syncNetworkStates(); - - Serial.println("Matter Network Commissioning Control Example"); - Serial.println("==========================================="); - printNetworkStatus(); - printCommands(); -} - -void loop() { - // Handle serial commands - if (Serial.available()) { - char cmd = Serial.read(); - handleSerialCommand(cmd); - } - - // Update Matter - delay(100); -} - -void handleSerialCommand(char cmd) { - switch (cmd) { - case 'w': - case 'W': - toggleWiFiCommissioning(); - break; - - case 't': - case 'T': - toggleThreadCommissioning(); - break; - - case 'r': - case 'R': - resetToFactory(); - break; - - case 's': - case 'S': - printNetworkStatus(); - break; - - case '1': - setWiFiOnlyMode(); - break; - - case '2': - setThreadOnlyMode(); - break; - - case '3': - setBothNetworksMode(); - break; - - case '0': - setNoNetworksMode(); - break; - - case 'h': - case 'H': - case '?': - printCommands(); - break; - - default: - if (cmd != '\n' && cmd != '\r') { - Serial.println("Unknown command. Type 'h' for help."); - } - break; - } -} - -void toggleWiFiCommissioning() { -#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION - wifiCommissioningEnabled = !wifiCommissioningEnabled; - - if (wifiCommissioningEnabled) { - if (Matter.enableWiFiNetworkCommissioning()) { - Serial.println("✓ WiFi commissioning enabled"); - } else { - Serial.println("✗ Failed to enable WiFi commissioning"); - wifiCommissioningEnabled = false; // Revert state - } - } else { - if (Matter.disableWiFiNetworkCommissioning()) { - Serial.println("✓ WiFi commissioning disabled"); - } else { - Serial.println("✗ Failed to disable WiFi commissioning"); - wifiCommissioningEnabled = true; // Revert state - } - } - - // Verify actual state matches our intended state - bool actualState = Matter.isWiFiNetworkCommissioningEnabled(); - if (actualState != wifiCommissioningEnabled) { - Serial.printf("⚠️ Warning: State mismatch - intended: %s, actual: %s\n", - wifiCommissioningEnabled ? "enabled" : "disabled", - actualState ? "enabled" : "disabled"); - wifiCommissioningEnabled = actualState; // Sync to actual state - } -#else - Serial.println("WiFi commissioning not supported (not compiled in)"); -#endif - printNetworkStatus(); -} - -void toggleThreadCommissioning() { -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD - threadCommissioningEnabled = !threadCommissioningEnabled; - - if (threadCommissioningEnabled) { - if (Matter.enableThreadNetworkCommissioning()) { - Serial.println("✓ Thread commissioning enabled"); - } else { - Serial.println("✗ Failed to enable Thread commissioning"); - threadCommissioningEnabled = false; // Revert state - } - } else { - if (Matter.disableThreadNetworkCommissioning()) { - Serial.println("✓ Thread commissioning disabled"); - } else { - Serial.println("✗ Failed to disable Thread commissioning"); - threadCommissioningEnabled = true; // Revert state - } - } - - // Verify actual state matches our intended state - bool actualState = Matter.isThreadNetworkCommissioningEnabled(); - if (actualState != threadCommissioningEnabled) { - Serial.printf("⚠️ Warning: State mismatch - intended: %s, actual: %s\n", - threadCommissioningEnabled ? "enabled" : "disabled", - actualState ? "enabled" : "disabled"); - threadCommissioningEnabled = actualState; // Sync to actual state - } -#else - Serial.println("Thread commissioning not supported (not compiled in)"); -#endif - printNetworkStatus(); -} - -void setWiFiOnlyMode() { - Serial.println("Setting WiFi-only commissioning mode..."); - wifiCommissioningEnabled = true; - threadCommissioningEnabled = false; - - if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { - Serial.println("✓ WiFi-only mode set successfully"); - } else { - Serial.println("✗ Failed to set WiFi-only mode"); - // Sync our state with actual API state - syncNetworkStates(); - } - printNetworkStatus(); -} - -void setThreadOnlyMode() { - Serial.println("Setting Thread-only commissioning mode..."); - wifiCommissioningEnabled = false; - threadCommissioningEnabled = true; - - if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { - Serial.println("✓ Thread-only mode set successfully"); - } else { - Serial.println("✗ Failed to set Thread-only mode"); - // Sync our state with actual API state - syncNetworkStates(); - } - printNetworkStatus(); -} - -void setBothNetworksMode() { - Serial.println("Setting both networks commissioning mode..."); - wifiCommissioningEnabled = true; - threadCommissioningEnabled = true; - - if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { - Serial.println("✓ Both networks mode set successfully"); - } else { - Serial.println("✗ Failed to set both networks mode"); - // Sync our state with actual API state - syncNetworkStates(); - } - printNetworkStatus(); -} - -void setNoNetworksMode() { - Serial.println("Disabling all network commissioning..."); - wifiCommissioningEnabled = false; - threadCommissioningEnabled = false; - - if (Matter.setNetworkCommissioningMode(wifiCommissioningEnabled, threadCommissioningEnabled)) { - Serial.println("✓ All networks disabled successfully"); - } else { - Serial.println("✗ Failed to disable all networks"); - // Sync our state with actual API state - syncNetworkStates(); - } - printNetworkStatus(); -} - -void resetToFactory() { - Serial.println("Resetting to factory defaults..."); - Matter.decommission(); - Serial.println("✓ Factory reset completed. Device will restart."); - delay(1000); - ESP.restart(); -} - -void syncNetworkStates() { - // Synchronize our local state variables with the actual API state -#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION - wifiCommissioningEnabled = Matter.isWiFiNetworkCommissioningEnabled(); -#else - wifiCommissioningEnabled = false; -#endif - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD - threadCommissioningEnabled = Matter.isThreadNetworkCommissioningEnabled(); -#else - threadCommissioningEnabled = false; -#endif - - Serial.println("🔄 Network states synchronized with API"); -} - -void printNetworkStatus() { - Serial.println("\n--- Network Commissioning Status ---"); - -#if CHIP_DEVICE_CONFIG_ENABLE_WIFI_STATION - bool wifiEnabled = Matter.isWiFiNetworkCommissioningEnabled(); - bool wifiConnected = Matter.isWiFiConnected(); - Serial.printf("WiFi Commissioning: %s", wifiEnabled ? "ENABLED" : "DISABLED"); - if (wifiEnabled && wifiConnected) { - Serial.print(" (Connected)"); - } - Serial.println(); -#else - Serial.println("WiFi Commissioning: NOT SUPPORTED"); -#endif - -#if CHIP_DEVICE_CONFIG_ENABLE_THREAD - bool threadEnabled = Matter.isThreadNetworkCommissioningEnabled(); - bool threadConnected = Matter.isThreadConnected(); - Serial.printf("Thread Commissioning: %s", threadEnabled ? "ENABLED" : "DISABLED"); - if (threadEnabled && threadConnected) { - Serial.print(" (Connected)"); - } - Serial.println(); -#else - Serial.println("Thread Commissioning: NOT SUPPORTED"); -#endif - - Serial.printf("Device Commissioned: %s\n", Matter.isDeviceCommissioned() ? "YES" : "NO"); - Serial.printf("Device Connected: %s\n", Matter.isDeviceConnected() ? "YES" : "NO"); - Serial.println("----------------------------------\n"); -} - -void printCommands() { - Serial.println("\n--- Available Commands ---"); - Serial.println("w/W : Toggle WiFi commissioning"); - Serial.println("t/T : Toggle Thread commissioning"); - Serial.println("r/R : Reset to factory defaults"); - Serial.println("s/S : Show network status"); - Serial.println("1 : WiFi-only mode"); - Serial.println("2 : Thread-only mode"); - Serial.println("3 : Both networks mode"); - Serial.println("0 : No networks mode"); - Serial.println("h/H/? : Show this help"); - Serial.println("-------------------------\n"); -} - -// Matter event callback -void onMatterEvent(matterEvent_t event, const ChipDeviceEvent *eventData) { - switch (event) { - case MATTER_COMMISSIONING_COMPLETE: - Serial.println("🎉 Matter commissioning completed!"); - printNetworkStatus(); - break; - - case MATTER_COMMISSIONING_SESSION_STARTED: - Serial.println("🔗 Matter commissioning session started"); - break; - - case MATTER_COMMISSIONING_SESSION_STOPPED: - Serial.println("🔌 Matter commissioning session stopped"); - break; - - case MATTER_WIFI_CONNECTIVITY_CHANGE: - Serial.println("📶 WiFi connectivity changed"); - printNetworkStatus(); - break; - - case MATTER_THREAD_CONNECTIVITY_CHANGE: - Serial.println("🕸️ Thread connectivity changed"); - printNetworkStatus(); - break; - - case MATTER_CHIPOBLE_CONNECTION_ESTABLISHED: - Serial.println("📱 CHIPoBLE connection established"); - break; - - case MATTER_CHIPOBLE_CONNECTION_CLOSED: - Serial.println("📱 CHIPoBLE connection closed"); - break; - - default: - break; - } -} diff --git a/libraries/Matter/examples/MatterNetworkCommissioning/README.md b/libraries/Matter/examples/MatterNetworkCommissioning/README.md deleted file mode 100644 index 7439a0b679b..00000000000 --- a/libraries/Matter/examples/MatterNetworkCommissioning/README.md +++ /dev/null @@ -1,215 +0,0 @@ -# Matter Network Commissioning Example - -This example demonstrates how to control which networks (WiFi/Thread) are available for commissioning when using CHIPoBLE (Chip over Bluetooth Low Energy) with an ESP32 SoC microcontroller.\ -The application showcases Matter network commissioning control, enabling/disabling WiFi and Thread commissioning modes, and monitoring commissioning events via serial commands. - -## Supported Targets - -| SoC | WiFi | Thread | BLE Commissioning | Status | -| --- | ---- | ------ | ----------------- | ------ | -| ESP32 | ✅ | ❌ | ❌ | Limited (WiFi only, no BLE) | -| ESP32-S2 | ✅ | ❌ | ❌ | Limited (WiFi only, no BLE) | -| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported | -| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported | -| ESP32-C6 | ✅ | ✅ | ✅ | Fully supported | -| ESP32-C5 | ✅ | ✅ | ✅ | Fully supported | -| ESP32-H2 | ❌ | ✅ | ✅ | Fully supported (Thread only) | - -### Note on Commissioning: - -- **ESP32 & ESP32-S2** do not support commissioning over Bluetooth LE. For these chips, network commissioning control is limited. This example is primarily designed for chips that support BLE commissioning (ESP32-S3, ESP32-C3, ESP32-C6, ESP32-C5, ESP32-H2). -- **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. -- **ESP32-C5** 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. - -## Features - -- Matter protocol implementation with network commissioning control -- Enable/disable WiFi network commissioning dynamically -- Enable/disable Thread network commissioning dynamically -- Set specific network commissioning modes (WiFi-only, Thread-only, both, or none) -- Serial command interface for controlling network commissioning -- Real-time network status monitoring -- Matter event callback for commissioning events -- Support for both WiFi and Thread(*) connectivity -- Matter commissioning via QR code or manual pairing code -- Integration with Apple HomeKit, Amazon Alexa, and Google Home -(*) It is necessary to compile the project using Arduino as IDF Component. - -## Hardware Requirements - -- ESP32 compatible development board (see supported targets table) -- USB connection for serial communication - -## Software Setup - -### Prerequisites - -1. Install the Arduino IDE (2.0 or newer recommended) -2. Install ESP32 Arduino Core with Matter support -3. ESP32 Arduino libraries: - - `Matter` - - `WiFi` - -## Building and Flashing - -1. Open the `MatterNetworkCommissioning.ino` sketch in the Arduino IDE. -2. Select your ESP32 board from the **Tools > Board** menu. -3. Connect your ESP32 board to your computer via USB. -4. Click the **Upload** button to compile and flash the sketch. - -## Expected Output - -Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: - -``` -Matter Network Commissioning Control Example -=========================================== - ---- Network Commissioning Status --- -WiFi Commissioning: ENABLED -Thread Commissioning: DISABLED -Device Commissioned: NO -Device Connected: NO ----------------------------------- - ---- Available Commands --- -w/W : Toggle WiFi commissioning -t/T : Toggle Thread commissioning -r/R : Reset to factory defaults -s/S : Show network status -1 : WiFi-only mode -2 : Thread-only mode -3 : Both networks mode -0 : No networks mode -h/H/? : Show this help -------------------------- -``` - -## Using the Device - -### Serial Commands - -The example provides a serial command interface to control network commissioning modes. Type the following commands in the Serial Monitor: - -#### Individual Network Control - -- **`w` or `W`**: Toggle WiFi commissioning on/off -- **`t` or `T`**: Toggle Thread commissioning on/off - -#### Predefined Modes - -- **`1`**: Set WiFi-only commissioning mode -- **`2`**: Set Thread-only commissioning mode -- **`3`**: Set both networks commissioning mode (WiFi and Thread) -- **`0`**: Disable all network commissioning - -#### Utility Commands - -- **`s` or `S`**: Show current network status -- **`r` or `R`**: Reset to factory defaults (decommission and restart) -- **`h`, `H`, or `?`**: Show help (available commands) - -### Example Usage - -1. **Start with WiFi-only mode**: - ``` - Type '1' in Serial Monitor - Output: ✓ WiFi-only mode set successfully - ``` - -2. **Enable Thread commissioning**: - ``` - Type 't' in Serial Monitor - Output: ✓ Thread commissioning enabled - ``` - -3. **Check current status**: - ``` - Type 's' in Serial Monitor - Output: Shows current network commissioning status - ``` - -4. **Set both networks mode**: - ``` - Type '3' in Serial Monitor - Output: ✓ Both networks mode set successfully - ``` - -### Smart Home Integration - -Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device. The network commissioning mode determines which networks are available during the commissioning process. - -#### Apple Home - -1. Open the Home app on your iOS device -2. Tap the "+" button > Add Accessory -3. Scan the QR code displayed in the Serial Monitor, or -4. Tap "I Don't Have a Code or Cannot Scan" and enter the manual pairing code -5. Follow the prompts to complete setup -6. The device will appear as an on/off light in your Home app - -#### Amazon Alexa - -1. Open the Alexa app -2. Tap More > Add Device > Matter -3. Select "Scan QR code" or "Enter code manually" -4. Complete the setup process -5. The light will appear in your Alexa app - -#### Google Home - -1. Open the Google Home app -2. Tap "+" > Set up device > New device -3. Choose "Matter device" -4. Scan the QR code or enter the manual pairing code -5. Follow the prompts to complete setup - -## Code Structure - -The MatterNetworkCommissioning example consists of the following main components: - -1. **`setup()`**: Initializes Serial communication, registers Matter event callback, initializes the Matter on/off light endpoint, sets initial network commissioning mode (WiFi-only by default), starts the Matter stack, synchronizes network states, and displays initial status. - -2. **`loop()`**: Handles serial commands from the user and allows the Matter stack to process events. - -3. **Serial Command Handlers**: - - `handleSerialCommand()`: Routes commands to appropriate handlers - - `toggleWiFiCommissioning()`: Enables/disables WiFi commissioning - - `toggleThreadCommissioning()`: Enables/disables Thread commissioning - - `setWiFiOnlyMode()`: Sets WiFi-only commissioning mode - - `setThreadOnlyMode()`: Sets Thread-only commissioning mode - - `setBothNetworksMode()`: Enables both WiFi and Thread commissioning - - `setNoNetworksMode()`: Disables all network commissioning - - `resetToFactory()`: Performs factory reset (decommission and restart) - -4. **Utility Functions**: - - `syncNetworkStates()`: Synchronizes local state variables with actual API state - - `printNetworkStatus()`: Displays current network commissioning status - - `printCommands()`: Displays available serial commands - -5. **Event Callback**: - - `onMatterEvent()`: Handles Matter events such as commissioning completion, session start/stop, WiFi/Thread connectivity changes, and CHIPoBLE connection events - -## Network Commissioning Modes - -The example supports the following network commissioning modes: - -- **WiFi-only**: Only WiFi networks are available for commissioning -- **Thread-only**: Only Thread networks are available for commissioning -- **Both networks**: Both WiFi and Thread networks are available for commissioning -- **No networks**: All network commissioning is disabled (device cannot be commissioned via networks) - -## Troubleshooting - -- **Device not visible during commissioning**: Ensure network commissioning is enabled for the desired network type (WiFi or Thread). Check the network status using the 's' command -- **WiFi commissioning not supported**: This message appears if WiFi station support is not compiled into the Matter library for your board -- **Thread commissioning not supported**: This message appears if Thread support is not compiled into the Matter library for your board -- **Commands not working**: Ensure you're typing commands in the Serial Monitor (not Serial Plotter) and that the baud rate is set to 115200 -- **State mismatch warnings**: If you see state mismatch warnings, the API has been synchronized to match the actual state. This is normal and handled automatically -- **Failed to commission**: Try changing the network commissioning mode (e.g., switch from Thread-only to WiFi-only) and attempt commissioning again. You can also use the 'r' command to factory reset -- **No serial output**: Check baudrate (115200) and USB connection - -## License - -This example is licensed under the Apache License, Version 2.0. - From 2d7f20ca8ae7a7d1daeda68435d31efa37444f98 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Wed, 5 Nov 2025 11:47:17 +0000 Subject: [PATCH 09/10] ci(pre-commit): Apply automatic fixes --- .../Matter/examples/MatterColorLight/README.md | 4 ++-- .../Matter/examples/MatterCommissionTest/README.md | 1 - .../Matter/examples/MatterComposedLights/README.md | 1 - .../Matter/examples/MatterContactSensor/README.md | 1 - .../Matter/examples/MatterDimmableLight/README.md | 1 - .../examples/MatterEnhancedColorLight/README.md | 1 - libraries/Matter/examples/MatterEvents/README.md | 1 - libraries/Matter/examples/MatterFan/README.md | 1 - .../Matter/examples/MatterHumiditySensor/README.md | 1 - .../MatterLambdaSingleCallbackManyEPs/README.md | 1 - libraries/Matter/examples/MatterMinimum/README.md | 1 - .../Matter/examples/MatterOccupancySensor/README.md | 13 ++++++------- .../Matter/examples/MatterOnIdentify/README.md | 1 - .../Matter/examples/MatterOnOffLight/README.md | 1 - .../Matter/examples/MatterOnOffPlugin/README.md | 1 - .../Matter/examples/MatterPressureSensor/README.md | 1 - .../Matter/examples/MatterSmartButton/README.md | 1 - .../examples/MatterTemperatureLight/README.md | 1 - .../examples/MatterTemperatureSensor/README.md | 1 - .../Matter/examples/MatterThermostat/README.md | 1 - 20 files changed, 8 insertions(+), 27 deletions(-) diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 2a860a58c11..6e5a50e56a2 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -105,7 +105,7 @@ Matter Node is commissioned and connected to the network. Ready for use. ## Using the Device -### Manual Control +### Manual Control The user button (BOOT button by default) provides manual control: @@ -161,4 +161,4 @@ The MatterColorLight example consists of the following main components: ## License -This example is licensed under the Apache License, Version 2.0. \ No newline at end of file +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md index 0d3dc9ae0e2..c43130b6075 100644 --- a/libraries/Matter/examples/MatterCommissionTest/README.md +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -149,4 +149,3 @@ The MatterCommissionTest example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterComposedLights/README.md b/libraries/Matter/examples/MatterComposedLights/README.md index d1a6d218307..3a652a5a544 100644 --- a/libraries/Matter/examples/MatterComposedLights/README.md +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -173,4 +173,3 @@ The MatterComposedLights example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterContactSensor/README.md b/libraries/Matter/examples/MatterContactSensor/README.md index b17bd95e63c..87e4817a424 100644 --- a/libraries/Matter/examples/MatterContactSensor/README.md +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -170,4 +170,3 @@ The MatterContactSensor example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterDimmableLight/README.md b/libraries/Matter/examples/MatterDimmableLight/README.md index a4511d62b37..47060a25355 100644 --- a/libraries/Matter/examples/MatterDimmableLight/README.md +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -168,4 +168,3 @@ The MatterDimmableLight example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterEnhancedColorLight/README.md b/libraries/Matter/examples/MatterEnhancedColorLight/README.md index 557eac162d4..d6a9e381d53 100644 --- a/libraries/Matter/examples/MatterEnhancedColorLight/README.md +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -175,4 +175,3 @@ The MatterEnhancedColorLight example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterEvents/README.md b/libraries/Matter/examples/MatterEvents/README.md index b4aeaac6854..86e15647d42 100644 --- a/libraries/Matter/examples/MatterEvents/README.md +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -179,4 +179,3 @@ The MatterEvents example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterFan/README.md b/libraries/Matter/examples/MatterFan/README.md index c431d8ecb01..9a87ab8f779 100644 --- a/libraries/Matter/examples/MatterFan/README.md +++ b/libraries/Matter/examples/MatterFan/README.md @@ -192,4 +192,3 @@ The MatterFan example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterHumiditySensor/README.md b/libraries/Matter/examples/MatterHumiditySensor/README.md index 865339121b3..d9c5e6f1ed7 100644 --- a/libraries/Matter/examples/MatterHumiditySensor/README.md +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -187,4 +187,3 @@ The MatterHumiditySensor example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md index 21013d89efc..9bd2ca8565d 100644 --- a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -203,4 +203,3 @@ The MatterLambdaSingleCallbackManyEPs example consists of the following main com ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterMinimum/README.md b/libraries/Matter/examples/MatterMinimum/README.md index e1e74905363..187c80cb661 100644 --- a/libraries/Matter/examples/MatterMinimum/README.md +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -169,4 +169,3 @@ This minimal example can be extended with additional features: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterOccupancySensor/README.md b/libraries/Matter/examples/MatterOccupancySensor/README.md index 8e54ac261e5..4a5280364c8 100644 --- a/libraries/Matter/examples/MatterOccupancySensor/README.md +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -151,10 +151,10 @@ const uint8_t pirPin = 4; // Change this to your PIR sensor pin void setup() { // ... existing code ... pinMode(buttonPin, INPUT_PULLUP); - + // Initialize PIR sensor pin pinMode(pirPin, INPUT); - + // ... rest of setup code ... } ``` @@ -179,9 +179,9 @@ bool simulatedHWOccupancySensor() { static bool lastState = false; static uint32_t lastChangeTime = 0; const uint32_t debounceTime = 100; // 100ms debounce - + bool currentState = digitalRead(pirPin) == HIGH; - + // Only update if state has changed and debounce time has passed if (currentState != lastState) { if (millis() - lastChangeTime > debounceTime) { @@ -190,7 +190,7 @@ bool simulatedHWOccupancySensor() { Serial.printf("Occupancy state changed: %s\r\n", currentState ? "OCCUPIED" : "UNOCCUPIED"); } } - + return lastState; } ``` @@ -251,7 +251,7 @@ The MatterOccupancySensor example consists of the following main components: - **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured - **Occupancy readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization - **State not changing**: The simulated sensor toggles every 2 minutes (120000 ms). If you're using a real sensor, ensure it's properly connected and reading correctly -- **PIR sensor not detecting motion**: +- **PIR sensor not detecting motion**: - Verify PIR sensor wiring (VCC, GND, OUT connections) - Check if PIR sensor requires 5V or 3.3V power (some PIR sensors need 5V) - Allow 30-60 seconds for PIR sensor to stabilize after power-on @@ -265,4 +265,3 @@ The MatterOccupancySensor example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterOnIdentify/README.md b/libraries/Matter/examples/MatterOnIdentify/README.md index 4122b07d268..1795d629048 100644 --- a/libraries/Matter/examples/MatterOnIdentify/README.md +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -211,4 +211,3 @@ The MatterOnIdentify example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterOnOffLight/README.md b/libraries/Matter/examples/MatterOnOffLight/README.md index 998fd10d708..00d1520a6cc 100644 --- a/libraries/Matter/examples/MatterOnOffLight/README.md +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -179,4 +179,3 @@ The MatterOnOffLight example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterOnOffPlugin/README.md b/libraries/Matter/examples/MatterOnOffPlugin/README.md index 94757495c97..dcb48b4c795 100644 --- a/libraries/Matter/examples/MatterOnOffPlugin/README.md +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -196,4 +196,3 @@ The MatterOnOffPlugin example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterPressureSensor/README.md b/libraries/Matter/examples/MatterPressureSensor/README.md index 32c9ac1d727..0a48ede2f66 100644 --- a/libraries/Matter/examples/MatterPressureSensor/README.md +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -189,4 +189,3 @@ The MatterPressureSensor example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterSmartButton/README.md b/libraries/Matter/examples/MatterSmartButton/README.md index 6a08e04f819..cb361020ae6 100644 --- a/libraries/Matter/examples/MatterSmartButton/README.md +++ b/libraries/Matter/examples/MatterSmartButton/README.md @@ -173,4 +173,3 @@ The MatterSmartButton example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterTemperatureLight/README.md b/libraries/Matter/examples/MatterTemperatureLight/README.md index 0cc2f6b8007..55bdb176542 100644 --- a/libraries/Matter/examples/MatterTemperatureLight/README.md +++ b/libraries/Matter/examples/MatterTemperatureLight/README.md @@ -205,4 +205,3 @@ The MatterTemperatureLight example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterTemperatureSensor/README.md b/libraries/Matter/examples/MatterTemperatureSensor/README.md index f2fd82b985c..32c8e44f192 100644 --- a/libraries/Matter/examples/MatterTemperatureSensor/README.md +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -204,4 +204,3 @@ The MatterTemperatureSensor example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - diff --git a/libraries/Matter/examples/MatterThermostat/README.md b/libraries/Matter/examples/MatterThermostat/README.md index 57f33130411..318d262e594 100644 --- a/libraries/Matter/examples/MatterThermostat/README.md +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -228,4 +228,3 @@ The MatterThermostat example consists of the following main components: ## License This example is licensed under the Apache License, Version 2.0. - From 2334eb4a9baef9f0add078d95526802a245c2fd9 Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Date: Wed, 5 Nov 2025 09:03:19 -0300 Subject: [PATCH 10/10] fix(pre-commit): Fix spelling --- .../examples/MatterColorLight/README.md | 26 ++++++++-------- .../examples/MatterCommissionTest/README.md | 26 ++++++++-------- .../examples/MatterComposedLights/README.md | 26 ++++++++-------- .../examples/MatterContactSensor/README.md | 26 ++++++++-------- .../examples/MatterDimmableLight/README.md | 26 ++++++++-------- .../MatterEnhancedColorLight/README.md | 26 ++++++++-------- .../Matter/examples/MatterEvents/README.md | 30 +++++++++---------- libraries/Matter/examples/MatterFan/README.md | 28 ++++++++--------- .../examples/MatterHumiditySensor/README.md | 28 +++++++++-------- .../README.md | 26 ++++++++-------- .../Matter/examples/MatterMinimum/README.md | 26 ++++++++-------- .../examples/MatterOccupancySensor/README.md | 30 +++++++++---------- .../examples/MatterOnIdentify/README.md | 30 +++++++++---------- .../examples/MatterOnOffLight/README.md | 26 ++++++++-------- .../examples/MatterOnOffPlugin/README.md | 30 +++++++++---------- .../examples/MatterPressureSensor/README.md | 26 ++++++++-------- .../examples/MatterSmartButton/README.md | 28 ++++++++--------- .../examples/MatterTemperatureLight/README.md | 26 ++++++++-------- .../MatterTemperatureSensor/README.md | 26 ++++++++-------- .../examples/MatterThermostat/README.md | 26 ++++++++-------- .../examples/MatterThreadLight/README.md | 24 +++++++-------- 21 files changed, 284 insertions(+), 282 deletions(-) diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md index 6e5a50e56a2..03a5928cd27 100644 --- a/libraries/Matter/examples/MatterColorLight/README.md +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | RGB LED | Status | | --- | ---- | ------ | ----------------- | ------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a color light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - RGB color control with HSV color model - State persistence using `Preferences` library - Button control for toggling light and factory reset @@ -52,16 +52,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in RGB LED): @@ -83,12 +83,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -145,7 +145,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterColorLight example consists of the following main components: -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. +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. 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. 3. **Callbacks**: - `setLightState()`: Controls the physical RGB LED. @@ -154,7 +154,7 @@ The MatterColorLight example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **RGB LED not responding**: Verify pin configurations and connections - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md index c43130b6075..52b2b1eb8e6 100644 --- a/libraries/Matter/examples/MatterCommissionTest/README.md +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device connection to smart home ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device connection to smart home ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an on/off light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Matter commissioning via QR code or manual pairing code - Automatic decommissioning after 30 seconds for continuous testing - Integration with Apple HomeKit, Amazon Alexa, and Google Home @@ -43,16 +43,16 @@ The application showcases Matter commissioning, device connection to smart home 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` ## Building and Flashing @@ -64,12 +64,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -136,12 +136,12 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterCommissionTest example consists of the following main components: -1. **`setup()`**: Configures WiFi (if needed), initializes the Matter On/Off Light endpoint, and starts the Matter stack. +1. **`setup()`**: Configures Wi-Fi (if needed), initializes the Matter On/Off Light endpoint, and starts the Matter stack. 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. ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection - **Device keeps decommissioning**: This is expected behavior - the device automatically decommissions after 30 seconds to allow continuous testing diff --git a/libraries/Matter/examples/MatterComposedLights/README.md b/libraries/Matter/examples/MatterComposedLights/README.md index 3a652a5a544..cea56d0151a 100644 --- a/libraries/Matter/examples/MatterComposedLights/README.md +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, a single Matter node containing ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,9 +17,9 @@ The application showcases Matter commissioning, a single Matter node containing ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features @@ -28,7 +28,7 @@ The application showcases Matter commissioning, a single Matter node containing - Light #1: Simple On/Off Light - Light #2: Dimmable Light (on/off with brightness control) - Light #3: Color Light (RGB color control) -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Button control for factory reset (decommission) - Matter commissioning via QR code or manual pairing code - Integration with Apple HomeKit, Amazon Alexa, and Google Home @@ -52,16 +52,16 @@ The application showcases Matter commissioning, a single Matter node containing 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -79,12 +79,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -156,7 +156,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterComposedLights example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up three Matter endpoints (OnOffLight, DimmableLight, ColorLight), and registers callbacks for state changes. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up three Matter endpoints (OnOffLight, DimmableLight, ColorLight), and registers callbacks for state changes. 2. **`loop()`**: Checks the Matter commissioning state, displays the state of all three lights every 5 seconds, handles button input for factory reset, and allows the Matter stack to process events. 3. **Callbacks**: - `setLightOnOff1()`: Handles on/off state changes for Light #1. @@ -165,7 +165,7 @@ The MatterComposedLights example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Only one or two lights appear**: Some smart home platforms may group or display lights differently. Check your app's device list - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterContactSensor/README.md b/libraries/Matter/examples/MatterContactSensor/README.md index 87e4817a424..3f7e73b4788 100644 --- a/libraries/Matter/examples/MatterContactSensor/README.md +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status | | --- | ---- | ------ | ----------------- | --- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a contact sensor device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Contact state indication using LED (ON = Closed, OFF = Open) - Automatic simulation of contact state changes every 20 seconds - Button control for toggling contact state and factory reset @@ -51,16 +51,16 @@ The application showcases Matter commissioning, device control via smart home ec 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in LED): @@ -83,12 +83,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -155,13 +155,13 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterContactSensor example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter Contact Sensor endpoint with initial state (Open), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter Contact Sensor endpoint with initial state (Open), and waits for Matter commissioning. 2. **`loop()`**: Handles button input for toggling contact state and factory reset, and automatically simulates contact state changes every 20 seconds. 3. **`simulatedHWContactSensor()`**: Simulates a hardware contact sensor by toggling the contact state every 20 seconds. ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **LED not responding**: Verify pin configurations and connections - **Contact sensor state not updating**: Check Serial Monitor output to verify state changes are being processed - **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 erase_flash` diff --git a/libraries/Matter/examples/MatterDimmableLight/README.md b/libraries/Matter/examples/MatterDimmableLight/README.md index 47060a25355..0879ae2171d 100644 --- a/libraries/Matter/examples/MatterDimmableLight/README.md +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status | | --- | ---- | ------ | ----------------- | --- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a dimmable light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Brightness control (0-255 levels) - State persistence using `Preferences` library - Button control for toggling light and factory reset @@ -52,16 +52,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in LED): @@ -84,12 +84,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -151,7 +151,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterDimmableLight example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter endpoint, restores the last known state (on/off and brightness) from `Preferences`, and registers callbacks for state changes. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter endpoint, restores the last known state (on/off and brightness) from `Preferences`, and registers callbacks for state changes. 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. 3. **Callbacks**: - `setLightState()`: Controls the physical LED with brightness level (supports both RGB LED and regular LED with PWM). @@ -160,7 +160,7 @@ The MatterDimmableLight example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **LED not responding or brightness not working**: Verify pin configurations and connections. For non-RGB LEDs, ensure the pin supports PWM (analogWrite) - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterEnhancedColorLight/README.md b/libraries/Matter/examples/MatterEnhancedColorLight/README.md index d6a9e381d53..59ddc3a2166 100644 --- a/libraries/Matter/examples/MatterEnhancedColorLight/README.md +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | RGB LED | Status | | --- | ---- | ------ | ----------------- | ------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an enhanced color light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - RGB color control with HSV color model - Color temperature control (warm to cool white) - Brightness control (0-255 levels) @@ -54,16 +54,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in RGB LED): @@ -86,12 +86,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -155,7 +155,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterEnhancedColorLight example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter endpoint, restores the last known state (on/off and HSV color) from `Preferences`, and registers callbacks for state changes. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter endpoint, restores the last known state (on/off and HSV color) from `Preferences`, and registers callbacks for state changes. 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. 3. **Callbacks**: - `setLightState()`: Controls the physical RGB LED with state, HSV color, brightness, and color temperature parameters. @@ -166,7 +166,7 @@ The MatterEnhancedColorLight example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **RGB LED not responding**: Verify pin configurations and connections - **Color temperature not working**: Verify that the color temperature callback is properly handling HSV conversion - **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 erase_flash` diff --git a/libraries/Matter/examples/MatterEvents/README.md b/libraries/Matter/examples/MatterEvents/README.md index 86e15647d42..724e3e73cdb 100644 --- a/libraries/Matter/examples/MatterEvents/README.md +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -5,7 +5,7 @@ The application showcases Matter event handling, commissioning, and automatic de ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,16 +17,16 @@ The application showcases Matter event handling, commissioning, and automatic de ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation with comprehensive event monitoring -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Event callback handler that displays all Matter events to Serial Monitor -- Monitors connectivity changes (WiFi, Thread, Internet, IPv4/IPv6) +- Monitors connectivity changes (Wi-Fi, Thread, Internet, IPv4/IPv6) - Tracks commissioning lifecycle events - Monitors fabric management events - Tracks BLE/CHIPoBLE events @@ -46,16 +46,16 @@ The application showcases Matter event handling, commissioning, and automatic de 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` ## Building and Flashing @@ -67,12 +67,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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 and displays Matter events: +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 and displays Matter events: ``` Connecting to your-wifi-ssid ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Starting Matter Commission Test... @@ -108,7 +108,7 @@ Matter Node is decommissioned. Commissioning widget shall start over. The example continuously monitors and displays Matter events to the Serial Monitor. This includes: -- **Connectivity Events**: WiFi, Thread, Internet connectivity changes, IP address assignments +- **Connectivity Events**: Wi-Fi, Thread, Internet connectivity changes, IP address assignments - **Commissioning Events**: Commissioning session start/stop, commissioning window open/close, commissioning complete - **Fabric Events**: Fabric committed, updated, removed - **BLE Events**: CHIPoBLE connection established/closed, advertising changes @@ -164,13 +164,13 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterEvents example consists of the following main components: -1. **`setup()`**: Initializes Serial communication, configures WiFi (if needed), sets up the Matter On/Off Light endpoint, registers the Matter event callback handler, and starts the Matter stack. +1. **`setup()`**: Initializes Serial communication, configures Wi-Fi (if needed), sets up the Matter On/Off Light endpoint, registers the Matter event callback handler, and starts the Matter stack. 2. **`loop()`**: Checks the Matter commissioning state, displays pairing information when not commissioned, waits for commissioning, and then automatically decommissions after 60 seconds to repeat the cycle. 3. **`onMatterEvent()`**: Comprehensive event callback handler that processes and displays all Matter events, including connectivity changes, commissioning events, fabric management, BLE events, and system events. ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **No events displayed**: Verify that the event callback is properly registered using `Matter.onEvent()` - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterFan/README.md b/libraries/Matter/examples/MatterFan/README.md index 9a87ab8f779..89889ace3d6 100644 --- a/libraries/Matter/examples/MatterFan/README.md +++ b/libraries/Matter/examples/MatterFan/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | PWM Pin | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | PWM Pin | Status | | --- | ---- | ------ | ----------------- | ------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a fan device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - On/Off control - Speed control (0-100% in steps of 10%) - Fan modes (OFF, ON, SMART, HIGH) @@ -56,16 +56,16 @@ The application showcases Matter commissioning, device control via smart home ec 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **DC Motor PWM pin configuration** (if not using built-in RGB LED): @@ -94,12 +94,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -172,17 +172,17 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterFan example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, analog input, PWM output), configures WiFi (if needed), sets up the Matter Fan endpoint with initial state (OFF, 0% speed), and registers callbacks for state changes. +1. **`setup()`**: Initializes hardware (button, analog input, PWM output), configures Wi-Fi (if needed), sets up the Matter Fan endpoint with initial state (OFF, 0% speed), and registers callbacks for state changes. 2. **`loop()`**: Checks the Matter commissioning state, handles button input for toggling the fan and factory reset, reads analog input to adjust fan speed, and allows the Matter stack to process events. 3. **Callbacks**: - - `onChangeSpeedPercent()`: Handles speed percent changes (0-100%). Automatically turns fan on/off based on speed. + - `onChangeSpeedPercent()`: Handles speed percentage changes (0% to 100%). Automatically turns fan on/off based on speed. - `onChangeMode()`: Handles fan mode changes (OFF, ON, SMART, HIGH). Automatically sets speed to 50% when switching from OFF to another mode. - `onChange()`: Generic callback that controls the DC motor via PWM and reports the current state. - `fanDCMotorDrive()`: Drives the DC motor (or simulates it with RGB LED brightness) based on fan state and speed. ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Fan speed not responding**: Verify PWM pin configuration and connections. For DC motor control, ensure the pin supports PWM output - **Analog input not working**: Verify analog pin configuration and that the input voltage is within the ESP32's ADC range (0-3.3V typically) - **Speed changes not synchronized**: The analog input is read continuously, and speed updates only when the value changes by a step (0-9 steps mapped to 10-100%) diff --git a/libraries/Matter/examples/MatterHumiditySensor/README.md b/libraries/Matter/examples/MatterHumiditySensor/README.md index d9c5e6f1ed7..940516a2194 100644 --- a/libraries/Matter/examples/MatterHumiditySensor/README.md +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, sensor data reporting to smart h ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a humidity sensor device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Humidity measurement reporting (0-100%) - Automatic simulation of humidity readings (10% to 30% range) - Periodic sensor updates every 5 seconds @@ -51,16 +51,16 @@ The application showcases Matter commissioning, sensor data reporting to smart h 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -81,12 +81,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -172,15 +172,17 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterHumiditySensor example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Humidity Sensor endpoint with initial value (95%), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Humidity Sensor endpoint with initial value (95%), and waits for Matter commissioning. 2. **`loop()`**: Displays the current humidity value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. 3. **`getSimulatedHumidity()`**: Simulates a hardware humidity sensor by cycling through values from 10% to 30% in 0.5% steps. Replace this function with your actual sensor reading code. ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Humidity readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization + - **Humidity values out of range**: Ensure humidity values are between 0-100%. The Matter protocol stores values as 1/100th of a percent internally + - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md index 9bd2ca8565d..f31732d66d6 100644 --- a/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, multiple endpoint management, an ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | GPIO Pins | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | GPIO Pins | Status | | --- | ---- | ------ | ----------------- | --------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,16 +17,16 @@ The application showcases Matter commissioning, multiple endpoint management, an ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation with multiple endpoints in a single node - Six on/off light endpoints sharing a single callback function - Lambda function with capture variable for efficient endpoint identification -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Each endpoint has a unique GPIO pin and friendly name - Matter commissioning via QR code or manual pairing code - Integration with Apple HomeKit, Amazon Alexa, and Google Home @@ -62,16 +62,16 @@ uint8_t lightPins[MAX_LIGHT_NUMBER] = {2, 4, 6, 8, 10, 12}; 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **GPIO pin configuration** (optional): @@ -103,12 +103,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -182,7 +182,7 @@ The MatterLambdaSingleCallbackManyEPs example consists of the following main com - `lightPins[]`: Array of GPIO pins for each light - `lightName[]`: Array of friendly names for each light -2. **`setup()`**: Configures WiFi (if needed), initializes all GPIO pins, initializes all Matter endpoints, registers lambda callbacks with capture variables for each endpoint, and starts the Matter stack. +2. **`setup()`**: Configures Wi-Fi (if needed), initializes all GPIO pins, initializes all Matter endpoints, registers lambda callbacks with capture variables for each endpoint, and starts the Matter stack. 3. **`loop()`**: Checks the Matter commissioning state and connection status, displays appropriate messages, and allows the Matter stack to process events. @@ -193,7 +193,7 @@ The MatterLambdaSingleCallbackManyEPs example consists of the following main com ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Only some endpoints appear**: Some smart home platforms may group or display endpoints differently. Check your app's device list - **GPIO pins not responding**: Verify pin configurations match your hardware. Ensure pins are not used by other peripherals - **Failed to commission**: Try erasing the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` diff --git a/libraries/Matter/examples/MatterMinimum/README.md b/libraries/Matter/examples/MatterMinimum/README.md index 187c80cb661..a91fa651954 100644 --- a/libraries/Matter/examples/MatterMinimum/README.md +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -5,7 +5,7 @@ The application showcases the minimal implementation for Matter commissioning an ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status | | --- | ---- | ------ | ----------------- | --- | ------ | | ESP32 | ✅ | ❌ | ❌ | Optional | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Optional | Fully supported | @@ -17,14 +17,14 @@ The application showcases the minimal implementation for Matter commissioning an ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Minimal Matter protocol implementation for an on/off light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Simple on/off control via Matter app - Button control for factory reset (decommission) - Matter commissioning via QR code or manual pairing code @@ -51,16 +51,16 @@ The application showcases the minimal implementation for Matter commissioning an 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in LED): @@ -83,12 +83,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. @@ -142,7 +142,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterMinimum example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (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. +1. **`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. 2. **`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. @@ -160,7 +160,7 @@ This minimal example can be extended with additional features: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **LED not responding**: Verify pin configurations and connections. The LED will only respond to Matter app commands after commissioning - **Failed to commission**: Try erasing the SoC Flash Memory by using `Arduino IDE Menu` -> `Tools` -> `Erase All Flash Before Sketch Upload: "Enabled"` or directly with `esptool.py --port erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterOccupancySensor/README.md b/libraries/Matter/examples/MatterOccupancySensor/README.md index 4a5280364c8..f83dafc4c4f 100644 --- a/libraries/Matter/examples/MatterOccupancySensor/README.md +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, sensor data reporting to smart h ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an occupancy sensor device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Occupancy state reporting (Occupied/Unoccupied) - Automatic simulation of occupancy state changes every 2 minutes - Button control for factory reset (decommission) @@ -51,16 +51,16 @@ The application showcases Matter commissioning, sensor data reporting to smart h 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -84,12 +84,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -130,7 +130,7 @@ Here's a complete example for integrating a simple PIR (Passive Infrared) motion #### Hardware Connections Connect the PIR sensor to your ESP32: -- **PIR VCC** → ESP32 3.3V or 5V (check your PIR sensor specifications) +- **PIR VCC** → ESP32 3.3 V or 5 V (check your PIR sensor specifications) - **PIR GND** → ESP32 GND - **PIR OUT** → ESP32 GPIO pin (e.g., GPIO 4) @@ -240,7 +240,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterOccupancySensor example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Occupancy Sensor endpoint with initial state (unoccupied), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Occupancy Sensor endpoint with initial state (unoccupied), and waits for Matter commissioning. 2. **`loop()`**: Handles button input for factory reset, continuously checks the simulated occupancy sensor and updates the Matter attribute, and allows the Matter stack to process events. @@ -248,12 +248,12 @@ The MatterOccupancySensor example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Occupancy readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization - **State not changing**: The simulated sensor toggles every 2 minutes (120000 ms). If you're using a real sensor, ensure it's properly connected and reading correctly - **PIR sensor not detecting motion**: - Verify PIR sensor wiring (VCC, GND, OUT connections) - - Check if PIR sensor requires 5V or 3.3V power (some PIR sensors need 5V) + - Check if PIR sensor requires 5 V or 3.3 V power (some PIR sensors need 5 V) - Allow 30-60 seconds for PIR sensor to stabilize after power-on - Adjust PIR sensor sensitivity and time delay potentiometers (if available on your sensor) - Ensure the PIR sensor has a clear view of the detection area diff --git a/libraries/Matter/examples/MatterOnIdentify/README.md b/libraries/Matter/examples/MatterOnIdentify/README.md index 1795d629048..06d6732466f 100644 --- a/libraries/Matter/examples/MatterOnIdentify/README.md +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status | | --- | ---- | ------ | ----------------- | --- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an on/off light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - On Identify callback implementation - LED blinks when device is identified - Visual identification feedback (red blinking for RGB LED, toggling for regular LED) - Button control for factory reset (decommission) @@ -52,16 +52,16 @@ The application showcases Matter commissioning, device control via smart home ec 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in LED): @@ -84,12 +84,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. @@ -185,9 +185,9 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterOnIdentify example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), initializes the Matter on/off light endpoint, registers the on/off callback and the Identify callback, and starts the Matter stack. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), initializes the Matter on/off light endpoint, registers the on/off callback and the Identify callback, and starts the Matter stack. -2. **`loop()`**: Handles the Identify blinking logic (if identify flag is active, blinks the LED every 500ms), handles button input for factory reset, and allows the Matter stack to process events. +2. **`loop()`**: Handles the Identify blinking logic (if identify flag is active, blinks the LED every 500 ms), handles button input for factory reset, and allows the Matter stack to process events. 3. **Callbacks**: - `onOffLightCallback()`: Controls the physical LED based on on/off state from Matter controller. @@ -196,11 +196,11 @@ The MatterOnIdentify example consists of the following main components: 4. **Identify Blinking Logic**: - For RGB LEDs: Blinks in red color (brightness 32) when identify is active - For regular LEDs: Toggles on/off when identify is active - - Blinking rate: Every 500ms (determined by the delay in loop) + - Blinking rate: Every 500 ms (determined by the delay in loop) ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **LED not responding**: Verify pin configurations and connections - **Identify feature not working**: Ensure the device is commissioned and you're using a Matter app that supports the Identify cluster. Some apps may not have a visible Identify button - **LED not blinking during identify**: Check Serial Monitor for "Identify Cluster is Active" message. If you don't see it, the Identify command may not be reaching the device diff --git a/libraries/Matter/examples/MatterOnOffLight/README.md b/libraries/Matter/examples/MatterOnOffLight/README.md index 00d1520a6cc..2a2138ca2c7 100644 --- a/libraries/Matter/examples/MatterOnOffLight/README.md +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | LED | Status | | --- | ---- | ------ | ----------------- | --- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an on/off light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Simple on/off control - State persistence using `Preferences` library - Button control for toggling light and factory reset @@ -52,16 +52,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in LED): @@ -84,12 +84,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -160,7 +160,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterOnOffLight example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), initializes `Preferences` library, sets up the Matter endpoint with the last saved state (defaults to ON if not previously saved), registers the callback function, and starts the Matter stack. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), initializes `Preferences` library, sets up the Matter endpoint with the last saved state (defaults to ON if not previously saved), registers the callback function, and starts the Matter stack. 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. @@ -169,7 +169,7 @@ The MatterOnOffLight example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **LED not responding**: Verify pin configurations and connections - **State not persisting**: Check that the `Preferences` library is properly initialized and that flash memory is not corrupted - **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 erase_flash` diff --git a/libraries/Matter/examples/MatterOnOffPlugin/README.md b/libraries/Matter/examples/MatterOnOffPlugin/README.md index dcb48b4c795..70db06ff0fb 100644 --- a/libraries/Matter/examples/MatterOnOffPlugin/README.md +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Relay/LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Relay/LED | Status | | --- | ---- | ------ | ----------------- | --------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for an on/off plugin unit (power relay) device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Simple on/off control for power management - State persistence using `Preferences` library - Button control for factory reset (decommission) @@ -52,16 +52,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Power relay pin configuration** (if not using built-in LED): @@ -85,12 +85,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -131,7 +131,7 @@ The device saves the last known on/off state using the `Preferences` library. Af For production use with a power relay module: 1. **Connect the relay module** to your ESP32: - - Relay VCC → ESP32 3.3V or 5V (check relay module specifications) + - Relay VCC → ESP32 3.3 V or 5 V (check relay module specifications) - Relay GND → ESP32 GND - Relay IN → ESP32 GPIO pin (configured as `onoffPin`) @@ -177,7 +177,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterOnOffPlugin example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, relay/LED pin), configures WiFi (if needed), initializes `Preferences` library, sets up the Matter plugin endpoint with the last saved state (defaults to OFF if not previously saved), registers the callback function, and starts the Matter stack. +1. **`setup()`**: Initializes hardware (button, relay/LED pin), configures Wi-Fi (if needed), initializes `Preferences` library, sets up the Matter plugin endpoint with the last saved state (defaults to OFF if not previously saved), registers the callback function, and starts the Matter stack. 2. **`loop()`**: Checks the Matter commissioning state, handles button input for factory reset, and allows the Matter stack to process events. @@ -186,10 +186,10 @@ The MatterOnOffPlugin example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Relay/LED not responding**: Verify pin configurations and connections. For relay modules, ensure proper power supply and wiring - **State not persisting**: Check that the `Preferences` library is properly initialized and that flash memory is not corrupted -- **Relay not switching**: For relay modules, verify the control signal voltage levels match your relay module requirements (some relays need 5V, others work with 3.3V) +- **Relay not switching**: For relay modules, verify the control signal voltage levels match your relay module requirements (some relays need 5 V, others work with 3.3 V) - **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 erase_flash` - **No serial output**: Check baudrate (115200) and USB connection diff --git a/libraries/Matter/examples/MatterPressureSensor/README.md b/libraries/Matter/examples/MatterPressureSensor/README.md index 0a48ede2f66..d18ab9d5198 100644 --- a/libraries/Matter/examples/MatterPressureSensor/README.md +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, sensor data reporting to smart h ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a pressure sensor device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Pressure measurement reporting in hectopascals (hPa) - Automatic simulation of pressure readings (950-1100 hPa range) - Periodic sensor updates every 5 seconds @@ -51,16 +51,16 @@ The application showcases Matter commissioning, sensor data reporting to smart h 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -81,12 +81,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -171,7 +171,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterPressureSensor example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Pressure Sensor endpoint with initial value (900 hPa), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Pressure Sensor endpoint with initial value (900 hPa), and waits for Matter commissioning. 2. **`loop()`**: Displays the current pressure value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. @@ -179,7 +179,7 @@ The MatterPressureSensor example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Pressure readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization - **Pressure values out of range**: Ensure pressure values are in hectopascals (hPa). The Matter protocol stores values as uint16_t internally. Typical atmospheric pressure ranges from 950-1050 hPa at sea level - **State not changing**: The simulated sensor increases by 10 hPa every 5 seconds. If you're using a real sensor, ensure it's properly connected and reading correctly diff --git a/libraries/Matter/examples/MatterSmartButton/README.md b/libraries/Matter/examples/MatterSmartButton/README.md index cb361020ae6..2928897503f 100644 --- a/libraries/Matter/examples/MatterSmartButton/README.md +++ b/libraries/Matter/examples/MatterSmartButton/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, sending button click events to s ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, sending button click events to s ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a smart button (generic switch) device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Button click event reporting to Matter controller - Button control for triggering events and factory reset - Matter commissioning via QR code or manual pairing code @@ -49,16 +49,16 @@ The application showcases Matter commissioning, sending button click events to s 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -76,12 +76,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -151,18 +151,18 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterSmartButton example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), initializes the Matter Generic Switch endpoint, and starts the Matter stack. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), initializes the Matter Generic Switch endpoint, and starts the Matter stack. 2. **`loop()`**: Checks the Matter commissioning state, handles button input for sending click events and factory reset, and allows the Matter stack to process events. 3. **Button Event Handling**: - - Detects button press and release with debouncing (250ms) + - Detects button press and release with debouncing (250 ms) - Sends click event to Matter controller using `SmartButton.click()` when button is released - Handles long press (>5 seconds) for factory reset ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Button clicks not registering**: Check Serial Monitor for "User button released" messages. Verify button wiring and that debounce time is appropriate - **Automations not triggering**: Ensure the device is commissioned and that automations are properly configured in your Matter app. The button sends events, but automations must be set up in the app - **Button not responding**: Verify button pin configuration and connections. Check that the button is properly connected with pull-up resistor (INPUT_PULLUP mode) diff --git a/libraries/Matter/examples/MatterTemperatureLight/README.md b/libraries/Matter/examples/MatterTemperatureLight/README.md index 55bdb176542..68a05632192 100644 --- a/libraries/Matter/examples/MatterTemperatureLight/README.md +++ b/libraries/Matter/examples/MatterTemperatureLight/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, device control via smart home ec ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | RGB LED | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | RGB LED | Status | | --- | ---- | ------ | ----------------- | ------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Required | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Required | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, device control via smart home ec ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a color temperature light device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Color temperature control (warm white to cool white, 100-500 mireds) - Brightness level control (0-255) - State persistence using `Preferences` library @@ -55,16 +55,16 @@ The application showcases Matter commissioning, device control via smart home ec 3. ESP32 Arduino libraries: - `Matter` - `Preferences` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **LED pin configuration** (if not using built-in RGB LED): @@ -87,12 +87,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -176,7 +176,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterTemperatureLight example consists of the following main components: -1. **`setup()`**: Initializes hardware (button, LED), configures WiFi (if needed), sets up the Matter Color Temperature Light endpoint, restores the last known state from `Preferences` (on/off, brightness, color temperature), and registers callbacks for state changes. +1. **`setup()`**: Initializes hardware (button, LED), configures Wi-Fi (if needed), sets up the Matter Color Temperature Light endpoint, restores the last known state from `Preferences` (on/off, brightness, color temperature), and registers callbacks for state changes. 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. @@ -193,7 +193,7 @@ The MatterTemperatureLight example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **RGB LED not responding**: Verify pin configurations and connections. For RGB LEDs, ensure the board defines `RGB_BUILTIN` or set the pin manually - **LED not showing color temperature correctly**: RGB LED conversion uses `espCTToRgbColor()` function. For regular LEDs, only brightness is controlled via PWM - **Color temperature not changing**: Verify that color temperature is within valid range (100-500 mireds). Check Serial Monitor for callback messages diff --git a/libraries/Matter/examples/MatterTemperatureSensor/README.md b/libraries/Matter/examples/MatterTemperatureSensor/README.md index 32c8e44f192..017f3ee9abc 100644 --- a/libraries/Matter/examples/MatterTemperatureSensor/README.md +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, sensor data reporting to smart h ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, sensor data reporting to smart h ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a temperature sensor device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Temperature measurement reporting in Celsius - Automatic simulation of temperature readings (-10°C to 10°C range) - Periodic sensor updates every 5 seconds @@ -51,16 +51,16 @@ The application showcases Matter commissioning, sensor data reporting to smart h 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -81,12 +81,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -186,7 +186,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterTemperatureSensor example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Temperature Sensor endpoint with initial value (-25°C), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Temperature Sensor endpoint with initial value (-25°C), and waits for Matter commissioning. 2. **`loop()`**: Displays the current temperature value every 5 seconds, updates the sensor reading from the simulated hardware sensor, handles button input for factory reset, and allows the Matter stack to process events. @@ -194,7 +194,7 @@ The MatterTemperatureSensor example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Temperature readings not updating**: Check that the sensor simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization - **Temperature values out of range**: Ensure temperature values are in Celsius. The Matter protocol stores values as int16_t internally (1/100th of a degree Celsius), so -273.15°C (absolute zero) to 327.67°C is the valid range - **State not changing**: The simulated sensor increases by 0.5°C every 5 seconds. If you're using a real sensor, ensure it's properly connected and reading correctly diff --git a/libraries/Matter/examples/MatterThermostat/README.md b/libraries/Matter/examples/MatterThermostat/README.md index 318d262e594..8f0a69abe08 100644 --- a/libraries/Matter/examples/MatterThermostat/README.md +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -5,7 +5,7 @@ The application showcases Matter commissioning, thermostat control via smart hom ## Supported Targets -| SoC | WiFi | Thread | BLE Commissioning | Status | +| SoC | Wi-Fi | Thread | BLE Commissioning | Status | | --- | ---- | ------ | ----------------- | ------ | | ESP32 | ✅ | ❌ | ❌ | Fully supported | | ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | @@ -17,14 +17,14 @@ The application showcases Matter commissioning, thermostat control via smart hom ### Note on Commissioning: -- **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. -- **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. -- **ESP32-C5** 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. +- **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. +- **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. +- **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. ## Features - Matter protocol implementation for a thermostat device -- Support for both WiFi and Thread(*) connectivity +- Support for both Wi-Fi and Thread(*) connectivity - Multiple thermostat modes: OFF, HEAT, COOL, AUTO - Heating and cooling setpoint control - Automatic temperature regulation in AUTO mode @@ -53,16 +53,16 @@ The application showcases Matter commissioning, thermostat control via smart hom 2. Install ESP32 Arduino Core with Matter support 3. ESP32 Arduino libraries: - `Matter` - - `WiFi` (only for ESP32 and ESP32-S2) + - `Wi-Fi` (only for ESP32 and ESP32-S2) ### Configuration Before uploading the sketch, configure the following: -1. **WiFi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): ```cpp - const char *ssid = "your-ssid"; // Change to your WiFi SSID - const char *password = "your-password"; // Change to your WiFi password + const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID + const char *password = "your-password"; // Change to your Wi-Fi password ``` 2. **Button pin configuration** (optional): @@ -83,12 +83,12 @@ Before uploading the sketch, configure the following: ## Expected Output -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: +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 ....... -WiFi connected +Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. @@ -200,7 +200,7 @@ Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon E The MatterThermostat example consists of the following main components: -1. **`setup()`**: Initializes hardware (button), configures WiFi (if needed), sets up the Matter Thermostat endpoint with cooling/heating sequence of operation and AUTO mode enabled, sets initial setpoints (heating: 23.0°C, cooling: 20.0°C) and initial temperature (12.5°C), and waits for Matter commissioning. +1. **`setup()`**: Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Thermostat endpoint with cooling/heating sequence of operation and AUTO mode enabled, sets initial setpoints (heating: 23.0°C, cooling: 20.0°C) and initial temperature (12.5°C), and waits for Matter commissioning. 2. **`loop()`**: Reads serial input for manual temperature setting, simulates heating/cooling systems and temperature changes every 10 seconds, controls heating/cooling based on thermostat mode and setpoints, handles button input for factory reset, and allows the Matter stack to process events. @@ -216,7 +216,7 @@ The MatterThermostat example consists of the following main components: ## Troubleshooting -- **Device not visible during commissioning**: Ensure WiFi or Thread connectivity is properly configured +- **Device not visible during commissioning**: Ensure Wi-Fi or Thread connectivity is properly configured - **Temperature not updating**: Check that the simulation function is being called correctly. For real sensors, verify sensor wiring and library initialization - **Heating/cooling not responding**: Verify that the thermostat mode is set correctly and that setpoints are properly configured - **Setpoints not working**: Ensure cooling setpoint is at least 2.5°C lower than heating setpoint in AUTO mode diff --git a/libraries/Matter/examples/MatterThreadLight/README.md b/libraries/Matter/examples/MatterThreadLight/README.md index 9dea8e7a4c3..3a971b279b5 100644 --- a/libraries/Matter/examples/MatterThreadLight/README.md +++ b/libraries/Matter/examples/MatterThreadLight/README.md @@ -6,7 +6,7 @@ This example demonstrates a Matter Light device that uses Thread network commiss - **Thread-only commissioning**: Device can only be commissioned over Thread network - **On/Off Light control**: Simple light that can be controlled via Matter -- **Automatic fallback**: On non-Thread capable devices, falls back to WiFi +- **Automatic fallback**: On non-Thread capable devices, falls back to Wi-Fi - **Status monitoring**: Displays network and commissioning status - **Decommissioning support**: Long-press boot button to decommission @@ -18,7 +18,7 @@ This example demonstrates a Matter Light device that uses Thread network commiss - **ESP32-C5**: Native Thread support ### Other ESP32 Variants -- **ESP32, ESP32-S2, ESP32-S3, ESP32-C3**: Will automatically fall back to WiFi commissioning +- **ESP32, ESP32-S2, ESP32-S3, ESP32-C3**: Will automatically fall back to Wi-Fi commissioning ## Hardware Setup @@ -72,7 +72,7 @@ Device commissioned: No Device connected: No Thread connected: No Thread commissioning: Enabled -WiFi commissioning: Disabled +Wi-Fi commissioning: Disabled Light state: OFF ================================ ``` @@ -125,9 +125,9 @@ Light ON ### Non-Thread Device Fallback ``` Starting Thread-only Matter Light... -⚠ Thread support not compiled in, using WiFi commissioning +⚠ Thread support not compiled in, using Wi-Fi commissioning Matter Node is not commissioned yet. -WiFi commissioning: Enabled +Wi-Fi commissioning: Enabled ``` ## Troubleshooting @@ -216,23 +216,23 @@ bool isOn = OnOffLight.getOnOff(); OnOffLight.toggle(); ``` -## Thread vs WiFi Comparison +## Thread vs Wi-Fi Comparison -| Feature | Thread | WiFi | +| Feature | Thread | Wi-Fi | |---------|--------|------| | **Power Consumption** | Low | Higher | | **Range** | Mesh network, self-healing | Single point to router | -| **Setup** | Requires Border Router | Direct to WiFi router | -| **Reliability** | High (mesh redundancy) | Depends on WiFi quality | +| **Setup** | Requires Border Router | Direct to Wi-Fi router | +| **Reliability** | High (mesh redundancy) | Depends on Wi-Fi quality | | **Device Limit** | 250+ devices per network | Limited by router | | **Security** | Built-in mesh security | WPA2/WPA3 | ## Related Examples -- **[SimpleNetworkCommissioning](../SimpleNetworkCommissioning/)**: Basic WiFi/Thread selection +- **[SimpleNetworkCommissioning](../SimpleNetworkCommissioning/)**: Basic Wi-Fi/Thread selection - **[MatterNetworkCommissioning](../MatterNetworkCommissioning/)**: Interactive commissioning control -- **[MatterMinimum](../MatterMinimum/)**: Simplest WiFi-only setup -- **[MatterOnOffLight](../MatterOnOffLight/)**: WiFi-based light with persistence +- **[MatterMinimum](../MatterMinimum/)**: Simplest Wi-Fi-only setup +- **[MatterOnOffLight](../MatterOnOffLight/)**: Wi-Fi-based light with persistence ## Further Reading