py-ninja is a Python wrapper for the Ninja Blocks API. It's still experimental, and should be considered unstable (hence its unpackaged state).

Install the requirements: pip install -r requirements.txt

An access token is also required. This can be found on the API tab of the Ninja Block dashboard. It can also be acquired through OAuth.

There are three major components to py-ninja: the core API wrapper, the devices, and a system of nodes for managing a data flow.

See the scripts in examples/ for sample usage of each.

Given your access token and the device GUID of the onboard temperature sensor, display the current temperature reading, in Celsius, every 10 seconds:

from ninja.api      import NinjaAPI
from ninja.devices  import TemperatureSensor

api = NinjaAPI(ACCESS_TOKEN)
temp_sensor = TemperatureSensor(api, GUID)

def printData(inst, data):
    print inst.last_read, ':', data.c

temp_sensor.onHeartbeat(printStatus)
temp_sensor.pulse(10)

The core is the NinjaAPI class, which handles the direct interaction with the Ninja Block API. NinjaAPI instances are initialized with an access token.

from ninja.api import NinjaAPI
api = NinjaAPI(ACCESS_TOKEN)

Once initialized, the instance can be used to get a list of devices, a specific, or the authenticated user's information.

• api.getDevices()
• api.getDevice(device_guid)
• api.getUser()

The devices returned are instances of the device classes in ninja.devices.

The devices are a set of classes for each possible device, with helpers for each kind.

Devices must be initialized with a NinjaAPI instance, and a GUID:

from ninja.devices import TemperatureSensor
temp_sensor = TemperatureSensor(api, GUID)

The devices are event-based. By adding a callback to the heartbeat event using .onHeartbeat, the data can be processed whenever the heartbeat event occurs:

def printData(inst, data):
	print inst.last_read, ':', data.c

temp_sensor.onHeartbeat(printStatus)

Multiple handlers can be added to a device's heartbeat event, which can be triggered by calling device_instance.heartbeat(). This will use the initialized NinjaAPI instance to make a GET request to that device's heartbeat endpoint, and then call each event handler with the device instance and the new data.

To read data repetitively, device heartbeats can be 'pulsed' some number of seconds using their .pulse method:

temp_sensor.pulse(10)

The catch with the .pulse method is that its loop is blocking, so only one device can be pulsed at a time.

The Watcher class is provided to trigger the heartbeat of any number of devices in a regular cycle.

Assuming some devices initialized as above:

from ninja.api import Watcher
watcher = Watcher(device1, device2)
watcher.start(period=10)

will trigger a heartbeat on each device, in order, and any attached handlers, every 10 seconds.

For working with more complicated flows and manipulations of data, a set of node classes are provided in ninja.nodes. These nodes can be used to build a graph of data transformations and handling.

Each node can have an input and/or and output. Data flows from output to input. Any number of outputs can be connected to an input, and any number of inputs can be connected to an output. There are nodes for devices, channel nodes that aggregate outputs and provide points for transform functions, IO nodes for writing CSV and JSON files or making HTTP requests, and logic nodes for managing the flow of data. There is also a Ticker that wraps the Watcher, for triggering the device nodes in regular cycles.

See examples/multiple_devices_with_nodes.py for an example of nodes in action. (It looks more complicated than it is.)

There is also a set of unit helpers, including Temperature and Color, in ninja.units.

• add devices
• provide helpers for the OAuth flow
• geventify
• package
• more thorough docs and examples
• sample web app with oauth flow
• tests once parts stabilize
• simulation mode

• Alec Perkins

Unlicensed aka Public Domain. See UNLICENSE for more information.