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.(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.(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.(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.
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.
Links
Authors
Contributors
Special thanks to the following people for submitting patches.
Changelog
See CHANGELOG