thermostat 0.0.2 → 1.0.0

data/History.txt

@@ -0,0 +1,5 @@
+=== 1.0.0 2010-03-09
+
+* major enhancements:
+  * Conversion to newgem package for easier future maintenance
+  * Make a more sane from end interface

data/Manifest.txt

@@ -0,0 +1,29 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+account.yaml.example
+config/website.yml
+config/website.yml.sample
+docs/PDP_API_R1_11.pdf
+examples/test-fan-off.rb
+examples/test-fan-on.rb
+examples/test-run.rb
+examples/test-set-heat.rb
+lib/pdp/constants.rb
+lib/pdp/network.rb
+lib/pdp/oid.rb
+lib/thermostat.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+test/test_helper.rb
+test/test_oid.rb
+test/test_thermostat.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,5 @@
+
+For more information on thermostat.rb, see http://sdaguegems.rubyforge.org/thermostat
+
+
+

data/README.rdoc

@@ -0,0 +1,66 @@
+= thermostat
+
+* http://github.com/sdague/thermostat.rb
+
+== 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
+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.
+
+Important notices from the manual:
+
+**Limitations on the Frequency of Operations**
+
+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.
+
+== SYNOPSIS:
+
+  FIX (code sample of usage)
+
+== REQUIREMENTS:
+
+== INSTALL:
+
+sudo gem install thermostat
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 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.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/thermostat'
+
+ENV['VERSION'] = Thermostat::VERSION
+
+Hoe.plugin :newgem
+Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$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.extra_deps = [['temperature', '>= 1.0.0']]
+    # self.extra_deps         = [['activesupport','>= 2.0.2']]
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/account.yaml.example

@@ -0,0 +1,4 @@
+user: admin
+passwd: passwd
+ip: 0.0.0.0
+

data/config/website.yml

@@ -0,0 +1,2 @@
+host: sdague@rubyforge.org
+remote_dir: /var/www/gforge-projects/sdaguegems/thermostat

data/config/website.yml.sample

@@ -0,0 +1,2 @@
+host: unknown@rubyforge.org
+remote_dir: /var/www/gforge-projects/thermostat

data/examples/test-fan-off.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby
+
+$LOAD_PATH.unshift "../lib"
+
+require "yaml"
+require 'thermostat'
+include Proliphix
+
+c = YAML.load_file("../account.yaml")
+
+t = Thermostat.new(c["ip"], c["user"], c["passwd"])
+
+t.set_senors(ThermHvacMode, ThermHvacState, ThermFanState, ThermFanMode, ThermAverageTemp, ThermHeat1Usage)
+t.fetch_data
+
+puts t
+
+t.set_data(ThermFanMode, 1)
+
+puts t

data/examples/test-fan-on.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby
+
+$LOAD_PATH.unshift "../lib"
+
+require "yaml"
+require 'thermostat'
+
+include Proliphix
+
+c = YAML.load_file("../account.yaml")
+
+t = Thermostat.new(c["ip"], c["user"], c["passwd"])
+
+t.set_senors(ThermHvacMode, ThermHvacState, ThermFanState, ThermFanMode, ThermAverageTemp, ThermHeat1Usage)
+t.fetch_data
+
+puts t
+
+t.set_data(ThermFanMode, 2)
+

data/examples/test-run.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/ruby
+
+$LOAD_PATH.unshift "../lib"
+
+require "yaml"
+require 'thermostat'
+
+include Proliphix
+
+c = YAML.load_file("../account.yaml")
+
+t = Thermostat.new(c["ip"], c["user"], c["passwd"])
+
+t.set_senors(ThermHvacMode, ThermHvacState, ThermFanState, ThermFanMode, ThermAverageTemp, ThermHeat1Usage, ThermSetbackHeat)
+
+t.fetch_data
+
+puts t
+
+
+

data/examples/test-set-heat.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby
+
+$LOAD_PATH.unshift "../lib"
+
+require "yaml"
+require 'thermostat'
+include Proliphix
+
+c = YAML.load_file("../account.yaml")
+
+t = Thermostat.new(c["ip"], c["user"], c["passwd"])
+
+t.set_senors(ThermHvacMode, ThermHvacState, ThermFanState, ThermFanMode, ThermAverageTemp, ThermHeat1Usage, ThermSetbackHeat)
+t.fetch_data
+
+puts t
+
+# Sets the heat to 68.0 F 
+t.set_data(ThermSetbackHeat, 680)
+

data/lib/pdp/network.rb

