thermostat 1.1.1 → 1.2.0

data/History.txt

@@ -1,3 +1,11 @@
+=== 1.2.0 2011-01-16
+* fix rakefile so readme is correct
+* added support for aux heat/aux heat offset/system time (Mark Flocco)
+
+
+=== 1.1.1 2010-03-11
+* update examples
+
 === 1.1.0 2010-03-10
 * relatively complete unit test coverage
 * add a simulation mode to the network layer so it's easier to test

data/README.rdoc

@@ -9,30 +9,47 @@ the web services provided by the Proliphix line of network
 thermostats.  Their API is documented at
 http://www.proliphix.com/Documentation.aspx.
 
-The code is tested on the NT20e unit, which is what I own.  It should
+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:
 
-Note: It wrote the base module over a year ago, and am now starting to more actively use it in a new project, so interfaces may change to make the api easier to use.
+=== Pholiphix Quirks
 
-Important notices from the manual:
+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.  
 
-**Limitations on the Frequency of Operations**
+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.
 
-While the device can handle numerous back to back requests, it is
-advisable to not sustain an operation frequency higher than 1 request
-per 60 second period for a substantial amount of time. In other words,
-sustained polling of the device should not exceed a few requests per
-minute. A prolonged burst of requests higher than 1 request per 60
-second period may degrade the main function of the thermostat.  Also,
-if one is making a PIB set and wishes to observe a reaction from the
-device, it is advisable to wait for at least 1 second between the set
-request and subsequent get request.
+=== 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 = Thermostate.new("hostname", "admin", "password")
+  thermostat = Thermostat.new("hostname", "admin", "password")
 
   # get the current temperature
   current_temp = thermostat.temp
@@ -43,17 +60,26 @@ request and subsequent get request.
   # set the thermostat to 69F (units are set in the thermost)
   thermostat.heat_to = 69
 
+== DOCUMENTATION
+
+Complete API documentation can be found at http://sdaguegems.rubyforge.org/thermostat/rdoc
+
 == REQUIREMENTS:
 
 == INSTALL:
 
 sudo gem install thermostat
 
+== AUTHORS:
+
+* Sean Dague 
+* Mark Flocco
+
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2008-2010 Sean Dague
+Copyright (c) 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

data/Rakefile

@@ -1,3 +1,4 @@
+# encoding: US-ASCII
 require 'rubygems'
 gem 'hoe', '>= 2.1.0'
 require 'hoe'
@@ -12,10 +13,11 @@ Hoe.plugin :website
 
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.spec 'thermostat' do
+$hoe = Hoe.spec "thermostat" do
     self.developer 'Sean Dague', 'sean@dague.net'
-    self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
-    self.rubyforge_name       = 'sdaguegems'
+    self.rubyforge_name = "sdaguegems"
+    self.extra_rdoc_files = ["README.rdoc"]
+    self.readme_file = "README.rdoc"
     self.extra_deps = [['temperature', '>= 1.0.0']]
     # self.extra_deps         = [['activesupport','>= 2.0.2']]
 end

data/lib/pdp/constants.rb

@@ -2,7 +2,19 @@
 module Proliphix
     # a whole crap load of constants for the proliphix API
 
