Floppy-currentcost 0.1.0 → 0.1.1

data/README

@@ -23,6 +23,6 @@ Floppy-rb232 >= 0.1.0
 
 == USAGE
 
-You can read data from the meter by creating an instance of the Meter class, 
-and regularly polling it for readings. See examples/simple.rb for an easy 
-example of how to do this.
+You can read data from the meter by creating an instance of the CurrentCost::Meter
+class, and registering an observer which will receive readings. See examples/simple.rb
+or the CurrentCost::Meter documentation for a simple example of how to do this.

data/examples/simple.rb

@@ -16,13 +16,24 @@ OptionParser.new do |opts|
   end  
 end.parse!
 
+# A simple observer class which will receive updates from the meter
+class SimpleObserver
+  def update(reading)
+    # Add all channels to get real figure
+    watts = 0 
+    reading.channels.each { |c| watts += c[:watts] }
+    # Print out measurement
+    puts "New reading received: #{watts} W"
+  end
+end
+
 # Create meter
 meter = CurrentCost::Meter.new(options[:port])
-
-while true
-  reading = meter.latest_reading
-  if reading
-    puts "#{reading.channels[0][:watts]}W"
-  end
-  sleep(6)
-end
+# Create observer
+observer = SimpleObserver.new
+# Register observer with meter
+meter.add_observer(observer)
+# Wait a while, let some readings come in
+sleep(30)
+# Close the meter object to stop it receiving data
+meter.close

data/lib/currentcost/exceptions.rb

@@ -1,5 +1,6 @@
 module CurrentCost
-  
+
+  # Signifies an XML parsing error. Raised by CurrentCost::Reading.from_xml.
   class ParseError < Exception
   end
 

data/lib/currentcost/meter.rb

@@ -1,11 +1,42 @@
 require 'rb232'
 require 'rb232/text_protocol'
+require 'currentcost/meter'
 require 'currentcost/reading'
+require 'observer'
 
 module CurrentCost
+
+  # A class to represent a physical CurrentCost meter attached to a serial port.
+  # This class is Observable (see Ruby documentation for details). Client code
+  # should create an observer class which defines an update(CurrentCost::Reading)
+  # function, and call Meter.add_observer(my_observer) to receive updates when
+  # new readings are received from the physical meter.
+  # 
+  # For example:
+  #
+  #   require 'currentcost/meter'
+  #
+  #   class SimpleObserver
+  #     def update(reading)
+  #       puts "New reading received: #{reading.channels[0][:watts]} W"
+  #     end
+  #   end
+  # 
+  #   meter = CurrentCost::Meter.new
+  #   observer = SimpleObserver.new
+  #   meter.add_observer(observer)
+  #   sleep(30) # wait a while, let some readings come in
+  #   meter.close
+
   
   class Meter
-    
+
+    include Observable
+
+    # Constructor. 'port' is the name of the serial port that the physical
+    # meter is connected to.
+    # This function will automatically start processing serial data on the
+    # specified port. To stop this processing, call close.
     def initialize(port = '/dev/ttyS0')
       @port = RB232::Port.new(port, :baud_rate => 9600)
       @protocol = RB232::TextProtocol.new(@port, "\n")
@@ -13,16 +44,30 @@ module CurrentCost
       @protocol.start
     end
 
+    # Internal use only, client code does not need to use this function. Informs
+    # the Meter object that a new message has been received by the serial port. 
     def update(message)
-      @latest_reading = Reading.from_xml(message) unless message.nil?
+      unless message.nil?
+        # Parse reading from message
+        @latest_reading = Reading.from_xml(message)
+        # Inform observers
+        changed
+        notify_observers(@latest_reading)
+      end
     rescue CurrentCost::ParseError
       nil
     end
 
+    # Get the last Reading received. If no reading has been received yet,
+    # returns nil. If you have registered an observer with add_observer(),
+    # you will most likely not need this function as the reading will be
+    # delivered automatically to your observer's update() function.
     def latest_reading
       @latest_reading
     end
 
+    # Stops serial data processing. Call this once you're done with the Meter
+    # object.
     def close
       @protocol.stop
     end

data/lib/currentcost/reading.rb

@@ -4,7 +4,10 @@ require 'rexml/document'
 module CurrentCost
   
   class Reading
-    
+
+    # Creates a reading object from an XML string.
+    # Raises CurrentCost::ParseError if the XML is malformed or missing
+    # expected content.
     def self.from_xml(xml)
       # Parse XML
       doc = REXML::Document.new(xml)
@@ -49,19 +52,30 @@ module CurrentCost
     rescue 
       raise CurrentCost::ParseError.new("Couldn't parse XML data.")
     end
-    
+
+    # Number of days since the meter was turned on
     attr_accessor :days_since_birth
+    # Current time - hour
     attr_accessor :hour
+    # Current time - minute
     attr_accessor :minute
+    # Current time - second
     attr_accessor :second
+    # Name of the device - always "CC02".
     attr_accessor :name
+    # ID number of the device
     attr_accessor :id
+    # Type id of the device - "1" for a standard CurrentCost meter.
     attr_accessor :type
+    # Version of the meter software
     attr_accessor :software_version
+    # An array of channels. channels[x][:watts] contains the current power for that channel in watts. The figure shown on the meter is the sum of the wattage for all channels.
     attr_accessor :channels
+    # Current temperature
     attr_accessor :temperature
+    # Historical data, represented as a hash. There is a hash entry for days, weeks, months, and years. Each of these is an array of historical kWh data.
     attr_accessor :history
-    
+
   end
-  
-end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: Floppy-currentcost
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - James Smith
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-19 00:00:00 -07:00
+date: 2008-08-20 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -38,7 +38,7 @@ files:
 - lib/currentcost/version.rb
 - lib/currentcost/exceptions.rb
 - examples/simple.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/Floppy/currentcost-ruby
 post_install_message: 
 rdoc_options: []