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

@@ -3,13 +3,8 @@ include($ENV{IDF_PATH}/tools/cmake/version.cmake)
 set(srcs "src/led_strip_api.c" "src/led_strip_common.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,30 @@ 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
+    .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
-    .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 */
+    .num_color_components = 3,     // Each pixel has 3 color components: R,G,B
+    .color_component_order = LED_STRIP_SET_RGB_ORDER(1, 0, 2), // Component order: 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 +55,29 @@ 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
+    .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
-    .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 */
+    .num_color_components = 3,     // Each pixel has 3 color components: R,G,B
+    .color_component_order = LED_STRIP_SET_RGB_ORDER(1, 0, 2), // Component order: 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
 
@@ -352,8 +311,16 @@ Although only the MOSI line is used for generating the signal, the whole SPI bus
 | Type | Name |
 | ---: | :--- |
 | 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\_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)._ |
 
 ## Structures and Types Documentation
 
@@ -375,40 +342,92 @@ 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
+- uint8\_t color_component_order  <br>Specifies the order of color components in each pixel. Use helper macros LED\_STRIP\_SET\_RGB\_ORDER or LED\_STRIP\_SET\_RGBW\_ORDER to set the order. Set to 0 to use the default order. 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>LED model
+- [**led\_model\_t**](#enum-led_model_t) led_model  <br>Specifies the LED strip model (e.g., WS2812, SK6812)
 
-- uint32\_t max_leds  <br>Maximum LEDs in a single strip
+- uint32\_t max_leds  <br>Maximum number of LEDs that can be controlled in a single strip
 
-- uint8\_t pixel_order  
+- uint8\_t num_color_components  <br>Number of color components per LED pixel. Use 3 for RGB (Red, Green, Blue) or 4 for RGBW (Red, Green, Blue, White). If set to 0, the driver will default to 3 (RGB).
 
 - int strip_gpio_num  <br>GPIO number that used by LED strip
 
+### struct `led_strip_config_t::led_strip_extra_flags`
+
+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_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 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: '../../../'

led_strip/examples/led_strip_rmt_ws2812/main/led_strip_rmt_ws2812_main.c

@@ -23,24 +23,24 @@ led_strip_handle_t configure_led(void)
 {
     // LED strip general initialization, according to your led board design
     led_strip_config_t strip_config = {
-        .strip_gpio_num = LED_STRIP_GPIO_PIN,   // The GPIO that connected to the LED strip's data line
-        .max_leds = LED_STRIP_LED_COUNT,        // 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
-        .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 = LED_STRIP_GPIO_PIN, // The GPIO that connected to the LED strip's data line
+        .max_leds = LED_STRIP_LED_COUNT,      // The number of LEDs in the strip,
+        .led_model = LED_MODEL_WS2812,        // LED strip model
+        .num_color_components = 3,            // Each pixel has 3 color components: R,G,B
+        .color_component_order = LED_STRIP_SET_RGB_ORDER(1, 0, 2), // Component order: G,R,B
+        .flags = {
+            .invert_out = false, // don't invert the output signal
+        }
     };
 
     // LED strip backend configuration: RMT
     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 = LED_STRIP_RMT_RES_HZ, // RMT counter clock frequency
-        .flags.with_dma = false,               // DMA feature is available on ESP target like ESP32-S3
-#endif
+        .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
+        }
     };
 
     // LED Strip object handle

led_strip/examples/led_strip_spi_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_spi_ws2812)