-    # read/write
+    # This is the user setable mode for what state the thermostat is
+    # in.  This could be one of Off, Heat, Cool, or Auto.  These
+    # really mean which setback values the thermostat is going to pay
+    # attention to.  
+    #
+    # In Off, obviously, it ignores them all.  In Heat mode, it only
+    # cares if you are below SetbackHeat.  In Cool mode, it only cares
+    # if you are above SetbackCool.  In Auto mode it will both heat
+    # and cool to keep within some target range.
+    #
+    # Unless you are storing great works of art, Auto mode is
+    # overkill, and probably going to cost you a lot of money on
+    # Spring and Fall days.
     ThermHvacMode = OID.new("HVAC Mode",
                             "4.1.1",
                             false,
@@ -126,5 +138,22 @@ module Proliphix
     ThermLastUsageReset = OID.new("Last Usage Reset",
                                   "4.5.6",
                                   false, nil, false) # we're going to have to be tricky about this one
+
+    ThermSystemTimeSecs = OID.new("System Time (seconds since epoch)",
+                                  "2.5.1",
+                                  false, nil, false)
+    
+    ThermAuxHeatMode = OID.new("Aux Heat Mode", 
+                               "4.2.30",
+                               false,
+                               {
+                                  1 => "Disabled",
+                                  2 => "Enabled with Compressors",
+                                  3 => "Enabled without Compressors"
+                                })
+
+    ThermAuxHeatOffset = OID.new("Aux Heat Offset (degrees F)",
+                                 "4.1.24",
+                                 true)          
     
 end

data/lib/pdp/network.rb

@@ -27,7 +27,10 @@ module Proliphix
                         ThermHeat1Usage,
                         ThermCool1Usage,
                         ThermFanUsage,
-                        ThermAverageTemp
+                        ThermAverageTemp,
+                        ThermSystemTimeSecs,
+                        ThermAuxHeatMode,
+                        ThermAuxHeatOffset
                        ]
         end
       

data/lib/pdp/oid.rb

@@ -1,7 +1,18 @@
 module Proliphix
     # This is the basic encapsulation class for OIDs used by the Proliphix thermostat.
-        
+       
     class OID
+        # Create a new OID.  It takes 5 parameters
+        #  * name - some name you want to make up
+        #  * oid - the oid that Proliphix uses in it's web service call
+        #  * readonly - is the attribute read only (prevents us from 
+        #    ever trying to do a set call
+        #  * valuemap - if the return is fundamentally an enumeration, 
+        #     provide a hash that we can map these to strings that make sense
+        #  * scale - degrees are sent back as ints which are degrees * 10.  
+        #    If scale is set to true these are automatically divided by 10 before
+        #    returned so that you get the answer in degrees
+        
         def initialize(name, oid, readonly, valuemap = nil, scale = true)
             @name = name
             @oid = oid

data/lib/thermostat.rb

@@ -4,7 +4,7 @@ $:.unshift(File.dirname(__FILE__)) unless
 # This is the main class for controlling the Proliphix Thermostat.
 # You must first initialize it with the control point credentials
 class Thermostat
-    VERSION = '1.1.1'
+    VERSION = '1.2.0'
         
     require 'pdp/oid'
     require 'pdp/constants'
@@ -123,6 +123,44 @@ class Thermostat
         self[ThermFanMode] = 1
         self[ThermFanState]
     end
+    
+    # Get the thermostat system time
+    def system_time
+        self[ThermSystemTimeSecs]
+    end
+    
+    # Set the thermostat system time
+    def system_time=(value)
+        self[ThermSystemTimeSecs] = value.to_i
+        system_time
+    end
+    
+    # Get the aux heat mode
+    def aux_heat
+        self[ThermAuxHeatMode]
+    end
+    
+    # Set the aux heat mode
+    def aux_heat=(value)
+        if (value == "1") or (value == "2") or (value == "3") then
+          self[ThermAuxHeatMode] = value.to_i
+        end
+        aux_heat
+    end
+    
+    # Get the aux heat offset
+    def aux_heat_offset
+        self[ThermAuxHeatOffset]
+    end
+    
+    # Set the aux heat offset
+    def aux_heat_offset=(value)
+        if (value >= 0) and (value <= 10)
+          self[ThermAuxHeatOffset] = value.to_i
+        end
+        aux_heat_offset
+    end
+    
 end
 
 

data/test/test_network.rb

@@ -18,7 +18,7 @@ class TestThermostatNetwork < Test::Unit::TestCase
     end
 
     def test_get_query_generate
-        base_query = "http://foo/get?OID4.1.1=&OID4.1.2=&OID4.1.3=&OID4.1.4=&OID4.1.5=&OID4.1.6=&OID4.5.1=&OID4.5.3=&OID4.5.5=&OID4.1.13="
+        base_query = "http://foo/get?OID4.1.1=&OID4.1.2=&OID4.1.3=&OID4.1.4=&OID4.1.5=&OID4.1.6=&OID4.5.1=&OID4.5.3=&OID4.5.5=&OID4.1.13=&OID2.5.1=&OID4.2.30=&OID4.1.24="
         
         @@t.heat_to
         assert_equal(base_query, query)

data/website/index.html

@@ -24,17 +24,23 @@
       }
       var versionBox = new curvyCorners(settings, document.getElementById("version"));
       versionBox.applyCornersToAll();
+      var mainBox = new curvyCorners(settings, document.getElementById("main"));
+      mainBox.applyCornersToAll();
+      var titleBox = new curvyCorners(settings, document.getElementById("title"));
+        titleBox.applyCornersToAll();
     }
   </script>
 </head>
 <body>
 <div id="main">
 
-    <h1>thermostat</h1>
+    <div id="title">
+      <h1>thermostat</h1>
+    </div>
     <div class="sidebar">
       <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/sdaguegems"; return false'>
         <p>Get Version</p>
-        <a href="http://rubyforge.org/projects/sdaguegems" class="numbers">1.0.0</a>
+        <a href="http://rubyforge.org/projects/sdaguegems" class="numbers">1.1.1</a>
       </div>
     </div>
     <h2>What</h2>
@@ -45,15 +51,30 @@ of some simple home temperature monitoring.</p>
 <p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">thermostat</span></pre></p>
 <h2>The basics</h2>
 <h2>Demonstration of usage</h2>
+<p><pre class='syntax'>
+  <span class="ident">thermostat</span> <span class="punct">=</span> <span class="constant">Thermostat</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(&quot;</span><span class="string">hostname</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">admin</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">password</span><span class="punct">&quot;)</span>
+
+  <span class="comment"># get the current temperature</span>
+  <span class="ident">current_temp</span> <span class="punct">=</span> <span class="ident">thermostat</span><span class="punct">.</span><span class="ident">temp</span>
+
+  <span class="comment"># get the current setback heat value</span>
+  <span class="ident">current_target_temp</span> <span class="punct">=</span> <span class="ident">thermostat</span><span class="punct">.</span><span class="ident">heat_to</span>
+
+  <span class="comment"># set the thermostat to 69F (units are set in the thermostat)</span>
+  <span class="ident">thermostat</span><span class="punct">.</span><span class="ident">heat_to</span> <span class="punct">=</span> <span class="number">69</span>
+</pre></p>
 <h2>Documentation</h2>
 <p>Full module level documentat can be found here:http://sdaguegems.rubyforge.org/thermostat/rdoc</p>
 <h2>How to submit patches</h2>
-<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
+<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a></p>
 <p>You can fetch the source from</p>
 <ul>
 	<li>github: <a href="http://github.com/sdague/thermostat.rb/tree/master">http://github.com/sdague/thermostat.rb/tree/master</a></li>
 </ul>
 <pre>git clone git://github.com/sdague/thermostat.rb.git</pre>
+<p>To send me code updates, fork the tree on github, make your changes,<br />
+then send me a pull request.  That will make it easy for me to<br />
+integrate your patches.</p>
 <h3>Build and test instructions</h3>
 <pre>cd thermostat
 rake test
@@ -63,9 +84,10 @@ rake install_gem</pre>
 <h2>Contact</h2>
 <p>Comments are welcome. Send an email to <a href="mailto:sean@dague.net">Sean Dague</a></p>
     <p class="coda">
-      <a href="FIXME email">FIXME full name</a>, 7th March 2010<br>
+      <a href="http://dague.net">Sean Dague</a>, 12th March 2010<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
+
 </div>
 
 <!-- insert site tracking codes here, like Google Urchin -->

data/website/index.txt

@@ -15,7 +15,7 @@ h2. The basics
 h2. Demonstration of usage
 
 <pre syntax="ruby">
-  thermostat = Thermostate.new("hostname", "admin", "password")
+  thermostat = Thermostat.new("hostname", "admin", "password")
 
   # get the current temperature
   current_temp = thermostat.temp
