[DEPRECATED] Free Ecobee Suite, Version 1.2.*

Free Ecobee Suite, Version 1.2.*

Important Notice:

As of February 11, 2018, I have released the new fork of this work as the Free Ecobee Suite, Version 1.4.0 (see the announcement here for important instructions on obtaining and installing this new version).

I have also simultaneously released most (but not all) of the enhancements in that new release as the Ecobee Suite, Version 1.2.90. Note that all future enhancements will be made to the 1.3.0 fork ONLY, and this version will soon be deprecated.

You are encouraged to move to the Free Ecobee Suite version 1.4.0 as soon as possible.

I am pleased to announce the availability of version 1.2.0 of the free Ecobee Suite that I have been developing. See these posts for updates:

This release represents a significant update to the suite, and particularly to the UI of the DTH, which now employs dynamically updated icons for most actions. Buttons that are not applicable to the current state of the thermostat (including thermostat mode, fan mode, programs, vacations and holds) are now greyed out, and most actions are now updated to the DTH tiles immediately or within a few seconds. Buttons that are used only as indicators and greyed-out buttons will not take any action.

Other notable enhancements and additions in this version include:

  • Thermostat off - it is now possible to turn the Thermostat off via the UI. Note that if you have circulation enabled (non-zero fanMinOnTime), you cannot turn off the thermostat - the button will be greyed out until such time as the minimum fan runtime is 0. You can reset the fanMinOnTime by turning the fan off or to auto mode - this will then enable the Thermostat’s off mode.
  • Fan Mode cycler - you can now cycle through the 4 supported fan modes: on, auto, circulate, off. Note that the difference between auto and circulate is that auto is in effect when the fan minimum on time per hour is 0; circulate is active if the fanMinOnTime is greater than 0. (fanMinOnTime can be configured on the thermostat, in the Web UI, and using the Smart Circulation or Routines Helper SmartApps).
  • Thermostat Mode cycler - although there are separate buttons for the 4 main thermostat modes (off, heat, cool, auto), you can also cycle through the available thermostat modes by pressing the leftmost button/indicator under the “Command Center” header.
  • Additional Default Hold Type: holdHours - as with the Ecobee3 thermostat itself, you can now set the default hold to be 2 or 4 hours. You can also specify a custom hold time between 1-48 hours. This is in addition to the existing “Until I Change” (permanent hold) and “Until Next Program” (temporary hold). (Due to limitations of the ST UI, the interactive setting of hold time has not been implemented).
  • Thermostat Hold Setting Default - You can now also choose to use the setting on the Thermostat as your default hold type. (Since the interactive (askMe) hold type is not supported, this will default to be a permanent hold).
  • New Refresh Icon and Action - the Refresh icon on the DTHs has been updated, and there is a new Refresh action. If you press it once, it will simply cause the Ecobee Cloud to be polled for any changes to the current Thermostat (or the Sensor’s thermostat). But if you press it again, within a couple of seconds of the Bee icon re-appearing after the first press, it will cause a full refresh from the Ecobee cloud. This is mostly for debugging, and you normally shouldn’t need it, but can help the UI recover from disconnected states (for example).
  • ecobee Smart Circulation Helper SmartApp: Thermostat Mode Filter - You can now select to run the automated circulation changes only when the thermostat is in a specific Mode (e.g. off, heat, cool, auto, auxHeatOnly). This is in addition to filtering for specific Location Modes or Thermostat Programs. If any of the configured cases match, the SmartApp will execute the specified action(s).
  • ecobee Routines Helper SmartApp - updated to allow setting hold time to a specified number of hours, or to default to the physical Thermostat Setting. Hold type is now calculated at the time of the hold so as to use the latest value set in the DTH preferences, Ecobee (Connect) preferences or on the Thermostat itself, dependent upon whatever is specified.
  • Configurable DTH Icon/Image - both the Thermostat and the Sensor DTH now display a default icon in the list displays (like in the Room list). You can override this icon, and/or use an image instead, if you prefer.
  • Support for latest SmartThings Thermostat attributes - SmartThings recently extended the definition of their Thermostat device model (see July 07, 2017 entry here: http://docs.smartthings.com/en/latest/latest-updates.html)
  • Fahrenheit 451° - The alerts and displays when the link between the thermostat and the Ecobee cloud is down now shows the temperature 451° (the ignition point of paper) on a red background. (Note, this is the display value only, the thermostat will still report the last known actual temperature for the temperature attribute). When the connection is re-established, it can take a few minutes for all of the DTH tiles/status to return to normal.
  • Bug Fixes and Optimizations - numerous bugs have been squashed and the code/communications have been further optimized in several dimensions. That said, I’m sure that I have also introduced new bugs, so your patience is appreciated.

Please post any problem reports to this thread, and I will endeavor to resolve them in a timely manner.

If you would like to try out this Suite of Ecobee Device Type Handlers and supporting SmartApps, you can follow the instructions on my GitHub SmartThings repository:

For those familiar with using SmartThings/GitHub integration, the particulars you need are:

Owner: SANdood
Name: SmartThingsPublic
Branch: StorageAnarchy-Ecobee

Note: Occasionally people have found that not all of the SmartApps and DTHs are updated properly using the SmartThings Github integration. While I have no idea why, you may have to manually update one or more files (copy/paste them into your SmartThings IDE). You can use the version number found near the top of each file to recognize whether you have the latest version in your IDE.

Installation Overview

  1. You will need to get ALL EIGHT of the .groovy SmartApps under the SmartThings directory, and BOTH of the Device Handlers in deviceTypes under the SmartThings directory (you need them all saved within your IDE instance, even if you don’t plan on using them all).
  2. After first enabling OAuth for Ecobee (Connect), publish Ecobee (Connect) and the two DTHs. You can also publish the rest of the Helper SmartApps if you like - their names are intentionally lower-case so that they will appear at the end of you My Apps list. Just note that if you publish them once, you will have to publish them again every time you update the source files.
  3. In your mobile app, go to Marketplace/SmartApps/My Apps, and run Ecobee (Connect) to create and configure your Thermostat(s), Sensor(s) and Helper SmartApps. The first time you run this you will connect to your Ecobee account. Then, exit and re-enter Ecobee (Connect) from the Automation/SmartApp list, and then select your thermostat(s), sensor(s) and preferences. Exit out again, and your new Ecobee thermostat & sensor devices will appear in your list of Things under My Home.
  4. Finally, you can go back into Ecobee (Connect) to create and configure any of the Helper SmartApps.

IMPORTANT! You should not try to install the Device Type handlers manually through the IDE - this will not work! Ecobee (Connect) is the Parent SmartApp for the entire suite, and it will create the Child devices and Helper SmartApps for you.

More information is in the Readme file in the GitHUB directory linked above.


My current ToDo list includes (not in priority order):

  • Configurable default fanMinOnTime (possibly per-Program/Climate)
  • Button selector and/or cycler for Hold times
  • A new Helper SmartApp for Custom Hold times (including dateTime and future holds, if possible)
  • An all-black-background UI (except for the multi-Attribute tile at the top)
  • Finish updating the documentation on Github to fully represent this implementation (new screenshots added with this version)
  • …your suggestions here!

Motivation & Recognition

My motivation in this effort is simply to create a robust free SmartThings Device Handler and SmartApp Suite for Ecobee thermostats. This work is based off of the original SmartThings-provided DTH, and the significant contributions built on top of that Open Source version by @StrykerSKS. I have since overhauled Sean’s work significantly to produce this version, leveraging my own experience in interfacing with the Ecobee API efficiently and in creating a robust and responsive UI in SmartThings.

There are other DTH’s for the Ecobee family of thermostats:

Let me be clear: this is not a competition. I am not trying to replace or outdo any other version, and I personally have nothing against people making money off of their efforts. I have invested my time in this as Open Source so as to meet my own wants and desires, and I offer the result back to the community with no strings attached.

Please feel free to try them all, and pick the one that best fits your own use case and preference.

I do simply request that if you have issues or need help with any of the above, please post them to the appropriate thread. All of us are committed to helping you in every way possible, but we don’t necessarily follow each others’ discussions. And if you do find an Ecobee suite that you like, please let the Authors know - positive feedback is our greatest reward.


All that said, this work is fully Open Source, and available for your use at no charge. If you would like to make a small donation as a token of your support, you can send it to me at PayPal.Me

Please post suggestions and problem reports for this version (only) to this thread!!!


Thanks for including Ask Alexa Message Queue capabilities to your app as well!

1 Like

Great! Glad you got the HOLD options implemented. Seems to be working well so far. :slight_smile:

1 Like

UPDATE: Ecobee Thermostat v1.2.1

1.) Ensure that Mode buttons are re-enabled after Vacation Hold ends
2.) Optimize button enable/disable - remove isStateChange: true for all button updates

