Universal Devices ISY994i Driver

This driver communicates with the ISY994i series of interfaces from Universal Devices. The ISY keeps the driver informed of changes in status of the Insteon network and removes the need to track device ID's by allowing the driver to send commands to Insteon modules by name. The Insteon network, with all of its links, is built with the ISY itself. The devices you want to control from the driver are entered into the driver configuration.

Revision History
1.0: The original release of the driver
1.01: Fixes a bug that can cause the driver to fail reading the configuration

1.1: Adds toggle and fast toggle commands, adds variables that match ISY integers for display on RTI panels, fixes the double click off event

1.11: Fixes the default Dim Down command (was dimming up) and fixed a problem where changes in unconfigured variables could cause the driver to miss some legit messages.

Connecting to the ISY994i

The ISY can be discovered by the driver automatically so no particular network setup is required; the ISY can remain on DHCP. While this process is very reliable, it is not very fast. It is possible to put an IP address for the device into the configuration to save the time it takes for the interface to be located. When the driver begins communicating with the interface it will fill in the 'Current IP' variable.

Configuring the Driver

Besides the Connection Settings, the User ID and Password for the device need to be entered into the configuration so the driver can send authenticated commands to the ISY.

Device Types

Most devices in the network have an on/off state as well as a concept of a 'level', and it would be possible to do almost all the work of the driver treating all the devices the same. Different devices use these commands in their own way and/or expand on it to fit their need however. Because of this the driver expands the simple on, off and set commands into different sets of commands and variables for different device types:

Names

Because the driver locates devices by name you must enter the full name of the device, as it is in the ISY Administrative Console, into the driver configuration. The driver makes these names available as variables but also makes a 'Short Name' available. The short name is just the last word (all characters after the last white space) in the long name. This allows you to name something 'Basement Theater Sconces" for example, and have it show up as 'Sconces' on the panel.

LIGHTS:

NOTE: The 6 (or 8) button switches should be considered to be 5 (or 7) distinct lights as each button has its own state and level. The light portion of any FanLinc should also be entered into the Light section.

Lights are the simplest devices to configure and operate, simply enter the name given to the device in the ISY software and its variables and commands will show up in ID. Besides their name, light devices have a state variable and a level variable. Dimmers will have a value between 0 and 255 while switches and other non-dimmer devices will have levels of ONLY 0 or 255.

Commands that can be sent to lights include standard on and off commands that will use the devices ramp time to change levels (the ramp time can be set in the ISY interface), and fast on and fast off commands to immediately switch the device to its new level, regardless of the ramp time programmed into the device. These commands include a level parameter which can take a value between 0 and 255 to allow a dimmable device to take an intermediate value. Off commands need the parameter as well but the value makes no difference.

In addition there are two ways to gradually change the light value: The Brighten and Dim commands increase or decrease the level by 1/32 of the full value each time it is sent allowing a gradual fade that is easy to get to fractional levels by sending a certain number of commands. These commands should be sent with a fairly low repeat rate, no less than 300-400 ms so the light can keep up. Sending these commands in succession is normally visible as slight jumps in light brightness. The other method is smoother to the eye but harder to reach a precise level. The Manual Brighten and Dim commands begin to ramp the lamp value when first sent and need the value repeated at least every 300 ms (the driver defaults to 200, there’s no need to change it). Once the repeating stops, caused by releasing the button, the driver sends the command to stop the changing value of the light. Speeding up the repeat WILL NOT increase the speed of the ramping, nor will lowering it.

There are a large number of driver events attached to lights as well. Besides on and off for the light loads there are events for the operation of the switches themselves, regardless of the current value of the load. On and off presses of the switch will send an On Cmd event, double clicks and a press and hold have their own distinct events allowing each button to have alternate behaviors. Finally a command is available on the release of a press and hold, although the ISY does not report whether the release is from and up or down fade.

