185 lines
4.2 KiB
Markdown
185 lines
4.2 KiB
Markdown
# WS2812 Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2015-02-05 | [Till Klocke](https://github.com/dereulenspiegel), [Thomas Soëte](https://github.com/Alkorin) | [Till Klocke](https://github.com/dereulenspiegel) | [ws2812.c](../../../app/modules/ws2812.c)|
|
|
|
|
ws2812 is a library to handle ws2812-like led strips.
|
|
It works at least on WS2812, WS2812b, APA104, SK6812 (RGB or RGBW).
|
|
|
|
The library uses UART1 routed on GPIO2 (Pin D4 on NodeMCU DEVKIT) to
|
|
generate the bitstream.
|
|
|
|
## ws2812.init()
|
|
Initialize UART1 and GPIO2, should be called once and before write()
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
## ws2812.write()
|
|
Send data to a led strip using its native format which is generally Green,Red,Blue for RGB strips
|
|
and Green,Red,Blue,White for RGBW strips.
|
|
|
|
#### Syntax
|
|
`ws2812.write(string)`
|
|
|
|
#### Parameters
|
|
- `string` payload to be sent to one or more WS2812 like leds.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
ws2812.init()
|
|
ws2812.write(string.char(255,0,0,255,0,0) -- turn the two first RGB leds to green
|
|
```
|
|
|
|
```lua
|
|
ws2812.init()
|
|
ws2812.write(string.char(0,0,0,255,0,0,0,255) -- turn the two first RGBW leds to white
|
|
```
|
|
|
|
# Buffer module
|
|
For more advanced animations, it is useful to keep a "framebuffer" of the strip,
|
|
interact with it and flush it to the strip.
|
|
|
|
For this purpose, the ws2812 library offers a read/write buffer.
|
|
|
|
#### Example
|
|
Led chaser with a RGBW strip
|
|
```lua
|
|
local i, b = 0, ws2812.newBuffer(300, 4); b:fill(0,0,0,0); tmr.alarm(0, 50, 1, function()
|
|
i=i+1
|
|
b:fade(2)
|
|
b:set(i%b:size()+1, 0, 0, 0, 255)
|
|
b:write()
|
|
end)
|
|
```
|
|
|
|
## ws2812.newBuffer()
|
|
Allocate a new memory buffer to store led values.
|
|
|
|
#### Syntax
|
|
`ws2812.newBuffer(numberOfLeds, bytesPerLed)`
|
|
|
|
#### Parameters
|
|
- `numberOfLeds` length of the led strip
|
|
- `bytesPerLed` 3 for RGB strips and 4 for RGBW strips
|
|
|
|
#### Returns
|
|
`ws2812.buffer`
|
|
|
|
## ws2812.buffer:get()
|
|
Return the value at the given position
|
|
|
|
#### Syntax
|
|
`buffer:get(index)`
|
|
|
|
#### Parameters
|
|
- `index` position in the buffer (1 for first led)
|
|
|
|
#### Returns
|
|
`(color)`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:get(2) -- return the color of the second led
|
|
```
|
|
## ws2812.buffer:set()
|
|
Set the value at the given position
|
|
|
|
#### Syntax
|
|
`buffer:set(index, color)`
|
|
|
|
#### Parameters
|
|
- `index` position in the buffer (1 for the first led)
|
|
- `color` bytes of the color
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:set(1, 255, 0, 0) -- set the first led green for a RGB strip
|
|
```
|
|
## ws2812.buffer:size()
|
|
Return the size of the buffer in number of leds
|
|
|
|
#### Syntax
|
|
`buffer:size()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`int`
|
|
|
|
## ws2812.buffer:fill()
|
|
Fill the buffer with the given color.
|
|
The number of given bytes must match the number of bytesPerLed of the buffer
|
|
|
|
#### Syntax
|
|
`buffer:fill(color)`
|
|
|
|
#### Parameters
|
|
- `color` bytes of the color
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:fill(0, 0, 0) -- fill the buffer with black for a RGB strip
|
|
```
|
|
## ws2812.buffer:fade()
|
|
Fade in or out. Defaults to out. Multiply or divide each byte of each led with/by the given value. Useful for a fading effect.
|
|
|
|
#### Syntax
|
|
`buffer:fade(value [, direction])`
|
|
|
|
#### Parameters
|
|
- `value` value by which to divide or multiply each byte
|
|
- `direction` ws2812.FADE\_IN or ws2812.FADE\_OUT. Defaults to ws2812.FADE\_OUT
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:fade(2)
|
|
buffer:fade(2, ws2812.FADE_IN)
|
|
```
|
|
## ws2812.buffer:shift()
|
|
Shift the content of the buffer in positive or negative direction. This allows simple animation effects.
|
|
|
|
#### Syntax
|
|
`buffer:shift(value [, mode])`
|
|
|
|
#### Parameters
|
|
- `value` number of pixels by which to rotate the buffer. Positive values rotate forwards, negative values backwards.
|
|
- `mode` is the shift mode to use. Can be one of `ws2812.SHIFT_LOGICAL` or `ws2812.SHIFT_CIRCULAR`. In case of SHIFT\_LOGICAL, the freed pixels are set to 0 (off). In case of SHIFT\_CIRCULAR, the buffer is treated like a ring buffer, inserting the pixels falling out on one end again on the other end. Defaults to SHIFT\_LOGICAL.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
buffer:shift(3)
|
|
```
|
|
|
|
## ws2812.buffer:write()
|
|
Output the buffer to the led strip
|
|
|
|
#### Syntax
|
|
`buffer:write()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|
|
|