Insteon PLM Binding - vpjuslin/openhab GitHub Wiki

Insteon is a home area networking technology developed primarily for connecting light switches and loads. Insteon devices send messages either via the power line, or by means of radio frequency (RF) waves, or both (dual-band). A considerable number of Insteon compatible devices such as switchable relays, thermostats, sensors etc are available. More about Insteon can be found on Wikipedia.

This binding provides access to the Insteon network by means of either an Insteon PowerLinc Modem (PLM), or an Insteon Hub (2245-222 aka "Hub 2014"). The modem can be connected to the openHAB server either via a serial port (Model 2413S) or a USB port (Model 2413U). The binding translates openHAB commands into Insteon messages and sends them on the Insteon network. Relevant messages from the Insteon network (like notifications about switches being toggled) are picked up by the modem and converted to openHAB status updates by the binding. The binding also supports sending and receiving of legacy X10 messages.

OpenHAB is not a configuration tool! To configure and set up your devices, use the free HouseLinc software provided by Insteon or link the devices manually.

Every Insteon device type is uniquely identified by its Insteon product key, a six digit hex number. For some of the older device types (in particular the SwitchLinc switches and dimmers), Insteon does not give a product key, so an arbitrary fake one of the format Fxx.xx.xx (or Xxx.xx.xx for X10 devices) is assigned by the binding.

Finally, each Insteon device comes with a hard-coded Insteon address that can be found on a label on the device. This address should be recorded for every device in the network, as it is a mandatory part of the binding configuration string. X10 devices are addressed with houseCode.unitCode, e.g. A.2.

The following devices have been tested and should work out of the box:

Before Insteon devices communicate with one another, they must be linked. During the linking process, one of the devices will be the "Controller", the other the "Responder" (see e.g. the SwitchLinc Instructions).

The responder listens to messages from the controller, and reacts to them. Note that except for the case of a motion detector (which is just a controller to the modem), the modem controls the device (e.g. send on/off messages to it), and the device controls the modem (so the modem learns about the switch being toggled). For this reason, most devices and in particular switches/dimmers should be linked twice, with one taking the role of controller during the first linking, and the other acting as controller during the second linking process. To do so, first press and hold the "Set" button on the modem until the light starts blinking. Then press and hold the "Set" button on the remote device, e.g. the light switch, until it double beeps (the light on the modem should go off as well). Now do exactly the reverse: press and hold the "Set" button on the remote device until its light starts blinking, then press and hold the "Set" button on the modem until it double beeps, and the light of the remote device (switch) goes off. Done.

The binding does not support linking new devices on the fly, i.e. all devices must be linked with the modem before starting the InsteonPLM binding. Each device has an Insteon address of the format 'xx.xx.xx' which can usually be found on a label on the device.

