Insteon Thermostat HomeSeer Plug-in

Release notes and Legal notices

Insteon Thermostat Support Forum

Overview

This plug-in adds support for Thermostats compatible with the Insteon protocol.  It allows HomeSeer to be configured to connect to these thermostats, receive real-time status updates, send thermostat control commands and establishes the necessary HomeSeer devices, triggers and actions to be used in events for more complex control.

System Requirements

Insteon Thermostat

Smarthome 2441TH

Smarthome wired Insteon thermostat

Smarthome 2441ZTH

Smarthome wireless Insteon thermostat

Venstar/Totaline Insteon Adapter 2441V

Smarthome Insteon adapter for Venstar/Totaline compatible thermostats

This plug-in was developed and tested with 2441TH/2441ZTH (firmware D) and 2441V (firmware 95)


HomeSeer Components

HomeSeer 3

3.0.0.96

Insteon Plugin by Mark Sandler

3.0.4.2 or newer


Plug-in Web-Based Help

Access to this HTML help from the running HS system is available via the plug-in menus.

PLUG-INS -> Insteon Thermostat -> Insteon Thermostat Help

Web-Based Help Navigate


Plug-in Web-Based Configuration

This section details the plug-in configuration options. Access the plug-in configuration via the menus.

PLUG-INS -> Insteon Thermostat -> Insteon Thermostat Config

Web-Based Config Navigate

 

This will present a tabbed layout with various configuration options. NOTE! Don't forget to save after making changes on any of the configuration tabs. Changes are not completed and applied until SAVE is used.

Plugin changes are saved to the hspi_insteon_thermostat.ini file which can be found in HS3 Installation directory / Config / hspi_insteon_thermostat.ini

Config General Tab

TabSectionItemDescription
GeneralGeneralLog Debug Information Add additional debug level logging to the HS3 log and to the plug-ins own debug log file which is found in the HS3 install directory under \Logs\InsteonThermostatDebug.log. This setting is useful if there are any issues using the plugin. If there are no issues, it is suggested to leave this off.
GeneralGeneralInsteon FlagsThis field controls the max number of hops defined in the Insteon commands issued. Generally leave this set to F
GeneralBoundsLow/High for Temp, Heat SetPoint, Cool SetPoint, Humidity

These are values used within the plugin for sanity checks and to control the range of values found on the setpoint dropdowns on the status page. It may be necessary to adjust the bounds values depending on if the thermostat is using Fahrenheit or Celsius.

GeneralControl PageAuto-Refresh How often to refresh the plus-ins own status webpage, in seconds.
GeneralInformationalallGenerally useful information like the plug-in version and PLM address

Don't forget to SAVE!

 

The next tab is for configuring thermostats. Do not configure a thermostat within the HS Insteon plugin itself. All Insteon Thermostats will be added via this plugin on the Thermostats tab.

Config Thermostats Tab

Checkbox
TabSectionItemDescription
ThermostatsNameADD NEWThis is the only option when first configuring the plug-in. Click the ADD NEW text box and provide a unique name for the thermostat. Once named, this cannot be changed without deleting the thermostat and using ADD NEW again. The plug-in supports multiple thermostats so use ADD NEW for each one.
ThermostatsNameName
[devcat,firmware,protocol]
This field shows the unique name given to the thermostat. This cannot be changed after creating it. Below the name is a bracketed box. Once successful communication with the thermostat has been established, this box should change from [???,FFFFFFFF,] to something much more useful like [050A,D,2] See descriptions below.
ThermostatsNameDevice Category ("devcat") This is the first of the three comma separated values. If ??? is present, then communication with the thermostat is not yet established. A series of numbers/letters should be shown like 0503 or 050A. These correspond to the thermostat hardware and are reported back from the thermostat itself. The known values are shown below. If any other values are reported please post in the support forum.
  • 050B = SmartHome 2441TH wired Insteon Thermostat
  • 050A = SmartHome 2441ZTH wireless Insteon Thermostat (US)
  • 0511 = SmartHome 2441ZTH wireless Insteon Thermostat (EU)
  • 0512 = SmartHome 2441ZTH wireless Insteon Thermostat (AUS/NZ)
  • 0503 = SmartHome 2441V Insteon Adaptor
  • 050E = Venstar 2491T1E or 2491T7E with integrated Insteon (no separate adaptor)
