# 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][kbd4x] plugin for a practical, existing example about how to use the
driver.

 [kbd4x]: ../../../src/kaleidoscope/hardware/kbdfans/KBD4x.h

## Using the driver

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

```c++
#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:

```c++
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][kbd4x] hardware library is recommended.