Skip to content

Quickstart

Light a strip from your MCU: wire it, write a small port class over your timed-output peripheral, call three driver functions.

Datasheet sections this page relies on

From Worldsemi WS2812B-V5 V5.0:

  • Pins and package: four pin 5050: PIN Configuration, p. 2

All of them, with the driver API for each: Datasheet map.

1. Wire it

MCU Strip Notes
Timed-output pin (on ESP32 an RMT channel) DIN A 5 V strip needs a level shifter for a 3.3 V MCU: see Hardware
GPIO (optional) Supply enable Only if you want PowerOn() and PowerOff()
GND GND Common ground with the strip supply
VDD 5 V supply with a large capacitor at the strip input and 100 nF at each pixel

2. Add the driver

git submodule add https://github.com/kokeb-labs-drivers/driver-ws2812-rmt.git external/driver-ws2812-rmt

3. Write the port

my_port.hpp
class MyPort : public ws2812_rmt::GpioInterface<MyPort> {
public:
  // Create and enable the channel once; the line idles low. Later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_tx_open(kDataGpio, ws2812_rmt::kRecommendedResolutionHz);
    }
    return ready_;
  }

  // The rate the channel really runs at, not the one you asked for.
  bool ResolutionHz(uint32_t& hz) noexcept {
    hz = platform_tx_rate();
    return hz != 0U;
  }

  // Send every byte, most significant bit first, as one gapless stream, then hold the line low for
  // wave.reset_ticks. Return when the last tick is out, or false on a failure or a timeout (leave
  // the line low: the driver then waits a full reset through DelayUs() before the next frame).
  bool Transmit(std::span<const uint8_t> wire, const ws2812_rmt::Waveform& wave,
                uint32_t timeout_ms) noexcept {
    return platform_tx_send(wire.data(), static_cast<uint32_t>(wire.size()), wave, timeout_ms);
  }

  // A wait with the line low.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  static constexpr int32_t kDataGpio = 4;
  bool ready_ = false;
};

On ESP32 use the finished port in examples/esp32 instead.

4. Show a colour

main.cpp
#include "ws2812_rmt.hpp"

// 60 pixels of a current WS2812B (V5 or later): the default variant, GRB order.
int32_t light_first_pixel_red() {
  MyPort port;
  ws2812_rmt::Ws2812Rmt<MyPort, 60> strip(port); // owns the pixel and wire buffers; no I/O yet
  if (auto r = strip.EnsureInitialized(); !r) { // 1. channel up, waveform resolved at the real rate
    return static_cast<int32_t>(r.error); //    Bus, or TimingUnreachable for an unsuitable rate
  }
  strip.Clear();                                                          // 2. all pixels black
  static_cast<void>(strip.SetPixel(0, ws2812_rmt::Colour{255, 0, 0, 0})); //    pixel 0 is the first
  if (auto r = strip.Show(); !r) {        // 3. encode, send, wait for the reset
    return static_cast<int32_t>(r.error); //    Bus: the frame was not sent
  }
  return 0;
}
  1. EnsureInitialized() creates the channel through your port, asks it for its real tick rate and resolves the waveform. A rate that cannot meet the datasheet windows is refused here (TimingUnreachable).
  2. SetPixel() and Fill() only store colours. Show() encodes them and sends the frame.

The defaults suit a current WS2812B (V5 or V6, GRB). For another part set Config::variant: Timing says which one to pick.

Next: API guide.