1. Copy the binding (e.g. openhab.binding.insteonplm-<version>.jar into the openhab/addons folder
2. Edit the relevant section in the openhab configuration file (openhab/configurations/openhab.cfg). Note that while multiple modems and/or hubs can be configured, the binding has never been tested for more than one port!
3. Add configuration information to the .items file (see below)
4. Optional: configure for debug logging into a separate file (see trouble shooting section)

Since Insteon devices can have multiple features (for instance a switchable relay and a contact sensor) under a single Insteon address, an openHAB item is not bound to a device, but to a given feature of a device:

insteonplm="<insteon_address>:<product_key>#feature[,<parameter>=value, ...]>"

The following lines in your insteonplm.items file would configure a light switch, a dimmer, a motion sensor, and a garage door opener with contact sensor, a front door lock, a button of a mini remote, a KeypadLinc 2487, and a 6-button keypad dimmer 2334-232:

Switch officeLight "office light" {insteonplm="24.02.dc:F00.00.02#switch"}
Dimmer kitchenChandelier "kitchen chandelier" {insteonplm="20.c4.43:F00.00.01#dimmer"}
Contact garageMotionSensor "motion sensor [MAP(contact.map):%s]" insteonplm="27.8c.c3:0x00004A#contact"}
Switch garageDoorOpener "garage door opener" <garagedoor> {insteonplm="28.c3.f1:0x00001A#switch"}
Contact garageDoorContact "garage door contact [MAP(contact.map):%s]"    {insteonplm="28.c3.f1:0x00001A#contact"}
Switch frontDoorLock "Front Door [MAP(lock.map):%s]" {insteonplm="xx.xx.xx:F00.00.09#switch"}
Switch miniRemoteContactButton1	    "mini remote button 1" insteonplm="2e.7c.9a:F00.00.02#buttonA"}
Switch keypadSwitch    "main load" {insteonplm="xx.xx.xx:F00.00.14#loadswitch"}
Switch keypadSwitchButtonA   "keypad switch button A"	{insteonplm="xx.xx.xx:F00.00.14#keypadbuttonA,group=2"}
Dimmer keypadDimmer "dimmer" {insteonplm="xx.xx.xx:F00.00.15#loaddimmer"}
Switch keypadDimmerButtonA    "keypad dimmer button A"	{insteonplm="xx.xx.xx:F00.00.15#keypadbuttonA,group=2"}
Dimmer dimmerWithMax "dimmer 2"   {insteonplm="xx.xx.xx:F00.00.11#dimmer,dimmermax=70"}

For the meaning of the group parameter, please see notes on groups and keypad buttons below. Note the use of a MAP(contact.map), which should go into the transforms directory and look like this:

OPEN=open
CLOSED=closed
-=unknown

'MAP(lock.map)`, which should go into the transforms directory and look like this:

ON=Lock
OFF=Unlock
-=unknown

If you have a garage door opener, see the I/O Linc documentation for the meaning of the momentary keyword (not supported/needed for other devices).

Dimmers can be configured with a maximum level when turning a device on or setting a percentage level. If a maximum level is configured, openHAB will never set the level of the dimmer above the level specified. The below example sets a maximum level of 70% for dim 1 and 60% for dim 2:

Dimmer d1 "dim 1" {insteonplm="xx.xx.xx:F00.00.11#dimmer,dimmermax=70"}
Dimmer d2 "dim 2" {insteonplm="xx.xx.xx:F00.00.15#loaddimmer,dimmermax=60"}

Setting a maximum level does not affect manual turning on or dimming a switch.

The iMeter Solo reports both wattage and kilowatt hours, and is updated during the normal polling process of the devices. You can also manually update the current values from the device and reset the device. See the example below:

Number iMeterWatts   "iMeter [%d watts]"  {insteonplm="xx.xx.xx:F00.00.17#meter,field=watts"}
Number iMeterKwh     "iMeter [%.04f kwh]" {insteonplm="xx.xx.xx:F00.00.17#meter,field=kwh"}
Switch iMeterUpdate  "iMeter Update"      {insteonplm="xx.xx.xx:F00.00.17#meter,cmd=update"}
Switch iMeterReset   "iMeter Reset"       {insteonplm="xx.xx.xx:F00.00.17#meter,cmd=reset"}

Here are some examples for configuring X10 devices. Note that X10 switches/dimmers send no status updates, i.e. openHAB will not learn about switches that are toggled manually.

Switch x10Switch	"X10 switch" {insteonplm="A.1:X00.00.01#switch"}
Dimmer x10Dimmer	"X10 dimmer" {insteonplm="A.5:X00.00.02#dimmer"}
Contact x10Motion	"X10 motion" {insteonplm="A.3:X00.00.03#contact"}

When a button is pressed on a keypad button, a broadcast message is sent out on the Insteon network to all members of a pre-configured group. Let's say you press the keypad button A on a 2487S, it will send out a message to group 3. You first need to configure your modem to be a responder to that group. That can be simply done by pressing the keypad button and then holding the set button (for details see instructions), just as for any Insteon device. After this step, the binding will be notified whenever you press a keypad button, and you can configure a Switch item that will reflect its state. However, if the switch is flipped from within openHAB, the keypad button will not update its state. For that, include the keypad button into an Insteon group using the HouseLinc software, such that the keypad button responds to modem broadcast messages on e.g modem group 2. Then add the parameter group=2 to the binding config string (see example above). Now toggling the switch item will send out a broadcast message to group 2, which should flip the switch. You need to configure each button into a different modem group to switch them separately.

