Fixed linter and small refactor

.travis.yml

@@ -1,14 +1,33 @@
 language: node_js
-sudo: false
 node_js:
   - '0.10'
   - '0.12'
-  - 'iojs'
+  - '4.0'
+  - '4.1'
+  - '4.2'
+  - '5.0'
+  - '5.1'
+env:
+  - CXX=g++-4.8
 before_install:
+  - sudo apt-get update
   - "mkdir -p ~/.npm"
-before_script:
+install:
+  - npm install -g node-gyp-install
+  - node-gyp-install
+  - npm install serialport
+  - npm install noble
+  - npm install
   - npm install -g grunt-cli istanbul codeclimate-test-reporter
 script:
   - grunt lint
   - istanbul cover ./node_modules/.bin/_mocha spec/helper.js spec/lib/*.js spec/lib/**/*.js --report lcovonly -- -R spec
-  - CODECLIMATE_REPO_TOKEN=88ec807c5d22e853e1a21b9289233f525e793f09e5e81322899ee519587d3689 codeclimate < coverage/lcov.info
+  - CODECLIMATE_REPO_TOKEN=88ec807c5d22e853e1a21b9289233f525e793f09e5e81322899ee519587d3689 codeclimate-test-reporter < coverage/lcov.info
+addons:
+  apt:
+    sources:
+    - ubuntu-toolchain-r-test
+    packages:
+    - g++-4.8
+    - g++-4.8-multilib
+    - libbluetooth-dev

README.markdown

@@ -1,44 +1,174 @@
-# sphero.js
+# Sphero.js
 
