drivers/ws281x: Add gpio_ll and timer based driver

[chrysn]

Contribution description

This adds a driver for WS281x style LEDs (tested here with SK6812 RGBW), which is based on gpio_ll and timers (with a small addition).

Review-wise, I'd ask for this to be reviewed as a whole. PR-wise (for change log etc) it may make sense to factor out the timer additions into a second PR that's then fast-tracked and only contains the first commits, but this is all better understood as a whole.

Changes are:

• Fixes to existing timers. (Missing define, and a NULL callback made nRF5x crash).
• Adds the periph_timer_poll feature on periph_timer -- when present, we get a new timer_poll_channel inline function, which checks whether a counter has been reached (even when interrupts are off, or when there is no handler for this timer).
• Implements the bit-banging protocol. We have a rather tight time budget, with a single tick of the 16MHz counter making the difference on whether or not a one is actually read as a 1, but there'd some time to spare if we didn't choose the timing parameters this tightly. (But when doing the rounding properly, I didn't need to alter the existing nanosecond times).

There is a general alternative: Using SPI, PWM or really any other suitable general peripheral. But this works (albeit blockingly), and should be somewhat portable (although I wouldn't know what to test it on), and can still serve as a reference when doing anything more fancy.

Testing procedure

• Take any nRF52 device (probably nRF5x), and wire up WS281x style LEDs.
• I wired up SK6812 RGBW, so I had to apply this extra:

diff --git a/drivers/include/ws281x.h b/drivers/include/ws281x.h
index fe448ee198..14b2b02b6c 100644
--- a/drivers/include/ws281x.h
+++ b/drivers/include/ws281x.h
@@ -104 +104 @@ extern "C" {
-#define WS281X_BYTES_PER_DEVICE       (3U)
+#define WS281X_BYTES_PER_DEVICE       (4U)

• Pick a pin, a number of LEDs and a timer for the configuration. (If a board were wired with LEDs, that'd be part of the board config). For me, I had a particle-xenon and attached to the bottom right pin (SDA), so I applied:

diff --git a/tests/drivers/ws281x/Makefile b/tests/drivers/ws281x/Makefile
index a8def79895..aa01ed28e9 100644
--- a/tests/drivers/ws281x/Makefile
+++ b/tests/drivers/ws281x/Makefile
@@ -5,2 +5,2 @@ include ../Makefile.drivers_common
-# PIN ?= GPIO_PIN(0, 0)
-# N ?= 8
+PIN ?= GPIO_PIN(0, 26)
+N ?= 8
@@ -9,2 +9,2 @@ include ../Makefile.drivers_common
-# TIMER ?= 2
-# FREQ ?= 16000000
+TIMER ?= 2
+FREQ ?= 16000000

• make -C tests/drivers/ws281x BOARD=particle-xenon all flash term PARTICLE_MONOFIRMWARE=1 or whatever your board needs
• Watch it show funny rainbows, and have fun until your power supply says that no to all the LEDs lighting up (I had a full strand connected, and the example lit up all of it while it lasted). Or turn down the 100 rainbows in tests/drivers/ws281x/main.c

Issues/PRs references

Closes: #19859

This might also be a band-aid for #19158 -- but given there is that neat PIO, that's probably the way to go.

[riot-ci]

Murdock results

✔️ PASSED

6a0b1c5 boards/nrf9160dk: Override WS281X_TIMER_*

Success	Failures	Total	Runtime
138167	0	138167	02h:32m:55s

Artifacts

• Documentation preview

[jimporter]

Coming from #19859, I tested this out on an Adafruit ItsyBitsy nRF52840 with an 8-LED strip.

It works sometimes (if I just set the colors once instead of in a loop) but overall it's pretty glitchy for me. Seems like timing issues, but I could be doing something wrong of course. To keep things as simple as possible, I used the following test program, which should just repeatedly set all the LEDs to red, but instead I get a random strobe effect:

Makefile

USEMODULE += ws281x
USEMODULE += xtimer

TIMER = 2
FREQ = 16000000

# ...

main.c

int main(void) {
  // NeoPixel strip
  ws281x_t neopixel;
  uint8_t neo_state[8];
  ws281x_params_t neo_params = {
    .buf = neo_state,
    .numof = 8,
    .pin = GPIO_PIN(0, 27)
  };
  if(ws281x_init(&neopixel, &neo_params) != 0) {
    printf("failed to initialize NeoPixel\n");
    return 3;
  }

  xtimer_ticks32_t last_wakeup = xtimer_now();
  while(true) {
    color_rgb_t neo_color = {255, 0, 0};
    for(int i = 0; i < 8; i++)
      ws281x_set(&neopixel, i, neo_color);
    ws281x_write(&neopixel);
    xtimer_periodic_wakeup(&last_wakeup, 100 * US_PER_MS);
  }

  return 0;
}

[chrysn]

Thanks for testing. The product you link is unspecific as to whether WS2812B or SK6812 LEDs are in there; do you happen to know? (I hope it's WS2812B, as that'd explain differences in behavior). It'd be helpful if you could do 3 things: * In ./drivers/ws281x/timer_gpio_ll.c, change DEBUG from 0 to 1, and send the output. (And keep it that way for the next tests). * In drivers/ws281x/include/ws281x_constants.h, increase the DATA_ONE_NS in one test (say, to 750), and * decrease DATA_ZERO_NS in another test (say, to 275). Do things work stably here? What is the debug output?

[MrKevinWeiss]

Hmmm I wonder why of the no fail fast label has an issue with the merge queues

This never worked this way. It only affects the "quick build" prior to entering the merge queue / bors. You can add a CI: full build to turn the quick build into a full build, though.

You could also hack in a quick change to only build the ws281x test app in the quick build, but for all boards. That should cover anything that I would expect to fail here. If this quick build passed, the CI: full build and the hack commit could be dropped again.

True true, how we used to do it. I will just let it run in the night I suppose and save a commit drop.

[benpicco]

Suggested change

	#define WS281X_TIMER_FREQ 16000000
	#define WS281X_TIMER_FREQ MHZ(16)

reads a bit nicer

[MrKevinWeiss]

It seems like using the MHZ macro causes some conflicts with the ESP so I think it best to just leave it out.

[MrKevinWeiss]

The tests are passing (at least for the driver). Maybe @chrysn and @benpicco can see if they agree then I would squash and merge.

[MrKevinWeiss]

Nice, thanks for the contribution and reviews! Our feature-nrf52840-sense board it becoming more powerful every day!

[chrysn]

Thank you all for pushing this over the finish line!