--- 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 --- {% 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]" (All) {isy="ctrl=29.24.98.1,type=thermostat,cmd=ST"} Number Temperature_Setpoint "Desired Temperature [%.2f °F]" (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" (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" (Locks) {isy="ctrl=ZW004_1,type=lock"} Number BDoorLock_Battery "Back Door Lock Battery [%d]" (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.