WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Functions | Variables
Pure functions

Colour maths, encoding, the waveform resolver and frame arithmetic. More...

Functions

constexpr uint8_t ws2812_rmt::Scale8 (uint8_t v, uint8_t b) noexcept
 round(v * b / 255), halves up: exact at b = 255 (identity) and b = 0 (zero), monotone in both arguments, at most half a least significant bit of error. (The old truncating form differed by at most one.)
 
constexpr uint8_t ws2812_rmt::ApplyGamma (uint8_t v, Gamma gamma) noexcept
 The transfer curve of a channel value.
 
constexpr uint8_t ws2812_rmt::ChannelOf (const Colour &colour, Channel channel) noexcept
 One channel of a colour.
 
constexpr uint8_t ws2812_rmt::WireValue (uint8_t v, uint8_t brightness, Gamma gamma) noexcept
 The wire value of a channel: gamma first, then brightness (linear dimming of the corrected value).
 
constexpr bool ws2812_rmt::IsValidOrder (const ColourOrder &order) noexcept
 Whether order is usable: a count of 3 (distinct channels among R, G, B) or 4 (all four).
 
constexpr size_t ws2812_rmt::EncodePixel (const Colour &colour, const ColourOrder &order, uint8_t brightness, Gamma gamma, std::span< uint8_t > out) noexcept
 Encode one pixel into wire order.
 
constexpr size_t ws2812_rmt::EncodeFrame (std::span< const Colour > pixels, const ColourOrder &order, uint8_t brightness, Gamma gamma, std::span< uint8_t > out) noexcept
 Encode a whole strip, pixel 0 first.
 
constexpr size_t ws2812_rmt::DecodeWire (std::span< const uint8_t > wire, const ColourOrder &order, std::span< Colour > out) noexcept
 The inverse of EncodeFrame() at brightness 255 and no gamma, for models and tests.
 
constexpr Colour ws2812_rmt::ExtractWhite (const Colour &colour) noexcept
 Move the common part of red, green and blue into the white channel, for an RGBW strip that should show an RGB colour with the white die. Never applied implicitly.
 
constexpr Colour ws2812_rmt::Wheel (uint8_t position) noexcept
 A colour wheel: red to green to blue to red in three segments of 85 steps.
 
constexpr uint64_t ws2812_rmt::NsToTicks (uint64_t ns, uint64_t hz) noexcept
 round(ns * hz / 1e9), halves up, in 64 bits (ns and hz below 2^32 cannot overflow).
 
constexpr Result< Waveform > ws2812_rmt::ResolveWaveform (const Timing &timing, uint32_t resolution_hz, uint32_t reset_us) noexcept
 Turn a timing into ticks at the port's real tick rate.
 
constexpr uint64_t ws2812_rmt::TicksToNs (uint64_t ticks, uint32_t resolution_hz) noexcept
 Convert ticks back to nanoseconds, rounding up (frame arithmetic, never a window check).
 
constexpr bool ws2812_rmt::WaveformInWindow (Variant variant, const Waveform &wave) noexcept
 The windows check of a waveform against a named profile, in exact integer arithmetic: the mixed-chain and compatibility helper (is this waveform legal for that variant).
 
constexpr uint64_t ws2812_rmt::FrameBits (size_t pixels, uint8_t channels) noexcept
 The number of bits in a frame.
 
constexpr uint64_t ws2812_rmt::FrameTimeNs (size_t pixels, uint8_t channels, const Waveform &wave) noexcept
 Worst-case time of a frame: every bit a one (or a zero, whichever is longer), plus the reset.
 
constexpr uint32_t ws2812_rmt::MaxRefreshHz (size_t pixels, uint8_t channels, const Waveform &wave) noexcept
 The refresh rate the frame time allows.
 
constexpr size_t ws2812_rmt::MaxPixelsAtRate (uint32_t rate_hz, uint8_t channels, const Waveform &wave) noexcept
 The longest strip that still refreshes at rate_hz.
 
constexpr Result< uint32_t > ws2812_rmt::ResolveRmtRate (uint32_t source_hz, uint32_t requested_hz, uint32_t tolerance_ppm=1000U) noexcept
 The tick rate an ESP32 RMT channel really runs at, computed as ESP-IDF v5.5 does (rmt_common.c): the channel divider is rounded to the nearest integer, (clock + request / 2) / request, so the real rate can be above or below the request. On the targets with a group prescaler (all but the ESP32 and ESP32-S2) the group prescaler is the first from 1 up that brings that divider into 1 to 256; on the ESP32 and ESP32-S2 the divider is the rounded one directly, which gives the same rate whenever it is at most 256 (every request above source_hz / 256).
 
