flukso4r 0.1.2 → 0.2.0

data/README.rdoc

@@ -11,6 +11,30 @@ meter. A simple call to retrieve the readings of the last day is:
 
 flukso_query -t day -u watt -a <your-sensor-alias>
 
+In addition, the library includes two scripts that can be used to
+archive your Flukso readings at the highest resolution. The values are
+stored in an sqlite3 database.
+
+First, copy the flukso4rrc template file to a destination of your
+liking:
+
+$ cp etc/flukso4rrc $HOME/.flukso4rrc
+
+Then, edit the file and specify the database file and your API key.
+Please note that the library uses HTTPS to communicate with the Flukso
+webservice, so your API key is not sent unencrypted over the net.
+
+Then, create an empty database:
+
+$ flukso_create_db -c <CONFIG_FILE>
+
+After the DB has been created, you can add new data with the command
+
+$ flukso_archive_watts -c <CONFIG_FILE>
+
+This command will download all values of the last hour and add the new
+ones to the database. It is intended to be run as a cronjob.
+
 The code in lib is a cheap knockoff of the twitter ruby gem - many
 thanks to John Nunemaker! You can find the twitter ruby gem here:
 
@@ -18,7 +42,6 @@ http://twitter.rubyforge.org/
 
 == TODO
 
-* There is no authentication implemented currently.
 * Tests of the internals are needed.
 
 == Note on Patches/Pull Requests

data/Rakefile

@@ -11,12 +11,13 @@ begin
     gem.homepage = "http://gonium.net/md/flukso4r"
     gem.authors = ["Mathias Dalheimer"]
     gem.bindir = 'bin'
-    gem.executables = ['flukso_query']
+    gem.executables = ['flukso_query', 'flukso_archive_watts', 'flukso_create_db']
     gem.default_executable = 'flukso_query'
     gem.files = FileList["[A-Z]*", "{bin,lib,test}/**/*"]
      
     #gem.add_dependency('oauth', '~> 0.3.6')
     gem.add_dependency('httparty', '~> 0.4.3')
+    gem.add_dependency('sqlite3-ruby', '~> 1.2.5')
     #gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/bin/flukso_archive_watts

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+###
+## 
+# flukso4r: A Ruby library for Flukso 
+# Copyright (C) 2010 Mathias Dalheimer (md@gonium.net)
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#  
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+##
+###
+
+# Read the flukso4r location 
+libpath=File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift << libpath 
+#puts "Using libraty path #{$:.join(":")}" 
+
+require 'flukso'
+require 'optparse'
+require 'ostruct'
+
+###
+## Commandline parser
+#
+class Optparser
+  CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
+  CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
+  #
+  # Return a structure describing the options.
+  #
+  def self.parse(args)
+    # The options specified on the command line will be collected in *options*.
+    # We set default values here.
+    options = OpenStruct.new
+    options.inplace = false
+    options.encoding = "utf8"
+    options.verbose = false
+    opts = OptionParser.new do |opts|
+      opts.banner = "Usage: #{$0} [options]"
+      opts.separator ""
+      opts.separator "Specific options:"
+      opts.on("-c", "--config FILE", "The file where the configuration lives.") do |file|
+        options.config_file = file
+      end
+      # Boolean switch.
+      opts.on("-v", "--verbose", "Run verbosely") do |v|
+        options.verbose = v
+      end
+      opts.on_tail("-h", "--help", "Show this message") do
+        puts opts
+        exit
+      end
+    end
+    opts.parse!(args)
+    options
+  end
+end
+
+###
+## Script startup
+#
+options = Optparser.parse(ARGV)
+$verbose = options.verbose
+if options.config_file == nil
+  puts "Please provide a configuration file... (-h for details)."
+  exit(-1);
+end
+if not File.exists?(options.config_file) 
+  puts " Configuration file #{options.config_file} not found - no database configuration available!"
+  exit(-3);
+else
+  $CONFIG=YAML.load_file(options.config_file);
+  puts "Using this configuration:" if $verbose
+  puts "#{$CONFIG}" if $verbose
+  dbfile=$CONFIG['DB_FILE']
+end
+if $verbose
+  puts " Using database file #{dbfile}"
+end
+# check and expand paths.
+if not File.exists?(dbfile)
+  puts " Database does not exist - please create one. Aborting."
+  exit(-2);
+end
+
+
+# No authentication by now.
+auth=Flukso::HTTPAuth.new("", "");
+api=Flukso::API.new(auth);
+query=Flukso::QueryReadings.new($CONFIG["ACCESS_KEY"], :hour, :watt)
+begin
+  readings=query.execute(api);
+rescue Exception => e
+  puts "Query failed: #{e}"
+  exit(-10);
+end
+
+# Remove NaN elements - NaN Handling in Ruby sucks.
+clean_readings = readings.map{|reading|
+  #puts "checking #{reading.value} of class #{reading.value.class}"
+  if reading.value.class==Float 
+    if reading.value.nan?
+      nil;
+    else
+      reading
+    end
+  else
+    reading;
+  end
+}.compact
+
+if $verbose
+  clean_readings.each{|reading|
+    puts reading
+  }
+end
+
+db=Flukso::FluksoDB.open($CONFIG["DB_FILE"], $CONFIG["DB_TABLE_NAME"]);
+begin
+  last=db.find_reading_last();
+  puts "Last reading: #{last}"
+rescue Flukso::ElementNotFoundError => e
+  puts "Empty database - not able to provide last reading."
+end
+insertCount = db.appendNewReadings(clean_readings);
+puts "Added #{insertCount} new readings to the database."
+db.close

