WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, colours, timing profiles, waveform and configuration. More...

Classes

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

Enumerations

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

Functions

constexpr const char * ws2812_rmt::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Range ws2812_rmt::MakeRange (uint32_t min_ns, uint32_t max_ns, uint32_t nominal_ns) noexcept
 A timing window from its three numbers.
 
constexpr Limits ws2812_rmt::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 ws2812_rmt::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 ws2812_rmt::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 ws2812_rmt::DefaultOrder (Variant variant) noexcept
 The colour order a named variant uses unless Config overrides it.
 
constexpr const char * ws2812_rmt::GetDriverVersion () noexcept
 
constexpr uint32_t ws2812_rmt::GetDriverVersionMajor () noexcept
 
constexpr uint32_t ws2812_rmt::GetDriverVersionMinor () noexcept
 
constexpr uint32_t ws2812_rmt::GetDriverVersionPatch () noexcept
 

Variables

constexpr ColourOrder ws2812_rmt::kOrderGrb
 Green, red, blue: the wire order of every WS2812 and SK6812 RGB part.
 
constexpr ColourOrder ws2812_rmt::kOrderRgb
 Red, green, blue.
 
constexpr ColourOrder ws2812_rmt::kOrderGrbw
 Green, red, blue, white: SK6812RGBW Rev 07 (the default for Variant::Sk6812Rgbw).
 
constexpr ColourOrder ws2812_rmt::kOrderRgbw
 Red, green, blue, white: SK6812RGBW Rev 01 and Rev 03.
 
constexpr uint32_t ws2812_rmt::kMaxDurationNs = 100'000
 Longest single high or low duration a Custom timing may name, in ns (covers 400 kbit/s).
 
constexpr uint32_t ws2812_rmt::kMaxPeriodNs = 200'000
 Longest period a Custom timing may name, in ns.
 
constexpr uint32_t ws2812_rmt::kMaxResetUs = 10'000
 Longest reset a timing or Config::reset_us may name, in microseconds.
 
constexpr uint32_t ws2812_rmt::kResetMarginUs = 20
 Added to the datasheet reset minimum when Config::reset_us is 0, in microseconds (A-3).
 
constexpr size_t ws2812_rmt::kMaxPixels = 65'536
 Largest strip the driver accepts, in pixels.
 
constexpr uint32_t ws2812_rmt::kMaxSettleUs = 1'000'000
 Longest power-on settle Config may ask for, in microseconds.
 
constexpr uint32_t ws2812_rmt::kMaxSlackMs = 60'000
 Longest transmit slack Config may ask for, in milliseconds.
 
constexpr uint32_t ws2812_rmt::kMaxResolutionHz = 1'000'000'000
 The highest tick rate the driver accepts from a port, in Hz.
 
constexpr uint32_t ws2812_rmt::kMaxSupplyMv = 6000
 Supplies above this count as 6 V in MinLogicHighMv() (the absolute maximum is 5.3 V).
 
constexpr uint32_t ws2812_rmt::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 ws2812_rmt::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

Errors, results, colours, timing profiles, waveform and configuration.

Enumeration Type Documentation

◆ Channel

enum class ws2812_rmt::Channel : uint8_t
strong

A colour channel of a pixel.

Enumerator
R 

Red.

G 

Green.

B 

Blue.

W 

White (RGBW parts only).

◆ Error

enum class ws2812_rmt::Error : uint8_t
strong

Why a call failed. Values 0 to 9 are the shared base set; chip-specific values start at 16.

The pixels have no read-back path: no identity, no status, no CRC, so Timeout, DeviceIdMismatch, Crc, Busy and DeviceFault are never returned (docs/contract.md).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded.

InvalidArgument 

Validate() failed, or a pixel index is out of range.

Bus 

A port hook (init, resolution, transmit, power pin) returned false; an underrun the port cannot see is not reported (docs/contract.md).

Timeout 

Not returned by this driver: the port reports a timeout as false.

DeviceIdMismatch 

Not returned by this driver: the pixels are write-only.

Crc 

Not returned by this driver: the frame has no checksum.

Busy 

Not returned by this driver: Show() blocks until the frame is out.

DeviceFault 

Not returned by this driver: no pixel reports a fault.

Unsupported 

PowerOn() or PowerOff() on a port without a GpioSet() hook.

TimingUnreachable 

The port's tick rate cannot place any tick count inside a timing window.

NotPowered 

Show() or TraceWire() between PowerOff() and PowerOn(): nothing is sent.

◆ Gamma

enum class ws2812_rmt::Gamma : uint8_t
strong

The transfer curve applied before brightness (convenience, not a chip feature).

Enumerator
None 

Identity.

Gamma22 

round(255 * (v / 255) ^ 2.2) from a committed table.

◆ LogLevel

enum class ws2812_rmt::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events.

Debug 

Detail for bring-up.

◆ Variant

enum class ws2812_rmt::Variant : uint8_t
strong

The timing generation (window set) of the part, chosen by what is printed on or known about it.

