WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
ws2812_rmt::Ws2812Rmt< Port, PixelCapacity > Class Template Reference

Driver for one strip of up to PixelCapacity single-wire addressable LEDs. More...

#include <ws2812_rmt.hpp>

Public Member Functions

 Ws2812Rmt (Port &port, const Config &config=Config::Default()) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail; the pixels start black.
 
 Ws2812Rmt (const Ws2812Rmt &)=delete
 One driver object per strip.
 
Ws2812Rmt & operator= (const Ws2812Rmt &)=delete
 One driver object per strip.
 
Result< void > EnsureInitialized () noexcept
 Start the driver, once: the only way to initialise it.
 
bool IsInitialized () const noexcept
 
Result< void > SetPixel (size_t index, const Colour &colour) noexcept
 Store a colour; nothing is sent until Show(). The logical colour is kept, so brightness stays reversible.
 
Result< Colour > GetPixel (size_t index) const noexcept
 Read back a stored colour (the logical colour, before brightness and gamma). No I/O.
 
void Fill (const Colour &colour) noexcept
 Set every pixel of the strip to colour. No I/O.
 
void Clear () noexcept
 Set every pixel to black. No I/O.
 
void SetBrightness (uint8_t brightness) noexcept
 Set the linear brightness applied at Show(); 0 is off, 255 is unchanged. No I/O.
 
uint8_t Brightness () const noexcept
 
void SetGamma (Gamma gamma) noexcept
 Set the transfer curve applied at Show(); an unknown value acts as Gamma::None. No I/O.
 
Result< void > Show () noexcept
 Encode the pixels (gamma, then brightness, in the wire order) and send them, blocking until the frame and the reset are out. One pass, no allocation. A failed send leaves the pixels intact and the driver usable; the next Show() or TraceWire() first waits a full reset through DelayUs(), so a half frame the failure left in the pixels is latched and cannot shift the next one.
 
Result< void > TraceWire (std::span< const uint8_t > bytes) noexcept
 Single-shot raw access: send bytes exactly as given, as one frame with the resolved waveform. No colour order, brightness or gamma, no retry, the stored pixels untouched. For finding the order of a strip and for bench work. Like Show() it blocks until the bytes and the reset are out.
 
std::span< const uint8_t > GetLastWire () const &noexcept
 The bytes Show() encoded last, whether or not they were sent; empty before the first Show(). No I/O. The view is valid until the next Show().
 
void GetLastWire () const &&=delete
 Not on a temporary driver: the view would dangle (handbook KB-CPP20-044).
 
Result< void > PowerOn () noexcept
 Switch the strip supply on and wait Config::power_on_settle_us.
 
Result< void > PowerOff () noexcept
 Switch the strip supply off. The waveform is kept; no re-initialisation is needed. Show() and TraceWire() return NotPowered until PowerOn() succeeds. The switch-off is never refused for a state the driver is in doubt about.
 
size_t Length () const noexcept
 
uint8_t ChannelsPerPixel () const noexcept
 
Result< Waveform > CurrentWaveform () const noexcept
 
Result< uint32_t > FrameTimeUs () const noexcept
 Worst-case time of one Show(): every bit the longer of the two codes, plus the reset.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
 

Detailed Description

template<Ws2812RmtPort Port, size_t PixelCapacity>
requires detail::NonZeroSize<PixelCapacity>
class ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >

Driver for one strip of up to PixelCapacity single-wire addressable LEDs.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start; then set pixels and call Show(). Show() and CurrentWaveform() return NotInitialized until EnsureInitialized() has succeeded; the pixel setters only store.

Optional hooks: bool GpioSet(CtrlPin, GpioSignal) (the strip supply; without it PowerOn() and PowerOff() return Unsupported; with it the strip starts unpowered, and Show() and TraceWire() are refused with NotPowered until the first successful PowerOn() and again after PowerOff()), void Log(LogLevel, const char*).

Concurrency: one owner task per strip; no locking, never from an interrupt. Memory: PixelCapacity pixels of 4 bytes plus PixelCapacity x 4 wire bytes live inside the object, so give it static storage on a small stack.

Template Parameters
PortYour class derived from GpioInterface<Port>.
PixelCapacityThe most pixels the strip object holds, 1 to kMaxPixels.

Constructor & Destructor Documentation

◆ Ws2812Rmt()

