uploaded 2 months ago
Provide multiple dimming driver solutions to easily build lightbulb applications
readme
# Lightbulb Component
👉 [中文版](./README_CN.md)
The lightbulb component encapsulates several commonly used dimming schemes for lightbulbs, managing these schemes through an abstract layer for easy integration into developers' applications. Currently, support has been extended to all ESP32 series chips.
- PWM Scheme:
- RGB + C/W
- RGB + CCT/Brightness
- IIC Dimming Scheme
- ~~SM2135E~~
- SM2135EH
- SM2X35EGH (SM2235EGH/SM2335EGH)
- BP57x8D (BP5758/BP5758D/BP5768)
- BP1658CJ
- KP18058
- Single Bus Scheme:
- WS2812
## Supported common functionalities
- Dynamic Effects: Supports various color transitions using fades, and allows configuring periodic breathing and blinking effects.
- Calibration: Enables fine-tuning of output data using coefficients to achieve white balance functionality, and supports gamma calibration curves.
- Status Storage: Utilizes the `NVS` component to store the current state of the lightbulb, facilitating features like power loss memory.
- LED Configuration: Supports up to 5 types of LED configurations, with the following combinations:
- Single-channel, cold or warm temperature LED, capable of brightness control under a single color temperature.
- Dual-channel, cold and warm LEDs, enabling control of both color temperature and brightness.
- Tri-channel, red, green, and blue LEDs, allowing for arbitrary color control.
- Four-channel, red, green, blue, and cold or warm temperature LEDs, enabling color control and brightness control under a single color temperature. If a mixing table is configured, different color temperatures can be achieved by mixing these LEDs, enabling color temperature control.
- Five-channel, red, green, blue, cold, and warm temperature LEDs, enabling color and color temperature-controlled brightness.
- Power Limitation: Balances the output power under different color temperatures and colors.
- Low Power: Reduces overall power consumption without compromising dynamic effects.
- Software Color Temperature: Applicable for PWM-driven scenarios where hardware color temperature adjustment is not performed.
## Example of PWM Scheme
The PWM scheme is implemented using the LEDC driver, supporting both software and hardware fade functionalities. It also automatically configures resolution based on frequency. An example of usage is provided below:
```c
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 Based on Your Needs
.capability.enable_fade = true,
.capability.fade_time_ms = 800,
.capability.enable_lowpower = false,
/* If your driver controls white light output separately through hardware instead of software mixing, enable this feature. */
.capability.enable_hardware_cct = true,
.capability.enable_status_storage = true,
/* Used to configure the combination of LED beads */
.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. Limit parameters, defaults are usually sufficient
.external_limit = NULL,
// 5. Calibration parameters, defaults are usually sufficient
.gamma_conf = NULL,
// 6. Initialize status parameters; if "on" is set, the light will turn on 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);
```
## Example of IIC Scheme
The IIC dimming chip solution now supports configuring all parameters of the IIC dimming chip. Please refer to the manual for the specific functions and parameters of the dimming chip and fill in accordingly. An example of usage is provided below:
```c
lightbulb_config_t config = {
// 1. Select the desired chip and configure parameters. Each chip has different configuration parameters. Please carefully refer 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, 60, 30, 50},
// 2. Capability Selection: Enable/Disable Based on 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 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. Limit parameters, defaults are usually sufficient
.external_limit = NULL,
// 5. Calibration parameters, defaults are usually sufficient
.gamma_conf = NULL,
// 6. Initialize status parameters; if "on" is set, the light will turn on 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);
```
## Example of Single-bus Scheme
Single-bus scheme utilizes the SPI driver to output data for WS2812 LEDs, with data packaging sequence set as GRB.
```c
lightbulb_config_t config = {
// 1. Select WS2812 output and configure parameters
.type = DRIVER_WS2812,
.driver_conf.ws2812.led_num = 22,
.driver_conf.ws2812.ctrl_io = 4,
// 2. Capability Selection: Enable/Disable Based on Your Needs
.capability.enable_fade = true,
.capability.fade_time_ms = 800,
.capability.enable_status_storage = true,
/* For WS2812, you can only choose LED_BEADS_3CH_RGB */
.capability.led_beads = LED_BEADS_3CH_RGB,
.capability.storage_cb = NULL,
// 3. Limit parameters, defaults are usually sufficient
.external_limit = NULL,
// 4. Calibration parameters, defaults are usually sufficient
.gamma_conf = NULL,
// 5. Initialize status parameters; if "on" is set, the light will turn on 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);
```
## Example of Limit Parameters
The primary purpose of limit parameters is to restrict the maximum output power and constrain the brightness parameters within a specific range. This component allows independent control of colored light and white light, which results in two sets of maximum/minimum brightness parameters and power parameters. Colored light uses the HSV model, with the value representing colored light brightness, while white light uses the brightness parameter. The input range for both value and brightness is 0 <= x <= 100.
If brightness limitation parameters are set, the input values will be proportionally scaled. For instance, consider the following parameters:
```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
}
```
The relationship between value and brightness inputs and outputs is as follows:
```c
input output
100 100
80 82
50 55
11 19
1 10
0 0
```
Power limit is applied after the brightness parameter limitations, and for the RGB channel adjustment, the range is 100 <= x <= 300. The relationship between input and output is as follows:
```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
```
## Example of Calibration Parameters
Color calibration parameters consist of two components: curve coefficients `curve_coefficient` used to generate the gamma grayscale table, and white balance coefficients `balance_coefficient` used for the final adjustments.
- Curve coefficients have values within the range of 0.8 <= x <= 2.2. The output for each parameter is as follows:
```c
| x = 1.0 | x < 1.0 | x > 1.0
max| | |
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
| * | * | *
0 |------------------------------------|----------------------------------|------------------------------
0 ... 255
```
The component will generate a gamma calibration table based on the maximum input values supported by each driver. All 8-bit RGB values will be converted to their calibrated counterparts. It is recommended to set the same coefficient for the RGB channels.
- White balance coefficients have values within the range of 0.5 to 1.0. They are used for final fine-tuning of the data, and the calculation rule is: output value = input value * coefficient. Different coefficients can be set for each channel.
## Example Code
Click [here](https://github.com/espressif/esp-iot-solution/tree/master/examples/lighting/lightbulb) to access the example code and usage instructions.
changelog
# ChangeLog
## v1.1.2 - 2024-02-05
### Bug Fixes:
* fix(lightbulb): incorrect type.
## v1.1.1 - 2024-02-04
### Bug Fixes:
* Add CCT data range check.
* Fixed the issue of setting interrupt_forbidden to true but the effect is still interrupted.
## v1.1.0 - 2024-01-30
### Enhancements:
* Added the conversion function of IIC current values to the enumeration values required by the driver.
* Added driver layer parameter checking macro and allowed to configure the detail level of the output log through menuconfig.
## v1.0.0 - 2024-01-16
### Enhancements:
* The driver provides LED bead combination options and supports different types of lightbulbs.
* Added feature to count IIC driver transmission failures, aiding in hardware health monitoring.
* Discontinued support for SM2135E driver, removing related files and code.
* Updated BP5758D driver files to BP57X8D for consistency with SM2X35EGH.
* The driver now supports setting white balance parameters for all channels. This means that you can adjust the white balance individually for each channel, allowing for precise control and customization of the lighting output.
* Increased the power limit range from 100-300 to 100-500, facilitating power setting for RGBWW beads.
* Introduced CCT output modes: standard mode (consistent with original scheme, mapping percentage to Kelvin values proportionally) and precise mode (setting individual percentages for each Kelvin value and predetermining current coefficients for each channel, scaling these coefficients proportionally during writing).
* Some configuration changes:
* Removed mode_mask from capability, now using led_beads to set the LED panel bead combination
* Renamed enable_mix_cct to enable_hardware_cct, fades_ms to fade_time_ms, and enable_fades to enable_fade
* Removed hardware_monitor_cb
## v0.5.5 - 2024-01-15
### Bug Fixes:
* Update conditions for CI tests
## v0.5.4 - 2024-01-12
### Bug Fixes:
* fix: stack overflow in task fade_tick_task on xtensa architecture
## v0.5.3 - 2024-01-10
### Bug Fixes:
* fix: function declaration isn't a prototype [-Werror=strict-prototypes]
## v0.5.2 - 2023-10-28
### Enhancements:
* Update LEDC low power code logic.
* Modify the test cases and use the pytest tool for real hardware testing.
## 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
Links
Supports all targets
License: Apache-2.0
To add this component to your project, run:
or
download archive
idf.py add-dependency "espressif/lightbulb_driver^1.1.2"
Examples:
lightbulb
more detailsTo create a project from this example, run:
idf.py create-project-from-example "espressif/lightbulb_driver^1.1.2:lightbulb"
Stats
-
Downloaded in total 17.7k times
-
This version: 1.6k times
Badge
