Commonsense::Ruby::Lib

Client library to communicate with CommonSense written in ruby

Installation

Install with rubygems :

$ gem install cs

If you use Bundler to manage gem dependency, add this line to your Gemfile:

gem 'cs'

And then execute:

$ bundle

Usage

Authentication

client = CS::Client.new
client.login('username','password')

# setting session_id manually

client = CS::Client.new
client.session_id = '1234'

# get current user
current_user = client.current_user

Querying Sensor

# create sensors relation
sensors = client.sensors

# is the same as
sensors = CS::Relation::Sensors.new
sensors.session = session

# Get all sensor
sensors = client.sensors
sensors.to_a

# show parameters available when querying
client.sensors.parameters

# Get sensor by specifying parameters
client.sensors.where(page: 0, per_page: 1000)
client.sensors.where(owned: true)
client.sensors.where(physical: true)
client.sensors.where(page: 0, per_page: 1000, physical: true, owned: true, details: "full")

# process each sensor
client.sensors.where(owned: true).each {|sensor| puts sensor.name}

# Chain parameters
client.sensors.where(page:0, per_page: 10).where(physical: true)

# Find sensor by name
client.sensors.find_by_name(/position/)
client.sensors.find_by_name(/position/, owned: true) # or
client.sensors.where(owned: true).find_by_name(/position/)

# Get first sensor or last sensor
sensor = client.sensors.first
sensor = client.sensors.last

# Get number of sensors
client.sensors.count
client.sensors.where(owned: true).count

Creating Sensor

sensor = client.sensor.build
sensor.name = "light"
sensor.display_name = "Light"
sensor.device_type = "Android"
sensor.pager_type = ""
sensor.data_type = "json"
sensor.data_structure = {lux: "integer"}
sensor.save!

Uploading data point

# Find the first position sensor
sensor = client.sensors.find_by_name(/position/).first

# save data point
data = sensor.data.build
data.date = Time.now
data.value = {"lux" => 1}
data.save!

# more compact version
sensor.data.build(date: Time.now, value: {"lux" => 1}).save!

Making manual API call

With the client we could interact with CS API using the client object

example

client.get('/users/current.json')
client.post('/sensors.json', {"params": "bar"})

Debuging

To get information about the API response (body, code, headers) use this method

example

# do some API call
current_user = client.current_user

response_code = client.response_code
response_body = client.resopnse_body
header = client.response_headers

# dump the output to text file
session.dump_to_text("/tmp/output.txt")

# open output in browser. Require 'launchy' gem
session.open_in_browser

Command Line Executable

This gem also contain executables to run from command line. The main executable is cs

$ cs -h
Usage: cs <command>

    -h, --help                       Show this message

Available commands are:

    console       Run REPL console based on PRY
    password      Generate hased password from plaintext

The console executable will run an REPL (Read Evaluate Print Loop) session based on pry.

install pry first in order to use it. pry-doc and pry-nav is optional

$ gem install pry
$ gem install pry-doc
$ gem install pry-nav

you can have a configuration file on ~/.cs.yml which contain the following

users:
  user1:
    username: "user1@example.com"
    password: ""
    password_md5: 1234567890abcdef1234567890abcdef
  user2:
    username: "user2@example.com"
    password: "V3rryS3curePaswd"
    password_md5: ""

default_user: user1

you can either fill in the password or md5-hashed password. It will use password_md5 if you fill in both

now you can use it on cs console

$ cs console
CS console 0.1.1

# create a client with default user

[1] pry(main)> client = new_client()
Successfully logged in with user 'user1@example.com'
=> #<CS::Client:0x00000004cd7540
 @base_uri="https://api.sense-os.nl",
 @session=SESSION_ID "1234567890abcdefg1.23456789">

# create a client with another user

[2] pry(main)> user2_client = new_client("user2")
Successfully logged in with user 'user2@example.com'
=> #<CS::Client:0x00000004cd7560
 @base_uri="https://api.sense-os.nl",
 @session=SESSION_ID "1234567890abcdefg1.23456789">

# create an empty client object and will not do the login

[3] pry(main)> empty_client = new_client(false)
> #<CS::Client:0x00000004cf2cf0 @base_uri="https://api.sense-os.nl">

Testing

$ cp spec/support/spec_config.yml.sample spec/support/spec_config.yml
$ rspec

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

cs

Development

Runtime