jaxcore-spin v0.0.2

Jaxcore Spin

NodeJS library for Jaxcore Spin, the programmable wifi dial remote control.

Usage

npm install jaxcore-spin

Example Script

var Spin = require('jaxcore-spin');

Spin.connectAll(function (spin) {
	console.log('connected', spin.id);
	
	spin.on('spin', function (direction, position) {
		console.log('spin', direction, position);
	});
	
	spin.on('knob', function (pushed) {
		console.log('knob', pushed);
	});
	
	spin.on('button', function (pushed) {
		console.log('button', pushed);
	});
});

Save as test.js and run:

node test.js

Then turn on your Jaxcore Spin device, configure it for your wifi network, and it will auto-connect to the test script and begin printing the log when the knob is spun, or the button or knob is pushed.

If you do not own a Jaxcore Spin, try the web-based Spin Simulator which will launch a simulation of the device and appear on the network using the same TCP/UDP protocol that the physical devices implement.

Examples

See the /examples directory for test scripts.

Also see:

• Spin-Synth - an html5 audio keyboard controlled by the Spin

• Spin-A-Sketch - an html5 canvas etch-a-sketch game controlled by two Spin devices

Static Methods

• Spin.debug(on) -- turn on verbose debugging

Spin.debug(true);

• Spin.create(device) -- factory method for instantiating Spin instances, use the device object provided by the scan, connectAll, connectOne, connectTo, connectUSB, or connectUSBDevice static methods

• Spin.scan(callback) -- low level scan, receives pings from all Jaxcore Spin devices

Spin.scan(function(device, done, rescan) {
	
	console.log('received ping from '+device.id);

	var spin = Spin.create(device);
	spin.on('spin', function(direction) {
		console.log('spinning', direction);
	});
	spin.connect();
		
});

• Spin.connectAll(callback) -- greedily connect all Jaxcore Spins (wifi and usb), this is a short-hand version of using both scan() and connectUSB()

Spin.connectAll(function(spin) {
	console.log('connected', spin.id);
});

• Spin.connectOne(callback) -- greedily connect only one Jaxcore Spin then stop scanning, after the device is disconnected or turned off this method will automatically connect next available Jaxcore Spin

Spin.connectOne(function(spin) {
	console.log('connected', spin.id);
});

• Spin.connectTo(id, callback) - connect to a specific Jaxcore Spin by its unique ID

Spin.connectTo('D3F5A3DS80', function(spin) {
	console.log('connected', spin.id);
});

• Spin.connectUSB(callback) -- connect any Spin devices connected by USB cable

Spin.connectUSB(function(spin) {
	console.log('connected by USB', spin.id, spin.usbDevice);
});

• Spin.connectUSB(id, callback) -- connect a specific Spin device by USB

Spin.connectUSB('D3F5A3DS80', function(spin) {
	console.log('connected by USB', spin.id, spin.usbDevice);
});

• Spin.connectUSBDevice(devicePath, callback) -- connect any Spin to a specific USB device path

Spin.connectUSBDevice('/dev/DFN199', function(spin) {
	console.log('connected by USB', spin.id, spin.usbDevice);
});

Spin Instance Methods

Instance Method Examples

var Spin = require('jaxcore-spin');

Spin.connectAll(function(spin) {

	spin.setScaleColors(0,[255,0,0], [0,0,255], [255,255,255])

	// flash green when connected
	spin.on('connect', function() {
		spin.flash([0,255,0]);
	});
	
	// rotate the LEDs color depending on button/knob pushes
	spin.on('spin', function(direction) {
		if (spin.knobPushed) spin.rotate(direction, 1);
		if (spin.buttonPushed) spin.rotate(direction, 2);
		else spin.rotate(direction, 0);
	});
  	
  	// shine blue when the button is pushed
	spin.on('button', function(pushed) {
		if (pushed) {
			spin.lightsOn([0,0,255]);
		}
		else {
			spin.lightsOff();
		}
	});
	
});

Properties

All public properties are exposed in a ReactJS-style .state child property and can be read at any time or watched for in the events (below).

Properties Examples

var Spin = require('jaxcore-spin');

Spin.connectAll(function(spin) {

	spin.on('connected', function() {
		console.log('spin battery at '+ (Math.round(spin.state.batteryPercent*100*10)/10) + '%');
	});
	
	spin.on('spin', function(direction) {
		console.log('spin position=' + spin.state.spinPosition);
	});
  	
  	spin.on('button', function(pushed) {
		if (!pushed) { // if released
			console.log('button held for ' + spin.state.buttonPushDuration + ' ms');
		}
	});
	
});

Events

Spin Buffer

Jaxcore Spin's resolution of 32 pulses per revolution is often too precise for many things you may want to do with the device, particularly when navigating menus. To reduce the resolution (ie. to slow the device down) the Spin Buffer can be used to absorb some of the spin events.

The Spin Buffer uses a combination of 3 types of buffer strategies (static, kinetic, and momentum) and a delay mechanism giving many ways to improve usability.

Spin Buffer API:

Create a spin buffer:

• new Spin.Buffer( spin, bufferConfig )

spin: an instance of Spin() supplied by Spin.scan or Spin.connect() bufferConfig: sets alternative configuration options:

var bufferConfig = {
    staticTimeout: 2000,    // how many seconds of inactivity re-activates static buffer (default 3s)
    defaultDelay: 1000     // sets the default .delay() length of time in ms
};

Spin Buffer Methods

• buffer.spin( direction, kineticBufferSize, staticBufferSize )

Updates the buffer and returns true if either the static or kinetic buffer has has been overflowed.

• direction: is the direction parameter supplied from a spin event
• kineticBufferSize: how many spin events to skip until the kinetic buffer is overflowed
• staticBufferSize: how many spin events to skip before the static buffer is overflowed

The kinetic buffer is active while the Spin's knob is rotating in one direction. When the knob is idle for more than 2 seconds or it's direction of rotation is changed, the static buffer becomes active.

Example:

spin.on('spin', function (direction) {
    if (buffer.spin( direction, 4, 3 )) {
        /* your spin even handler code goes here */
    }
});

• buffer.delay( delayTime )

  delayTimeamount of time in milliseconds to ignore spin events (optional, default is 500ms)

• buffer.reset()

Resets the static buffer. This is the same as leaving the knob inactive for more than 3 seconds.

Spin Buffer Example:

var Spin = require('jaxcore-spin');
Spin.connectAll(function (spin) {
	
	var buffer = new Spin.Buffer(spin);
	
    spin.on('button', function(pushed) {
    	if (pushed) {
    		// reset static buffer when the button is pushed
    		buffer.reset();
    	}
    	else {
    	    // ignore all spin events for 2 seconds after releasing the button
    	    buffer.delay(2000);
    	}
    });
	
	spin.on('spin', function (direction) {
		if (buffer.spin(direction, 1, 3)) {
			// kinetic buffer of 1 will skip every other spin event
			// static buffer of 3 will skip 3 spin events when changing directions or idle for 2s
		    
		    console.log('spin', direction);
		}
		else {
			console.log('buffering...');
		}
	});
});

Momentum Timeout

TODO