feat(led_indicator): Update docs, examples and standardize comments

zhongchaoesp · zhongchaoesp · commit 0b89351cae59 · 2025-06-18T19:26:43.000+08:00
diff --git a/components/led/led_indicator/include/led_custom.h b/components/led/led_indicator/include/led_custom.h
@@ -34,8 +34,6 @@ typedef struct {
 /**
  * @brief Create a new custom LED indicator device.
  *
- * This function initializes a new LED indicator device using the provided LED configuration
- * and custom configuration parameters.
  *
  * @param led_config    Pointer to the LED configuration structure.
  * @param custom_cfg    Pointer to the custom configuration structure for the LED indicator.
diff --git a/components/led/led_indicator/include/led_gpio.h b/components/led/led_indicator/include/led_gpio.h
@@ -58,9 +58,6 @@ esp_err_t led_indicator_gpio_set_on_off(void *handle, bool on_off);
 /**
  * @brief Create a new LED indicator device using a GPIO pin.
  *
- * This function initializes a new LED indicator device based on the provided LED configuration
- * and GPIO configuration. It returns a handle to the created LED indicator device, which can be
- * used for further control and management.
  *
  * @param led_config   Pointer to the LED configuration structure.
  * @param gpio_cfg     Pointer to the GPIO configuration structure for the LED.
diff --git a/components/led/led_indicator/include/led_ledc.h b/components/led/led_indicator/include/led_ledc.h
@@ -69,8 +69,6 @@ esp_err_t led_indicator_ledc_set_brightness(void *ledc_handle, uint32_t brightne
 /**
  * @brief Create a new LED indicator device using the LEDC (LED Controller) peripheral.
  *
- * This function initializes a new LED indicator device with the specified configuration,
- * utilizing the ESP32's LEDC hardware for PWM control.
  *
  * @param led_config   Pointer to the general LED configuration structure.
  * @param ledc_cfg     Pointer to the LEDC-specific configuration structure.
diff --git a/components/led/led_indicator/include/led_rgb.h b/components/led/led_indicator/include/led_rgb.h
@@ -101,8 +101,6 @@ esp_err_t led_indicator_rgb_set_brightness(void *rgb_handle, uint32_t brightness
 /**
  * @brief Create a new RGB LED device instance.
  *
- * This function initializes a new RGB LED device using the specified LED configuration
- * and RGB-specific configuration parameters.
  *
  * @param led_config Pointer to the general LED configuration structure.
  * @param rgb_cfg Pointer to the RGB-specific configuration structure.
diff --git a/components/led/led_indicator/include/led_strips.h b/components/led/led_indicator/include/led_strips.h
@@ -111,8 +111,6 @@ esp_err_t led_indicator_strips_set_brightness(void *strips, uint32_t ibrightness
 /**
  * @brief Create a new LED indicator device using LED strips.
  *
- * This function initializes and returns a handle to a new LED indicator device
- * based on the provided LED configuration and LED strips configuration.
  *
  * @param led_config    Pointer to the LED configuration structure.
  * @param strips_cfg    Pointer to the LED strips specific configuration structure.
diff --git a/components/led/led_indicator/src/led_custom.c b/components/led/led_indicator/src/led_custom.c
@@ -14,7 +14,6 @@ led_indicator_handle_t iot_led_new_custom_device(const led_config_t *led_config,
     bool if_blink_default_list = false;
 
     ESP_LOGI(TAG, "LED Indicator Version: %d.%d.%d", LED_INDICATOR_VER_MAJOR, LED_INDICATOR_VER_MINOR, LED_INDICATOR_VER_PATCH);
-    LED_INDICATOR_CHECK(led_config != NULL, "invalid config pointer", return NULL);
     LED_INDICATOR_CHECK(custom_cfg != NULL, "invalid config pointer", return NULL);
     _led_indicator_com_config_t com_cfg = {0};
     _led_indicator_t *p_led_indicator = NULL;
diff --git a/components/led/led_indicator/src/led_gpio.c b/components/led/led_indicator/src/led_gpio.c
@@ -77,7 +77,6 @@ led_indicator_handle_t iot_led_new_gpio_device(const led_config_t *led_config, c
     bool if_blink_default_list = false;
 
     ESP_LOGI(TAG, "LED Indicator Version: %d.%d.%d", LED_INDICATOR_VER_MAJOR, LED_INDICATOR_VER_MINOR, LED_INDICATOR_VER_PATCH);
-    LED_INDICATOR_CHECK(led_config != NULL, "invalid config pointer", return NULL);
     LED_INDICATOR_CHECK(gpio_cfg != NULL, "invalid config pointer", return NULL);
     _led_indicator_com_config_t com_cfg = {0};
     _led_indicator_t *p_led_indicator = NULL;
diff --git a/components/led/led_indicator/src/led_ledc.c b/components/led/led_indicator/src/led_ledc.c
@@ -124,7 +124,6 @@ led_indicator_handle_t iot_led_new_ledc_device(const led_config_t *led_config, c
     bool if_blink_default_list = false;
 
     ESP_LOGI(TAG, "LED Indicator Version: %d.%d.%d", LED_INDICATOR_VER_MAJOR, LED_INDICATOR_VER_MINOR, LED_INDICATOR_VER_PATCH);
-    LED_INDICATOR_CHECK(led_config != NULL, "invalid config pointer", return NULL);
     LED_INDICATOR_CHECK(ledc_cfg != NULL, "invalid config pointer", return NULL);
     _led_indicator_com_config_t com_cfg = {0};
     _led_indicator_t *p_led_indicator = NULL;
diff --git a/components/led/led_indicator/src/led_rgb.c b/components/led/led_indicator/src/led_rgb.c
@@ -165,7 +165,6 @@ led_indicator_handle_t iot_led_new_rgb_device(const led_config_t *led_config, co
     bool if_blink_default_list = false;
 
     ESP_LOGI(TAG, "LED Indicator Version: %d.%d.%d", LED_INDICATOR_VER_MAJOR, LED_INDICATOR_VER_MINOR, LED_INDICATOR_VER_PATCH);
-    LED_INDICATOR_CHECK(led_config != NULL, "invalid config pointer", return NULL);
     LED_INDICATOR_CHECK(rgb_cfg != NULL, "invalid config pointer", return NULL);
     _led_indicator_com_config_t com_cfg = {0};
     _led_indicator_t *p_led_indicator = NULL;
diff --git a/components/led/led_indicator/src/led_strips.c b/components/led/led_indicator/src/led_strips.c
@@ -196,7 +196,6 @@ led_indicator_handle_t iot_led_new_strips_device(const led_config_t *led_config,
     bool if_blink_default_list = false;
 
     ESP_LOGI(TAG, "LED Indicator Version: %d.%d.%d", LED_INDICATOR_VER_MAJOR, LED_INDICATOR_VER_MINOR, LED_INDICATOR_VER_PATCH);
-    LED_INDICATOR_CHECK(led_config != NULL, "invalid config pointer", return NULL);
     LED_INDICATOR_CHECK(strips_cfg != NULL, "invalid config pointer", return NULL);
     _led_indicator_com_config_t com_cfg = {0};
     _led_indicator_t *p_led_indicator = NULL;
diff --git a/docs/en/display/led_indicator.rst b/docs/en/display/led_indicator.rst
@@ -230,16 +230,15 @@ Create an indicator by specifying an IO and a set of configuration information.
 
 .. code:: c
 
-    led_indicator_config_t config = {
-        .mode = LED_GPIO_MODE,
-        .led_gpio_config = {
-            .active_level = 1,
-            .gpio_num = 1,
-        },
+   led_indicator_gpio_config_t led_indicator_gpio_config = {
+        .gpio_num = 1,              /**< num of GPIO */
+        .is_active_level_high = 1,
+    };
+    led_config_t config = {
         .blink_lists = led_indicator_get_sample_lists(),
         .blink_list_num = led_indicator_get_sample_lists_num(),
     };
