455 lines
12 KiB
Markdown
455 lines
12 KiB
Markdown
|
# API Reference
|
||
|
|
|
||
|
|
## Header files
|
||
|
|
|
||
|
|
- [include/led_strip.h](#file-includeled_striph)
|
||
|
|
- [include/led_strip_rmt.h](#file-includeled_strip_rmth)
|
||
|
|
- [include/led_strip_spi.h](#file-includeled_strip_spih)
|
||
|
|
- [include/led_strip_types.h](#file-includeled_strip_typesh)
|
||
|
|
- [interface/led_strip_interface.h](#file-interfaceled_strip_interfaceh)
|
||
|
|
|
||
|
|
## File include/led_strip.h
|
||
|
|
|
||
|
|
## Functions
|
||
|
|
|
||
|
|
| Type | Name |
|
||
|
|
| ---: | :--- |
|
||
|
|
| esp\_err\_t | [**led\_strip\_clear**](#function-led_strip_clear) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip) <br>_Clear LED strip (turn off all LEDs)_ |
|
||
|
|
| esp\_err\_t | [**led\_strip\_del**](#function-led_strip_del) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip) <br>_Free LED strip resources._ |
|
||
|
|
| esp\_err\_t | [**led\_strip\_refresh**](#function-led_strip_refresh) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip) <br>_Refresh memory colors to LEDs._ |
|
||
|
|
| esp\_err\_t | [**led\_strip\_set\_pixel**](#function-led_strip_set_pixel) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip, uint32\_t index, uint32\_t red, uint32\_t green, uint32\_t blue) <br>_Set RGB for a specific pixel._ |
|
||
|
|
| esp\_err\_t | [**led\_strip\_set\_pixel\_hsv**](#function-led_strip_set_pixel_hsv) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip, uint32\_t index, uint16\_t hue, uint8\_t saturation, uint8\_t value) <br>_Set HSV for a specific pixel._ |
|
||
|
|
| esp\_err\_t | [**led\_strip\_set\_pixel\_rgbw**](#function-led_strip_set_pixel_rgbw) ([**led\_strip\_handle\_t**](#struct-led_strip_t) strip, uint32\_t index, uint32\_t red, uint32\_t green, uint32\_t blue, uint32\_t white) <br>_Set RGBW for a specific pixel._ |
|
||
|
|
|
||
|
|
## Functions Documentation
|
||
|
|
|
||
|
|
### function `led_strip_clear`
|
||
|
|
|
||
|
|
_Clear LED strip (turn off all LEDs)_
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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**](#struct-led_strip_rmt_config_t) <br>_LED Strip RMT specific configuration._ |
|
||
|
|
|
||
|
|
## Functions
|
||
|
|
|
||
|
|
| Type | Name |
|
||
|
|
| ---: | :--- |
|
||
|
|
| esp\_err\_t | [**led\_strip\_new\_rmt\_device**](#function-led_strip_new_rmt_device) (const [**led\_strip\_config\_t**](#struct-led_strip_config_t) \*led\_config, const [**led\_strip\_rmt\_config\_t**](#struct-led_strip_rmt_config_t) \*rmt\_config, [**led\_strip\_handle\_t**](#struct-led_strip_t) \*ret\_strip) <br>_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 <br>RMT clock source
|
||
|
|
|
||
|
|
- struct [**led\_strip\_rmt\_config\_t**](#struct-led_strip_rmt_config_t) flags <br>Extra driver flags
|
||
|
|
|
||
|
|
- size\_t mem_block_symbols <br>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 <br>RMT tick resolution, if set to zero, a default resolution (10MHz) will be applied
|
||
|
|
|
||
|
|
- uint32\_t with_dma <br>Use DMA to transmit data
|
||
|
|
|
||
|
|
## Functions Documentation
|
||
|
|
|
||
|
|
### function `led_strip_new_rmt_device`
|
||
|
|
|
||
|
|
_Create LED strip based on RMT TX channel._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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**](#struct-led_strip_spi_config_t) <br>_LED Strip SPI specific configuration._ |
|
||
|
|
|
||
|
|
## Functions
|
||
|
|
|
||
|
|
| Type | Name |
|
||
|
|
| ---: | :--- |
|
||
|
|
| esp\_err\_t | [**led\_strip\_new\_spi\_device**](#function-led_strip_new_spi_device) (const [**led\_strip\_config\_t**](#struct-led_strip_config_t) \*led\_config, const [**led\_strip\_spi\_config\_t**](#struct-led_strip_spi_config_t) \*spi\_config, [**led\_strip\_handle\_t**](#struct-led_strip_t) \*ret\_strip) <br>_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 <br>SPI clock source
|
||
|
|
|
||
|
|
- struct [**led\_strip\_spi\_config\_t**](#struct-led_strip_spi_config_t) flags <br>Extra driver flags
|
||
|
|
|
||
|
|
- spi\_host\_device\_t spi_bus <br>SPI bus ID. Which buses are available depends on the specific chip
|
||
|
|
|
||
|
|
- uint32\_t with_dma <br>Use DMA to transmit data
|
||
|
|
|
||
|
|
## Functions Documentation
|
||
|
|
|
||
|
|
### function `led_strip_new_spi_device`
|
||
|
|
|
||
|
|
_Create LED strip based on SPI MOSI channel._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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**](#enum-led_model_t) <br>_LED strip model._ |
|
||
|
|
| enum | [**led\_pixel\_format\_t**](#enum-led_pixel_format_t) <br>_LED strip pixel format._ |
|
||
|
|
| struct | [**led\_strip\_config\_t**](#struct-led_strip_config_t) <br>_LED Strip Configuration._ |
|
||
|
|
| typedef struct [**led\_strip\_t**](#struct-led_strip_t) \* | [**led\_strip\_handle\_t**](#typedef-led_strip_handle_t) <br>_LED strip handle._ |
|
||
|
|
|
||
|
|
## Structures and Types Documentation
|
||
|
|
|
||
|
|
### enum `led_model_t`
|
||
|
|
|
||
|
|
_LED strip model._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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._
|
||
|
|
|
||
|
|
```c
|
||
|
|
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**](#struct-led_strip_config_t) flags <br>Extra driver flags
|
||
|
|
|
||
|
|
- uint32\_t invert_out <br>Invert output signal
|
||
|
|
|
||
|
|
- led\_model\_t led_model <br>LED model
|
||
|
|
|
||
|
|
- led\_pixel\_format\_t led_pixel_format <br>LED pixel format
|
||
|
|
|
||
|
|
- uint32\_t max_leds <br>Maximum LEDs in a single strip
|
||
|
|
|
||
|
|
- int strip_gpio_num <br>GPIO number that used by LED strip
|
||
|
|
|
||
|
|
### typedef `led_strip_handle_t`
|
||
|
|
|
||
|
|
_LED strip handle._
|
||
|
|
|
||
|
|
```c
|
||
|
|
typedef struct led_strip_t* led_strip_handle_t;
|
||
|
|
```
|
||
|
|
|
||
|
|
## File interface/led_strip_interface.h
|
||
|
|
|
||
|
|
## Structures and Types
|
||
|
|
|
||
|
|
| Type | Name |
|
||
|
|
| ---: | :--- |
|
||
|
|
| struct | [**led\_strip\_t**](#struct-led_strip_t) <br>_LED strip interface definition._ |
|
||
|
|
| typedef struct [**led\_strip\_t**](#struct-led_strip_t) | [**led\_strip\_t**](#typedef-led_strip_t) <br> |
|
||
|
|
|
||
|
|
## Structures and Types Documentation
|
||
|
|
|
||
|
|
### struct `led_strip_t`
|
||
|
|
|
||
|
|
_LED strip interface definition._
|
||
|
|
|
||
|
|
Variables:
|
||
|
|
|
||
|
|
- esp\_err\_t(\* clear <br>_Clear LED strip (turn off all LEDs)_<br>**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 <br>_Free LED strip resources._<br>**Parameters:**
|
||
|
|
|
||
|
|
- `strip` LED strip
|
||
|
|
|
||
|
|
**Returns:**
|
||
|
|
|
||
|
|
- ESP\_OK: Free resources successfully
|
||
|
|
- ESP\_FAIL: Free resources failed because error occurred
|
||
|
|
|
||
|
|
- esp\_err\_t(\* refresh <br>_Refresh memory colors to LEDs._<br>**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 <br>_Set RGB for a specific pixel._<br>**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 <br>_Set RGBW for a specific pixel. Similar to_ `set_pixel`_but also set the white component._<br>**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`
|
||
|
|
|
||
|
|
```c
|
||
|
|
typedef struct led_strip_t led_strip_t;
|
||
|
|
```
|
||
|
|
|
||
|
|
Type of LED strip
|