ZigbeeColorDimmableLight

About

The ZigbeeColorDimmableLight class provides an endpoint for color dimmable lights in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for color lighting devices, supporting multiple color modes (RGB/XY, HSV, and Color Temperature), dimming, and scene management.

Features: * On/off control * Brightness level control (0-255) * RGB/XY color control * HSV (Hue/Saturation) color support * Color temperature (mireds) support * Configurable color capabilities (enable/disable color modes) * Separate callbacks for RGB, HSV, and Temperature modes * Automatic color mode switching * Scene and group support * Automatic state restoration * Integration with common endpoint features (binding, OTA, etc.) * Zigbee HA standard compliance

Use Cases: * Smart RGB light bulbs * Color-changing LED strips * Tunable white light bulbs * Full-spectrum color temperature lights * Mood lighting systems * Entertainment lighting * Architectural lighting * Smart home color lighting

API Reference

Constructor

ZigbeeColorDimmableLight

Creates a new Zigbee color dimmable light endpoint.

ZigbeeColorDimmableLight(uint8_t endpoint);

endpoint - Endpoint number (1-254)

Color Capabilities

setLightColorCapabilities

Configures which color modes are supported by the light. Must be called before starting Zigbee. By default, only XY (RGB) mode is enabled.

bool setLightColorCapabilities(uint16_t capabilities);

capabilities - Bit flags indicating supported color modes (can be combined with bitwise OR):
- ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION - Hue/Saturation support
- ZIGBEE_COLOR_CAPABILITY_X_Y - XY (RGB) support
- ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP - Color temperature support
- ZIGBEE_COLOR_CAPABILITY_ENHANCED_HUE - Enhanced hue support
- ZIGBEE_COLOR_CAPABILITY_COLOR_LOOP - Color loop support

Example:

// Enable XY and Temperature modes
light.setLightColorCapabilities(
    ZIGBEE_COLOR_CAPABILITY_X_Y | ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP
);

// Enable all color modes
light.setLightColorCapabilities(
    ZIGBEE_COLOR_CAPABILITY_X_Y |
    ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION |
    ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP
);

This function will return true if successful, false otherwise.

Callback Functions

Callback Type Definitions

For better type safety and readability, typedefs are provided for all callback functions:

typedef void (*ZigbeeColorLightRgbCallback)(bool state, uint8_t red, uint8_t green, uint8_t blue, uint8_t level);
typedef void (*ZigbeeColorLightHsvCallback)(bool state, uint8_t hue, uint8_t saturation, uint8_t value);
typedef void (*ZigbeeColorLightTempCallback)(bool state, uint8_t level, uint16_t color_temperature);

These typedefs can be used instead of raw function pointer syntax for better code clarity.

onLightChange

Deprecated since version This: method is deprecated and will be removed in a future major version. Use onLightChangeRgb() instead.

Sets the legacy callback function for light state changes (RGB mode).

void onLightChange(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t));

callback - Function pointer to the light change callback (state, red, green, blue, level)
- state - Light state (true = on, false = off)
- red - Red component (0-255)
- green - Green component (0-255)
- blue - Blue component (0-255)
- level - Brightness level (0-255)

Note

This method is deprecated. Please use onLightChangeRgb() for RGB/XY mode callbacks.

onLightChangeRgb

Sets the callback function for RGB/XY color mode changes.

void onLightChangeRgb(ZigbeeColorLightRgbCallback callback);
// or using raw function pointer syntax:
void onLightChangeRgb(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t));

callback - Function pointer to the RGB light change callback (state, red, green, blue, level)
- state - Light state (true = on, false = off)
- red - Red component (0-255)
- green - Green component (0-255)
- blue - Blue component (0-255)
- level - Brightness level (0-255)

onLightChangeHsv

Sets the callback function for HSV (Hue/Saturation) color mode changes.

void onLightChangeHsv(ZigbeeColorLightHsvCallback callback);
// or using raw function pointer syntax:
void onLightChangeHsv(void (*callback)(bool, uint8_t, uint8_t, uint8_t));

