ce-greenbutton 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b411fe5d5b0acdab84cbf12802c81c41925f4003
+  data.tar.gz: 90fedbb838bf0ff0afad023f0b9adba288c23728
+SHA512:
+  metadata.gz: 067ceefd90b3d862db54711d73206119a024cbdb19225bfc956a35ba1ae5aca10f8c7e068119002412d02eff8fc02121d022dc661a878db4ee92bfa3a7442790
+  data.tar.gz: 9a010716a45917e24cc70900bb040ff0a3b2f14b40dc26d9e57470e2c1ac2e6554935ae7e961d9dfe8e53c730e710d8b462346083b42ef0cc005b3db3b162a5b

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in greenbutton.gemspec
+gemspec
+gem 'simplecov', :require => false, :group => :test

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 TODO: Write your name
+
+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.md

@@ -0,0 +1,162 @@
+# Overview
+GreenButton gem is a Ruby wrapper for the  [Green Button](http://www.greenbuttondata.org) Data. It allows third-party applications to retrieve the GreenButton data in the form of handy Ruby objects hiding the details of the XML representation and parsing.
+
+## About the module
+The GreenButton gem is designed for extendability and scalability. It provides a framework for processing the GreenButton data. It currently supports only the electricity consumption data, but plugins can be easily adapted to support new kinds of data.
+
+The increased size of data by time was a significant factor in designing this module. To support this expected size of data, the [SAX parsing technique] is leveraged in this module.
+
+### Why SAX and why sax-machine?
+Unlike [DOM](http://en.wikipedia.org/wiki/Document_Object_Model), SAX need not to load the whole file into memory for parsing. It is an event driven parsing.
+As we don't need power featchers of DOM like XPath for example, so SAX is ideal for data size scalability.
+
+
+The [SAX Machine](https://github.com/pauldix/sax-machine) provides a simple and elegant binding interface that binds xml elements to Ruby objects and properties.
+
+## Setup Prerequisites
+1. [Latest Ruby SDK] (https://www.ruby-lang.org/en/)
+[bundler](http://bundler.io/) is used to build and manage dependency.
+2. [bundler](http://bundler.io/) is used to build and manage dependency.
+3. [TomDoc](http://www.rubydoc.info/gems/tomdoc/0.2.5/frames#Installation) is used
+
+
+
+
+## Installation
+
+Using [bundler](http://bundler.io/), add this line to your application's Gemfile:
+
+```ruby
+gem 'greenbutton'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install greenbutton
+
+The parser uses [SAX Machine](https://github.com/pauldix/sax-machine) and will install it as dependency.
+
+## Usage
+A typical scenario of the module usage will be like this
+
+The following will download and parse all data for subscription
+
+```ruby
+require 'greenbutton'
+GreenButton.config(reg_access_token: "your access token",
+                application_information_url: "http://app_info_url")
+gb = GreenButton.download_data('your access token', 'http://greenbutton.data.url')
+```
+
+The following will download and parse all 2013 data for subscription
+
+```ruby
+require 'greenbutton'
+GreenButton.config(reg_access_token: "your access token",
+                  application_information_url: "http://app_info_url")
+gb = GreenButton.download_data('your access token', 'http://greenbutton.data.url'
+                               Date.new(2013,1,1), Date.new(2013,12,31))
+```
+### Notes on usage
+1. The access token is an OAuth2 access token.
+2. The GreenButton.config must be called before the first call to download_data
+3. You can test real data with the following values
+    * registration access token: d89bb056-0f02-4d47-9fd2-ec6a19ba8d0c
+    * application information url: https://services.greenbuttondata.org:443/DataCustodian/espi/1_1/resource/ApplicationInformation/2
+    * access_token: 688b026c-665f-4994-9139-6b21b13fbeee
+    * data url (resource): https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Batch/Subscription/6
+
+
+**Note, the call to `config` is mandatory before the first usage of the module.**
+
+the returning result of the download_data call is an array of GbDataDescription
+and it can be accessed like that.
+
+```ruby
+gb_data_descriptions.each do |gb_data_desc|
+  gb_data = gb_data_desc.gb_data_array.first
+  gb_data_reading = gb_data.interval_readings.first
+  puts gb_data_reading.cost
+end
+```
+
+
+## Limitations
+1. Only the electricity consumption data is supported.
+2. Only required data is extracted from the XML. For full list of required data,
+check the `GbDataDescription`, `GbData` and `GbDataReading` classes in the
+`model` directory.
+
+## Extending Notes
+The module is designed to ease extension in the following paths
+
+1. Extract more information: that will be done by adding more elements to the
+ parser in "greenbutton/elements"
+2. Support more interpreters for different GreenButton data (like 'gas' for
+example). This will be done by adding the interpreter implementation in the
+"greenbutton/interpreters" directory.
+
+### Supporting new kind of GreenButton data
+1. Implement the new interpreter. Name the file as <service kind name>_interpreter.rb and put it in the interpreters folder.
+  **NOTE  that this is very important as without this naming convention, the module may not be loaded as expected.**
+2. Take the provided electricity_interpreter as a guide for the expected data.
+3. It is preferred to use the following names for the different data kinds.
+Using those names will make the interpreter loaded automatically.
+
+```ruby
+SERVICEKIND_NAMES = {
+      0 => 'electricity',
+      1 => 'gas',
+      2 => 'water',
+      3 => 'time',
+      4 => 'heat',
+      5 => 'refuse',
+      6 => 'sewerage',
+      7 => 'rates',
+      8 => 'tvLicence',
+      9 => 'internet'
+  }
+```
+## Code Documentation
+[TomDoc Notation](http://tomdoc.org/) was used to document code in this gem.
+
+### TomDoc generation
+To generate the docs:
+
+*  The latest development version of the [TomDoc tool](https://github.com/defunkt/tomdoc) should be used as the published version seems to be out-dated. Refer to [TomDoc Local Development] (https://github.com/defunkt/tomdoc#local-dev) for instructions.
+*  Use the console format (default), the HTML generator will not detect all docs.
+*  To generate the console docs, just issue the following command for each file
+
+         $ruby -rubygems /path/to/cloned/tomdoc/bin/tomdoc /path/to/tomdoced/code.rb
+
+## Test
+### Local data
+Run a local web server on port 8123 and serve files under the `test_files` directory.
+ Using  [NodeJS] (www.nodejs.org)
+
+    $ npm install http-server -g
+    $ cd test_files
+    $ http-server -p 8123
+**Note** You may need admin (root) privilege to install node/http-server
+
+From the base directory of the module (the directory containing the .gemspec file.
+
+    $ bundle install
+    $ bundle exec rspec
+
+Coverage reports will be found under the `coverage` subfolder.
+
+## GreenButton API reference
+- [Green Button Home](http://www.greenbuttondata.org)
+- [Green Button API sandbox](http://energyos.github.io/OpenESPI-GreenButton-API-Documentation/API/)
+- [GReen Button Concept overview](http://www.greenbuttondata.org/developers/)
+
+
+### Reference this Ruby Gem Documentation
+`tomdoc` was used to generate documentation files for this gem. The generated files are included in `docs` directory.
+
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/ce-greenbutton/elements/gb_application_information.rb

@@ -0,0 +1,17 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'sax-machine'
+module GreenButton
+  module Parser
+  # a sax-machine mapping for the ApplicationInformation structure.
+  #
+  # For example
+  #   app_info = GbApplicationInformation.parse(open(application_information.xml))
+  #
+  # Author ahmed.seddiq
+  # Version 1.0
+  class GbApplicationInformation
+      include SAXMachine
+      element :'espi:dataCustodianId', as: :data_custodian_id
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_content.rb

@@ -0,0 +1,26 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'sax-machine'
+require 'ce-greenbutton/elements/gb_interval_block'
+require 'ce-greenbutton/elements/gb_usage_point'
+require 'ce-greenbutton/elements/gb_local_time_parameters'
+require 'ce-greenbutton/elements/gb_reading_type'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the Content structure
+    #
+    # For example:
+    #   content = GbContent.parse(open(content.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbContent
+      include SAXMachine
+      element :'espi:UsagePoint', class: GbUsagePoint, as: :usage_point
+      element :'espi:IntervalBlock', class: GbIntervalBlock, as: :interval_block
+      element :'espi:LocalTimeParameters', class: GbLocalTimeParameters, as: :local_time_parameters
+      element :'espi:ReadingType', class: GbReadingType, as: :reading_type
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_data_feed.rb

@@ -0,0 +1,34 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'sax-machine'
+require 'ce-greenbutton/elements/gb_entry'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:DataFeed structure
+    #
+    # For example:
+    #   data_feed = GbDataFeed.parse(open(data_feed.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbDataFeed
+      include SAXMachine
+      elements :entry, class: GbEntry, as: :entries
+
+      # Get the related entry to the given entry of the given type
+      #
+      # entry - the parent entry.
+      # type  - the type of the required entry,e.g. 'MeterReading'
+      #
+      # Note: This method should be only called on instances returned from Parser.parse
+      # method.
+      #
+      # Returns the related GbEntry
+      def get_related (entry, type)
+        related_entry_key = entry.related[type] unless entry.related.nil?
+        self.entries[related_entry_key]
+      end
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_entry.rb

@@ -0,0 +1,68 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'sax-machine'
+require 'ce-greenbutton/elements/gb_content'
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the Entry structure
+    #
+    # For example:
+    #   entry = GbEntry.parse(open(entry.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbEntry
+      include SAXMachine
+
+      # The related entries. It is a hash {entry_type => entry_url}
+      #   entry_urls are the href value of the link element with type "related"
+      attr_accessor :related
+
+      # The entry type, e.g. UsagePoint, IntervalBlock,...etc
+      attr_accessor :type
+
+      # Extract the href of the parent Entry
+      element :link, as: :up, value: :href,  with: {rel: 'up'}
+
+      # Extract the href of this Entry
+      # The type is inferred from this href
+      element :link, as: :self, value: :href,  with: {rel: 'self'} do |url|
+        self.type = entry_type url
+        url
+      end
+
+      # Extract the related Entries to the :related hash.
+      elements :link, value: :href,  with: {rel: 'related'} do |url|
+        if self.related.nil?
+          self.related = {}
+        end
+        type = entry_type url
+        unless type.nil?
+          self.related[type] = url
+        end
+      end
+
+      element :content, class: GbContent
+
+      element :updated do |updated|
+        DateTime.parse(updated).to_time
+      end
+
+      # Helper method to infer the entry type from the given url.
+      #
+      # url - the url
+      #
+      # Returns the entry type, e.g. UsagePoint, IntervalBlock,...etc
+      private
+      def entry_type(url)
+        match = /\/(\w+)(\/(\d+))*$/.match(url)
+        if match.nil?
+          nil
+        else
+          match[1]
+        end
+      end
+
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_interval.rb

@@ -0,0 +1,21 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'sax-machine'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:Interval structure
+    #
+    # For example:
+    #   interval = GbInterval.parse(open(interval.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbInterval
+      include SAXMachine
+      element :'espi:duration', class: Integer,  as: :duration
+      element :'espi:start',  class: Integer, as: :start
+    end
+
+  end
+end

data/lib/ce-greenbutton/elements/gb_interval_block.rb

@@ -0,0 +1,24 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'sax-machine'
+require 'ce-greenbutton/elements/gb_interval'
+require 'ce-greenbutton/elements/gb_interval_reading'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:IntervalBlock structure
+    #
+    # For example:
+    #   interval_block = GbIntervalBlock.parse(open(interval_block.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbIntervalBlock
+      include SAXMachine
+      element :'espi:interval', class: GbInterval, as: :interval
+      elements :'espi:IntervalReading', class: GbIntervalReading, as: :readings
+    end
+
+  end
+end

data/lib/ce-greenbutton/elements/gb_interval_reading.rb

@@ -0,0 +1,22 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'sax-machine'
+require 'ce-greenbutton/elements/gb_interval'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:IntervalReading structure
+    #
+    # For example:
+    #   interval_reading = GbIntervalReading.parse(open(interval_reading.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbIntervalReading < GbInterval
+      include SAXMachine
+      element :'espi:value', class: Integer, as: :value
+      element :'espi:cost', class: Integer, as: :cost
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_local_time_parameters.rb

@@ -0,0 +1,50 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'sax-machine'
+require 'ce-greenbutton/utils'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:LocalTimeParameters structure
+    #
+    # For example:
+    #   local_time_parameters = GbLocalTimeParameters.parse(open(local_time_parameters.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbLocalTimeParameters
+      include SAXMachine
+      include Utils::DSTRule
+
+      attr_accessor :dst_start_time
+      attr_accessor :dst_end_time
+
+      element :'espi:dstEndRule', as: :dst_end_rule do |rule|
+        @dst_end_time = to_time(rule)
+        rule
+      end
+      element :'espi:dstStartRule', as: :dst_start_rule do |rule|
+        @dst_start_time = to_time(rule)
+        rule
+      end
+      element :'espi:dstOffset', class: Integer, as: :dst_offset
+      element :'espi:tzOffset', class: Integer, as: :tz_offset
+
+      # Converts time to local based on the given time configuration.
+      #
+      # The time after applying the rules in the time_config
+      #
+      def local_time(time)
+        # apply timezone offset
+        time += self.tz_offset
+        # apply dst offset
+        if Time.now.between?(@dst_start_time, @dst_end_time)
+          time += self.dst_offset
+        end
+        Time.at(time)
+      end
+    end
+
+  end
+end

data/lib/ce-greenbutton/elements/gb_reading_type.rb

@@ -0,0 +1,23 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'sax-machine'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:ReadingType structure
+    #
+    # For example:
+    #   reading_type = GbReadingType.parse(open(reading_type.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbReadingType
+      include SAXMachine
+      element :'espi:commodity', class: Integer, as: :commodity
+      element :'espi:currency', class: Integer, as: :currency
+      element :'espi:uom', class: Integer, as: :uom
+      element :'espi:powerOfTenMultiplier', class: Integer, as: :power_of_ten_multiplier
+    end
+  end
+end

data/lib/ce-greenbutton/elements/gb_usage_point.rb

@@ -0,0 +1,20 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'sax-machine'
+
+module GreenButton
+  module Parser
+    # a sax-machine mapping for the espi:UsagePoint structure
+    #
+    # For example:
+    #   usage_point = GbUsagePoint.parse(open(usage_point.xml))
+    #
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    class GbUsagePoint
+      include SAXMachine
+      element :'espi:kind', class: Integer, as: :kind
+    end
+  end
+end

data/lib/ce-greenbutton/interpreters/electricity_interpreter.rb

@@ -0,0 +1,114 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+
+require 'date'
+require 'ce-greenbutton'
+require 'ce-greenbutton/model/gb_data_description'
+require 'ce-greenbutton/model/gb_data'
+require 'ce-greenbutton/model/gb_data_reading'
+
+module GreenButton
+  module Interpreters
+    # An interpreter for the Electricity GreenButton data. It can be registered
+    # to the GreenButton module by calling GreenButton.register_interpreter.
+    #
+    # The interpreter will be called by the GreenButton module to interpret the
+    # electricity GreenButton data (kind = 0)
+    #
+    # For example:
+    #   # This call will bind this interpreter to the GreenButton data of kind=0
+    #   GreenButton.register_interpreter(0,:electricity)
+    #
+    # Author: ahmed.seddiq
+    # Version: 1.0
+    #
+    module ElectricityInterpreter
+
+      # Maps the parsed GbUsagePoint to the equivalent GbDataDescription.
+      #
+      # usage_point - The parsed GbUsagePoint.
+      # feed        - The parsed GbDataFeed. It is used to resolve related
+      #                 entries in the usage_point hierarchy.
+      #
+      # Returns the newly created GbDataDescription instance.
+      #
+      def self.get_gb_data_description (usage_point, feed)
+        gb_data_description = GbDataDescription.new
+        gb_data_description.updated = usage_point.updated
+
+        meter_readings = feed.get_related(usage_point, 'MeterReading')
+        raise GreenButton::InvalidGbDataError, 'Missing MeterReading data' if meter_readings.nil?
+
+        time_config = feed.get_related(usage_point, 'LocalTimeParameters')
+        raise GreenButton::InvalidGbDataError, 'Missing LocalTimeParameters data' if time_config.nil?
+
+        # get the actual time parameters from the entry.content
+        time_config = time_config.content.local_time_parameters
+
+        # We can have multiple meter readings per usage point.
+        unless meter_readings.is_a? Array
+          meter_readings = [meter_readings]
+        end
+        meter_readings.each do |meter_reading|
+          interpret_meter_reading(gb_data_description, meter_reading,
+                                  time_config, feed)
+        end
+
+        gb_data_description
+      end
+
+      # Interprets a single MeterReading structure. It will append all interpreted
+      # GbData instances to gb_data_description.gb_data_array.
+      #
+      # gb_data_description - the GbDataDescription under construction now.
+      # meter_reading       - the GbEntry describing the MeterReading structure.
+      # time_config         - the GbLocalTimeParameters used to convert time
+      #                         values to local.
+      # feed                - the parsed GbDataFeed, used to resolve any related
+      #                         GbEntries
+      #
+      # Returns Nothing.
+      #
+      private
+      def self.interpret_meter_reading(gb_data_description, meter_reading,
+          time_config, feed)
+        reading_type = feed.get_related(meter_reading, 'ReadingType')
+        raise GreenButton::InvalidGbDataError, 'Missing ReadingType data' if reading_type.nil?
+
+        reading_type = reading_type.content.reading_type
+        gb_data_description.commodity = reading_type.commodity
+        gb_data_description.currency = reading_type.currency
+        gb_data_description.unit_of_measure = reading_type.uom
+        gb_data_description.power_of_ten_multiplier =
+            reading_type.power_of_ten_multiplier
+
+        # interval blocks
+        interval_blocks = feed.get_related(meter_reading, 'IntervalBlock') || []
+
+        if gb_data_description.gb_data_array.nil?
+          gb_data_description.gb_data_array = []
+        end
+        updated = gb_data_description.updated
+        interval_blocks.each do |interval_block|
+          updated = interval_block.updated if interval_block.updated > updated
+          interval_block = interval_block.content.interval_block
+          gb_data = GbData.new
+          gb_data.gb_data_description = gb_data_description
+          gb_data.time_duration = interval_block.interval.duration
+          gb_data.time_start = time_config.local_time(interval_block.interval.start)
+          gb_data.interval_readings = []
+          interval_block.readings.each do |reading|
+            gb_data_reading = GbDataReading.new
+            gb_data_reading.time_duration = reading.duration
+            gb_data_reading.time_start = time_config.local_time(reading.start)
+            gb_data_reading.value = reading.value
+            gb_data_reading.cost = reading.cost
+            gb_data.interval_readings << gb_data_reading
+          end
+          gb_data_description.gb_data_array << gb_data
+        end
+        gb_data_description.updated = time_config.local_time(updated.to_time.to_i)
+      end
+
+    end
+  end
+end

data/lib/ce-greenbutton/model/gb_data.rb

@@ -0,0 +1,30 @@
+# Copyright (C) 2015 TopCoder Inc., All Rights Reserved.
+require 'ce-greenbutton/utils'
+
+# Represents an IntervalBlock structure.
+#
+# Author TCSASSEMBLER
+# Version 1.0
+class GbData
+  include Utils::Hash
+
+  # A reference to the owner GbDataDescription
+  attr_accessor :gb_data_description
+
+  # Represents the start time (local) value from the IntervalBlock -> Interval
+  # structure
+  attr_accessor :time_start
+
+  # Represents the duration value from the IntervalBlock -> Interval structure
+  attr_accessor :time_duration
+
+  # An array of GbDataReading
+  attr_accessor :interval_readings
+
+  # Returns the parsed elements as a hash with key equals the property name and
+  # value equals the parsed value.
+  def _parse
+    to_hash
+  end
+
+end