nodemcu-firmware/docs/en/modules/ws2812.md

# 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`