callback - Function pointer to the HSV light change callback (state, hue, saturation, value)
- state - Light state (true = on, false = off)
- hue - Hue component (0-254)
- saturation - Saturation component (0-254)
- value - Value/brightness component (0-255)

onLightChangeTemp

Sets the callback function for color temperature mode changes.

void onLightChangeTemp(ZigbeeColorLightTempCallback callback);
// or using raw function pointer syntax:
void onLightChangeTemp(void (*callback)(bool, uint8_t, uint16_t));

callback - Function pointer to the temperature light change callback (state, level, temperature_mireds)
- state - Light state (true = on, false = off)
- level - Brightness level (0-255)
- temperature_mireds - Color temperature in mireds (inverse of Kelvin)

Control Methods

setLightState

Sets the light on/off state.

bool setLightState(bool state);

state - Light state (true = on, false = off)

This function will return true if successful, false otherwise.

setLightLevel

Sets the light brightness level.

bool setLightLevel(uint8_t level);

level - Brightness level (0-255, where 0 is off, 255 is full brightness)

This function will return true if successful, false otherwise.

setLightColor (RGB)

Sets the light color using RGB values. Requires ZIGBEE_COLOR_CAPABILITY_X_Y capability to be enabled.

bool setLightColor(uint8_t red, uint8_t green, uint8_t blue);
bool setLightColor(espRgbColor_t rgb_color);

red - Red component (0-255)
green - Green component (0-255)
blue - Blue component (0-255)
rgb_color - RGB color structure

This function will return true if successful, false otherwise. Returns false if XY capability is not enabled.

setLightColor (HSV)

Sets the light color using HSV values. Requires ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION capability to be enabled.

bool setLightColor(espHsvColor_t hsv_color);

hsv_color - HSV color structure

This function will return true if successful, false otherwise. Returns false if HSV capability is not enabled.

setLightColorTemperature

Sets the light color temperature in mireds. Requires ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP capability to be enabled.

bool setLightColorTemperature(uint16_t color_temperature);

color_temperature - Color temperature in mireds (inverse of Kelvin: mireds = 1000000 / Kelvin)

Example:

// Set to 4000K (cool white)
uint16_t mireds = 1000000 / 4000;  // = 250 mireds
light.setLightColorTemperature(mireds);

// Set to 2700K (warm white)
mireds = 1000000 / 2700;  // = 370 mireds
light.setLightColorTemperature(mireds);

This function will return true if successful, false otherwise. Returns false if color temperature capability is not enabled.

setLightColorTemperatureRange

Sets the minimum and maximum color temperature range supported by the hardware.

bool setLightColorTemperatureRange(uint16_t min_temp, uint16_t max_temp);

min_temp - Minimum color temperature in mireds
max_temp - Maximum color temperature in mireds

Example:

// Set range for 2000K (warm) to 6500K (cool)
uint16_t min_mireds = 1000000 / 6500;  // = 154 mireds
uint16_t max_mireds = 1000000 / 2000;  // = 500 mireds
light.setLightColorTemperatureRange(min_mireds, max_mireds);

This function will return true if successful, false otherwise.

setLight

Sets all light parameters at once (RGB mode). Requires ZIGBEE_COLOR_CAPABILITY_X_Y capability to be enabled.

bool setLight(bool state, uint8_t level, uint8_t red, uint8_t green, uint8_t blue);

state - Light state (true/false)
level - Brightness level (0-255)
red - Red component (0-255)
green - Green component (0-255)
blue - Blue component (0-255)

This function will return true if successful, false otherwise. Returns false if XY capability is not enabled.

State Retrieval Methods

getLightState

Gets the current light state.

bool getLightState();

This function will return current light state (true = on, false = off).

getLightLevel

Gets the current brightness level.

uint8_t getLightLevel();

This function will return current brightness level (0-255).

getLightColor

Gets the current RGB color.

espRgbColor_t getLightColor();

This function will return current RGB color structure.

getLightRed

Gets the current red component.

uint8_t getLightRed();

This function will return current red component (0-255).

getLightGreen

Gets the current green component.

uint8_t getLightGreen();

This function will return current green component (0-255).

getLightBlue

