Lightbulb Driver

[中文]

The Lightbulb driver component encapsulates several commonly used dimming schemes for bulb lights, using an abstraction layer to manage these schemes, making it easier for developers to integrate into their applications. Currently, all ESP32 series chips are fully supported

Dimming scheme

PWM Dimming scheme

PWM dimming is a technique that controls LED brightness by adjusting the pulse width. The core idea is to vary the duty cycle of the current pulse (i.e., the proportion of high-level time within the entire cycle time). When the duty cycle is high, the LED receives current for a longer duration, resulting in higher brightness; conversely, a low duty cycle shortens the current duration, producing lower brightness.

All ESP chips support PWM output using hardware LEDC driver or MCPWM driver. It is recommended to use the LEDC driver as it supports hardware fading, with configurable frequency and duty cycle, and a maximum resolution of 20 bits. The following types of PWM dimming drivers are currently supported:

RGB + C/W

RGB + CCT/Brightnes

PWM scheme use cases

Use the PWM scheme to light up a 3-channel RGB bulb with PWM frequency set to 4000Hz. Use software color mixing, enable the fade function, and set the power-on color to red.

lightbulb_config_t config = {
    // 1. Select PWM output and configure parameters
    .type = DRIVER_ESP_PWM,
    .driver_conf.pwm.freq_hz = 4000,

    // 2. capability selection: enable/disable according to your needs
    .capability.enable_fade = true,
    .capability.fade_time_ms = 800,
    .capability.enable_lowpower = false,
    /* Enable this feature if your white light output is hardware-controlled independently rather than software color-mixed */
    .capability.enable_hardware_cct = true,
    .capability.enable_status_storage = true,
    /* Configure the LED combination based on your LED aluminum substrate */
    .capability.led_beads = LED_BEADS_3CH_RGB,
    .capability.storage_cb = NULL,
    .capability.sync_change_brightness_value = true,

    // 3. Configure hardware pins for PWM output
    .io_conf.pwm_io.red = 25,
    .io_conf.pwm_io.green = 26,
    .io_conf.pwm_io.blue = 27,

    // 4. Limits parameter
    .external_limit = NULL,

    // 5. Color calibration parameters
    .gamma_conf = NULL,

    // 6. Initialize lighting parameters; if 'on' is set, the lightbulb will light up during driver initialization
    .init_status.mode = WORK_COLOR,
    .init_status.on = true,
    .init_status.hue = 0,
    .init_status.saturation = 100,
    .init_status.value = 100,
};
lightbulb_init(&config);

I2C Dimming Scheme

I2C Dimming : Control commands are sent via the I2C bus to the dimming chip, adjusting the LED brightness by changing the output current of the dimming chip. The I2C bus consists of two lines: the data line (SDA) and the clock line (SCL). All ESP chips support dimming chips using hardware I2C communication. The following dimming chips are currently supported:

SM2135EH

SM2X35EGH (SM2235EGH/SM2335EGH)

BP57x8D (BP5758/BP5758D/BP5768)

BP1658CJ

KP18058

I2C Dimming Use Case

Use the I2C driver to control the BP5758D chip to light up a 5-channel RGBCW bulb. Set the I2C communication rate to 300KHz, with RGB LEDs driven at 50mA and CW LEDs at 30mA. Use software color mixing, enable the fade function, and set the power-on color to red.

lightbulb_config_t config = {
    // 1. Select the required chip and configure parameters. Each chip has different configuration parameters, so please refer carefully to the chip manual.
    .type = DRIVER_BP57x8D,
    .driver_conf.bp57x8d.freq_khz = 300,
    .driver_conf.bp57x8d.enable_iic_queue = true,
    .driver_conf.bp57x8d.iic_clk = 4,
    .driver_conf.bp57x8d.iic_sda = 5,
    .driver_conf.bp57x8d.current = {50, 50, 50, 30, 30},

    // 2. capability selection: enable/disable according to your needs
    .capability.enable_fade = true,
    .capability.fade_time_ms = 800,
    .capability.enable_lowpower = false,

    .capability.enable_status_storage = true,
    .capability.led_beads = LED_BEADS_5CH_RGBCW,
    .capability.storage_cb = NULL,
    .capability.sync_change_brightness_value = true,

    // 3. Configure the hardware pins for the IIC chip
    .io_conf.iic_io.red = OUT3,
    .io_conf.iic_io.green = OUT2,
    .io_conf.iic_io.blue = OUT1,
    .io_conf.iic_io.cold_white = OUT5,
    .io_conf.iic_io.warm_yellow = OUT4,

    // 4. Limits parameter
    .external_limit = NULL,

    // 5. Color calibration parameters
    .gamma_conf = NULL,

    // 6. Initialize lighting parameters; if 'on' is set, the lightbulb will light up during driver initialization
    .init_status.mode = WORK_COLOR,
    .init_status.on = true,
    .init_status.hue = 0,
    .init_status.saturation = 100,
    .init_status.value = 100,
};
lightbulb_init(&config);

