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;
}
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).SetPixel()andFill()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.