Gets the current blue component.

uint8_t getLightBlue();

This function will return current blue component (0-255).

getLightColorTemperature

Gets the current color temperature.

uint16_t getLightColorTemperature();

This function will return current color temperature in mireds.

getLightColorMode

Gets the current active color mode.

uint8_t getLightColorMode();

This function will return current color mode: * ZIGBEE_COLOR_MODE_HUE_SATURATION (0x00) - HSV mode * ZIGBEE_COLOR_MODE_CURRENT_X_Y (0x01) - XY/RGB mode * ZIGBEE_COLOR_MODE_TEMPERATURE (0x02) - Temperature mode

getLightColorHue

Gets the current hue value (HSV mode).

uint8_t getLightColorHue();

This function will return current hue value (0-254).

getLightColorSaturation

Gets the current saturation value (HSV mode).

uint8_t getLightColorSaturation();

This function will return current saturation value (0-254).

getLightColorCapabilities

Gets the currently configured color capabilities.

uint16_t getLightColorCapabilities();

This function will return the current color capabilities bit flags.

Utility Methods

restoreLight

Restores the light to its last known state. Uses the appropriate callback based on the current color mode.

void restoreLight();

Color Modes and Automatic Behavior

The ZigbeeColorDimmableLight class supports three color modes:

XY/RGB Mode (ZIGBEE_COLOR_MODE_CURRENT_X_Y) - Uses X/Y coordinates for color representation, internally converted to RGB
HSV Mode (ZIGBEE_COLOR_MODE_HUE_SATURATION) - Uses Hue and Saturation values directly, without RGB conversion
Temperature Mode (ZIGBEE_COLOR_MODE_TEMPERATURE) - Uses color temperature in mireds

Automatic Mode Switching:

The color mode is automatically updated based on which attributes are set:

Setting RGB colors via setLight() or setLightColor() (RGB) → switches to XY mode
Setting HSV colors via setLightColor() (HSV) → switches to HSV mode
Setting temperature via setLightColorTemperature() → switches to Temperature mode
Receiving Zigbee commands for XY/HSV/TEMP attributes → automatically switches to the corresponding mode

Capability Validation:

All set methods validate that the required capability is enabled before allowing the operation:

RGB/XY methods require ZIGBEE_COLOR_CAPABILITY_X_Y
HSV methods require ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION
Temperature methods require ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP

If a capability is not enabled, the method will return false and log an error.

Callback Selection:

The appropriate callback is automatically called based on the current color mode:

RGB/XY mode → onLightChangeRgb() callback
HSV mode → onLightChangeHsv() callback
Temperature mode → onLightChangeTemp() callback

When level or state changes occur, the callback for the current color mode is used automatically.

Note

The legacy onLightChange() callback is deprecated and will be removed in a future major version. Always use the mode-specific callbacks (onLightChangeRgb(), onLightChangeHsv(), or onLightChangeTemp()).

Example

Color Dimmable Light Implementation

// Copyright 2024 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.

/**
 * @brief This example demonstrates Zigbee Color Dimmable light bulb with RGB and Temperature support.
 *
 * The example demonstrates how to use Zigbee library to create an end device with
 * color dimmable light end point supporting both RGB (X/Y) and Color Temperature modes.
 * The light bulb is a Zigbee end device, which is controlled by a Zigbee coordinator.
 *
 * Proper Zigbee mode must be selected in Tools->Zigbee mode
 * and also the correct partition scheme must be selected in Tools->Partition Scheme.
 *
 * Please check the README.md for instructions and more detailed description.
 *
 * Created by Jan Procházka (https://github.com/P-R-O-C-H-Y/)
 */

#ifndef ZIGBEE_MODE_ED
#error "Zigbee end device mode is not selected in Tools->Zigbee mode"
#endif

#include "Zigbee.h"

/* Zigbee color dimmable light configuration */
#define ZIGBEE_RGB_LIGHT_ENDPOINT 10
uint8_t led = RGB_BUILTIN;
uint8_t button = BOOT_PIN;

ZigbeeColorDimmableLight zbColorLight = ZigbeeColorDimmableLight(ZIGBEE_RGB_LIGHT_ENDPOINT);