Single-wire dimming scheme

A single-wire dimming scheme is a method of controlling LED brightness through a single communication line. The core idea is to adjust LED brightness by sending control signals through a specific communication protocol. This scheme can be implemented on ESP chips using the RMT peripheral or SPI peripheral. SPI is recommended for controlling LED communication. The following LED types are currently supported:

WS2812

WS2812 Use Case

Use the SPI driver to light up 10 WS2812 LEDs, enable the fade function, and set the power-on color to red.

lightbulb_config_t config = {
    // 1. Select WS2812 output and configure parameters
    .type = DRIVER_WS2812,
    .driver_conf.ws2812.led_num = 10,
    .driver_conf.ws2812.ctrl_io = 4,

    // 2. capability selection: enable/disable according to your needs
    .capability.enable_fade = true,
    .capability.fade_time_ms = 800,
    .capability.enable_status_storage = true,

    /* For WS2812, only LED_BEADS_3CH_RGB can be selected */
    .capability.led_beads = LED_BEADS_3CH_RGB,
    .capability.storage_cb = NULL,

    // 4. Limits parameter
    .external_limit = NULL,

    // 5. Color calibration parameters
    .gamma_conf = NULL,

    // 6. Initialize lighting parameters; if 'on' is set, the lightbulb will light up during driver initialization
    .init_status.mode = WORK_COLOR,
    .init_status.on = true,
    .init_status.hue = 0,
    .init_status.saturation = 100,
    .init_status.value = 100,
};
lightbulb_init(&config);

Fade principle

The fade effect in the bulb light component is implemented through software. Each channel records the current output value, target value, step size, and remaining steps. When the API is used to set a color, it updates the target value, step size, step count, and enables a fade timer. This timer triggers a callback every 12ms, where each channel’s steps are checked. As long as there are steps remaining, the current value is adjusted by the step size and updated in the underlying driver. When all channels have reached zero steps, the fade is complete, and the timer is stopped.

Low-power implementation process

To pass certifications like T20 for low power consumption, after optimizing the light board’s power supply, some low-power configurations are needed in the software. Apart from the settings mentioned in the Low-Power Mode Usage Guide the driver logic also requires adjustments. In the lightbulb component, low-power adjustments have been added for both PWM and I2C dimming schemes. The specific logic involves the I2C scheme using the dimming chip’s low-power command to exit or enter low power when switching the light on or off. For the PWM scheme, ESP32 requires power lock management with the APB clock source to prevent flickering—locking power and disabling dynamic frequency scaling when the light is on, and releasing the lock when off, other chips use the XTAL clock source, so no further measures are necessary.

Color calibration scheme

CCT Mode

The calibration for color temperature mode requires configuring the following structure.

union {
    struct {
        uint16_t kelvin_min;
        uint16_t kelvin_max;
    } standard;
    struct {
        lightbulb_cct_mapping_data_t *table;
        int table_size;
    } precise;
} cct_mix_mode;

Standard mode: calibrate the maximum and minimum Kelvin values, use linear interpolation to fill in intermediate values, and then adjust the output ratio of cool and warm LEDs according to the target color temperature.
Precision mode: calibrate the required output ratios of red, green, blue, cool, and warm LEDs at different color temperatures. Use these calibration points to directly output the corresponding ratios. The more calibration points, the more accurate the color temperature.

Color Mode

The calibration for color mode requires configuring the following structure.

union {
    struct {
        lightbulb_color_mapping_data_t *table;
        int table_size;
    } precise;
} color_mix_mode;

Standard Mode: No parameter configuration is required. Internal theoretical algorithms will convert HSV, XYY, and other color models into RGB ratios, and LEDs will light up directly based on this ratio.
Precision Mode: Calibrate colors using the HSV model. Measure the required output ratios of red, green, blue, cool, and warm LEDs for various hues and saturation levels as calibration points. Use linear interpolation to fill in intermediate values and light up the LEDs based on these calibrated ratios.