@@ -0,0 +1,123 @@
+module Proliphix
+    # This is the core networking module for getting data off the
+    # thermostat.  It looks sort of funny because I am reusing
+    # constants as hash keys which are actually objects.
+    # 
+    require "open-uri"
+    
+    class Network
+        def initialize(ip, user, passwd)
+            @ip = ip
+            @user = user
+            @passwd = passwd
+            @last = Time.now.to_i
+            @fetched = {}
+            @sensors = [
+                        ThermHvacMode,
+                        ThermHvacState,
+                        ThermFanMode,
+                        ThermFanState,
+                        ThermSetbackHeat,
+                        ThermSetbackCool,
+                        ThermHeat1Usage,
+                        ThermCool1Usage,
+                        ThermFanUsage,
+                        ThermAverageTemp
+                       ]
+        end
+      
+        
+        def [](reading)
+            return @fetched[reading]
+        end
+
+        def get(name)
+            if self[name] and up_to_date
+                return self[name]
+            else
+                fetch_data
+                # TODO: what if we don't manage to return values
+                return self[name]
+            end
+        end
+                  
+        def set(name, value)
+            set_data(name, value)
+            sleep 1
+            fetch_data
+        end
+        
+        private 
+        
+        # Are we currently up to date with our data, if so don't worry
+        # about getting any other values.
+        def up_to_date 
+            return (@last + 60) > Time.now.to_i
+        end
+        
+        def url
+            return "http://#{@ip}"
+        end
+        
+        def get_query_url
+            query = ""
+            for item in @sensors
+                if query != ""
+                    query += "&"
+                end
+                query += "OID#{item.oid}="
+            end
+            query = url + "/get?" + query
+        end
+        
+        def set_query_url(mod, value)
+            query = "OID#{mod.oid}=#{value}"
+            query = url + "/pdp?" + query + "&sumbit=Submit"
+        end
+        
+        # Because of the timing issues with the thermostat we want to
+        # get all the data we can in one packet.
+        def fetch_data()
+            open(get_query_url, :http_basic_authentication => [@user, @passwd]) do |line|
+                parse_data(line.read)
+            end
+            return self
+        end
+        
+        def set_data(mod, value)
+            unless mod.ro?
+                open(set_query_url(mod, value), :http_basic_authentication => [@user, @passwd]) do |line|
+                    parse_data(line.read)
+                end
+            end
+            return self
+        end
+        
+        # The return for the data from Proliphix is kind of silly.  It
+        # includes oids = values in what looks like a uri string.  So
+        # split twice to get values.
+        def parse_data(raw_data)
+            results = raw_data.split('&')
+            results.each do |r|
+                (oid, value) = r.split('=')
+                mod = lookup_oid(oid)
+                if mod
+                    @fetched[mod] = mod[value]
+                end
+            end
+            @last = Time.now.to_i
+        end
+        
+        def lookup_oid(oid)
+            newid = oid.sub(/^OID/, '')
+            @sensors.each do |s|
+                if s.oid == newid
+                    return s
+                end
+            end
+            return nil
+        end
+        
+
+    end
+end

data/lib/pdp/oid.rb

@@ -1,4 +1,6 @@
 module Proliphix
+    # This is the basic encapsulation class for OIDs used by the Proliphix thermostat.
+        
     class OID
         def initialize(name, oid, readonly, valuemap = nil, scale = true)
             @name = name
@@ -8,22 +10,29 @@ module Proliphix
             @scale = scale
         end
         
+        # return the oid of the item that is used in the proliphix web
+        # service calls.  This is typically of the format '4.1.12' or
+        # '4.5.2'
         def oid
             return @oid
         end
 
+        # return the name which you've provided.  This should be a basic string.
         def name
             return @name
         end
 
+        # is the data from the oid read only.
         def ro?
             return @readonly
         end
 
-        # a little tricky, but not too bad.  Basically the access
-        # gives us either the value off the value map, or the degrees
-        # reading (as we always get degrees as 10x ints)
-
+        # Make the OIDs act as their own translator for the values
+        # that come out of the webservices interface.  This is done
+        # via the array opperator because it's doable. 
+        #
+        # We more or less get the raw value or the value divided by
+        # 10, as degrees come back as a 10x integer.
         def [](value)
             if @valuemap 
                 return @valuemap[value.to_i]

data/lib/thermostat.rb

@@ -1,95 +1,112 @@
-require 'net/http'
-require 'uri'
-require 'open-uri'
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
-# order here is important
-require 'pdp/oid'
-require 'pdp/constants'
-
-# Some docs
+# This is the main class for controlling the Proliphix Thermostat.
+# You must first initialize it with the control point credentials
 class Thermostat