/********************* Temperature conversion functions **************************/
uint16_t kelvinToMireds(uint16_t kelvin) {
  return 1000000 / kelvin;
}

uint16_t miredsToKelvin(uint16_t mireds) {
  return 1000000 / mireds;
}

/********************* RGB LED functions **************************/
void setRGBLight(bool state, uint8_t red, uint8_t green, uint8_t blue, uint8_t level) {
  if (!state) {
    rgbLedWrite(led, 0, 0, 0);
    return;
  }
  float brightness = (float)level / 255;
  rgbLedWrite(led, red * brightness, green * brightness, blue * brightness);
}

/********************* Temperature LED functions **************************/
void setTempLight(bool state, uint8_t level, uint16_t mireds) {
  if (!state) {
    rgbLedWrite(led, 0, 0, 0);
    return;
  }
  float brightness = (float)level / 255;
  // Convert mireds to color temperature (K) and map to white/yellow
  uint16_t kelvin = miredsToKelvin(mireds);
  uint8_t warm = constrain(map(kelvin, 2000, 6500, 255, 0), 0, 255);
  uint8_t cold = constrain(map(kelvin, 2000, 6500, 0, 255), 0, 255);
  rgbLedWrite(led, warm * brightness, warm * brightness, cold * brightness);
}

// Create a task on identify call to handle the identify function
void identify(uint16_t time) {
  static uint8_t blink = 1;
  log_d("Identify called for %d seconds", time);
  if (time == 0) {
    // If identify time is 0, stop blinking and restore light as it was used for identify
    zbColorLight.restoreLight();
    return;
  }
  rgbLedWrite(led, 255 * blink, 255 * blink, 255 * blink);
  blink = !blink;
}

/********************* Arduino functions **************************/
void setup() {
  Serial.begin(115200);

  // Init RMT and leave light OFF
  rgbLedWrite(led, 0, 0, 0);

  // Init button for factory reset
  pinMode(button, INPUT_PULLUP);

  // Enable both XY (RGB) and Temperature color capabilities
  uint16_t capabilities = ZIGBEE_COLOR_CAPABILITY_X_Y | ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP;
  zbColorLight.setLightColorCapabilities(capabilities);

  // Set callback functions for RGB and Temperature modes
  zbColorLight.onLightChangeRgb(setRGBLight);
  zbColorLight.onLightChangeTemp(setTempLight);

  // Optional: Set callback function for device identify
  zbColorLight.onIdentify(identify);

  // Optional: Set Zigbee device name and model
  zbColorLight.setManufacturerAndModel("Espressif", "ZBColorLightBulb");

  // Set min/max temperature range (High Kelvin -> Low Mireds: Min and Max is switched)
  zbColorLight.setLightColorTemperatureRange(kelvinToMireds(6500), kelvinToMireds(2000));

  // Add endpoint to Zigbee Core
  Serial.println("Adding ZigbeeLight endpoint to Zigbee Core");
  Zigbee.addEndpoint(&zbColorLight);

  // When all EPs are registered, start Zigbee in End Device mode
  if (!Zigbee.begin()) {
    Serial.println("Zigbee failed to start!");
    Serial.println("Rebooting...");
    ESP.restart();
  }
  Serial.println("Connecting to network");
  while (!Zigbee.connected()) {
    Serial.print(".");
    delay(100);
  }
  Serial.println();
}

void loop() {
  // Checking button for factory reset
  if (digitalRead(button) == LOW) {  // Push button pressed
    // Key debounce handling
    delay(100);
    int startTime = millis();
    while (digitalRead(button) == LOW) {
      delay(50);
      if ((millis() - startTime) > 3000) {
        // If key pressed for more than 3secs, factory reset Zigbee and reboot
        Serial.println("Resetting Zigbee to factory and rebooting in 1s.");
        delay(1000);
        Zigbee.factoryReset();
      }
    }
    // Increase blightness by 50 every time the button is pressed
    zbColorLight.setLightLevel(zbColorLight.getLightLevel() + 50);
  }
  delay(100);
}