sk WARE HS4 Lyric Thermostat Plug-In for Homeseer Instruction Manual

sk WARE HS4 Lyric Thermostat Plug-In for Homeseer

Product Information

• Version: 4.5
• Release Date: 7/28/2023
• The skWare Lyric Thermostat Plug-In for Homeseer allows you to monitor and control your Lyric Thermostat devices from within Homeseer.

Product Usage Instructions

Installation System Requirements: Please ensure that your system meets the following requirements before installing the plug-in.

• [System Requirement 1]
• [System Requirement 2]
• [System Requirement 3]

Configuration

• Once your account is connected, you can reset your connection from the Settings page. This action will disconnect the plug-in from your Lyric account but will not remove any related HS devices. Reauthorizing your account may be necessary from time to time.
• The Config page allows you to control the plug-in behavior and logging output.

Thermostat Configuration After connecting your account, go to the Thermostat List Page in the plug-in menu to add one or more thermostats for control by Homeseer. Select the location and device you wish to add.

Thermostat Devices Once your thermostats are configured, the Home screen will display the current values of your devices.

Actions This plug-in provides the following Actions that can be included in Events:

• – [Action 1]
• – [Action 2]
• – [Action 3]

Plug-In Functions The plug-in functions include:

• [Function 1]
• [Function 2]
• [Function 3]

Command Processing Known Issues:

1. The Lyric API doesn’t properly report Fan Status, showing it as Off at all times. A response from Honeywell is awaited regarding this issue.
2. If you have created your own Resideo Developer account using spaces or other punctuation in your application, attempts to initiate changes from the plug-in to the thermostat using the Lyric API will fail with a 400 (Bad Request) Device Not Found error.

Support Support for the square Lyric Thermostat Plug-In for Homeseer is provided through the standard Homeseer channels. You can seek support via the Lyric Thermostat Plug-in forum on the Homeseer website. For direct contact, you can email the author at steve@skware.net.

Appendix 1: Files The following files are used by the Plug-In:

• [File 1]
• [File 2]
• [File 3]

Appendix 2: Creating a Resideo Developer Account Follow these steps to create a Resideo Developer Account:

1. The Callback URL must be:<https://skware-oauth-hs.azurewebsites.net/api/OAuthCallback>
2. Get the Key & Secret
3. Add Key & Secret to Plug-In

After changing the Key and Secret, you will be disconnected from your Lyric account. Follow the normal steps to authorize your new Resideo App to connect to your thermostat. Use your Thermostat Account for this step. Once you get the code and provide it to the plug-in, your thermostat should successfully update without any errors.

TERMS & CONDITIONS

Resideo has provided an API for developers and is in control of what capabilities are provided. This means that if Resideo changes their API, work will have to be done on this plug-in to make it compatible, and the type of changes and timing of those changes is outside of my control. Maintenance windows for Resideo’s servers occurs on their schedule as well, which can interrupt the plug-in’s ability to communicate with the servers and control your devices. Your purchase and use of this plug-in is as-is and at your own risk.
Excessive activity on your account may result in your account being suspended, requiring you to call Resideo and get it re-activated. While this plug-in has been designed to minimize the chances of this occurring by implementing preventative measures such as timers and minimum command, update and polling frequencies, these values can be changed by the user. Regardless of the values entered (be they the default, smaller or larger), by activating this plug-in in your Homeseer software, you acknowledge this risk and agree to indemnify and hold harmless the developer of this plug-in, Homeseer Technologies, and any other third party plug-in developers from any damages (including but not limited to financial, time spent, opportunity cost, loss of account privileges, and the inability to remotely control your thermostats or other connected devices).
Lyric™ is a trademark of Resideo Technologies, Inc.

OVERVIEW

The skWare Lyric Thermostat Plug-In for Homeseer provides you with a way to monitor and control your Lyric Thermostat devices from within Homeseer.

INSTALLATION

• This Plug-In is installed using the built-in updater capability of Homeseer. New installations include the binaries and supporting files needed to run the Plug-In, and updates will replace any of those items that have changed.
• Before you set it up, you must have a working account and a functioning Lyric device. If you are running this plug-in from a Linux platform (including the Zee), you may need to update certain dependencies manually, per the instructions posted on the plug-in’s support forum.

SYSTEM REQUIREMENTS

• The skWare Lyric Thermostat Plug-In for Homeseer runs on both Windows and Linux installations of HS3 and has been tested with version 3.0.0.148+. Earlier versions of HS3 should work but have not been specifically checked.
• On Linux, this plug-in requires Mono 4.8.1 or higher. For Windows servers, it must be Vista or newer.
• This plug-in has been developed and tested with both T5 and T10 models (with special thanks to CPTKIRK for access to, and feedback on, the latter), but any Lyric device supported by the Honeywell Connected Home API should work. Please report back via the Homeseer forums if you have success or problems with any specific model.

CONFIGURATION

