WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Concepts | Enumerations | Functions | Variables
ws2812_rmt Namespace Reference

The WS2812_RMT driver: everything it declares lives here; internals in detail. More...

Classes

struct  Colour
 A pixel colour, 8 bit per channel; w is used only by four-channel orders. More...
 
struct  ColourOrder
 The order of the channels on the wire, first sent first. More...
 
struct  Config
 Everything EnsureInitialized() uses. The defaults suit a current WS2812B (V5, V6). More...
 
class  GpioInterface
 CRTP base of the platform port. More...
 
struct  Limits
 The four limits of a Timing (a parameter group of MakeTiming()). More...
 
struct  Range
 A timing window in nanoseconds, with the value the driver aims for. More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  Timing
 The wire timing of one window set. More...
 
struct  Waveform
 What the port needs to send the frame, in ticks of resolution_hz. More...
 
class  Ws2812Rmt
 Driver for one strip of up to PixelCapacity single-wire addressable LEDs. More...
 

Concepts

concept  Ws2812RmtPort
 Satisfied by a class that derives from GpioInterface<Port> and implements the required hooks with exactly the types above, noexcept and returning bool (handbook KB-CPP20-006).
 

Enumerations

enum class  CtrlPin : uint8_t { Power }
 Control pins the port may drive through the optional GpioSet() hook. More...
 
enum class  GpioSignal : uint8_t { INACTIVE = 0 , ACTIVE = 1 }
 Logical level of a pin; the port maps it to the physical polarity. More...
 
enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch = 5 , Error::Crc = 6 , Error::Busy = 7 ,
  Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::TimingUnreachable , Error::NotPowered
}
 Why a call failed. Values 0 to 9 are the shared base set; chip-specific values start at 16. More...
 
enum class  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Variant : uint8_t {
  Variant::Ws2812 , Variant::Ws2812bPreV5 , Variant::Ws2812bV5 , Variant::Ws2812c ,
  Variant::Ws2812d , Variant::Sk6812 , Variant::Sk6812Rgbw , Variant::Sk6812Mini ,
  Variant::Custom
}
 The timing generation (window set) of the part, chosen by what is printed on or known about it. More...
 
enum class  Channel : uint8_t { Channel::R , Channel::G , Channel::B , Channel::W }
 A colour channel of a pixel. More...
 
enum class  Gamma : uint8_t { Gamma::None , Gamma::Gamma22 }
 The transfer curve applied before brightness (convenience, not a chip feature). More...
 

Functions

constexpr uint8_t 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 ApplyGamma (uint8_t v, Gamma gamma) noexcept
 The transfer curve of a channel value.
 
constexpr uint8_t ChannelOf (const Colour &colour, Channel channel) noexcept
 One channel of a colour.
 
constexpr uint8_t 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 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 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 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 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 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 Wheel (uint8_t position) noexcept
 A colour wheel: red to green to blue to red in three segments of 85 steps.
 
constexpr uint64_t 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 > 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 TicksToNs (uint64_t ticks, uint32_t resolution_hz) noexcept
 Convert ticks back to nanoseconds, rounding up (frame arithmetic, never a window check).
 
constexpr bool 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 FrameBits (size_t pixels, uint8_t channels) noexcept
 The number of bits in a frame.
 
constexpr uint64_t 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 MaxRefreshHz (size_t pixels, uint8_t channels, const Waveform &wave) noexcept
 The refresh rate the frame time allows.
 
constexpr size_t 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 > 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 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 TimingOf (const Config &config) noexcept
 The timing a configuration selects.
 
constexpr ColourOrder OrderOf (const Config &config) noexcept
 The wire order a configuration selects.
 
constexpr Result< void > 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.
 
constexpr Variant KconfigVariant () noexcept
 The variant menuconfig selected; Variant::Ws2812bV5 without a selection.
 
constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the datasheet defaults.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Range MakeRange (uint32_t min_ns, uint32_t max_ns, uint32_t nominal_ns) noexcept
 A timing window from its three numbers.
 
constexpr Limits MakeLimits (uint32_t period_min_ns, uint32_t period_max_ns, uint32_t reset_min_ns, uint32_t max_low_ns) noexcept
 The limits of a timing from their four numbers.
 
constexpr Timing MakeTiming (const Range &t0h, const Range &t0l, const Range &t1h, const Range &t1l, const Limits &limits) noexcept
 A timing from its four windows and its limits.
 
constexpr Timing ProfileTiming (Variant variant) noexcept
 The window set of a named variant, as nanoseconds. Values are the intersection of the windows of every document of that variant (docs/timing.md, section "Profiles").
 
constexpr ColourOrder DefaultOrder (Variant variant) noexcept
 The colour order a named variant uses unless Config overrides it.
 
constexpr const char * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

constexpr uint64_t kNsPerSecond = 1'000'000'000ULL
 Nanoseconds in a second, for the integer tick arithmetic.
 
constexpr uint32_t kRmtMaxPrescale = 256
 
constexpr std::array< uint8_t, 256 > kGamma22
 The gamma 2.2 transfer curve for 8 bit values.
 
constexpr uint32_t kMinResolutionHz = 20'000'000
 
constexpr uint32_t kRecommendedResolutionHz = 20'000'000
 
constexpr uint32_t kRmtHalfSymbolMaxTicks = 32'767
 
constexpr ColourOrder kOrderGrb
 Green, red, blue: the wire order of every WS2812 and SK6812 RGB part.
 
constexpr ColourOrder kOrderRgb
 Red, green, blue.
 
constexpr ColourOrder kOrderGrbw
 Green, red, blue, white: SK6812RGBW Rev 07 (the default for Variant::Sk6812Rgbw).
 
