MatterEnhancedColorLight

About

The MatterEnhancedColorLight class provides an Extended Color Light (0x010D) with RGB (HSV and XY), brightness, and color temperature. Use MatterColorLight when the endpoint must not include color temperature.

Features: * On/off control * RGB color control with HSV color model * Brightness level control (0-255; Matter CurrentLevel uses 1-254, and 255 is the nullable null sentinel) * Color temperature control (100-500 mireds; higher mireds are warmer) * State persistence support * Callback support for all parameter changes * Integration with Home Assistant, Apple Home, Amazon Alexa, and Google Home * Matter standard compliance

Use Cases: * Full-featured RGB smart lights * Advanced color and temperature control * Mood lighting with all features * Entertainment lighting * Circadian lighting with color temperature * Smart home advanced lighting automation

API Reference

Constructor

MatterEnhancedColorLight

Creates a new Matter enhanced color light endpoint.

MatterEnhancedColorLight();

Initialization

begin

Initializes the Matter enhanced color light endpoint with optional initial state, color, brightness, and color temperature.

bool begin(bool initialState = false, espHsvColor_t colorHSV = {21, 216, 25}, uint8_t newBrightness = 25, uint16_t colorTemperature = 454);

• initialState - Initial on/off state (default: false = off)

• colorHSV - Initial HSV color (default: HSV(21, 216, 25) = warm white)

• newBrightness - Initial brightness level (0-255, default: 25 = 10%)

• colorTemperature - Initial color temperature in mireds (100-500, default: 454 = Warm White)

This function will return true if successful, false otherwise.

end

Stops processing Matter light events.

void end();

Constants

MAX_BRIGHTNESS

Maximum brightness value (255).

static const uint8_t MAX_BRIGHTNESS = 255;

MAX_COLOR_TEMPERATURE

Maximum color temperature value in mireds (500 mireds = warm white, about 2000 K).

static const uint16_t MAX_COLOR_TEMPERATURE = 500;

MIN_COLOR_TEMPERATURE

Minimum color temperature value in mireds (100 mireds = cool white, about 10000 K).

static const uint16_t MIN_COLOR_TEMPERATURE = 100;

On/Off Control

setOnOff

Sets the on/off state of the light.

bool setOnOff(bool newState);

getOnOff

Gets the current on/off state.

bool getOnOff();

toggle

Toggles the on/off state.

bool toggle();

Color Control

setColorRGB

Sets the color using RGB values.

bool setColorRGB(espRgbColor_t rgbColor);

getColorRGB

Gets the current color as RGB values.

espRgbColor_t getColorRGB();

setColorHSV

Sets the color using HSV values.

bool setColorHSV(espHsvColor_t hsvColor);

• hsvColor - HSV color structure: hue (0-254, where 254 is 360°), saturation (0-254), and value/brightness (0-254). Do not pass degrees in the 0-360 range.

getColorHSV

Gets the current color as HSV values.

espHsvColor_t getColorHSV();

Brightness Control

setBrightness

Sets the brightness level.

bool setBrightness(uint8_t newBrightness);

getBrightness

Gets the current brightness level.

uint8_t getBrightness();

Color Temperature Control

setColorTemperature

Sets the color temperature.

bool setColorTemperature(uint16_t newTemperature);

• newTemperature - Color temperature in mireds. Values outside 100-500 are clamped. ColorTempPhysicalMin/MaxMireds are advertised as 100/500. Higher mireds are warmer white; lower mireds are cooler white.

getColorTemperature

Gets the current color temperature.

uint16_t getColorTemperature();

Event Handling

onChange

Sets a callback for when any parameter changes.

void onChange(EndPointCB onChangeCB);

The callback signature is:

bool onChangeCallback(bool newState, espHsvColor_t newColor, uint8_t newBrightness, uint16_t newTemperature);

onChangeOnOff

Sets a callback for on/off state changes.

void onChangeOnOff(EndPointOnOffCB onChangeCB);

onChangeBrightness

Sets a callback for brightness changes.

void onChangeBrightness(EndPointBrightnessCB onChangeCB);

onChangeColorHSV

Sets a callback for color changes.

void onChangeColorHSV(EndPointRGBColorCB onChangeCB);

onChangeColorTemperature

Sets a callback for color temperature changes.

void onChangeColorTemperature(EndPointTemperatureCB onChangeCB);

updateAccessory

Updates the physical light state using current Matter internal state.

void updateAccessory();

Operators

bool operator

Returns current on/off state.

operator bool();

Assignment operator

Turns light on or off.

void operator=(bool state);

Example

Enhanced Color Light

// 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 <Arduino.h>
#include <Matter.h>
#include <Preferences.h>

// ESP32-C3/H2/C5: if the node never commissions (usual low-heap symptom), uncomment this.
// The default 8 KB loop stack is reserved from the heap before setup();
// 4 KB is enough for this sketch and frees 4 KB for CHIPoBLE + Wi-Fi.
// SET_LOOP_TASK_STACK_SIZE(4 * 1024);

// List of Matter Endpoints for this Node
// Enhanced Color Light Endpoint
MatterEnhancedColorLight EnhancedColorLight;

