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

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 strip
• index index of pixel to set
• red red part of color
• green green part of color
• blue 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 strip
• index index of pixel to set
• hue 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 strip
• index index of pixel to set
• red red part of color
• green green part of color
• blue blue part of color
• white 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

Functions

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 configuration
• rmt_config RMT specific configuration
• ret_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

Functions

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 configuration
• spi_config SPI specific configuration
• ret_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

Macros

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 like LED_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

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 strip
• timeout_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 strip
• timeout_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 strip
• index index of pixel to set
• red red part of color
• green green part of color
• blue 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 to set_pixel_ but also set the white component._
  Parameters:

• strip LED strip
• index index of pixel to set
• red red part of color
• green green part of color
• blue blue part of color
• white 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