-    led_indicator_handle_t led_handle = led_indicator_create(8, &config); // attach to gpio 8
+    led_indicator_handle_t led_handle  = iot_led_new_gpio_device(&config, &led_indicator_gpio_config);
 
 
 Start/stop blinking: control your indicator to start/stop a specified type of blink by calling corresponding functions. The functions are returned immediately after calling, and the blink process is controlled by the internal timer. The same indicator can perform multiple blink types in turn based on their priorities.
@@ -288,14 +287,14 @@ Custom light blink
         [BLINK_NUM] = NULL,
     };
 
-    led_indicator_config_t config = {
-        .mode = LED_GPIO_MODE,
-        .led_gpio_config = {
-            .active_level = 1,
-            .gpio_num = 1,
-        },
-        .blink_lists = led_blink_lst,
-        .blink_list_num = BLINK_MAX,
+    led_indicator_gpio_config_t led_indicator_gpio_config = {
+        .gpio_num = 1,              /**< num of GPIO */
+        .is_active_level_high = 1,
+    };
+
+    led_config_t config = {
+        .blink_lists = led_blink_lst,,
+        .blink_list_num = BLINK_MAX,,
     };
 
 By defining ``led_blink_lst[]`` to achieve the custom indicator.
diff --git a/docs/zh_CN/display/led_indicator.rst b/docs/zh_CN/display/led_indicator.rst
@@ -226,16 +226,15 @@ LED 指示灯是最简单的输出外设之一，可以通过不同形式的闪
 
 .. code:: c
 
-    led_indicator_config_t config = {
-        .mode = LED_GPIO_MODE,
-        .led_gpio_config = {
-            .active_level = 1,
-            .gpio_num = 1,
-        },
+   led_indicator_gpio_config_t led_indicator_gpio_config = {
+        .gpio_num = 1,              /**< num of GPIO */
+        .is_active_level_high = 1,
+    };
+    led_config_t config = {
         .blink_lists = led_indicator_get_sample_lists(),
         .blink_list_num = led_indicator_get_sample_lists_num(),
     };
-    led_indicator_handle_t led_handle = led_indicator_create(8, &config); // attach to gpio 8
+    led_indicator_handle_t led_handle  = iot_led_new_gpio_device(&config, &led_indicator_gpio_config);
 
 
 开始/停止闪烁：控制指示灯开启/停止指定闪烁类型，函数调用后立刻返回，内部由定时器控制闪烁流程。同一个指示灯可以开启多种闪烁类型，将根据闪烁类型优先级依次执行。
@@ -285,16 +284,17 @@ LED 指示灯是最简单的输出外设之一，可以通过不同形式的闪
         [BLINK_NUM] = NULL,
     };
 
-    led_indicator_config_t config = {
-        .mode = LED_GPIO_MODE,
-        .led_gpio_config = {
-            .active_level = 1,
-            .gpio_num = 1,
-        },
-        .blink_lists = led_blink_lst,
-        .blink_list_num = BLINK_MAX,
+    led_indicator_gpio_config_t led_indicator_gpio_config = {
+        .gpio_num = 1,              /**< num of GPIO */
+        .is_active_level_high = 1,
+    };
+
+    led_config_t config = {
+        .blink_lists = led_blink_lst,,
+        .blink_list_num = BLINK_MAX,,
     };
 
+
 通过定义 ``led_blink_lst[]`` 实现自定义指示灯。
 
 gamma 曲线调光
diff --git a/examples/indicator/gpio/main/main.c b/examples/indicator/gpio/main/main.c
@@ -120,13 +120,11 @@ void app_main(void)
     };
 
     const led_indicator_config_t config = {
-        .mode = LED_GPIO_MODE,
-        .led_indicator_gpio_config = &gpio_config,
         .blink_lists = led_mode,
         .blink_list_num = BLINK_MAX,
     };
 
-    led_handle = led_indicator_create(&config);
+    led_handle = iot_led_new_gpio_device(&config, &gpio_config);
     assert(led_handle != NULL);
 
 #if CONFIG_EXAMPLE_ENABLE_CONSOLE_CONTROL
diff --git a/examples/indicator/ledc/main/main.c b/examples/indicator/ledc/main/main.c
@@ -148,13 +148,11 @@ void app_main(void)
     };
 
     const led_indicator_config_t config = {
-        .mode = LED_LEDC_MODE,
-        .led_indicator_ledc_config = &ledc_config,
         .blink_lists = led_mode,
         .blink_list_num = BLINK_MAX,
     };
 
