Ruby Client for the AMEE AMON API

This is a Ruby client library for the AMEE AMON API. More details and links to be inserted once information about the API is publicly available.

This is version 0.12.0 and is built to support AMON V3: https://github.com/AMEE/amon

Installation

Dependencies

Currently, the library depends on:

These will be automatically installed if installing as a gem.

Standard installation: as a rubygem

The library is not currently available via any public gem servers. However, it can be installed as a gem using the following steps:

  1. Grab the code: git clone [email protected]:AMEE/amon.client.ruby.git
  2. Build the gem: gem build amon.gemspec
  3. Install the gem: sudo gem install amon-0.1.0.gem

Alternative: manual installation

You can manually install the code somewhere, and then ensure that the lib/ directory is listed in your LOAD_PATH.

Alternative: vendoring in a Rails app

If you are using the library inside a Rails (2.3) app, clone the code into vendor/gems/amon-0.1.0. Then list it as a gem dependency in config/environment.rb and Rails will automatically find and load it.

If using Rails 3, you could do a similar thing using Bundler.

Loading the library in your code

Once installed, the library can be loaded using require "amon".

Configuration

Interaction with the API is achieved through Session objects. For convenience, you can configure some 'default session options' by setting the values in the AMON.default_session_options hash. You can then create a session from these options at any time by calling AMON.create_default_session.

See the AMON::Session page for a full explanation of the options available.

Example default session configuration

AMON.default_session_options[:base_uri] = "http://amon.amee.com/1"
AMON.default_session_options[:user] = "fred"
AMON.default_session_options[:password] = "s3cr3t"

Usage

Methods which can be called on a Session can be called directly on the AMON module, which will cause a default session to be created and used.

Simple usage example

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.devices.first
electricity_reading = concentrator.readings_by_type["electricalInput"]
electricity_reading.measurements(start_date, end_date) # => Array of measurements

Development

Tests can be run with RSpec: spec spec/.

The documentation is generated with YARD: rake yard.

TODO List

  • Error handling
  • Rename Document and DocumentPart to Resource and ResourcePart