To get additional debugging information, insert the following into your logback.xml file:

<appender name="INSTEONPLMFILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/insteonplm.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/insteonplm-%d{yyyy-ww}.log.zip</fileNamePattern>
    <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{30}[:%line]- %msg%n%ex{5}</pattern>
    </encoder>
</appender>
<!-- Change DEBUG->TRACE for even more detailed logging -->
<logger name="org.openhab.binding.insteonplm" level="DEBUG" additivity="false">
<appender-ref ref="INSTEONPLMFILE" />
</logger>

This will log additional debugging messages to a separate file in the log directory.

Device types are defined in the file device_types.xml, which is inside the InsteonPLM bundle and thus not visible to the user. You can however load your own device_types.xml by referencing it in the openhab.cfg file like so:

insteonplm:more_devices=/usr/local/openhab/rt/my_own_devices.xml

Where the my_own_devices.xml file defines a new device like this:

<xml>
 <device productKey="F00.00.XX">
  <model>2456-D3</model>
  <description>LampLinc V2</description>
  <feature name="dimmer">GenericDimmer</feature>
  <feature name="lastheardfrom">GenericLastTime</feature>
 </device>
</xml>

Finding the Insteon product key can be tricky since Insteon has not updated the product key table (http://www.insteon.com/pdf/insteon_devcats_and_product_keys_20081008.pdf) since 2008. If a web search does not turn up the product key, make one up, starting with "F", like: F00.00.99. Avoid duplicate keys by finding the highest fake product key in the device_types.xml file, and incrementing by one.

If you can't can't build a new device out of the existing device features (for a complete list see device_features.xml) you can add new features by specifying a file (let's call it my_own_features.xml) with the "more_devices" option in the openhab.cfg file:

insteonplm:more_features=/usr/local/openhab/rt/my_own_features.xml

In this file you can define your own features (or even overwrite an existing feature). In the example below a new feature "MyFeature" is defined, which can then be referenced from the device_types.xml file (or from my_own_devices.xml):

<xml>
 <feature name="MyFeature">
 <message-dispatcher>DefaultDispatcher</message-dispatcher>
 <message-handler cmd="0x03">NoOpMsgHandler</message-handler>
 <message-handler cmd="0x06">NoOpMsgHandler</message-handler>
 <message-handler cmd="0x11">NoOpMsgHandler</message-handler>
 <message-handler cmd="0x13">NoOpMsgHandler</message-handler>
 <message-handler cmd="0x19">LightStateSwitchHandler</message-handler>
 <command-handler command="OnOffType">IOLincOnOffCommandHandler</command-handler>
 <poll-handler>DefaultPollHandler</poll-handler>
 </feature>
</xml>

If you cannot cobble together a suitable device feature out of existing handlers you will have to define new ones by editing the corresponding Java classes in the source tree (see below).

If all else fails there are the Java sources, in particular the classes MessageHandler.java (what to do with messages coming in from the Insteon network), PollHandler.java (how to form outbound messages for device polling), and CommandHandler.java (how to translate openhab commands to Insteon network messages). To that end you'll need to become a bonafide openHAB developer, and set up an openHAB Eclipse build environment, following the online instructions.

1. Devices cannot be linked to the modem while the binding is running. If new devices are linked, the binding must be restarted.
2. Setting up Insteon groups and linking devices cannot be done from within openHAB. Use HouseLinc for that.
3. Very rarely during binding startup, a message arrives at the modem while the initial read of the modem database happens. Somehow the modem then stops sending the remaining link records and the binding no longer is able to address the missing devices. The fix is to simply restart the binding.