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)

| 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

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

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

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

• pipe()

• unpipe()

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

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