-The official Orbotix JavaScript SDK module to programatically control Sphero robots.
+The official Orbotix JavaScript SDK module to programmatically control Sphero robots.
 
 [![Build Status](https://travis-ci.org/orbotix/sphero.js.svg?branch=master)](https://travis-ci.org/orbotix/sphero.js) [![Code Climate](https://codeclimate.com/github/orbotix/sphero.js/badges/gpa.svg)](https://codeclimate.com/github/orbotix/sphero.js) [![Test Coverage](https://codeclimate.com/github/orbotix/sphero.js/badges/coverage.svg)](https://codeclimate.com/github/orbotix/sphero.js/coverage)
 
-## Installation
+## Usage
+
+To initialize and connect to a BB-8 or an Ollie:
+
+```javascript
+var sphero = require("sphero"),
+    bb8 = sphero("F3:F2:6D:55:71:09"); // change BLE address accordingly
+
+bb8.connect(function() {
+  // roll BB-8 in a random direction, changing direction every second
+  setInterval(function() {
+    var direction = Math.floor(Math.random() * 360);
+    bb8.roll(150, direction);
+  }, 1000);
+});
+```
+
+To initialize and connect to a Sphero 1.0/2.0 or SPRK, just change the **port** to match your connection:
+
+```javascript
+var sphero = require("sphero"),
+    orb = sphero("/dev/rfcomm0"); // change port accordingly
+
+orb.connect(function() {
+  // Sphero's connected!
+  // do some cool stuff here!
+});
+```
+
+Once connected, you can give your Sphero commands and receive notifications from the built-in sensors:
+
+```javascript
+orb.connect(function() {
+  // roll Sphero forward
+  orb.roll(150, 0);
+
+  // turn Sphero green
+  orb.color("green");
+
+  // have Sphero tell you when it detect collisions
+  orb.detectCollisions();
+
+  // when Sphero detects a collision, turn red for a second, then back to green
+  orb.on("collision", function(data) {
+    console.log("collision detected");
+    console.log("  data:", data);
+
+    orb.color("red");
+
+    setTimeout(function() {
+      orb.color("green");
+    }, 1000);
+  });
+});
+```
+
+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
+```
+
+## Installation for BB-8 & Ollie
+
+The BB-8 and Ollie use a Bluetooth Low Energy (LE) interface, also known as "Bluetooth Smart" or "Bluetooth 4.0/4.1". You must have a hardware adapter that supports the Bluetooth 4.x+ standard to connect your computer to your BB-8 or Ollie.
+
+Run the following command:
+
+    $ npm install sphero noble
+
+To use Sphero.js with your BB-8 or Ollie, you must also install the Node.js noble module (https://github.com/sandeepmistry/noble) from [@sandeepmistry](https://github.com/sandeepmistry).
+
+## Installation for Sphero 1.0/2.0 & SPRK
+
+The Sphero 1.0/2.0 and the SPRK use a Bluetooth Classic interface, also known as "Bluetooth 2.0/3.0".
+
+Run the following command:
 
-    $ npm install sphero
+    $ npm install sphero serialport
 
-## Connecting to Sphero
+To use Sphero.js with your Sphero or SPRK, you must also install the Node.js serialport module (https://github.com/voodootikigod/node-serialport) from [@voodootikigod](https://github.com/voodootikigod).
+
+## Connecting to BB-8/Ollie
 
 ### OS X
 
-To connect to your Sphero, you first need to pair it. To pair your device on OS X, open the Bluetooth settings here: System Preferences > Bluetooth. From this menu, locate your Sphero in the Devices list and click the **Pair** button to pair it with your computer.
+To connect to your BB-8 or Ollie, you first need to determine UUID. Once you have Noble installed, you can use the `advertisement-discovery.js` program to determine the device UUID:
+
+```
+$ node ./node_modules/noble/examples/advertisement-discovery.js
+peripheral discovered (944f561f8cf441f3b5405ed48f5c63cf with address <unknown, unknown>, connectable true, RSSI -73:
+    hello my local name is:
+        BB-131D
+    can I interest you in any of the following advertised services:
+        []
+    here is my manufacturer data:
+        "3330"
+    my TX power level is:
+        -18
+```
+
+In the above output, the device UUID is `944f561f8cf441f3b5405ed48f5c63cf`. Use this value to connect to your BB-8 or Ollie.
+
+### Linux - Ubuntu
 
-Once you've successfully paired your Sphero, open your terminal and navigate to your system's `/dev/` directory and locate the serial device connection for your newly paired Sphero; it should look something like this:
+To connect to your BB-8 or Ollie, you first need to determine the MAC address. Once you have Noble installed, you can use the `advertisement-discovery.js` program to determine the device address:
 
 ```
-tty.Sphero-RGB-AMP-SPP
+$ node ./node_modules/noble/examples/advertisement-discovery.js
+peripheral discovered (f3f26d557108 with address <f3:f2:6d:55:71:08, random>, connectable true, RSSI -37:
+    hello my local name is:
+            BB-7108
+    can I interest you in any of the following advertised services:
+            ["22bb746f2ba075542d6f726568705327"]
+    here is my manufacturer data:
+            "3330"
+    my TX power level is:
+            6
 ```
 
-Note, your device will likely be different depending on its preset color code (the three colors your Sphero cycles through when you first turn it on). The example above is for a Sphero with a Red, Green, and Blue (RGB) color code.
+In the above output, the device address is `f3f26d557108` (or alternately `f3:f2:6d:55:71:08`). Use this value to connect to your BB-8 or Ollie.
+
+### Windows
+
+To connect to your BB-8 or Ollie, you will need to be running Windows 8.1+. Instructions coming soon...
+
+## Connecting to Sphero/SPRK
+
+### OS X
+
+To connect to your Sphero 1.0/2.0 or SPRK, you first need to pair it. To pair your device on OS X, open the Bluetooth settings in **System Preferences** > **Bluetooth**. From this menu, locate your Sphero in the Devices list and click the **Pair** button to pair it with your computer.
+
+Once you've successfully paired your Sphero, open your terminal, go to your `/dev` folder and locate the serial device connection (or use `ls -a /dev | grep tty.Sphero`) for your newly paired Sphero; it should look something like `tty.Sphero-RGB-AMP-SPP`. Note, your device will likely be different depending on its preset color code (the three colors your Sphero cycles through when you first turn it on). The previous example is for a Sphero with a Red, Green and Blue (RGB) color code.
+
+So, your Sphero port will be at
+
+```
+/dev/tty.Sphero-XXX-XXX-XXX
+```
 
 ***
 
 ### Linux - Ubuntu
 
-To make things easy install `Blueman Bluetooth Manager`. In Ubuntu this is pretty easy, just open the **Ubuntu Software Center**, type the program name and install it from there. When the installation is complete, open the program and search for devices. Make sure the Sphero is flashing its color code. Once the Sphero appears in the list of devices, select it, click on setup and follow the instructions.
+To connect to your Sphero 1.0/2.0 or SPRK, you first need to pair it. To make things easy install `Blueman Bluetooth Manager`. In Ubuntu this is pretty easy, just open the **Ubuntu Software Center**, type the program name and install it from there. When the installation is complete, open the program and search for devices. Make sure the Sphero is flashing its color code. Once the Sphero appears in the list of devices, select it, click on setup and follow the instructions.
 
 You can connect and disconnect the Sphero from a serialport interface by right clicking on it inside the Blueman list of devices and selecting `RN-SPP` or `disconnect`, respectively (after it has been setup and added permanently to the list). Make sure to notice the serialport address Blueman displays after the Sphero connects, as this will be the one used in your code. The serialport address displayed for the Sphero should look something like this:
 
 ```
 /dev/rfcomm0
 ```
 
+You might need to add a udev rule in order to properly set permissions for your program to be able to access the Bluetooth interface. For example:
+
+```
+$ cat /etc/udev/rules.d/55-rfcomm.rules
+KERNEL=="rfcomm[0-9]*", NAME="%k", GROUP="dialout"
+```
+
+The udev rule above will allow any user who is a member of the `dialout` group to access any port that is added by connecting by running the `rfcomm` command. Note that running the `rfcomm` command itself to create the port, may require running under `sudo`.
+
 ***
 
 ### Windows
 
-Locate the Bluetooth icon in the taskbar (or inside the system task tray button) and follow the necessary steps to pair with your Sphero.
+To connect to your Sphero 1.0/2.0 or SPRK, you first need to pair it. Locate the Bluetooth icon in the taskbar (or inside the system task tray button) and follow the necessary steps to pair with your Sphero.
 
 Once you've successfully paired your Sphero, there are two options available to you to check and see which serialport corresponds to the Sphero you just connected. The first option is to right click on the bluetooth icon in the task bar (same you use to pair), click on `Open Settings`, when the settings window appears, navigate to the `COM Ports` tab where you should see a list of ports which should list your Sphero. If your Sphero is listed in more than one port, take note of the one that has `RN-SPP` in the name, and use that one to connect. The list should look something similar to:
 
@@ -55,59 +185,38 @@ The second option is to identify the port number. Click the `start` button and t
 ```
 COM2, COM3, COM4
 ```
+## Error handling
 
-## Usage
-
-To initialize and connect to a Sphero:
+Under most circumstances, Sphero.js will attempt to gracefully recover from any bad or incomplete packets that might be received back from the connected wireless device. If you wish to handle these errors yourself, you must set the `emitPacketErrors` option to true, as shown by this example:
 
-```javascript
+```
 var sphero = require("sphero"),
-    orb = sphero("/dev/rfcomm0");
+    orb = sphero("/dev/rfcomm0", {emitPacketErrors: true});
 
 orb.connect(function() {
   // Sphero's connected!
   // do some cool stuff here!
+  orb.on("error", function(err, data) {
+    // Do something with the err or just ignore.
+  });
 });
 ```
 
-Once connected, you can give Sphero commands:
-
-```javascript
-orb.connect(function() {
-  // roll Sphero forward
-  orb.roll(150, 0);
-
-  // turn Sphero green
-  orb.color("green");
-
-  // have Sphero tell you when it detect collisions
-  orb.detectCollisions();
-
-  // when Sphero detects a collision, turn red for a second, then back to green
-  orb.on("collision", function(data) {
-    console.log("collision detected");
-    console.log("  data:", data);
-
-    orb.color("red");
+## Compatibility
 
-    setTimeout(function() {
-      orb.color("green");
-    }, 1000);
-  });
-});
-```
+The Sphero.js module is currently compatible with Node.js versions 0.10.x thru 5.x
 
-For more examples, check out the `examples` dir, or the JavaScript SDK documentation on the Sphero developer portal.
+In order to install it with Node.js 5.x+, you will need to have g++ v4.8 or higher.
 
 ## Development
 
-Use `npm install` to install development dependencies.
+Use `npm install` to install development dependencies. You will also need to install [Grunt](http://gruntjs.com) by running `npm install -g grunt-cli`
 
-You can run tests with `grunt test`.
+You can then run tests with `grunt test`.
 
-Using `grunt lint` to run ESLint against both `lib` and `spec/lib`.
+Use `grunt lint` to run ESLint against both `lib` and `spec/lib`.
 
-The `grunt` command will run both of the above tasks.
+The `grunt` command by itself will run both of the above tasks.
 
 ## License
 

examples/bluetooth-info.js

@@ -1,14 +1,19 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   orb.color("FF00FF");
 
   orb.getBluetoothInfo(function(err, data) {
-    console.log("bluetooth info fetched");
     if (err) { console.error("err:", err); }
-    console.log("data:", data);
+    else {
+      console.log("bluetoothInfo:");
+      console.log("  name:", data.name);
+      console.log("  btAddress:", data.btAddress);
+      console.log("  separator:", data.separator);
+      console.log("  colors:", data.colors);
+    }
   });
 });

examples/calibration.js

@@ -1,7 +1,7 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   console.log("::START CALIBRATION::");

examples/collision-detection.js

@@ -1,7 +1,7 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   orb.detectCollisions();

examples/color.js

@@ -1,7 +1,7 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   // sets color to the provided r/g/b values

examples/conway.js

@@ -5,7 +5,7 @@
 var sphero = require("../");
 
 var spheros = {
-  Thelma : sphero("/dev/rfcomm0"),
+  Thelma : sphero(process.env.PORT),
   Louise : sphero("/dev/rfcomm1"),
   Grace  : sphero("/dev/rfcomm2"),
   Ada    : sphero("/dev/rfcomm3")

examples/data-streaming.js

@@ -1,7 +1,7 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   // options for streaming data

examples/freefall.js

@@ -0,0 +1,19 @@
+"use strict";
+
+var sphero = require("../");
+var orb = sphero(process.env.PORT, {timeout: 200});
+
+orb.connect(function() {
+  orb.detectFreefall();
+
+  orb.on("freefall", function(data) {
+    console.log("freefall detected");
+    console.log("  data:", data);
+  });
+
+  orb.on("landed", function(data) {
+    console.log("landing detected");
+    console.log("  data:", data);
+  });
+
+});

examples/get-color.js

@@ -1,7 +1,7 @@
 "use strict";
 
 var sphero = require("../");
-var orb = sphero("/dev/rfcomm0");
+var orb = sphero(process.env.PORT);
 
 orb.connect(function() {
   // sets color to the provided r/g/b values