Merge pull request #70 from orbotix/feature/promises-dual-interface

README.markdown

@@ -55,11 +55,32 @@ orb.connect(function() {
 
     setTimeout(function() {
       orb.color("green");
-    }, 1000);
+    }, 100);
   });
 });
 ```
 
+You can also use a Promises/A+ interface for your code, instead of the callback-based API:
+
+```javascript
+orb.connect().then(function() {
+  return orb.roll(155, 0);
+}).then(function() {
+  return orb.color("green");
+}).then(orb.detectCollisions);
+
+orb.on("collision", function(data) {
+  console.log("collision detected");
+  console.log("  data:", data);
+
+  orb.color("red")
+    .delay(100)
+    .then(function() {
+      return orb.color("green");
+    });
+});
+```
+
 For more examples, check out the `examples` dir, or the JavaScript SDK documentation on the Sphero developer portal. When running these examples, don't forget to pass the port as an ENV variable like this:
 ```
 PORT=/your/port node example.js

examples/promise-bluetooth-info.js

@@ -0,0 +1,18 @@
+"use strict";
+
+var sphero = require("../");
+var orb = sphero(process.env.PORT);
+
+orb.connect().then(function() {
+  return orb.color("FF00FF");
+}).then(function() {
+  return orb.getBluetoothInfo();
+}).then(function(data) {
+  console.log("bluetoothInfo:");
+  console.log("  name:", data.name);
+  console.log("  btAddress:", data.btAddress);
+  console.log("  separator:", data.separator);
+  console.log("  colors:", data.colors);
+}).catch(function(err) {
+  console.error("err:", err);
+});

examples/promise-collision-detection.js

@@ -0,0 +1,19 @@
+"use strict";
+
+var sphero = require("../");
+var orb = sphero(process.env.PORT);
+
+orb.connect().then(orb.detectCollisions).then(function() {
+  return orb.color("green");
+}).then(function() {
+  return orb.roll(155, 0);
+});
+
+orb.on("collision", function(data) {
+  console.log("collision detected");
+  console.log("  data:", data);
+
+  orb.color("red").delay(100).then(function() {
+    return orb.color("green");
+  });
+});

examples/promise-color.js

@@ -0,0 +1,20 @@
+"use strict";
+
+var sphero = require("../");
+var orb = sphero(process.env.PORT);
+
+orb.connect().then(function() {
+  return orb.color({ red: 255, green: 0, blue: 255 });
+}).delay(1000).then(function() {
+  console.log("color 1");
+  // sets color to the provided hex value
+  return orb.color(0xff0000);
+}).delay(1000).then(function() {
+  console.log("color 2");
+  // hex numbers can also be passed in strings
+  return orb.color("00ff00");
+}).delay(1000).then(function() {
+  console.log("color 3");
+  // sets color to the provided color name
+  return orb.color("magenta");
+});

examples/promise-roll.js

@@ -0,0 +1,12 @@
+"use strict";
+
+var sphero = require("../");
+var orb = sphero(process.env.PORT);
+
+orb.connect().then(function() {
+  // roll orb in a random direction, changing direction every second
+  setInterval(function() {
+    var direction = Math.floor(Math.random() * 360);
+    orb.roll(150, direction);
+  }, 1000);
+});

lib/devices/core.js

