tempoiq 1.0.0

data/lib/tempoiq/constants.rb

@@ -0,0 +1,6 @@
+module TempoIQ
+  module Constants
+    VERSION = "1.0.0"
+    TRUSTED_CERT_FILE = File.join(File.dirname(__FILE__), "..", "trusted-certs.crt")
+  end
+end

data/lib/tempoiq/models/bulk_write.rb

@@ -0,0 +1,31 @@
+module TempoIQ
+  # Used to write DataPoints into your TempoIQ backend.
+  class BulkWrite
+    def initialize
+      @writes = Hash.new do |sensors, device_key|
+        sensors[device_key] = Hash.new do |points, sensor_key|
+          points[sensor_key] = []
+        end
+      end
+    end
+
+    # Alias for #add
+    def <<(device_key, sensor_key, datapoint)
+      add(device_key, sensor_key, datapoint)
+    end
+
+    # Add a DataPoint to the request
+    #
+    # * +device_key+ [String] - The device key to write to
+    # * +sensor_key+ [String] - The sensor key within the device to write to
+    # * +datapoint+ [DataPoint] - The datapoint to write
+    def add(device_key, sensor_key, datapoint)
+      @writes[device_key][sensor_key] << datapoint.to_hash
+    end
+
+    def to_hash
+      @writes
+    end
+  end
+end
+

data/lib/tempoiq/models/cursor.rb

@@ -0,0 +1,48 @@
+require 'enumerator'
+require 'json'
+
+module TempoIQ
+  # Cursor is an abstraction over a sequence / stream of objects. It
+  # uses lazy iteration to transparently fetch segments of data from
+  # the server.
+  #
+  # It implements the Enumerable interface, which means convenience functions
+  # such as Enumerable#to_a are available if you know you're working with a 
+  # small enough segment of data that can reasonably fit in memory.
+  class Cursor
+    PAGE_LINK = "next_page"
+    NEXT_QUERY = "next_query"
+
+    attr_reader :remoter, :route, :query, :headers, :segment_key
+
+    include Enumerable
+
+    def initialize(klass, remoter, route, query, headers = {}, segment_key = "data")
+      @klass = klass
+      @remoter = remoter
+      @route = route
+      @query = query
+      @headers = headers
+      @segment_key = segment_key
+    end
+
+    def each
+      segment = nil
+      until segment == nil && query == nil do
+        json = get_segment(JSON.dump(query.to_hash))
+        segment = json[segment_key]
+        segment.each { |item| yield @klass.from_hash(item) }
+        segment = nil
+        @query = json.fetch(PAGE_LINK, {})[NEXT_QUERY]
+      end
+    end
+
+    private
+
+    def get_segment(next_query)
+      remoter.get(route, next_query, headers).on_success do |result|
+        JSON.parse(result.body)
+      end
+    end
+  end
+end

data/lib/tempoiq/models/datapoint.rb

@@ -0,0 +1,28 @@
+require 'time'
+
+module TempoIQ
+  # The core type of TempoIQ. Holds a timestamp and value.
+  class DataPoint
+    # The timestamp of the datapoint [Time]
+    attr_reader :ts
+
+    # The value of the datapoint [Fixnum / Float]
+    attr_reader :value
+
+    def initialize(ts, value)
+      @ts = ts
+      @value = value
+    end
+
+    def to_hash
+      {
+        't' => ts.iso8601(3),
+        'v' => value
+      }
+    end
+
+    def self.from_hash(hash)
+      new(Time.parse(hash['t']), m['v'])
+    end
+  end
+end

data/lib/tempoiq/models/delete_summary.rb

@@ -0,0 +1,12 @@
+module TempoIQ
+  # When deleting multiple objects from a TempoIQ backend, return
+  # information about what was actually deleted.
+  class DeleteSummary
+    # Number of objects deleted in the call
+    attr_reader :deleted
+
+    def initialize(deleted)
+      @deleted = deleted
+    end
+  end
+end

data/lib/tempoiq/models/device.rb

@@ -0,0 +1,40 @@
+require 'tempoiq/models/sensor'
+
+module TempoIQ
+  # The top level container for a group of sensors.
+  class Device
+    # The primary key of the device [String]
+    attr_reader :key
+
+    # Human readable name of the device [String] EG - "My Device"
+    attr_accessor :name
+
+    # Indexable attributes. Useful for grouping related Devices.
+    # EG - {'location' => '445-w-Erie', 'model' => 'TX75', 'region' => 'Southwest'}
+    attr_accessor :attributes
+
+    # Sensors attached to the device [Array] (Sensor)
+    attr_accessor :sensors
+
+    def initialize(key, name = "", attributes = {}, *sensors)
+      @key = key
+      @name = name
+      @attributes = attributes
+      @sensors = sensors
+    end
+
+    def self.from_hash(hash)
+      new(hash['key'], hash['name'], hash['attributes'],
+          *hash['sensors'].map { |s| Sensor.new(s['key'], s['name'], s['attributes']) })
+    end
+
+    def to_hash
+      {
+        'key' => key,
+        'name' => name,
+        'attributes' => attributes,
+        'sensors' => sensors.map(&:to_hash)
+      }
+    end
+  end
+end

