feat(led_strip): discontinue esp-idf v4 and bump major version 🚀

Author: suda-morris

led_strip/CHANGELOG.md

@@ -1,7 +1,8 @@
-## 2.6.0
+## 3.0.0
+
+- Discontinued support for ESP-IDF v4.x
+- Added configuration for user-defined color component format
 
-- Add pixel order configuration to support user-defined pixel order.
-  
 ## 2.5.5
 
 - Simplified the led_strip component dependency, the time of full build with ESP-IDF v5.3 can now be shorter.

led_strip/CMakeLists.txt

@@ -1,15 +1,10 @@
 include($ENV{IDF_PATH}/tools/cmake/version.cmake)
 
-set(srcs "src/led_strip_api.c" "src/led_strip_common.c")
+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()
-    list(APPEND srcs "src/led_strip_rmt_dev_idf4.c")
+if(CONFIG_SOC_RMT_SUPPORTED)
+    list(APPEND srcs "src/led_strip_rmt_dev.c" "src/led_strip_rmt_encoder.c")
 endif()
 
 # the SPI backend driver relies on some feature that was available in IDF 5.1

led_strip/README.md

@@ -15,28 +15,29 @@ This is the most economical way to drive the LEDs because it only consumes one R
 ```c
 #define BLINK_GPIO 0
 
-led_strip_handle_t led_strip;
-
-/* LED strip initialization with the GPIO and pixels number*/
+/// LED strip common configuration
 led_strip_config_t strip_config = {
-    .strip_gpio_num = BLINK_GPIO, // The GPIO that connected to the LED strip's data line
-    .max_leds = 1, // The number of LEDs in the strip,
-    .bytes_per_pixel = 3, // 3 bytes per pixel of the LED strip
-    .led_model = LED_MODEL_WS2812, // LED strip model
-    .flags.invert_out = false, // whether to invert the output signal (useful when your hardware has a level inverter)
-    .pixel_order = LED_STRIP_SET_RGB_ORDER(1, 0, 2), /* The order of the pixel color. Not set or set to 0 if the default order is used.
-                                                        Here set to the default GRB order to demonstrate usage */
+    .strip_gpio_num = BLINK_GPIO,  // The GPIO that connected to the LED strip's data line
+    .max_leds = 1,                 // The number of LEDs in the strip,
+    .led_model = LED_MODEL_WS2812, // LED strip model, it determines the bit timing
+    .color_component_format = LED_STRIP_COLOR_COMPONENT_FMT_GRB, // The color component format is G-R-B
+    .flags = {
+        .invert_out = false, // don't invert the output signal
+    }
 };
 
+/// RMT backend specific configuration
 led_strip_rmt_config_t rmt_config = {
-#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(5, 0, 0)
-    .rmt_channel = 0,
-#else
-    .clk_src = RMT_CLK_SRC_DEFAULT, // different clock source can lead to different power consumption
-    .resolution_hz = 10 * 1000 * 1000, // 10MHz
-    .flags.with_dma = false, // whether to enable the DMA feature
-#endif
+    .clk_src = RMT_CLK_SRC_DEFAULT,    // different clock source can lead to different power consumption
+    .resolution_hz = 10 * 1000 * 1000, // RMT counter clock frequency: 10MHz
+    .mem_block_symbols = 64,           // the memory size of each RMT channel, in words (4 bytes)
+    .flags = {
+        .with_dma = false, // DMA feature is available on chips like ESP32-S3/P4
+    }
 };
+
+/// Create the LED strip object
+led_strip_handle_t led_strip;
 ESP_ERROR_CHECK(led_strip_new_rmt_device(&strip_config, &rmt_config, &led_strip));
 ```
 