• After installing the plug-in, a new “Lyric Thermostat” menu item can be found under “Plug-Ins” menu in the Homeseer browser interface. The “Configuration” item will take you to the configuration page, where you are able to define your devices and setup additional options for the plug-in.
• The first step is to accept the plug-in Terms & Conditions (see above) and connect to your account. The plug-in has a built-in API Key and Secret, but some users have reported “429 Too Many Requests” errors from Resideo, which may be linked to the number of plug-in users on that key without Resideo increasing the limits. Unfortunately, they are unresponsive to requests to increase it. To avoid those errors, optional fields to use your own API account have been provided (see Appendix 2 for instructions on how to set this up). For those who have already connected their accounts, a reconnect will be required if this approach is used, but no devices or events will be affected.
• After completing the initial setup, the authorization process begins by redirecting you to the Honeywell Home service. Once you login and select the thermostats plugin will be allowed to choose from, you will be redirected back to Homeseer to complete the process.
• Once your account is connected, you will have the option to reset your connection from the Settings page. Performing this action will disconnect the plug-in from your Lyric account until you complete the steps again, but it will not remove any related HS devices. Reauthorizing your account may be necessary from time to time.

The “Config” page also provides the control over plug-in behavior and logging output.

• The polling interval (in seconds) specifies how often HS should login to the website and check the current settings. A value of 300 seconds (5 minutes) or higher is required.
• The “Update Frequency” controls how much time must pass between update requests. These are specific requests outside of the polling window requested manually (via the “Update” button or script commands). A value of 15 seconds or higher is required. Requests made within less time than this will result in a “Waiting for update…” status temporarily, until the 15 seconds have passed.
• For thermostats that do not support “Auto” mode, the Plug-in can simulate this capability if you enable it. If the Indoor Temperature is greater than the Cool Setpoint or lower than the Heat Setpoint, the operating mode will be changed automatically. You must maintain a 3 degree difference between Cool and Heat Setpoints.
• Optional log data can be recorded in both the Homeseer log and in a stand-alone Plug-In log (which can be found in the “Logs” directory of your Homeseer installation). Please note that the “TRACE” message level should only be used when troubleshooting or sending in for support as it can have a significant impact on performance.
• The “Download Log File” and “Clear Log File” buttons on this page make it easier to manage the plug-in log files on your server, as you are no longer required to access the file system to get them when requested for support.

THERMOSTAT CONFIGURATION

Once your account is connected, the “Thermostat List” Page will be added to the plug-in menu, where you can add one or more thermostats to be controlled by Homeseer by selecting the location and device you wish to add.

• You can edit the minimum and maximum allowed cool or heat settings for each device – these do not replace the settings on the thermostat, but rather are specific to Homeseer. Attempting to go above or below these values is not allowed in Homeseer events, and if a change beyond these limits is detected on a status update, it will be adjusted up/down to the limit accordingly.
• When you’ve added your device to the list, the initial parent device will be created. After the first polling of the status occurs, a series of child devices will be created based on the capabilities of your Lyric device, including:

1. Root Device
2. Update Status
3. Fan Mode
4. System Mode
5. Operating Mode
6. Operating Status
7. Cool Setpoint
8. Heat Setpoint
9. Hold Type
10. Indoor Temperature
11. Indoor Humidity
12. Outdoor Temperature
13. Outdoor Humidity
14. Emergency Heat

You can also highlight a thermostat in the list and click “Remove”, which will delete the associated devices.

THERMOSTAT DEVICES

Once your thermostats are configured, your devices will show the current values on the Home screen.

• The “Status” device shows the status of the last request or command and tracks the last data refresh date/time.

• The “Indoor Temp”, “Indoor Humidity”, “Outdoor Temp”, and “Outdoor Humidity” devices are status-only displays of the data last reported at the thermostat’s location, and are included based on your thermostat’s capabilities.

• The “Fan Mode” shows what the setting is (“On” or “Auto”) and provides control buttons to change the mode.2

• The “Fan Status” device indicates whether the fan is actually running at this time or not (“On”, “Off”).1

• The “Cool Setpoint” and “Heat Setpoint” devices shows what the current setpoint is. It provides a dropdown of valid values to adjust the setpoint for the current mode, as well as +1/-1 adjustments (or +0.5/-0.5 for Celsius). If the device is currently in a Permanent Hold, that hold will be maintained, otherwise a temporary hold will be issued if your thermostat supports such a capability. 2

• The “Hold Type” device shows whether the thermostat is following the schedule (“None”), in a Temporary Hold (“Until HH:MM”) or a “Permanent” hold, depending on capabilities. Buttons are provided to change the type of hold in place. 2

• The “System Mode” shows what the setting is (“Cool”, “Heat”, “Auto” or “Off”, as appropriate to your thermostat model) and provides control buttons to change the mode2. If you have enabled the “Simluate Auto” option, an
  “Auto” mode button will be added even if your thermostat doesn’t support it natively, and switching will be handled by the plug-in if the temperature exceeds the cool setpoint or drops below the heat setpoint.

