ESP-Nodes/ESP32-IDF_ePaper/managed_components/espressif__led_strip/api.md

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 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)
• value value part of color (0 - 255)

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

Type	Name
struct	led_strip_rmt_config_t LED Strip RMT specific configuration.

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

• uint32_t resolution_hz
  RMT tick resolution, if set to zero, a default resolution (10MHz) will be applied

• 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

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

Type	Name
enum	led_model_t LED strip model.
enum	led_pixel_format_t LED strip pixel format.
struct	led_strip_config_t LED Strip Configuration.
typedef struct led_strip_t *	led_strip_handle_t LED strip handle.

Structures and Types Documentation

enum led_model_t

LED strip model.

enum led_model_t {
    LED_MODEL_WS2812,
    LED_MODEL_SK6812,
    LED_MODEL_INVALID
};

Note:

Different led model may have different timing parameters, so we need to distinguish them.

enum led_pixel_format_t

LED strip pixel format.

enum led_pixel_format_t {
    LED_PIXEL_FORMAT_GRB,
    LED_PIXEL_FORMAT_GRBW,
    LED_PIXEL_FORMAT_INVALID
};

struct led_strip_config_t

LED Strip Configuration.

Variables:

• struct led_strip_config_t flags
  Extra driver flags

• uint32_t invert_out
  Invert output signal

• led_model_t led_model
  LED model

• led_pixel_format_t led_pixel_format
  LED pixel format

• uint32_t max_leds
  Maximum LEDs in a single strip

• int strip_gpio_num
  GPIO number that used by LED strip

typedef led_strip_handle_t

LED strip handle.

typedef struct led_strip_t* led_strip_handle_t;

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 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_pixelbut 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