home-thing v0.0.25

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
• Peer
• Property
• Stream
• Subscription

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

• addProperty()
• addStream()
• getPeers()
• end()
• on()
• removeProperty()
• removeStream()

Add Property

object addProperty (name, type, description, methods)

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)

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

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)

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)

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

• addSubscription()
• getDetails()
• getProperties()
• getStreams()
• on()

Add Subscription

Object addSubscription (property, callback)

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

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

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

Example

peer.getStreams(function(streams){
  // Prints out peer's published streams.
  console.dir(streams);
});

On

void on (eventName, callback)

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()
• set()

Get

void get (callback(value))

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

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()
• pipe()

• unpipe()

On

void on (eventName, callback)

Example

stream.on("data", function(data){
  console.log("line: "+ data);
});

Pipe

void pipe(ouputStream)

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()
• on()

End

void end (callback)

End the subscription.

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

On

void on (eventName, callback(object))

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