Power limiting scheme

Power limiting is used to balance and fine-tune the output current of a specific channel or the overall system to meet power requirements.

To limit the overall power, configure the following structure.

typedef struct {
    /* Scale the incoming value
     * range: 10% <= value <= 100%
     * step: 1%
     * default min: 10%
     * default max: 100%
     */
    uint8_t white_max_brightness; /**< Maximum brightness limit for white light output. */
    uint8_t white_min_brightness; /**< Minimum brightness limit for white light output. */
    uint8_t color_max_value;      /**< Maximum value limit for color light output. */
    uint8_t color_min_value;      /**< Minimum value limit for color light output. */

    /* Dynamically adjust the final power
     * range: 100% <= value <= 500%
     * step: 10%
     */
    uint16_t white_max_power;     /**< Maximum power limit for white light output. */
    uint16_t color_max_power;     /**< Maximum power limit for color light output. */
} lightbulb_power_limit_t;

white_max_brightness and white_min_brightness are used in color temperature mode to constrain the brightness parameter set by the color temperature API within these maximum and minimum values.
color_max_value and color_min_value are used in color mode to constrain the value parameter set by the color API within these maximum and minimum values.
white_max_power is used to limit power in color temperature mode. The default value is 100, meaning the maximum output power is half of the full power; if set to 200, it can reach the maximum power of the cool and warm LEDs.
color_max_power is used to limit power in color mode. The default value is 100, meaning the maximum output power is one-third of full power; if set to 300, it can reach the maximum power of the red, green, and blue LEDs.

To limit the power of individual LEDs, configure the following structure:

typedef struct {
    float balance_coefficient[5]; /**< Array of float coefficients for adjusting the intensity of each color channel (R, G, B, C, W).
                                       These coefficients help in achieving the desired color balance for the light output. */

    float curve_coefficient;      /**< Coefficient for gamma correction. This value is used to modify the luminance levels
                                       to suit the non-linear characteristics of human vision, thus improving the overall
                                       visual appearance of the light. */
} lightbulb_gamma_config_t;

balance_coefficient is used to fine-tune the output current of each LED. The final output of the driver will be reduced according to this ratio, with a default value of 1.0, meaning no reduction.
curve_coefficient is used to convert linear changes during fading into curve-based changes.

Note

Modifying balance_coefficient will affect the accuracy of color calibration, so this parameter should be adjusted before performing color calibration. This parameter is especially useful for I2C dimming chips that output current in multiples of 5 or 10; if specific currents are needed, this parameter can be used for adjustment.

API Reference

Header File

components/led/lightbulb_driver/include/lightbulb.h

Functions

esp_err_t lightbulb_init(lightbulb_config_t *config)

Initialize the lightbulb.

Parameters: config – Pointer to the configuration parameters for the lightbulb.
Returns: esp_err_t

esp_err_t lightbulb_deinit(void)

Deinitialize the lightbulb and release resources.

Returns: esp_err_t

esp_err_t lightbulb_set_fade_time(uint32_t fade_time_ms)

Set lightbulb fade time.

Parameters: fade_time_ms – Fade time in milliseconds (ms). Range: 100ms - 3000ms.
Returns: esp_err_t

esp_err_t lightbulb_set_fades_function(bool is_enable)

Enable/Disable the lightbulb fade function.

Parameters: is_enable – A boolean flag indicating whether to enable (true) or disable (false) the fade function.
Returns: esp_err_t

esp_err_t lightbulb_set_storage_function(bool is_enable)

Enable/Disable the lightbulb storage function.

Parameters: is_enable – A boolean flag indicating whether to enable (true) or disable (false) the storage function.
Returns: esp_err_t

esp_err_t lightbulb_update_status(lightbulb_status_t *new_status, bool trigger)

Re-update the lightbulb status.

Parameters

new_status – Pointer to the new status to be applied to the lightbulb.
trigger – A boolean flag indicating whether the update should be triggered immediately.

Returns

esp_err_t

bool lightbulb_get_fades_function_status(void)

Get lightbulb fade function enabled status.

Returns: true if the fade function is enabled.
Returns: false if the fade function is disabled.

esp_err_t lightbulb_hsv2rgb(uint16_t hue, uint8_t saturation, uint8_t value, uint8_t *red, uint8_t *green, uint8_t *blue)

Convert HSV model to RGB model.

Note

RGB model color depth is 8 bit (0-255).

Parameters

