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

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/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)

led_strip/examples/led_strip_spi_ws2812/main/idf_component.yml

@@ -1,6 +1,6 @@
 ## IDF Component Manager Manifest File
 dependencies:
   espressif/led_strip:
-    version: '^2.4'
+    version: '^3'
     override_path: '../../../'
   idf: ">=5.1"

led_strip/examples/led_strip_spi_ws2812/main/led_strip_spi_ws2812_main.c

@@ -21,20 +21,23 @@ 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: SPI
     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
+        .flags = {
+            .with_dma = true, // Using DMA can improve performance and help drive more LEDs
+        }
     };
 
     // LED Strip object handle

led_strip/idf_component.yml

@@ -1,5 +1,7 @@
-version: "2.5.6"
+version: "3.0.0"
 description: Driver for Addressable LED Strip (WS2812, etc)
 url: https://github.com/espressif/idf-extra-components/tree/master/led_strip
+issues: https://github.com/espressif/idf-extra-components/issues
+repository: https://github.com/espressif/idf-extra-components.git
 dependencies:
-  idf: ">=4.4"
+  idf: ">=5.0"

led_strip/include/led_strip.h

@@ -8,39 +8,12 @@
 #include <stdint.h>
 #include "esp_err.h"
 #include "led_strip_rmt.h"
-#include "esp_idf_version.h"
-
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 1, 0)
 #include "led_strip_spi.h"
-#endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- * @brief 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.
- *        The positions are counted from the least significant bit (LSB).
- * @param R The position of the red channel in the color order.
- * @param G The position of the green channel in the color order.
- * @param 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.
- */
-#define LED_STRIP_SET_RGB_ORDER(R, G, B) (R << 0 | G << 2 | B << 4)
-
-/**
- * @brief 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.
- *        The positions are counted from the least significant bit (LSB).
- * @param R The position of the red channel in the color order.
- * @param G The position of the green channel in the color order.
- * @param B The position of the blue channel in the color order.
- * @param 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_RGBW_ORDER(R, G, B, W) (R << 0 | G << 2 | B << 4 | W << 6)
-
 /**
  * @brief Set RGB for a specific pixel
  *

led_strip/include/led_strip_rmt.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -9,10 +9,7 @@
 #include "esp_err.h"
 #include "led_strip_types.h"
 #include "esp_idf_version.h"
-
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0)
 #include "driver/rmt_types.h"
-#endif
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,14 +19,11 @@ extern "C" {
  * @brief LED Strip RMT specific configuration
  */
 typedef struct {
-#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(5, 0, 0)
-    uint8_t rmt_channel;        /*!< Specify the channel number, the legacy RMT driver doesn't support channel allocator */
-#else // new driver supports specify the clock source and clock resolution
     rmt_clock_source_t clk_src; /*!< RMT clock source */
     uint32_t resolution_hz;     /*!< RMT tick resolution, if set to zero, a default resolution (10MHz) will be applied */
-#endif
     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. */
-    struct {
+    /*!< Extra RMT specific driver flags */
+    struct led_strip_rmt_extra_config {
         uint32_t with_dma: 1;   /*!< Use DMA to transmit data */
     } flags;                    /*!< Extra driver flags */
 } led_strip_rmt_config_t;

led_strip/include/led_strip_spi.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -27,6 +27,7 @@ typedef struct {
 
 /**
  * @brief Create LED strip based on SPI MOSI channel
+ *
  * @note Although only the MOSI line is used for generating the signal, the whole SPI bus can't be used for other purposes.
  *
  * @param led_config LED strip configuration

led_strip/include/led_strip_types.h

@@ -11,6 +11,11 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Type of LED strip handle
+ */
+typedef struct led_strip_t *led_strip_handle_t;
+
 /**
  * @brief LED strip model
  * @note Different led model may have different timing parameters, so we need to distinguish them.
@@ -22,24 +27,46 @@ typedef enum {
 } led_model_t;
 
 /**
- * @brief LED strip handle
+ * @brief 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.
+ *        The positions are counted from the least significant bit (LSB).
+ * @param R The position of the red channel in the color order.
+ * @param G The position of the green channel in the color order.
+ * @param 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.
  */
-typedef struct led_strip_t *led_strip_handle_t;
+#define LED_STRIP_SET_RGB_ORDER(R, G, B) (R << 0 | G << 2 | B << 4)
+
+/**
+ * @brief 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.
+ *        The positions are counted from the least significant bit (LSB).
+ * @param R The position of the red channel in the color order.
+ * @param G The position of the green channel in the color order.
+ * @param B The position of the blue channel in the color order.
+ * @param 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_RGBW_ORDER(R, G, B, W) (R << 0 | G << 2 | B << 4 | W << 6)
 
 /**
- * @brief LED Strip Configuration
+ * @brief LED Strip common configurations
+ *        The common configurations are not specific to any backend peripheral.
  */
 typedef struct {
-    int strip_gpio_num;      /*!< GPIO number that used by LED strip */
-    uint32_t max_leds;       /*!< Maximum LEDs in a single strip */
-    uint8_t bytes_per_pixel; /*!< bytes per LED pixel. Should be 3 or 4 */
-    led_model_t led_model;   /*!< LED model */
-    uint8_t pixel_order; /*! 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. */
-    struct {
+    int strip_gpio_num;           /*!< GPIO number that used by LED strip */
+    uint32_t max_leds;            /*!< Maximum number of LEDs that can be controlled in a single strip */
+    led_model_t led_model;        /*!< Specifies the LED strip model (e.g., WS2812, SK6812) */
+    uint8_t num_color_components; /*!< 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). */
+    uint8_t color_component_order; /*!< 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_extra_flags {
         uint32_t invert_out: 1; /*!< Invert output signal */
-    } flags;                    /*!< Extra driver flags */
+    } flags; /*!< Extra driver flags */
 } led_strip_config_t;
 
 #ifdef __cplusplus