3.3.7

libraries/Matter/examples/MatterTemperatureLight/MatterTemperatureLight.ino

@@ -0,0 +1,205 @@
+// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Matter Manager
+#include <Matter.h>
+#if !CONFIG_ENABLE_CHIPOBLE
+// if the device can be commissioned using BLE, WiFi is not used - save flash space
+#include <WiFi.h>
+#endif
+#include <Preferences.h>
+
+// List of Matter Endpoints for this Node
+// Color Temperature CW/WW Light Endpoint
+MatterColorTemperatureLight CW_WW_Light;
+
+// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
+#if !CONFIG_ENABLE_CHIPOBLE
+// WiFi is manually set and started
+const char *ssid = "your-ssid";          // Change this to your WiFi SSID
+const char *password = "your-password";  // Change this to your WiFi password
+#endif
+
+// it will keep last OnOff & Brightness state stored, using Preferences
+Preferences matterPref;
+const char *onOffPrefKey = "OnOff";
+const char *brightnessPrefKey = "Brightness";
+const char *temperaturePrefKey = "Temperature";
+
+// set your board RGB LED pin here
+#ifdef RGB_BUILTIN
+const uint8_t ledPin = RGB_BUILTIN;
+#else
+const uint8_t ledPin = 2;  // Set your pin here if your board has not defined LED_BUILTIN
+#warning "Do not forget to set the RGB LED pin"
+#endif
+
+// set your board USER BUTTON pin here
+const uint8_t buttonPin = BOOT_PIN;  // Set your pin here. Using BOOT Button.
+
+// Button control
+uint32_t button_time_stamp = 0;                // debouncing control
+bool button_state = false;                     // false = released | true = pressed
+const uint32_t debouceTime = 250;              // button debouncing time (ms)
+const uint32_t decommissioningTimeout = 5000;  // keep the button pressed for 5s, or longer, to decommission
+
+// Set the RGB LED Light based on the current state of the Color Temperature Light
+bool setLightState(bool state, uint8_t brightness, uint16_t temperature_Mireds) {
+
+  if (state) {
+#ifdef RGB_BUILTIN
+    espRgbColor_t rgb_ct = espCTToRgbColor(temperature_Mireds);
+    // simple intensity correction
+    float brightnessPercent = (float)brightness / MatterColorTemperatureLight::MAX_BRIGHTNESS;
+    rgb_ct.r = brightnessPercent * rgb_ct.r;
+    rgb_ct.g = brightnessPercent * rgb_ct.g;
+    rgb_ct.b = brightnessPercent * rgb_ct.b;
+    // set the RGB LED
+    rgbLedWrite(ledPin, rgb_ct.r, rgb_ct.g, rgb_ct.b);
+#else
+    // No Color RGB LED, just use the brightness to control the LED
+    analogWrite(ledPin, brightness);
+#endif
+  } else {
+#ifndef RGB_BUILTIN
+    // after analogWrite(), it is necessary to set the GPIO to digital mode first
+    pinMode(ledPin, OUTPUT);
+#endif
+    digitalWrite(ledPin, LOW);
+  }
+  // store last Brightness and OnOff state for when the Light is restarted / power goes off
+  matterPref.putUChar(brightnessPrefKey, brightness);
+  matterPref.putBool(onOffPrefKey, state);
+  matterPref.putUShort(temperaturePrefKey, temperature_Mireds);
+  // This callback must return the success state to Matter core
+  return true;
+}
+
+void setup() {
+  // Initialize the USER BUTTON (Boot button) GPIO that will act as a toggle switch
+  pinMode(buttonPin, INPUT_PULLUP);
+  // Initialize the LED (light) GPIO and Matter End Point
+  pinMode(ledPin, OUTPUT);
+
+  Serial.begin(115200);
+
+// CONFIG_ENABLE_CHIPOBLE is enabled when BLE is used to commission the Matter Network
+#if !CONFIG_ENABLE_CHIPOBLE
+  // We start by connecting to a WiFi network
+  Serial.print("Connecting to ");
+  Serial.println(ssid);
+  // Manually connect to WiFi
+  WiFi.begin(ssid, password);
+  // Wait for connection
+  while (WiFi.status() != WL_CONNECTED) {
+    delay(500);
+    Serial.print(".");
+  }
+  Serial.println("\r\nWiFi connected");
+  Serial.println("IP address: ");
+  Serial.println(WiFi.localIP());
+  delay(500);
+#endif
+
+  // Initialize Matter EndPoint
+  matterPref.begin("MatterPrefs", false);
+  // default OnOff state is ON if not stored before
+  bool lastOnOffState = matterPref.getBool(onOffPrefKey, true);
+  // default brightness ~= 6% (15/255)
+  uint8_t lastBrightness = matterPref.getUChar(brightnessPrefKey, 15);
+  // default temperature ~= 454 Mireds (Warm White)
+  uint16_t lastTemperature = matterPref.getUShort(temperaturePrefKey, WARM_WHITE_COLOR_TEMPERATURE.ctMireds);
+  CW_WW_Light.begin(lastOnOffState, lastBrightness, lastTemperature);
+  // set the callback function to handle the Light state change
+  CW_WW_Light.onChange(setLightState);
+
+  // lambda functions are used to set the attribute change callbacks
+  CW_WW_Light.onChangeOnOff([](bool state) {
+    Serial.printf("Light OnOff changed to %s\r\n", state ? "ON" : "OFF");
+    return true;
+  });
+  CW_WW_Light.onChangeBrightness([](uint8_t level) {
+    Serial.printf("Light Brightness changed to %d\r\n", level);
+    return true;
+  });
+  CW_WW_Light.onChangeColorTemperature([](uint16_t temperature) {
+    Serial.printf("Light Color Temperature changed to %d\r\n", temperature);
+    return true;
+  });
+
+  // Matter beginning - Last step, after all EndPoints are initialized
+  Matter.begin();
+  // This may be a restart of a already commissioned Matter accessory
+  if (Matter.isDeviceCommissioned()) {
+    Serial.println("Matter Node is commissioned and connected to the network. Ready for use.");
+    Serial.printf(
+      "Initial state: %s | brightness: %d | Color Temperature: %d mireds \r\n", CW_WW_Light ? "ON" : "OFF", CW_WW_Light.getBrightness(),
+      CW_WW_Light.getColorTemperature()
+    );
+    // configure the Light based on initial on-off state and brightness
+    CW_WW_Light.updateAccessory();
+  }
+}
+
+void loop() {
+  // Check Matter Light Commissioning state, which may change during execution of loop()
+  if (!Matter.isDeviceCommissioned()) {
+    Serial.println("");
+    Serial.println("Matter Node is not commissioned yet.");
+    Serial.println("Initiate the device discovery in your Matter environment.");
+    Serial.println("Commission it to your Matter hub with the manual pairing code or QR code");
+    Serial.printf("Manual pairing code: %s\r\n", Matter.getManualPairingCode().c_str());
+    Serial.printf("QR code URL: %s\r\n", Matter.getOnboardingQRCodeUrl().c_str());
+    // waits for Matter Light Commissioning.
+    uint32_t timeCount = 0;
+    while (!Matter.isDeviceCommissioned()) {
+      delay(100);
+      if ((timeCount++ % 50) == 0) {  // 50*100ms = 5 sec
+        Serial.println("Matter Node not commissioned yet. Waiting for commissioning.");
+      }
+    }
+    Serial.printf(
+      "Initial state: %s | brightness: %d | Color Temperature: %d mireds \r\n", CW_WW_Light ? "ON" : "OFF", CW_WW_Light.getBrightness(),
+      CW_WW_Light.getColorTemperature()
+    );
+    // configure the Light based on initial on-off state and brightness
+    CW_WW_Light.updateAccessory();
+    Serial.println("Matter Node is commissioned and connected to the network. Ready for use.");
+  }
+
+  // A button is also used to control the light
+  // Check if the button has been pressed
+  if (digitalRead(buttonPin) == LOW && !button_state) {
+    // deals with button debouncing
+    button_time_stamp = millis();  // record the time while the button is pressed.
+    button_state = true;           // pressed.
+  }
+
+  // Onboard User Button is used as a Light toggle switch or to decommission it
+  uint32_t time_diff = millis() - button_time_stamp;
+  if (button_state && time_diff > debouceTime && digitalRead(buttonPin) == HIGH) {
+    button_state = false;  // released
+    // Toggle button is released - toggle the light
+    Serial.println("User button released. Toggling Light!");
+    CW_WW_Light.toggle();  // Matter Controller also can see the change
+  }
+
+  // Onboard User Button is kept pressed for longer than 5 seconds in order to decommission matter node
+  if (button_state && time_diff > decommissioningTimeout) {
+    Serial.println("Decommissioning the Light Matter Accessory. It shall be commissioned again.");
+    CW_WW_Light = false;  // turn the light off
+    Matter.decommission();
+    button_time_stamp = millis();  // avoid running decommissining again, reboot takes a second or so
+  }
+}

