hahn-controller

Hahn-controller

A butchered Copy of automategreen/home-controller, a node package to control Insteon home automation devices.

Overview

hahn-controller is a node package to control Insteon home automation devices. The API uses the direct PLM connection over Serial. Insteon PowerLinc Modem is required.

Overview
Features
Getting Started
API
Testing
References

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 hahn-controller

Example

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

var Insteon = require('hahn-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.6.0 Update Hightlights:

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('hahn-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.

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