constexpr ColourOrder kOrderRgbw
 Red, green, blue, white: SK6812RGBW Rev 01 and Rev 03.
 
constexpr uint32_t kMaxDurationNs = 100'000
 Longest single high or low duration a Custom timing may name, in ns (covers 400 kbit/s).
 
constexpr uint32_t kMaxPeriodNs = 200'000
 Longest period a Custom timing may name, in ns.
 
constexpr uint32_t kMaxResetUs = 10'000
 Longest reset a timing or Config::reset_us may name, in microseconds.
 
constexpr uint32_t kResetMarginUs = 20
 Added to the datasheet reset minimum when Config::reset_us is 0, in microseconds (A-3).
 
constexpr size_t kMaxPixels = 65'536
 Largest strip the driver accepts, in pixels.
 
constexpr uint32_t kMaxSettleUs = 1'000'000
 Longest power-on settle Config may ask for, in microseconds.
 
constexpr uint32_t kMaxSlackMs = 60'000
 Longest transmit slack Config may ask for, in milliseconds.
 
constexpr uint32_t kMaxResolutionHz = 1'000'000'000
 The highest tick rate the driver accepts from a port, in Hz.
 
constexpr uint32_t kMaxSupplyMv = 6000
 Supplies above this count as 6 V in MinLogicHighMv() (the absolute maximum is 5.3 V).
 
constexpr uint32_t kV5MinHighMv = 2700
 The fixed floor of VIH of the V5 family, in millivolts (V5.0, datasheet p.2); later revisions print a fraction of VDD instead (MinLogicHighMv()).
 
constexpr uint32_t kSk6812MinHighMv = 3400
 The 3.4 V input high level of the SK6812 family at 5 V, in millivolts: the minimum of SK6812RGBW Rev 01 and Rev 03 (p.4), the typical value of SK6812 RGB Rev 01 (p.4, which prints no minimum). SK6812RGBX Rev 07 prints 0.7 x VDD instead (p.6); MinLogicHighMv() takes the larger.
 

Detailed Description

The WS2812_RMT driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ CtrlPin

enum class ws2812_rmt::CtrlPin : uint8_t
strong

Control pins the port may drive through the optional GpioSet() hook.

Enumerator
Power 

The strip supply or the level shifter's enable; ACTIVE means powered. Idle: INACTIVE.

◆ GpioSignal

enum class ws2812_rmt::GpioSignal : uint8_t
strong

Logical level of a pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted.

ACTIVE 

The pin function is asserted.

Function Documentation

◆ KconfigDefaults()

constexpr Config ws2812_rmt::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the datasheet defaults.

Returns
Config::Default() with the variant, brightness, reset and settle from Kconfig.

◆ KconfigVariant()

constexpr Variant ws2812_rmt::KconfigVariant ( )
constexprnoexcept

The variant menuconfig selected; Variant::Ws2812bV5 without a selection.

Returns
The variant.

Variable Documentation

◆ kGamma22

constexpr std::array<uint8_t, 256> ws2812_rmt::kGamma22
inlineconstexpr
Initial value:
{{
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1,
1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 4,
4, 4, 4, 5, 5, 5, 5, 6, 6, 6, 6, 7, 7, 7, 8, 8, 8, 9, 9,
9, 10, 10, 11, 11, 11, 12, 12, 13, 13, 13, 14, 14, 15, 15, 16, 16, 17, 17,
18, 18, 19, 19, 20, 20, 21, 22, 22, 23, 23, 24, 25, 25, 26, 26, 27, 28, 28,
29, 30, 30, 31, 32, 33, 33, 34, 35, 35, 36, 37, 38, 39, 39, 40, 41, 42, 43,
43, 44, 45, 46, 47, 48, 49, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60,
61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 73, 74, 75, 76, 77, 78, 79, 81,
82, 83, 84, 85, 87, 88, 89, 90, 91, 93, 94, 95, 97, 98, 99, 100, 102, 103, 105,
106, 107, 109, 110, 111, 113, 114, 116, 117, 119, 120, 121, 123, 124, 126, 127, 129, 130, 132,
133, 135, 137, 138, 140, 141, 143, 145, 146, 148, 149, 151, 153, 154, 156, 158, 159, 161, 163,
165, 166, 168, 170, 172, 173, 175, 177, 179, 181, 182, 184, 186, 188, 190, 192, 194, 196, 197,
199, 201, 203, 205, 207, 209, 211, 213, 215, 217, 219, 221, 223, 225, 227, 229, 231, 234, 236,
238, 240, 242, 244, 246, 248, 251, 253, 255,
}}

The gamma 2.2 transfer curve for 8 bit values.

◆ kMinResolutionHz

constexpr uint32_t ws2812_rmt::kMinResolutionHz = 20'000'000
inlineconstexpr

The lowest tick rate the driver accepts for a named variant: below 20 MHz some profile has a window edge within 10 ns of its value (V5 sits exactly on one at 16 MHz and below, docs/timing.md); Variant::Custom is not limited.

◆ kRecommendedResolutionHz

constexpr uint32_t ws2812_rmt::kRecommendedResolutionHz = 20'000'000
inlineconstexpr

The tick rate to prefer: 50 ns ticks leave margin on every window (ambiguity A-5); a finer rate (40 MHz, 80 MHz) keeps the same margins.

◆ kRmtHalfSymbolMaxTicks

constexpr uint32_t ws2812_rmt::kRmtHalfSymbolMaxTicks = 32'767
inlineconstexpr

The longest half-symbol of an ESP32 RMT symbol, in ticks (15 bits): the limit of every bit phase. The reset is not a symbol: the port holds the line low for it after the last bit.