template<Ws2812RmtPort Port, size_t PixelCapacity>
ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::Ws2812Rmt ( Port &  port,
const Config &  config = Config::Default() 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail; the pixels start black.

Parameters
portThe port; it must outlive the driver.
configThe configuration, checked by EnsureInitialized() before any I/O.

Member Function Documentation

◆ Brightness()

template<Ws2812RmtPort Port, size_t PixelCapacity>
uint8_t ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::Brightness ( ) const
inlinenoexcept
Returns
The brightness. No I/O.

◆ ChannelsPerPixel()

template<Ws2812RmtPort Port, size_t PixelCapacity>
uint8_t ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::ChannelsPerPixel ( ) const
inlinenoexcept
Returns
The channels per pixel on the wire (3 or 4). No I/O.

◆ CurrentWaveform()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< Waveform > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::CurrentWaveform ( ) const
noexcept
Returns
The waveform in use, or NotInitialized. No I/O.

◆ EnsureInitialized()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::EnsureInitialized ( )
noexcept

Start the driver, once: the only way to initialise it.

Validates the configuration (no I/O on failure), lets the port create its channel, asks the port for its real tick rate and resolves the waveform inside the datasheet windows. After it succeeds later calls return Ok at once with no I/O; after it fails the driver stays uninitialised and the next call starts again from the beginning.

Returns
Ok, InvalidArgument (Validate() failed), Bus (the port could not start or report a rate) or TimingUnreachable (no tick count fits a window at that rate).

◆ Fill()

template<Ws2812RmtPort Port, size_t PixelCapacity>
void ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::Fill ( const Colour &  colour)
noexcept

Set every pixel of the strip to colour. No I/O.

Parameters
colourThe logical colour.

◆ FrameTimeUs()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< uint32_t > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::FrameTimeUs ( ) const
noexcept

Worst-case time of one Show(): every bit the longer of the two codes, plus the reset.

Returns
Microseconds rounded up, or NotInitialized. No I/O.

◆ GetConfig()

template<Ws2812RmtPort Port, size_t PixelCapacity>
const Config & ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration stored. No I/O.

◆ GetLastWire()

template<Ws2812RmtPort Port, size_t PixelCapacity>
std::span< const uint8_t > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::GetLastWire ( ) const &
inlinenoexcept

The bytes Show() encoded last, whether or not they were sent; empty before the first Show(). No I/O. The view is valid until the next Show().

Returns
The wire bytes.

◆ GetPixel()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< Colour > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::GetPixel ( size_t  index) const
noexcept

Read back a stored colour (the logical colour, before brightness and gamma). No I/O.

Parameters
indexPixel index.
Returns
The colour, or InvalidArgument.

◆ IsInitialized()

template<Ws2812RmtPort Port, size_t PixelCapacity>
bool ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized(). No I/O.

◆ Length()

template<Ws2812RmtPort Port, size_t PixelCapacity>
size_t ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::Length ( ) const
inlinenoexcept
Returns
The number of pixels of the strip (Config::pixel_count, or the capacity). No I/O.

◆ PowerOff()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::PowerOff ( )
noexcept

Switch the strip supply off. The waveform is kept; no re-initialisation is needed. Show() and TraceWire() return NotPowered until PowerOn() succeeds. The switch-off is never refused for a state the driver is in doubt about.

Returns
Ok, NotInitialized, Unsupported (no GpioSet() hook) or Bus.

◆ PowerOn()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::PowerOn ( )
noexcept

Switch the strip supply on and wait Config::power_on_settle_us.

Returns
Ok, NotInitialized, Unsupported (no GpioSet() hook) or Bus.

◆ SetBrightness()

template<Ws2812RmtPort Port, size_t PixelCapacity>
void ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::SetBrightness ( uint8_t  brightness)
inlinenoexcept

Set the linear brightness applied at Show(); 0 is off, 255 is unchanged. No I/O.

Parameters
brightnessThe scale, 0 to 255.

◆ SetGamma()

template<Ws2812RmtPort Port, size_t PixelCapacity>
void ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::SetGamma ( Gamma  gamma)
inlinenoexcept

Set the transfer curve applied at Show(); an unknown value acts as Gamma::None. No I/O.

Parameters
gammaThe curve.

◆ SetPixel()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::SetPixel ( size_t  index,
const Colour &  colour 
)
noexcept

Store a colour; nothing is sent until Show(). The logical colour is kept, so brightness stays reversible.

Parameters
indexPixel index, 0 to Length() - 1.
colourThe colour.
Returns
Ok, or InvalidArgument for an index out of range (nothing changes).

◆ Show()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::Show ( )
noexcept

Encode the pixels (gamma, then brightness, in the wire order) and send them, blocking until the frame and the reset are out. One pass, no allocation. A failed send leaves the pixels intact and the driver usable; the next Show() or TraceWire() first waits a full reset through DelayUs(), so a half frame the failure left in the pixels is latched and cannot shift the next one.

With a GpioSet() hook it is refused (NotPowered) and nothing is sent until the first successful PowerOn() and again after PowerOff(): a driven DIN on an unpowered strip back-feeds it (docs/hardware.md).

Returns
Ok, NotInitialized or NotPowered (no port call is made), or Bus (the port's Transmit() failed, timed out or underran where the port can see it; an underrun it cannot see returns Ok, see docs/contract.md).

◆ TraceWire()

template<Ws2812RmtPort Port, size_t PixelCapacity>
Result< void > ws2812_rmt::Ws2812Rmt< Port, PixelCapacity >::TraceWire ( std::span< const uint8_t >  bytes)
noexcept

Single-shot raw access: send bytes exactly as given, as one frame with the resolved waveform. No colour order, brightness or gamma, no retry, the stored pixels untouched. For finding the order of a strip and for bench work. Like Show() it blocks until the bytes and the reset are out.

Parameters
bytesThe wire bytes, 1 to 4 per pixel of the capacity.
Returns
Ok, NotInitialized or NotPowered (no port call is made), InvalidArgument (empty or too long) or Bus.

The documentation for this class was generated from the following file: