thermostat

DESCRIPTION:

Thermostat.rb is an attempt to build an easy to use ruby api around the web services provided by the Proliphix line of network thermostats. Their API is documented at www.proliphix.com/Documentation.aspx.

The code is tested on the NT20e unit, which is what I own (the NT10e is the same hardware, just can’t handle remote sensors). It should react that same across all their network accessible units.

FEATURES/PROBLEMS:

Pholiphix Quirks

There is an important notice in the manual which states that you shouldn’t make more than 1 request to the thermostat per 60 seconds for any sustainable period of time. Because of that Thermostat.rb does internal caching. If you have a long lived Thermostat.rb object, it will fetch attributes on demand, and only refresh them after they are more than 60 seconds old.

Set calls obviously still have to hit the thermostat, but the rate at which you are going to use those calls should be much less. Because the thermostat appears to be single threaded to some degree, I’ve found that after a set, an immediate get fails. To get around this, I’ve made the set call wait 1 second, then do a get off all values again. This means the value map should be right after the set, so all attribute gets should reflect the new state of the world.

Future Todo

Unit detection. There is no API to figure out if you are in degrees C or degrees F, so I’m currently assuming F (though none of the code really cares). I’d like to both detect that correctly, and use my Temperature module to ensure you’ve values have units.

Day Classes and Activity Periods. These are in the plumbing but not exposed yet. The API won’t let you set them, but at least you could get the current versions.

If anyone else has different thermostats they think could plug into this interface, I’d be happy to work with them to do so. The code isn’t overly generic because I don’t like premature abstractions.

SYNOPSIS:

thermostat = Thermostat.new("hostname", "admin", "password")

# get the current temperature
current_temp = thermostat.temp

# get the current setback heat value
current_target_temp = thermostat.heat_to

# set the thermostat to 69F (units are set in the thermost)
thermostat.heat_to = 69

DOCUMENTATION

Complete API documentation can be found at sdaguegems.rubyforge.org/thermostat/rdoc

REQUIREMENTS:

INSTALL:

sudo gem install thermostat

AUTHORS:

  • Sean Dague

  • Mark Flocco

LICENSE:

(The MIT License)

Copyright © 2008-2011 Sean Dague

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.