adafruit-io 1.0.4 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf49702a000a24c8e91a39ef16ab202275be559c
-  data.tar.gz: 8cf000902c5787f6bc547b4ee263ba162e05ddb5
+  metadata.gz: afe1c61c665a4169c49212f7e179a571f3e11b60
+  data.tar.gz: 9ef600f6b460eee9dc128fa302a5575ef463d193
 SHA512:
-  metadata.gz: aa2a2359ffbdf5ba332ba55314ab32d81e92e5d2527e1546f3661d80b025a287060af80c5b25e5358ed4a221646b8818010028cf3ae57a0e68d24cdfb03cce16
-  data.tar.gz: f8f95579fbe13971780f0f71dbacd9740bef4bd0814e983dbefc65b53d11eea7643f42590e66524c0ab8dd2759997bef139f07bf66eaf045cda4d99feb5300a8
+  metadata.gz: fafc8ce872d75a0142a651fd115129b51b8bb36fa622570d739c9284d08d8092c90d2719fd2d2fa7dff12396beacd43d1f45fa789c085153a256dd2ab8cacf16
+  data.tar.gz: 0ae5c3f1de447e53c579b1624c8f792e46873bbc24ec56552ff36a30392df6f7c6c617d2dac26ceff55acdc55ec8b90b8ec8b6dc43cae981e47e9040b6d1d47a

data/LICENSE.md

@@ -1,5 +1,5 @@
 Copyright (c) 2014 Adafruit
-Author: Justin Cooper
+Author: Justin Cooper, Adam Bachman
 
 MIT License
 

data/README.md

@@ -4,354 +4,143 @@
 
 A [Ruby][1] client for use with with [io.adafruit.com][2].
 
-## Installation
+Note, this documentation covers the gem supporting V2 of the API, which is currently under active development and may be missing some features. It also breaks support for code that used version <= 1.0.4 of this library.
 
-Add this line to your application's Gemfile:
+Older releases are available at these links:
 
