doc: update led_strip doc for pixel format and led model (#127)

Author: suda-morris

led_strip/README.md

@@ -20,13 +20,16 @@ led_strip_handle_t led_strip;
 /* LED strip initialization with the GPIO and pixels number*/
 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
+    .max_leds = 1, // The number of LEDs in the strip,
+    .led_pixel_format = LED_PIXEL_FORMAT_GRB, // Pixel format of your 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)
 };
 
 led_strip_rmt_config_t rmt_config = {
     .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, // wether to enable the DMA feature
+    .flags.with_dma = false, // whether to enable the DMA feature
 };
 ESP_ERROR_CHECK(led_strip_new_rmt_device(&strip_config, &rmt_config, &led_strip));
 ```

led_strip/idf_component.yml

@@ -1,4 +1,4 @@
-version: "2.2.0"
+version: "2.2.1"
 description: Driver for Addressable LED Strip (WS2812, etc)
 url: https://github.com/espressif/idf-extra-components/tree/master/led_strip
 dependencies:

led_strip/include/led_strip.h

@@ -32,16 +32,20 @@ esp_err_t led_strip_set_pixel(led_strip_handle_t strip, uint32_t index, uint32_t
 /**
  * @brief Set RGBW for a specific pixel
  *
+ * @note 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
+ *
  * @param strip: LED strip
  * @param index: index of pixel to set
  * @param red: red part of color
  * @param green: green part of color
  * @param blue: blue part of color
- * @param white: separate white component (sk6812rgbw leds)
+ * @param white: separate white component
  *
  * @return
- *      - ESP_OK: RGBW color succesfully set for the pixel
- *      - ESP_ERR_INVALID_ARG: Set RGB for a specific pixel failed because of an invalid argument
+ *      - 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_err_t led_strip_set_pixel_rgbw(led_strip_handle_t strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue, uint32_t white);
 

led_strip/include/led_strip_types.h

@@ -11,14 +11,23 @@
 extern "C" {
 #endif
 
+/**
+ * @brief LED strip pixel format
+ */
 typedef enum {
-    LED_PIXEL_FORMAT_GRB,
-    LED_PIXEL_FORMAT_GRBW
+    LED_PIXEL_FORMAT_GRB,    /*!< Pixel format: GRB */
+    LED_PIXEL_FORMAT_GRBW,   /*!< Pixel format: GRBW */
+    LED_PIXEL_FORMAT_INVALID /*!< Invalid pixel format */
 } led_pixel_format_t;
 
+/**
+ * @brief LED strip model
+ * @note Different led model may have different timing parameters, so we need to distinguish them.
+ */
 typedef enum {
-    LED_MODEL_WS2812,
-    LED_MODEL_SK6812
+    LED_MODEL_WS2812, /*!< LED strip model: WS2812 */
+    LED_MODEL_SK6812, /*!< LED strip model: SK6812 */
+    LED_MODEL_INVALID /*!< Invalid LED strip model */
 } led_model_t;
 
 /**
@@ -32,8 +41,8 @@ typedef struct led_strip_t *led_strip_handle_t;
 typedef struct {
     uint32_t strip_gpio_num; /*!< GPIO number that used by LED strip */
     uint32_t max_leds;       /*!< Maximum LEDs in a single strip */
-    led_pixel_format_t led_pixel_format;
-    led_model_t led_model;
+    led_pixel_format_t led_pixel_format; /*!< LED pixel format */
+    led_model_t led_model;   /*!< LED model */
     struct {
         uint32_t invert_out: 1; /*!< Invert output signal */
     } flags;

led_strip/interface/led_strip_interface.h

@@ -35,18 +35,19 @@ struct led_strip_t {
     esp_err_t (*set_pixel)(led_strip_t *strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue);
 
     /**
-     * @brief Set RGBW for a specific pixel
+     * @brief Set RGBW for a specific pixel. Similar to `set_pixel` but also set the white component
      *
      * @param strip: LED strip
      * @param index: index of pixel to set
      * @param red: red part of color
      * @param green: green part of color
      * @param blue: blue part of color
-     * @param white: separate white component (sk6812rgbw leds)
+     * @param white: separate white component
      *
      * @return
-     *      - ESP_OK: RGBW color succesfully set for the pixel
-     *      - ESP_ERR_INVALID_ARG: Set RGB for a specific pixel failed because of an invalid argument
+     *      - 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_err_t (*set_pixel_rgbw)(led_strip_t *strip, uint32_t index, uint32_t red, uint32_t green, uint32_t blue, uint32_t white);
 

led_strip/src/led_strip_rmt_dev.c

@@ -92,12 +92,14 @@ esp_err_t led_strip_new_rmt_device(const led_strip_config_t *led_config, const l
     led_strip_rmt_obj *rmt_strip = NULL;
     esp_err_t ret = ESP_OK;
     ESP_GOTO_ON_FALSE(led_config && rmt_config && ret_strip, ESP_ERR_INVALID_ARG, err, TAG, "invalid argument");
-    ESP_GOTO_ON_FALSE(led_config->led_pixel_format <= LED_PIXEL_FORMAT_GRBW, ESP_ERR_INVALID_ARG, err, TAG, "invalid led_pixel_format");
+    ESP_GOTO_ON_FALSE(led_config->led_pixel_format < LED_PIXEL_FORMAT_INVALID, ESP_ERR_INVALID_ARG, err, TAG, "invalid led_pixel_format");
     uint8_t bytes_per_pixel;
     if (led_config->led_pixel_format == LED_PIXEL_FORMAT_GRBW) {
         bytes_per_pixel = 4;
-    } else {
+    } else if (led_config->led_pixel_format == LED_PIXEL_FORMAT_GRB) {
         bytes_per_pixel = 3;
+    } else {
+        assert(false);
     }
     rmt_strip = calloc(1, sizeof(led_strip_rmt_obj) + led_config->max_leds * bytes_per_pixel);
     ESP_GOTO_ON_FALSE(rmt_strip, ESP_ERR_NO_MEM, err, TAG, "no mem for rmt strip");

led_strip/src/led_strip_rmt_encoder.c

@@ -76,6 +76,7 @@ esp_err_t rmt_new_led_strip_encoder(const led_strip_encoder_config_t *config, rm
     esp_err_t ret = ESP_OK;
     rmt_led_strip_encoder_t *led_encoder = NULL;
     ESP_GOTO_ON_FALSE(config && ret_encoder, ESP_ERR_INVALID_ARG, err, TAG, "invalid argument");
+    ESP_GOTO_ON_FALSE(config->led_model < LED_MODEL_INVALID, ESP_ERR_INVALID_ARG, err, TAG, "invalid led model");
     led_encoder = calloc(1, sizeof(rmt_led_strip_encoder_t));
     ESP_GOTO_ON_FALSE(led_encoder, ESP_ERR_NO_MEM, err, TAG, "no mem for led strip encoder");
     led_encoder->base.encode = rmt_encode_led_strip;
@@ -96,9 +97,9 @@ esp_err_t rmt_new_led_strip_encoder(const led_strip_encoder_config_t *config, rm
                 .level1 = 0,
                 .duration1 = 0.6 * config->resolution / 1000000, // T1L=0.6us
             },
-            .flags.msb_first = 1 // SK6812 transfer bit order: G7...G0R7...R0B7...B0W7...W0
+            .flags.msb_first = 1 // SK6812 transfer bit order: G7...G0R7...R0B7...B0(W7...W0)
         };
-    } else {
+    } else if (config->led_model == LED_MODEL_WS2812) {
         // different led strip might have its own timing requirements, following parameter is for WS2812
         bytes_encoder_config = (rmt_bytes_encoder_config_t) {
             .bit0 = {
@@ -115,6 +116,8 @@ esp_err_t rmt_new_led_strip_encoder(const led_strip_encoder_config_t *config, rm
             },
             .flags.msb_first = 1 // WS2812 transfer bit order: G7...G0R7...R0B7...B0
         };
+    } else {
+        assert(false);
     }
     ESP_GOTO_ON_ERROR(rmt_new_bytes_encoder(&bytes_encoder_config, &led_encoder->bytes_encoder), err, TAG, "create bytes encoder failed");
     rmt_copy_encoder_config_t copy_encoder_config = {};

led_strip/src/led_strip_rmt_encoder.h

@@ -17,8 +17,8 @@ extern "C" {
  * @brief Type of led strip encoder configuration
  */
 typedef struct {
-    uint32_t resolution; /*!< Encoder resolution, in Hz */
-    led_model_t led_model;
+    uint32_t resolution;   /*!< Encoder resolution, in Hz */
+    led_model_t led_model; /*!< LED model */
 } led_strip_encoder_config_t;
 
 /**