data/bin/flukso_create_db

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# This file is part of fluksobot
+# (c) 2009 Mathias Dalheimer, md@gonium.net
+#
+# FluksoBot is free software; you can 
+# redistribute it and/or modify it under the terms of the GNU General Public 
+# License as published by the Free Software Foundation; either version 2 of 
+# the License, or any later version.
+#
+# FluksoBot is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with FluksoBot; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+# Read the fluksobot location 
+libpath=File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift << libpath 
+#puts "Using libraty path #{$:.join(":")}" 
+
+require 'rubygems'
+require 'optparse'
+require 'ostruct'
+require 'flukso'
+
+###
+## Commandline parser
+#
+class Optparser
+  CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
+  CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
+  #
+  # Return a structure describing the options.
+  #
+  def self.parse(args)
+    # The options specified on the command line will be collected in *options*.
+    # We set default values here.
+    options = OpenStruct.new
+    options.inplace = false
+    options.encoding = "utf8"
+    options.verbose = false
+    opts = OptionParser.new do |opts|
+      opts.banner = "Usage: #{$0} [options]"
+      opts.separator ""
+      opts.separator "Specific options:"
+    opts.on("-c", "--config FILE", "The configuration file to use.") do |file|
+      options.config_file = file 
+    end
+    # Boolean switch.
+    opts.on("-f", "--force", "Ignore warnings") do |f|
+      options.force = f 
+    end
+    opts.on("-v", "--verbose", "Run verbosely") do |v|
+      options.verbose = v
+    end
+    opts.on_tail("-h", "--help", "Show this message") do
+      puts opts
+      exit
+    end
+  end
+  opts.parse!(args)
+  options
+end
+end
+
+###
+## Script startup
+#
+options = Optparser.parse(ARGV)
+$verbose = options.verbose
+$force = options.force
+puts "FluksoBot database setup script."
+if options.config_file == nil
+  puts "Please provide a configuration file... (-h for details)."
+  exit(-1);
+end
+if not File.exists?(options.config_file) 
+  puts " Configuration file #{options.config_file} not found - no database configuration available!"
+  exit(-3);
+else
+  $CONFIG=YAML.load_file(options.config_file);
+  puts "Using this configuration:" if $verbose
+  puts "#{$CONFIG}" if $verbose
+  dbfile=$CONFIG['DB_FILE']
+end
+if $verbose
+  puts " Using database file #{dbfile}"
+end
+# check and expand paths.
+if File.exists?(dbfile) and not $force
+  puts " Database already exists. Aborting."
+  exit(-2);
+end
+
+# The database does not exist. Create the DB and populate it with 
+# tables.
+begin
+  db=Flukso::FluksoDB.create(dbfile, $CONFIG['DB_TABLE_NAME']);
+  db.close();
+  puts "Success."
+rescue Exception => e
+  puts "Failed to initialize db: #{e}"
+  puts "Backtrace:" if $verbose
+  puts e.backtrace if $verbose
+end
+

data/bin/flukso_query

@@ -49,15 +49,12 @@ class Optparser
       opts.banner = "Usage: #{$0} [options]"
       opts.separator ""
       opts.separator "Specific options:"
-      opts.on("-t", "--timerange VALUE", "The time range you want to query. Valid queries are: {hour, day, month, year}") do |timerange|
+      opts.on("-t", "--timerange VALUE", "The time range you want to query. Valid queries are: {hour, day, month, year, night}") do |timerange|
         options.timerange = timerange 
       end
       opts.on("-u", "--unit VALUE", "The unit you want to query. Valid queries are: {watt, kwh, eur, aud}") do |unit|
         options.unit = unit 
       end
-      opts.on("-u", "--unit VALUE", "The unit you want to query. Valid queries are: {watt, kwh, eur, aud}") do |unit|
-        options.unit = unit 
-      end
       opts.on("-a", "--alias VALUE", "The device alias you want to query.") do |alias_id|
         options.alias_id = alias_id
       end