hue – Hue value in the range of 0-360 degrees.
saturation – Saturation value in the range of 0-100.
value – Value (brightness) value in the range of 0-100.
red – Pointer to a variable to store the resulting Red component (0-255).
green – Pointer to a variable to store the resulting Green component (0-255).
blue – Pointer to a variable to store the resulting Blue component (0-255).

Returns

esp_err_t

esp_err_t lightbulb_rgb2hsv(uint16_t red, uint16_t green, uint16_t blue, uint16_t *hue, uint8_t *saturation, uint8_t *value)

Convert RGB model to HSV model.

Note

RGB model color depth is 8 bit (0-255).

Parameters

red – Red component value in the range of 0-255.
green – Green component value in the range of 0-255.
blue – Blue component value in the range of 0-255.
hue – Pointer to a variable to store the resulting Hue value (0-360 degrees).
saturation – Pointer to a variable to store the resulting Saturation value (0-100).
value – Pointer to a variable to store the resulting Value (brightness) value (0-100).

Returns

esp_err_t

esp_err_t lightbulb_xyy2rgb(float x, float y, float Y, uint8_t *red, uint8_t *green, uint8_t *blue)

Convert xyY model to RGB model.

Note

Refer: https://www.easyrgb.com/en/convert.php#inputFORM https://www.easyrgb.com/en/math.php

Parameters

x – x coordinate value in the range of 0 to 1.0.
y – y coordinate value in the range of 0 to 1.0.
Y – Y (luminance) value in the range of 0 to 100.0.
red – Pointer to a variable to store the resulting Red component (0-255).
green – Pointer to a variable to store the resulting Green component (0-255).
blue – Pointer to a variable to store the resulting Blue component (0-255).

Returns

esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_rgb2xyy(uint8_t red, uint8_t green, uint8_t blue, float *x, float *y, float *Y)

Convert RGB model to xyY model.

Parameters

red – Red component value in the range of 0 to 255.
green – Green component value in the range of 0 to 255.
blue – Blue component value in the range of 0 to 255.
x – Pointer to a variable to store the resulting x coordinate (0-1.0).
y – Pointer to a variable to store the resulting y coordinate (0-1.0).
Y – Pointer to a variable to store the resulting Y (luminance) value (0-100.0).

Returns

esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_kelvin2percentage(uint16_t kelvin, uint8_t *percentage)

Convert CCT (Color Temperature) kelvin to percentage.

Parameters

kelvin – Default range: 2200k - 7000k (Color Temperature in kelvin).
percentage – Pointer to a variable to store the resulting percentage (0 - 100).

Returns

esp_err_t

esp_err_t lightbulb_percentage2kelvin(uint8_t percentage, uint16_t *kelvin)

Convert percentage to CCT (Color Temperature) kelvin.

Attention

Parameters

percentage – Percentage value in the range of 0 to 100.
kelvin – Pointer to a variable to store the resulting Color Temperature in kelvin. Default range: 2200k - 7000k.

Returns

esp_err_t

esp_err_t lightbulb_set_hue(uint16_t hue)

Set the hue value.

Parameters: hue – Hue value in the range of 0-360 degrees.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_saturation(uint8_t saturation)

Set the saturation value.

Parameters: saturation – Saturation value in the range of 0-100.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_value(uint8_t value)

Set the value (brightness) of the lightbulb.

Parameters: value – Brightness value in the range of 0-100.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_cct(uint16_t cct)

Set the color temperature (CCT) of the lightbulb.

Note

Supports using either percentage or Kelvin values.

Parameters: cct – CCT value in the range of 0-100 or 2200-7000.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_brightness(uint8_t brightness)

Set the brightness of the lightbulb.

Parameters: brightness – Brightness value in the range of 0-100.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_xyy(float x, float y, float Y)

Set the xyY color model for the lightbulb.

Attention: The xyY color model cannot fully correspond to the HSV color model, so the color may be biased. The grayscale will be recalculated in lightbulb, so we cannot directly operate the underlying driver through the xyY interface.

Parameters

x – x-coordinate value in the range of 0 to 1.0.
y – y-coordinate value in the range of 0 to 1.0.
Y – Y-coordinate (luminance) value in the range of 0 to 100.0.

Returns

esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_hsv(uint16_t hue, uint8_t saturation, uint8_t value)

Set the HSV (Hue, Saturation, Value) color model for the lightbulb.

Parameters

hue – Hue value in the range of 0 to 360 degrees.
saturation – Saturation value in the range of 0 to 100.
value – Value (brightness) value in the range of 0 to 100.

