API guide¶
The driver by task. Every fallible call returns Result<T>: check it with ok() or if (result), then use
value or error. Nothing throws, and nothing is allocated.
Datasheet sections this page relies on
From Worldsemi WS2812B-V5 V5.0:
- 24 bit data, GRB, high bit first: Composition of 24bit Data, p. 4
- Cascade and data transmission method: Data Transmission Method, p. 4
All of them, with the driver API for each: Datasheet map.
| Task | Calls |
|---|---|
| Start | EnsureInitialized(), IsInitialized() |
| Colours | SetPixel(), GetPixel(), Fill(), Clear(), SetBrightness(), SetGamma() |
| Send | Show() |
| Supply | PowerOn(), PowerOff() |
| Raw access | TraceWire(), GetLastWire() |
| Inspect | Length(), ChannelsPerPixel(), CurrentWaveform(), FrameTimeUs(), GetConfig() |
| Pure functions | ResolveWaveform(), WaveformInWindow(), EncodeFrame(), DecodeWire(), Wheel(), ExtractWhite(), ... |
The object¶
The second template argument is the capacity: the object holds 60 colours and the byte buffer for them (4 bytes per
pixel at most), so no heap is needed and the buffers live where you put the object. Config::pixel_count can be
smaller than the capacity (0 means the whole capacity). The constructor does no I/O and cannot fail.
Start¶
EnsureInitialized() checks the configuration, asks the port to open its channel, asks for the tick rate and
resolves the waveform. It returns InvalidArgument (the configuration is invalid, no port call made), Bus (the
port failed) or TimingUnreachable (the rate cannot meet a window). After a failure the driver is still
uninitialised and the next call starts again. After a success it returns Ok at once.
Set and show¶
SetPixel() stores a logical colour and returns InvalidArgument for an index past the strip (nothing changes).
Fill(), Clear(), SetBrightness() and SetGamma() never fail and do no I/O. Show() encodes every pixel
(gamma, then brightness, in the wire order) and asks the port to send it; it blocks until the frame and the reset are
out. A failed Show() leaves the pixels intact: call it again.
Brightness and colour order¶
Colour has both, and Configuration every field of Config.
// An SK6812RGBW strip: four channels, white last. Rev 01 and Rev 03 datasheets send red first.
ws2812_rmt::Config RgbwConfig(bool old_revision) {
ws2812_rmt::Config c = ws2812_rmt::Config::Default();
c.variant = ws2812_rmt::Variant::Sk6812Rgbw;
if (old_revision) {
c.use_default_order = false;
c.order = ws2812_rmt::kOrderRgbw; // red and green swapped on the strip means: use this
}
return c;
}
Raw access¶
TraceWire(bytes) sends bytes exactly as given, as one frame with the resolved waveform: no order, brightness or
gamma, no retry, the stored pixels untouched. It finds the order of an unknown strip (send {0xFF, 0, 0} and see
which colour lights). GetLastWire() returns the bytes Show() encoded last, with no I/O, valid until the next
Show(); compare it with what a logic analyser captured.
Supply¶
PowerOn() drives the port's power pin active and waits Config::power_on_settle_us; PowerOff() drives it inactive
and keeps the waveform. A port without a GpioSet() hook gets Unsupported. A port with the hook starts
unpowered: call PowerOn() before the first Show(). A port with the hook but no pin must return true from
GpioSet(). After PowerOff(), Show() and
TraceWire() return NotPowered and send nothing, because a driven DIN on an unpowered strip back-feeds it
(Hardware).
// The strip supply on a switch: the port implements GpioSet(), the driver sequences it.
ws2812_rmt::Error ShowAfterPowerUp(Strip& strip) {
if (auto r = strip.PowerOn(); !r) {
return r.error; // Unsupported (no GpioSet hook), NotInitialized or Bus
}
return strip.Show().error;
}
Errors¶
const char* Describe(ws2812_rmt::Error e) {
switch (e) {
case ws2812_rmt::Error::TimingUnreachable:
return "the port's tick rate cannot place a window: use 20 MHz or more";
case ws2812_rmt::Error::Bus:
return "the port failed: channel, rate, send, timeout or underrun";
default:
return ws2812_rmt::ToString(e);
}
}
The pixels are write-only: no identity, no status, no checksum. So Timeout, DeviceIdMismatch, Crc, Busy and
DeviceFault are never returned; a timeout or an underrun that the port detects arrives as Bus. See
Contract for each error.