sphero-with-node.md

Sphero with Node

This document will help you get started with controlling an Orbotix Sphero using Node.js.

Client Libraries

There are several different libraries for controlling the Sphero. Currently, the best one seems to be The Hybrid Group's fork of spheron. This module provides a complete interface to the entire Sphero API. You can install this with npm install git://github.com/hybridgroup/spheron.git.

There is also CylonJS, but this just uses the spheron module and exposes the same API, so unless you are already using Cylon to control different hardware it probably makes sense to just use spheron directly.

API Documentation

The spheron client library does provide much documentation, but Orbotix has detailed documentation for the entire Spheron API. You will have to manually inspect the functions available on the spheron sphero object and match them up to commands found in Sphero API PDF to understand the parameters and what they do. The names match up pretty nicely.

Connecting to Sphero

Based on my experience on a MBP and OSX 10.9. For Linux see comment below.

Bluetooth Pairing

Once removed from the charger, you need to shake the sphero twice until it lights up with your 3-color signature. At this point you should see the device in your Bluetooth settings (in System Preferences) and can click Pair to pair with the device. Any time the Sphero wakes up (e.g., was not "lit up" and you shook it to light it up) you will have to remove and re-pair the device (see troubleshootin below).

Connecting in Node

Once you have paired and have a Bluetooth connection with the Sphero you should see a device file in /dev.

$ ls /dev | grep -i sphero 
cu.Sphero-BYR-RN-SPP
tty.Sphero-BYR-RN-SPP

The one starting with cu. is what you will use when connecting:

var sphero = require('spheron').sphero();
sphero.open("/dev/cu.Sphero-BYR-RN-SPP");

If this fails, try the troubleshooting section below.

Troubleshooting

• Device not in Bluetooth list: If your Sphero device does not appear in the list of found Bluetooth devices, make sure the Sphero is emitting its 3-color signature. If it is not, shake the device until it does.

• Remove and re-pair: Any time you see the Sphero device in your Bluetooth settings but Not Connected, you should forget the device (right click -> Remove), wait for the Sphero to show up again, and click Pair again.

• Reset the device: If you still have issues connecting, you can reset the device (described in the Sphero Quick-Start Guide manual) and try again. Make sure to remove the device from your paired Blueooth devices and re-pair after resetting.