Returns

esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_cctb(uint16_t cct, uint8_t brightness)

Set the color temperature (CCT) and brightness of the lightbulb.

Note

Supports using either percentage or Kelvin values.

Parameters

cct – CCT value in the range of 0-100 or 2200-7000.
brightness – Brightness value in the range of 0-100.

Returns

esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_set_switch(bool status)

Set the on/off status of the lightbulb.

Parameters: status – On/off status (true for on, false for off).
Returns: esp_err_t An error code indicating the success or failure of the operation.

int16_t lightbulb_get_hue(void)

Get the hue value of the lightbulb.

Returns: int16_t The hue value in the range of 0 to 360 degrees.

int8_t lightbulb_get_saturation(void)

Get the saturation value of the lightbulb.

Returns: int8_t The saturation value in the range of 0 to 100.

int8_t lightbulb_get_value(void)

Get the value (brightness) of the lightbulb.

Returns: int8_t The brightness value in the range of 0 to 100.

int8_t lightbulb_get_cct_percentage(void)

Get the color temperature (CCT) percentage of the lightbulb.

Returns: int8_t The CCT percentage value in the range of 0 to 100.

int16_t lightbulb_get_cct_kelvin(void)

Get the color temperature (CCT) Kelvin value of the lightbulb.

Returns: int16_t The CCT Kelvin value in the range of 2200 to 7000.

int8_t lightbulb_get_brightness(void)

Get the brightness value of the lightbulb.

Returns: int8_t The brightness value in the range of 0 to 100.

bool lightbulb_get_switch(void)

Get the on/off status of the lightbulb.

Returns: true The lightbulb is on.
Returns: false The lightbulb is off.

lightbulb_works_mode_t lightbulb_get_mode(void)

Get the work mode of the lightbulb.

Returns: lightbulb_works_mode_t The current work mode of the lightbulb.

esp_err_t lightbulb_get_all_detail(lightbulb_status_t *status)

Get all the status details of the lightbulb.

Parameters: status – A pointer to a lightbulb_status_t structure where the status details will be stored.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_status_get_from_nvs(lightbulb_status_t *value)

Get the lightbulb status from NVS.

Parameters: value – Pointer to a lightbulb_status_t structure where the stored state will be read into.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_status_set_to_nvs(const lightbulb_status_t *value)

Store the lightbulb state to NVS.

Parameters: value – Pointer to a lightbulb_status_t structure representing the current running state to be stored.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_status_erase_nvs_storage(void)

Erase the lightbulb state stored in NVS.

Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_basic_effect_start(lightbulb_effect_config_t *config)

Start some blinking/breathing effects.

Parameters: config – Pointer to a lightbulb_effect_config_t structure containing the configuration for the effect.
Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_basic_effect_stop(void)

Stop the effect in progress and keep the current lighting output.

Returns: esp_err_t An error code indicating the success or failure of the operation.

esp_err_t lightbulb_basic_effect_stop_and_restore(void)

Stop the effect in progress and restore the previous lighting output.

Returns: esp_err_t An error code indicating the success or failure of the operation.

void lightbulb_lighting_output_test(lightbulb_lighting_unit_t mask, uint16_t speed_ms)

Used to test lightbulb hardware functionality.

Parameters

mask – A bitmask representing the test unit or combination of test units to be tested.
speed_ms – The switching speed in milliseconds for the lighting patterns.

Structures

struct lightbulb_cct_mapping_data_t

CCT (Correlated Color Temperature) mapping data.

Note

This structure is used for precise color temperature calibration. Each color temperature value (cct_kelvin) needs to have a corresponding percentage (cct_percentage) determined, which is used to calibrate the color temperature more accurately. The rgbcw array specifies the current coefficients for the RGBCW channels. These coefficients are instrumental in adjusting the intensity of each color channel (Red, Green, Blue, Cool White, Warm White) to achieve the desired color temperature. They are also used for power limiting to ensure energy efficiency and LED longevity. Therefore, the sum of all values in the rgbcw array must equal 1 to maintain the correct power balance.

Public Members

float rgbcw[5]: Array of float coefficients for CCT data (R, G, B, C, W). These coefficients are used to adjust the intensity of each color channel.

uint8_t cct_percentage: Percentage representation of the color temperature. Used to calibrate the light’s color temperature within a predefined range.

uint16_t cct_kelvin: The specific color temperature value in Kelvin. Used to define the perceived warmth or coolness of the light emitted.