constexpr uint32_t ws2812_rmt::MinLogicHighMv (Variant variant, uint32_t vdd_mv) noexcept
 The lowest logic-high level the part's DIN accepts at a supply voltage, from the part's electrical table (informational: the driver cannot see the supply; docs/hardware.md).
 
constexpr Timing ws2812_rmt::TimingOf (const Config &config) noexcept
 The timing a configuration selects.
 
constexpr ColourOrder ws2812_rmt::OrderOf (const Config &config) noexcept
 The wire order a configuration selects.
 
constexpr Result< void > ws2812_rmt::Validate (const Config &config, size_t capacity) noexcept
 Check a configuration against a strip capacity without touching hardware. Pure and constexpr, so a fixed configuration can be proved with static_assert.
 

Variables

constexpr uint64_t ws2812_rmt::kNsPerSecond = 1'000'000'000ULL
 Nanoseconds in a second, for the integer tick arithmetic.
 
constexpr uint32_t ws2812_rmt::kRmtMaxPrescale = 256
 

Detailed Description

Colour maths, encoding, the waveform resolver and frame arithmetic.

Function Documentation

◆ ApplyGamma()

constexpr uint8_t ws2812_rmt::ApplyGamma ( uint8_t  v,
Gamma  gamma 
)
constexprnoexcept

The transfer curve of a channel value.

Parameters
vThe value.
gammaThe curve.
Returns
v for Gamma::None, the table entry for Gamma::Gamma22.

◆ ChannelOf()

constexpr uint8_t ws2812_rmt::ChannelOf ( const Colour &  colour,
Channel  channel 
)
constexprnoexcept

One channel of a colour.

Parameters
colourThe colour.
channelThe channel.
Returns
Its value.

◆ DecodeWire()

constexpr size_t ws2812_rmt::DecodeWire ( std::span< const uint8_t >  wire,
const ColourOrder &  order,
std::span< Colour >  out 
)
constexprnoexcept

The inverse of EncodeFrame() at brightness 255 and no gamma, for models and tests.

Parameters
wireBytes in wire order.
orderThe wire order.
outReceives one colour per complete pixel of wire; unused channels stay 0.
Returns
The pixels written; 0 when order is invalid.

◆ EncodeFrame()

constexpr size_t ws2812_rmt::EncodeFrame ( std::span< const Colour >  pixels,
const ColourOrder &  order,
uint8_t  brightness,
Gamma  gamma,
std::span< uint8_t >  out 
)
constexprnoexcept

Encode a whole strip, pixel 0 first.

Parameters
pixelsThe logical colours.
orderThe wire order.
brightnessLinear dimming.
gammaThe curve.
outReceives pixels.size() x order.count bytes.
Returns
The bytes written; 0 when order is invalid or out is too small (nothing is written).

◆ EncodePixel()

constexpr size_t ws2812_rmt::EncodePixel ( const Colour &  colour,
const ColourOrder &  order,
uint8_t  brightness,
Gamma  gamma,
std::span< uint8_t >  out 
)
constexprnoexcept

Encode one pixel into wire order.

Parameters
colourThe logical colour; w is ignored for a three-channel order.
orderThe wire order.
brightnessLinear dimming.
gammaThe curve.
outReceives order.count bytes.
Returns
The bytes written; 0 when order is invalid or out is too small (nothing is written).

◆ ExtractWhite()

constexpr Colour ws2812_rmt::ExtractWhite ( const Colour &  colour)
constexprnoexcept

Move the common part of red, green and blue into the white channel, for an RGBW strip that should show an RGB colour with the white die. Never applied implicitly.

Parameters
colourAn RGB colour (w is replaced).
Returns
w = min(r, g, b), subtracted from the other three.

◆ FrameBits()

constexpr uint64_t ws2812_rmt::FrameBits ( size_t  pixels,
uint8_t  channels 
)
constexprnoexcept

The number of bits in a frame.

Parameters
pixelsPixels.
channelsChannels per pixel (3 or 4).
Returns
pixels x channels x 8.

◆ FrameTimeNs()

