---
id: isy
label: Description
title: Description - Bindings
type: binding
description: "This is a openHAB binding for the Universal Devices ISY 994i router and PLM. Universal Devices offers a Java SDK for"
source: https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.isy/README.md
since: 1x
install: manual
---

<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->

{% include base.html %}

## Description

This is a openHAB binding for the Universal Devices ISY 994i router and PLM. Universal Devices offers a Java SDK for
external programs to communicate with the router. Alternatives include an extensive REST API. See details at
https://www.universal-devices.com/isy-developers/.

## Items Configuration with ISY Binding Details

The following settings can be added to the Items definition.

* ctrl - Controller address in the format "x.y.z.w". This can be the address of a ISY Insteon Scene. Insteon addresses use the first three bytes and the last byte identified a particular capability of the device.
* type - This can be used to select device types with special configuration needs.  See the "Device Types" section below.
* cmd - Specific ISY control to send to the ISY router as a command, **ST** is the default if left out
* addr - The Insteon address to monitor for the change. A scene does not report a status change, only the devices in the scene do. Specify the controller of the scene here. Defaults to the controller address if left out

## Device Types

You can specify a specific device type to let the binding know that a device is a special type.  This is done using the "type=" configuation item in the binding.

There are currently 3 types available:

* thermostat - required to perform temperature calculations properly
* lock - locks use the security command instead of the normal off/on commands
* heartbeat - several battery powered sensors send a heartbeat.  This is just a ST (status) with value 255, and it means that the sensor is still alive.  To make rules easier, you can define these as type=heartbeat with an item type of DateTime, and it will update with the current time every time the heartbeat is received.  You can then check the item using a rule to see if the DateTime item is too old.

## OpenHAB Item Examples

        /* Insteon-enabled thermostat.  Note "type=thermostat" to ensure proper temp calculations, and cmd=CLISPH to use the ISY setpoint heat value instead of status */
        Number Temperature_Indoor "Inside [%.2f °F]" <temperature> (All) {isy="ctrl=29.24.98.1,type=thermostat,cmd=ST"}
        Number Temperature_Setpoint		"Desired Temperature [%.2f °F]" <temperature> (All) {isy="ctrl=29.24.98.1,type=thermostat,cmd=CLISPH"}

        /* Regular ISY scene id #12220, but look at device 30.CB.66.1 to get the scene status */
        Switch Light_Hallway2 "Hallway" <switch> (GroundFloor,Lights) {isy="ctrl=12220,addr=30.CB.66.1"}
        /* Regular ISY device, controlled directly (won't update scenes!)
        Switch K_DiningRoom_Light "Dining Room Light" (GroundFloor,Lights) {isy="ctrl=F.C3.7C.1"}

        /* ZWave lock.  Note type=lock (makes it use the security commands necessary). The second (Number) entry watches the BATLVL value, which battery-powered devices use to report battery level in percent */
        Switch BDoorLock "Back Door Lock" <lock> (Locks) {isy="ctrl=ZW004_1,type=lock"}
        Number BDoorLock_Battery "Back Door Lock Battery [%d]" <battery> (Locks,BattLevels) {isy="ctrl=ZW004_1,cmd=BATLVL"}

        /* Insteon FanLinc, set up with a Keypadlinc.  4 scenes - Off, Low, Med, High */
        Switch LR_Fan_Off "LR Fan Off" (ISYScenes) {isy="ctrl=4622,addr=1c.e2.d1.3", autoupdate="false"}
        Switch LR_Fan_Low "LR Fan Low" (ISYScenes) {isy="ctrl=20771,addr=1c.e2.d1.4", autoupdate="false"}
        Switch LR_Fan_Med "LR Fan Med" (ISYScenes) {isy="ctrl=22031,addr=1c.e2.d1.5", autoupdate="false"}
        Switch LR_Fan_High "LR Fan High" (ISYScenes) {isy="ctrl=11187,addr=1c.e2.d1.6", autoupdate="false"}

        /* Insteon water sensor - it has 3 subdevices: 1 = dry, 2 = wet, 4 = heartbeat
           The heartbeat device sends an "ON" (255) ST code as a heartbeat.  With type=heartbeat, the binding
           sends a DateTime value.  You can use a rule to check that DateTime to see if you have received
           a heartbeat recently */
        Contact Water_Heater_Dry "Water Heater Sensor [MAP(watersensor-en.map):%s]" (Sensors) {isy="addr=25.AD.4F.1"}
        DateTime Water_Heater_Heartbeat "Water Heater HB [%1$td.%1$tm.%1$tY %1$tH:%1$tM]" (Sensors) {isy="addr=25.AD.4F.4", type=heartbeat}

The transform file (watersensor-en.map) for the water sensor is:

        CLOSED=Wet
        OPEN=Dry
        undefined=Unknown
        -=Unknown

## ISY Binding Configuration

The following settings configure the ISY binding in the openhab.cfg file.

* isy:refresh=60000 # refresh interval in milliseconds (optional, defaults to 60000 [1 minute])
* isy:upnp=true # if true, use UPNP to communicate with the ISY 994i
* isy:uuid=uuid:%your_uudid% # UUID of the ISY router
* isy:ip=192.168.x.x # the hostname of the ISY router
* isy:port=80 # the port of the ISY router
* isy:user=user # the user of the ISY router
* isy:password=password # the password of the ISY router


## Disclaimer

There is no guarantee for the function of the binding or its correctness. Use at your own risk.

## Development Upgrade Instructions

To build and install the isy binding, you need to first download the Java SDK that corresponds with the firmware version
of your ISY 994i.


1. [Download](https://www.universal-devices.com/isy-developers/.) the latest Java SDK zip file, e.g. ISY-WSDK-4.2.21.zip
1. Unzip it to some local folder
1. Copy the isy_inst.jar file into the org.openhab.binding.isy/lib folder
1. Provided that the API and the file name have not changed, there should not be a need to change the source code. Watch for
   compilation errors and adjust accordingly.


The Lib is pushed with the binding, if you are using a older firmware version than the bundled version you may have issues. The SDK used should work with all newer version. 