@@ -15,10 +15,10 @@ module.exports = function core(device) {
    * orb.ping(function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.ping = function(callback) {
-    command(commands.ping, null, callback);
+    return command(commands.ping, null, callback);
   };
 
   /**
@@ -44,10 +44,10 @@ module.exports = function core(device) {
    *     console.log("  apiMin:", data.apiMin);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.version = function(callback) {
-    command(commands.version, null, callback);
+    return command(commands.version, null, callback);
   };
 
   /**
@@ -59,10 +59,10 @@ module.exports = function core(device) {
    * orb.controlUartTx(function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.controlUartTx = function(callback) {
-    command(commands.controlUARTTx, null, callback);
+    return command(commands.controlUARTTx, null, callback);
   };
 
   /**
@@ -80,7 +80,7 @@ module.exports = function core(device) {
    * orb.setDeviceName("rollingOrb", function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.setDeviceName = function(name, callback) {
     var data = [];
@@ -89,7 +89,7 @@ module.exports = function core(device) {
       data[i] = name.charCodeAt(i);
     }
 
-    command(commands.setDeviceName, data, callback);
+    return command(commands.setDeviceName, data, callback);
   };
 
   /**
@@ -112,10 +112,10 @@ module.exports = function core(device) {
    *     console.log("  colors:", data.colors);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.getBluetoothInfo = function(callback) {
-    command(commands.getBtInfo, null, callback);
+    return command(commands.getBtInfo, null, callback);
   };
 
   /**
@@ -130,10 +130,10 @@ module.exports = function core(device) {
    * orb.setAutoReconnect(1, 20, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.setAutoReconnect = function(flag, time, callback) {
-    command(commands.setAutoReconnect, [flag, time], callback);
+    return command(commands.setAutoReconnect, [flag, time], callback);
   };
 
   /**
@@ -151,10 +151,10 @@ module.exports = function core(device) {
    *     console.log("  time:", data.time);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.getAutoReconnect = function(callback) {
-    command(commands.getAutoReconnect, null, callback);
+    return command(commands.getAutoReconnect, null, callback);
   };
 
   /**
@@ -189,10 +189,10 @@ module.exports = function core(device) {
    *     console.log("  secondsSinceCharge:", data.secondsSinceCharge);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.getPowerState = function(callback) {
-    command(commands.getPwrState, null, callback);
+    return command(commands.getPwrState, null, callback);
   };
 
   /**
@@ -208,10 +208,10 @@ module.exports = function core(device) {
    * orb.setPowerNotification(1, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.setPowerNotification = function(flag, callback) {
-    command(commands.setPwrNotify, [flag], callback);
+    return command(commands.setPwrNotify, [flag], callback);
   };
 
   /**
@@ -229,15 +229,15 @@ module.exports = function core(device) {
    * orb.sleep(10, 0, 0, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.sleep = function(wakeup, macro, orbBasic, callback) {
     wakeup = utils.intToHexArray(wakeup, 2);
     orbBasic = utils.intToHexArray(orbBasic, 2);
 
     var data = [].concat(wakeup, macro, orbBasic);
 
-    command(commands.sleep, data, callback);
+    return command(commands.sleep, data, callback);
   };
 
   /**
@@ -258,10 +258,10 @@ module.exports = function core(device) {
    *     console.log("  vCrit:", data.vCrit);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.getVoltageTripPoints = function(callback) {
-    command(commands.getPowerTrips, null, callback);
+    return command(commands.getPowerTrips, null, callback);
   };
 
   /**
@@ -286,15 +286,15 @@ module.exports = function core(device) {
    * orb.setVoltageTripPoints(675, 650, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.setVoltageTripPoints = function(vLow, vCrit, callback) {
     vLow = utils.intToHexArray(vLow, 2);
     vCrit = utils.intToHexArray(vCrit, 2);
 
     var data = [].concat(vLow, vCrit);
 
-    command(commands.setPowerTrips, data, callback);
+    return command(commands.setPowerTrips, data, callback);
   };
 
   /**
@@ -310,11 +310,11 @@ module.exports = function core(device) {
    * orb.setInactivityTimeout(120, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.setInactivityTimeout = function(time, callback) {
     var data = utils.intToHexArray(time, 2);
-    command(commands.setInactiveTimer, data, callback);
+    return command(commands.setInactiveTimer, data, callback);
   };
 
   /**
@@ -329,10 +329,10 @@ module.exports = function core(device) {
    * orb.jumpToBootLoader(function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.jumpToBootloader = function(callback) {
-    command(commands.goToBl, null, callback);
+    return command(commands.goToBl, null, callback);
   };
 
   /**
@@ -349,10 +349,10 @@ module.exports = function core(device) {
    * orb.runL1Diags(function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.runL1Diags = function(callback) {
-    command(commands.runL1Diags, null, callback);
+    return command(commands.runL1Diags, null, callback);
   };
 
   /**
@@ -390,10 +390,10 @@ module.exports = function core(device) {
    *     console.log("  gyroAdjustCount:", data.gyroAdjustCount);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.runL2Diags = function(callback) {
-    command(commands.runL2Diags, null, callback);
+    return command(commands.runL2Diags, null, callback);
   };
 
   /**
@@ -408,15 +408,15 @@ module.exports = function core(device) {
    * orb.clearCounters(function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.clearCounters = function(callback) {
-    command(commands.clearCounters, null, callback);
+    return command(commands.clearCounters, null, callback);
   };
 
   device._coreTimeCmd = function(cmd, time, callback) {
     var data = utils.intToHexArray(time, 4);
-    command(cmd, data, callback);
+    return command(cmd, data, callback);
   };
 
   /**
@@ -429,10 +429,10 @@ module.exports = function core(device) {
    * orb.assignTime(0x00ffff00, function(err, data) {
    *   console.log(err || "data: " + data);
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.assignTime = function(time, callback) {
-    device._coreTimeCmd(commands.assignTime, time, callback);
+    return device._coreTimeCmd(commands.assignTime, time, callback);
   };
 
   /**
@@ -454,9 +454,9 @@ module.exports = function core(device) {
    *     console.log("  t3:", data.t3);
    *   }
    * }
-   * @return {void}
+   * @return {object} promise for command
    */
   device.pollPacketTimes = function(time, callback) {
-    device._coreTimeCmd(commands.pollTimes, time, callback);
+    return device._coreTimeCmd(commands.pollTimes, time, callback);
   };
 };