Get the latest ecobee-thermostat.groovy from the repo…

Thank you for this device handler. I installed an Ecobee3 last week and it works great!

1 Like

Hello, I just installed your device handler and smartapps. When I launch Ecobee Connect and select “ecobee Authorization” I get the following error. Clicking on Retry yields the same result.

Any guidance would be greatly appreciated.


Could you please share what Ecobee (Connect) logs to Live Logging in the IDE when this happens?

I just double checked on both iOS and Android mobile devices and it works fine for me…are you still having problems?

I got that screen earlier (on a different device) and refreshed and it worked. I think it was from yesterday’s hub firmware update.

1 Like

UPDATE: Ecobee Thermostat v1.2.3 and Ecobee (Connect) v1.2.3a


  1. Displays when thermostat is overcooling to reduce humidity

  2. Displays when dehumidifying while cooling

  3. Handles “Auto Away” and “Auto Home” (sensor-driven modes) - these behave same as Hold: Away/Home

  4. Significant optimizations of the event update handler

  5. Misc bug fixes & typo corrections

Get the latest ecobee-thermostat.groovy and ecobee-connect.groovy from the repo…


Looks great… Will try it once i’m back home next week

Quick q - any issues for the folks using Keen vents using Kneect with this SmartApp ?


Nope, there shouldn’t be any problems. This DTH will work essentially the same as the Ecobee webApp - it can control/change things, but it basically reports/displays whatever the Ecobee API presents.

