home-controller

v0.9.2

Published

2 years ago

A Node Home Automation Controller for Insteon Devices

Downloads

0High
0Medium
0Low

brandongoode

siburny

automation insteon

home-controller

a node package to control Insteon home automation devices

Overview

home-controller is a node package to control Insteon home automation devices. The API uses the direct PLM connection over TCP, Serial connection or the cloud. To control the Insteon devices one of the following is needed:

Automate Green WiFi Hub i
Automate Green PLM WiFi Adapter - Insteon Hub 2242
Insteon SmartLinc
Insteon PowerLinc Modem is required.
Insteon Hub 2245 is only supported over the HTTP client interface, which has caveats (see httpClient)

Features

Device and Gateway Info
Linking and Group Control
Scene Control
Lighting Control
Thermostat Control
Sensor 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.8.0 Update Highlights:

BREAKING CHANGES
- By default, events are not emitted for commands you call. You can restore the previous functionality by setting insteon.emitSelfAck = true.
Updated dependencies
Improved testing and code

0.7.0 Update Highlights:

Major bugfixes and refactor of parsing code for event data
Support for the Insteon 2245 hub
Support for the following device types:
- X10
- IO Linc
- GarageDoor
Drastic increase in test coverage

0.6.0 Update Highlights:

Add support for IO
Add support for FanLinc (light)
Add support for Node 0.12
Add support for Spark based devices
Bug fixes

0.5.2 Update Hightlights:

Add support for iMeter (meter)

0.5 Update Hightlights:

Add events for devices
Add sensors support (motion, door, & leak)
Node.js 0.11 support
As always, a few bug fixes

0.4.3 Update Highlights:

Add thermostat.status()
Several bug fixes

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 were 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.

Examples

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

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;

Warning serialport is not supported in all environments. Verify serialport installed successfully before using this functionality. Note Starting with verion 5.0 options parameter accepts key names in camelCase only.

insteon.httpClient({host: 'host' port: 123, ...}, [connectListener])

Connect to a newer Hub (such as model 2245) via the HTTP interface. The config must be an object with at minimum host and port. Full set of options:

host Required, the IP address or hostname of the hub on your local network
port Required, the port of the hub's interface (printed on the label on the bottom)
user The username for the endpoint (usually printed on the bottom label)
password Password for the endpoint (also on bottom label)
maxDelay Advanced Usage: the maximum amount of time (in milliseconds) between fetches. If not provided, this defaults to 5000.

The optional connectListener parameter can be passed a function which will be called after the client has made its first request, and is provided mainly for symmetry with all the other types of client connections.

HTTP Limitations

Due to limitations in the Insteon Hub's single threaded design, when using the HTTP client, it will "lock out" any other local network apps (such as the Insteon Hub iOS app or other internal home-control apps) from accessing the hub for programming, setup, etc. To resume using those apps, you must first close your home-controller instance using either insteon.close() or closing out your application.

Similarly, you will probably find that if you were using one of these iOS apps, your application using home-controller will refuse to start until you quit the app.

HTTP Client Example

var insteon = new Insteon();
var config = {
  host: '192.168.10.10',
  port: 2525,
  user: 'hubuser',
  password: 'hubpassword'
};
insteon.httpClient(config, 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.emitOnAck

By default, events will be emitted for both device triggered (button presses) and hub triggered actions. If you don't want that behavior, disable it by setting emitOnAck to false.

Example:

var hub = new Insteon();
var light = hub.light('112233');

hub.connect(...);

light.turnOn(); // Emits 'turnOn' event

hub.emitOnAck = false; // Disables events on command ack

light.turnOn(); // Does not emit event

insteon.emitDuplicates

By default, duplicate events for devices will be suppressed. If you want to see the duplicate events, you must enable them by setting emitDuplicates to true.

Example:

var hub = new Insteon();

hub.emitDuplicates = true; // Enabled duplicate events

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('gw', ['111111', '222222', '333333'], function(error, link) {
  // link data from last responder, 33.33.33
})

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

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

// Link unknown device to gateway (same as link(null, 'gw', fn))
insteon.link(null, 'gw', 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 'gw', or null. If a device id is provided, the device will be configured as the controller. If controller is 'gw' 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 (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.

remove is the boolean flag used to delete a responder(s) from the scene.