-    gem 'adafruit-io'
+* [1.0.4](https://github.com/adafruit/io-client-ruby/tree/v1.0.4)
+* [1.0.3](https://github.com/adafruit/io-client-ruby/tree/v1.0.3)
+* [1.0.0](https://github.com/adafruit/io-client-ruby/tree/v1.0.0)
 
-And then execute:
+This is a near complete rewrite and strip-down of the library intended to support V2 of the Adafruit IO API with less code, maintenance, and stress.
 
-    $ bundle
+Why rewrite? This lets us the replace the existing, custom ActiveRecord-based interface with a flat, stateless API client returning plain hashes based on the JSON returned from API.Instead of writing a bunch of Ruby to make it feel like we're in a Rails app, we're just providing hooks into the API and a thin wrapper around Faraday.
 
-Or install it yourself as:
+The API is not very complex, code that uses it shouldn't be either.
 
-    $ gem install adafruit-io
+## Roadmap
 
-## Usage
+It is our goal to eventually support all API V2 methods, but that will happen in stages.
 
-Each time you use the library, you'll want to pass your [AIO Key][4] to the client.
+- [x] Feeds `2.0.0.beta.1`
+- [x] Data `2.0.0.beta.1`
+- [x] Groups `2.0.0.beta.1`
+- Activities
+- Blocks
+- Dashboards
+- MQTT
+- Permissions
+- Sessions
+- Tokens
+- Triggers
 
-```ruby
-
-require 'adafruit/io'
-
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
-
-```
-
-## Table of Contents
-
-* [Feeds](#feeds)
-  * [Create](#feed-creation)
-  * [Read](#feed-retrieval)
-  * [Update](#feed-updating)
-  * [Delete](#feed-deletion)
-* [Data](#data)
-  * [Create](#data-creation)
-  * [Read](#data-retrieval)
-  * [Update](#data-updating)
-  * [Delete](#data-deletion)
-  * [Helper Methods](#helper-methods)
-    * [Send](#send)
-    * [Next](#next)
-    * [Last](#last)
-    * [Previous](#previous)
-  * [Readable](#readable-data)
-  * [Writable](#writable-data)
-* [Groups](#groups)
-  * [Create](#group-creation)
-  * [Read](#group-retrieval)
-  * [Update](#group-updating)
-  * [Delete](#group-deletion)
-
-### 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][3].
-
-```ruby
-require 'adafruit/io'
+## Installation
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
+Add this line to your application's Gemfile:
 
-puts aio.feeds.create({:name => "Temperature"})
-```
+    gem 'adafruit-io'
 
-#### Feed Retrieval
+And then execute:
 
-You can get a list of your feeds by using the `aio.feeds.retrieve` method.
+    $ bundle
 
-```ruby
-require 'adafruit/io'
+Or install it yourself as:
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
+    $ gem install adafruit-io
 
-#get all feeds
-puts aio.feeds.retrieve
-```
+## Basic Usage
 
-You can also get a specific feed by ID, key, or name by using the `aio.feeds.retrieve(id)` method.
+Each time you use the library, you'll want to pass your [AIO Key][4] to the client.
 
 ```ruby
-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][3] by retrieving a feed, and subsequently calling the save method.
-
-```ruby
 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
+aio = Adafruit::IO::Client.new key: 'KEY'
 ```
-#### Feed Deletion
 
-You can delete a feed by ID, key, or name by retrieving a feed, and subsequently calling the delete method.
+Since every API request requires a username, you can also pass a username to the client initializer.
 
 ```ruby
-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](#data-creation), by using the
-`aio.feeds(id).data.create(value)` method.
-
-```ruby
 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
+aio = Adafruit::IO::Client.new key: 'KEY', username: 'USERNAME'
 ```
 
-#### Data Retrieval
+All return values are plain Ruby hashes based on the JSON response returned by the API. Most basic requests should get back a Hash with a `key` field. The key can be used in subsequent requests. API requests that return a list of objects will return a simple array of hashes.
 
-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.
+Here's an example of creating, adding data to, and deleting a feed.
 
 ```ruby
 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.
+api_key = ENV['AIO_KEY']
+username = ENV['AIO_USER']
 
-```ruby
-require 'adafruit/io'
+api = Adafruit::IO::Client.new key: api_key, username: username
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
-
-data = aio.feeds(187).data.retrieve(288718)
-puts data.inspect
-```
+# create a feed
+puts "create"
+garbage = api.create_feed(name: "Garbage 123")
 
-#### Data Updating
+# add data
+puts "add data"
+api.send_data garbage, 'something'
+api.send_data garbage, 'goes here'
 
-Values can be updated by retrieving the data, updating the property, and subsequently calling the save method.
+# load data
+puts "load data"
+data = api.data(garbage)
+puts "#{data.size} points: #{ data.map {|d| d['value']}.join(', ') }"
 
-```ruby
-require 'adafruit/io'
+# get details
+puts "read"
+puts JSON.pretty_generate(api.feed_details(garbage))
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
+# delete feed
+puts "delete"
+api.delete_feed(garbage)
 
-#get the feed
-data = aio.feeds("Temperature").data.last
-data.value = "adsfsdff"
-data.save
+# try reading
+puts "read?"
+# ... get nothing
+puts api.feed(garbage['key']).inspect
 ```
 
-#### Data Deletion
-
-Values can be deleted by retrieving the data, and calling the delete method.
-
-```ruby
-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.
-
-```ruby
-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.
-
-```ruby
-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.
-
-```ruby
-require 'adafruit/io'
+## Table of Contents
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
+* [Feeds](#feeds)
+* [Data](#data)
+* [Groups](#groups)
+* [Dashboards](#dashboards)
+* [Blocks](#blocks)
+* [Activities](#activities)
+* [Triggers](#triggers)
+* [Permissions](#permissions)
+* [Tokens](#tokens)
 
-data = aio.feeds(187).data.next
-puts data.inspect
-```
+### Feeds
 
-##### Previous
+Create
 
-You can get the the last record that has been processed by using the `aio.feeds(id).data.previous` method.
 
-```ruby
-require 'adafruit/io'
 
-# create an instance
-aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
 
-data = aio.feeds(187).data.previous
-puts data.inspect
-```
 
+### Data
 ### Groups
+### Dashboards
+### Blocks
+### Activities
+### Triggers
+### Permissions
+### Tokens
 
-Groups allow you to update and retrieve multiple feeds with one request. You can add feeds
-to multiple groups.
-
-#### Group Creation
+## Pagination
 
-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][5].
-
-```ruby
-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.
-
-```ruby
-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.
-
-```ruby
-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][5] by retrieving a group, updating the object, and using the save method.
-
-```ruby
-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.
-
-```ruby
-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.