# Fork This fork uses the updated native module bindings submodule which supports more hardware revisions. # control ws281x-LEDs with node.js **NOTE: This will only ever work on the Raspberry Pi.** This module provides native bindings to the [rpi_ws281x](https://github.com/jgarff/rpi_ws281x) library by Jeremy Garff that is used to control strips of individually addressable LEDs directly from a raspberry-pi. Supported are all LEDs of the NEOPIXEL/WS281x-family (specifically WS2811, WS2812, WS2812b, SK6812, SK6812W in all variations). ## setup this module is available via npm: npm install @simontaga/rpi-ws281x-native if you prefer installing from source: npm install -g node-gyp git clone --recursive https://github.com/Simontaga/node-rpi-ws281x-native.git cd rpi-ws281x-native npm install ## node-version You will need an up-to-date version of nodejs that supports at least some es6-features (>= 6.5). If you are running on a RaspberryPi 1 or zero (running an ARMv61 processor), you might need to download and install the nodejs-binaries manually. Head over to https://nodejs.org/dist, find the version to install and download the `-armv61`-version. See here for more information: https://raspberrypi.stackexchange.com/questions/48303/install-nodejs-for-all-raspberry-pi ## Usage Example This is the simplest example that will actually do something. It will initialize the driver for 100 LEDs and set all LEDs to the same, pinkish color: ```javascript const ws281x = require('rpi-ws281x-native'); const channel = ws281x(100, { stripType: 'ws2812' }); const colorArray = channel.array; for (let i = 0; i < channel.count; i++) { colorsArray[i] = 0xffcc22; } ws281x.render(); ``` ## API ### `ws281x(numLeds: number, options = {}): Channel` For simple setups (i.e. those using just one channel), there is an easy way for initialization using the top-level export function. #### Example: ```javascript const ws2821x = require('rpi-ws281x-native'); const options = { dma: 10, freq: 800000, gpio: 18, invert: false, brightness: 255, stripType: ws281x.stripType.WS2812 }; const channel = ws281x(20, options); const colors = channel.array; // update color-values colors[42] = 0xffcc22; ws281x.render(); ``` This function takes two parameters, the number of LEDs (`numLeds`) and an `options`-object which is entirely optional. These options combine the channel-options and the global option from the init-function as described below. The returned object is a channel object (also described below) that gives access to the color-data. ### `ws281x.init(options: Object): Channel[]` Configures and initializes the drivers and returns an array of channel-interfaces. #### Example: ```javascript const ws2821x = require('rpi-ws281x-native'); const channels = ws281x.init({ dma: 10, freq: 800000, channels: [ {count: 20, gpio: 18, invert: false, brightness: 255, stripType: 'ws2812'}, {count: 20, gpio: 13, invert: false, brightness: 128, stripType: 'sk6812-rgbw'} ] }); ``` The only parameter `options` is an object with the following properties (unspecified properties will use the default-value): - `dma: number`: the dma-number to use for the driver's data-transport to the LEDs (default: `10`) - `freq: number`: the frequency in Hz of the control-signal. This is 800kHz for ws2812/sk6812 LEDs and 400kHz for older ws2811 LEDs (default `800000`). - `channels: Object[]`: an array of one or two objects with channel-specific configuration for the two possible outputs: - `count: number`: the number of LEDs on this channel. - `gpio: number`: the GPIO port-number the strip is connected to. (default: `18` for the first channel and `12` for the second channel) - `invert: boolean`: whether the output-signal should be inverted (needed when a inverting level-shifter is used) (default: `false`) - `brightness: number`: the brightness, applied to all LEDs on this channel. Value between 0 and 255 (default: `255`). - `stripType: string|number`: the LED-type connected on this channel. See `./lib/constants.js`. Can be a string-constant or one of the values from `ws281x.stripType` (default `ws281x.stripType.WS2812`) ### `ws281x.render()` Send the current state of the channel color-buffers to the LEDs. #### Example: ```javascript const ws2821x = require('rpi-ws281x-native'); // initialize const [channel] = ws281x.init(options); // set some color-values channel.array[12] = 0xff0000; // render ws281x.render(); ``` ### `ws281x.reset()` Clear all color-values and render. ### `ws281x.finalize()` Shut down the drivers and free all resources. ### `Channel` Each of the channels is represented by a channel-object. Channels do not contain any public methods – all interaction happens through the following properties: - `[readonly] count: number`: number of LEDs on this channel - `[readonly] stripType: number`: the numeric LED-type (see `ws281x.stripType`) - `[readonly] invert: boolean`: if the signal for the LEDs is inverted - `[readonly] gpio: number`: the GPIO port-number used - `brightness: number`: the current brightness. Setting this property will have an effect with the very next `render()`-call. - `array: Uint32Array`: the color-data, represented as a Uint32Array. Each index in this array represents the color-value of an LED in 32 bits (8 bit each for white, red, green, blue, counting from MSB to LSB). So the numbers can be specified in hex using `0xwwrrggbb`-format. For RGB-LEDs (those without a seperate white-channel) the MSB is ignored. - `buffer: Buffer`: A node-buffer, providing an alternative way to manipulate the color-data. This is a view on the same array-buffer that is used by the Uint32Array. When using the buffer, make sure to check for endianness to prevent problems (I believe it is little endian on the raspebrry-pi). ## testing basic functionality connect the WS2812-strip to the raspberry-pi as described [here](https://learn.adafruit.com/neopixels-on-raspberry-pi/raspberry-pi-wiring) and run the command `sudo node examples/rainbow.js `. You should now see some rainbow-colors animation on the LED-strip. ## needs to run as root As the native part of this module needs to directly interface with the physical memory of the raspberry-pi (which is required in order to configure the PWM and DMA-modules), it always has to run with root-privileges (there are probably ways around this requirement, but that doesn't change the fact that the node-process running the LEDs needs access to the raw physical memory – a thing you should never allow to any user other than root). If you are using this module as part of a program that should not be run with elevated privileges, it would be a good idea to have the LED-driver running in a seperate process. In such a case you could use the openpixel-control protocol to send the pixel-data to the driver-process. A stream-based node-implementation and some more information [can be found here](https://github.com/beyondscreen/node-openpixelcontrol). ## Hardware There is a guide [over at adafruit.com](https://learn.adafruit.com/neopixels-on-raspberry-pi) on how to get the hardware up and running. I followed these instructions by the word and had a working LED-strip. Essentially, you need the Raspberry Pi, a logic-level converter and of course a LED-Strip or other types of WS281x/SK6812-LEDs. The logic-level shifter is required to shift the output-voltage of the GPIO from 3.3V up to 5V. The adafruit-guide mentions the 74AHCT125, but in fact most of the 74HCT-series chips or even a simple transistor can be used for this. To connect all that together, I'd recommend buying a small breadboard and some jumper-wires. Also, consider buying a 5V power-supply that can deliver up to 60mA per LED (so you'll need up to 6A (30W) to fully power 100 LEDs). For smaller applications, a good USB-charger should do the job just fine. ### Buying stuff A short checklist of what you will need: * Raspberry-PI and SD-Card * 5V power-supply (Meanwell for instance builds really good ones) * LED-Strip with WS2811/WS2812 Controllers (there are several other controller-variations that are not supported) * a breadboard and some jumper-wires (m/m as well as at least two f/m to connect the GPIO-Pins) * a 3.3V to 5V logic-level converter (74AHCT125 or 74HCT125N, others will probably also work) * more wire to connect the LED-strips You can buy everything at [adafruit.com](https://adafruit.com), [sparkfun](https://sparkfun.com), on ebay or your favourite electronics retailer (germany: check [conrad electronic](http://www.conrad.de), [watterott](http://watterott.com) or [reichelt](http://reichelt.de) where I bought most of my stuff). If you got more time than money to spend, I recommend buying directly from chinese manufacturers (via aliexpress for example). Shipping takes ages, but you end up paying only half as much for the LEDs for example. ## Known Issues ### Raspberry integrated soundcard There is a conflict where the internal soundcard uses the same GPIO / DMA / PWM functions that are needed to run the LED-drivers. As far as I know you can not use both at the same time. To disable audio, comment out the following line in config.txt contained on the boot partion. #dtparam=audio=on As @AdyiPool [pointed out](https://github.com/beyondscreen/node-rpi-ws281x-native/issues/49), that file seems to not exist in newer raspbian-versions, Alternatively, you can create a file `/etc/modprobe.d/blacklist-ws281x.conf` with the following contents (effectively preventing sound-related modules to be loaded into the kernel): ``` blacklist snd_bcm2835 blacklist snd_pcm blacklist snd_timer blacklist snd_pcsp blacklist snd ``` (after updating the file you need to run `sudo update-initramfs -u` to get the changes into the boot-partition or something like that) If anyone finds a better solution please get in touch!