lelylan-rb 0.0.1 → 0.0.2

data/.gitignore

@@ -1,6 +1,7 @@
 *.gem
 *.rbc
 *.swp
+*.swo
 *.tmproj
 *.DS_Store
 *~

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
-## v0.1.0 ()
+## v0.0.2 (January 25, 2013)
 
-First version Ruby wrapper for Lelylan API
+* First version Ruby wrapper for Lelylan API
+
+## v0.0.1 (July 25, 2012)
+
+* First version Ruby wrapper for Lelylan API

data/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
 
-platforms :jruby do
-  gem "jruby-openssl", "~> 0.7"
-end
+ruby '1.9.3'
 
 gemspec

data/Guardfile

@@ -1,4 +1,4 @@
-guard 'rspec', cli: '--format Fuubar --color', all_after_pass: false, :version => 2 do
+guard 'rspec', cli: '--format Fuubar --color', all_after_pass: false do
   watch(%r{^spec/.+_spec\.rb})
   watch(%r{^lib/(.+)\.rb})     { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb') { "spec" }

data/README.md

@@ -2,6 +2,14 @@
 
 Ruby client library for [Lelylan API](http://dev.lelylan.com)
 
+## What is Lelylan
+
+Lelylan makes it easy for developers to monitor and control all devices in
+your house providing a simple, self descriptive and consistent representation of them. Lelylan
+maps every device in your house to a unique URI which will provide a simple access over it.
+
+With Lelylan developers can build secure applications and services that use real-time data
+coming from the real world to create the future connected house.
 
 ## Requirements
 
@@ -10,131 +18,169 @@ Ruby client library is tested against MRI 1.9.3.
 
 ## Installation
 
-Install gem using Bundler.
+Install the client using Bundler.
 
-    gem 'lelylan-rb', require: 'lelylan'
+```ruby
+gem 'lelylan-rb', require: 'lelylan'
+gem 'oauth2'
+```
 
 Development version.
 
-    gem 'lelylan-rb', require: 'lelylan', git: 'https://github.com/lelylan/lelylan-rb', branch: 'dev'
-
-
-## Resources
-
-* [Ruby gem documentation](http://rdoc.info/gems/lelylan-rb)
-* [Lelylan API](http://dev.lelylan.com)
-
+```ruby
+gem 'lelylan-rb', require: 'lelylan', git: 'https://github.com/lelylan/lelylan-rb', branch: 'master'
+```
 
 ## Getting started
 
-Require gems.
+### Require Gem
 
-    require 'rubygems'
-    require 'lelylan-rb'
+```ruby
+require 'rubygems'
+require 'lelylan-rb'
+require 'oauth2'
+```
 
+### Get an access token
 
-### Create the access token
+First of all you need an access token to authoraze your requests in
+Lelylan. To get one use the [OAuth2 gem](https://github.com/intridea/oauth2/)
+and if you are not used to OAuth2 concepts, take 10 minutes and read the
+related documentation in the [dev center](http://dev.lelylan.com/api/oauth#language=node).
 
-Create a client (uses the [OAuth2 gem](https://github.com/intridea/oauth2/)).
 
-    oauth = OAuth2::Client.new(client_id, client_secret, site: site)
+```ruby
+# Create a client
+oauth = OAuth2::Client.new(client_id, client_secret, site: site)
 
-Redirect the application to the Lelylan authorization page.
+# Redirect the application to the Lelylan authorization page
+redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
+# => http://people.lelylan.com/oauth/authorize?redirect_uri=http://localhost:3000/callback&scope=devices&response_type=code&client_id=<client-id>
 
-    redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
+# Get the access token object (authorization code is given from the previous step)
+token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+```
 
-Create the access token. The params[:code] contains the authorization
-code created from Lelylan and sent to the redirect_uri.
+### Lelylan access
 
-    token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+Once you have the access token you can access to the Lelylan API. The
+following example shows how to print in the console a list of owned devices.
 
-### Create the Lelylan client.
+```ruby
+# Initialize Lelylan client
+lelylan = Lelylan::Client.new(token: token)
 
-    client = Lelylan::Client.new(token: token)
+# Get the first device where the name matches with Dimmer
+device = lelylan.devices(name: 'Dimmer').first
+```
 
-### Access Lelylan API
+### Realtime services
 
-Get 10 devices.
+When using the [subscription](http://dev.lelylan.com/api/realtime#language=node) services
+you don't need an access token. In this case what you need is to set the client credentials.
 
-    client.devices(per: 10)
+```ruby
+lelylan = Lelylan::Client.new(client_id:'<client-id>', client_secret: '<client-secret>')
+subscriptions = lelylan.subscriptions
+```
 
-Get a device based on its URI.
+## Authorization flows
 
-    client.device('http://api.lelylan.com/devices/:id')
+Lelylan support three OAuth2 authorization flows.
 
-Search a device based on its name.
+### Authorization code flows
 
-    client.devices(name: 'Dimmer').first
+```ruby
+oauth = OAuth2::Client.new(client_id, client_secret, site: site)
+redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
+token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+```
 
-Create a device (in this case we suppose the type is a dimmer)
+### Implicit grant flow
 
-    device = client.create_device(name: 'Closet dimmer', type_uri: dimmer.uri)
+```ruby
+oauth = OAuth2::Client.new(client_id, client_secret, site: site)
+redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
+token = OAuth2::AccessToken.from_kvform(client, params)
+```
 
-Execute a function.
+### Resource owner password credentials flow
 
-    client.execute(device.uri, function.uri)
+```ruby
+oauth = OAuth2::Client.new(client_id, client_secret, site: site)
+token = oauth.password.get_token('email', 'password')
+```
 
-Get a public type based on its URI. Remember, when a resource is public the client
-with a token is not needed.
+Access tokens, when expired, are automatically refreshed.
 
-    Lelylan.type('http://api.lelylan.com/types/:id')
 
+## Lelylan Services
 
-## More examples
+### Devices
 
-For more examples check out the [ruby gem documentation](http://rdoc.info/gems/lelylan-rb).
+The Device API defines a set of services to monitor and control every existing device.
+Its final goal is to map every device to a unique URI which provides control over it.
+[See examples](http://dev.lelylan.com/api/devices#ruby).
 
-* [Device examples](docs/Lelylan/Client/Devices)
-* [Consumption examples](docs/Lelylan/Client/Consumptions)
-* [Hisotry examples](docs/Lelylan/Client/Histories)
-* [Types examples](docs/Lelylan/Client/Types)
-* [Properties examples](docs/Lelylan/Client/Properties)
-* [Functions examples](docs/Lelylan/Client/Functions)
-* [Statuses examples](docs/Lelylan/Client/Statuses)
-* [Categories examples](docs/Lelylan/Client/Categories)
-* [Locations examples](docs/Lelylan/Client/Locations)
+### Histories
 
-## Authorization flows
+When a device updates its properties or executes a function a new history resource with
+a snapshot of all device properties is created by Lelylan, also the ones that has not been
+updated. This makes it easy to recreate previous device status and extract usage patterns
+to improve the way people live their house.
+[See examples](http://dev.lelylan.com/api/devices/histories#ruby).
 
-Lelylan support four OAuth2 authorization flows.
+### Types
 
-### Authorization code flows
+A type describes the structure of a device. In its simplest form every type can be defined
+as the combination of three key elements: properties (what vary during time), functions
+(what a device can do), statuses (what a device is in a specific time of its life).
+[See examples](http://dev.lelylan.com/api/types#ruby).
 
-    oauth = OAuth2::Client.new(client_id, client_secret, site: site)
-    redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
-    token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri)
+### Properties
 
-### Implicit grant flow
+A property is whatever vary in a device during time. It can be the intensity in a dimmer,
+the temperature in a cooling system or the volume in a television.
+[See examples](http://dev.lelylan.com/api/types/properties#ruby).
 
-    oauth = OAuth2::Client.new(client_id, client_secret, site: site)
-    redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri)
-    token = OAuth2::AccessToken.from_kvform(client, params)
+### Functions
 
-### Resource owner password credentials flow
+Functions defines the daily interactions you have with the devices in your house, for
+example when you turn on a light, close a door or raise the temperature in a room.
+With functions you can control any device in the same way you do everyday of your life.
+[See examples](http://dev.lelylan.com/api/types/functions#ruby).
 
-    oauth = OAuth2::Client.new(client_id, client_secret, site: site)
-    token = oauth.password.get_token('email', 'password')
+### Statuses
 
-### Client credentials flow
+Properties are not always enough to describe the status of a device. Think at a roller
+shutter for example. It has the property aperture that is 100 when open or 0 when closed.
+But what if the roller shutter is opening? It is nether open or close. To have a complete
+control over the device status in a specific moment of its life is to use the status API.
+[See examples](http://dev.lelylan.com/api/types/statuses#ruby).
 
-    token = oauth.client_credentials.get_token
+### Locations
 
-All access tokens, when expired, are automatically refreshed.
+Locations are the places we live in and where physical devices are placed. Lelylan identifies
+three types of locations usually organized in a hierarchical structure: houses, floors and
+rooms.
+[See examples](http://dev.lelylan.com/api/locations#ruby).
 
+### Physical devices
 
-## Settings
+Physical devices are the real objects you physically interact with everyday of your life
+like lights, appliances, alarms and more. To enable the communication between Lelylan and
+physical devices they should provide a simple set of web services.
+[See examples](http://dev.lelylan.com/api/physicals#ruby).
 
-### API endpoint
+### Subscriptions
 
-Configuration block.
-
-    Lelylan.configure { |c| c.endpoint = 'https://lelylan.yourhouse.com' }
-    @client = Lelylan::Client.new(token: token)
+Get real-time updates by subscribing to a resource and its related event.
+[See examples](http://dev.lelylan.com/api/realtime#ruby).
 
-Client instance.
+### Authenticated User Profile
 
-    @client = Lelylan::Client.new(token: token)
-    @client.endpoint = 'https://lelylan.yourhouse.com'
+Returns extended information for the authenticated user.
+[See examples](http://dev.lelylan.com/api/core#get-a-user-ruby).
 
 
 ## Errors
@@ -152,18 +198,41 @@ Exceptions are raised when a 4xx or 5xx status code is returned.
 
 Through the error message attribute you can access the error information.
 
-    begin
-      @type = Lelylan::Type.type("https://type.lelylan.com/types/not_existing_uri")
-    rescue Lelylan::NotFound => e
-      puts "The resource #{e.message.error.uri} was not found"
-    end
+```ruby
+begin
+  @type = Lelylan::Type.type("https://type.lelylan.com/types/wrong")
+rescue Lelylan::NotFound => e
+  puts "The resource #{e.message.error.uri} was not found"
+end
+```
+
+Learn more about the [error response structure](http://dev.lelylan.com/api/core#errors).
+
+
+## Configurations
+
+### API endpoint
+
+Configuration block.
+
+```ruby
+Lelylan.configure { |c| c.endpoint = 'https://localhost:8000' }
+lelylan = Lelylan::Client.new(token: token)
+```
+
+Client instance.
+
+```ruby
+lelylan = Lelylan::Client.new(token: token)
+lelylan.endpoint = 'https://lelylan.yourhouse.com'
+```
 
-Learn more about the [error response structure](http://dev.lelylan.com/rest/core/#errors).
+Learn more about the [error response structure](http://dev.lelylan.com/api/core#errors).
 
 
 ## Contributing
 
-Fork the repo on github and send a pull requests with topic branches. Do not forget to 
+Fork the repo on github and send a pull requests with topic branches. Do not forget to
 provide specs to your contribution.
 
 
@@ -177,7 +246,7 @@ provide specs to your contribution.
 
 ## Spec guidelines
 
-Follow [rspec best practices](https://docs.google.com/document/d/1gi00-wwPaLk5VvoAJhBVNh9Htw4Rwmj-Ut88T4M2MwI/edit?hl=en#) guidelines.
+Follow [rspec best practices](http://betterspecs.org) guidelines.
 
 
 ## Coding guidelines
@@ -191,9 +260,10 @@ Use the [issue tracker](http://github.com/lelylan/lelylan-rb/issues) for bugs.
 [Mail](mailto:touch@lelylan.com) or [Tweet](http://twitter.com/lelylan) us for any idea that can improve the project.
 
 
-## Links 
+## Links
 
 * [GIT Repository](http://github.com/lelylan/lelylan-rb)
+* [Lelylan Ruby Website](http://lelylan.github.com/lelylan-rb).
 * [Lelylan Dev Center](http://dev.lelylan.com)
 * [Lelylan Site](http://lelylan.com)
 
@@ -210,9 +280,10 @@ Special thanks to the following people for submitting patches.
 
 ## Changelog
 
-See [CHANGELOG](people/blob/master/CHANGELOG.md)
+See [CHANGELOG](https://github.com/lelylan/lelylan-rb/blob/master/CHANGELOG.md)
 
 
 ## Copyright
 
-Copyright (c) 2013 [Lelylan](http://lelylan.com). See [LICENSE](people/blob/master/LICENSE.md) for details.
+Copyright (c) 2013 [Lelylan](http://lelylan.com).
+See [LICENSE](https://github.com/lelylan/lelylan-rb/blob/master/LICENSE.md) for details.

data/Rakefile

@@ -4,18 +4,5 @@ Bundler::GemHelper.install_tasks
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-task :test => :spec
-task :default => :spec
-
-namespace :doc do
-  require 'yard'
-  YARD::Rake::YardocTask.new do |task|
-    task.files   = ['README.md', 'CHANGELOG.md', 'lib/lelylan/client/**/*.rb']
-    task.options = [
-      '--plugin', 'yard-tomdoc',
-      '--markup-provider', 'redcarpet',
-      '--markup', 'markdown',
-      '--output-dir', 'doc'
-    ]
-  end
-end
+task test: :spec
+task default: :spec

data/index.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html>
+
+  <head>
+    <meta charset='utf-8' />
+    <meta http-equiv="X-UA-Compatible" content="chrome=1" />
+    <meta name="description" content="Lelylan-rb : Ruby wrapper for Lelylan API" />
+
+    <link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
+
+    <title>Lelylan-rb</title>
+  </head>
+
+  <body>
+
+    <!-- HEADER -->
+    <div id="header_wrap" class="outer">
+        <header class="inner">
+          <a id="forkme_banner" href="https://github.com/lelylan/lelylan-rb">View on GitHub</a>
+
+          <h1 id="project_title">Lelylan-rb</h1>
+          <h2 id="project_tagline">Ruby wrapper for Lelylan API</h2>
+
+            <section id="downloads">
+              <a class="zip_download_link" href="https://github.com/lelylan/lelylan-rb/zipball/master">Download this project as a .zip file</a>
+              <a class="tar_download_link" href="https://github.com/lelylan/lelylan-rb/tarball/master">Download this project as a tar.gz file</a>
+            </section>
+        </header>
+    </div>
+
+    <!-- MAIN CONTENT -->
+    <div id="main_content_wrap" class="outer">
+      <section id="main_content" class="inner">
+        <h3>Welcome to GitHub Pages.</h3>
+
+<p>This automatic page generator is the easiest way to create beautiful pages for all of your projects. Author your page content here using GitHub Flavored Markdown, select a template crafted by a designer, and publish. After your page is generated, you can check out the new branch:</p>
+
+<pre><code>$ cd your_repo_root/repo_name
+$ git fetch origin
+$ git checkout gh-pages
+</code></pre>
+
+<p>If you're using the GitHub for Mac, simply sync your repository and you'll see the new branch.</p>
+
+<h3>Designer Templates</h3>
+
+<p>We've crafted some handsome templates for you to use. Go ahead and continue to layouts to browse through them. You can easily go back to edit your page before publishing. After publishing your page, you can revisit the page generator and switch to another theme. Your Page content will be preserved if it remained markdown format.</p>
+
+<h3>Rather Drive Stick?</h3>
+
+<p>If you prefer to not use the automatic generator, push a branch named <code>gh-pages</code> to your repository to create a page manually. In addition to supporting regular HTML content, GitHub Pages support Jekyll, a simple, blog aware static site generator written by our own Tom Preston-Werner. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers intelligent blog support and other advanced templating features.</p>
+
+<h3>Authors and Contributors</h3>
+
+<p>You can <a href="https://github.com/blog/821" class="user-mention">@mention</a> a GitHub username to generate a link to their profile. The resulting <code>&lt;a&gt;</code> element will link to the contributor's GitHub Profile. For example: In 2007, Chris Wanstrath (<a href="https://github.com/defunkt" class="user-mention">@defunkt</a>), PJ Hyett (<a href="https://github.com/pjhyett" class="user-mention">@pjhyett</a>), and Tom Preston-Werner (<a href="https://github.com/mojombo" class="user-mention">@mojombo</a>) founded GitHub.</p>
+
+<h3>Support or Contact</h3>
+
+<p>Having trouble with Pages? Check out the documentation at <a href="http://help.github.com/pages">http://help.github.com/pages</a> or contact <a href="mailto:support@github.com">support@github.com</a> and we’ll help you sort it out.</p>
+      </section>
+    </div>
+
+    <!-- FOOTER  -->
+    <div id="footer_wrap" class="outer">
+      <footer class="inner">
+        <p class="copyright">Lelylan-rb maintained by <a href="https://github.com/lelylan">lelylan</a></p>
+        <p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
+      </footer>
+    </div>
+
+    
+
+  </body>
+</html>