data/lib/tempoiq/models/find.rb

@@ -0,0 +1,18 @@
+module TempoIQ
+  class Find
+    attr_reader :name, :limit
+
+    def initialize(limit = nil)
+      @name = "find"
+      @limit = limit
+    end
+
+    def to_hash
+      hash = {
+        "quantifier" => "all"
+      }
+      hash["limit"] = limit if limit
+      hash
+    end
+  end
+end

data/lib/tempoiq/models/multi_status.rb

@@ -0,0 +1,27 @@
+module TempoIQ
+  # MultiStatus is used in cases where an operation might partially succeed
+  # and partially fail. It provides several helper functions to introspect the
+  # failure and take appropriate action. (Log failure, resend DataPoints, etc.)
+  class MultiStatus
+    attr_reader :status
+
+    def initialize(status = nil)
+      @status = status
+    end
+
+    # Was the request a total success?
+    def success?
+      status.nil?
+    end
+
+    # Did the request have partial failures?
+    def partial_success?
+      !success?
+    end
+
+    # Retrieve the failures, key => message [Hash]
+    def failures
+      Hash[status.map { |device_key, v| [device_key, v["message"]] } ]
+    end
+  end
+end

data/lib/tempoiq/models/pipeline.rb

@@ -0,0 +1,86 @@
+module TempoIQ
+  # Used to transform a stream of devices using a list of
+  # function transformations.
+  class Pipeline
+    attr_reader :functions
+
+    def initialize
+      @functions = []
+    end
+
+    # DataPoint aggregation
+    #
+    # * +function+ [Symbol] - Function to aggregate by. One of:
+    #   * count - The number of datapoints across sensors
+    #   * sum - Summation of all datapoints across sensors
+    #   * mult - Multiplication of all datapoints across sensors
+    #   * min - The smallest datapoint value across sensors
+    #   * max - The largest datapoint value across sensors
+    #   * stddev - The standard deviation of the datapoint values across sensors
+    #   * ss - Sum of squares of all datapoints across sensors
+    #   * range - The maximum value less the minimum value of the datapoint values across sensors
+    #   * percentile,N (where N is what percentile to calculate) - Percentile of datapoint values across sensors
+    def aggregate(function)
+      functions << {
+        "name" => "aggregation",
+        "arguments" => [function.to_s]
+      }
+    end
+
+    # Rollup a stream of DataPoints to a given period
+    #
+    # * +period+ [String] - The duration of each rollup. Specified by:
+    #   * A number and unit of time: EG - '1min' '10days'.
+    #   * A valid ISO8601 duration
+    # * +function+ [Symbol] - Function to rollup by. One of:
+    #   * count - The number of datapoints in the period
+    #   * sum - Summation of all datapoint values in the period
+    #   * mult - Multiplication of all datapoint values in the period
+    #   * min - The smallest datapoint value in the period
+    #   * max - The largest datapoint value in the period
+    #   * stddev - The standard deviation of the datapoint values in the period
+    #   * ss - Sum of squares of all datapoint values in the period
+    #   * range - The maximum value less the minimum value of the datapoint values in the period
+    #   * percentile,N (where N is what percentile to calculate) - Percentile of datapoint values in period
+    # * +start+ [Time] - The beginning of the rollup interval
+    def rollup(period, function, start)
+      functions << {
+        "name" => "rollup",
+        "arguments" => [
+                        function.to_s,
+                        period,
+                        start.iso8601(3)
+                       ]
+      }
+    end
+
+    # Interpolate missing data within a sensor, based on
+    #
+    # * +period+ [String] - The duration of each rollup. Specified by:
+    #   * A number and unit of time: EG - '1min' '10days'.
+    #   * A valid ISO8601 duration
+    # * +function+ [Symbol] - The type of interpolation to perform. One of:
+    #   * linear - Perform linear interpolation
+    #   * zoh - Zero order hold interpolation
+    # * +start+ [Time] - The beginning of the interpolation range
+    # * +stop+ [Time] - The end of the interpolation range
+    def interpolate(period, interpolation_function, start, stop)
+      functions << {
+        "name" => "interpolate",
+        "arguments" => [
+                        interpolation_function.to_s,
+                        period,
+                        start.iso8601(3),
+                        stop.iso8601(3)
+                       ]
+      }
+    end
+
+    def to_hash
+      {
+        "functions" => functions
+      }
+    end
+  end
+end
+

