Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Switch to using yardoc for documentation.

  • Loading branch information...
commit b5e4a3c48c722e0862585551f2d60d63e8c79d80 1 parent 6c9eecf
@mcolyer authored
View
2  .gitignore
@@ -3,6 +3,8 @@
.bundle/*
.rvmrc
docs/*
+doc/*
+.yardoc/*
data/*
pkg/*
vendor/gems/*
View
1  .yardopts
@@ -0,0 +1 @@
+--no-private --protected lib/**/*.rb - README LICENSE
View
17 README.md
@@ -15,6 +15,23 @@ Getting Started
gem install smartermeter
smartermeter
+Manipulating the data
+---------------------
+
+After you've successfully downloaded one set of data, you should be able
+to manipulate it using ruby like so:
+
+ require 'rubygems'
+ require 'smartermeter'
+
+ config = YAML.load_file(File.expand_path("~/.smartermeter"))
+ csv_file = Dir.glob(File.join(config[:data_dir], "*.csv")).last
+
+ samples = SmarterMeter::Samples.parse_csv(csv_file)
+ kwh_used = samples.total_kwh
+ api = SmarterMeter::Services::BrighterPlanet.new
+ puts api.calculate_kg_carbon(kwh_used)
+
Google PowerMeter
-----------------
View
1  lib/smartermeter/daemon.rb
@@ -4,6 +4,7 @@
require 'date'
module SmarterMeter
+ # @private
class Daemon
def initialize(interface)
View
2  lib/smartermeter/interfaces/swing.rb
@@ -3,6 +3,7 @@
require 'profligacy/lel'
module SmarterMeter
+ # @private
module Interfaces
class Swing
include_package "java.awt"
@@ -147,6 +148,7 @@ def initialize(&block)
end
end
+ # @private
class Wizard
include_package "javax.swing"
include_package "java.awt"
View
23 lib/smartermeter/sample.rb
@@ -2,29 +2,40 @@
require 'time'
module SmarterMeter
+ # Represents a single hourly sample taken from the PG&E hourly electricity
+ # data. It's the most basic data unit of SmarterMeter.
class Sample
attr_accessor :time, :kwh
+ # Creates a new Sample.
+ #
+ # @param [Time] time the start of the sample period.
+ # @param [Float] kwh the number of killowatt hours used during the period of this sample.
+ # @return [Sample] the new Sample.
def initialize(time, kwh)
@time = time
@kwh = kwh
end
- # Public: The start time of this measurement
+ # The start time of this measurement in UTC.
#
- # Returns the time in the format of 2011-01-06T09:00:00.000Z
+ # @return [String] the time in the format of 2011-01-06T09:00:00.000Z
def utc_start_time
@time.utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")
end
- # Public: The stop time of this measurement, it's assumed to be 1 hour after
- # the start.
+ # The stop time of this measurement in UTC. It's assumed to be 1 hour after
+ # the start as that is the current resolution of PG&E's data.
#
- # Returns the time in the format of 2011-01-06T09:00:00.000Z
+ # @return [String] the time in the format of 2011-01-06T09:00:00.000Z
def utc_stop_time
- (@time + 60*60).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")
+ one_hour = 60*60
+ (@time + one_hour).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")
end
+ # Interrogates the current state of the Sample.
+ #
+ # Returns [String] a compact representation of the Sample.
def inspect
"<Sample #{@time} #{@kwh}>"
end
View
22 lib/smartermeter/samples.rb
@@ -2,12 +2,13 @@
require 'time'
module SmarterMeter
+ # Represents a collection of samples. In some cases it's useful to operate on
+ # groups of samples and this class provides that functionality.
class Samples < Hash
- # Parses the CSV returned by PG&E
+ # Parses the CSV returned by PG&E and creates a Samples collection.
#
- # data - The string containing the CSV returned by PG&E
- #
- # Returns a Hash of with keys as Date objects and values of Arrays of samples.
+ # @param [String] data the string containing the CSV returned by PG&E
+ # @return [Samples] creates a Samples collection from the given data.
def self.parse_csv(data)
samples = Samples.new
date_re = /([0-9]{1,2})\/([0-9]{1,2})\/([0-9]{4})/
@@ -41,21 +42,18 @@ def self.parse_csv(data)
samples
end
- # Public: Calculates the total number of kilowatt hours
+ # Calculates the total number of kilowatt hours for all samples.
#
- # Returns a floating point number representing the sum of kilowatt hours
- # for all samples within this collection. If no samples are found 0 is
- # returned.
+ # @return [Float] the sum of kilowatt hours for all samples within this collection. If no samples are found 0 is returned.
def total_kwh
self.keys.reduce(0) { |sum, d| sum + total_kwh_on(d) }
end
- # Public: Calculates the total number of kilowatt hours
+ # Calculates the total number of kilowatt hours
#
- # date - The date of the samples to include within the total.
+ # @param [Date] date The date of the samples to include within the total.
#
- # Returns a floating point number representing the sum of kilowatt hours
- # for samples made of the given day. If none are found 0 is returned.
+ # @return [Float] the sum of kilowatt hours for samples made of the given day. If none are found 0 is returned.
def total_kwh_on(date)
if self[date]
self[date].reduce(0) { |sum, s| sum + (s.kwh or 0) }
View
23 lib/smartermeter/service.rb
@@ -2,12 +2,21 @@
require 'csv'
module SmarterMeter
+ # Provides access to the PG&E SmartMeter data through a ruby interface. This
+ # class depends on the PG&E website to function the same that it does today,
+ # so if something stops working its likely that something changed on PG&E's
+ # site and this class will need to be adapted.
class Service
LOGIN_URL = "http://www.pge.com/myhome/"
OVERVIEW_URL = "https://www.pge.com/csol/actions/login.do?aw"
ENERGYGUIDE_AUTH_URL = "https://www.energyguide.com/LoadAnalysis/LoadAnalysis.aspx?Referrerid=154"
+ # Provides access to the last page retrieved by mechanize. Useful for
+ # debugging and reporting errors.
attr_reader :last_page
+
+ # Provides access to the last exception thrown while accessing PG&E's site.
+ # Useful for debugging/error reporting.
attr_reader :last_exception
def initialize
@@ -16,7 +25,10 @@ def initialize
}
end
- # Returns true upon succesful login and false otherwise
+ # Authenticates to the PG&E's website. Only needs to be performed once per
+ # instance of this class.
+ #
+ # @return [Boolean] true upon succesful login and false otherwise
def login(username, password)
begin
@agent.get(LOGIN_URL) do |page|
@@ -61,6 +73,15 @@ def login(username, password)
end
end
+ # Downloads a CSV containing hourly date on that date. Up to a week worth
+ # of other data will be included depending on which day of the week that
+ # you request.
+ #
+ # PG&E compiles this data on a weekly schedule so if you ask for Monday
+ # you'll get the previous Sunday and the following days upto the next
+ # Sunday.
+ #
+ # @return [String] the CSV data.
def fetch_csv(date)
raise RuntimeException, "login must be called before fetch_csv" unless @authenticated
View
32 lib/smartermeter/services/brighterplanet.rb
@@ -4,13 +4,45 @@
module SmarterMeter
module Services
+ # Allows users to calculate the carbon produced by their energy usage by
+ # accessing the Brighter Planet CM1 Electricity API.
+ #
+ # More details can be found here:
+ # http://carbon.brighterplanet.com/models/electricity_use
+ #
+ # Example:
+ # api = SmarterMeter::Services::BrighterPlanet.new
+ # puts api.calculate_kg_carbon(10.1)
+ #
+ # Prints:
+ # 0.6460529833458619
+ #
class BrighterPlanet
+ # The api key required for commericial access to the API. For more detail see:
+ # http://carbon.brighterplanet.com/pricing
attr_accessor :api_key
+ # Initializes the Brigher Planet CM1 Electricity API.
+ #
+ # Example:
+ #
+ # SmarterMeter::Services::BrighterPlanet.new do |c|
+ # c.api_key = "key"
+ # end
+ #
+ # @return [BrighterPlanet]
def initialize
yield self if block_given?
end
+ # Calculates the number of kilograms of carbon produced from the given
+ # electrical energy usage.
+ #
+ # Note: this is an estimate and depends on many factors, to improve
+ # accuracy include an optional zipcode of where this energy was consumed.
+ #
+ # @param [Float] kwh the number of kilowatt hours consumed.
+ # @return [Float] kilograms of carbon produced by this much energy.
def calculate_kg_carbon(kwh)
response = RestClient.get 'http://carbon.brighterplanet.com/electricity_uses.json', :energy => kwh
JSON.parse(response.body)["emission"]
Please sign in to comment.
Something went wrong with that request. Please try again.