ThermostatsNameFirmware Version This is the second of the comma separated values. This shows the firmware version as reported by the thermostat hardware. There are some reports that certain firmware versions can incorrectly identify which Insteon engine to use. This value along with the "force protocol 2" option may help resolve issues on thermostats with older firmware that should be using protocol 2 not 1.
ThermostatsNameInsteon Protocol Version This is the third of the comma separated values. This shows which Insteon protocol is being used. If it shows in red then "force protocol 2" has been set.
ThermostatsLocationText field to enter the locationCorresponds to the floor as shown on the HS Home devices page
ThermostatsInsteon AddressThree text fields to enter the Insteon address.All three must be populated. Taken together they form the Insteon address of the thermostat.
ThermostatsHas Humidistat?CheckboxDoes this thermostat have a humidity sensor built-in? If so, check this box.
ThermostatsHas External Sensor?CheckboxDoes this thermostat have an external temperature sensor? If so, check this box.
ThermostatsForce Protocol 2Checkbox Normally this is not necessary and should be left unchecked. If checked, this tells the plug-in to use extended Insteon commands as necessary and ignore the protocol reported from the thermostat itself. See the firmware description.
ThermostatsHVAC Unit Dropdown list of defined HVAC units This is where a HVAC unit can be associated to a thermostat. HVAC units have to be defined first. See HVAC tab config topic.
ThermostatsActionsCommand buttons
  • Delete = Delete this thermostat and all associated thermostat HS devices. This does not affect HVAC units that may be associated to this thermostat.
  • Register Thermostat with Insteon Plugin = After adding a new thermostat and entering the Insteon Address, use this to establish communication to it via Mark's Insteon plugin
  • Read Links = Read the Insteon links database from the Thermostat and report to the log file. Generally only used for debugging.
  • Update Links = (Re)Issue link commands to connect the PLM to the Thermostat. Generally not needed. May be useful for debugging.

Don't forget to SAVE!

 

The next tab is for configuring HVAC unit(s) which create a virtual representation in the plug-in to keep incrementing counters of the heat and cool times and a decrementing counter toward the next maintenance interval (when it reaches 0).

Config HVAC Tab

TabSectionItemDescription
HVAC UnitsNameADD NEWThis is the only option when first configuring the plug-in. Click the ADD NEW text box and provide a unique name for the HVAC unit. Once named, this cannot be changed without deleting the HVAC unit and using ADD NEW again. The plug-in supports multiple HVAC units so use ADD NEW for each one.
HVAC UnitsNameNameThe unique name of the HVAC unit
HVAC UnitsLocationText field to enter the locationCorresponds to the floor as shown on the HS Home devices page
HVAC UnitsMaintenance Interval (Hours)Text field to enter hoursThis represents the total hours between maintenance intervals for the HVAC unit. It is used when resetting the countdown timer on the HVAC maintenance device.
HVAC UnitsActionsCommand buttons
  • Delete = Delete this HVAC unit and all associated HVAC unit HS devices. This does not affect thermostats that may be associated to this HVAC unit.

Don't forget to SAVE!

 

The next tab is for configuring virtual PROGRAMS within the plug-in. These are NOT programs that run on the thermostat hardware! These become virtual HS devices that can be set to control the mode, fan and heat/cool setpoints based on HS events. See the Master Program device below for an example.

Config HVAC Tab

