From 1bceed71a654be550c140212ba9ddd790b0f5273 Mon Sep 17 00:00:00 2001 From: morris Date: Mon, 12 Aug 2024 10:49:52 +0800 Subject: [PATCH] change(led_strip): clean up component dependency Starting from esp-idf v5.3, the RMT and SPI drivers are moved to separate components --- led_strip/CHANGELOG.md | 16 ++ led_strip/CMakeLists.txt | 15 +- led_strip/api.md | 335 +++++++++++++----------------------- led_strip/idf_component.yml | 2 +- 4 files changed, 148 insertions(+), 220 deletions(-) diff --git a/led_strip/CHANGELOG.md b/led_strip/CHANGELOG.md index 51c0cd30c3..66906b6c71 100644 --- a/led_strip/CHANGELOG.md +++ b/led_strip/CHANGELOG.md @@ -1,3 +1,19 @@ +## 2.5.5 + +- Simplified the led_strip component dependency, the time of full build with ESP-IDF v5.3 can now be shorter. + +## 2.5.4 + +- Inserted extra delay when initialize the SPI LED device, to ensure all LEDs are in the reset state correctly + +## 2.5.3 + +- Extend reset time (280us) to support WS2812B-V5 + +## 2.5.2 + +- Added API reference doc (api.md) + ## 2.5.0 - Enabled support for IDF4.4 and above diff --git a/led_strip/CMakeLists.txt b/led_strip/CMakeLists.txt index 37950cf014..a4e576be7a 100644 --- a/led_strip/CMakeLists.txt +++ b/led_strip/CMakeLists.txt @@ -1,22 +1,31 @@ include($ENV{IDF_PATH}/tools/cmake/version.cmake) set(srcs "src/led_strip_api.c") +set(public_requires) +# Starting from esp-idf v5.x, the RMT driver is rewritten if("${IDF_VERSION_MAJOR}.${IDF_VERSION_MINOR}" VERSION_GREATER_EQUAL "5.0") if(CONFIG_SOC_RMT_SUPPORTED) list(APPEND srcs "src/led_strip_rmt_dev.c" "src/led_strip_rmt_encoder.c") endif() -else() +else() list(APPEND srcs "src/led_strip_rmt_dev_idf4.c") endif() -# the SPI backend driver relies on something that was added in IDF 5.1 +# the SPI backend driver relies on some feature that was available in IDF 5.1 if("${IDF_VERSION_MAJOR}.${IDF_VERSION_MINOR}" VERSION_GREATER_EQUAL "5.1") if(CONFIG_SOC_GPSPI_SUPPORTED) list(APPEND srcs "src/led_strip_spi_dev.c") endif() endif() +# Starting from esp-idf v5.3, the RMT and SPI drivers are moved to separate components +if("${IDF_VERSION_MAJOR}.${IDF_VERSION_MINOR}" VERSION_GREATER_EQUAL "5.3") + list(APPEND public_requires "esp_driver_rmt" "esp_driver_spi") +else() + list(APPEND public_requires "driver") +endif() + idf_component_register(SRCS ${srcs} INCLUDE_DIRS "include" "interface" - REQUIRES "driver") + REQUIRES ${public_requires}) diff --git a/led_strip/api.md b/led_strip/api.md index 37648ace08..8fc04af4f4 100644 --- a/led_strip/api.md +++ b/led_strip/api.md @@ -10,11 +10,6 @@ ## File include/led_strip.h - - - - - ## Functions | Type | Name | @@ -26,86 +21,73 @@ | esp\_err\_t | [**led\_strip\_set\_pixel\_hsv**](#function-led_strip_set_pixel_hsv) ([**led\_strip\_handle\_t**](#typedef-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**](#function-led_strip_set_pixel_rgbw) ([**led\_strip\_handle\_t**](#typedef-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)_ + ```c esp_err_t led_strip_clear ( led_strip_handle_t strip -) +) ``` - **Parameters:** - -* `strip` LED strip - +- `strip` LED strip **Returns:** +- ESP\_OK: Clear LEDs successfully +- ESP\_FAIL: Clear LEDs failed because some other error occurred - -* 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 - +- `strip` LED strip **Returns:** +- ESP\_OK: Free resources successfully +- ESP\_FAIL: Free resources failed because error occurred - -* 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 - +- `strip` LED strip **Returns:** - - -* ESP\_OK: Refresh successfully -* ESP\_FAIL: Refresh failed because some other error occurred - - - +- 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, @@ -113,30 +95,27 @@ esp_err_t led_strip_set_pixel ( 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 - +- `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\_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, @@ -144,30 +123,27 @@ esp_err_t led_strip_set_pixel_hsv ( 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) - +- `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 - -* 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, @@ -176,48 +152,34 @@ esp_err_t led_strip_set_pixel_rgbw ( 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) - - +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 - +- `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 - +- 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 | @@ -230,7 +192,6 @@ Also see `led_strip_set_pixel` if you only want to specify the RGB part of the c | ---: | :--- | | 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**](#typedef-led_strip_handle_t) \*ret\_strip)
_Create LED strip based on RMT TX channel._ | - ## Structures and Types Documentation ### struct `led_strip_rmt_config_t` @@ -239,55 +200,45 @@ _LED Strip RMT specific configuration._ Variables: -- rmt\_clock\_source\_t clk_src
RMT clock source +- rmt\_clock\_source\_t clk_src
RMT clock source -- struct led\_strip\_rmt\_config\_t::@0 flags
Extra driver flags +- 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. +- 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 +- 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._ + ```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 - +- `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 - +- 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 | @@ -300,7 +251,6 @@ esp_err_t led_strip_new_rmt_device ( | ---: | :--- | | 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**](#typedef-led_strip_handle_t) \*ret\_strip)
_Create LED strip based on SPI MOSI channel._ | - ## Structures and Types Documentation ### struct `led_strip_spi_config_t` @@ -309,60 +259,48 @@ _LED Strip SPI specific configuration._ Variables: -- spi\_clock\_source\_t clk_src
SPI clock source +- spi\_clock\_source\_t clk_src
SPI clock source -- struct led\_strip\_spi\_config\_t::@1 flags
Extra driver flags +- 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 +- 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._ + ```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 - +- `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 - +- 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 | @@ -372,13 +310,12 @@ Although only the MOSI line is used for generating the signal, the whole SPI bus | struct | [**led\_strip\_config\_t**](#struct-led_strip_config_t)
_LED Strip Configuration._ | | typedef struct [**led\_strip\_t**](#struct-led_strip_t) \* | [**led\_strip\_handle\_t**](#typedef-led_strip_handle_t)
_LED strip handle._ | - - ## Structures and Types Documentation ### enum `led_model_t` _LED strip model._ + ```c enum led_model_t { LED_MODEL_WS2812, @@ -387,13 +324,14 @@ enum led_model_t { }; ``` - **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, @@ -408,34 +346,28 @@ _LED Strip Configuration._ Variables: -- struct led\_strip\_config\_t::@2 flags
Extra driver flags +- struct led\_strip\_config\_t::@2 flags
Extra driver flags -- uint32\_t invert_out
Invert output signal +- uint32\_t invert_out
Invert output signal -- [**led\_model\_t**](#enum-led_model_t) led_model
LED model +- [**led\_model\_t**](#enum-led_model_t) led_model
LED model -- [**led\_pixel\_format\_t**](#enum-led_pixel_format_t) led_pixel_format
LED pixel format +- [**led\_pixel\_format\_t**](#enum-led_pixel_format_t) led_pixel_format
LED pixel format -- uint32\_t max_leds
Maximum LEDs in a single strip +- uint32\_t max_leds
Maximum LEDs in a single strip -- int strip_gpio_num
GPIO number that used by LED strip +- int strip_gpio_num
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 | @@ -443,8 +375,6 @@ typedef struct led_strip_t* led_strip_handle_t; | struct | [**led\_strip\_t**](#struct-led_strip_t)
_LED strip interface definition._ | | typedef struct [**led\_strip\_t**](#struct-led_strip_t) | [**led\_strip\_t**](#typedef-led_strip_t)
| - - ## Structures and Types Documentation ### struct `led_strip_t` @@ -453,90 +383,67 @@ _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 +- 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:** -* 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 - +- `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:** -* 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 - +- `strip` LED strip +- `timeout_ms` timeout value for refreshing task **Returns:** - - -* ESP\_OK: Refresh successfully -* ESP\_FAIL: Refresh failed because some other error occurred - - - +- 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 +- 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:** -* 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 - +- `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 +- 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` @@ -544,8 +451,4 @@ Variables: typedef struct led_strip_t led_strip_t; ``` - Type of LED strip - - - diff --git a/led_strip/idf_component.yml b/led_strip/idf_component.yml index deda1bc743..4928449549 100644 --- a/led_strip/idf_component.yml +++ b/led_strip/idf_component.yml @@ -1,4 +1,4 @@ -version: "2.5.4" +version: "2.5.5" description: Driver for Addressable LED Strip (WS2812, etc) url: https://github.com/espressif/idf-extra-components/tree/master/led_strip dependencies: