This guide explains how to get the Ninja client app running on your desktop. If you want to connect an Arduino project to Ninja, write a Ninja module, or just have a nerdy good time, this how-to is for you.
Ninja Blocks is a growing open source platform that makes it easier to connect physical devices to internet services and applications. Everything can be accessed through a RESTful API documented at docs.ninja.is. Whilst REST APIs are fantastic as a lowest common denominator, HTTP isn't the most efficient answer to everything. The Ninja client is a Node.js application that handles communication with the Ninja service over a socket. You can think of it as a smart proxy or gateway that can be easily extended. It is what is running on the official Ninja Block.
You can run the Ninja client on any platform that supports node.js (some modules may require native libraries). At the time of writing we have setup scripts for Debian on Raspberry Pi and Ubuntu on Beagle Bone. These setup scripts are available on github.
You can install 'nodejs' and 'npm' via your favourite package manager (brew, apt-get, etc) for your OS, binaries and source are available from here. NOTE: in OSX brew, the name is 'node' (not nodejs).
You will need to have a version of nodejs >= 0.8. Linux on an intel can try Chris-Lea's pre-compiled packages. Linux on an ARM (Beagle, RaspberryPi), must be compiled from source. OSX brew installs v0.8.15 at the time of writing. If you are unsure what version is running, you can check the version with node -v.
NB: you will need to symbolically link the nodejs binary to node for future use (this is not the package called 'node').
sudo ln -s /usr/bin/nodejs /usr/bin/node
sudo npm install -g node-gyp
Whilst node.js itself runs in V8s virtual machine, libraries can include native code. An example of this is the serial port library that communicates with Arduino's. In order to build on your platform you might need to download some extra tools.
sudo apt-get install build-essential
Check-out the source code from https://github.com/ninjablocks/client into a directory ninjaclient, switch to the 'develop' branch, and download dependencies.
git clone git://github.com/ninjablocks/client.git ninjaClient
git checkout develop
This last step grabs the dependencies from package.json and builds them if necessary. At the time of writing there are a couple of dependencies that will attempt to compile native code to access the serial port and usb notification subsystem. This may take a while (looking at you embedded linux).
Set the environment variable "NODE_ENV" to "hacking", eg. linux/mac (can also be put in something like ~/.bash_profile - remember that usually environment variables are scoped to your terminal session). The hacking flag increases logging, generates a serial number, and generally behaves better for development.
$ export NODE_ENV=hacking
From inside the client directory, run client.js with node:
$ node client.js
[Tue, 22 Jan 2013 23:23:27 GMT] (info) Successfully loaded token from file
[Tue, 22 Jan 2013 23:23:27 GMT] (info) Successfully loaded serial from file
[Tue, 22 Jan 2013 23:23:27 GMT] (info) This Ninja's Serial: XXXXXXXXXXXXXX
[Tue, 22 Jan 2013 23:23:27 GMT] (info) loadModule success: serial
[Tue, 22 Jan 2013 23:23:27 GMT] (info) loadModule success: platform
[Tue, 22 Jan 2013 23:23:29 GMT] (info) Attempting to activate...
Copy the serial number to your clipboard, you will need it to pair your block in the next step.
Protip: Install the handy nodemon tool (npm install -g nodemon) and use nodemon in place of node. Nodemon will restart the app whenever file changes are detected, very handy for development.
Sign in at a.ninja.is/born (your serial number will work for your invite code)
From the home screen (https://a.ninja.is/home), click Pair Block
Now enter your serial number copied from the console.
You should get a confirmation that the block has been paired (and you should messages on the console) but you wont see any new device appear yet because there aren't any modules that automatically send device data.
Connect an Arduino based project using the NinjaBlockSerial Arduino library. Specify your Arduino port by editing app/argv.js in the hacking section or as a command line argument, e.g.
$ node client.js --device /dev/tty.usbmodem1421
For advanced players, you might like to write a Ninja Module. There are a few in the ninja_modules directory or take a look at this one that wraps the Philips Hue unoffical API https://github.com/thatguydan/ninja-hue
As always, please let us know what you make or any issues you run into on the forums.