TabSectionItemDescription
ProgramsProgram NameADD NEW This is the only option when first configuring the plug-in. Click the ADD NEW text box and provide a name for the Program. Program names CAN be changed and they CAN be non-unique (i.e. duplicate names) The combination of the Program Name and the associated Thermostat (or Default) should resolve to a single unique value.
ProgramsProgram NameText box for nameThe name of the program. It can be changed and can be non-unique
ProgramsThermostatDefault or a specific thermostat to associate to Default means this program can apply to any thermostat that doesn't have another version of this same named program applied to it already. See the Master Program device for an example.
ProgramsHeatText field for heat setpointThis is an optional field. If set and if the thermostat mode already in use or specified by the program allows the heat setpoint to be changed, then this heat setpoint will be applied.
ProgramsCoolText field for cool setpointThis is an optional field. If set and if the thermostat mode already in use or specified by the program allows the cool setpoint to be changed, then this cool setpoint will be applied.
ProgramsModeDrop down list to set the modeThis is an optional field. The default is "Don't Set" If set, the thermostat mode will be changed to this when the program is run.
ProgramsFanDrop down list to set the fanThis is an optional field. The default is "Don't Set" If set, the thermostat fan will be changed to this when the program is run.
ProgramsActionsCommand buttons
  • Delete = Delete this Program and remove it from the Master program device and all thermostat programs virtual devices.

Don't forget to SAVE!

HomeSeer Devices

Once the plugin has been configured and saved, a set of HomeSeer devices will be created. These are critical to the correct functioning of the plug-in so do not remove them.

Master Program Device

Master Program Device

The first device created is the Master Program device. This is a pseudo-parent to all the other devices created by the plug-in. This device has the full list of all defined program names. Recall that program names could be duplicated. This list is only the unique set of all the names. Using the drop down list to select a program on this device will attempt to set that program on each configured thermostat. It does this by first looking for a specific match of the program name and thermostat name pair. If it finds that it uses it and moves on to the next thermostat. If it doesn't find that pairing, it will then look to see if the selected program name has a "Default" for the thermostat name and if so it will use that. If neither matches then it will skip that thermostat.

Example: A house has three levels (basement, main, upper) and a thermostat on each. The programs for summer are shown in the table below and would be configured on the Programs tab as described previously.

ProgramThermostatHeatCoolModeFan
Summer DayDefault81CoolAuto
Summer DayMain75CoolOn
Summer NightDefault 84 CoolAuto
Summer NightUpper79CoolAuto
Summer MorningMain77CoolOn

The dropdown control for the Master Program device would contain: None, Summer Day, Summer Morning, Summer Night

Here is a sample running of these programs using only the Master Program device triggered by a timed HS event to set the program. Notice how Summer Morning only has a specific match defined, the other thermostats are skipped when this program is set on the Master Program device. Then note how the Default match is used in the Summer Day and Summer Night programs.

Time Master Program device set to Basement Thermostat is set toMain Thermostat is set toUpper Thermostat is set to
05:00 Summer Morning Skipped Main = 77,Cool,On Skipped
07:00 Summer Day Default = 81,Cool,Auto Main = 75,Cool,On Default = 81,Cool,Auto
18:00 Summer Night Default = 84,Cool,Auto Default = 84,Cool,Auto Upper = 79,Cool,Auto

Thermostat Devices

Each configured thermostat has a set of devices to represent thermostat state as well as provide control.

Thermostat Devices

