Feat/support async api for led strip by Kainarx · Pull Request #681 · espressif/idf-extra-components

Kainarx · 2026-02-06T08:36:04Z

Checklist

Component contains License
Component contains README.md
Component contains idf_component.yml file with url field defined
Component was added to upload job
Component was added to build job
Optional: Component contains unit tests
CI passing

Change description

Please describe your change here

Copilot

Pull request overview

This PR adds asynchronous refresh APIs for LED strip control, allowing the next frame to be computed while the current frame is being transmitted. It also adds support for custom LED timing configurations and runtime GPIO switching for the RMT backend.

Changes:

Added async refresh APIs (led_strip_refresh_async and led_strip_refresh_wait_async_done) to both RMT and SPI backends
Added LED_MODEL_CUSTOM enum and led_strip_encoder_timings_t struct for custom LED timing configuration in RMT backend
Added led_strip_switch_gpio API for runtime GPIO switching (RMT backend only)

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
led_strip/idf_component.yml	Version bump from 3.0.3 to 3.0.4
led_strip/CHANGELOG.md	Documents new async API, custom timing support, and GPIO switching feature
led_strip/include/led_strip_types.h	Adds LED_MODEL_CUSTOM enum and led_strip_encoder_timings_t struct; adds timings field to led_strip_config_t
led_strip/include/led_strip.h	Declares public async refresh and GPIO switching APIs
led_strip/include/led_strip_spi.h	Adds name to anonymous struct for better type identification
led_strip/interface/led_strip_interface.h	Adds function pointers for async refresh and GPIO switching to led_strip_t interface
led_strip/src/led_strip_api.c	Implements led_strip_switch_gpio wrapper function
led_strip/src/led_strip_rmt_encoder.h	Adds timings field to led_strip_encoder_config_t
led_strip/src/led_strip_rmt_encoder.c	Implements LED_MODEL_CUSTOM support with custom timings; converts if-else chain to switch statement; removes decimal points from WS2811 calculations
led_strip/src/led_strip_rmt_dev.c	Implements async refresh functions and GPIO switching for RMT backend
led_strip/src/led_strip_spi_dev.c	Implements async refresh functions for SPI backend; adds WS2816 clock resolution support; updates supported model warning
led_strip/examples/led_strip_rmt_ws2812/pytest_led_strip_rmt_ws2812.py	Adds pytest test case for RMT example
led_strip/examples/led_strip_spi_ws2812/pytest_led_strip_spi_ws2812.py	Adds pytest test case for SPI example

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-24T04:56:57Z

+static esp_err_t led_strip_spi_refresh_async(led_strip_t *strip)
 {
    led_strip_spi_obj *spi_strip = __containerof(strip, led_strip_spi_obj, base);
-    spi_transaction_t tx_conf;
-    memset(&tx_conf, 0, sizeof(tx_conf));
+    memset(&spi_strip->trans, 0, sizeof(spi_strip->trans));
+    spi_strip->trans.length = spi_strip->strip_len * spi_strip->bytes_per_pixel * SPI_BITS_PER_COLOR_BYTE;
+    spi_strip->trans.tx_buffer = spi_strip->pixel_buf;
+    spi_strip->trans.rx_buffer = NULL;
+    ESP_RETURN_ON_ERROR(spi_device_queue_trans(spi_strip->spi_device, &spi_strip->trans, SPI_TRANS_MAX_DELAY), TAG, "transmit pixels by SPI failed");


The async refresh API documentation states users should not modify LED colors until refresh_wait_async_done completes, but there's no enforcement mechanism. Since tx_buffer points directly to pixel_buf, modifying pixels via set_pixel or set_pixel_rgbw after calling refresh_async but before refresh_wait_async_done could corrupt the ongoing SPI transmission. Consider adding a flag to track whether an async operation is in progress and validate against concurrent modifications, or document this limitation more explicitly in the function documentation.

Copilot · 2026-02-24T04:56:58Z

 #include "soc/spi_periph.h"
 #include "led_strip.h"
 #include "led_strip_interface.h"
 #include "esp_heap_caps.h"


The include "esp_heap_caps.h" is duplicated. It appears on both line 12 and line 16. Please remove the duplicate include statement.

Suggested change

#include "esp_heap_caps.h"

Copilot · 2026-02-24T04:56:58Z

+
+esp_err_t led_strip_switch_gpio(led_strip_handle_t strip, gpio_num_t new_gpio_num, bool invert_output)
+{
+    ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");


The switch_gpio function pointer is called directly without checking if it's NULL. Since this function is only implemented for the RMT backend and not for the SPI backend, calling led_strip_switch_gpio on an SPI-backed LED strip will cause a NULL pointer dereference. Add a NULL check before calling the function pointer and return an appropriate error (e.g., ESP_ERR_NOT_SUPPORTED) if the backend doesn't support this operation.

Suggested change

ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");

ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");

ESP_RETURN_ON_FALSE(strip->switch_gpio, ESP_ERR_NOT_SUPPORTED, TAG, "switch_gpio not supported by this backend");

Copilot · 2026-02-24T04:56:58Z

+            },
+            .flags.msb_first = 1
+        };
+        reset_ticks = config->resolution / 1000000 * config->timings.reset / 2; // divide by 2... signal is sent twice


