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

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::@0 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::@1 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::@2 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

API Reference

Header files

File include/led_strip.h

Functions

Functions Documentation

function led_strip_clear

function led_strip_del

function led_strip_refresh

function led_strip_set_pixel

function led_strip_set_pixel_hsv

function led_strip_set_pixel_rgbw

File include/led_strip_rmt.h

Structures and Types

Functions

Structures and Types Documentation

struct led_strip_rmt_config_t

Functions Documentation

function led_strip_new_rmt_device

File include/led_strip_spi.h

Structures and Types

Functions

Structures and Types Documentation

struct led_strip_spi_config_t

Functions Documentation

function led_strip_new_spi_device

File include/led_strip_types.h

Structures and Types

Structures and Types Documentation

enum led_model_t

enum led_pixel_format_t

struct led_strip_config_t

typedef led_strip_handle_t

File interface/led_strip_interface.h

Structures and Types

Structures and Types Documentation

struct led_strip_t

typedef led_strip_t

function `led_strip_clear`

function `led_strip_del`

function `led_strip_refresh`

function `led_strip_set_pixel`

function `led_strip_set_pixel_hsv`

function `led_strip_set_pixel_rgbw`

struct `led_strip_rmt_config_t`

function `led_strip_new_rmt_device`

struct `led_strip_spi_config_t`

function `led_strip_new_spi_device`

enum `led_model_t`

enum `led_pixel_format_t`

struct `led_strip_config_t`

typedef `led_strip_handle_t`

struct `led_strip_t`

typedef `led_strip_t`