node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org »

home-thing

home-thing

A module for npm

Install

From git:

npm install

How to set up

var name = "Example Thing";
var description = "A smart device that is being tested.";
 
var app = require("home-thing")(name, desription);

How to get the value of a property called value on another device:

 
var propertyName = "volume";
 
app.on("new peer", function(peer){
 
  peer.getProperties(function(property){
 
    property[propertyName].get(function(value){
    
      console.log(propertyName + " = " + value);
      
    });
    
  });
  
});
 

Structure

HomeThing

var name = "My Smart Device";
var description = "This is the coolest Smart Device";
 
var app = require("home-thing")(name, description);

This is the main-object that should only exist in one instance on the computer. The technical reason for this, is that the discovery mechanism requires reservation of port 50000. In the examples of the following documentation, the variable name app is used for holding this object.

Methods

Add Property

object addProperty (name, type, description, methods)
Type Parameter Description
String name Name of the property
String type "boolean", "number", "text", "list", "object"
String description A short textual description of the property.
Object methods Object with "get" and "set" functions.

Without anything to share, smart devices are not very interesting. The addProperty method allows adding of properties like temperature and power state for instance.

In order to share a property with the other smart devices on the network, a get-function must be declared. This function must be able to return the internal property value when requested by other peers. If you want to enable other devices to also change the value, you must also provide a set-function. For more information about this, see the examples below.

In addition to the functions, the property's name, type and description must also be provided according to the table above.

Note that property names are not case sensitive. Also, the object returned contains get- and set-functions similarly to what you declared except for one important difference; they also notify subscribing peers' listeners when the value change.

Example 1
 
// This is the variable that will be made externally available. 
var volume = 0;
 
var volumeProperty = app.addProperty("volume", "number", "Volume of computer", {
 
  // The get method must use a callback method when returning the value. 
  'get' : function(callback){
    callback(volume);
  },
  
  // The set method must also use a callback method. 
  'set' : function(value, callback){
    volume = value;
    callback();
  }
});
  

Another way to do the same:

Example 2
 
function VolumeProperty(){
 
  // This is the variable that will be made externally available. 
  var internalValue = 0;
 
  // The get method must use a callback method when returning the value. 
  this.get = function(callback){
    callback(internalValue);
  };
  
  // The set method must also use a callback method. 
  this.set = function(volume, callback){
    internalValue = volume;
    callback();
  };
  
}
 
var name = "volume";
var type = "number";
var desc = "Volume of computer";
 
var volumeProperty = app.addProperty(name, type, desc, new VolumeProperty());
  

Add Stream

void addStream (name, description, stream)
Type Parameter Description
String name Name of the stream.
String description A short textual description of the stream.
Object stream The stream-object containing stdout.

Not all data can be described sufficiently by properties. Therefore, this module are able to share streams over the WebSocket protocol. The addStream method allows your device to share internal data streams with other devices. This can for instance be a video streamed from a web camera or the output of a bash script. Sharing of streams enables creation of processing pipelines across the network.

Example
// This allows us to spawn child processes. 
var terminal = require('child_process');
 
// We start ffmpeg which will access the video device and pipe it to stdout in avi format 
var stream = terminal.spawn("ffmpeg", ["-i","/dev/video0","-f","avi","-"]);
 
// Publishing the stream, making it visible for other devices on the network 
app.addStream("video", "Video from webcam", stream.stdout);
 

End

void end ()

The end method shuts down the module and sends disconnect signal to all devices on the network.


Get Peers

Array getPeers ()

The getPeers method returns all avaiable peers on the network as objects in an array from an internal cache. The peers returned here are smart devices that responded to the network discovery on start up in addition to smart devices that later broadcasted their presence on the network.

Example
var peers = app.getPeers();
 
// Print out Array of peer objects 
console.dir(peers);

On

void on (eventName, callback(object))
Type Parameter Description
String eventName "new peer"
Function callback A function that will run when event is triggered.

The on method allows you to build event driven execution of tasks. The supported listeners are listed in the table above.