libraries/Matter/examples/MatterTemperatureLight/README.md

@@ -0,0 +1,217 @@
+# 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 | Supported (Thread only) |
+| 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 using Arduino as an IDF Component and to disable the Matter Wi-Fi station feature.
+- **ESP32-C5** Although it has Wi-Fi 2.4 GHz and 5 GHz support, the ESP32 Arduino Matter Library has been pre compiled using Thread only. In order to configure it for Wi-Fi operation it is necessary to build the project using Arduino as an ESP-IDF component and disable Thread network, keeping only Wi-Fi station.
+
+## 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.
+<!-- vale off -->
+3. Select **"Huge APP (3MB No OTA/1MB SPIFFS)"** from **Tools > Partition Scheme** menu.
+<!-- vale on -->
+4. Enable **"Erase All Flash Before Sketch Upload"** option from **Tools** menu.
+5. Connect your ESP32 board to your computer via USB.
+6. 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 <PORT> erase_flash`
+- **No serial output**: Check baudrate (115200) and USB connection
+
+## Related Documentation
+
+- [Matter Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter.html)
+- [Matter Endpoint Base Class](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/matter_ep.html)
+- [Matter Color Temperature Light Endpoint](https://docs.espressif.com/projects/arduino-esp32/en/latest/matter/ep_color_temperature_light.html)
+
+## License
+
+This example is licensed under the Apache License, Version 2.0.

libraries/Matter/examples/MatterTemperatureLight/ci.yml

@@ -0,0 +1,4 @@
+fqbn_append: PartitionScheme=huge_app
+
+requires:
+  - CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y