The reset_ticks calculation for LED_MODEL_CUSTOM may produce incorrect results due to integer division order. The expression "config->resolution / 1000000 * config->timings.reset / 2" should be reordered to "(config->resolution * config->timings.reset) / (1000000 * 2)" or use floating-point arithmetic to avoid precision loss. The timings.reset is in microseconds, so this needs to convert from microseconds to ticks correctly.

Copilot · 2026-02-24T04:56:59Z

@@ -29,6 +32,7 @@ typedef struct {
    uint32_t strip_len;
    uint8_t bytes_per_pixel;
    led_color_component_format_t component_fmt;


The spi_transaction_t is stored in the led_strip_spi_obj structure and reused for each async refresh. This design limits the implementation to one in-flight transaction at a time. If a user calls refresh_async twice without calling refresh_wait_async_done in between, the second call will overwrite the transaction data and potentially cause incorrect behavior when spi_device_get_trans_result is called. Consider documenting this limitation or adding validation to prevent multiple concurrent async operations.

Suggested change

led_color_component_format_t component_fmt;

led_color_component_format_t component_fmt;

// NOTE: This transaction object is reused for each async refresh.

// This design only supports a single in-flight async SPI transaction

// per led_strip_spi_obj. Users must not start a new async refresh

// before the previous one has completed (e.g., before calling

// refresh_wait_async_done for the prior operation).

Copilot · 2026-02-24T04:56:59Z

+esp_err_t led_strip_switch_gpio(led_strip_handle_t strip, gpio_num_t new_gpio_num, bool invert_output)
+{
+    ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
+    return strip->switch_gpio(strip, new_gpio_num, invert_output);
+}


The new async refresh APIs (led_strip_refresh_async and led_strip_refresh_wait_async_done) are declared in the public header led_strip.h but are not implemented in led_strip_api.c. These wrapper functions should be added to maintain API consistency with other functions like led_strip_refresh, led_strip_clear, etc.

Copilot · 2026-02-24T04:56:59Z

+    dut.expect_exact('example: LED OFF!')
+    dut.expect_exact('example: LED ON!')
+
+


Trailing whitespace detected on line 19. Please remove the trailing whitespace to maintain code cleanliness.

Suggested change

Copilot · 2026-02-24T04:56:59Z

+    dut.expect_exact('example: LED OFF!')
+    dut.expect_exact('example: LED ON!')
+
+


Trailing whitespace detected on line 19. Please remove the trailing whitespace to maintain code cleanliness.

Suggested change

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

    uint32_t strip_len;
    uint8_t bytes_per_pixel;
    led_color_component_format_t component_fmt;
+    spi_transaction_t trans;
    uint8_t pixel_buf[];


+    memset(&spi_strip->trans, 0, sizeof(spi_strip->trans));
+    spi_strip->trans.length = spi_strip->strip_len * spi_strip->bytes_per_pixel * SPI_BITS_PER_COLOR_BYTE;
+    spi_strip->trans.tx_buffer = spi_strip->pixel_buf;
+    spi_strip->trans.rx_buffer = NULL;
+    ESP_RETURN_ON_ERROR(spi_device_queue_trans(spi_strip->spi_device, &spi_strip->trans, SPI_TRANS_MAX_DELAY), TAG, "transmit pixels by SPI failed");


+static esp_err_t led_strip_spi_refresh_wait_async_done(led_strip_t *strip)
+{
+    led_strip_spi_obj *spi_strip = __containerof(strip, led_strip_spi_obj, base);
+    spi_transaction_t *tx_conf = NULL;
+    ESP_RETURN_ON_ERROR(spi_device_get_trans_result(spi_strip->spi_device, &tx_conf, SPI_TRANS_MAX_DELAY), TAG, "wait for done failed");
+    return ESP_OK;
+}


    ESP_RETURN_ON_ERROR(rmt_enable(rmt_strip->rmt_chan), TAG, "enable RMT channel failed");
    ESP_RETURN_ON_ERROR(rmt_transmit(rmt_strip->rmt_chan, rmt_strip->strip_encoder, rmt_strip->pixel_buf,
                                     rmt_strip->strip_len * rmt_strip->bytes_per_pixel, &tx_conf), TAG, "transmit pixels by RMT failed");
-    ESP_RETURN_ON_ERROR(rmt_tx_wait_all_done(rmt_strip->rmt_chan, -1), TAG, "flush RMT channel failed");
+    return ESP_OK;


suda-morris force-pushed the feat/support_async_api_for_led_strip branch from 7220a92 to 4ea58b1 Compare February 14, 2026 02:39

suda-morris reviewed Feb 14, 2026

View reviewed changes

Comment thread led_strip/CHANGELOG.md Outdated

Kainarx force-pushed the feat/support_async_api_for_led_strip branch from 4ea58b1 to d167f3c Compare February 14, 2026 06:43

suda-morris force-pushed the feat/support_async_api_for_led_strip branch from d167f3c to b172944 Compare February 24, 2026 04:41

suda-morris requested a review from Copilot February 24, 2026 04:50

Copilot started reviewing on behalf of suda-morris February 24, 2026 04:51 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

Kainarx added 2 commits March 6, 2026 16:48

feat(led_strip): add async refresh api

7411fab

feat(led_strip): add timing config for RMT backend

7460ec2

Kainarx force-pushed the feat/support_async_api_for_led_strip branch 2 times, most recently from 2757d85 to 74de61f Compare March 12, 2026 07:29

Kainarx added 3 commits March 16, 2026 14:22

faet(led_strip): add pytest

6dceadb

feat(led_strip): support to switch gpio at runtime in rmt backend

319513c

feat(led_strip): update the version to 3.0.4

c8f755e

Kainarx force-pushed the feat/support_async_api_for_led_strip branch from 74de61f to c8f755e Compare March 16, 2026 06:22

suda-morris mentioned this pull request Apr 15, 2026

led_strip: asynchronous transfer support (IEC-519) #726

Open

Merge branch 'master' into feat/support_async_api_for_led_strip

79e0143

suda-morris requested a review from Copilot June 22, 2026 04:59

Copilot started reviewing on behalf of suda-morris June 22, 2026 05:01 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat/support async api for led strip#681

Feat/support async api for led strip#681
Kainarx wants to merge 6 commits into
espressif:masterfrom
Kainarx:feat/support_async_api_for_led_strip

Kainarx commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI Feb 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
	ESP_RETURN_ON_FALSE(strip, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
	ESP_RETURN_ON_FALSE(strip->switch_gpio, ESP_ERR_NOT_SUPPORTED, TAG, "switch_gpio not supported by this backend");

-    led_color_component_format_t component_fmt;
+    led_color_component_format_t component_fmt;
+    // NOTE: This transaction object is reused for each async refresh.
+    // This design only supports a single in-flight async SPI transaction
+    // per led_strip_spi_obj. Users must not start a new async refresh
+    // before the previous one has completed (e.g., before calling
+    // refresh_wait_async_done for the prior operation).

		dut.expect_exact('example: LED OFF!')
		dut.expect_exact('example: LED ON!')

Uh oh!

Conversation

Kainarx commented Feb 6, 2026

Checklist

Change description

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants