Hack like a Ninja (Blocks developer)

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. 

Supported Platforms

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

  • Raspberry Pi users see this how-to guide for specific setup details including a script and an image.
  • Beagle Bone users can use the latest Ninja image.
  • Ubuntu users may have success with the beagle script, obviously you will not want to run the whole thing ;)



The Ninja client is a Node.js application. Node.js is very productive platform for writing network intensive applications. It runs on Google's V8 javascript virtual machine which has an extensive and rapidly growing list of supported platforms. It also has excellent library support backed by a mature package manager in NPM.

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

Install node-gyp globally via the node package manager.
    sudo npm install -g node-gyp


Native Build Tools

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.

  • Linux.
        sudo apt-get install build-essential
  • Mac: Install XCode and the CLT (Command Line Tools) 
  • Windows: Install Python 2.7.3 and MS Visual Studio Express 2012

Get it here.

Ninja Setup

Get the Source

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
cd 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). 

Running the Client

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. 

Ninja Blocks Registration and Setup

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.

What Next?

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.

James Zaki
James Zaki