• The “Operating Status” is an indication of whether the system is currently running or not (“Idle”, “Heating”,
  “Cooling”), and the “Operating Mode” device that shows the mode the unit is currently working in when Auto (or Simulated Auto) is used.

• The “Emergency Heat” device is turned on when emergency heat is activated on your thermostat.

ACTIONS

This plugin provides the following Actions that can be included in Events:

Change Setpoint

• While setpoints can be changed directly on the devices, this action allows multiple coordinated changes to the Setpoint, System Mode, and Hold Status all in a single command.
• The choices of setpoint type and hold will depend on the capabilities of the selected Thermostat.

PLUG-IN FUNCTIONS

The following functions are available for use via scripts and the Homeseer “hs.PluginFunction” method.

• • ChangeMode(deviceID, mode, update)
  • deviceID = string ID of the device, found on the Thermostat List page
  • mode = desired mode
  • Off = 0
  • Heat = 1
  • Cool = 2
  • Auto = 3
  • update = request a full refresh of the data after sending command
• ChangeFanMode(deviceID, mode, update)
  • deviceID = string ID of the device, found on the Thermostat List page
  • mode = desired mode
  • Auto = 0
  • On = 1
  • Circulate = 2
  • update = request a full refresh of the data after sending command
• ChangeHold(deviceID, type, update)
  • deviceID = string ID of the device, found on the Thermostat List page
  • type = type of hold
  • None = 0
  • Temporary = 1
  • Permanent = 2
  • update = request a full refresh of the data after sending command
• ChangeSetpoint(deviceID, setpoint, holdType, mode, update)
  • deviceID = string ID of the device, found on the Thermostat List page
  • setpoint = double
  • type = hold type (see above)
  • mode = which setpoint to change (see above)
  • update = request a full refresh of the data after sending command
• ChangeAll(deviceID, heatSetpoint, coolSetpoint, mode, holdType)
  • deviceID = string ID of the device, found on the Thermostat List page
  • heatSetpoint/coolSetpoint = double
  • mode = which setpoint to change (see above)
  • type = hold type (see above)

COMMAND PROCESSING

In an effort to prevent excessive commands from being sent, when an update is requested, the plug-in checks the timestamp of the last requested update for that thermostat and if it’s too soon (based on “Update Frequency”), it sets a timer to wait until the “Update Frequency” has passed, then requests the update. Any polling timers are stopped and restarted each time an update occurs, so if you change the setpoint (which also requests an update), the next polling won’t occur for the specified number of seconds (“Polling Interval”) regardless of how long ago the last poll occurred.

KNOWN ISSUES

1. The Lyric API doesn’t properly report Fan Status, so it currently shows as “Off” at all times. I’m awaiting a response from Honeywell on this issue.
2. Attempts to initiate changes from the plug-in to the thermostat using the Lyric API will fail with a “400 (Bad Request) Device Not Found” error if you have created your own Resideo Developer account and your application was created using spaces or other punctuation.

SUPPORT

Support for the skWare Lyric Thermostat Plug-In for Homeseer is provided through the standard Homeseer channels. The primary mechanism is via the Lyric Thermostat Plug-in forum on the Homeseer website. The author can be contacted directly at steve@skware.net.

APPENDIX 1: FILES

The following files are used by the Plug-In. Directories in bold are part of the standard Homeseer installation. Files marked with * are created by the software during usage; all other files are included in the installation.

APPENDIX 2: CREATING A RESIDEO DEVELOPER ACCOUNT

In order to leverage your own API key and secret to avoid the “429 Too Many Requests” errors, you must establish your own Developer Account. This is separate from your Thermostat Account, which is used to login and authorize the plug-in.

• Step 1: Create an Account
  Sign up for an account on the Resideo developer site: https://developer.honeywellhome.com/user/register

• Step 2: Register an App
  User the “Create New App” button to define a new App that will use the Honeywell Connected Home API. The App Name must be unique, so I suggest adding your own name to the end or something similar. In order to avoid a potential issue with control requests, make sure your app name uses alphanumeric characters only – no spaces or punctuation.

The “Callback URL” must be: https://skware-oauth- hs.azurewebsites.net/api/OAuthCallback

Step 3: Get the Key & Secret

Step 4: Add Key & Secret to lug-in

• After you change the Key and Secret, you will be disconnected from your Lyric account. Follow the normal steps to authorize your new Resideo App to connect to your thermostat (on the Resideo page you’ll now see your App name from step 2). Be sure and use your Thermostat Account for this step.
• Once you get the code and provide it to the plug-in, your thermostat should successfully update without the 429 errors.

References

• Honeywell Home Developer Site | Register
• Honeywell Lyric (shill) - HomeSeer Message Board

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>