skygrid v0.2.8

#SkyGrid An API for the physical world.

Installation

NPM:

npm install --save skygrid

Bower:

bower install --save skygrid

CDN:

https://cdn.skygrid.io/sdk/js/skygrid-0.2.8.min.js

The SDK itself makes heavy use of ES6 Promises. As a result of this to enable support in some browsers requires a polyfill,

Usage

Interacting with devices

The Device object allows us to fetch the current state of the device from the SkyGrid backend, to update the state of the device, and subscribe to changes to that device.

var skygrid = require('skygrid');

// Get a Project object that lets us interact with a SkyGrid project.
var project = skygrid.project('94hfg93');

// Gets a Device object that lets us interact with a device.
var device = project.device('mjd93ngk');

Fetching data

First we'll cover the fetching of device data. This is simply done with the fetch() method. It is an async method that returns a Promise. If you are unfamiliar with ES6 promises in JavaScript, you can learn more about them here.

device.fetch().then(() => {
	// Device state has been successfully fetched
}).catch(err => {
	// Handle errors here
});

There is also the fetchIfNeeded() method, which fetches data from the server if it has not yet been fetched. Please note, however, this does not mean a device state will be fetched if it has previously been fetched and changed on the backend since this time.

Setting data

Device properties can be set with the set() method, and retrieved with the get() method. Any change made to a device instance is not pushed to the backend until the save() method is called.

device.set('speed', 100);
device.set('distance', 10);
device.save().then(device => {
	// Successfully saved
});

You can also directly set properties in the save method:

device.save({
	speed: 100,
	distance: 10
});

Note that internally, all device changes are stored as a changeset until they are pushed to the server. When accessing the Device instance locally, the changes will be returned when querying properties. Changes can also be discarded any time before save() is called.

var device = project.device('9fh9hfws');
device.get('speed'); // 100
device.set('speed', 10);
device.get('speed'); // 10
device.discardChanges();
device.get('speed'); // 100

Subscribing to changes

Subscribing to a device allows us to receive changes in real time as they are received by the SkyGrid backend. Once subscribe() is called on a device, that particular instance of the device is kept up to date.

device.subscribe();

We can also pass a function to subscribe() that will get called every time an event is received.

function logChanges(changes, device) {
	changes.map(function(change) {
		console.log(change + ': ' + device.get(change));
	});
}

device.subscribe(logChanges);

var subId = device.subscribe(changes => {
	changes.map(change => {
		console.log(change + ': ' + device.get(change));
	});
});

Removing subscriptions

You can use the unique subscription ID returned by subscribe() to remove a subscription, or you can remove all subscriptions at once.

// Remove by function
device.unsubscribe(logChanges);

// Remove by subscription ID
device.unsubscribe(subId);

// Remove all
device.unsubscribe();