struct lightbulb_color_mapping_data_t

Color mode mapping data.

Note

Used for calibrating color accuracy in color mode.

Public Members

float rgbcw_100[5]: The RGBCW components required when saturation is 100 at a specific hue.

float rgbcw_50[5]: The RGBCW components required when saturation is 50 at a specific hue.

float rgbcw_0[5]: The RGBCW components required when saturation is 10 at a specific hue.

uint16_t hue: hue.

struct lightbulb_gamma_config_t

Gamma correction and color balance configuration.

Note

This structure is used for calibrating the brightness proportions and color balance of a lightbulb. Typically, the human eye perceives changes in brightness in a non-linear manner, which is why gamma correction is necessary. This helps to adjust the brightness to match the non-linear perception of the human eye, ensuring a more natural and visually comfortable light output. The color balance coefficients are used to adjust the intensity of each color channel (Red, Green, Blue, Cool White, Warm White) to achieve the desired color balance and overall light quality.

Public Members

float balance_coefficient[5]: Array of float coefficients for adjusting the intensity of each color channel (R, G, B, C, W). These coefficients help in achieving the desired color balance for the light output.

float curve_coefficient: Coefficient for gamma correction. This value is used to modify the luminance levels to suit the non-linear characteristics of human vision, thus improving the overall visual appearance of the light.

struct lightbulb_status_t

The working status of the lightbulb.

Attention: Both the variable value and the variable brightness are used to mark light brightness. They respectively indicate the brightness of color light and white light.

Note

Due to the differences in led beads, the percentage does not represent color temperature. The real meaning is the output ratio of cold and warm led beads: 0% lights up only the warm beads, 50% lights up an equal number of cold and warm beads, and 100% lights up only the cold beads. For simplicity, we can roughly assume that 0% represents the lowest color temperature of the beads, and 100% represents the highest color temperature. The meaning of intermediate percentages varies under different color temperature calibration schemes:

Standard Mode: The percentage is proportionally mapped between the lowest and highest color temperatures.
Precise Mode:
- For hardware CCT schemes (only applicable to PWM-driven): The percentage actually represents the duty cycle of the PWM-driven color temperature channel, with each percentage corresponding to an accurate and real color temperature.
- For those with CW channels: The percentage represents the proportion of cold and warm beads involved in the output. The increase in percentage does not linearly correspond to the increase in color temperature, and instruments are needed for accurate determination.
- For those using RGB channels to mix cold and warm colors: The percentage has no real significance and can be ignored. In actual use, it can serve as an index to reference corresponding color temperature values.”

Public Members

lightbulb_works_mode_t mode: The working mode of the lightbulb (color, white, etc.).

bool on: On/off status of the lightbulb.

uint16_t hue: Hue value for color light (range: 0-360).

uint8_t saturation: Saturation value for color light (range: 0-100).

uint8_t value: Brightness value for color light (range: 0-100).

uint8_t cct_percentage: 0% -> .. -> 100% 2200K -> .. -> 7000K warm -> .. -> cold Cold and warm led bead output ratio (range: 0-100).

uint8_t brightness: Brightness value for white light (range: 0-100).

struct lightbulb_power_limit_t

Output limit or gain without changing color.

Public Members

uint8_t white_max_brightness: Maximum brightness limit for white light output.

uint8_t white_min_brightness: Minimum brightness limit for white light output.

uint8_t color_max_value: Maximum value limit for color light output.

uint8_t color_min_value: Minimum value limit for color light output.

uint16_t white_max_power: Maximum power limit for white light output.

uint16_t color_max_power: Maximum power limit for color light output.

struct lightbulb_cct_kelvin_range_t

Used to map percentages to Kelvin values.

Public Members

uint16_t min: Minimum color temperature value in Kelvin, default is 2200 K.

uint16_t max: Maximum color temperature value in Kelvin, default is 7000 K.

struct lightbulb_capability_t

Some Lightbulb Capability Configuration Options.

Public Members

uint16_t fade_time_ms: Fade time in milliseconds (ms), data range: 100ms - 3000ms, default is 800ms.

uint16_t storage_delay_ms: Storage delay time in milliseconds (ms), used to mitigate adverse effects of short-term repeated erasing and writing of NVS.

lightbulb_led_beads_comb_t led_beads: Configuration for the combination of LED beads. Please select the appropriate type for the onboard LED.

lightbulb_status_storage_cb_t storage_cb: Callback function to be called when the lightbulb status starts to be stored.