DeviceThermostat APIDescriptionControls
Program DeviceTypeInfo.eDeviceType_Thermostat.Root The program device is similar in concept to the Master Program device described previously except that it applies only to the single thermostat it is defined for. The program device is designated as the Root Parent for all the other devices of a thermostat. This causes them to group together nicely in the Home Device List page of HS. It also means that if the program device is deleted, all the thermostat child devices will also be deleted by HS. Dropdown list of unique programs for this thermostat, or None
CoolDeviceTypeInfo.eDeviceType_Thermostat.Setpoint
DeviceTypeInfo.eDeviceSubType_Setpoint.Cooling_1
This device shows the cool set point for this thermostat. + / - buttons to adjust the setpoint by 1 degree. See Script API, status page or events for alternate setpoint control
HeatDeviceTypeInfo.eDeviceType_Thermostat.Setpoint
DeviceTypeInfo.eDeviceSubType_Setpoint.Heating_1
This device shows the heat set point for this thermostat. + / - buttons to adjust the setpoint by 1 degree. See Script API, status page or events for alternate setpoint control
FanDeviceTypeInfo.eDeviceType_Thermostat.Fan_Mode_Set This device shows the state of the thermostat fan Buttons to change the fan state to Auto, On or Toggle between them
Run/HoldDeviceTypeInfo.eDeviceType_Thermostat.Hold_Mode This device shows the logical run/hold state of this thermostat relative to the programs defined in the plug-in. It is not the thermostat hardware run/hold state. Setting this to Hold will prevent a defined program from running on this thermostat and a log message to be generated. Setting this back to run will reenable the plug-in's programs for this thermostat. Buttons to change the run/hold state to Run, Hold or Toggle between them.
ModeDeviceTypeInfo.eDeviceType_Thermostat.Mode_Set This device shows the mode that the thermostat hardware is set to. The mode is critically important to being able to adjust the heat and cool setpoints. For example, if the thermostat is in Cool mode, it will not take changes to the heat setpoint. An easy way around this is to use Auto mode which allows both heat and cool setpoints to be made. Buttons to change the mode to a valid option for the thermostat. Common modes for all thermostats are: Off, Heat, Cool, Auto, Program. The Venstar thermostats via the 2441V Insteon Adapter also support Program-Heat and Program-Cool modes which activate those program modes as stored on the thermostat hardware. It is beyond the scope of this plug-in to describe Program-Heat or Program-Cool.
TempDeviceTypeInfo.eDeviceType_Thermostat.Temperature This device shows the thermostat temperature sensor reading. There are no controls for this device.
External TempDeviceTypeInfo.eDeviceType_Thermostat.Additional_Temperature If the thermostat has an external temperature sensor and if it was configured on the thermostats tab, then this device will be created to represent it. There are no controls for this device.
Humidity

This is set to PluginAPI, not ThermostatAPI as at the time of development there wasn't a humidity device type to use.

DeviceTypeInfo.eDeviceType_Thermostat.Operating_State

If the thermostat has a humidity sensor and if it was configured on the thermostats tab, then this device will be created to represent it. There are no controls for this device.

HVAC Devices

Each configured HVAC unit has a set of devices to represent the logical counters for the HVAC and controls to reset those counters.

Thermostat Devices

Device Plug_In API (pseudo Thermostat API) DescriptionControls
Mode DeviceTypeInfo.eDeviceAPI.Plug_In
DeviceTypeInfo.eDeviceType_Thermostat.Mode_Set

The mode device for the HVAC shows the mode being called for by the associated thermostat. The mode device also serves as the Root Parent for all the other devices of a HVAC. This causes them to group together nicely in the Home Device List page of HS. It also means that if the mode device is deleted, all the HVAC child devices will also be deleted by HS.

There are no controls for this device.
FanDeviceTypeInfo.eDeviceAPI.Plug_In
DeviceTypeInfo.eDeviceType_Thermostat.Fan_Status
The mode device for the HVAC shows the fan state being called for by the associated thermostat There are no controls for this device.
Cool DeviceTypeInfo.eDeviceAPI.Plug_In
DeviceTypeInfo.eDeviceType_Thermostat.RunTime
DeviceTypeInfo.eDeviceSubType_Setpoint.Cooling_1
This device shows an incrementing counter to display how long all thermostats associated to this HVAC unit have been calling for cool. The counter starts when the first thermostat calls for cool and will stop once the last thermostat stops calling for cool. Reset - this will reset the counter to 00:00
HeatDeviceTypeInfo.eDeviceAPI.Plug_In
DeviceTypeInfo.eDeviceType_Thermostat.RunTime
DeviceTypeInfo.eDeviceSubType_Setpoint.Heating_1
This device shows an incrementing counter to display how long all thermostats associated to this HVAC unit have been calling for heat. The counter starts when the first thermostat calls for heat and will stop once the last thermostat stops calling for heat. Reset - this will reset the counter to 00:00
Maintenance

