Kaleidoscope/doc/driver/led/WS2812.md

kaleidoscope::driver::led::WS2812

This driver provides a generic base class for driving WS2812-based LED strips. This is not a plugin, and is not meant to be user-facing. It is meant to be used by developers, and hardware plugins in particular. See the KBDFans KBD4x plugin for a practical, existing example about how to use the driver.

Using the driver

To use the driver, we need to include the header:

#include <kaleidoscope/driver/led/WS2812.h>

For performance reasons, the driver is templated, and requires three template arguments:

1. pin, the PIN the driver will use to communicate with the LED strip.
2. class Color, the color class that determines the order of the RGB components, and should match the component order the LED strip uses. We provide three orders out of the box, all in the kaleidoscope::driver::led::color namespace: RGB, GRB, and BGR.
3. ledCount is the number of LEDs on the strip this instance of the driver should be able to address.

Armed with this knowledge, instantiating an object is as easy as:

using Color = kaleidoscope::driver::led::color::GRB;

kaleidoscope::driver::led::WS2812<PIN_E2, Color, 6> LEDs;

Driver methods

The instantiated WS2812 object will have the following methods:

.led_count()

Returns the number of LEDs, the same value as the ledCount template argument.

.sync()

Synchronises the internal LED state with the hardware, by sending over all of the LED data.

It is recommended to call this at most once per cycle. Calling it less frequently isn't wrong either.

.setColorAt(index, color)

.setColorAt(index, r, g, b)

Sets the color at the given index to the specified value. He value can either be a Color object (the same type as the template argument), or a list of RGB component values.

.getColorAt(index)

Returns the color at the given index, as a Color object.

Further information

To have a better idea how to use the driver in practice, looking at the KBD4x hardware library is recommended.