@@ -89,6 +86,8 @@ when /^month$/i
   range=:month
 when /^year$/i
   range=:year
+when /^night$/i
+  range=:night
 else begin
   puts "Invalid timerange: #{options.timerange} - see -h for more information."
   exit(-1);

data/lib/flukso/api.rb

@@ -25,7 +25,7 @@ module Flukso
     def initialize(alias_id, timerange=:hour, unit=:watt)
       @alias_id=alias_id;
       # sanity checks.
-      valid_timeranges=[:hour, :day, :month, :year];
+      valid_timeranges=[:hour, :day, :month, :year, :night];
       valid_units=[:watt, :kwh, :eur, :aud];
       raise Flukso::General, "Invalid timerange #{timerange}" unless valid_timeranges.include?(timerange);
       raise Flukso::General, "Invalid unit #{unit}" unless valid_units.include?(unit);
@@ -52,24 +52,6 @@ module Flukso
     end
   end
 
-  class UTCReading
-    attr_accessor :utc_timestamp, :value
-    def initialize(utc_timestamp, value)
-      # sanity checks.
-      raise Flukso::General, "Invalid reading timestamp: #{utc_timestamp}" if utc_timestamp < 0; 
-      #raise Flukso::General, "Invalid reading value: #{value}" if value.class != Fixnum || value < 0;
-      @utc_timestamp = utc_timestamp.to_i;
-      if value =~ /^nan$/i
-        @value=0.0/0.0  # Workaround: Ruby does not allow to assign NaN directly.
-      else
-        @value = value
-      end
-    end
-    def to_s
-      return "#{@utc_timestamp} -> #{@value}"
-    end
-  end
-
   class API
     extend Forwardable
 

data/lib/flukso/database.rb