DeviceTypeInfo.eDeviceAPI.Plug_In
DeviceTypeInfo.eDeviceType_Thermostat.Filter_Remind

This device shows a decrementing counter. It starts using the maintenance hours as configured on the HVAC tab of the config page. If the reset button is pushed, those same hours are again used to calculate the reset value. Note that this shows as a DotNet timespan so it is read as DAYS.HOURS:MINUTES (days dot hours colon minutes) This will reset the maintenance count down timer back to the original value as calculated using the maintenance hours from the HVAC tab of the config page.

Plug-in Web-Based Status / Control Page

This section details the plug-in web status and control page. Access the plug-in web stage page via the menus.

PLUG-INS -> Insteon Thermostat -> Insteon Thermostat Status

Web-Based Status Control Page Navigate

This page is a plug-in generated view of the thermostat(s). It shows each one in its own tab. It provides controls to change the state of the thermostat devices and thus the thermostat itself. It shows the associated HVAC unit information (if any) and controls to reset the HVAC counters if desired. The Master Program device is represented on each thermostat tab.

This page allows more arbitrary setpoint control so it is good to use this when experimenting with different temperature settings. Instead of +/- 1 on the HS devices page, it is possible to jump directly to any setpoint. Note that the bounds settings from the config page control the min/max that can be shown on the setpoint dropdown controls. Also note that rudimentary sanity checking is done to make sure heat can't be set higher than cool or cool set lower than heat to avoid sending conflicting settings to the thermostat.

Recall from above that the Run/Hold control is the logical run/hold relative to the plug-in provided programs. It is not the run/hold on the thermostat hardware.

This page is refreshed every X seconds as determined from the general tab on the config page. When making changes, wait for the page refresh in between to let the commands be issued to the thermostat and the replies received back by the plugin and then shown on the next page refresh. The page refresh can be set to a faster (lower) value but any faster than 8-10 seconds may miss the status updates from the thermostat. The default setting of 20 seconds appears to be a good value to use. Make a change, wait for the refresh to take and the change to appear. Then make another change if needed. If faster status / change reporting is needed, using the Home Device List screen where changes appear as fast as the plug-in receives them.

Web-Based Status Control Page

 

Script API

The plugin supports a rich set of script API calls that allow scripts to perform all the same device controls that can be done via the HS Devices or the web status page. This script API endeavors to maintain compatibility with the SAGE plugin for HS2 script API. Minor changes may be necessary but the core functionality is there. The fastest way to get started using the Script API is to look in the under the HS3 installation directory / scripts / InsteonThermostat_script_api.vb This is an example script showing how to get a handle to the plugin and then an example of each call.

Dim pluginName As String = "Insteon Thermostat"
Dim Instance As String = ""
Dim plugin As Object = New HomeSeerAPI.PluginAccess(hs, pluginName, Instance)

Script API Call API Call Parameters Description
GetMasterProgram   Get the value of the plug-in Master Program device (this is not thermostat specific so no argument is needed)
SetMaster Program None or programName Set the value of the plug-in Master Program device to None or a valid programName
     
GetProgram thermostatName Get the value of the thermostat program device
GetHold thermostatName Get the value of the thermostat logical run/hold device
GetMode thermostatName Get the value of the thermostat mode device
GetFan thermostatName Get the value of the thermostat fan device
GetTemp thermostatName Get the value of the thermostat temperature device
GetExtTemp thermostatName Get the value of the thermostat external temperature device
GetHumidity thermostatName Get the value of the thermostat humidity device
GetCoolSetpoint thermostatName Get the value of the thermostat cool setpoint
GetHeatSetpoint thermostatName Get the value of the thermostat heat setpoint
     
