jaxcore-spin

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

Method	Arguments	Description
connect()		connect the Spin device, the Spin device will open a TCP communication channel to the Spin NodeJS server
disconnect()		disconnect the Spin device from the Spin NodeJS server
isConnected()		returns boolean whether the device is connected to the NodeJS Server
flash(color, repeat)	color array RGB color array repeat integer (0-3) number of times to repeat the flash	Flash all LEDs the same color, eg. spin.flash([0,255,0]) will flash green once for 2s spin.flash([255,0,0],2) will flash red twice for 1s each
quickFlash(color)	color array RGB color array	flashes all LEDs for 200ms, eg spin.flash([255,255,0]]
quickFlashSingle(color, index)	color array RGB color array index integer the led to flash (0 to 23)	flash a single LED for 200ms, eg spin.quickFlashSingle([0,0,255],0)
lightsOn(color)	color array RGB color array	turns all LEDs on until they are specifically turned off
lightsOff()		turns all LEDs off
setThrottle(throttle)	throttle integer data rate limit in milliseconds, default is 20ms	eg. spin.setThrottle(100) will restrict TCP communications to every 100ms
setBrightness(brightness)	brightness integer 0 to 255	sets the LED brightness, all configured color patterns will be scaled by this brightness level
setRotateColors(mode, colorLeft, colorRight)	mode integer 0,1,2 colorLeft array RGB color array, colorRight array RGB color array	configure the LED rotation pattern colors
rotate(direction, mode)	direction integer 1 or -1 mode integer 0, 1, 2	shine the LED lights in a rotation pattern (eg. navigation)
setScaleColors(mode, colorLow, colorHigh, colorMid)	mode integer 0,1,2 colorLow array RGB color array for below the scale() percent colorHigh array RGB color array above the scale() percent colorMid array RGB color array for the midpoint	configures the LED rotation pattern colors, eg. spin.setScaleColors(0,[255,0,0], [0,0,255], [255,255,255]) will set mode 0 to be red/blue with a white midpoint
scale(percent, mode)	percent float percentage ratio 0.0 to 1.0 mode integer 0,1,2	shine the LED lights in a linear scale pattern (eg. volume bar)
sleep()		immediately go to low-power sleep mode
delaySleep()		delays sleep mode (same thing as pressing a button or spinning the knob)
setSleepEnabled(enabled)	enabled boolean true for sleep mode, false for never sleep	enables or disabled sleep mode
setSleepTimer(ms)	ms integer number of milliseconds of inactivity	sets amount of inactivity before the device goes into low-power sleep mode

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).

State	Type	Description
brightness	integer	brightness value between 0 and 255
buttonPushed	boolean	true when the button is pushed
buttonPushTime	Date	timestamp of when the button was last pushed
buttonReleaseTime	Date	timestamp of when the button was last released
buttonPushDuration	integer	elapsed time the knob has been pushed in milliseconds
buttonHold	boolean	true when the button has been held down for 2 seconds, configurable with setButtonHoldThreshold()
buttonHoldThreshold	integer	determines how long pushing the button activates the hold events, configurable with setButtonHoldThreshold()
connected	boolean	true when the devices is connected to a Spin NodeJS service
spinPosition	integer	absolute position index
spinDirection	integer	direction (1 or -1) rotated relative to the previous spin event
spinPreviousTime	Date	timestamp of the previous spin event
spinTime	Date	Date of the most recent spin event
knobPushed	boolean	true when the knob is pushed
knobPushTime	Date	timestamp of when the knob was last pushed
knobReleaseTime	Date	timestamp of when the knob was last released
knobPushDuration	integer	elapsed time the knob has been pushed in milliseconds
knobHold	boolean	true when the knob has been held down for 2 seconds, configurable with setKnobHoldThreshold()
knobHoldThreshold	integer	determines how long pushing the knob activates the hold events, configurable with setKnobHoldThreshold()
batteryVoltage	integer	battery voltage, typically between 2.7 and 4.2 Volts, shows as 5 Volts while charging
batteryPercent	integer	battery percentage as a ratio betwen 0.0 (2.7V minimum charge) and 1.0 (4.2V fully charged)
isCharging	boolean	true when the device is plugged into a USB charger
isCharged	boolean	true when the battery is fully charged (charging LED shines green)
sleepEnabled	boolean	true when the sleep mode is enabled, configurable with setSleepEnabled()
sleeping	boolean	true when the device has notified that has gone to sleep
sleepTimer	integer	sleep timer in milliseconds, configurable with setSleepTimer()
inactivityTime	integer	milliseconds since last activity

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

Event	Parameters	Description (emitted when)
connect		the device has connected to the NodeJS spin service
battery	batteryVoltage integer voltage between 2.7 and 4.2 or 5 while charging	battery voltage has changed
disconnect		the device has disconnected from the NodeJS spin service
knob	pushed boolean	knob is pushed or released
knob-hold		knob is held for more than 2 seconds
knob-press		knob is released after having been held for less than 2 seconds
knob-longpress		knob is released after having been held for more than 2 seconds
button	pushed boolean	button is pushed or released
button-hold		button is held for more than 2 seconds
button-press		button is released after having been held for less than 2 seconds
button-longpress		button is released after having been held for more than 2 seconds
charged	charged boolean true when fully charged	battery is fully charged or starts getting drawn down
charging	charging boolean true while plugged in	device has been plugged or unplugged from a USB charging port
settings-changed	changes object	hardware settings such as brightness, knobHoldThreshold, buttonHoldThreshold, sleepEnabled, or sleepTimer havechanged
sleep-warning		the 15 second sleep warning (yellow flashes) has activated
sleeping		device has entered sleep mode
spin	direction integer (1 or -1) direct knob has been rotated position integer absolute position index	the knob has been rotated
update	changes object	any property has been changed

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