-    led_handle = led_indicator_create(&config);
+    led_handle = iot_led_new_ledc_device(&config, &ledc_config);
     assert(led_handle != NULL);
 
 #if CONFIG_EXAMPLE_ENABLE_CONSOLE_CONTROL
diff --git a/examples/indicator/rgb/main/main.c b/examples/indicator/rgb/main/main.c
@@ -182,13 +182,11 @@ void app_main(void)
     };
 
     const led_indicator_config_t config = {
-        .mode = LED_RGB_MODE,
-        .led_indicator_rgb_config = &rgb_config,
         .blink_lists = led_mode,
         .blink_list_num = BLINK_MAX,
     };
 
-    led_handle = led_indicator_create(&config);
+    led_handle = iot_led_new_rgb_device(&config, &rgb_config);
     assert(led_handle != NULL);
 
 #if CONFIG_EXAMPLE_ENABLE_CONSOLE_CONTROL
diff --git a/examples/indicator/ws2812_strips/main/main.c b/examples/indicator/ws2812_strips/main/main.c
@@ -212,13 +212,11 @@ void app_main(void)
     };
 
     const led_indicator_config_t config = {
-        .mode = LED_STRIPS_MODE,
-        .led_indicator_strips_config = &strips_config,
         .blink_lists = led_mode,
         .blink_list_num = BLINK_MAX,
     };
 