Example
app.on("new peer", function(peer){
 
  // Prints peer objects of all new peers 
  console.dir(peer);
});

Remove Property

void removeProperty (name)
Type Parameter Description
String name The name of the property

The removeProperty method allows you to remove previously created properties.

Example
// Removing a previously added property called volume 
app.removeProperty("volume");

Remove Stream

void removeStream (name)
Type Parameter Description
String name The name of the stream

The removeStream method allows you to unpublish a stream.

Example
// Removing a previously added stream called video 
app.removeStream("video");

Peer

The Peer object represents a smart device on the network.

var peers = app.getPeers();
for(var peer in peers){
  
  ...
}
Methods

Add Subscription

Object addSubscription (property, callback)
Type Parameter Description
String property Name of the property
Function callback The function that will run when property is changed.

The addSubscription method enables a smart device to subscribe to changes of a property on another device.

Example
peer.addSubscription("volume", function(data){
  // Prints out new data every time a update notification is received. 
  console.dir(data);
});
 

Get Details

void getDetails (callback(object))
Type Parameter Description
Function callback The function that will run when the new value returns.

The getDetails method requests basic details such as name and description from the smart device.

Example
peer.getDetails(function(details){
  // Prints out peer's basic details like name and description. 
  console.dir(details);
});

Get Properties

void getProperties (callback(Array))
Type Parameter Description
Function callback The function that will run when the details returns.

The getProperties method returns an array of Property objects.

Example
peer.getProperties(function(properties){
  // Prints out peer's properties. 
  console.dir(properties);
});

Get Streams

void getStreams (callback(object))
Type Parameter Description
Function callback The function that will run when a list of streams returns.
Example
peer.getStreams(function(streams){
  // Prints out peer's published streams. 
  console.dir(streams);
});

On

void on (eventName, callback)
Type Parameter Description
String eventName "disconnect", "structure change"
Function callback The function that will run when the event is triggered.
Example
peer.on("disconnected", function(){
  console.log("This peer just disconnected");
});

Property

The property object is a local handler for an external resource.

peer.getProperties(function(properties){
  if(properties && properties["volume"]){
    properties["volume"].get(function(value){
      console.log("Volume is "+ value);
    });
  }
});
Methods

Get

void get (callback(value))
Type Parameter Description
Function callback The function that will get the property.

This method lets you request a property value from its belonging smart device.

volumeProperty.get(function(volume){
 
  // Prints the current value of the volume property 
  console.log("Volume is now "+ volume);
});

Set

void set (value, callback(object))
Type Parameter Description
Var value The value to set
Function callback The function that will change the property.

The set method sends the given value to the smart device that has the property. The callback function is executed when the smart device has given its response.

volumeProperty.set(54, function(){
  console.log("Volume set.");
});

Stream

peer.getStreams(function(streams){
  for(var key in streams){
    console.log("stream "+ key);
  }
});
Methods

On

void on (eventName, callback)
Type Parameter Description
String eventName "data", "end" (see nodejs-docs)
Function callback The function that will run when the event is triggered.
Example
stream.on("data", function(data){
  console.log("line: "+ data);
});

Pipe

void pipe(ouputStream)
Type Parameter Description
Object ouputStream The stream that will recieve data.

The pipe method lets you pipe streams from other peers to your local processes.

// Saving stream from other device to a file 
var fileStream = fs.createWriteStream(filename);
remoteVideoStream.pipe(fileStream);

Unpipe

void unpipe()

The unpipe method breaks the pipe between two streams.

stream.unpipe();

Subscription

var subscription = peer.addSubscription("volume", function(data){
  console.dir(data);
});
 
subscription.on("added", function(){
  console.dir("Added Subscription!");
});

Subscriptions

Methods

End

void end (callback)
Type Parameter Description
Function callback The function that will run when the subscription is ended.

End the subscription.

subscription.end(function(){
  console.log("Subscription ended.");
})

On

void on (eventName, callback(object))
Type Parameter Description
String eventName "added"
Function callback The function that will run.
var subscription = peer.addSubscription("volume", function(data){
  console.log("Subscription added.");
  console.dir(data);
});