Library for controlling addressable LEDs (such as NeoPixels) from firmata or Johnny Five.
npm install node-pixel-async> A completely derivative work of node-pixel
I am using this repo as a place to make rapid changes, as it matures and I am able to add more meaningful updates to it I will update this readme. Until then consider this repo as unuseable unless you understand all of the code in it. I will be keeping it up to date with node-pixel, and providing what patches I can. I'm trying to get something done by end of this month and iteration spped is vital!
Back to the README!
We are building docs for this now here. Please use them for info about this project, they are aut-generated.
The purpose of this library is to provide a node js interface for addressable
RGB LEDs. Most commonly these are known as Neo Pixels (if you shop at Adafruit)
however any WS2812b addressable LED should work with this library.
The current iteration supports two methods of set up:
* a custom version of firmata that provides an interface to talk to the "pixels".
* an I2C "backpack" using an arduino pro mini or nano that provides the interface
and control of the pixels and then the IO controller talks to this backpack over
I2C messages.
The pixel library can be used with both Johnny-Five or stock Node Firmata and
can be used by any board that provides an IO interface with I2C support such as
a Raspberry PI.
Both fimwares are provided in this repo in the
firmware/build directory.
If you need some help getting your pixel strip working with johnny five jump into
the Gitter Chat or reach out to
ajfisher on twitter or just raise an
issue here.
Installation of both backpack and custom firmata are covered in detail in the
Installation Guide.
Short version for node-pixel custom firmata.
``
npm install node-pixel
npm install -g nodebots-interchange
Plug in your arduino
`
interchange install git+https://github.com/ajfisher/node-pixel -a uno --firmata
Note that on windows, you may need to explictly pass a port to flash due to the
way com ports work. eg:
`
interchange install git+https://github.com/ajfisher/node-pixel -a uno -p COM3 --firmata
Multiple led strips on one arduino or backpack are supported up to a maximum
of 8 individual strips (8 pins in use at once). Each strip can be different
lengths but you can only have a maximum of 192 pixels for Firmata and about
500 pixels for the backpack version.
Multiple strips connected to a single board or backpack are for the purposes
of node-pixel considered to be a single strip and are joined together in sequence
in the order that you define them.
On a backpack, the strips are defined sequentially from pin 0-7 on the backpack.
On an arduino, each strip can be defined with an individual pin which doesn't
need to be sequential (eg you can use pin 3, then pin 9, then pin 7).
One thing to note is that the timings on these strips are quite tight and you
will reach an upper limit of how much data you can push to the board controlling
the pixels (all that RGB data going over the wire) and the sheer number of
pixels you can refresh quickly (each pixel is written "in turn"). As such,
you may run into some blocking conflicts. These are discussed in
this issue.
The Pixel API is provided below.
A sequence of LEDs collected together is called a strip. A strip hasstrip
a controller to tell it to use the custom firmata or I2C backpack. A
can be a single physical strip in which case a single and length canpin
be provided. Otherwise it is made up of multiple physical strips, each of which
have their own and length and are composed together into order by usingstrips
the array as part of the definition of the object.
For the purposes of interaction however, once a strip is defined, it is all
one logical unit and the firmware will take care of writing data in the right
order, performing optimisations for strips that have or haven't changed and
writing in sequence or parallel as appropriate.
* options An object of property parameters
| Property | Type | Value / Description | Default | Required |
|----------|------|---------------------|---------|----------|
| pin | Number | Digital Pin. Used to set which pin the signal line to the pixels is being used when using a single strip. | 6 | no (4) |
| length | Number | Number of pixels to be set on a single strip or all strips if individual lengths are not defined in the strips array | 32 | no (5) |
| color_order | Constant | Determines the order of the RGB values against the pixels. Can be GRB, RGB or BRG | pixel.COLOR_ORDER.GRB | no (6) |
| strips | Array | Array of pin and length objects or array of length objects | 6 | no (2)(3) |
| board | IO Object | IO Board object to use with Johnny Five | undefined | yes(1) |
| firmata | Firmata board | Firmata board object to use with Firmata directly | undefined | yes(1) |
| controller | String | I2CBACKPACK, FIRMATA | FIRMATA | no |
| skip_firmware_check | Boolean | If the controller is FIRMATA, optionally skip the check for the matching node-pixel sketch | false | no |
| gamma | Number | A number representing the gamma correction for a strip. Can be any decimal number. 2.8 generally works well. | 1.0 (7) | no |
(1) A board or firmata object is required but only one of these needs to be set.
(2) If using a backpack use an array of lengths eg [8, 8, 8] which would set
pins 0, 1 & 2 on the backpack to have strips of length 8 each on them.
(3) If using custom firmata then use an array of objects eg
[ {pin: 4, length: 8}, {pin: 10, length: 8}, {pin: 11, length: 8} ]
which would set pins 4, 10 & 11 to have strips of length 8 on each of them.
(4) If not supplied, it is assumed a strips array will be provided with apin parameter for each object in the array.
(5) If not supplied, it is assumed a strips array will be provided with alength parameter for each object in the array.
(6) If supplied it will apply to all strips unless overridden selectively instrips
the array eg [ {color_order: pixel.COLOR_ORDER.RGB}, ..]
(7) Currently set to 1.0 to maintain current behaviour. Will move to 2.8 default
in version 0.10.
* length - number of pixels in the strip
* - the currently set gamma for the strip
* onready() - emits when the strip is configured.onerror()
* - returns the error that occurred.
_Johnny-Five instantiation_
`javascript
pixel = require("node-pixel");
five = require("johnny-five");
var board = new five.Board(opts);
var strip = null;
board.on("ready", function() {
strip = pixel.Strip({
board: this,
controller: "FIRMATA",
strips: [ {pin: 6, length: 4}, ], // this is preferred form for definition
gamma: 2.8, // set to a gamma that works nicely for WS2812
});
strip.on("ready", function() {
// do stuff with the strip here.
});
});
`
_Firmata instantiation_
`javascript
pixel = require("node-pixel");
var firmata = require('firmata');
var board = new firmata.Board('path to usb',function(){
strip = pixel.Strip({
pin: 6, // this is still supported as a shorthand
length: 4,
firmata: board,
controller: "FIRMATA",
});
strip.on("ready", function() {
// do stuff with the strip here.
});
});
`
_Johnny Five with backpack_
`javascript
pixel = require("node-pixel");
five = require("johnny-five");
var board = new five.Board(opts);
board.on("ready", function() {
strip = pixel.Strip({
board: this,
controller: "I2CBACKPACK",
strips: [4, 6, 8], // 3 physical strips on pins 0, 1 & 2 with lengths 4, 6 & 8.
});
strip.on("ready", function() {
// do stuff with the strip here.
});
});
`
Note that Johnny-Five uses the board option and firmata uses the firmata option.
This is because the pixel library supports a Board capable of presenting an
IO interface. The library will work out the right thing to do based on the
board being passed and the controller being set.
#### show();
The show method should be called at the point you want to "set" the frame on
the strip of pixels and show them.
Note that when this method is called it will trigger the process that writes
the frame to the strips. If you have a very long strip of LEDs this may take
some time (assume 0.5ms per pixel) and is a blocking operation in most cases.
This gives you an upper limit as to how many frames you can drive per second.
Example
`javascript
// ... make pixel modifications
strip.show(); // make the strip latch and update the LEDs
`
Addressable LEDs work by clocking data along their entire length and so
you make the various changes you want to the strip as you need to without
triggering the display (like a frame buffer). Once you're ready you can then
call show() to propagate this data through the LEDs and display the frame.
#### off();
All LEDs on the strip can be turned off by using the .off() method. This effectively clears the current colours set on the strip.
.clear() is also aliased to the same method.
Example
`javascript`
strip.off(); // turn the strip off / clear pixel colours
#### color( colourstring );
All LEDs on the strip can be set to the same colour using the .color() method.
.colour() is also aliased to the same method.
Parameters
* colourstring A String as a standard HTML hex colour or a CSS colour name,Array
or a CSS rgb(r, g, b) value used to specify the colour of the strip. Alternatively
an object as an rgb value eg [r, g, b]
Examples
_Set strip using a hex value_
`javascript`
strip.color("#ff0000"); // turns entire strip red using a hex colour
strip.show();
_Update strip using a named CSS colour_
`javascript`
strip.colour("teal"); // sets strip to a blue-green color using a named colour
strip.show();
_You can also use CSS RGB values_
`javascript`
strip.color("rgb(0, 255, 0)"); // sets strip to green using rgb values
strip.show();
_Or set using an array of RGB values_
`javascript`
strip.color([255, 255, 0]); // Sets strip using an array
strip.show();
#### shift( amt, direction, wrap );
All LEDs on the strip can be shifted along the strip forwards or backwards
by the given amount. This is very useful for long strip animation when you're
moving the whole strip by a pixel in one direction each frame and means you
don't have to send an update of framelength messages
Parameters
* amt A Number representing the number of pixels you want everything toPixel.FORWARD
shift by.
* direction Either or Pixel.BACKWARD value which determinesBoolean
direction of travel. Forward direction is in the flow index values (ie index 1->2 etc).
* wrap a representing whether to wrap the values that go off the
"end" of the strip back around to the start - useful for circular displays.
Example
`javascript`
strip.pixel(0).color("#000");
strip.pixel(1).color("red");
strip.shift(1, pixel.FORWARD, true);
strip.pixel(1).color; // will now be nothing
strip.pixel(2).color; // will now be red.
#### pixel( address );
Individual pixels can be addressed by the pixel method using their address in
the sequence.
Note that if you have two physical strips of 8 and 10 then pixel(10) will be
the third pixel on the second physical strip.
Parameters
* address A Number indexing the pixel you want. Returns a Pixel object.
Example
`javascript`
var p = strip.pixel(1); // get the second LED. p is now a Pixel object
A pixel is an individual element in the strip. It is fairly basic and it's API
is detailed below.
#### color( color string )
Colors work exactly the same way on individual pixels as per strips so see the
strip.color reference above.
.colour() is aliased to this method as well.
Parameters
* color string A String providing the hex colour, CSS colour name or CSSArray
rgb() values to be used to set the individual pixel a certain colour. You can also
pass in an object that is a set of RGB values as [r, g, b].
Examples
`javascript
var p = strip.pixel(1); // get second LED
p.color("#0000FF"); // set second pixel blue.
p = strip.pixel(2); // get third LED
p.colour("orange"); // set third pixel red/yellow
p = strip.pixel(3); // get fourth LED
p.color("rgb(0, 255, 0)"); // set fourth LED green
p = strip.pixel(4); // get fifth LED
p.color([255, 0, 255]); // set fifth LED magenta
`
#### color()
Returns an object representing the color of this pixel with the shape below.
.colour() is aliased to this method as well.
Parameters
* none
Shape
`javascript`
{
r: 0, // red component
g: 0, // green component
b: 0, // blue component
hexcode: "#000000", // hexcode of color
color: "black", // keyword name of color if matching
rgb: [0,0,0], // RGB component array
}
Example
Get a pixel, set it's colour and then query it's current state.
`javascript
var p = strip.pixel(1); // get second LED
p.color("#0000FF"); // set second pixel blue.
p.color(); // returns {r:0, g:0, b:255, hexcode:"#0000ff", color:"blue", rgb[0,0,255]}
`
#### off()
Turns the pixel to it's off state.
.clear() is also aliased to this method.
Example
Set a pixel value to off
`javascript
var p = strip.pixel(1); // get second LED
p.off(); // turn it off
p.color(); // returns {r: 0, g: 0, b: 0, hexcode:"#000000", color:"black", rgb: [0,0,0]}
strip.show(); // pixel will be off
`
* Basic single strip using custom firmata
* Basic single strip using Johnny Five Firmata
* Single strip using Johnny Five over I2C Backpack
* Mutiple strips using Johnny Five over firmata
* Multiple strips using Johnny Five over I2C Backpack
* Controlling a panel and using strip.color()`
* Static rainbow with a single strip
* Dynamic rainbow over a single strip
* Dynamic rainbow over multiple strips
* Random pixels flowing down multiple strips
This library is under active development and planned modifications are:
* Provide methods of having different shapes to the strips including 3D
* Prvide method of pixel selection using polar coordinates for circles and hexes