data/lib/tempoiq/models/query.rb

@@ -0,0 +1,20 @@
+module TempoIQ
+  class Query
+    attr_reader :search, :action, :pipeline
+
+    def initialize(search, action, pipeline = nil)
+      @search = search
+      @action = action
+      @pipeline = pipeline
+    end
+
+    def to_hash
+      hash = {
+        "search" => search.to_hash,
+        action.name => action.to_hash
+      }
+      hash["fold"] = pipeline.to_hash if pipeline
+      hash
+    end
+  end
+end

data/lib/tempoiq/models/read.rb

@@ -0,0 +1,21 @@
+module TempoIQ
+  class Read
+    attr_reader :name, :start, :stop, :limit
+
+    def initialize(start, stop, limit = nil)
+      @name = "read"
+      @start = start
+      @stop = stop
+      @limit = limit
+    end
+
+    def to_hash
+      hash = {
+        "start" => start.iso8601(3),
+        "stop" => stop.iso8601(3)
+      }
+      hash["limit"] = limit if limit
+      hash
+    end
+  end
+end

data/lib/tempoiq/models/row.rb

@@ -0,0 +1,32 @@
+module TempoIQ
+  # Represents all the data found at a single timestamp.
+  #
+  # The hierarchy looks like:
+  # - timestamp
+  #   - device_key
+  #     - sensor_key => value
+  class Row
+    # Timestamp of the row
+    attr_reader :ts
+
+    # Data at the timestamp [Hash]
+    #
+    # Looks like: {"device1" => {"sensor1" => 1.23, "sensor2" => 2.34}}
+    attr_reader :values
+    
+    def initialize(ts, values)
+      @ts = ts
+      @values = values
+    end
+    
+    def self.from_hash(hash)
+      new(hash['t'], hash['data'])
+    end
+
+    # Convenience method to select a single (device, sensor)
+    # value from within the row.
+    def value(device_key, key)
+      @values[device_key][key]
+    end
+  end
+end

data/lib/tempoiq/models/search.rb

@@ -0,0 +1,17 @@
+module TempoIQ
+  class Search
+    attr_reader :select, :selection
+
+    def initialize(select, selection)
+      @select = select
+      @selection = selection
+    end
+
+    def to_hash
+      {
+        "select" => select,
+        "filters" => selection.to_hash
+      }
+    end
+  end
+end

data/lib/tempoiq/models/selection.rb

@@ -0,0 +1,57 @@
+module TempoIQ
+  # Selection is a core concept that defines how you can retrieve
+  # a group of related objects by common metadata. For Device and
+  # Sensor selection, it is primarily used to drive Device searching
+  # (Client#list_devices) and for driving reads (Client#read).
+  #
+  # TempoIQ currently maps selection onto the following domain objects
+  #
+  # - Device
+  # - Sensor
+  #
+  # TempoIQ currently supports filtering objects by the following metadata:
+  #
+  # ==== Simple selectors:
+  #
+  # - +key+
+  # - +attribute_key+
+  # - +attributes+
+  #
+  # ==== Compound selectors:
+  # - +or+
+  # - +and+
+  #
+  # ==== Simple Examples
+  #
+  #    # Select devices with the key 'heatpump4549' (should return an Array of size 1)
+  #    {:devices => {:key => 'heatpump4549'}}
+  #
+  #    # Select devices that are in buildings
+  #    {:devices => {:attribute_key => 'building'}}
+  #
+  #    # Select devices that are in building '445-w-erie'
+  #    {:devices => {:attributes => {'building' => '445-w-erie'}}}
+  #
+  #    # Select devices in buildings that have TX455 model sensors
+  #    {:devices => {:attribute_key => 'building'},
+  #     :sensors => {:attributes => {'model' => 'TX455'}}}
+  #
+  # ==== Compound examples
+  #
+  #    # Select devices with key 'heatpump4549' or 'heatpump5789'
+  #    {:devices => {:or => [{:key => 'heatpump4549'}, {:key => 'heatpump5789'}]}}
+  #
+  #    # Select devices in buildings in the Evanston region
+  #    {:devices => {:and => [{:attribute_key => 'building'}, {:attributes => {'region' => 'Evanston'}}]}}
+  class Selection
+    attr_reader :select, :filter
+
+    def initialize(select, filter = {})
+      @select = select
+      @filter = filter
+    end
+
+    def to_hash
+    end
+  end
+end