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 RGB color control, dimming, and scene management.

Features: * On/off control * Brightness level control (0-100%) * RGB color control * HSV color support * 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 * 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)

Callback Functions

onLightChange

Sets the callback function for light state changes.

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)

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-100, where 0 is off, 100 is full brightness)

This function will return true if successful, false otherwise.

setLightColor (RGB)

Sets the light color using RGB values.

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.

setLightColor (HSV)

Sets the light color using HSV values.

bool setLightColor(espHsvColor_t hsv_color);
  • hsv_color - HSV color structure

This function will return true if successful, false otherwise.

setLight

Sets all light parameters at once.

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-100)

  • red - Red component (0-255)

  • green - Green component (0-255)

  • blue - Blue component (0-255)

This function will return true if successful, false otherwise.

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-100).

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).

Utility Methods

restoreLight

Restores the light to its last known state.

void restoreLight();

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.
 *
 * The example demonstrates how to use Zigbee library to create an end device with
 * color dimmable light end point.
 * 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);

/********************* 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);
}

// 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);

  // Set callback function for light change
  zbColorLight.onLightChange(setRGBLight);

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

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

  // 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);
}