LED Strip Programming Guide
Allocate LED Strip Object with RMT Backend
#define BLINK_GPIO 0
/// LED strip common configuration
led_strip_config_t strip_config = {
.strip_gpio_num = BLINK_GPIO, // The GPIO that connected to the LED strip's data line
.max_leds = 1, // The number of LEDs in the strip,
.led_model = LED_MODEL_WS2812, // LED strip model, it determines the bit timing
.color_component_format = LED_STRIP_COLOR_COMPONENT_FMT_GRB, // The color component format is G-R-B
.flags = {
.invert_out = false, // don't invert the output signal
}
};
/// RMT backend specific configuration
led_strip_rmt_config_t rmt_config = {
.clk_src = RMT_CLK_SRC_DEFAULT, // different clock source can lead to different power consumption
.resolution_hz = 10 * 1000 * 1000, // RMT counter clock frequency: 10MHz
.mem_block_symbols = 64, // the memory size of each RMT channel, in words (4 bytes)
.flags = {
.with_dma = false, // DMA feature is available on chips like ESP32-S3/P4
}
};
/// Create the LED strip object
led_strip_handle_t led_strip = NULL;
ESP_ERROR_CHECK(led_strip_new_rmt_device(&strip_config, &rmt_config, &led_strip));
You can create multiple LED strip objects with different GPIOs and pixel numbers. The backend driver will automatically allocate sufficient RMT channels for you wherever possible. If the RMT channels are not enough, the led_strip_new_rmt_device will return an error.
Allocate LED Strip Object with SPI Backend
#define BLINK_GPIO 0
/// LED strip common configuration
led_strip_config_t strip_config = {
.strip_gpio_num = BLINK_GPIO, // The GPIO that connected to the LED strip's data line
.max_leds = 1, // The number of LEDs in the strip,
.led_model = LED_MODEL_WS2812, // LED strip model, it determines the bit timing
.color_component_format = LED_STRIP_COLOR_COMPONENT_FMT_GRB, // The color component format is G-R-B
.flags = {
.invert_out = false, // don't invert the output signal
}
};
/// SPI backend specific configuration
led_strip_spi_config_t spi_config = {
.clk_src = SPI_CLK_SRC_DEFAULT, // different clock source can lead to different power consumption
.spi_bus = SPI2_HOST, // SPI bus ID
.flags = {
.with_dma = true, // Using DMA can improve performance and help drive more LEDs
}
};
/// Create the LED strip object
led_strip_handle_t led_strip = NULL;
ESP_ERROR_CHECK(led_strip_new_spi_device(&strip_config, &spi_config, &led_strip));
The number of LED strip objects can be created depends on how many free SPI controllers are free to use in your project.
FAQ
- How to set the brightness of the LED strip?
- You can tune the brightness by scaling the value of each R-G-B element with a same factor. But pay attention to the overflow of the value.
API Reference
Header files
- include/led_strip.h
- include/led_strip_rmt.h
- include/led_strip_spi.h
- include/led_strip_types.h
- interface/led_strip_interface.h
File include/led_strip.h
Functions
Type | Name |
---|---|
esp_err_t | led_strip_clear (led_strip_handle_t strip) Clear LED strip (turn off all LEDs) |
esp_err_t | led_strip_del (led_strip_handle_t strip) Free LED strip resources. |
esp_err_t | led_strip_refresh (led_strip_handle_t strip) Refresh memory colors to LEDs. |
esp_err_t | led_strip_set_pixel (led_strip_handle_t strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue) Set RGB for a specific pixel. |
esp_err_t | led_strip_set_pixel_hsv (led_strip_handle_t strip, uint32_t index, uint16_t hue, uint8_t saturation, uint8_t value) Set HSV for a specific pixel. |
esp_err_t | led_strip_set_pixel_rgbw (led_strip_handle_t strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue, uint32_t white) Set RGBW for a specific pixel. |
Functions Documentation
function led_strip_clear
Clear LED strip (turn off all LEDs)
esp_err_t led_strip_clear (
led_strip_handle_t strip
)
Parameters:
strip
LED strip
Returns:
- ESP_OK: Clear LEDs successfully
- ESP_FAIL: Clear LEDs failed because some other error occurred
function led_strip_del
Free LED strip resources.
esp_err_t led_strip_del (
led_strip_handle_t strip
)
Parameters:
strip
LED strip
Returns:
- ESP_OK: Free resources successfully
- ESP_FAIL: Free resources failed because error occurred
function led_strip_refresh
Refresh memory colors to LEDs.
esp_err_t led_strip_refresh (
led_strip_handle_t strip
)
Parameters:
strip
LED strip
Returns:
- ESP_OK: Refresh successfully
- ESP_FAIL: Refresh failed because some other error occurred
Note:
: After updating the LED colors in the memory, a following invocation of this API is needed to flush colors to strip.
function led_strip_set_pixel
Set RGB for a specific pixel.
esp_err_t led_strip_set_pixel (
led_strip_handle_t strip,
uint32_t index,
uint32_t red,
uint32_t green,
uint32_t blue
)
Parameters:
strip
LED stripindex
index of pixel to setred
red part of colorgreen
green part of colorblue
blue part of color
Returns:
- ESP_OK: Set RGB for a specific pixel successfully
- ESP_ERR_INVALID_ARG: Set RGB for a specific pixel failed because of invalid parameters
- ESP_FAIL: Set RGB for a specific pixel failed because other error occurred
function led_strip_set_pixel_hsv
Set HSV for a specific pixel.
esp_err_t led_strip_set_pixel_hsv (
led_strip_handle_t strip,
uint32_t index,
uint16_t hue,
uint8_t saturation,
uint8_t value
)
Parameters:
strip
LED stripindex
index of pixel to sethue
hue part of color (0 - 360)saturation
saturation part of color (0 - 255, rescaled from 0 - 1. e.g. saturation = 0.5, rescaled to 127)value
value part of color (0 - 255, rescaled from 0 - 1. e.g. value = 0.5, rescaled to 127)
Returns:
- ESP_OK: Set HSV color for a specific pixel successfully
- ESP_ERR_INVALID_ARG: Set HSV color for a specific pixel failed because of an invalid argument
- ESP_FAIL: Set HSV color for a specific pixel failed because other error occurred
function led_strip_set_pixel_rgbw
Set RGBW for a specific pixel.
esp_err_t led_strip_set_pixel_rgbw (
led_strip_handle_t strip,
uint32_t index,
uint32_t red,
uint32_t green,
uint32_t blue,
uint32_t white
)
Note:
Only call this function if your led strip does have the white component (e.g. SK6812-RGBW)
Note:
Also see led_strip_set_pixel
if you only want to specify the RGB part of the color and bypass the white component
Parameters:
strip
LED stripindex
index of pixel to setred
red part of colorgreen
green part of colorblue
blue part of colorwhite
separate white component
Returns:
- ESP_OK: Set RGBW color for a specific pixel successfully
- ESP_ERR_INVALID_ARG: Set RGBW color for a specific pixel failed because of an invalid argument
- ESP_FAIL: Set RGBW color for a specific pixel failed because other error occurred
File include/led_strip_rmt.h
Structures and Types
Type | Name |
---|---|
struct | led_strip_rmt_config_t LED Strip RMT specific configuration. |
struct | led_strip_rmt_extra_config |
Functions
Type | Name |
---|---|
esp_err_t | led_strip_new_rmt_device (const led_strip_config_t *led_config, const led_strip_rmt_config_t *rmt_config, led_strip_handle_t *ret_strip) Create LED strip based on RMT TX channel. |
Structures and Types Documentation
struct led_strip_rmt_config_t
LED Strip RMT specific configuration.
Variables:
-
rmt_clock_source_t clk_src
RMT clock source -
struct led_strip_rmt_config_t::led_strip_rmt_extra_config flags
Extra driver flags -
size_t mem_block_symbols
How many RMT symbols can one RMT channel hold at one time. Set to 0 will fallback to use the default size. Extra RMT specific driver flags -
uint32_t resolution_hz
RMT tick resolution, if set to zero, a default resolution (10MHz) will be applied
struct led_strip_rmt_config_t::led_strip_rmt_extra_config
Variables:
- uint32_t with_dma
Use DMA to transmit data
Functions Documentation
function led_strip_new_rmt_device
Create LED strip based on RMT TX channel.
esp_err_t led_strip_new_rmt_device (
const led_strip_config_t *led_config,
const led_strip_rmt_config_t *rmt_config,
led_strip_handle_t *ret_strip
)
Parameters:
led_config
LED strip configurationrmt_config
RMT specific configurationret_strip
Returned LED strip handle
Returns:
- ESP_OK: create LED strip handle successfully
- ESP_ERR_INVALID_ARG: create LED strip handle failed because of invalid argument
- ESP_ERR_NO_MEM: create LED strip handle failed because of out of memory
- ESP_FAIL: create LED strip handle failed because some other error
File include/led_strip_spi.h
Structures and Types
Type | Name |
---|---|
struct | led_strip_spi_config_t LED Strip SPI specific configuration. |
Functions
Type | Name |
---|---|
esp_err_t | led_strip_new_spi_device (const led_strip_config_t *led_config, const led_strip_spi_config_t *spi_config, led_strip_handle_t *ret_strip) Create LED strip based on SPI MOSI channel. |
Structures and Types Documentation
struct led_strip_spi_config_t
LED Strip SPI specific configuration.
Variables:
-
spi_clock_source_t clk_src
SPI clock source -
struct led_strip_spi_config_t flags
Extra driver flags -
spi_host_device_t spi_bus
SPI bus ID. Which buses are available depends on the specific chip -
uint32_t with_dma
Use DMA to transmit data
Functions Documentation
function led_strip_new_spi_device
Create LED strip based on SPI MOSI channel.
esp_err_t led_strip_new_spi_device (
const led_strip_config_t *led_config,
const led_strip_spi_config_t *spi_config,
led_strip_handle_t *ret_strip
)
Note:
Although only the MOSI line is used for generating the signal, the whole SPI bus can't be used for other purposes.
Parameters:
led_config
LED strip configurationspi_config
SPI specific configurationret_strip
Returned LED strip handle
Returns:
- ESP_OK: create LED strip handle successfully
- ESP_ERR_INVALID_ARG: create LED strip handle failed because of invalid argument
- ESP_ERR_NOT_SUPPORTED: create LED strip handle failed because of unsupported configuration
- ESP_ERR_NO_MEM: create LED strip handle failed because of out of memory
- ESP_FAIL: create LED strip handle failed because some other error
File include/led_strip_types.h
Structures and Types
Type | Name |
---|---|
union | led_color_component_format_t LED color component format. |
struct | format_layout |
enum | led_model_t LED strip model. |
struct | led_strip_config_t LED Strip common configurations The common configurations are not specific to any backend peripheral. |
struct | led_strip_extra_flags |
typedef struct led_strip_t * | led_strip_handle_t Type of LED strip handle. |
Macros
Type | Name |
---|---|
define | LED_STRIP_COLOR_COMPONENT_FMT_GRB (led_color_component_format_t){.format = {.r_pos = 1, .g_pos = 0, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 3}} Helper macros to set the color component format. |
define | LED_STRIP_COLOR_COMPONENT_FMT_GRBW (led_color_component_format_t){.format = {.r_pos = 1, .g_pos = 0, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 4}} |
define | LED_STRIP_COLOR_COMPONENT_FMT_RGB (led_color_component_format_t){.format = {.r_pos = 0, .g_pos = 1, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 3}} |
define | LED_STRIP_COLOR_COMPONENT_FMT_RGBW (led_color_component_format_t){.format = {.r_pos = 0, .g_pos = 1, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 4}} |
Structures and Types Documentation
union led_color_component_format_t
LED color component format.
Note:
The format is used to specify the order of color components in each pixel, also the number of color components.
Variables:
-
struct led_color_component_format_t::format_layout format
Format layout -
uint32_t format_id
Format ID
struct led_color_component_format_t::format_layout
Variables:
-
uint32_t b_pos
Position of the blue channel in the color order: 0~3 -
uint32_t g_pos
Position of the green channel in the color order: 0~3 -
uint32_t num_components
Number of color components per pixel: 3 or 4. If set to 0, it will fallback to 3 -
uint32_t r_pos
Position of the red channel in the color order: 0~3 -
uint32_t reserved
Reserved -
uint32_t w_pos
Position of the white channel in the color order: 0~3
enum led_model_t
LED strip model.
enum led_model_t {
LED_MODEL_WS2812,
LED_MODEL_SK6812,
LED_MODEL_WS2811,
LED_MODEL_INVALID
};
Note:
Different led model may have different timing parameters, so we need to distinguish them.
struct led_strip_config_t
LED Strip common configurations The common configurations are not specific to any backend peripheral.
Variables:
-
led_color_component_format_t color_component_format
Specifies the order of color components in each pixel. Use helper macros likeLED_STRIP_COLOR_COMPONENT_FMT_GRB
to set the format LED strip extra driver flags -
struct led_strip_config_t::led_strip_extra_flags flags
Extra driver flags -
led_model_t led_model
Specifies the LED strip model (e.g., WS2812, SK6812) -
uint32_t max_leds
Maximum number of LEDs that can be controlled in a single strip -
int strip_gpio_num
GPIO number that used by LED strip
struct led_strip_config_t::led_strip_extra_flags
Variables:
- uint32_t invert_out
Invert output signal
typedef led_strip_handle_t
Type of LED strip handle.
typedef struct led_strip_t* led_strip_handle_t;
Macros Documentation
define LED_STRIP_COLOR_COMPONENT_FMT_GRB
Helper macros to set the color component format.
#define LED_STRIP_COLOR_COMPONENT_FMT_GRB ( led_color_component_format_t ){.format = {.r_pos = 1, .g_pos = 0, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 3}}
define LED_STRIP_COLOR_COMPONENT_FMT_GRBW
#define LED_STRIP_COLOR_COMPONENT_FMT_GRBW ( led_color_component_format_t ){.format = {.r_pos = 1, .g_pos = 0, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 4}}
define LED_STRIP_COLOR_COMPONENT_FMT_RGB
#define LED_STRIP_COLOR_COMPONENT_FMT_RGB ( led_color_component_format_t ){.format = {.r_pos = 0, .g_pos = 1, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 3}}
define LED_STRIP_COLOR_COMPONENT_FMT_RGBW
#define LED_STRIP_COLOR_COMPONENT_FMT_RGBW ( led_color_component_format_t ){.format = {.r_pos = 0, .g_pos = 1, .b_pos = 2, .w_pos = 3, .reserved = 0, .num_components = 4}}
File interface/led_strip_interface.h
Structures and Types
Type | Name |
---|---|
struct | led_strip_t LED strip interface definition. |
typedef struct led_strip_t | led_strip_t |
Structures and Types Documentation
struct led_strip_t
LED strip interface definition.
Variables:
- esp_err_t(* clear
Clear LED strip (turn off all LEDs)
Parameters:
strip
LED striptimeout_ms
timeout value for clearing task
Returns:
- ESP_OK: Clear LEDs successfully
- ESP_FAIL: Clear LEDs failed because some other error occurred
- esp_err_t(* del
Free LED strip resources.
Parameters:
strip
LED strip
Returns:
- ESP_OK: Free resources successfully
- ESP_FAIL: Free resources failed because error occurred
- esp_err_t(* refresh
Refresh memory colors to LEDs.
Parameters:
strip
LED striptimeout_ms
timeout value for refreshing task
Returns:
- ESP_OK: Refresh successfully
- ESP_FAIL: Refresh failed because some other error occurred
Note:
: After updating the LED colors in the memory, a following invocation of this API is needed to flush colors to strip.
- esp_err_t(* set_pixel
Set RGB for a specific pixel.
Parameters:
strip
LED stripindex
index of pixel to setred
red part of colorgreen
green part of colorblue
blue part of color
Returns:
- ESP_OK: Set RGB for a specific pixel successfully
- ESP_ERR_INVALID_ARG: Set RGB for a specific pixel failed because of invalid parameters
- ESP_FAIL: Set RGB for a specific pixel failed because other error occurred
- esp_err_t(* set_pixel_rgbw
Set RGBW for a specific pixel. Similar toset_pixel
_ but also set the white component._
Parameters:
strip
LED stripindex
index of pixel to setred
red part of colorgreen
green part of colorblue
blue part of colorwhite
separate white component
Returns:
- ESP_OK: Set RGBW color for a specific pixel successfully
- ESP_ERR_INVALID_ARG: Set RGBW color for a specific pixel failed because of an invalid argument
- ESP_FAIL: Set RGBW color for a specific pixel failed because other error occurred
typedef led_strip_t
typedef struct led_strip_t led_strip_t;
Type of LED strip