Client library to communicate with CommonSense written in ruby

Gem Version Code Climate Build Status Test Coverage

RDoc Documentation


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



client =

# setting session_id manually

client =
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 =
sensors.session = session

# Get all sensor
sensors = client.sensors

# show parameters available when querying

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

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

# Find sensor by name
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.where(owned: true).count

Creating Sensor

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

Uploading data point

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

# save data point
data = =
data.value = {"lux" => 1}!

# more compact version, value: {"lux" => 1}).save!

Making manual API call

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


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


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


# 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

# open output in browser. Require 'launchy' gem

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

    username: ""
    password: ""
    password_md5: 1234567890abcdef1234567890abcdef
    username: ""
    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 ''
=> #<CS::Client:0x00000004cd7540
 @session=SESSION_ID "1234567890abcdefg1.23456789">

# create a client with another user

[2] pry(main)> user2_client = new_client("user2")
Successfully logged in with user ''
=> #<CS::Client:0x00000004cd7560
 @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="">


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


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