@@ -53,24 +54,28 @@ Please note, the SPI backend has a dependency of **ESP-IDF >= 5.1**
 ```c
 #define BLINK_GPIO 0
 
-led_strip_handle_t led_strip;
-
-/* LED strip initialization with the GPIO and pixels number*/
+/// LED strip common configuration
 led_strip_config_t strip_config = {
-    .strip_gpio_num = BLINK_GPIO, // The GPIO that connected to the LED strip's data line
-    .max_leds = 1, // The number of LEDs in the strip,
-    .bytes_per_pixel = 3, // 3 bytes per pixel of the LED strip
-    .led_model = LED_MODEL_WS2812, // LED strip model
-    .flags.invert_out = false, // whether to invert the output signal (useful when your hardware has a level inverter)
-    .pixel_order = LED_STRIP_SET_RGB_ORDER(1, 0, 2), /* The order of the pixel color. Not set or set to 0 if the default order is used.
-                                                        Here set to the default GRB order to demonstrate usage */
+    .strip_gpio_num = BLINK_GPIO,  // The GPIO that connected to the LED strip's data line
+    .max_leds = 1,                 // The number of LEDs in the strip,
+    .led_model = LED_MODEL_WS2812, // LED strip model, it determines the bit timing
+    .color_component_format = LED_STRIP_COLOR_COMPONENT_FMT_GRB, // The color component format is G-R-B
+    .flags = {
+        .invert_out = false, // don't invert the output signal
+    }
 };
 
+/// SPI backend specific configuration
 led_strip_spi_config_t spi_config = {
     .clk_src = SPI_CLK_SRC_DEFAULT, // different clock source can lead to different power consumption
-    .flags.with_dma = true, // Using DMA can improve performance and help drive more LEDs
-    .spi_bus = SPI2_HOST,   // SPI bus ID
+    .spi_bus = SPI2_HOST,           // SPI bus ID
+    .flags = {
+        .with_dma = true, // Using DMA can improve performance and help drive more LEDs
+    }
 };
+
+/// Create the LED strip object
+led_strip_handle_t led_strip;
 ESP_ERROR_CHECK(led_strip_new_spi_device(&strip_config, &spi_config, &led_strip));
 ```
 

led_strip/api.md