@@ -23,7 +23,7 @@ h2. Demonstration of usage
   # get the current setback heat value
   current_target_temp = thermostat.heat_to
 
-  # set the thermostat to 69F (units are set in the thermost)
+  # set the thermostat to 69F (units are set in the thermostat)
   thermostat.heat_to = 69
 </pre>
 

data/website/stylesheets/screen.css

@@ -1,5 +1,5 @@
 body {
-  background-color: #8DBD82;
+  background-color: #666666;
   font-family: "Georgia", sans-serif;
   font-size: 16px;
   line-height: 1.6em;
@@ -15,8 +15,15 @@ h1 {
   font-size: 4em;
   line-height: 0.8em;
   letter-spacing: -0.1ex;
-	margin: 5px;
+     margin: 5px 0px;
+     color: white;
+     padding: 20px;
+
 }
+#title { 
+         background-color: #B30000;
+         margin-bottom: 30px;
+         }
 li {
   padding: 0;
   margin: 0;
@@ -24,7 +31,6 @@ li {
 }
 a {
   color: #5E5AFF;
-	background-color: #A1DDB1;
   font-weight: normal;
   text-decoration: underline;
 }
@@ -40,8 +46,10 @@ blockquote {
 
 #main {
   width: 55em;
-  padding: 0;
+  background-color: white;
+  padding: 20px;
   margin: 0 auto;
+  margin-bottom: 30px;
 }
 .coda {
   text-align: right;

data/website/template.html.erb

@@ -24,13 +24,19 @@
       }
       var versionBox = new curvyCorners(settings, document.getElementById("version"));
       versionBox.applyCornersToAll();
+      var mainBox = new curvyCorners(settings, document.getElementById("main"));
+      mainBox.applyCornersToAll();
+      var titleBox = new curvyCorners(settings, document.getElementById("title"));
+        titleBox.applyCornersToAll();
     }
   </script>
 </head>
 <body>
 <div id="main">
 
-    <h1><%= title %></h1>
+    <div id="title">
+      <h1><%= title %></h1>
+    </div>
     <div class="sidebar">
       <div id="version" class="clickable" onclick='document.location = "<%= download %>"; return false'>
         <p>Get Version</p>
@@ -39,9 +45,10 @@
     </div>
     <%= body %>
     <p class="coda">
-      <a href="FIXME email">FIXME full name</a>, <%= modified.pretty %><br>
+      <a href="http://dague.net">Sean Dague</a>, <%= modified.pretty %><br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
+
 </div>
 
 <!-- insert site tracking codes here, like Google Urchin -->

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: thermostat
 version: !ruby/object:Gem::Version 
-  version: 1.1.1
+  hash: 31
+  prerelease: false
+  segments: 
+  - 1
+  - 2
+  - 0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Sean Dague
@@ -9,56 +15,81 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-11 00:00:00 -05:00
+date: 2011-01-16 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: temperature
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
         version: 1.0.0
-    version: 
+  type: :runtime
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rubyforge
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 0
+        - 3
         version: 2.0.3
-    version: 
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: gemcutter
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 0
+        - 3
+        - 0
         version: 0.3.0
-    version: 
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: hoe
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 2
+        - 5
+        - 0
         version: 2.5.0
-    version: 
+  type: :development
+  version_requirements: *id004
 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
   http://www.proliphix.com/Documentation.aspx.
   
-  The code is tested on the NT20e unit, which is what I own.  It should
+  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.
 email: 
 - sean@dague.net
@@ -71,6 +102,7 @@ extra_rdoc_files:
 - Manifest.txt
 - PostInstall.txt
 - website/index.txt
+- README.rdoc
 files: 
 - History.txt
 - Manifest.txt
@@ -105,28 +137,34 @@ has_rdoc: true
 homepage: http://github.com/sdague/thermostat.rb
 licenses: []
 
-post_install_message: PostInstall.txt
+post_install_message: 
 rdoc_options: 
 - --main
 - README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: sdaguegems
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: 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