bool enable_fade: Enable this option to use fade effects for color switching instead of direct rapid changes.

bool enable_lowpower: Enable low-power regulation when the lights are off.

bool enable_status_storage: Enable this option to store the lightbulb state in NVS.

bool enable_hardware_cct: Enable this option if your driver uses hardware CCT. Some PWM type drivers may need to set this option.

bool enable_precise_cct_control: Enable this option if you need precise CCT control. Must set ‘enable_hardware_cct’ to false in order to enable it.

bool enable_precise_color_control: Enable this option if you need precise Color control.

bool sync_change_brightness_value: Enable this option if you need to use a parameter to mark the brightness of the white and color output.

bool disable_auto_on: Enable this option if you don’t need automatic on when the color/white value is set.

struct lightbulb_config_t

Lightbulb Configuration Options.

Public Members

lightbulb_driver_t type: Type of the lightbulb driver.

union lightbulb_config_t::[anonymous] driver_conf: Configuration specific to the lightbulb driver.

uint16_t kelvin_min: Minimum Kelvin value.

uint16_t kelvin_max: Maximum Kelvin value.

struct lightbulb_config_t::[anonymous]::[anonymous] standard: Standard Mode

lightbulb_cct_mapping_data_t *table: Mixed Color table

int table_size: Table size

struct lightbulb_config_t::[anonymous]::[anonymous] precise: Precise Mode

union lightbulb_config_t::[anonymous] cct_mix_mode: This configuration is used to set up the CCT (Correlated Color Temperature) calibration scheme. The default mode is the standard mode, which requires no additional configuration. For the precise mode, a color mixing table needs to be configured. To enable this precise CCT control, the ‘enable_precise_cct_control’ should be set to true in the capability settings.

lightbulb_color_mapping_data_t *table: Mixed Color table

struct lightbulb_config_t::[anonymous]::[anonymous] precise: Precise Mode

union lightbulb_config_t::[anonymous] color_mix_mode: This configuration is used to set up the color calibration scheme. Measure certain hue and saturation values as calibration points, and use a linear interpolation method for color calibration.

lightbulb_gamma_config_t *gamma_conf: Pointer to the gamma configuration data.

lightbulb_power_limit_t *external_limit: Pointer to the external power limit configuration.

gpio_num_t red: GPIO Pin for the red LED

gpio_num_t green: GPIO Pin for the green LED

gpio_num_t blue: GPIO Pin for the blue LED

gpio_num_t cold_cct: GPIO Pin for the cold or cct LED

gpio_num_t warm_brightness: GPIO Pin for the warm or brightness LED

struct lightbulb_config_t::[anonymous]::[anonymous] pwm_io: Configuration for PWM driver I/O pins.

lightbulb_iic_out_pin_t red: Port of the IIC dimming chip for red output

lightbulb_iic_out_pin_t green: Port of the IIC dimming chip for green output

lightbulb_iic_out_pin_t blue: Port of the IIC dimming chip for blue output

lightbulb_iic_out_pin_t cold_white: Port of the IIC dimming chip for cold or white output

lightbulb_iic_out_pin_t warm_yellow: Port of the IIC dimming chip for warm or yellow output

struct lightbulb_config_t::[anonymous]::[anonymous] iic_io: Configuration for IIC driver I/O pins.

union lightbulb_config_t::[anonymous] io_conf: Union for I/O configuration based on the selected driver type.

lightbulb_capability_t capability: Lightbulb capability configuration.

lightbulb_status_t init_status: Initial status of the lightbulb.

struct lightbulb_effect_config_t

Effect function configuration options.

Public Members

lightbulb_effect_t effect_type: Type of the effect to be configured.

lightbulb_works_mode_t mode: Working mode of the lightbulb during the effect.

uint16_t hue: Hue component value for the effect (0-360).

uint8_t saturation: Saturation component value for the effect (0-100).

uint16_t cct: Color temperature value for the effect.

uint8_t min_value_brightness: Minimum brightness level for the effect (0-100).

uint8_t max_value_brightness: Maximum brightness level for the effect (0-100).

uint16_t effect_cycle_ms: Cycle time for the effect in milliseconds (ms).

int total_ms: Total duration of the effect in milliseconds (ms). If greater than 0, enables an auto-stop timer.

void (*user_cb)(void): User-defined callback function to be called when the auto-stop timer triggers.

bool interrupt_forbidden: If true, the auto-stop timer can only be stopped by specific interfaces or FreeRTOS triggers.