constexpr uint64_t ws2812_rmt::FrameTimeNs ( size_t  pixels,
uint8_t  channels,
const Waveform &  wave 
)
constexprnoexcept

Worst-case time of a frame: every bit a one (or a zero, whichever is longer), plus the reset.

Parameters
pixelsPixels.
channelsChannels per pixel.
waveThe waveform.
Returns
Nanoseconds.

◆ IsValidOrder()

constexpr bool ws2812_rmt::IsValidOrder ( const ColourOrder &  order)
constexprnoexcept

Whether order is usable: a count of 3 (distinct channels among R, G, B) or 4 (all four).

Parameters
orderThe order.
Returns
true when valid.

◆ MaxPixelsAtRate()

constexpr size_t ws2812_rmt::MaxPixelsAtRate ( uint32_t  rate_hz,
uint8_t  channels,
const Waveform &  wave 
)
constexprnoexcept

The longest strip that still refreshes at rate_hz.

Parameters
rate_hzFrames per second, non-zero.
channelsChannels per pixel.
waveThe waveform.
Returns
Pixels; 0 when the rate is 0 or the reset alone does not fit.

◆ MaxRefreshHz()

constexpr uint32_t ws2812_rmt::MaxRefreshHz ( size_t  pixels,
uint8_t  channels,
const Waveform &  wave 
)
constexprnoexcept

The refresh rate the frame time allows.

Parameters
pixelsPixels.
channelsChannels per pixel.
waveThe waveform.
Returns
Frames per second, rounded down; 0 when the frame time is 0.

◆ MinLogicHighMv()

constexpr uint32_t ws2812_rmt::MinLogicHighMv ( Variant  variant,
uint32_t  vdd_mv 
)
constexprnoexcept

The lowest logic-high level the part's DIN accepts at a supply voltage, from the part's electrical table (informational: the driver cannot see the supply; docs/hardware.md).