-
+    VERSION = '1.0.0'
+        
+    require 'pdp/oid'
+    require 'pdp/constants'
+    require 'pdp/network'
+    
+    include Proliphix
+    
+    # create a new thermostat object.  It needs
+    #  * ip - the ip address of the thermostat, probably 192.168.1.2
+    #  * user - the admin user for the thermostat
+    #  * passwd - the admin passwd for the thermostat
     def initialize(ip, user, passwd)
-        @ip = ip
-        @user = user
-        @passwd = passwd
-        @fetched = {}
-        @sensors = []
+        @network = Proliphix::Network.new(ip, user, passwd)
     end
-
+    
+    # Get a reading for a constant, returns raw values
     def [](reading)
-        return @fetched[reading]
+        return @network.get(reading)
     end
-
-    def url
-        return "http://#{@ip}"
+    
+    # Set a reading for a constant.
+    def []=(reading, value)
+        return @network.set(reading, value)
     end
-
-    def set_senors(*array)
-        @sensors = array
-        return self
+    
+    # Get the thermostat mode.  This will come back as one of "Off",
+    # "Heat", "Cool", or "Auto".
+    def mode
+        self[ThermHvacMode]
     end
-
-    def get_query_url
-        query = ""
-        for item in @sensors
-            if query != ""
-                query += "&"
-            end
-            query += "OID#{item.oid}="
+    
+    # Return what temperature the thermostat is attempting to heat to.
+    def heat_to
+        case mode
+        when "Heat" then return self[ThermSetbackHeat]
+        when "Auto" then return self[ThermSetbackHeat]
         end
-        query = url + "/get?" + query
+        return nil
     end
-
-    def set_query_url(mod, value)
-        query = "OID#{mod.oid}=#{value}"
-        query = url + "/pdp?" + query + "&sumbit=Submit"
+    
+    # Return what temperature the thermostat is attempting to cool to.
+    def cool_to
+        case mode
+        when "Cool" then return self[ThermSetbackCool]
+        when "Auto" then return self[ThermSetbackCool]
+        end
+        return nil
+    end
+    
+    # Return the current temperature reading on the thermostat
+    def temp
+        self[ThermAverageTemp]
     end
 
-    # Because of the timing issues with the thermostat we want to get all the data we can in one packet.
-    def fetch_data()
-        open(get_query_url, :http_basic_authentication => [@user, @passwd]) do |line|
-            parse_data(line.read)
+    # Set the target heat-to temperature.  The effects in non heating
+    # mode aren't well defined.
+    def heat_to=(value)
+        value *= 10
+        if (value > 500) and (value < 800)
+            self[ThermSetbackHeat] = value.to_i
         end
-        return self
+        heat_to
     end
 
-    def set_data(mod, value)
-        unless mod.ro?
-            open(set_query_url(mod, value), :http_basic_authentication => [@user, @passwd]) do |line|
-                parse_data(line.read)
-            end
+    # Set the target cool-to temperature.  The effects in non cooling
+    # mode aren't well defined.
+    def cool_to=(value)    
+        value *= 10
+        if (value > 600) and (value < 900)
+            self[ThermSetbackCool] = value.to_i
         end
-        return self
+        cool_to
+    end
+    
+    # Are we currently running the heat, returns a boolean
+    def heating?
+        self[ThermHvacState] == "Heat"
     end
 
+    # Are we currently running the AC, returns a boolean
+    def cooling?
+        self[ThermHvacState] == "Cool"
+    end
 
-    def parse_data(raw_data)
-        results = raw_data.split('&')
-        results.each do |r|
-            (oid, value) = r.split('=')
-            mod = lookup_oid(oid)
-            if mod
-                @fetched[mod] = mod[value]
-            end
-        end
+    # Is the fan currently on.  It doesn't matter why it's on, just
+    # that it's on.
+    def fan_on?
+        self[ThermFanState] == "On"
     end
 
-    def lookup_oid(oid)
-        newid = oid.sub(/^OID/, '')
-        @sensors.each do |s|
-            if s.oid == newid
-                return s
-            end
-        end
-        return nil
+    # Turn the fan on
+    def fan_on!
+        self[ThermFanMode] = 2
+        self[ThermFanState]
     end
 
-    def to_s
-        s = ""
-        @fetched.each do |k, v|
-            s += "#{k.name}: #{v}\n"
-        end
-        return s
+    # Turn the fan off
+    def fan_off!
+        self[ThermFanMode] = 1
+        self[ThermFanState]
     end
 end
+
+
+