adafruit-io

A Ruby client for use with with io.adafruit.com.

Installation

Add this line to your application's Gemfile:

gem 'adafruit-io'

And then execute:

$ bundle

Or install it yourself as:

$ gem install adafruit-io

Usage

Each time you use the library, you'll want to pass your AIO Key to the client.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

Table of Contents

• Feeds
  • Create
  • Read
  • Update
  • Delete
• Data
  • Create
  • Read
  • Update
  • Delete
  • Helper Methods
    • Send
    • Next
    • Last
    • Previous
  • Readable
  • Writable
• Groups
  • Create
  • Read
  • Update
  • Delete

Feeds

Feeds are the core of the Adafruit IO system. The feed holds metadata about data that gets pushed, and you will have one feed for each type of data you send to the system. You can have separate feeds for each sensor in a project, or you can use one feed to contain JSON encoded data for all of your sensors.

Feed Creation

You have two options here, you can create a feed by passing a feed name, or you can pass an object if you would like to define more properties. If you would like to find information about what properties are available, please visit the Adafruit IO feed API docs.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

puts aio.feeds.create({:name => "Temperature"})

Feed Retrieval

You can get a list of your feeds by using the aio.feeds.retrieve method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get all feeds
puts aio.feeds.retrieve

You can also get a specific feed by ID, key, or name by using the aio.feeds.retrieve(id) method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get a single feed
feed = aio.feeds.retrieve("Temperature")
puts feed.name
puts feed.last_value

Feed Updating

You can update feed properties by retrieving a feed, and subsequently calling the save method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get the feed
feed = aio.feeds.retrieve("Temperature")
feed.name = "adsfsdff"
feed.description = "hey hey"
feed.save

Feed Deletion

You can delete a feed by ID, key, or name by retrieving a feed, and subsequently calling the delete method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

feed = aio.feeds.retrieve("Temperature")
puts feed.delete

Data

Data represents the data contained in feeds. You can read, add, modify, and delete data. There are also a few convienient methods for sending data to feeds and selecting certain pieces of data.

Data Creation

Data can be created after you create a feed, by using the aio.feeds(id).data.create(value) method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds("Temperature").data.create({:value => 11})
puts data.inspect

Data Retrieval

You can get all of the data data by using the aio.feeds(187).data.retrieve method. The callback will be called with errors and the data array as arguments.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.retrieve
puts data.inspect

You can also get a specific value by ID by using the aio.feeds(id).data.retrieve(id) method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.retrieve(288718)
puts data.inspect

Data Updating

Values can be updated by retrieving the data, updating the property, and subsequently calling the save method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get the feed
data = aio.feeds("Temperature").data.last
data.value = "adsfsdff"
data.save

Data Deletion

Values can be deleted by retrieving the data, and calling the delete method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.retrieve(288718)
puts data.delete

Helper Methods

There are a few helper methods that can make interacting with data a bit easier.

Send

You can use the aio.feeds(id).data.send_data(value) method to find or create the feed based on the name passed, and also save the value passed.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds("Test").data.send_data(5)
puts data.inspect

Last

You can get the last inserted value by using the aio.feeds(id).data.last method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.last
puts data.inspect

Next

You can get the first inserted value that has not been processed by using the aio.feeds(id).data.next method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.next
puts data.inspect

Previous

You can get the the last record that has been processed by using the aio.feeds(id).data.previous method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

data = aio.feeds(187).data.previous
puts data.inspect

Groups

Groups allow you to update and retrieve multiple feeds with one request. You can add feeds to multiple groups.

Group Creation

You can create a group by passing an object of group properties. If you would like to find information about what properties are available, please visit the Adafruit IO group API docs.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

puts aio.groups.create({:name => "Greenhouse"})

Group Retrieval

You can get a list of your groups by using the aio.groups.retrieve method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get all groups
#puts aio.groups.retrieve

You can also get a specific group by ID, key, or name by using the aio.groups.retrieve(id) method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

#get a single group
group = aio.groups.retrieve("First Group")
puts group.name
puts group.inspect

Group Updating

You can update group properties by retrieving a group, updating the object, and using the save method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => '463c8fc334cfb19318eAIO_KEY_HEREa0a17c01f5b985f77f545'

#get the group
group = aio.groups.retrieve("Greenhouse")
group.name = "Gymnasium"
group.description = "hey hey"
group.save

group.name = "Greenhouse"
group.description = "new description"
group.save

Group Deletion

You can delete a group by ID, key, or name by retrieving the group, and subsequently calling the delete method.

require 'adafruit/io'

# create an instance
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'

group = aio.groups.retrieve("Greenhouse")
puts group.delete

License

Copyright (c) 2014 Adafruit Industries. Licensed under the MIT license.

Contributing

1. Fork it ( http://github.com/adafruit/io-client-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request