home-controller

Introduction

home-controller is a node package to control Insteon home automation devices. The API uses the direct PLM connection over TCP. To control the Insteon devices, either an Insteon Hub or an Insteon SmartLinc must be accessible from the app.

Features

Device and Gateway Info
Linking and Group Control
Scene Control
Lighting Control
Thermostat Control

Getting Started

Install

Install via npm:

npm install home-controller

Example

The example below is a simple RESTful interface using the home-controller module and Express.

var Insteon = require('home-controller').Insteon;
var hub = new Insteon();
var express = require('express');
var app = express();

app.get('/light/:id/on', function(req, res){
  var id = req.params.id;
  hub.light(id).turnOn()
  .then(function (status) {
    if(status.response) {
      res.send(200);
    } else {
      res.send(404);
    }
  });
});

hub.connect(process.env.HUB_IP, function () {
  app.listen(3000);
});

Additional Examples

API

0.4.2 Update Highlights:

Add connect.serial()

0.4 Update Highlights:

Major refactoring of the code structure.
All functions return promises (via Q). The callback function is now optional.
The lighting function have been moved to the light class. Old function are deprecated and will be removed with a later release.
Thermostat control is now available
As always, several bug wer fixed (and probably several new one introduced). Please open an issue if you find a bug.
Full releases notes

Insteon Gateway

Class: Insteon()

Add require statement to the app to access the Insteon class

var Insteon = require('home-controller').Insteon;

The Insteon class inherits EventEmitter

insteon.connect(host, [port], [connectListener])

Creates a connection to the gateway.

When the 'connect' event is emitted the connection is established. If there is a problem connecting, the 'connect' event will not be emitted, the 'error' event will be emitted with the exception. (See socket.connect);

connectListener will be added as an listener for the 'connect' event.

insteon.serial(comName, [options], [connectListener])

Creates a connection to a PowerLinc USB driver residing at the specified USB serial device. The 'options' parameter, if present, contains values suitable for use with the serialport constructor. The 'connectListener' parameter, if present, will be invoked once the connection is open;

Examples

var insteon = new Insteon();
insteon.connect('192.168.10.10', function(){
  console.log('Connected!');
});

insteon.close()

Closes the connection to the gateway. The event 'close' will be emitted once the connection is closed.

Event: 'connect'

Emitted when the connection to the gateway is successfully established.

Event: 'close'

Emitted once the socket is fully closed. The argument had_error is a boolean which says if the socket was closed due to a transmission error. (See net.Socket Event: 'close')

Callback arguments

had_error Boolean true if the socket had a transmission error

Event: 'command'

Emitted when an unsolicited command is received. The argument command will be the command object.

Callback arguments

command received from gateway

Event: 'error'

Emitted when an error occurs. The 'close' event will be called directly following this event.

Insteon Linking Functions

insteon.link([device,] [options,] [callback])

Links device(s) to gateway. Callback return link object as second argument (see insteon.links).

device is the device to link. It can either be a device id (6 digit hex String), an Array of ids, or null. If a device id is provided, the device will be linked. If an array of ids is provided, each devices will be configured linked. If device is null, the device must be put into linking state manually (hold set button). The device will be setup as the responder, unless the controller option is true.

options is an Object with the options to be used during linking.

Link Options Object

{
  controller: Boolean, // link the device(s) as a controller(s)
  group: Number, // controller group/button
  timeout: Number // timeout for manual linking
}

group is the controller group to link the responders to. Valid group numbers vary by device type. The hub supports group numbers 0-255. Default is 1.

timeout is the number of milliseconds to wait for linking to complete. (Remember you have to hold the set button for at least 10 seconds.)Default is 30000 ms.

Examples

var insteon = Insteon('my.home.com');

// Link two devices with for 2nd button on dimmer
insteon.link('AABBCC', '112233', {group: 2}, function(error, link) {
  // link data from responder, 11.22.33
});

// Link gateway to multiple devices
insteon.link('insteon', ['111111', '222222', '333333'], function(error, link) {
  // link data from last responder, 33.33.33
})

// Link device to gateway
insteon.link('ABCDEF', 'insteon', function(error, link) {
  // link data from gateway
});

// Shorthand to link gateway to unknown device
insteon.link(function(error, link) { // link('insteon', null, fn)
  // link data from unknown device (responder)
});

// Link unknown device to gateway (same as link(null, 'insteon', fn))
insteon.link(null, 'insteon', function(error, link) {
  // link data from gateway
});

// Shorthand to a device to an unknown device
insteon.link('123456', function(error, link) {  // link('123456', null, fn)
  // link data from gateway
});

insteon.unlink([[controller,] responder,] [options,] [callback])

Unlinks device from the gateway

See link for usage.

insteon.cancelLinking([callback])

Cancels linking/unlinking

insteon.links([id,] [callback])

Gets the links of a device or the gateway

Links are returned in the callback as an Array of Link Objects.

id is the id (6 digit hex String) of the device from which to retrieve the links.

Link Object

{
	id: String,
	group: Number,
	controller: Boolean,
	isInUse: Boolean,
	hasBeenUsed: Boolean,
	isLast: Boolean,
	data: Array(3)
}

insteon.firstLink([callback])

Gets the first link record on the gateway

insteon.nextLink([callback])

Gets the next link record on the gateway

insteon.linkAt(id, at, [callback])

Gets the link at a memory address on a device

id is the id (6 digit hex String) of the device

at is the memory address. Addresses start at 4095 (0xFFF) and count down by 8. (4095, 4087, 4079, ... ).

Scene Functions

insteon.scene(controller, responder, [options,] [callback])

Creates scene controller with responder(s). All devices must be available and linked to the gateway.

controller is the device to setup as controller. It can either be a device id (6 digit hex String), the string 'insteon', or null. If a device id is provided, the device will be configured as the controller. If controller is 'insteon' the gateway will be configured as the controller.

responder is the device to setup as responder. It can either be a responder object or an Array of responder objects. The responder object can also be the device id (6 digit hex String); default scene values will be used.

Responder Object

{
	id: String, // device id (6 digit hex String)
	level: Number, // See level in insteon.turnOn()
	rate: Number, // See rate in insteon.turnOn()
	data: Array  // data to be configure for scene (overrides level and rate)]
}

options is an Object with the options to be used during linking.

Scene Options Object

{
	group: Number, // controller group/button (default: 1)
	remove: boolean // remove existing responders if not passed in responder (default: false)
}

group is the controller group to link the responders to. Valid group numbers vary by device type. The hub supports group numbers 0-255. Default is 1.

timeout is the number of milliseconds to wait for linking to complete. (Remember you have to hold the set button for at least 10 seconds.) Default is 30,000 ms.