Lelylan Ruby Gem

Ruby client library for Lelylan API

Introduction

What is Lelylan

Lelylan makes it easy for developers to monitor and control all devices in your house providing a simple and consistent REST API.

Requirements

Ruby client library is tested against MRI 1.9.3.

Installation

Install the client using Bundler.

gem 'lelylan-rb', require: 'lelylan'
gem 'oauth2'

Development version.

gem 'lelylan-rb', require: 'lelylan', git: 'https://github.com/lelylan/lelylan-rb'

Getting started

Require Gem

require 'lelylan'
require 'oauth2'

Get an access token

First of all you need an access token to authoraze your requests in Lelylan. To get one use the OAuth2 gem and if you are not used to OAuth2 concepts, take 10 minutes and read the related documentation in the dev center.

# Create a client
oauth = OAuth2::Client.new(client_id, client_secret, site: site)

# Redirect the application to the Lelylan authorization page
redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri, scope: scope)
# => http://people.lelylan.com/oauth/authorize?
#      redirect_uri=http://localhost:3000/callback&
#      scope=<scope>&response_type=code&client_id=<client-id>

# 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)

Lelylan access

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.

# Initialize Lelylan client
lelylan = Lelylan::Client.new(token: token)

# Get the first device where the name matches with Dimmer.
device = lelylan.devices(name: 'Dimmer').first

# The client returns an Hashie (https://github.com/intridea/hashie)
puts device.uri # get the device uri
puts device.properties.first.value # get the first device property value

Realtime services

When using the subscription services you don't need an access token. In this case what you need is to set the client credentials.

lelylan = Lelylan::Client.new(client_id:'<client-id>', client_secret: '<client-secret>')
subscriptions = lelylan.subscriptions

Implemented Services

Learn how to use Lelylan and AngulasJS in deep.

[x] Devices.
[x] Activations.
[x] Histories.
[x] Types.
[x] Properties.
[x] Functions.
[x] Statuses.
[x] Locations.
[x] Physical devices.
[x] Subscriptions.
[x] User Profile.
[x] OAuth2.

Authorization flows

Authorization code flows

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)

Implicit grant flow

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)

Resource owner password credentials flow

oauth = OAuth2::Client.new(client_id, client_secret, site: site)
token = oauth.password.get_token('email', 'password')

Access tokens, when expired, are automatically refreshed.

Errors

Exceptions are raised when a 4xx or 5xx status code is returned.

Lelylan::BadRequest            # 400
Lelylan::Unauthorized          # 401
Lelylan::Forbidden             # 403
Lelylan::NotFound              # 404
Lelylan::NotAcceptable         # 406
Lelylan::NotValid              # 422
Lelylan::InternalServerError   # 500
Lelylan::NotImplemented        # 501
Lelylan::BadGateway            # 502
Lelylan::ServiceUnavailable    # 503

Through the error message attribute you can access the error information.

begin
  device = lelylan.device('<id>')
rescue Lelylan::Error => e
  puts e.message
end

Unluckily the #message method can only be a string. For this reason we can't return a JSON structure when lelylan offers it, but we return the error.description value. Learn more about errors on Lelylan.

Configurations

API endpoint

Configuration block.

Lelylan.configure { |c| c.endpoint = 'https://localhost:8000' }
lelylan = Lelylan::Client.new(token: token)

Client instance.

lelylan = Lelylan::Client.new(token: token)
lelylan.endpoint = 'https://lelylan.yourhouse.com'

Contributing

Fork the repo on github and send a pull requests with topic branches. Do not forget to provide specs to your contribution.

Running specs

Fork and clone the repository.
Run gem install bundler to get the latest for the gemset.
Run bundle install for dependencies.
Run bundle exec guard and press enter to execute all specs.

Running locally

Whenever you want to use the source code from your IRB session simply import lib/.

$ git clone https://github.com/lelylan/lelylan-rb
$ cd lelylan-rb
$ irb -I lib/
$ > require 'lelylan'

Spec guidelines

Follow rspec best practices guidelines.

Coding guidelines

Follow github guidelines.

Feedback

Use the issue tracker for bugs. Mail or Tweet us for any idea that can improve the project.

Authors

Andrea Reginato

Contributors

Special thanks to the following people for submitting patches.

Changelog

See CHANGELOG