ZigbeeDimmableLight

About

The ZigbeeDimmableLight class provides a dimmable light endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for dimmable lighting control with both on/off and brightness level control.

Features: * On/off control * Brightness level control (0-100%) * State and level change callbacks * Integration with common endpoint features (binding, OTA, etc.) * Zigbee HA standard compliance

Use Cases: * Dimmable smart bulbs * LED strips with brightness control * Any device requiring both on/off and dimming functionality

API Reference

Constructor

ZigbeeDimmableLight

Creates a new Zigbee dimmable light endpoint.

ZigbeeDimmableLight(uint8_t endpoint);
  • endpoint - Endpoint number (1-254)

Light Control

setLightState

Sets only the light state (on or off) without changing the brightness level.

bool setLightState(bool state);
  • state - true to turn on, false to turn off

This function will return true if successful, false otherwise.

setLightLevel

Sets only the brightness level (0-100) without changing the on/off state.

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.

setLight

Sets both the light state and brightness level simultaneously.

bool setLight(bool state, uint8_t level);
  • state - true to turn on, false to turn off

  • level - Brightness level (0-100)

This function will return true if successful, false otherwise.

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

restoreLight

Restores the light state and triggers any registered callbacks.

void restoreLight();

Event Handling

onLightChange

Sets a callback function to be called when the light state or level changes.

void onLightChange(void (*callback)(bool, uint8_t));
  • callback - Function to call when light state or level changes

Callback Parameters: * bool state - New light state (true = on, false = off) * uint8_t level - New brightness level (0-100)

Example

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 Dimmable light bulb.
 *
 * The example demonstrates how to use Zigbee library to create an end device with
 * 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 [FaBjE](https://github.com/FaBjE) based on examples 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 dimmable light configuration */
#define ZIGBEE_LIGHT_ENDPOINT 10
uint8_t led = RGB_BUILTIN;
uint8_t button = BOOT_PIN;

ZigbeeDimmableLight zbDimmableLight = ZigbeeDimmableLight(ZIGBEE_LIGHT_ENDPOINT);

/********************* RGB LED functions **************************/
void setLight(bool state, uint8_t level) {
  if (!state) {
    rgbLedWrite(led, 0, 0, 0);
    return;
  }
  rgbLedWrite(led, level, level, level);
}

// 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
    zbDimmableLight.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
  zbDimmableLight.onLightChange(setLight);

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

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

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

  // 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
    zbDimmableLight.setLightLevel(zbDimmableLight.getLightLevel() + 50);
  }
  delay(100);
}