Update library to use JS Promises instead of callbacks

README.md

@@ -21,13 +21,15 @@ See [node-hid's compiling from source instructions](https://github.com/node-hid/
 ## Usage
 
 ```javascript
-var Blink1 = require('node-blink1');
+const Blink1 = require('node-blink1');
 ```
 
 Get list of blink(1) devices connected:
 
+* Returns an array of serial numbers
+
 ```javascript
-Blink1.devices(); // returns array of serial numbers
+Blink1.devices();
 ```
 
 Create blink(1) object without serial number, uses first device:
@@ -39,95 +41,244 @@ var blink1 = new Blink1();
 Create blink(1) object with serial number, to get list of serial numbers use
 `Blink1.devices()`:
 
+* Accepts an optional Serial Number parameter
+
 ```javascript
 var blink1 = new Blink1(serialNumber);
 ```
 
+### rgbcolor package usage
+
+This blink1 package natively supports the [rgbcolor package](https://www.npmjs.com/package/rgbcolor). It is not required if you just pass an object containing RGB properties. At any point you see `new Color()` in the example code below, you can replace it with an RGB color object as shown:
+
+```javascript
+// An example color object for the color red
+var red = {
+    r: 255,
+    g: 0,
+    b: 0
+};
+
+// An few example rgbcolor objects for the color red
+const Color = require('rgbcolor');
+var red = new Color('red');
+var red = new Color('rgb(255,0,0)');
+var red = new Color('#FF0000');
+var red = new Color('#F00');
+```
+
 ### Get version
 
+* Accepts an optional callback function parameter
+* Returns Promise; automatically calls optional callback
+
 ```javascript
-blink1.version(callback(version));
+blink1.version([callback]).then*(version => {
+    console.log("Version:", version);
+});
 ```
 
 ### Set colors
 
-Fade to RGB, optional callback called after `fadeMillis` ms:
+Fade to RGB, returns Promise after `delay` ms:
+
+* Accepts an object containing:
+    - Required RGBColor object
+    - Optional delay in ms
+    - Optional index 0 - 2 (only Mk2 supported)
+    - Optional callback function
+* Returns Promise; automatically calls optional callback
 
 ```javascript
-blink1.fadeToRGB(fadeMillis, r, g, b, [callback]); // r, g, b: 0 - 255
+const Color = require('rgbcolor');
+let blinkObject = {
+    color : new Color('orange'),
+    delay : 1000,
+    index : 0,
+    callback : () => {}
+};
+blink1.fadeToRGB(blinkObject);
+```
+
+#### Extended Fade example
+
+Because most functions return promises, you can now chain actions together.
+
+This example will cause the device to fade to red over 2.5s, once complete, the device will then fade to green over another 2.5s.
 
-blink1.fadeToRGB(fadeMillis, r, g, b, [index, callback]); // r, g, b: 0 - 255
-                                                          // index (mk2 only): 0 - 2
+```javascript
+const Color = require('rgbcolor');
+let blinkObject = {
+    delay : 2500,
+    color : new Color('red')
+};
+blink1.fadeToRGB(blinkObject).then(({red, green, blue}) => {
+    let blinkObject = {
+        delay : 2500,
+        color : new Color('green')
+    };
+    blink1.fadeToRGB(blinkObject);
+});
 ```
 
-Set RGB:
+Set RGB, returns Promise:
+
+* Accepts a required RGBColor object
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
 
 ```javascript
-blink1.setRGB(r, g, b, [callback]); // r, g, b: 0 - 255
+const Color = require('rgbcolor');
+blink1.setRGB(new Color('red')[, callback]);
 ```
 
-Get RGB (mk2 only):
+Get current RGB (mk2 only):
+
+* Accepts an optional index (default is 0)
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
 
 ```javascript
-blink1.rgb([index,] callback(r, g, b));
+blink1.getRGB([index][, callback]);
 ```
 
+### Turn device off
+
 Off:
 
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
 blink1.off([callback]);
 ```
 
 ### Other methods
 
-Set server down (enable, disable), optional callback called after `millis` ms:
+#### enableServerDown() & disableServerDown()
+
+Set server down (enable, disable) after `delay` ms:
+
+* Accepts required delay in ms
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
 
 ```javascript
-blink1.enableServerDown(millis, [callback]); // tickle
+blink1.enableServerDown(delay[, callback]); // tickle
 
-blink1.disableServerDown(millis, [callback]); // off
+blink1.disableServerDown(delay[, callback]); // off
 ```
 
+#### play()
+
 Play (start playing the pattern lines at the specified position):
 
+* Accepts required play position
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
-blink1.play(position, [callback]);
+blink1.play(position[, callback]);
 ```
 
+#### playLoop()
+
 Play Loop (start playing a subset of the pattern lines at specified start and end positions. Specifying count = 0 will loop pattern forever):
 
+* Accepts an object containing:
+    - Required start position
+    - Required end position
+    - Required count
+    - Optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
-blink1.playLoop(startPosition, endPosition, count, [callback]);
+let blinkObject = {
+    start    : 1,
+    end      : 2,
+    count    : 2,
+    callback : () => {}
+};
+blink1.playLoop(blinkObject);
 ```
 
+#### pause()
+
 Pause (stop playing the pattern line):
 
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
 blink1.pause([callback]);
 ```
 
+#### writePatternLine()
+
 Write pattern line (set the parameters for a pattern line, at the specified position):
 
+* Accepts an object containing:
+    - Required RGBColor object
+    - Required delay in ms
+    - Required position
+    - Optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
-blink1.writePatternLine(fadeMillis, r, g, b, position, [callback]) // r, g, b: 0 - 255
+const Color = require('rgbcolor');
+let blinkObject = {
+    color    : new Color('red'),
+    delay    : 100,
+    position : 2,
+    callback : () => {}
+};
+blink1.writePatternLine(blinkObject);
 ````
 
 A simple example of this, used to flash red on & off is:
 
 ```javascript
-blink1.writePatternLine(200, 255, 0, 0, 0);
-blink1.writePatternLine(200, 0, 0, 0, 1);
+const Color = require('rgbcolor');
+let blinkObject = {
+    delay    : 200,
+    color    : new Color('red')
+    position : 0
+};
+let blinkObject2 = {
+    delay    : 200,
+    color    : new Color('black')
+    position : 1
+};
+blink1.writePatternLine(blinkObject);
+blink1.writePatternLine(blinkObject2);
 blink1.play(0);
 ```
 
+#### readPatternLine()
+
 Read pattern line (at the position):
 
+* Accepts a required position
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
+
 ```javascript
-blink1.readPatternLine(position, [callback])
+blink1.readPatternLine(position[, callback]).then(({
+    color,
+    delay
+}) => {
+    // readPatternLine values
+});
 ```
 
+#### close()
+
 Close (the underlying HID device):
 
+* Accepts an optional callback function
+* Returns Promise; automatically calls optional callback
+
+
 ```javascript
 blink1.close([callback]);
 ```

base.js

@@ -0,0 +1,76 @@
+const HID   = require('node-hid');
+const _     = require('lodash');
+
+/**********
+ * CONFIG *
+ **********/
+
+const VENDOR_ID = 0x27B8;
+const PRODUCT_ID = 0x01ED;
+
+const REPORT_ID     = 1;
+const REPORT_LENGTH = 9;
+
+class Blink1_Base {
+    constructor(serialNumber) {
+        let blink1HIDdevices = Blink1_Base._blink1HIDdevices();
+
+        if (blink1HIDdevices.length === 0) {
+            throw new Error('No blink(1)\'s could be found');
+        }
+
+        var blink1HIDdevicePath = null;
+
+        if (serialNumber === undefined) {
+            serialNumber = blink1HIDdevices[0].serialNumber;
+        }
+
+        _.find(blink1HIDdevices, (blink1HIDdevice) => {
+            if (serialNumber === blink1HIDdevice.serialNumber) {
+                blink1HIDdevicePath = blink1HIDdevice.path;
+            }
+
+            return (blink1HIDdevicePath !== null);
+        });
+
+        if (blink1HIDdevicePath === null) {
+            throw new Error('No blink(1)\'s with serial number ' + serialNumber + ' could be found');
+        }
+
+        this.serialNumber = serialNumber;
+        this.hidDevice = new HID.HID(blink1HIDdevicePath);
+    }
+
+    static _blink1HIDdevices() {
+        return HID.devices(VENDOR_ID, PRODUCT_ID);
+    };
+
+    static devices() {
+        return _.map(Blink1_Base._blink1HIDdevices(), ({ serialNumber }) => serialNumber);
+    };
+
+    // Hardware API
+
+    _sendCommand(/* command [, args ...]*/) {
+        var featureReport = [REPORT_ID, 0, 0, 0, 0, 0, 0, 0, 0];
+
+        _.forEach(arguments, (argument, k) => {
+            if (k === 0) {
+                featureReport[1] = argument.charCodeAt(0);
+                return;
+            }
+
+            featureReport[k + 1] = argument;
+        });
+
+        this.hidDevice.sendFeatureReport(featureReport);
+    }
+
+    _readResponse() {
+        return new Promise((resolve, reject) => {
+            resolve(this.hidDevice.getFeatureReport(REPORT_ID, REPORT_LENGTH));
+        });
+    }
+}
+
+module.exports = Blink1_Base;