readme
# 球泡灯组件
该组件将球泡灯中常用的多款调光方案做了封装,使用一个抽象层管理这些方案,便于开发者集成,提供功率限制、颜色校准、呼吸/渐变等多种常用功能,已支持的调光方案如下:
- PWM 直驱方案
- RGB 三路 + C/W 两路:RGB 彩光与 C/W 白光通道混光输出
- RGB 三路 + CCT/Brightness 两路:RGB 彩光通道混光输出,白光使用单独一路控制色温,另一路控制亮度
- IIC 调光芯片方案
- SM2135E
- SM2135EH
- SM2235EGH
- SM2335EGH
- BP5758/BP5758D/BP5768D
- BP1658CJ
- KP18058
- 单总线方案
- WS2812
## PWM 直驱方案使用示例
PWM 直驱方案对于 5 路球泡灯有 2 种控制方式,`RGB 三路 + C/W 两路` 与 `RGB 三路 + CCT/Brightness 两路`,最主要的区别在于后者使用单独的硬件通道控制色温与亮度,不需要程序计算混色比例,所以该方式下色温的准确度是最高的,前者则需要根据所需色温时刻计算冷色与暖色灯珠输出的占比。
使用实例如下:
```c
lightbulb_config_t config = {
//1. 选择 PWM 输出并进行参数配置
.type = DRIVER_ESP_PWM,
.driver_conf.pwm.freq_hz = 4000,
//2. 功能选择,根据你的需要启用/禁用
.capability.enable_fades = true,
.capability.fades_ms = 800,
.capability.enable_lowpower = false,
/* 如果你的驱动白光输出为软件混色而不是硬件单独控制,需要启用此功能 */
.capability.enable_mix_cct = false,
.capability.enable_status_storage = true,
/* 用于配置是 3 路或 2 路或 5 路输出模式 */
.capability.mode_mask = COLOR_MODE,
.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);
```
## IIC 调光芯片方案使用示例
该组件已支持多款 IIC 调光芯片,调光芯片的具体功能及参数请参阅芯片手册。
使用实例如下:
```c
lightbulb_config_t config = {
//1. 选择需要的芯片并进行参数配置,每款芯片配置的参数存在不同,请仔细参阅芯片手册
.type = DRIVER_SM2135E,
.driver_conf.sm2135e.rgb_current = SM2135E_RGB_CURRENT_20MA,
.driver_conf.sm2135e.wy_current = SM2135E_WY_CURRENT_40MA,
.driver_conf.sm2135e.iic_clk = 4,
.driver_conf.sm2135e.iic_sda = 5,
.driver_conf.sm2135e.freq_khz = 400,
.driver_conf.sm2135e.enable_iic_queue = true,
//2. 驱动功能选择,根据你的需要启用/禁用
.capability.enable_fades = true,
.capability.fades_ms = 800,
.capability.enable_lowpower = false,
/* 对于 IIC 方案,该选项必须配置为启用 */
.capability.enable_mix_cct = true,
.capability.enable_status_storage = true,
.capability.mode_mask = COLOR_AND_WHITE_MODE,
.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);
```
## 单总线方案使用示例
该组件使用 SPI 驱动输出 WS2812 所需要的数据,数据封装顺序为 GRB。
```c
lightbulb_config_t config = {
//1. 选择 WS2812 输出并进行参数配置
.type = DRIVER_WS2812,
.driver_conf.ws2812.led_num = 22,
.driver_conf.ws2812.ctrl_io = 4,
//2. 驱动功能选择,根据你的需要启用/禁用
.capability.enable_fades = true,
.capability.fades_ms = 800,
.capability.enable_status_storage = true,
/* 对于 WS2812 只能选择 COLOR_MODE */
.capability.mode_mask = COLOR_MODE,
.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);
```
## 限制参数使用说明
限制参数主要用途为限制输出的最大功率,以及将亮度参数限制在一个区间。该组件彩光与白光可独立控制,所以存在 2 组最大/最小亮度参数及功率参数。彩光使用 `HSV` 模型,`value` 代表彩光亮度,白光使用 `brightness` 参数。`value` 与 `brightness` 数据输入范围为 0 <= x <= 100。
如果设置了亮度限制参数,那么将对输入值进行等比例缩放,例如,我们设置了下面这些参数
```c
lightbulb_power_limit_t limit = {
.white_max_brightness = 100,
.white_min_brightness = 10,
.color_max_value = 100,
.color_min_value = 10,
.white_max_power = 100,
.color_max_power = 100
}
```
`value` 与 `brightness` 输入与输出的关系如下:
```c
input output
100 100
80 82
50 55
11 19
1 10
0 0
```
功率限制在亮度参数限制后进一步进行,对于 RGB 通道调整区间为 100 <= x <= 300,输入与输出的关系如下:
```c
input output(color_max_power = 100) output(color_max_power = 200) output(color_max_power = 300)
255,255,0 127,127,0 255,255,0 255,255,0
127,127,0 63,63,0 127,127,0 127,127,0
63,63,0 31,31,0 63,63,0 63,63,0
255,255,255 85,85,85 170,170,170 255,255,255
127,127,127 42,42,42 84,84,84 127,127,127
63,63,63 21,21,21 42,42,42 63,63,63
```
## 颜色校准参数
颜色校准参数由 2 个部分组成,用于生成 gamma 灰度表的曲线系数 `x_curve_coe` 及用于做最终调整的白平衡系数 `r_balance_coe`。
- 曲线系数的取值在 0.8 <= x <= 2.2,各参数输出如下
```c
| x = 1.0 | x < 1.0 | x > 1.0
max| | |
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
0 |------------------------------------|----------------------------------|------------------------------
0 ... 255
```
组件将根据各驱动所支持的最大输入值生成 gamma 校准表格,所有 8bit RGB 都将转为校准后的值,建议为 RGB 通道设置同一系数。
- 白平衡系数的取值在 0.5-1.0,对数据进行最后微调,计算规则为 `输出值 = 输入值 * 系数`,可以为每个通道设置不同的系数。
## 示例代码
[点击此处](https://github.com/espressif/esp-iot-solution/tree/master/examples/lighting/lightbulb) 获取示例代码及使用说明。
changelog
# ChangeLog
## v0.5.1 - 2023-10-26
### Bug Fixes:
* Fix phase delay for pwm cw channel.
## v0.5.0 - 2023-10-09
### Enhancements:
* Add a phase delay function to the PWM drive, and after enabling this function, all channel outputs will be in a complementary state.
## v0.4.1 - 2023-8-30
### Bug Fixes:
* Fixed a thread safety issue.
* Fixed fade direction being reversed.
## v0.4.0 - 2023-7-10
### Enhancements:
* The PWM driver will update the timer resolution based on the incoming PWM frequency to accommodate a wider range of frequencies.
* Remove the blocking check of the timer status in `lightbulb_basic_effect_start` to allow for subsequent calls within the callback.
## v0.3.3 - 2023-7-04
### Bug Fixes:
* Fixed a compilation problem caused by a macro naming error.
## v0.3.2 - 2023-6-02
### Bug Fixes:
* Fixed a thread safety issue
## v0.3.1 - 2023-5-15
### Enhancements:
* Add an active flag to gptimer to reduce invalid error print in the IDF gptimer driver
### Bug Fixes:
* Fixed a wrong error on kelvin range
## v0.3.0 - 2023-5-8
### Enhancements:
* Provide an option to use gptimer instead of esptimer to generate ticks for the fade process
### Bug Fixes:
* Fixed a wrong conversion on `percentage_convert_to_kelvin`
## v0.2.2 - 2023-3-10
### Bug Fixes:
* Fixed some wrong data types
* Provides configuration options for the iic task instead of hardcoding
* Added null pointer judgment to effect timer
## v0.2.1 - 2023-2-21
### Bug Fixes:
* Provide a workaround solution to temporarily solve the issue that LEDC hardware fade API calls are blocked
Please read some description of the macro PWM_ENABLE_HW_FADE in Kconfig
* Effect interrupt_forbidden flag will allow to set when total_ms == 0
## v0.2.0 - 2023-2-8
### Enhancements:
* Add interrupt_forbidden flag in effect
* Provide Yxy color model conversion function
### Bug Fixes:
* Fix nvs structure naming error
## v0.1.0 - 2023-1-11
### Enhancements:
* Support running on ESP32-C6
### Bug Fixes:
* Fix kelvin 2 percentage
* Fix effect timer time
* Modify the logic of low power mode entry and exit
## v0.0.9 - 2022-12-28
### Enhancements:
* Provide an effect timer
## v0.0.8 - 2022-12-22
### Enhancements:
* Provide new application layer capability: enable/disable auto-open
## v0.0.7 - 2022-12-15
### Enhancements:
* Support running on ESP32-H2
## v0.0.6 - 2022-12-05
### Enhancements:
* Support running on ESP32-C2
* Provide PWM signal invert
### Bug Fixes:
* Fix LEDC output is disabled after the software reset
## v0.0.5 - 2022-12-02
### Enhancements:
* Support compiling with IDF 5.0
### Bug Fixes:
* Fix some drivers being power halved in white light mode
* Fix some configuration errors in the demo
## v0.0.4 - 2022-11-10
### Enhancements:
* Support BP1658CJ IIC dimming chip
## v0.0.3 - 2022-10-26
### Enhancements:
* Support KP18058 IIC dimming chip
## v0.0.2 - 2022-10-26
### Enhancements:
* Support running on ESP32-S3
### Bug Fixes:
* Fix API `lightbulb_rgb2hsv` conversion error
* Update some typo
* `basis` -> `basic`
* `mix` -> `min`
## v0.0.1 - 2022-8-29
### Enhancements:
* Initial version
* The following dimming solutions are supported
* PWM
* RGB + CW
* RGB + CCT/Brightness
* IIC dimming IC
* SM2135E
* SM2135EH
* SM2235EGH
* SM2335EGH
* BP5758/BP5758D/BP5768D
* Single Line
* WS2812
* Support for power limit
* Support for color calibration
* Support for effect
* Blink
* Breathe
* Support for application layer capability configuration
* Status memory
* Fade
* Mix CCT
* Low-power
* Light mode select
* Sync change