As an example, if a light (a 2477 Dimmer) is on with a 255 level and the off button is pressed and released the light will turn off and both a Off event for the load and an ‘Off Cmd’ event will be received. If the bottom switch was double clicked you would still get the Off event but that would come with a Off Double Click event instead. If the light is off you will no longer get the Off event but you will continue to get events for any presses of the off side of the switch.

SCENES/GROUPS

Scenes in the ISY Administrative Console use the Insteon grouping feature to create a set of devices with specific levels and states that can be set with a single command. The values are sent to these devices when the scene is triggered but there is no scene 'state' per se, the scenes are not tracked to see if the devices are at matching levels or states Scenes can also be turned off. Turning a scene off will tell all the devices linked to that scene to turn themselves off. When scenes are triggered the driver will update the state and values of all the devices in the scene, but there are no variables for scenes except the names.

Scenes have also have commands for fast on and off. Sending a fast on command to a scene will not only ignore the ramp rates of the devices but will also ignore the programmed on levels in those scenes. It will turn all the loads in the scenes on immediately to their maximum level.

FANS

A FanLinc is essentially two devices in one case. The light half of the interface should be entered into the light section of the ISY interface and treated as a light. The fan half works very similarly and, while it too could be entered as a light, it gets is own section in the driver more suited to its function. Fans have an on and off function similar to lights except that the level value is limited to 0 to 3. An additional command speeds up the fan level by one every time it’s set, optionally wrapping around to 0 (off). When the ‘Fan Up’ command is sent the driver waits approximately a second and a half to send the command allowing the command to be sent a couple of times without sending the command every time. The variables provided for fans are the same as lights, once again except that the level range is 0-3 rather than 0-255. Fan events are limited to on and off.

SENSORS

There are a large number of Insteon devices that operate merely as sensors, taking a boolean on or off as their only values. To make integrating these devices easier there are two variables available for each sensor: it’s standard value and another one which is always it’s opposite. There are no commands for sensors as they are generally output only devices but there are two sets of events. One is triggered when the current state of the sensor changes and the other on subsequent triggers that may or may not change the state of the device. Motion sensors are an example of this. A motion sensor will change state when it detects motion and change it's state variables. This will trigger both sets of events, the 'On State' event as well as the 'On Trigger' event. After 5 minutes (the default in the sensor) the state will change to the off state again triggering the other two events. The motion sensor will continue to track during it's on time however, and any additional triggers will send a trigger event, but not a state event.

THERMOSTATS

When a thermostat is added to the Insteon network by the ISY software (the Administrative Console) it appears three times: a Main device and Heat and Cool Ctl devices. When adding a thermostat to the driver configuration you only use the part of the name you entered when linking the thermostat. For example, if the you entered ‘Bedroom’ as the device name you’d end up with Bedroom- Main, Bedroom- Cool Ctl and Bedroom- Heat Ctl in your device list. In the thermostat section of the driver configuration you’d simply enter ‘Bedroom’

The driver allows you to display heat and cool setpoints as well as current temperature and humidity. Temperature is reported by the thermostat with .5 degree precision. Fahrenheit users that don’t want to see the decimal points can use ID to have the button with the variable to not show any digits after the decimal point. This is done by right clicking on the button, selecting ‘Edit Text…’ and then selecting the {var}. When the Edit Variable Dialog opens select Fixed-Point Number and make sure the format is set to 1 rather than 1.4

You adjust the setpoints either directly with the ‘Set’ setpoint commands or by incrementing or decrementing them with the ‘Up’ and ‘Down’ commands. The up and down commands can be set to change the point by any amount using the step size parameter. The steps are actually half degrees so to increment a full degree you would set the step size to 2.

Events happen for thermostats when the mode changes or the current state (Heating, Cooling, Off) changes

VARIABLES

The ISY interface allows the creation of variables that can be changed as part of the ISY scrupting system. The names of these variables can be entered into the driver configuration to allow the creation of variables that will allow these to be displayed on RTI panels