Nuanced Pumpkin Mavens

    node-fadecandy

    2.0.5 • Public • Published

    node-fadecandy

    Node library to control and send video frames directly to a FadeCandy device from NodeJS, via USB.

    It does not require the fcserver from FadeCandy, this module communicates directly with the FadeCandy board via USB.

    I suggest to go and check out what FadeCandy can do for your project.

    TL;DR: it's a LED driver control board, having 8 output ports (GND and Signal). Each port can address 64 pixels, so a single FadeCandy board can drive 512 LEDs. To handle more, you'll need more FadeCandy boards, and this issue to be resolved, since in the current state of this lib only supports a single FadeCandy device.

    So 64 leds per port, you have to wire your leds according these ports, but not to worry about addressing them, because the FadeCandy device automatically splits the incoming data according to these ports. For example if you have 64 leds on the first, and 50 on the second one, you can send in a data for 114 pixels, and the FadeCandy will sort it out.

    You have to provide the 5V power source for the neopixels, or, if you're like me, and use a few leds (in my case: 114), you can power the led strips directly from the FadeCandy hackerport's 3.3V output.

    Requirements

    Note: this lib is also usable from the desktop with the FadeCandy controller

    This project is in a realy early state, see demo.js for usage below.

    Installation

    $ npm i node-fadecandy --save
    

    Documentation

    class FadeCandy

    FadeCandy is an instance of EventEmitter

    const FadeCandy = require('node-fadecandy')
    
    const fc = new FadeCandy()
    

    Events

    FadeCandy.events.READY

    The USB device is ready to use, you can set the color LUT or configure the controller

    fc.on(FadeCandy.events.READY, function (fc) {
    
        // the USB device is ready!
        
    })
    
    FadeCandy.events.COLOR_LUT_READY

    Color look-up table is set, ready to accept video frames

    fc.on(FadeCandy.events.COLOR_LUT_READY, function (fc) {
    
        // we have a CLUT, lets blink!
        
    })
    

    Properties

    fc.config

    Instance of FadeCandy.Configuration. Set or get the configuration values using this object. See the FadeCandy.Configuration class for more information.

    fc.clut

    Instance of FadeCandy.ColorLUT. You can send in a custom Color Look-Up Table, or use a default one. Check out the FadeCandy.ColorLUT class for more information.

    fc.usb

    Instance of FadeCandy.USBInterface. Device information and usb events are available through this object.

    Methods

    fc.send(data [, callback])
    • data {UInt8Array} typed array containing RGB values for every pixel
    • callback {Function} optional callback, which is fired on successful data transfer

    Send video frame data. Every controlled pixel need 3 values of color channels: R,G,B. The bytearray in data contains these simply concatenated, like this:

    // | 1st pixel  | 2nd pixel  | 3rd pixel
    [    255, 0, 0,   0, 255, 0,   0, 0, 255  .... ] 
    // first 3 pixels are a full red, a full green, and a full blue
    

    Note: This method works only after a CLUT has been set

    All the following classes are available as static properties on the FaceCandy class, or the instantiated object.


    FadeCandy.Configuration

    Configure the FadeCandy controller through this class.

    Detailed information of the configuration packet can be found here.

    Properties

    FadeCandy.Configuration.schema

    Contains the configuration schema that can be used

    Configuration key Default value
    MODE 0
    LED_STATUS 0
    LED_MODE 0
    DISABLE_KEYFRAME_INTERPOLATION 0
    DISABLE_DITHERING 0

    Methods

    fc.config.set(key, value)
    fc.config.set(obj)
    • key {String}
    • value {Boolean}

    Set a configuration value, or set multiple values. To set multiple values, pass in an object with the keys from the schema and their values.

    // set a single value
    fc.config.set(FadeCandy.Configuration.schema.DISABLE_KEYFRAME_INTERPOLATION, 1)
    
    // set multiple values
    fc.config.set({
        [FadeCandy.Configuration.schema.LED_MODE]: 1,
        [FadeCandy.Configuration.schema.LED_STATUS]: 1
    })
    
    
    fc.config.get([key])
    • key {String}

    Get a configuration value, or get the whole currently set configuration.

    // get the interpolation setting
    let i = fc.config.get(FadeCandy.Configuration.schema.DISABLE_KEYFRAME_INTERPOLATION)
    
    

    FadeCandy.ColorLUT

    FadeCandy.ColorLUT is an instance of EventEmitter. This class sets and/or generates a default Color Look-Up Table. As the original FadeCandy docs describe:

    The look-up table is structured as three arrays of 257 entries, starting with the entire red-channel LUT, then the green-channel LUT, then the blue-channel LUT.

    FadeCandy uses 16-bit color LUT entries, so for a bytearray or UInt8Array, these will be split into high and low bytes. The FadeCandy.ColorLUT accepts these data in one UInt8Array containing (3 channels * 256 entries * 2) bytes.

    Events

    FadeCandy.ColorLUT.events.READY

    Fired when the last color LUT data packet was sent succesfully.

    Methods

    fc.clut.create([data])
    • data {Uint8Array} optional bytearray containing a color LUT

    Set up a new Color LUT from the provided data. Data is optional, if not set, a default CLUT will be generated and used.

    fc.on(FadeCandy.events.READY, function (fc) {
    
        // the USB device is ready!
        
        // set up the CLUT
        fc.clut.create() 
        
    })
    
    fc.clut.generateDefault()

    Returns a Uint8Array, containing the default color look-up table. The code, that generates this default color LUT is based on this simple example in Python for FadeCandy

        // check out the CLUT before even using the FadeCandy lib
    
        let fclut = new FadeCandy.ColorLUT()
    
        let defaultCLUT = fclut.generateDefault() // UInt8Array
    
    

    FadeCandy.USBInterface

    FadeCandy.USBInterface is an instance of EventEmitter. This class does the USB device discovery, opening the device, and claiming the interface.

    This process is supposed to be an underlying mechanism, so you don't have to meddle with USB connections.

    Events

    FadeCandy.USBInterface.READY

    Emitted when the USB device is opened, and the interface is claimed, so basically it's ready to transfer data.

    FadeCandy.USBInterface.DETACHED

    Emitted if the FadeCancy device is detached from the host.

    FadeCandy.USBInterface.TRANSFERERROR

    Emitted, when a packet transfer results in error.

    Properties

    fc.usb.device

    The USB device seen through the node-usb module. For example, you can find the deviceDescriptor and configDescriptor data here if needed.

    fc.usb.endpoint

    The OUT endpoint on which we communicate with the FadeCandy device.

    Methods

    fc.usb.connect()

    Tries to connect to a FadeCandy device by it's vendor and product id.

    fc.usb.send(data [,callback])

    Sends data through the endpoint, handles callback, or emits TRANSFERERROR


    Example

    Load and init lib

    const FadeCandy = require('tessel2-fadecandy')
    
    let fc = new FadeCandy()
    

    Wait while the lib finds and setups the USB interface

    fc.on(FadeCandy.events.READY, function () {
    
        console.log('FadeCandy.events.READY')
    
        // see the config schema
        console.log(fc.Configuration.schema)
    
        // create default color look-up table
        fc.clut.create()
    
        // set fadecandy led to manual mode
        fc.config.set(fc.Configuration.schema.LED_MODE, 1)
    
        // blink that led
        let state = false
        setInterval(() => {
            state = !state;
            fc.config.set(fc.Configuration.schema.LED_STATUS, +state)
        }, 100)
    })
    
    

    video frames are available after a CLUT is set

    fc.on(FadeCandy.events.COLOR_LUT_READY, function () {
        console.log('FaceCandy says color lut ready')
    
        // do some reeeeally basic running light on 6 leds 
        let frame = 0
        setInterval(function () {
    
            let data = new Uint8Array(6 * 3)
    
            for (let pixel = 0; pixel < 6; pixel ++) {
                if (frame % 6 == pixel) {
                    let i = 3 * pixel
    
                    data[i] = 255
                    data[i + 1] = 0
                    data[i + 2] = 255
                }
            }
            fc.send(data)
            frame++
    
        }, 100)
    })
    

    License

    MIT License

    Copyright (c) 2016 Szabolcs Szabolcsi-Toth

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Install

    npm i node-fadecandy

    DownloadsWeekly Downloads

    2

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    24.7 kB

    Total Files

    12

    Last publish

    Collaborators

    • nec