|
WS2812_RMT Driver 0.1.0
API 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. | |
The WS2812_RMT driver: everything it declares lives here; internals in detail.
|
strong |
|
strong |
|
constexprnoexcept |
The configuration menuconfig selected, on top of the datasheet defaults.
Config::Default() with the variant, brightness, reset and settle from Kconfig.
|
constexprnoexcept |
The variant menuconfig selected; Variant::Ws2812bV5 without a selection.
|
inlineconstexpr |
The gamma 2.2 transfer curve for 8 bit values.
|
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.
|
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.
|
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.