No single waveform serves every part: the windows of the WS2812B alone differ between the 2013 documents, the 2017 document and the V5 and V6 documents, and their intersection is empty. Each named variant is the intersection of the windows of all documents that describe the same parts, so a waveform inside it satisfies every one of those documents (docs/timing.md).

Enumerator
Ws2812 

WS2812 (6 pin): 0.35/0.8/0.7/0.6 us +-150 ns, reset above 50 us.

Ws2812bPreV5 

WS2812B and WS2812S of 2013 to 2017: reset above 300 us.

Ws2812bV5 

WS2812B V5 and V6, WS2812B-2020, WS2812B-1313, WS2812C-2020: reset above 280 us.

Ws2812c 

WS2812C (5050) and WS2812-2020: T1L window 220 to 420 ns.

Ws2812d 

WS2812D-F8: 750 to 1000 ns on T0L and T1H.

Sk6812 

SK6812 RGB (Rev 01): 0.3/0.9/0.6/0.6 us +-150 ns, reset 80 us.

Sk6812Rgbw 

SK6812RGBW: 32 bit frame, low inside a frame below 20 us.

Sk6812Mini 

SK6812MINI and MINI-E: windows of the later revisions, low below 20 us. The SK6812MINIRGBX sheet (skm) only adds windows: its RGBW part takes Sk6812Rgbw or Custom.

Custom 

Any other part with the same frame: the whole timing is Config::custom.

Function Documentation

◆ DefaultOrder()

constexpr ColourOrder ws2812_rmt::DefaultOrder ( Variant  variant)
constexprnoexcept

The colour order a named variant uses unless Config overrides it.

Parameters
variantThe variant.
Returns
GRB for the RGB parts, GRBW for Sk6812Rgbw; a zero-count order for Custom.

◆ GetDriverVersion()

constexpr const char * ws2812_rmt::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0". No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t ws2812_rmt::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t ws2812_rmt::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t ws2812_rmt::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ MakeLimits()

constexpr Limits ws2812_rmt::MakeLimits ( uint32_t  period_min_ns,
uint32_t  period_max_ns,
uint32_t  reset_min_ns,
uint32_t  max_low_ns 
)
constexprnoexcept

The limits of a timing from their four numbers.

Parameters
period_min_nsShortest bit period, 0 none.
period_max_nsLongest bit period, 0 none.
reset_min_nsThe low time that must be exceeded to latch.
max_low_nsThe low time that must stay below inside a frame, 0 for reset_min_ns.
Returns
The limits.

◆ MakeRange()

constexpr Range ws2812_rmt::MakeRange ( uint32_t  min_ns,
uint32_t  max_ns,
uint32_t  nominal_ns 
)
constexprnoexcept

A timing window from its three numbers.

Parameters
min_nsInclusive lower bound.
max_nsInclusive upper bound, 0 for none.
nominal_nsThe target inside the window.
Returns
The window.

◆ MakeTiming()

constexpr Timing ws2812_rmt::MakeTiming ( const Range &  t0h,
const Range &  t0l,
const Range &  t1h,
const Range &  t1l,
const Limits &  limits 
)
constexprnoexcept

A timing from its four windows and its limits.

Parameters
t0h0 code, high time.
t0l0 code, low time.
t1h1 code, high time.
t1l1 code, low time.
limitsThe period, reset and low-time limits.
Returns
The timing.

◆ ProfileTiming()

constexpr Timing ws2812_rmt::ProfileTiming ( Variant  variant)
constexprnoexcept

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").

Parameters
variantA named variant; Custom returns an all-zero timing.
Returns
The timing.

◆ ToString()

constexpr const char * ws2812_rmt::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string; "Unknown" for a value that is not an enumerator.

Variable Documentation

◆ kOrderGrb

constexpr ColourOrder ws2812_rmt::kOrderGrb
inlineconstexpr
Initial value:
{.ch = {Channel::G, Channel::R, Channel::B, Channel::W},
.count = 3}

Green, red, blue: the wire order of every WS2812 and SK6812 RGB part.

◆ kOrderGrbw

constexpr ColourOrder ws2812_rmt::kOrderGrbw
inlineconstexpr
Initial value:
{.ch = {Channel::G, Channel::R, Channel::B, Channel::W},
.count = 4}

Green, red, blue, white: SK6812RGBW Rev 07 (the default for Variant::Sk6812Rgbw).

◆ kOrderRgb

constexpr ColourOrder ws2812_rmt::kOrderRgb
inlineconstexpr
Initial value:
{.ch = {Channel::R, Channel::G, Channel::B, Channel::W},
.count = 3}

Red, green, blue.

◆ kOrderRgbw

constexpr ColourOrder ws2812_rmt::kOrderRgbw
inlineconstexpr
Initial value:
{.ch = {Channel::R, Channel::G, Channel::B, Channel::W},
.count = 4}

Red, green, blue, white: SK6812RGBW Rev 01 and Rev 03.