amon 0.3.0 → 0.4.3

data/README.md

@@ -3,6 +3,8 @@ Ruby Client for the AMEE AMON API
 
 This is a Ruby client library for the [AMEE](http://www.amee.com/) <abbr title="AMEE Monitoring Object Notation">AMON</abbr> <abbr title="Application Programming Interface">API</abbr>. _More details and links to be inserted once information about the API is publicly available_.
 
+This is version 0.4.3 and is built to support AMON V3: https://github.com/AMEE/amon
+
 ## Installation ##
 
 ### Dependencies ###
@@ -54,13 +56,13 @@ Methods which can be called on a {AMON::Session Session} can be called directly
 
 ### Simple usage example ###
 
-This example gets some measurements from an electricity meter over a 1 month period.
+This example gets some measurements from an electricity device over a 1 month period.
 
     start_date = Time.local(2010, 3)
     end_date   = Time.local(2010, 4)
-    
+
     property = AMON.entity("da3906c0-7c6b-012d-a6d5-001c23973687")
-    concentrator = property.meters.first
+    concentrator = property.devices.first
     electricity_reading = concentrator.readings_by_type["electricalInput"]
     electricity_reading.measurements(start_date, end_date) # => Array of measurements
 

data/lib/amon/default_session.rb

@@ -3,17 +3,17 @@ require 'forwardable'
 # The AMON module responds to the same method names as an {AMON::Session}. When called,
 # these methods use a 'default' session returned by {create_default_session}. So the following
 # method calls are all equivalent:
-# 
+#
 #     AMON::Session.new(AMON.default_session_options).entity("77e50660-93e7-012d-b57d-001c23973687")
 #     AMON.create_default_session.entity("77e50660-93e7-012d-b57d-001c23973687")
 #     AMON.entity("77e50660-93e7-012d-b57d-001c23973687")
-# 
+#
 # Note that using a default session implicitly (as in the final line above) will cause a new
 # session to be created each time the method is called. This means caching will not be used.
-# 
+#
 # If you are likely to be requesting the same resources in short succession, it is advisable to
 # hold on to a session object yourself. For example:
-# 
+#
 #     @session = AMON.create_default_session
 #     @session.entity("77e50660-93e7-012d-b57d-001c23973687") # => <AMON::Entity> (from HTTP)
 #     @session.entity("77e50660-93e7-012d-b57d-001c23973687") # => <AMON::Entity> (from cache)
@@ -25,21 +25,21 @@ module AMON
     def default_session_options
       @default_session_options ||= {}
     end
-    
+
     # Assigns a new options hash as the {default_session_options}.
     # @param [Hash] options the options hash
     # @return [Hash] the options hash
     def default_session_options=(options)
       @default_session_options = options
     end
-    
+
     # Creates a new session using the {default_session_options}.
     # @return [Session]
     def create_default_session
       Session.new(default_session_options)
     end
-    
+
     extend Forwardable
-    def_delegators :create_default_session, :entity, :meter, :metering_point, :measurements
+    def_delegators :create_default_session, :entity, :device, :metering_point, :measurements
   end
 end

data/lib/amon/device.rb

@@ -0,0 +1,61 @@
+module AMON
+  # An AMON device, containing any number of {Reading readings}, and {Measurement measurements} for those readings.
+  class Device < Document
+    # @return [String] The id of the device
+    field :id, :name => 'deviceId'
+
+    # @return [Time] The latest measurement start date, if provided
+    field :latest_measurement, :name => 'latestMeasurement', :as => Time
+
+    # @return <String> The deviceId for the device
+    def uuid
+      @uuid ||= json['deviceId']
+    end
+
+    # @return <String> The description for the device
+    def description
+      @description ||= json['description']
+    end
+
+    # @return <String> The location for the device
+    def location_name
+      @location_name ||= json['location']['name']
+    end
+
+    # @return [Metadata] The metadata for the device
+    def metadata
+      @metadata ||= Metadata.new(self, json['metadata'])
+    end
+
+    # @return [Array<Reading>] The readings for the device
+    def readings
+      @readings ||= json['readings'].map { |reading| Reading.new(self, reading) }
+    end
+
+    # @return [Hash<String => Reading>] A hash allowing {Device#readings} to be retrieved by their
+    # {Reading#type}
+    def readings_by_type
+      readings.inject({}) do |readings_by_type, reading|
+        readings_by_type[reading.type] = reading
+        readings_by_type
+      end
+    end
+
+    # @return [Array<Measurement>] Measurements for this device
+    # @see Session#measurements
+    def measurements(entity_id, start_date, end_date, raw = false)
+      session.measurements(entity_id, id, start_date, end_date, raw)
+    end
+
+    # @return [Hash<String => Measurement>] A hash allowing {Device#measurements} to be retrieved
+    # by their {Measurement#name}
+    # @see Device#measurements
+    def measurements_by_name(entity_id, start_date, end_date, raw = false)
+      measurements(entity_id, start_date, end_date, raw).inject({}) do |measurements_by_name, measurement|
+        measurements_by_name[measurement.name] ||= []
+        measurements_by_name[measurement.name] << measurement
+        measurements_by_name
+      end
+    end
+  end
+end

data/lib/amon/document.rb

@@ -3,23 +3,23 @@ module AMON
   # @abstract
   class Document
     include JSONHelper
-    
+
     # @return [Session] The session associated with this document
     attr_reader :session
-    
+
     # @param [Session] session The session
     # @param [Hash] json The JSON data as a Hash
     def initialize(session, json)
       @session, @json = session, json
     end
-    
+
     # This should be implemented in subclasses, returning the UUID for the document
     # @abstract
     # @private
     def id
       raise NotImplementedError
     end
-    
+
     # Two documents are equal if they have the same class and their id fields are equal
     # @param [Document] other
     # @return [Boolean]

data/lib/amon/document_part.rb

@@ -1,14 +1,14 @@
 module AMON
   # An object representing part of an AMON {Document}. For example, a {Reading} is part of a
-  # {Meter}, and cannot exist outside of it.
-  # 
+  # {Device}, and cannot exist outside of it.
+  #
   # @abstract
   class DocumentPart
     include JSONHelper
-    
+
     # @return [Document] The parent document of which this object is a part
     attr_reader :parent
-    
+
     # @param [Document] parent The parent document
     # @param [Hash] json The JSON data as a Hash
     def initialize(parent, json)

data/lib/amon/entity.rb

@@ -3,19 +3,19 @@ module AMON
   class Entity < Document
     # @return [String] The id for this entity
     field :id,                 :name => 'entityId'
-    
-    # @return [Array<String>] The ids of all the meters associated with this entity
-    field :meter_ids,          :name => 'meterIds',                  :default => []
-    
+
+    # @return [Array<String>] The ids of all the devices associated with this entity
+    field :device_ids,          :name => 'deviceIds',                  :default => []
+
     # @return [Array<String>] The qualified ids of all the metering points associated with this entity
     # @todo Rename to qualified_metering_point_ids
     field :metering_point_ids, :name => 'qualifiedMeteringPointIds', :default => []
-    
-    # @return [Array<Meter>] The meters associated with this entity
-    def meters
-      @meters ||= meter_ids.map { |id| session.meter(id) }
+
+    # @return [Array<Device>] The devices associated with this entity
+    def devices
+      @devices ||= device_ids.map { |device_id| session.device(id, device_id) }
     end
-    
+
     # @return [Array<MeteringPoint>] The metering points associated with this entity
     def metering_points
       @metering_points ||= metering_point_ids.map { |id| session.metering_point(id) }

data/lib/amon/json_helper.rb

@@ -2,22 +2,22 @@ module AMON
   module JSONHelper
     # @return [Hash] The raw JSON data for this object, represented as a Hash
     attr_reader :json
-    
+
     private
-    
+
     def self.included(base)
       base.class_eval do
         extend ClassMethods
       end
     end
-    
+
     # @private
     module ClassMethods
       def field(name, options = {})
         class_eval do
           define_method(name) do
             original_value = json[(options[:name] || name).to_s]
-            
+
             if original_value.nil?
               options[:default]
             else

data/lib/amon/measurement.rb

@@ -1,24 +1,25 @@
 module AMON
-  # A measurement corresponding to a {Reading} of a {Meter}
+  # A measurement corresponding to a {Reading} of a {Device}
   class Measurement < DocumentPart
     # @return [String] The measurement's name
-    field :name
-    
+    field :type
+    alias :name :type
+
     # @return [Numeric] The measurement's value
     field :value
-    
+
     # @return [Time] The measurement's timestamp, if provided
     field :timestamp,  :as => Time
-    
+
     # @return [Time] The measurement's start date, if provided
     field :start_date, :name => 'startDate', :as => Time
-    
+
     # @return [Time] The measurement's end date, if provided
     field :end_date,   :name => 'endDate',   :as => Time
-    
-    # @attr_reader [Meter] meter The meter which took this measurement
-    alias_method :meter, :parent
-    
+
+    # @attr_reader [Device] device The device which took this measurement
+    alias_method :device, :parent
+
     # A measurement is instantaneous if it is given with a single timestamp. If, on the other hand,
     # start and end dates are provided, it is durational.
     # @return [Boolean]
@@ -26,20 +27,20 @@ module AMON
     def instantaneous?
       !timestamp.nil?
     end
-    
+
     # The opposite of {Measurement#instantaneous? instantaneous?}
     # @return [Boolean]
     # @see Measurement#instantaneous?
     def durational?
       !instantaneous?
     end
-    
-    # The {Meter meter} {Reading reading} associated with this measurement.
+
+    # The {Device device} {Reading reading} associated with this measurement.
     # @return [Reading]
     def reading
-      meter.readings_by_type[name]
+      device.readings_by_type[name]
     end
-    
+
     # A single timestamp in the 'middle' of this measurement. If the measurement is instantaneous,
     # then the mid timestamp is identical to the {Measurement#timestamp timestamp}. However, if it
     # is durational then the mid timestamp is the halfway point between the {Measurement#start_date}

data/lib/amon/metadata.rb

@@ -1,25 +1,25 @@
 module AMON
-  # Metadata associated with a {Meter}. The metadata section of an AMON document can have an
+  # Metadata associated with a {Device}. The metadata section of an AMON document can have an
   # arbitrary number of fields, so this class uses `method_missing` to look them up and respond
   # appropriately.
-  # 
+  #
   # @todo
   #   This doesn't yet support arbitrarily nested metadata, so you can't have JSON like so:
-  #   
+  #
   #     "metadata": {
   #       "foo": {
   #         "bar": "baz"
   #       }
   #     }
-  #   
+  #
   #   And then access:
-  #   
+  #
   #     object.metadata.foo.bar # => "baz"
-  #   
+  #
   #   However, in the meantime you could do:
-  #   
+  #
   #     object.metadata.foo[:bar] # => "baz"
-  #   
+  #
   #   (As the JSON is full parsed into a nested hash.)
 
   class Metadata < DocumentPart

data/lib/amon/reading.rb

@@ -1,59 +1,59 @@
 module AMON
-  # AMON readings are 'categories' of {Measurement measurements} which are taken by {Meter meters}.
+  # AMON readings are 'categories' of {Measurement measurements} which are taken by {Device devices}.
   # For example, one reading may be 'electricalInput' with the unit 'kWh'.
   class Reading < DocumentPart
-    # @return [String] The type of reading, which is unique within the parent {Meter meter}
+    # @return [String] The type of reading, which is unique within the parent {Device device}
     field :type
-    
+
     # @return [String] An arbitrary name for the reading
     field :name
-    
+
     # @return [String] The units this reading records {Measurement measurements} in
     field :unit
-    
+
     # @return [Numeric] The resolution of the reading
     field :resolution
-    
+
     # @return [Numeric] The accuracy of the reading
     field :accuracy
-    
+
     # @return ["instant", "duration"] Whether this reading records measurement values taken at a
     # specific point in time ('instant'), or taken as an average over a period of time ('duration')
     field :period, :default => "instant"
-    
-    # @attr_reader [Meter] meter The meter which took this measurement
-    alias_method :meter, :parent
-    
+
+    # @attr_reader [Device device] The device which took this measurement
+    alias_method :device, :parent
+
     # @return [Array<Measurement>] Measurements for this reading
-    # @see Meter#measurements
-    def measurements(start_date, end_date, raw = false)
-      meter.measurements_by_name(start_date, end_date, raw)[type] || []
+    # @see Device#measurements
+    def measurements(entity_id, start_date, end_date, raw = false)
+      device.measurements_by_name(entity_id, start_date, end_date, raw)[type] || []
     end
-    
+
     # @return [true] if the {#period} is 'instant'
     # @return [false] if the {#period} is 'duration'
     def instantaneous?
       period == "instant"
     end
-    
+
     # @return [Boolean] The opposite of {#instantaneous?}
     def durational?
       !instantaneous?
     end
-    
-    # One reading is equal to another if the meters are equal and they are the same type
+
+    # One reading is equal to another if the devices are equal and they are the same type
     # @return [Boolean]
     # @param [Reading] other The other reading to compare with.
     def ==(other)
-      meter == other.meter && type == other.type
+      device == other.device && type == other.type
     end
-    
-    # A unique id for the reading, composed of the {Meter meter} id, and the {#type}. So an
-    # '<code>electricalInput</code>' reading for a meter with id '<code>b7ddac00-9415-012d-b57e-001c23973687</code>' would
+
+    # A unique id for the reading, composed of the {Device device} id, and the {#type}. So an
+    # '<code>electricalInput</code>' reading for a device with id '<code>b7ddac00-9415-012d-b57e-001c23973687</code>' would
     # have the id '<code>b7ddac00-9415-012d-b57e-001c23973687-electricalInput</code>'.
     # @return [String] the id
     def id
-      "#{meter.id}-#{type}"
+      "#{device.id}-#{type}"
     end
   end
 end

data/lib/amon/session.rb

@@ -2,28 +2,28 @@ require 'uri'
 
 module AMON
   # Session objects take care of making the actual HTTP requests to the AMON API
-  # 
+  #
   # ## Caching ##
-  # 
-  # Sessions support caching which is enabled by default, but can be optionally turned off. When 
+  #
+  # Sessions support caching which is enabled by default, but can be optionally turned off. When
   # caching is enabled, the same request will not be performed twice in a session. Be aware that
   # this has some important implications:
-  # 
+  #
   # * If a long running process uses the same session, the cache may become stale as the backend
   #   data changes, but new API requests are not made.
   # * There is no mechanism for automatically expiring the cache; this is left up to users of the
   #   library.
-  # * The cache stores the AMON objects, rather than the raw response data. In this sense it 
+  # * The cache stores the AMON objects, rather than the raw response data. In this sense it
   #   functions as a sort of identity map - getting the same entity twice will return exactly the
   #   same object twice, rather than two different objects representing the same data.
-  # 
+  #
   # Often the most natural way to 'expire the cache' is to discard the session and use a new one
-  # at regular intervals. Alternatively, you can use {Session#clear_cache} and keep the same 
+  # at regular intervals. Alternatively, you can use {Session#clear_cache} and keep the same
   # session.
   class Session
     # @return [Hash] The hash of configuration options to be used when making requests
     attr_reader :options
-    
+
     # The default options for a session
     DEFAULT_OPTIONS = {
       :base_uri => nil,
@@ -31,7 +31,7 @@ module AMON
       :password => nil,
       :cache    => true
     }.freeze
-    
+
     # @param [Hash] options the options for the session
     # @option options [String] :base_uri The base URI for the AMON API, e.g. "http://amon.amee.com/1"
     # (note that this includes the API version, as this library only knows about version 1 of the API)
@@ -42,7 +42,7 @@ module AMON
       @options = DEFAULT_OPTIONS.merge(options)
       @options.freeze
     end
-    
+
     # Retrieves an entity from the API
     # @param [String] entity_id the ID of the entity to be requested
     # @return [Entity]
@@ -52,17 +52,17 @@ module AMON
         Entity.new(self, json)
       end
     end
-    
-    # Retrieves a meter from the API
-    # @param [String] meter_id the ID of the meter to be requested
-    # @return [Meter]
-    def meter(meter_id)
-      cache(:meters, meter_id) do
-        json = get("/meters/#{URI.escape(meter_id)}")['meter']
-        Meter.new(self, json)
+
+    # Retrieves a device from the API
+    # @param [String] device_id the ID of the device to be requested
+    # @return [Device]
+    def device(entity_id, device_id)
+      cache(:devices, device_id) do
+        json = get("/entities/#{ URI.escape(entity_id )}/devices/#{URI.escape(device_id)};latest")['device']
+        Device.new(self, json)
       end
     end
-    
+
     # Retrieves a metering point from the API
     # @param [String] metering_point_id the ID of the metering point to be requested
     # @return [MeteringPoint]
@@ -72,33 +72,34 @@ module AMON
         MeteringPoint.new(self, json)
       end
     end
-    
+
     # Retrieves measurements from the API
-    # @param [String] meter_id The ID of the meter to get the measurements from
+    # @param [String] entity_id The ID of the entity
+    # @param [String] device_id The ID of the device to get the measurements from
     # @param [Time] start_date The starting point for the measurements
     # @param [Time] end_date The ending point for the measurements
-    # @param [Boolean] raw Whether to return raw measurements as submitted by the hardware (may 
+    # @param [Boolean] raw Whether to return raw measurements as submitted by the hardware (may
     # contain a lot of data), or appropriate aggregations over the time period
-    def measurements(meter_id, start_date, end_date, raw = false)
-      cache(:measurements, [meter_id, start_date, end_date, raw]) do
-        meter = meter(meter_id)
+    def measurements(entity_id, device_id, start_date, end_date, raw = false)
+      cache(:measurements, [device_id, start_date, end_date, raw]) do
+        device = device(entity_id, device_id)
         measurements = get(
-          "/meters/#{meter.id}/measurements?" +
+          "/entities/#{ URI.escape(entity_id) }/devices/#{ URI.escape(device.id) }/measurements?" +
             "raw="       + raw.to_s + "&" +
             "startDate=" + start_date.utc.xmlschema + "&" +
             "endDate="   + end_date.utc.xmlschema
         )['measurements']
-        measurements.map { |measurement| Measurement.new(meter, measurement) }
+        measurements.map { |measurement| Measurement.new(device, measurement) }
       end
     end
-    
+
     # Completely clears the cache
     def clear_cache
       @cache = nil
     end
-    
+
     private
-    
+
       def cache(group, id, &block)
         if options[:cache]
           @cache            ||= {}
@@ -108,16 +109,16 @@ module AMON
           block.call
         end
       end
-    
+
       def get(url, params = {})
         JSON.parse(client[url].get(:params => params))
       end
-      
+
       def client
         raise ArgumentError, "Can't make a request without :base_uri option" unless options[:base_uri]
-        
+
         @client ||= RestClient::Resource.new(
-          options[:base_uri], 
+          options[:base_uri],
           :user     => options[:user],
           :password => options[:password],
           :headers  => {

data/lib/amon/version.rb

@@ -2,9 +2,9 @@ module AMON
   # Provides details about the version of the AMON library in use.
   module Version
     MAJOR = 0
-    MINOR = 3
-    TINY  = 0
-    
+    MINOR = 4
+    TINY  = 3
+
     STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
   end
 end

data/lib/amon.rb

@@ -6,13 +6,13 @@ module AMON
   autoload :Document,      'amon/document'
   autoload :DocumentPart,  'amon/document_part'
   autoload :Entity,        'amon/entity'
-  autoload :Meter,         'amon/meter'
+  autoload :Device,        'amon/device'
   autoload :MeteringPoint, 'amon/metering_point'
   autoload :Metadata,      'amon/metadata'
   autoload :Reading,       'amon/reading'
   autoload :Measurement,   'amon/measurement'
   autoload :Version,       'amon/version'
   autoload :Session,       'amon/session'
-  
+
   require 'amon/default_session'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: amon
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 9
   prerelease: 
   segments: 
   - 0
+  - 4
   - 3
-  - 0
-  version: 0.3.0
+  version: 0.4.3
 platform: ruby
 authors: 
 - AMEE
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-25 00:00:00 Z
+date: 2012-07-25 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
@@ -107,13 +107,13 @@ extra_rdoc_files: []
 
 files: 
 - lib/amon/default_session.rb
+- lib/amon/device.rb
 - lib/amon/document.rb
 - lib/amon/document_part.rb
 - lib/amon/entity.rb
 - lib/amon/json_helper.rb
 - lib/amon/measurement.rb
 - lib/amon/metadata.rb
-- lib/amon/meter.rb
 - lib/amon/metering_point.rb
 - lib/amon/reading.rb
 - lib/amon/session.rb

data/lib/amon/meter.rb

@@ -1,53 +0,0 @@
-module AMON
-  # An AMON meter, containing any number of {Reading readings}, and {Measurement measurements} for those readings.
-  class Meter < Document
-    # @return [String] The id of the meter
-    field :id, :name => 'meterId'
-
-    # @return <String> The description for the meter
-    def description
-      @description ||= json['description']
-    end
-
-    # @return <String> The location for the meter
-    def location_name
-      @location_name ||= json['location']['name']
-    end
-    
-    # @return [Metadata] The metadata for the meter
-    def metadata
-      @metadata ||= Metadata.new(self, json['metadata'])
-    end
-    
-    # @return [Array<Reading>] The readings for the meter
-    def readings
-      @readings ||= json['readings'].map { |reading| Reading.new(self, reading) }
-    end
-    
-    # @return [Hash<String => Reading>] A hash allowing {Meter#readings} to be retrieved by their
-    # {Reading#type}
-    def readings_by_type
-      readings.inject({}) do |readings_by_type, reading|
-        readings_by_type[reading.type] = reading
-        readings_by_type
-      end
-    end
-    
-    # @return [Array<Measurement>] Measurements for this meter
-    # @see Session#measurements
-    def measurements(start_date, end_date, raw = false)
-      session.measurements(id, start_date, end_date, raw)
-    end
-    
-    # @return [Hash<String => Measurement>] A hash allowing {Meter#measurements} to be retrieved
-    # by their {Measurement#name}
-    # @see Meter#measurements
-    def measurements_by_name(start_date, end_date, raw = false)
-      measurements(start_date, end_date, raw).inject({}) do |measurements_by_name, measurement|
-        measurements_by_name[measurement.name] ||= []
-        measurements_by_name[measurement.name] << measurement
-        measurements_by_name
-      end
-    end
-  end
-end