diff --git a/libraries/Matter/examples/MatterColorLight/README.md b/libraries/Matter/examples/MatterColorLight/README.md new file mode 100644 index 00000000000..03a5928cd27 --- /dev/null +++ b/libraries/Matter/examples/MatterColorLight/README.md @@ -0,0 +1,164 @@ +# 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 | Wi-Fi | 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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ``` 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**. The Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + - `onChangeOnOff()`: Handles on/off state changes. + - `onChangeColorHSV()`: Handles color changes. + +## Troubleshooting + +- **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 + +## License + +This example is licensed under the Apache License, Version 2.0. diff --git a/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino b/libraries/Matter/examples/MatterCommissionTest/MatterCommissionTest.ino index aa593758548..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. Commsssioning widget shall start over."); + Serial.println("Matter Node is decommissioned. Commissioning widget shall start over."); } diff --git a/libraries/Matter/examples/MatterCommissionTest/README.md b/libraries/Matter/examples/MatterCommissionTest/README.md new file mode 100644 index 00000000000..52b2b1eb8e6 --- /dev/null +++ b/libraries/Matter/examples/MatterCommissionTest/README.md @@ -0,0 +1,151 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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 + +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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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. Commissioning 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 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 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 + +## 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..cea56d0151a --- /dev/null +++ b/libraries/Matter/examples/MatterComposedLights/README.md @@ -0,0 +1,175 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + - `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 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 + +## 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..3f7e73b4788 --- /dev/null +++ b/libraries/Matter/examples/MatterContactSensor/README.md @@ -0,0 +1,172 @@ +# 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 | Wi-Fi | 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-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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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 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` +- **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..0879ae2171d --- /dev/null +++ b/libraries/Matter/examples/MatterDimmableLight/README.md @@ -0,0 +1,170 @@ +# 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 | Wi-Fi | 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-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 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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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). + - `onChangeOnOff()`: Handles on/off state changes. + - `onChangeBrightness()`: Handles brightness level changes (0-255). + +## Troubleshooting + +- **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 + +## 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..59ddc3a2166 --- /dev/null +++ b/libraries/Matter/examples/MatterEnhancedColorLight/README.md @@ -0,0 +1,177 @@ +# 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 | Wi-Fi | 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 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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + - `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 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` +- **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..724e3e73cdb --- /dev/null +++ b/libraries/Matter/examples/MatterEvents/README.md @@ -0,0 +1,181 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 Wi-Fi and Thread(*) connectivity +- Event callback handler that displays all Matter events to Serial Monitor +- Monitors connectivity changes (Wi-Fi, 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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 + +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 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 +....... +Wi-Fi 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**: 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 +- **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 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 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 +- **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..89889ace3d6 --- /dev/null +++ b/libraries/Matter/examples/MatterFan/README.md @@ -0,0 +1,194 @@ +# 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 | Wi-Fi | 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-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 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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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 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 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%) +- **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..940516a2194 --- /dev/null +++ b/libraries/Matter/examples/MatterHumiditySensor/README.md @@ -0,0 +1,191 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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 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 + +## 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..f31732d66d6 --- /dev/null +++ b/libraries/Matter/examples/MatterLambdaSingleCallbackManyEPs/README.md @@ -0,0 +1,205 @@ +# 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 | Wi-Fi | 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-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 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 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 +(*) 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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` +- **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..a91fa651954 --- /dev/null +++ b/libraries/Matter/examples/MatterMinimum/README.md @@ -0,0 +1,171 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | LED | Status | +| --- | ---- | ------ | ----------------- | --- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Optional | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Optional | Fully supported | +| ESP32-S3 | ✅ | ❌ | ✅ | Optional | Fully supported | +| ESP32-C3 | ✅ | ❌ | ✅ | Optional | Fully supported | +| ESP32-C5 | ✅ | ❌ | ✅ | Optional | 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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected + +Matter Node is not commissioned yet. +Initiate the device discovery in your Matter environment. +Commission it to your Matter hub with the manual pairing code or QR code +Manual pairing code: 34970112332 +QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00 +``` + +After commissioning, the device will be ready for control via Matter apps. No additional status messages are printed in this minimal example. + +## 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 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. + +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 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 +- **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..f83dafc4c4f --- /dev/null +++ b/libraries/Matter/examples/MatterOccupancySensor/README.md @@ -0,0 +1,267 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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) +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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.3 V or 5 V (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 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. + +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 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 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 + - 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..06d6732466f --- /dev/null +++ b/libraries/Matter/examples/MatterOnIdentify/README.md @@ -0,0 +1,213 @@ +# 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 | Wi-Fi | 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-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 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 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) +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected + +Matter Node is not commissioned yet. +Initiate the device discovery in your Matter environment. +Commission it to your Matter hub with the manual pairing code or QR code +Manual pairing code: 34970112332 +QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00 +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 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 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. + - `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 500 ms (determined by the delay in loop) + +## Troubleshooting + +- **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 +- **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..2a2138ca2c7 --- /dev/null +++ b/libraries/Matter/examples/MatterOnOffLight/README.md @@ -0,0 +1,181 @@ +# 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 | Wi-Fi | 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-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 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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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` +- **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..70db06ff0fb --- /dev/null +++ b/libraries/Matter/examples/MatterOnOffPlugin/README.md @@ -0,0 +1,198 @@ +# 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 | Wi-Fi | 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-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 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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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.3 V or 5 V (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 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. + +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 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 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 + +## 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..d18ab9d5198 --- /dev/null +++ b/libraries/Matter/examples/MatterPressureSensor/README.md @@ -0,0 +1,191 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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 +- **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/MatterSmartButon.ino b/libraries/Matter/examples/MatterSmartButton/MatterSmartButton.ino similarity index 100% rename from libraries/Matter/examples/MatterSmartButon/MatterSmartButon.ino rename to libraries/Matter/examples/MatterSmartButton/MatterSmartButton.ino diff --git a/libraries/Matter/examples/MatterSmartButton/README.md b/libraries/Matter/examples/MatterSmartButton/README.md new file mode 100644 index 00000000000..2928897503f --- /dev/null +++ b/libraries/Matter/examples/MatterSmartButton/README.md @@ -0,0 +1,175 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported | +| 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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 `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. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. The Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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 (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 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) +- **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/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 new file mode 100644 index 00000000000..68a05632192 --- /dev/null +++ b/libraries/Matter/examples/MatterTemperatureLight/README.md @@ -0,0 +1,207 @@ +# 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 | Wi-Fi | 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 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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + ```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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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 +- **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 new file mode 100644 index 00000000000..017f3ee9abc --- /dev/null +++ b/libraries/Matter/examples/MatterTemperatureSensor/README.md @@ -0,0 +1,206 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 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 +- 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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 +- **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..8f0a69abe08 --- /dev/null +++ b/libraries/Matter/examples/MatterThermostat/README.md @@ -0,0 +1,230 @@ +# 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 | Wi-Fi | Thread | BLE Commissioning | Status | +| --- | ---- | ------ | ----------------- | ------ | +| ESP32 | ✅ | ❌ | ❌ | Fully supported | +| 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) | + +### Note on Commissioning: + +- **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 Wi-Fi 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` + - `Wi-Fi` (only for ESP32 and ESP32-S2) + +### Configuration + +Before uploading the sketch, configure the following: + +1. **Wi-Fi credentials** (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2): + ```cpp + 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): + 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 Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning: + +``` +Connecting to your-wifi-ssid +....... +Wi-Fi connected +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 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. + +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 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 +- **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. diff --git a/libraries/Matter/examples/MatterThreadLight/README.md b/libraries/Matter/examples/MatterThreadLight/README.md new file mode 100644 index 00000000000..3a971b279b5 --- /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 Wi-Fi +- **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 Wi-Fi 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 +Wi-Fi 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 Wi-Fi commissioning +Matter Node is not commissioned yet. +Wi-Fi 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 Wi-Fi Comparison + +| Feature | Thread | Wi-Fi | +|---------|--------|------| +| **Power Consumption** | Low | Higher | +| **Range** | Mesh network, self-healing | Single point to router | +| **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 Wi-Fi/Thread selection +- **[MatterNetworkCommissioning](../MatterNetworkCommissioning/)**: Interactive commissioning control +- **[MatterMinimum](../MatterMinimum/)**: Simplest Wi-Fi-only setup +- **[MatterOnOffLight](../MatterOnOffLight/)**: Wi-Fi-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)