@@ -21,13 +21,6 @@
 |  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) <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**](#typedef-led_strip_handle_t) strip, uint32\_t index, uint32\_t red, uint32\_t green, uint32\_t blue, uint32\_t white) <br>_Set RGBW for a specific pixel._ |
 
-## Macros
-
-| Type | Name |
-| ---: | :--- |
-| define  | [**LED\_STRIP\_SET\_RGBW\_ORDER**](#define-led_strip_set_rgbw_order) (R, G, B, W) (R &lt;&lt; 0 \| G &lt;&lt; 2 \| B &lt;&lt; 4 \| W &lt;&lt; 6)<br>_Help macro to set pixel RGBW color order The default order of the four-color LED strips is GRBW. If you have a different order, you can use the macro to set_ `pixel_order`_in_[_**led\_strip\_config\_t**_](#struct-led_strip_config_t)_. The positions are counted from the least significant bit (LSB)._ |
-| define  | [**LED\_STRIP\_SET\_RGB\_ORDER**](#define-led_strip_set_rgb_order) (R, G, B) (R &lt;&lt; 0 \| G &lt;&lt; 2 \| B &lt;&lt; 4)<br>_Help macro to set pixel RGB color order The default order of the three-color LED strips is GRB. If you have a different order, you can use the macro to set_ `pixel_order`_in_[_**led\_strip\_config\_t**_](#struct-led_strip_config_t)_. The positions are counted from the least significant bit (LSB)._ |
-
 ## Functions Documentation
 
 ### function `led_strip_clear`
@@ -185,52 +178,14 @@ Also see `led_strip_set_pixel` if you only want to specify the RGB part of the c
 - 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
 
-## Macros Documentation
-
-### define `LED_STRIP_SET_RGBW_ORDER`
-
-_Help macro to set pixel RGBW color order The default order of the four-color LED strips is GRBW. If you have a different order, you can use the macro to set_ `pixel_order`_in_[_**led\_strip\_config\_t**_](#struct-led_strip_config_t)_. The positions are counted from the least significant bit (LSB)._
-
-```c
-#define LED_STRIP_SET_RGBW_ORDER (R, G, B, W) (R << 0 | G << 2 | B << 4 | W << 6)
-```
-
-**Parameters:**
-
-- `R` The position of the red channel in the color order.
-- `G` The position of the green channel in the color order.
-- `B` The position of the blue channel in the color order.
-- `W` The position of the white channel in the color order.
-
-**Note:**
-
-The order starts from 0. And the user needs to make sure that all the numbers appear exactly once and are all less than the number of colors per pixel.
-
-### define `LED_STRIP_SET_RGB_ORDER`
-
-_Help macro to set pixel RGB color order The default order of the three-color LED strips is GRB. If you have a different order, you can use the macro to set_ `pixel_order`_in_[_**led\_strip\_config\_t**_](#struct-led_strip_config_t)_. The positions are counted from the least significant bit (LSB)._
-
-```c
-#define LED_STRIP_SET_RGB_ORDER (R, G, B) (R << 0 | G << 2 | B << 4)
-```
-
-**Parameters:**
-
-- `R` The position of the red channel in the color order.
-- `G` The position of the green channel in the color order.
-- `B` The position of the blue channel in the color order.
-
-**Note:**
-
-The order starts from 0. And the user needs to make sure that all the numbers appear exactly once and are all less than the number of colors per pixel.
-
 ## 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._ |
+| struct | [**led\_strip\_rmt\_extra\_config**](#struct-led_strip_rmt_config_tled_strip_rmt_extra_config) <br> |
 
 ## Functions
 
@@ -248,12 +203,16 @@ Variables:
 
 - rmt\_clock\_source\_t clk_src  <br>RMT clock source
 
-- struct led\_strip\_rmt\_config\_t::@0 flags  <br>Extra driver flags
+- struct [**led\_strip\_rmt\_config\_t::led\_strip\_rmt\_extra\_config**](#struct-led_strip_rmt_config_tled_strip_rmt_extra_config) 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.
+- 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. Extra RMT specific driver flags
 
 - uint32\_t resolution_hz  <br>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  <br>Use DMA to transmit data
 
 ## Functions Documentation
@@ -307,7 +266,7 @@ Variables:
 
 - spi\_clock\_source\_t clk_src  <br>SPI clock source
 
-- struct led\_strip\_spi\_config\_t::@1 flags  <br>Extra driver flags
+- 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
 
@@ -351,12 +310,54 @@ Although only the MOSI line is used for generating the signal, the whole SPI bus
 
 | Type | Name |
 | ---: | :--- |
+| union  | [**led\_color\_component\_format\_t**](#union-led_color_component_format_t)  <br>_LED color component format._ |
+| struct | [**format\_layout**](#struct-led_color_component_format_tformat_layout) <br> |
 | enum  | [**led\_model\_t**](#enum-led_model_t)  <br>_LED strip model._ |
-| 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._ |
+| struct | [**led\_strip\_config\_t**](#struct-led_strip_config_t) <br>_LED Strip common configurations The common configurations are not specific to any backend peripheral._ |
+| struct | [**led\_strip\_extra\_flags**](#struct-led_strip_config_tled_strip_extra_flags) <br> |
+| typedef struct [**led\_strip\_t**](#struct-led_strip_t) \* | [**led\_strip\_handle\_t**](#typedef-led_strip_handle_t)  <br>_Type of LED strip handle._ |
+
+## Macros
+
+| Type | Name |
+| ---: | :--- |
+| define  | [**LED\_STRIP\_COLOR\_COMPONENT\_FMT\_GRB**](#define-led_strip_color_component_fmt_grb)  ([**led\_color\_component\_format\_t**](#union-led_color_component_format_t)){.format = {.r\_pos = 1, .g\_pos = 0, .b\_pos = 2, .w\_pos = 3, .reserved = 0, .num\_components = 3}}<br>_Helper macros to set the color component format._ |
+| define  | [**LED\_STRIP\_COLOR\_COMPONENT\_FMT\_GRBW**](#define-led_strip_color_component_fmt_grbw)  ([**led\_color\_component\_format\_t**](#union-led_color_component_format_t)){.format = {.r\_pos = 1, .g\_pos = 0, .b\_pos = 2, .w\_pos = 3, .reserved = 0, .num\_components = 4}}<br> |
+| define  | [**LED\_STRIP\_COLOR\_COMPONENT\_FMT\_RGB**](#define-led_strip_color_component_fmt_rgb)  ([**led\_color\_component\_format\_t**](#union-led_color_component_format_t)){.format = {.r\_pos = 0, .g\_pos = 1, .b\_pos = 2, .w\_pos = 3, .reserved = 0, .num\_components = 3}}<br> |
+| define  | [**LED\_STRIP\_COLOR\_COMPONENT\_FMT\_RGBW**](#define-led_strip_color_component_fmt_rgbw)  ([**led\_color\_component\_format\_t**](#union-led_color_component_format_t)){.format = {.r\_pos = 0, .g\_pos = 1, .b\_pos = 2, .w\_pos = 3, .reserved = 0, .num\_components = 4}}<br> |
 
 ## 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**](#struct-led_color_component_format_tformat_layout) format  <br>Format layout
+
+- uint32\_t format_id  <br>Format ID
+
+### struct `led_color_component_format_t::format_layout`
+
+Variables:
+
+- uint32\_t b_pos  <br>Position of the blue channel in the color order: 0~3
+
+- uint32\_t g_pos  <br>Position of the green channel in the color order: 0~3
+
+- uint32\_t num_components  <br>Number of color components per pixel: 3 or 4. If set to 0, it will fallback to 3
+
+- uint32\_t r_pos  <br>Position of the red channel in the color order: 0~3
+
+- uint32\_t reserved  <br>Reserved
+
+- uint32\_t w_pos  <br>Position of the white channel in the color order: 0~3
+
 ### enum `led_model_t`
 
 _LED strip model._
@@ -375,40 +376,70 @@ Different led model may have different timing parameters, so we need to distingu
 
 ### struct `led_strip_config_t`
 
-_LED Strip Configuration._
+_LED Strip common configurations The common configurations are not specific to any backend peripheral._
 
 Variables:
 
-- uint8\_t bytes_per_pixel  <br>bytes per LED pixel. Should be 3 or 4
+- [**led\_color\_component\_format\_t**](#union-led_color_component_format_t) color_component_format  <br>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::@2 flags  <br>The order of the pixel color. Use help macro LED\_STRIP\_SET\_RGB\_ORDER or LED\_STRIP\_SET\_RGBW\_ORDER to set. Not set or set to 0 if the default order is used. Extra driver flags
+- struct [**led\_strip\_config\_t::led\_strip\_extra\_flags**](#struct-led_strip_config_tled_strip_extra_flags) flags  <br>Extra driver flags
 
-- uint32\_t invert_out  <br>Invert output signal
+- [**led\_model\_t**](#enum-led_model_t) led_model  <br>Specifies the LED strip model (e.g., WS2812, SK6812)
 
-- [**led\_model\_t**](#enum-led_model_t) led_model  <br>LED model
+- uint32\_t max_leds  <br>Maximum number of LEDs that can be controlled in a single strip
 
-- uint32\_t max_leds  <br>Maximum LEDs in a single strip
+- int strip_gpio_num  <br>GPIO number that used by LED strip
 
-- uint8\_t pixel_order  
+### struct `led_strip_config_t::led_strip_extra_flags`
 
-- int strip_gpio_num  <br>GPIO number that used by LED strip
+Variables:
+
+- uint32\_t invert_out  <br>Invert output signal
 
 ### typedef `led_strip_handle_t`
 
-_LED strip handle._
+_Type of LED strip handle._
 
 ```c
 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._
+
+```c
+#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`
+
+```c
+#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`
+
+```c
+#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`
+
+```c
+#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
 
 | 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> |
+| typedef struct led\_strip\_t | [**led\_strip\_t**](#typedef-led_strip_t)  <br> |
 
 ## Structures and Types Documentation
 

led_strip/examples/led_strip_rmt_ws2812/CMakeLists.txt

@@ -1,8 +1,6 @@
-# For more information about build system see
-# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
-# The following five lines of boilerplate have to be in your project's
-# CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.16)
 
+set(COMPONENTS main)
+
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(led_strip_rmt_ws2812)

led_strip/examples/led_strip_rmt_ws2812/main/idf_component.yml

@@ -1,5 +1,5 @@
 ## IDF Component Manager Manifest File
 dependencies:
   espressif/led_strip:
-    version: '^2'
+    version: '^3'
     override_path: '../../../'