home-controller is a node package to control Insteon home automation devices. The API uses the direct PLM connection over TCP. As of 0.3, the HTTP interface is no longer used. To control the Insteon devices, either an Insteon Hub or an Insteon SmartLinc must be accessible from the app.
- Device and Gateway Info
- Linking and Group Control
- Lighting Control
- Thermostat Control Coming soon
Install via npm:
npm install home-controller
Note: As of version 0.3 the function on, onFast, off, and offFast have been renamed to turnOn, turnOnFast, turnOff, and turnOffFast. This was done to remove the name conflict with EventEmitter.
Add require
statement to the app to access the Insteon class
var Insteon = require('home-controller').Insteon;
The Insteon class inherits EventEmitter
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.
var gw = new Insteon();
gw.connect('192.168.10.10', function(){
console.log('Connected!');
});
Closes the connection to the gateway. The event 'close'
will be emitted once the connection is closed.
Emitted when the connection to the gateway is successfully established.
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
Emitted when an unsolicited command is received. The argument command
will be the command object.
Callback arguments
command
received from gateway
Emitted when an error occurs. The 'close' event will be called directly following this event.
Links device(s) to gateway. Callback return link object as second argument (see gw.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.
{
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.
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.
{
id: String, // device id (6 digit hex String)
level: Number, // See level in gw.turnOn()
rate: Number, // See rate in gw.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.
{
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.
var gw = Insteon('my.home.com');
// Link two devices with for 2nd button on dimmer
gw.link('AABBCC', '112233', {group: 2}, function(error, link) {
// link data from responder, 11.22.33
});
// Link gateway to multiple devices
gw.link('gw', ['111111', '222222', '333333'], function(error, link) {
// link data from last responder, 33.33.33
})
// Link device to gateway
gw.link('ABCDEF', 'gw', function(error, link) {
// link data from gateway
});
// Shorthand to link gateway to unknown device
gw.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))
gw.link(null, 'gw', function(error, link) {
// link data from gateway
});
// Shorthand to a device to an unknown device
gw.link('123456', function(error, link) { // link('123456', null, fn)
// link data from gateway
});
Unlinks device from the gateway
See link
for usage.
Cancels linking/unlinking
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.
{
id: String,
group: Number,
controller: Boolean,
isInUse: Boolean,
hasBeenUsed: Boolean,
isLast: Boolean,
data: Array(3)
}
Gets the first link record on the gateway
Gets the next link record on the gateway
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, ... ).
Gets the product information about the gateway or a device. Product info object is returned in callback.
id
is the id (6 digit hex String) of the device from which to get the product info. If not provided, the gateway's product info will be returned.
var gw = Insteon('my.home.com');
// Get gateway info
gw.checkStatus(function(error, info) {
// For details on the info object see below.
});
// Get Device info
gw.checkStatus('AABBCC', function(error, info) {
// For details on the info object see below.
});
{
id: String,
productKey, String,
deviceCategory: {
id: Number,
name: String
},
deviceSubCategory: {
id: Number
},
isDimmable: Boolean,
isLighting: Boolean,
isThermostat: Boolean
}
Sends a Insteon ping to a device. Response object is returned in the callback, if the ping was successful.
id
is the id (6 digit hex String) of the device from which to get the product info.
Gets the version information about a device. Version object is returned in callback. Valid version names are i1, i2, and i2cs.
id
is the id (6 digit hex String) of the device from which to get the product info.
{
code: Number,
name, String,
}
Turns an Insteon dimmer switch on to the provided level
id
is the id (6 digit hex String) of the light switch
level
is the percentage (0-100) of full to which the dimmer is set. Non-dimmable switches ignore this and turn on to full. Defaults to 100 percent.
rate
is the speed at which the light is turned on to the provided level
. If not provided, the default saved ramp rate of the device is used. The rate value can either be 'slow', 'fast', or the number of milliseconds. 'fast' is 0.1 seconds. 'slow' is 1 minute. If milliseconds is provided, the closest defined ramp rate less than the provided value is used.
Turn light on fast (no ramp) to pre-saved level
id
is the id (6 digit hex String) of the light switch.
Turns light off
id
is the id (6 digit hex String) of the light switch.
rate
is the speed the light turns off. See on
for values.
Turns light off fast (no ramp)
id
is the id (6 digit hex String) of the light switch.
Brightens the light one step
id
is the id (6 digit hex String) of the light switch.
Dims the light one step
id
is the id (6 digit hex String) of the light switch.
Gets or sets the light's current level
id
is the id (6 digit hex String) of the light switch.
level
is the percentage (0-100) of full to which the dimmer is set. If not provided, then the current level of the device is returned in the callback.
var gw = Insteon('my.home.com');
// Set light level
gw.level('AABBCC', 50, function(error) {
// Get light level
gw.level('AABBCC', function(error, level)){
console.log(level); // Should print 50
}
});
Coming Soon
For advanced users only. These function are leveraged by the higher level functions.
Sends command to PLM function on the gateway
command
can either be the String (hex byte) for the PLM command or the Command Object with a raw property.
Command Object:
{
raw: String,
type: String
}
timeout
is the number of milliseconds to wait before checking the status. If timeout
is omitted or null, the command doesn't check the status. timeout
should be set to zero to check immediately.
Sends direct command to Insteon device
id
is the id (6 digit hex String) of the device.
command
can either be a hex String (length 2) or an Object. The String must be a standard direct command. If command is a String, then param
can also be passed. The param
will be defaulted to '00'
. If the command is an extended command, it must be passed as an Object with the extended property.
Standard Command Object:
{
cmd1: String,
cmd2: String
}
Extended Command Object:
{
extended: true,
cmd1: String,
cmd2: String,
userData: Array
}
Checks the status of the gateway's buffer
This is used to read response messages. This buffer must be checked after each command if a response is expected. The buffer is overwritten each time a command is sent.
var gw = Insteon('my.home.com');
gw.checkStatus(function(error, status) {
// For details on the status object see below.
});
A Status Object will be returned in the callback. The Status Object format depends on the response type.
Get Modem Info Response (0x60) Status Object:
{
command: Object,
ack: Boolean,
response: {
raw: String,
type: String,
id: String,
deviceCategory: {
id: Number,
name: String
},
deviceSubcategory: {
id: Number
},
firewareVersion: String
}
}
Send Message Response (0x62) Status Object:
{
command: Object,
ack: Boolean,
response: {
raw: String,
type: String,
id: String,
standard: {
id: String,
gatewayId: String,
extended: false,
messageType: Number,
hopsLeft: Number,
maxHops: Number,
command1: String,
command2: String,
raw: String
},
extended: {
id: String,
gatewayId: String,
extended: true,
messageType: Number,
hopsLeft: Number,
maxHops: Number,
command1: String,
command2: String,
userData: Array(14),
raw: String
}
}
}
All-Linking Response (0x64) Status Object:
{
command: Object,
ack: Boolean,
response: {
raw: String,
type: String,
controller: Boolean,
wasDeleted: Boolean,
group: Number,
id: String,
deviceCategory: {
id: Number,
name: String
},
deviceSubcategory: {
id: Number
},
firmwareVersion: String
}
}
Get All-Link Record Response (0x69 & 0x6A) Status Object:
{
command: Object,
ack: Boolean,
response: {
raw: String,
type: String,
link: {
controller: Boolean,
isInUse: Boolean,
hasBeenUsed: Boolean,
isLast: Boolean,
group: Number,
id: String,
data: Array(3)
}
}
}
To test the package run:
grunt test