70 lines
2.1 KiB
70 lines
2.1 KiB
# 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.
|