Literate version of API example

examples/api/api.coffee

@@ -12,11 +12,11 @@ SpheroRobot =
 
   device: { name: 'sphero', driver: 'sphero' }
 
-  work: (me) ->
+  work: (my) ->
     every 1.seconds(), ->
-      Logger.info me.name
-      me.sphero.setRGB Math.floor(Math.random() * 100000)
-      me.sphero.roll 60, Math.floor(Math.random() * 360)
+      Logger.info my.name
+      my.sphero.setRGB Math.floor(Math.random() * 100000)
+      my.sphero.roll 60, Math.floor(Math.random() * 360)
 
 for bot in bots
   robot = Object.create SpheroRobot

examples/api/api.js

@@ -12,11 +12,11 @@ var SpheroRobot = {
 
   device: { name: 'sphero', driver: 'sphero' },
 
-  work: function(me) {
+  work: function(my) {
     every((1).seconds(), function() {
-      Logger.info(me.name);
-      me.sphero.setRGB(Math.floor(Math.random() * 100000));
-      return me.sphero.roll(60, Math.floor(Math.random() * 360));
+      Logger.info(my.name);
+      my.sphero.setRandomColor();
+      my.sphero.roll(60, Math.floor(Math.random() * 360));
     });
   }
 };

examples/api/api.litcoffee

@@ -0,0 +1,71 @@
+# API
+
+In this Cylon example, we'll be demonstrating the HTTP API that Cylon spins up
+when it starts.
+
+This example involves two Spheros, so before you start make sure you have the
+`cylon-sphero` module installed.
+
+First, let's import Cylon:
+
+    Cylon = require '../..'
+
+Next up, we'll configure the API Cylon will serve, telling it to serve on port
+`8080`.
+
+    Cylon.api host: '0.0.0.0', port: '8080'
+
+Since we're making two very similar robots (Spheros, in this case), let's put
+the different parts of each robot in objects so we can initialize them later.
+The only differences between the bots are their names and the port they'll be
+using.
+
+    bots = [
+      { port: '/dev/rfcomm0', name: 'Thelma' },
+      { port: '/dev/rfcomm1', name: 'Louise' }
+    ]
+
+Now we can define the basic robot both of our Sphero robots will be based on.
+
+    SpheroRobot =
+
+Both robots will be connecting to Spheros, and so using the cylon-sphero
+adaptor:
+
+      connection: { name: 'Sphero', adaptor: 'sphero' }
+
+And both will be connecting to the same kind of device (you guessed it,
+a Sphero).
+
+
+      device: { name: 'sphero', driver: 'sphero' }
+
+Both robots will be performing the same kind of work as well.  Every second,
+they'll print their name to the console, set themselves to a random color, and
+roll in a random direction.
+
+      work: (my) ->
+        every 1.seconds(), ->
+          Logger.info my.name
+          my.sphero.setRandomColor()
+          my.sphero.roll 60, Math.floor(Math.random() * 360)
+
+Now that we know what hardware the robots have and what work they'll be doing,
+let's create them! We'll iterate through our earlier `bots` array, creating
+a new Robot, assigning it it's unique characteristics, then passing it off to
+Cylon so it can keep track of it.
+
+    for bot in bots
+      robot = Object.create SpheroRobot
+      robot.connection.port = bot.port
+      robot.name = bot.name
+
+      Cylon.robot robot
+
+And now that Cylon has all the robots we're intending to give it, let's get
+started!
+
+    Cylon.start()
+
+Now Cylon will start up the robots and their devices, as well as an API server
+listening on `0.0.0.0:8080`.