@@ -0,0 +1,163 @@
+###
+##
+# flukso4r: A Ruby library for Flukso 
+# (c) 2010 Mathias Dalheimer, md@gonium.net
+#
+# Flukso4r is free software; you can 
+# redistribute it and/or modify it under the terms of the GNU General Public 
+# License as published by the Free Software Foundation; either version 2 of 
+# the License, or any later version.
+#
+# Flukso4r is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with CGWG; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+module Flukso
+  require 'sqlite3'
+  require 'flukso'
+
+  DB_SCHEMA=<<-SQL
+    create table :::TABLE_NAME::: (
+      EPOCHTIME integer primary key,
+      VALUE integer not null
+    );
+SQL
+
+
+  class FluksoDB
+    # create a new database
+    def self.create(filename, tablename)
+      filename=String.new(File.expand_path(filename));
+      if File.exists?(filename)
+        raise "Database file #{filename} already exists."
+      end
+      puts "Creating new database file #{filename}" if $verbose
+      db = SQLite3::Database.open(filename)
+      schema = FluksoDB.fill_template( DB_SCHEMA, { 'TABLE_NAME' => tablename} )
+      db.execute_batch(schema)
+      return FluksoDB.new(db, tablename);
+    end
+    # open an existing database
+    def self.open(filename, tablename)
+      filename=File.expand_path(filename);
+      if not File.exists?(filename)
+        raise "Database file #{filename} does not exist."
+      end
+      db = SQLite3::Database.open( filename)
+      return FluksoDB.new(db, tablename);
+    end
+    # See: http://freshmeat.net/articles/templates-in-ruby
+    # template: Returns a string formed from a template and replacement values
+    #
+    # templateStr - The template string (format shown below)
+    # values - A hash of replacement values
+    #
+    # Example format:
+    #   "Dear :::customer:::,\nPlease pay us :::amount:::.\n"
+    #
+    # The "customer" and "amount" strings are used as keys to index against the
+    # values hash.
+    #
+    def self.fill_template( templateStr, values )
+      outStr = templateStr.clone()
+      values.keys.each { |key|
+        outStr.gsub!( /:::#{key}:::/, values[ key ] )
+      }
+      outStr
+    end
+    # constuctor: give SQLite::Database object as argument. see class
+    # methods.
+    def initialize(db, tablename)
+      @tablename=tablename
+      @db=db;
+      @db.results_as_hash = true
+    end
+    def close
+      @db.close;
+    end
+    # Appends the readings of the provided array to the database.
+    def appendNewReadings(readings)
+      insertCounter=0
+      last_timestamp=0
+      begin
+        last_reading=find_reading_last();
+        last_timestamp=last_reading.utc_timestamp;
+      rescue Flukso::ElementNotFoundError => e
+        puts "Empty database - not able to provide last reading."
+      end
+      readings.each{|reading|
+        if reading.utc_timestamp > last_timestamp
+          puts "Appending #{reading}" if $verbose
+          storeReading(reading);
+          insertCounter += 1
+        else
+          puts "Skipping reading at #{reading.utc_timestamp}, already in DB." if $verbose
+        end
+      }
+      return insertCounter
+    end
+    def storeReading(reading)
+      # TODO: Make this more efficient, recycle insert statements.
+      if reading.class != UTCReading
+        raise "Must give a UTCReading instance."
+      end
+      stmt=<<-SQL
+      INSERT INTO #{@tablename}
+      VALUES ('#{reading.utc_timestamp}', '#{reading.value}'); 
+      SQL
+      @db.execute(stmt)
+    end
+    def find_reading_last_five
+      return find_last_reading(5);
+    end
+    def find_reading_last
+      return find_last_reading(1)[0];
+    end
+    def find_last_reading(amount)
+      if not amount.class==Fixnum
+        raise "Must provide the number of last readings desired as an Fixnum."
+      end
+      stmt=<<-SQL
+      SELECT * FROM #{@tablename}
+      order by epochtime DESC limit #{amount};
+      SQL
+      #puts "Using statement #{stmt}" if $verbose
+      readings=Array.new
+      @db.execute(stmt) {|row|
+        value=row['VALUE'].to_f;
+        #timestamp=Time.at(row['EPOCHTIME'].to_f);
+        timestamp=row['EPOCHTIME'].to_f;
+        #puts "Creating new UTCReading: #{timestamp}, #{value}"
+        reading=UTCReading.new(timestamp, value);
+        readings << reading
+      }
+      if readings.empty?
+        raise ElementNotFoundError
+      end
+      return readings;
+    end
+    def find_reading_by_epochtime(time)
+      stmt=<<-SQL
+        SELECT * FROM #{@tablename}
+        WHERE epochtime ='#{time}';
+      SQL
+      readings=Array.new
+      @db.execute(stmt) {|row|
+        reading=UTCReading.new(row['TIMESTAMP'].to_i, row['VALUE'].to_i)
+        readings << reading
+      }
+      if readings.empty?
+        raise ElementNotFoundError
+      end
+      return readings[0];
+    end
+  end
+
+      class ElementNotFoundError < RuntimeError
+      end
+    end

data/lib/flukso/reading.rb

@@ -0,0 +1,43 @@
+###
+## 
+# flukso4r: A Ruby library for Flukso 
+# Copyright (C) 2010 Mathias Dalheimer (md@gonium.net)
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#  
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+##
+###
+
+
+module Flukso
+ 
+  class UTCReading
+    attr_accessor :utc_timestamp, :value
+    def initialize(utc_timestamp, value)
+      # sanity checks.
+      raise Flukso::General, "Invalid reading timestamp: #{utc_timestamp}" if utc_timestamp < 0; 
+      #raise Flukso::General, "Invalid reading value: #{value}" if value.class != Fixnum || value < 0;
+      @utc_timestamp = utc_timestamp.to_i;
+      if value =~ /^nan$/i
+        @value=0.0/0.0  # Workaround: Ruby does not allow to assign NaN directly.
+      else
+        @value = value
+      end
+    end
+    def to_s
+      return "#{@utc_timestamp} -> #{@value}"
+    end
+  end
+
+end

data/lib/flukso.rb

@@ -43,12 +43,14 @@ module Flukso
   class Unavailable < StandardError; end
   class InformFlukso < StandardError; end
   class NotFound < StandardError; end
-
-  BASE_SENSOR_URL = "http://api.flukso.net/sensor"
+  # Use only the encrypted endpoint.
+  BASE_SENSOR_URL = "https://api.flukso.net/sensor"
 end
  
 directory = File.expand_path(File.dirname(__FILE__))
  
 require File.join(directory, 'flukso', 'http_auth')
+require File.join(directory, 'flukso', 'reading')
 require File.join(directory, 'flukso', 'request')
 require File.join(directory, 'flukso', 'api')
+require File.join(directory, 'flukso', 'database')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: flukso4r
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Mathias Dalheimer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-07 00:00:00 +01:00
+date: 2010-02-15 00:00:00 +01:00
 default_executable: flukso_query
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,10 +22,22 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.4.3
     version: 
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.2.5
+    version: 
 description: This gem provides a library for the Flukso API. See http://flukso.net for more information.
 email: md@gonium.net
 executables: 
 - flukso_query
+- flukso_archive_watts
+- flukso_create_db
 extensions: []
 
 extra_rdoc_files: 
@@ -36,10 +48,14 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- bin/flukso_archive_watts
+- bin/flukso_create_db
 - bin/flukso_query
 - lib/flukso.rb
 - lib/flukso/api.rb
+- lib/flukso/database.rb
 - lib/flukso/http_auth.rb
+- lib/flukso/reading.rb
 - lib/flukso/request.rb
 - test/helper.rb
 - test/test_flukso4r.rb