egauge 1.0.0

data/.rspec

@@ -0,0 +1 @@
+--require <%= File.join(File.expand_path(File.dirname(__FILE__)), 'spec', 'spec_helper.rb') %>

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0 / 2012-03-02
+
+* Initial revision

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Irongaze Consulting LLC
+
+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/README.rdoc

@@ -0,0 +1,67 @@
+= GEM: egauge
+
+Written by Rob Morris @ Irongaze Consulting LLC (http://irongaze.com)
+
+Funding for development provided by Sustainable Industrial Solutions LLC (http://sustainableis.com)
+
+== DESCRIPTION
+
+A set of classes to enable parsing and using data from eGauge meters as native Ruby objects.
+
+== SYNOPSIS
+
+This gem facilitates interpreting incoming monitoring data and converting it into Ruby objects for easier
+manipulation.  It handles parsing the xml data posted by eGauge devices, converting them into Ruby objects
+that can be manipulated with ease!
+
+To use:
+
+    # Require the library (not needed if using Rails/bundler)
+    >> require 'egauge'
+    
+    # Parse a posted xml chunk to extract the contained data, passing in
+    # the data posted to your server from the eGauge device
+    >> data = EGauge::Data.parse(request.body.read)
+
+    # Which device sent this data?
+    >> data.serial
+    => '0x37cdd096'
+    
+    # How many registers do we have data coming in from?
+    >> data.register_count
+    => 2
+
+    # How many rows of data?
+    >> data.row_count
+    => 3
+
+    # Check out a register
+    >> reg = data.registers.first
+    >> reg.label
+    => 'Solar'
+    >> reg.type_code
+    => 'P'
+    
+    # Get the data points from a given register, with timestamps
+    >> reg.each_with_timestamp do |val, ts|
+    >>   puts "#{ts}: #{val}"
+    >> end
+    2012-10-09 13:50:00 -0400: 51140761685
+    2012-10-09 13:51:00 -0400: 51140761792
+    2012-10-09 13:52:00 -0400: 51140761880
+    
+== REQUIREMENTS
+
+- Ruby 1.9
+- Nokogiri for XML parsing
+- Rspec to build and test the gem
+
+== INSTALL
+
+To install, simply run:
+
+    sudo gem install egauge
+    
+RVM users can skip the sudo:
+  
+    gem install egauge

data/Version.txt

@@ -0,0 +1 @@
+1.0.0

data/lib/egauge.rb

@@ -0,0 +1,21 @@
+# Load our dependencies
+#require 'iron/extensions'
+
+# Requires all classes
+search_path = File.join(File.expand_path(File.dirname(__FILE__)), '*', '*.rb')
+Dir.glob(search_path) do |path|
+  require path
+end
+
+module EGauge
+  
+  def self.parse_time(str)
+    # Chop off the initial hex flagging if present
+    str = str[2..-1] if str[/^0x/]
+    # Do ruby stuff to convert to 4 byte unsigned int
+    as_int = str.hex
+    # And return as a time...
+    Time.at(as_int)
+  end
+  
+end

data/lib/egauge/data.rb

@@ -0,0 +1,79 @@
+require 'nokogiri'
+
+module EGauge
+  class Data
+    # Attributes
+    attr_reader :serial, :registers, :timestamp
+    
+    # Parse XML and return an EGauge::Data object containing the data.
+    # This will be the primary entry point for most uses of this gem.
+    def self.parse(xml)
+      doc = Nokogiri::XML(xml)
+      doc.slop!
+      
+      data = new(doc)
+      data
+    end
+    
+    def initialize(xml)
+      # Store off Nokogiri xml tree
+      @xml = xml
+      @serial = @xml.group['serial']
+      
+      # Get first data segment, which sets the register info for all data segments
+      data = @xml.group.data
+      
+      # Save off our starting timestamp for this whole group
+      @timestamp = EGauge::parse_time(data['time_stamp'])
+      
+      # Build our registers
+      index = 0
+      @registers = data.cname.collect do |col|
+        reg = EGauge::Register.new(self, index, col)
+        index += 1
+        reg
+      end
+    end
+    
+    def xml
+      @xml
+    end
+    
+    def num_registers
+      @registers.count
+    end
+    
+    def num_rows
+      # Sum the count of rows across each <data> node
+      @xml.group.elements.collect do |chunk|
+        (chunk / './r').count
+      end.inject(&:+)
+    end
+    
+    # Run each value in this register
+    def each_with_timestamp
+      @xml.group.elements.each do |chunk|
+        # Set up for running this data chunk - prep timestamp and increment step from source xml
+        ts = EGauge::parse_time(chunk['time_stamp'])
+        step = chunk['time_delta'].to_i
+        
+        # Run each row in the chunk, and yield our results
+        (chunk / './r').each do |row|
+          vals = (row / './c').collect {|c| c.text.to_i}
+          yield ts, vals
+          ts += step
+        end
+      end
+    end
+    
+    # Return results as a 2D array, like so: [ [timestamp1, [val1, val2...]], [timestamp2, [val1, val2,...], ... ]
+    def to_a
+      res = []
+      each_with_timestamp do |ts, vals|
+        res << [ts, vals]
+      end
+      res
+    end
+    
+  end
+end

data/lib/egauge/register.rb

@@ -0,0 +1,46 @@
+
+# Represents a single register in the
+module EGauge
+  class Register
+    
+    attr_accessor :index, :label, :type_code
+    
+    def initialize(data, index, def_node)
+      @data = data
+      @index = index
+      
+      @label = def_node.text
+      @type_code = def_node['t']
+    end
+    
+    # Run each value in this register, yielding |timestamp, value| for each
+    def each_with_timestamp
+      @data.xml.group.elements.each do |chunk|
+        # Set up for running this data chunk - prep timestamp and increment step from source xml
+        ts = EGauge::parse_time(chunk['time_stamp'])
+        step = chunk['time_delta'].to_i
+        
+        # Run each row in the chunk, and yield our results
+        (chunk / './r').each do |row|
+          val = (row / './c')[@index].text.to_i
+          yield ts, val
+          ts += step
+        end
+      end
+    end
+    
+    # Return results as a 2D array, like so: [ [timestamp1, val1], [timestamp2, val2], ... ]
+    def to_a
+      res = []
+      each_with_timestamp do |ts, val|
+        res << [ts, val]
+      end
+      res
+    end
+    
+    def count
+      @data.num_rows
+    end
+    
+  end
+end

data/spec/egauge/data_spec.rb

@@ -0,0 +1,45 @@
+
+describe EGauge::Data do
+  
+  before do
+    # Let's get us a sample to work on...
+    @data1 = EGauge::Data.parse(SAMPLE_FILE['data1'])
+  end
+  
+  it 'should parse valid xml' do
+    xml = SAMPLE_FILE['data1']
+    group = EGauge::Data.parse(xml)
+    group.should_not be_nil
+  end
+  
+  it 'should provide the serial number' do
+    @data1.serial.should == '0x37cdd096'
+  end
+  
+  it 'should provide the timestamp' do
+    @data1.timestamp.should == Time.at(0x4c9197e4)
+  end
+  
+  it 'should provide a count of the registers' do
+    @data1.num_registers.should == 3
+  end
+
+  it 'should let you access registers as an array' do
+    @data1.should respond_to(:registers)
+    @data1.registers.should be_a(Array)
+    @data1.registers[2].should be_a(EGauge::Register)
+  end
+
+  it 'should know the number of data rows' do
+    @data1.num_rows.should == 3
+  end
+  
+  it 'should allow access to full row data' do
+    @data1.each_with_timestamp do |ts, values|
+      ts.should be_a(Time)
+      values.should be_a(Array)
+      values.count.should == 3
+    end
+  end
+
+end

data/spec/egauge/egauge_spec.rb

@@ -0,0 +1,8 @@
+
+describe EGauge do
+  
+  it 'should parse times correctly' do
+    EGauge.parse_time('0x4c9197e4').should == Time.at(1284610020)
+  end
+  
+end

data/spec/egauge/register_spec.rb

@@ -0,0 +1,39 @@
+
+describe EGauge::Register do
+  
+  before do
+    @data1 = EGauge::Data.parse(SAMPLE_FILE['data1'])
+    @reg = @data1.registers[1]
+  end
+  
+  it 'should provide a label' do
+    @reg.label.should == 'Solar'
+  end
+  
+  it 'should provide a type code' do
+    @reg.type_code.should == 'P'
+  end
+  
+  it 'should know its own index' do
+    @reg.index.should == 1
+  end
+  
+  it 'should return valid values' do
+    @reg.to_a.collect {|row| row[1]}.should == [21308125431, 21308125526, 21308125626]
+  end
+  
+  it 'should allow iterating over values with timestamps' do
+    counter = 0
+    @reg.each_with_timestamp do |ts, val|
+      val.should be_a(Integer)
+      ts.should be_a(Time)
+      counter += 1
+    end
+    counter.should == 3
+  end
+  
+  it 'should know the number of values it owns' do
+    @reg.count
+  end
+  
+end

data/spec/samples/data1.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<group serial="0x37cdd096">
+  <data columns="3" time_stamp="0x4c9197e4" time_delta="60" epoch="0x47395980">
+    <cname t="P">Grid</cname>
+    <cname t="P">Solar</cname>
+    <cname t="P">Grg&amp;Bth (PHEV)</cname>
+    <r><c>5203642184</c><c>21308125431</c><c>17598056700</c></r>
+    <r><c>5203503484</c><c>21308125526</c><c>17598116405</c></r>
+    <r><c>5203368999</c><c>21308125626</c><c>17598176060</c></r>
+  </data>
+</group>

data/spec/samples/data2.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE group PUBLIC "-//ESL/DTD eGauge 1.0//EN" "http://www.egauge.net/DTD/egauge-hist.dtd">
+<group serial="0x64bf2a22">
+<data columns="17" time_stamp="0x505b93c0" time_delta="60" epoch="0x50573af0">
+ <cname t="P">use</cname>
+ <cname t="P">gen</cname>
+ <cname t="P">Gen Virt</cname>
+ <cname t="#">aaron.testv1</cname>
+ <cname t="P">aaron.vtest2</cname>
+ <cname t="#">reac</cname>
+ <cname t="P">Mayo</cname>
+ <cname t="P">Mayo+</cname>
+ <cname t="S">Mayo*</cname>
+ <cname t="#">catchup ¥</cname>
+ <cname t="P">Register 1-</cname>
+ <cname t="P">Panel HP</cname>
+ <cname t="P">Panel PA</cname>
+ <cname t="P">Panel PB</cname>
+ <cname t="P">Panel LP</cname>
+ <cname t="P">solar2</cname>
+ <cname t="P">solar1</cname>
+ <r><c>745905872565</c><c>0</c><c>51140761685</c><c>1702828296559</c><c>-11291842883</c><c>193</c><c>-11309952897</c><c>-11291842883</c><c>1041</c><c>1702828296559</c><c>0</c><c>-50610360087</c><c>-486918628116</c><c>-533588476436</c><c>-695295512478</c><c>25077777223</c><c>26062984462</c></r>
+</data>
+</group>

data/spec/samples/data3.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<group serial="0x37cdd096">
+  <data columns="1" time_stamp="0x4c9197e4" time_delta="60" epoch="0x47395980">
+    <cname t="P">Grid</cname>
+    <r><c>123</c></r>
+    <r><c>456</c></r>
+  </data>
+  <data columns="1" time_stamp="0x4c9197e4" time_delta="300" epoch="0x47395980">
+    <cname t="P">Grid</cname>
+    <r><c>789</c></r>
+    <r><c>101112</c></r>
+  </data>
+</group>

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+# Require our library
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'egauge'))
+
+RSpec.configure do |config|
+  #config.add_formatter 'documentation'
+  config.color = true
+  config.backtrace_clean_patterns = [/rspec/]
+end
+
+# Set up some sample files
+SAMPLE_FILE = {}
+Dir.glob(File.join(File.dirname(__FILE__), './samples/*.xml')).each do |p|
+  SAMPLE_FILE[File.basename(p,'.xml')] = File.read(p)
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: egauge
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Rob Morris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows accepting and parsing eGauge Energy monitor xml data as native
+  Ruby objects.
+email:
+- rob@irongaze.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/egauge/data.rb
+- lib/egauge/register.rb
+- lib/egauge.rb
+- spec/egauge/data_spec.rb
+- spec/egauge/egauge_spec.rb
+- spec/egauge/register_spec.rb
+- spec/samples/data1.xml
+- spec/samples/data2.xml
+- spec/samples/data3.xml
+- spec/spec_helper.rb
+- LICENSE
+- History.txt
+- Version.txt
+- README.rdoc
+- .rspec
+homepage: http://irongaze.com
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Data stream parser for eGauge monitoring output
+test_files: []