Parameters
variantThe variant; Custom returns the generic 0.7 x VDD.
vdd_mvThe supply in millivolts.
Returns
Millivolts: 0.7 x VDD (older WS2812*, SK6812MINI), the larger of 3.4 V and 0.7 x VDD (SK6812RGBW: 3.4 V minimum in Rev 01 and Rev 03, 0.7 x VDD in Rev 07; SK6812 RGB: its Rev 01 prints 3.4 V as a typical value only, and the 0.7 x VDD is the driver's choice, the level of the other sheets of the family), the larger of 2.7 V and 0.63 x VDD for the V5 profile (the strictest of its documents: V6.0 and V6.1 print 0.63 x VDD, V6 2025 0.55 x VDD, V5.0 2.7 V). A supply above kMaxSupplyMv counts as kMaxSupplyMv.

◆ NsToTicks()

constexpr uint64_t ws2812_rmt::NsToTicks ( uint64_t  ns,
uint64_t  hz 
)
constexprnoexcept

round(ns * hz / 1e9), halves up, in 64 bits (ns and hz below 2^32 cannot overflow).

Parameters
nsA duration in nanoseconds.
hzA tick rate.
Returns
The nearest tick count.

◆ OrderOf()

constexpr ColourOrder ws2812_rmt::OrderOf ( const Config &  config)
constexprnoexcept

The wire order a configuration selects.

Parameters
configThe configuration.
Returns
config.order unless use_default_order is set, then the variant's default.

◆ ResolveRmtRate()

constexpr Result< uint32_t > ws2812_rmt::ResolveRmtRate ( uint32_t  source_hz,
uint32_t  requested_hz,
uint32_t  tolerance_ppm = 1000U 
)
constexprnoexcept

The tick rate an ESP32 RMT channel really runs at, computed as ESP-IDF v5.5 does (rmt_common.c): the channel divider is rounded to the nearest integer, (clock + request / 2) / request, so the real rate can be above or below the request. On the targets with a group prescaler (all but the ESP32 and ESP32-S2) the group prescaler is the first from 1 up that brings that divider into 1 to 256; on the ESP32 and ESP32-S2 the divider is the rounded one directly, which gives the same rate whenever it is at most 256 (every request above source_hz / 256).

Parameters
source_hzThe source clock in hertz.
requested_hzThe tick rate asked for.
tolerance_ppmThe largest deviation accepted, in parts per million.
Returns
The real rate, or TimingUnreachable when a rate is 0, no divider reaches the request, or the real rate is more than tolerance_ppm from the request.

◆ ResolveWaveform()

constexpr Result< Waveform > ws2812_rmt::ResolveWaveform ( const Timing &  timing,
uint32_t  resolution_hz,
uint32_t  reset_us 
)
constexprnoexcept

Turn a timing into ticks at the port's real tick rate.

Each of the four durations gets the tick count nearest its nominal that lies inside its window (windows inclusive); a bit period below period_min_ns is repaired by lengthening the low, and a period above period_max_ns or an empty window is TimingUnreachable. The reset is reset_us (0: the minimum plus kResetMarginUs), never at or below the minimum, which is a strict bound.

Parameters
timingA valid timing (see Config::custom).
resolution_hzThe tick rate the port reported, 1 to kMaxResolutionHz.
reset_usThe reset low time, 0 for the default, at most kMaxResetUs.
Returns
The waveform, TimingUnreachable when no tick count fits (or the arguments are out of range).

◆ Scale8()

constexpr uint8_t ws2812_rmt::Scale8 ( uint8_t  v,
uint8_t  b 
)
constexprnoexcept

round(v * b / 255), halves up: exact at b = 255 (identity) and b = 0 (zero), monotone in both arguments, at most half a least significant bit of error. (The old truncating form differed by at most one.)

Parameters
vThe channel value.
bThe brightness.
Returns
The scaled value.

◆ TicksToNs()

constexpr uint64_t ws2812_rmt::TicksToNs ( uint64_t  ticks,
uint32_t  resolution_hz 
)
constexprnoexcept

Convert ticks back to nanoseconds, rounding up (frame arithmetic, never a window check).

Parameters
ticksA tick count.
resolution_hzThe tick rate, non-zero.
Returns
ceil(ticks * 1e9 / hz); 0 when resolution_hz is 0.

◆ TimingOf()

constexpr Timing ws2812_rmt::TimingOf ( const Config &  config)
constexprnoexcept

The timing a configuration selects.

Parameters
configThe configuration.
Returns
config.custom for Custom, the profile otherwise.

◆ Validate()

constexpr Result< void > ws2812_rmt::Validate ( const Config &  config,
size_t  capacity 
)
constexprnoexcept

Check a configuration against a strip capacity without touching hardware. Pure and constexpr, so a fixed configuration can be proved with static_assert.

Rejected: an unknown variant or gamma; a custom timing on a named variant, or an inconsistent one on Custom; an order that is invalid, does not match the variant's channel count, or is missing on Custom; a reset_us that is not above the variant's minimum or above kMaxResetUs; a pixel count above the capacity or a capacity of 0 or above kMaxPixels; a settle or slack above its maximum.

Parameters
configThe configuration.
capacityThe pixel capacity of the driver object.
Returns
Ok or InvalidArgument.

◆ WaveformInWindow()

constexpr bool ws2812_rmt::WaveformInWindow ( Variant  variant,
const Waveform &  wave 
)
constexprnoexcept

The windows check of a waveform against a named profile, in exact integer arithmetic: the mixed-chain and compatibility helper (is this waveform legal for that variant).

Parameters
variantA named variant; Custom has no profile and returns false.
waveThe waveform.
Returns
true when every duration lies inside the profile's window, the bit periods obey the period rules, and the reset is above the profile's minimum.

◆ Wheel()

constexpr Colour ws2812_rmt::Wheel ( uint8_t  position)
constexprnoexcept

A colour wheel: red to green to blue to red in three segments of 85 steps.

Parameters
position0 to 255.
Returns
A fully saturated colour.

◆ WireValue()

constexpr uint8_t ws2812_rmt::WireValue ( uint8_t  v,
uint8_t  brightness,
Gamma  gamma 
)
constexprnoexcept

The wire value of a channel: gamma first, then brightness (linear dimming of the corrected value).

Parameters
vThe logical value.
brightnessLinear dimming.
gammaThe curve.
Returns
Scale8(ApplyGamma(v, gamma), brightness).

Variable Documentation

◆ kRmtMaxPrescale

constexpr uint32_t ws2812_rmt::kRmtMaxPrescale = 256
inlineconstexpr

The largest group and channel prescaler of the ESP32 RMT (ESP-IDF v5.5, RMT_LL_GROUP_CLOCK_MAX_INTEGER_PRESCALE and RMT_LL_CHANNEL_CLOCK_MAX_PRESCALE).