Type Definitions

typedef esp_err_t (*lightbulb_status_storage_cb_t)(lightbulb_status_t status)

Function pointer type to store lightbulb status.

Param status: The lightbulb_status_t structure containing the current status of the lightbulb.
Return: esp_err_t

Enumerations

enum lightbulb_driver_t

Supported drivers.

Values:

enumerator DRIVER_SELECT_INVALID

enumerator DRIVER_ESP_PWM

enumerator DRIVER_SM2135E

enumerator DRIVER_SM2135EH

enumerator DRIVER_SM2x35EGH

enumerator DRIVER_BP57x8D

enumerator DRIVER_BP1658CJ

enumerator DRIVER_KP18058

enumerator DRIVER_WS2812

enumerator DRIVER_SELECT_MAX

enum lightbulb_led_beads_comb_t

Supported LED bead combinations.

Values:

enumerator LED_BEADS_INVALID: Invalid LED bead combination.

enumerator LED_BEADS_1CH_C: Single-channel: Cold white LED bead.

enumerator LED_BEADS_1CH_W: Single-channel: Warm white LED bead.

enumerator LED_BEADS_2CH_CW: Two channels: Warm white + cold white LED beads combination.

enumerator LED_BEADS_3CH_RGB: Three channels: Red + green + blue LED beads combination.

enumerator LED_BEADS_4CH_RGBC: Four channels: Red + green + blue + cold white LED beads combination.

enumerator LED_BEADS_4CH_RGBCC: Four channels: Red + green + blue + 2 * cold white LED beads combination.

enumerator LED_BEADS_4CH_RGBW: Four channels: Red + green + blue + warm white LED beads combination.

enumerator LED_BEADS_4CH_RGBWW: Four channels: Red + green + blue + 2 * warm white LED beads combination.

enumerator LED_BEADS_5CH_RGBCW: Five channels: Red + green + blue + cold white + warm white LED beads combination.

enumerator LED_BEADS_5CH_RGBCC: Five channels: Red + green + blue + 2 * cold white + RGB mix warm white LED beads combination.

enumerator LED_BEADS_5CH_RGBWW: Five channels: Red + green + blue + 2 * warm white + RGB mix cold white LED beads combination.

enumerator LED_BEADS_5CH_RGBC: Five channels: Red + green + blue + cold white + RGB mix warm white LED beads combination.

enumerator LED_BEADS_5CH_RGBW: Five channels: Red + green + blue + warm white + RGB mix cold white LED beads combination.

enumerator LED_BEADS_MAX: Maximum number of supported LED bead combinations.

enum lightbulb_effect_t

Supported effects.

Values:

enumerator EFFECT_BREATH

enumerator EFFECT_BLINK

enum lightbulb_lighting_unit_t

Lighting test units.

Values:

enumerator LIGHTING_RAINBOW: Rainbow lighting effect.

enumerator LIGHTING_WARM_TO_COLD: Transition from warm to cold lighting.

enumerator LIGHTING_COLD_TO_WARM: Transition from cold to warm lighting.

enumerator LIGHTING_BASIC_FIVE: Basic five lighting colors.

enumerator LIGHTING_COLOR_MUTUAL_WHITE: Color and mutual white lighting.

enumerator LIGHTING_COLOR_EFFECT: Color-specific lighting effect.

enumerator LIGHTING_WHITE_EFFECT: White-specific lighting effect.

enumerator LIGHTING_ALEXA: Alexa integration lighting.

enumerator LIGHTING_COLOR_VALUE_INCREMENT: Incrementing color values lighting.

enumerator LIGHTING_WHITE_BRIGHTNESS_INCREMENT: Incrementing white brightness lighting.

enumerator LIGHTING_ALL_UNIT: All lighting units.

enum lightbulb_works_mode_t

The working mode of the lightbulb.

Values:

enumerator WORK_INVALID: Invalid working mode.

enumerator WORK_COLOR: Color mode, where the lightbulb emits colored light.

enumerator WORK_WHITE: White mode, where the lightbulb emits white light.

enum lightbulb_iic_out_pin_t

Port enumeration names for IIC chips.

Values:

enumerator OUT1: IIC output port 1.

enumerator OUT2: IIC output port 2.

enumerator OUT3: IIC output port 3.

enumerator OUT4: IIC output port 4.

enumerator OUT5: IIC output port 5.

enumerator OUT_MAX: The maximum value for the IIC output port enumeration, this is invalid value.

Provide feedback about this document