// Wi-Fi credentials for this sketch. Fill these in when the board cannot
// commission over BLE (Arduino prebuild on ESP32 / ESP32-S2): the sketch
// joins the AP itself. When Matter commissions over BLE (CHIPoBLE), the
// hub sends SSID and password — leave the placeholders; they are unused.
#define WIFI_SSID     "your-ssid"
#define WIFI_PASSWORD "your-password"

// It will use HSV color to control all Matter Attribute Changes
HsvColor_t currentHSVColor = {0, 0, 0};

// it will keep last OnOff & HSV Color state stored, using Preferences
Preferences matterPref;
const char *onOffPrefKey = "OnOff";
const char *hsvColorPrefKey = "HSV";

// 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 the board has no RGB_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.
MatterButton button;

// Set the RGB LED Light based on the current state of the Enhanced Color Light
bool setLightState(bool state, espHsvColor_t colorHSV, uint8_t brighteness, uint16_t temperature_Mireds) {

  if (state) {
#ifdef RGB_BUILTIN
    // currentHSVColor keeps final color result
    espRgbColor_t rgbColor = espHsvColorToRgbColor(currentHSVColor);
    // set the RGB LED
    rgbLedWrite(ledPin, rgbColor.r, rgbColor.g, rgbColor.b);
#else
    // No Color RGB LED, just use the HSV value (brightness) to control the LED
    analogWrite(ledPin, colorHSV.v);
#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 HSV Color and OnOff state for when the Light is restarted / power goes off
  matterPref.putBool(onOffPrefKey, state);
  matterPref.putUInt(hsvColorPrefKey, currentHSVColor.h << 16 | currentHSVColor.s << 8 | currentHSVColor.v);
  // 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
  button.begin(buttonPin);
  // Initialize the LED (light) GPIO and Matter End Point
  pinMode(ledPin, OUTPUT);

  Serial.begin(115200);

// CONFIG_ENABLE_CHIPOBLE=n: sketch starts Wi-Fi here; with CHIPoBLE the hub delivers credentials.
#if !CONFIG_ENABLE_CHIPOBLE
  matterConnectWiFi(WIFI_SSID, WIFI_PASSWORD);
#endif

  // Initialize Matter EndPoint
  matterPref.begin("MatterPrefs", false);
  // default OnOff state is ON if not stored before
  bool lastOnOffState = matterPref.getBool(onOffPrefKey, true);
  // default HSV color is (21, 216, 25) - Warm White Color at 10% intensity
  uint32_t prefHsvColor = matterPref.getUInt(hsvColorPrefKey, 21 << 16 | 216 << 8 | 25);
  currentHSVColor = {uint8_t(prefHsvColor >> 16), uint8_t(prefHsvColor >> 8), uint8_t(prefHsvColor)};
  EnhancedColorLight.begin(lastOnOffState, currentHSVColor);
  // set the callback function to handle the Light state change
  EnhancedColorLight.onChange(setLightState);

  // lambda functions are used to set the attribute change callbacks
  EnhancedColorLight.onChangeOnOff([](bool state) {
    Serial.printf("Light OnOff changed to %s\r\n", state ? "ON" : "OFF");
    return true;
  });
  EnhancedColorLight.onChangeColorTemperature([](uint16_t colorTemperature) {
    Serial.printf("Light Color Temperature changed to %u\r\n", colorTemperature);
    // get correspondent Hue and Saturation of the color temperature
    HsvColor_t hsvTemperature = espRgbColorToHsvColor(espCTToRgbColor(colorTemperature));
    // keep previous the brightness and just change the Hue and Saturation
    currentHSVColor.h = hsvTemperature.h;
    currentHSVColor.s = hsvTemperature.s;
    return true;
  });
  EnhancedColorLight.onChangeBrightness([](uint8_t brightness) {
    Serial.printf("Light brightness changed to %u\r\n", brightness);
    // change current brightness (HSV value)
    currentHSVColor.v = brightness;
    return true;
  });
  EnhancedColorLight.onChangeColorHSV([](HsvColor_t hsvColor) {
    Serial.printf("Light HSV Color changed to (%u,%u,%u)\r\n", hsvColor.h, hsvColor.s, hsvColor.v);
    // keep the current brightness and just change Hue and Saturation
    currentHSVColor.h = hsvColor.h;
    currentHSVColor.s = hsvColor.s;
    return true;
  });

  // Matter beginning - Last step, after all EndPoints are initialized
  Matter.begin();
  matterWaitUntilReady();
  Serial.printf(
    "Initial state: %s | RGB Color: (%u,%u,%u) \r\n", EnhancedColorLight ? "ON" : "OFF", EnhancedColorLight.getColorRGB().r, EnhancedColorLight.getColorRGB().g,
    EnhancedColorLight.getColorRGB().b
  );
  EnhancedColorLight.updateAccessory();
}

void loop() {
  matterRestartIfNoFabric();

  matterButtonEvent_t ev;
  while ((ev = button.poll()) != MATTER_BUTTON_NONE) {
    if (ev == MATTER_BUTTON_CLICK) {
      Serial.println("User button released. Toggling Light!");
      EnhancedColorLight.toggle();
    } else if (ev == MATTER_BUTTON_LONG_HOLD) {
      Serial.println("Decommissioning the Light Matter Accessory. It shall be commissioned again.");
      EnhancedColorLight = false;
      Matter.decommission();
    }
  }
}