It doesn’t seem that you need this, but the Suite also includes a SmartApp that will open/close vents (Econet and Keen) based on the room temperature and the thermostat’s target temperature - much like the Keen app will do. I would, however, advise against using both to control your vents, if only to prevent the vents from cycling due to different algorithms, etc.




thanks for the quick reply… Have a great weekend


51a8d103-774c-419e-81ff-ddc84d6d196c  6:00:32 PM: error java.lang.RuntimeException: Unexpected status code 400 from global /clients/null with status text @ line 218
51a8d103-774c-419e-81ff-ddc84d6d196c  6:00:31 PM: error java.lang.RuntimeException: Unexpected status code 400 from global /clients/null with status text @ line 218
51a8d103-774c-419e-81ff-ddc84d6d196c  6:00:30 PM: error java.lang.RuntimeException: Unexpected status code 400 from global /clients/null with status text @ line 218
51a8d103-774c-419e-81ff-ddc84d6d196c  6:00:28 PM: error java.lang.RuntimeException: Unexpected status code 400 from global /clients/null with status text @ line 218
51a8d103-774c-419e-81ff-ddc84d6d196c  6:00:24 PM: error java.lang.RuntimeException: Unexpected status code 400 from global /clients/null with status text @ line 218

Updated to 1.2.3a first, getting a repeat error on every refresh.

Thanks for looking into this.

Did you enable OAuth for Ecobee (Connect)?

Seems like I missed that part in the documentation. Enabled OAuth and everything worked. Is it possible to add a check for OAuth enablement in the mobile UI for bone heads like me? :smiley:

Thanks for your help.

1 Like

Good idea!

The problem is so prevalent that I’m adding an error check that will note the probable cause to Live Logging on the failure.

UPDATE: Ecobee (Connect) v1.2.4


  1. Catch OAuth initilization errors and suggest probable cause (OAuth not enabled) in Live Logging and in Mobile UI

NOTE: Tested & Verified, August 13, 2017 @ 9:00am


As a recent nest convert, I find myself missing my scheduled fan run time. I used it every morning for about 30min as I got ready for work. The default functionality of running so many minutes every hour is too aggressive for my taste.

Is there a work flow that I’m missing to accomplish the same thing with ST?

Two quick solutions:

  1. Using Ecobee (no SmartThings required): Create a program that is the same as your Home program, except that it has the Fan set to On (the default Home program has the fan set to Auto). Edit your schedule to run this program at the desired time of the morning. Limitations: Can only start and end the program on the hour or half hour (Ecobee limitation)

  2. Using SmartThings: Use WebCoRE to call fanOn() at the desired time, then have it call resumeProgram() 30 minutes later (changing the fan from Auto to On causes a Fan Hold to be set - the Hold will be in effect for the specified default Hold Action).

I’ve been asked for other time-based events, so I will add this to the backlog. It’s a little complicated by some of the SmartThings limitations on timers, but not impossible.

Another option:

  1. Here’s a hybrid approach: Create a new SmartThings Routine that does something innocuous - turn on a light that’s always on (or create a dummy switch - the Routine needs to do something). Set the routine to run at a specific time (or on whatever initiator you want). Then create a Mode/Routine/Program Helper SmartApp from within Ecobbee (Connect). Set it to run whenever the newly-create Routine executes, and have it change the thermostat program to your normal program (e.g. Home), but with the Fan On. Set the hold type to “until next change” if you normally leave the house (and have things change to Away), or to Specified Hours / 1 hour (unfortunately I haven’t implemented minutes support yet). OR You could create another routine that runs 30 minutes after the first one, and have a separate Helper SmartApp set the Ecobee Program to Home, with Fan Auto.

Fun with Modes, Routines and Programs!