球泡灯驱动

球泡灯驱动组件将球泡灯中常用的多款调光方案做了封装，使用一个抽象层管理这些方案，便于开发者集成到自己的应用程序中，目前所有 ESP32 系列芯片都已经完成支持。

调光方案

PWM 调光方案

PWM 调光是一种通过调节脉冲宽度来控制 LED 亮度的技术，核心在于通过改变电流脉冲的占空比（即高电平时间在整个周期时间中的比例）来调节。当占空比较高时，LED 获得的电流时间长，亮度高；反之，占空比低时，LED 获得的电流时间短，亮度低。所有 ESP 芯片均支持使用硬件 LEDC 驱动 / MCPWM 驱动输出 PWM，推荐优先使用 LEDC 驱动实现，LEDC 驱动支持硬件渐变，频率占空比均可配置，分辨率最高为 20 bit。目前已支持下述 PWM 调光驱动类型：

RGB + C/W

RGB + CCT/Brightnes

PWM 方案使用案例

使用 PWM 方案点亮一个 3 路 RGB 灯珠球泡灯，PWM 频率为 4000Hz，使用软件混色，启用渐变功能，上电点亮为红色。

lightbulb_config_t config = {
    //1. 选择 PWM 输出并进行参数配置
    .type = DRIVER_ESP_PWM,
    .driver_conf.pwm.freq_hz = 4000,

    //2. 功能选择，根据你的需要启用/禁用
    .capability.enable_fade = true,
    .capability.fade_time_ms = 800,
    .capability.enable_lowpower = false,
    /* 如果你的驱动白光输出为硬件单独控制而不是软件混色，需要启用此功能 */
    .capability.enable_hardware_cct = true,
    .capability.enable_status_storage = true,
    /* 用于配置 LED 灯珠组合 */
    .capability.led_beads = LED_BEADS_3CH_RGB,
    .capability.storage_cb = NULL,
    .capability.sync_change_brightness_value = true,

    //3. 配置 PWM 输出的硬件管脚
    .io_conf.pwm_io.red = 25,
    .io_conf.pwm_io.green = 26,
    .io_conf.pwm_io.blue = 27,

    //4. 限制参数
    .external_limit = NULL,

    //5. 颜色校准参数
    .gamma_conf = NULL,

    //6. 初始化照明参数，如果 on 置位将在初始化驱动时点亮球泡灯
    .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 调光方案

I2C 调光通过 I2C 总线发送控制命令到调光芯片，通过改变调光芯片的输出电流，调节 LED 的亮度。I2C 总线由两条线构成：数据线 (SDA) 和时钟线 (SCL)。所有 ESP 芯片均支持使用硬件 I2C 通信调光芯片。目前已支持下述调光芯片：

SM2135EH

SM2X35EGH (SM2235EGH/SM2335EGH)

BP57x8D (BP5758/BP5758D/BP5768)

BP1658CJ

KP18058

I2C 调光使用案例

使用 I2C 驱动 BP5758D 芯片点亮一个 5 路 RGBCW 灯珠球泡灯，I2C 通信速率为 300KHz，RGB 灯珠驱动电流为 50 mA，CW 灯珠驱动电流为 30mA，使用软件混色，启用渐变功能，上电点亮为红色。

lightbulb_config_t config = {
    //1. 选择需要的芯片并进行参数配置，每款芯片配置的参数存在不同，请仔细参阅芯片手册
    .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.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. 配置 IIC 芯片的硬件管脚
    .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. 限制参数，使用细则请参考后面小节
    .external_limit = NULL,

    //5. 颜色校准参数
    .gamma_conf = NULL,

    //6. 初始化照明参数，如果 on 置位将在初始化驱动时点亮球泡灯
    .init_status.mode = WORK_COLOR,
    .init_status.on = true,
    .init_status.hue = 0,
    .init_status.saturation = 100,
    .init_status.value = 100,
};
lightbulb_init(&config);

单线调光方案

单线调光方案是一种通过单根通信线控制 LED 亮度的方法，核心是通过特定的通信协议发送控制信号来调节 LED 的亮度，此类方案在 ESP 芯片上可使用 RMT 外设或 SPI外设实现，推荐优先使用 SPI 实现灯珠通信控制。目前已支持下述灯珠类型：

WS2812

WS2812 使用案例

使用 SPI 驱动点亮 10 颗 WS2812 灯珠，启用渐变功能，上电为红色。

lightbulb_config_t config = {
    //1. 选择 WS2812 输出并进行参数配置
    .type = DRIVER_WS2812,
    .driver_conf.ws2812.led_num = 10,
    .driver_conf.ws2812.ctrl_io = 4,

    //2. 驱动功能选择，根据你的需要启用/禁用
    .capability.enable_fade = true,
    .capability.fade_time_ms = 800,
    .capability.enable_status_storage = true,

    /* 对于 WS2812 只能选择 LED_BEADS_3CH_RGB */
    .capability.led_beads = LED_BEADS_3CH_RGB,
    .capability.storage_cb = NULL,

    //3. 限制参数，使用细则请参考后面小节
    .external_limit = NULL,

    //4. 颜色校准参数
    .gamma_conf = NULL,

    //5. 初始化照明参数，如果 on 置位将在初始化驱动时点亮球泡灯
    .init_status.mode = WORK_COLOR,
    .init_status.on = true,
    .init_status.hue = 0,
    .init_status.saturation = 100,
    .init_status.value = 100,
};
lightbulb_init(&config);

渐变原理

球泡灯组件中的渐变是用软件实现的，每个通道将记录驱动输出的当前值，最终值，步长，步数等。当使用 API 设置颜色时，会更改最终值，步长，步数，并启用渐变定时器，定时器每间隔 12ms 触发一次回调，回调函数中会检查每个通道的步数，只要存在未执行完的步数，就会根据步长加减当前值，并更新到底层驱动中。当所有通道步数为 0 时，便代表渐变完成，此时将停止定时器。

低功耗实现流程

球泡灯如果要通过 T20 等功耗认证，优化灯板电源后，软件上需要做一些低功耗配置，除了应用低功耗模式使用指南中提到的配置外，驱动部分也需要进行一些处理，球泡灯组件中已经在 PWM 方案与 I2C 2 种调光驱动方案增加了相关内容，具体逻辑为开关灯时，I2C 方案调用调光芯片自身的低功耗指令，退出或进入低功耗，PWM 方案中，ESP32 由于使用 APB 时钟源，需要通过电源锁管理，否则会出现灯光闪烁，开灯时拿电源锁，禁用动态调频，关灯时释放，其他芯片采用 XTAL 时钟源，无需采取任何措施。

颜色校准方案

色温模式

色温模式的校准需要配置下述结构体。

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;

标准模式：标定最大最小值开尔文值，使用线性插值的方式补全中间值，然后根据比色温值调节冷、暖灯珠输出的比例。
精准模式：校准不同色温所需要的红、绿、蓝、冷、暖灯珠输出比例，使用这些校准点直接输出对应比例，校准的点越多，色温越精准。

彩色模式

色彩模式的校准需要配置下述结构体。

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

标注模式：无需参数配置，内部将使用理论算法将 HSV、 XYY 等颜色模型转化为 RGB 比例，直接按此比例点亮灯珠。
精准模式：使用 HSV 模型标定颜色，测量一些不同色相与饱和度颜色所需要的红、绿、蓝、冷、暖灯珠输出比例作为校准点，使用线性插值的方式补全中间值，使用这些校准点后配比点亮灯珠。

功率限制方案

功率限制用于平衡、微调某个通道或整体的输出电流，以满足功率需求。

如果需要对整体功率进行限制需要配置下述结构体。

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 与 white_min_brightness 用于色温模式，将色温 API 设置的 brightness 参数限制在该最大最小值之间。
color_max_value 与 color_min_value 用于彩色模式，将彩色 API 设置的 value 参数限制在该最大最小值之间。
white_max_power 用于色温模式限制功率，默认值为 100，即输出的最大功率为满功率的 1/2，如果为 200 则能达到冷、暖灯珠的最大功率。
color_max_power 用于彩色模式限制功率，默认值为 100，即输出的最大功率为满功率的 1/3，如果为 300 则能达到红、绿、蓝灯珠的最大功率。

如果需要对单灯珠功率进行限制需要配置下述结构体：

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 用于微调每个灯珠输出电流，驱动最终输出将按该比例进行衰减，默认值为 1.0，即不衰减。
curve_coefficient 用于将渐变时的线性变化转化为曲线变化。

备注

修改 balance_coefficient 将影响颜色校准的准确性，需要先调整该参数在进行颜色校准。该参数最大的用途在于，某些 I2C 调光芯片输出的电流为 5mA 或者 10mA 的整倍数，如果需要特定电流便可使用该参数调整。

API 参考

Header File

components/led/lightbulb_driver/include/lightbulb.h

Functions

esp_err_t lightbulb_init(lightbulb_config_t *config)

Initialize the lightbulb.

参数: config – Pointer to the configuration parameters for the lightbulb.
返回: esp_err_t

esp_err_t lightbulb_deinit(void)

Deinitialize the lightbulb and release resources.

返回: esp_err_t

esp_err_t lightbulb_set_fade_time(uint32_t fade_time_ms)

Set lightbulb fade time.

参数: fade_time_ms – Fade time in milliseconds (ms). Range: 100ms - 3000ms.
返回: esp_err_t

esp_err_t lightbulb_set_fades_function(bool is_enable)

Enable/Disable the lightbulb fade function.

参数: is_enable – A boolean flag indicating whether to enable (true) or disable (false) the fade function.
返回: esp_err_t

esp_err_t lightbulb_set_storage_function(bool is_enable)

Enable/Disable the lightbulb storage function.

参数: is_enable – A boolean flag indicating whether to enable (true) or disable (false) the storage function.
返回: esp_err_t

esp_err_t lightbulb_update_status(lightbulb_status_t *new_status, bool trigger)

Re-update the lightbulb status.

参数

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.

返回

esp_err_t

bool lightbulb_get_fades_function_status(void)

Get lightbulb fade function enabled status.

返回: true if the fade function is enabled.
返回: 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.

备注

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

参数

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

返回

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.

备注

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

参数

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

返回

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.

备注

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

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

esp_err_t

esp_err_t lightbulb_percentage2kelvin(uint8_t percentage, uint16_t *kelvin)

Convert percentage to CCT (Color Temperature) kelvin.

Attention

参数

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.

返回

esp_err_t

esp_err_t lightbulb_set_hue(uint16_t hue)

Set the hue value.

参数: hue – Hue value in the range of 0-360 degrees.
返回: 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.

参数: saturation – Saturation value in the range of 0-100.
返回: 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.

参数: value – Brightness value in the range of 0-100.
返回: 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.

备注

Supports using either percentage or Kelvin values.

参数: cct – CCT value in the range of 0-100 or 2200-7000.
返回: 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.

参数: brightness – Brightness value in the range of 0-100.
返回: 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.

参数

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.

返回

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.

参数

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.

返回

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.

备注

Supports using either percentage or Kelvin values.

参数

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

返回

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.

参数: status – On/off status (true for on, false for off).
返回: 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.

返回: 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.

返回: 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.

返回: 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.

返回: 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.

返回: 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.

返回: 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.

返回: true The lightbulb is on.
返回: false The lightbulb is off.

lightbulb_works_mode_t lightbulb_get_mode(void)

Get the work mode of the lightbulb.

返回: 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.

参数: status – A pointer to a lightbulb_status_t structure where the status details will be stored.
返回: 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.

参数: value – Pointer to a lightbulb_status_t structure where the stored state will be read into.
返回: 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.

参数: value – Pointer to a lightbulb_status_t structure representing the current running state to be stored.
返回: 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.

返回: 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.

参数: config – Pointer to a lightbulb_effect_config_t structure containing the configuration for the effect.
返回: 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.

返回: 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.

返回: 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.

参数

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.

备注

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.

备注

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.

备注

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.

备注

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.

提供有关此文档的反馈