-    led_handle = led_indicator_create(&config);
+    led_handle = iot_led_new_strips_device(&config, &strips_config);
     assert(led_handle != NULL);
 
 #if CONFIG_EXAMPLE_ENABLE_CONSOLE_CONTROL
diff --git a/examples/usb/host/usb_cdc_4g_module/main/app_main.c b/examples/usb/host/usb_cdc_4g_module/main/app_main.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -113,26 +113,23 @@ static void _led_indicator_init()
         .is_active_level_high = LED_ACTIVE_LEVEL,
     };
 
-    led_indicator_config_t led_config = {
-        .led_indicator_gpio_config = &led_indicator_gpio_config,
-        .mode = LED_GPIO_MODE,
-    };
+    led_indicator_config_t led_config ;
 
     if (LED_RED_SYSTEM_GPIO) {
         led_indicator_gpio_config.gpio_num = LED_RED_SYSTEM_GPIO;
-        s_led_system_handle = led_indicator_create(&led_config);
+        s_led_system_handle = iot_led_new_gpio_device(&led_config, &led_indicator_gpio_config);
         assert(s_led_system_handle != NULL);
     }
     if (LED_BLUE_WIFI_GPIO) {
         led_indicator_gpio_config.gpio_num = LED_BLUE_WIFI_GPIO;
-        s_led_wifi_handle = led_indicator_create(&led_config);
+        s_led_wifi_handle = iot_led_new_gpio_device(&led_config, &led_indicator_gpio_config);
         assert(s_led_wifi_handle != NULL);
         led_indicator_stop(s_led_wifi_handle, BLINK_CONNECTED);
         led_indicator_start(s_led_wifi_handle, BLINK_CONNECTING);
     }
     if (LED_GREEN_4GMODEM_GPIO) {
         led_indicator_gpio_config.gpio_num = LED_GREEN_4GMODEM_GPIO;
-        s_led_4g_handle = led_indicator_create(&led_config);
+        s_led_4g_handle = iot_led_new_gpio_device(&led_config, &led_indicator_gpio_config);
         assert(s_led_4g_handle != NULL);
         led_indicator_stop(s_led_4g_handle, BLINK_CONNECTED);
         led_indicator_start(s_led_4g_handle, BLINK_CONNECTING);

Original file line number	Diff line number	Diff line change
`@@ -34,8 +34,6 @@ typedef struct {`
`34`	`34`	`/**`
`35`	`35`	`* @brief Create a new custom LED indicator device.`
`36`	`36`	`*`
`37`		`- * This function initializes a new LED indicator device using the provided LED configuration`
`38`		`- * and custom configuration parameters.`
`39`	`37`	`*`
`40`	`38`	`* @param led_config Pointer to the LED configuration structure.`
`41`	`39`	`* @param custom_cfg Pointer to the custom configuration structure for the LED indicator.`
Original file line number	Diff line number	Diff line change
`@@ -58,9 +58,6 @@ esp_err_t led_indicator_gpio_set_on_off(void *handle, bool on_off);`
`58`	`58`	`/**`
`59`	`59`	`* @brief Create a new LED indicator device using a GPIO pin.`
`60`	`60`	`*`
`61`		`- * This function initializes a new LED indicator device based on the provided LED configuration`
`62`		`- * and GPIO configuration. It returns a handle to the created LED indicator device, which can be`
`63`		`- * used for further control and management.`
`64`	`61`	`*`
`65`	`62`	`* @param led_config Pointer to the LED configuration structure.`
`66`	`63`	`* @param gpio_cfg Pointer to the GPIO configuration structure for the LED.`
Original file line number	Diff line number	Diff line change
`@@ -69,8 +69,6 @@ esp_err_t led_indicator_ledc_set_brightness(void *ledc_handle, uint32_t brightne`
`69`	`69`	`/**`
`70`	`70`	`* @brief Create a new LED indicator device using the LEDC (LED Controller) peripheral.`
`71`	`71`	`*`
`72`		`- * This function initializes a new LED indicator device with the specified configuration,`
`73`		`- * utilizing the ESP32's LEDC hardware for PWM control.`
`74`	`72`	`*`
`75`	`73`	`* @param led_config Pointer to the general LED configuration structure.`
`76`	`74`	`* @param ledc_cfg Pointer to the LEDC-specific configuration structure.`
Original file line number	Diff line number	Diff line change
`@@ -101,8 +101,6 @@ esp_err_t led_indicator_rgb_set_brightness(void *rgb_handle, uint32_t brightness`
`101`	`101`	`/**`
`102`	`102`	`* @brief Create a new RGB LED device instance.`
`103`	`103`	`*`
`104`		`- * This function initializes a new RGB LED device using the specified LED configuration`
`105`		`- * and RGB-specific configuration parameters.`
`106`	`104`	`*`
`107`	`105`	`* @param led_config Pointer to the general LED configuration structure.`
`108`	`106`	`* @param rgb_cfg Pointer to the RGB-specific configuration structure.`
Original file line number	Diff line number	Diff line change
`@@ -111,8 +111,6 @@ esp_err_t led_indicator_strips_set_brightness(void *strips, uint32_t ibrightness`
`111`	`111`	`/**`
`112`	`112`	`* @brief Create a new LED indicator device using LED strips.`
`113`	`113`	`*`
`114`		`- * This function initializes and returns a handle to a new LED indicator device`
`115`		`- * based on the provided LED configuration and LED strips configuration.`
`116`	`114`	`*`
`117`	`115`	`* @param led_config Pointer to the LED configuration structure.`
`118`	`116`	`* @param strips_cfg Pointer to the LED strips specific configuration structure.`