SetProgram thermostatName
None or programName
Sets the value of the thermostat program device to None or a valid programName
SetProgramParams thermostatName & " programName" HS2 Sage compatibility function - Similar to SetProgram but the thermostatName and program name form one string passed as input
SetMode thermostatName
Off,Heat,Cool,Auto,Program,Program-Heat, Program-Cool
Sets the thermostat to the given mode
SetModeNext thermostatName Cycles the thermostat to the next mode
SetModePrev thermostatName Cycles the thermostat to the previous mode
SetFanOn thermostatName Set the thermostat fan device to on
SetFanAuto thermostatName Set the thermostat fan device to auto
SetFanToggle thermostatName Cycles the thermostat fan device between on and auto
SetCoolSetpoint thermostatName
"##"
Sets the thermostat cool setpoint to the given number. Sanity checks are applied similar to the web status page.
AdjustCoolSetpoint thermostatName
"##"
Instead of setting to a specific number, adjust (increment/decrement) the cool setpoint by a positive or negative number. For example: "2" or "-2"
SetHeatSetpoint thermostatName
"##"
Sets the thermostat heat setpoint to the given number. Sanity checks are applied similar to the web status page.
AdjustHeatSetpoint thermostatName
"##"
Instead of setting to a specific number, adjust (increment/decrement) the heat setpoint by a positive or negative number. For example: "2" or "-2"
SetTStatSetpoint thermostatName
"heat ##" or "cool ##"
HS2 Sage compatibility function - Similar to SetCoolSetpoint and SetHeatSetpoint except this single function takes cool/heat as an input
SetTempUp thermostatName Increment both the heat and cool setpoints by 1
SetTempDown thermostatName Decrement both the heat and cool setpoints by 1

SetHold

thermostatName Sets the thermostat logical run/hold device to HOLD
SetRun thermostatName Sets the thermostat logical run/hold device to RUN
SetHoldToggle thermostatName Cycles the thermostats logical run/hold device between HOLD and RUN
TstatCallBack

thermostatName & " command"

Valid commands are: Off, Heat, Cool, Auto, Program, Program-Heat, Program-Cool, Mode-Next, Mode-Prev, TempUp, TempDown, Fan-Auto, Fan-On, Fan-Toggle, Hold-Hold, Hold-Run, Hold-Toggle.

HS2 Sage compatibility function - This is an all-in-one call for thermostats to set a specific function. The thermostatName and function are combined together into one string.

     
PollAllStats   Poll for the status of all thermostats
PollStat thermostatName Poll a specific thermostat by name
PollStatByNum "1" (a 1-based index into the list of thermostats) Can be used to poll a specific thermostat using the numeric index as found in the plug-in HS3/Config/hspi_insteon_thermostat.ini
     
GetCoolOnMinutes hvacName Get the number of minutes represented by the HVAC unit cool counter
GetCoolLastReset hvacName Get the date of the last time the HVAC unit cool counter was reset back to 0
GetHeatOnMinutes hvacName Get the number of minutes represented by the HVAC unit heat counter
GetHeatLastReset hvacName Get the date of the last time the HVAC unit heat counter was reset back to 0
GetMaintRemainingMinutes hvacName Get the number of minutes remaining on the HVAC unit maintenance counter before it reaches 0
GetLastMaintReset hvacName Get the date of the last time the HVAC unit maintenance counter was reset back to its calculated maximum value
     
ResetCoolTime hvacName Reset the HVAC unit cool counter to 0
ResetHeatTime hvacName Reset the HVAC unit heat counter to 0
ResetHeatCoolTime hvacName Reset both the HVAC unit cool and heat counters to 0
ResetMaintTime hvacName Reset the HVAC unit maintenance counter back to its calculated maximum value