adafruit-io 1.0.4 → 2.0.0.beta.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/LICENSE.md +1 -1
- data/README.md +79 -290
- data/adafruit-io.gemspec +1 -4
- data/lib/adafruit/io.rb +1 -2
- data/lib/adafruit/io/arguments.rb +73 -0
- data/lib/adafruit/io/client.rb +36 -38
- data/lib/adafruit/io/client/data.rb +103 -51
- data/lib/adafruit/io/client/feeds.rb +60 -0
- data/lib/adafruit/io/client/groups.rb +63 -0
- data/lib/adafruit/io/client/tokens.rb +48 -0
- data/lib/adafruit/io/configurable.rb +22 -0
- data/lib/adafruit/io/request_handler.rb +126 -0
- data/lib/adafruit/io/version.rb +1 -1
- metadata +13 -51
- data/lib/adafruit/io/client/feed.rb +0 -55
- data/lib/adafruit/io/client/group.rb +0 -87
- data/lib/adafruit/io/client/io_object.rb +0 -90
- data/lib/adafruit/io/client/request_handler.rb +0 -42
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: afe1c61c665a4169c49212f7e179a571f3e11b60
|
4
|
+
data.tar.gz: 9ef600f6b460eee9dc128fa302a5575ef463d193
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fafc8ce872d75a0142a651fd115129b51b8bb36fa622570d739c9284d08d8092c90d2719fd2d2fa7dff12396beacd43d1f45fa789c085153a256dd2ab8cacf16
|
7
|
+
data.tar.gz: 0ae5c3f1de447e53c579b1624c8f792e46873bbc24ec56552ff36a30392df6f7c6c617d2dac26ceff55acdc55ec8b90b8ec8b6dc43cae981e47e9040b6d1d47a
|
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -4,354 +4,143 @@
|
|
4
4
|
|
5
5
|
A [Ruby][1] client for use with with [io.adafruit.com][2].
|
6
6
|
|
7
|
-
|
7
|
+
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.
|
8
8
|
|
9
|
-
|
9
|
+
Older releases are available at these links:
|
10
10
|
|
11
|
-
|
11
|
+
* [1.0.4](https://github.com/adafruit/io-client-ruby/tree/v1.0.4)
|
12
|
+
* [1.0.3](https://github.com/adafruit/io-client-ruby/tree/v1.0.3)
|
13
|
+
* [1.0.0](https://github.com/adafruit/io-client-ruby/tree/v1.0.0)
|
12
14
|
|
13
|
-
|
15
|
+
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.
|
14
16
|
|
15
|
-
|
17
|
+
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.
|
16
18
|
|
17
|
-
|
19
|
+
The API is not very complex, code that uses it shouldn't be either.
|
18
20
|
|
19
|
-
|
21
|
+
## Roadmap
|
20
22
|
|
21
|
-
|
23
|
+
It is our goal to eventually support all API V2 methods, but that will happen in stages.
|
22
24
|
|
23
|
-
|
25
|
+
- [x] Feeds `2.0.0.beta.1`
|
26
|
+
- [x] Data `2.0.0.beta.1`
|
27
|
+
- [x] Groups `2.0.0.beta.1`
|
28
|
+
- Activities
|
29
|
+
- Blocks
|
30
|
+
- Dashboards
|
31
|
+
- MQTT
|
32
|
+
- Permissions
|
33
|
+
- Sessions
|
34
|
+
- Tokens
|
35
|
+
- Triggers
|
24
36
|
|
25
|
-
|
26
|
-
|
27
|
-
require 'adafruit/io'
|
28
|
-
|
29
|
-
# create an instance
|
30
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
31
|
-
|
32
|
-
```
|
33
|
-
|
34
|
-
## Table of Contents
|
35
|
-
|
36
|
-
* [Feeds](#feeds)
|
37
|
-
* [Create](#feed-creation)
|
38
|
-
* [Read](#feed-retrieval)
|
39
|
-
* [Update](#feed-updating)
|
40
|
-
* [Delete](#feed-deletion)
|
41
|
-
* [Data](#data)
|
42
|
-
* [Create](#data-creation)
|
43
|
-
* [Read](#data-retrieval)
|
44
|
-
* [Update](#data-updating)
|
45
|
-
* [Delete](#data-deletion)
|
46
|
-
* [Helper Methods](#helper-methods)
|
47
|
-
* [Send](#send)
|
48
|
-
* [Next](#next)
|
49
|
-
* [Last](#last)
|
50
|
-
* [Previous](#previous)
|
51
|
-
* [Readable](#readable-data)
|
52
|
-
* [Writable](#writable-data)
|
53
|
-
* [Groups](#groups)
|
54
|
-
* [Create](#group-creation)
|
55
|
-
* [Read](#group-retrieval)
|
56
|
-
* [Update](#group-updating)
|
57
|
-
* [Delete](#group-deletion)
|
58
|
-
|
59
|
-
### Feeds
|
60
|
-
|
61
|
-
Feeds are the core of the Adafruit IO system. The feed holds metadata about data that gets pushed, and you will
|
62
|
-
have one feed for each type of data you send to the system. You can have separate feeds for each
|
63
|
-
sensor in a project, or you can use one feed to contain JSON encoded data for all of your sensors.
|
64
|
-
|
65
|
-
#### Feed Creation
|
66
|
-
|
67
|
-
You have two options here, you can create a feed by passing a feed name, or you can pass an object if you would
|
68
|
-
like to define more properties. If you would like to find information about what properties are available, please
|
69
|
-
visit the [Adafruit IO feed API docs][3].
|
70
|
-
|
71
|
-
```ruby
|
72
|
-
require 'adafruit/io'
|
37
|
+
## Installation
|
73
38
|
|
74
|
-
|
75
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
39
|
+
Add this line to your application's Gemfile:
|
76
40
|
|
77
|
-
|
78
|
-
```
|
41
|
+
gem 'adafruit-io'
|
79
42
|
|
80
|
-
|
43
|
+
And then execute:
|
81
44
|
|
82
|
-
|
45
|
+
$ bundle
|
83
46
|
|
84
|
-
|
85
|
-
require 'adafruit/io'
|
47
|
+
Or install it yourself as:
|
86
48
|
|
87
|
-
|
88
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
49
|
+
$ gem install adafruit-io
|
89
50
|
|
90
|
-
|
91
|
-
puts aio.feeds.retrieve
|
92
|
-
```
|
51
|
+
## Basic Usage
|
93
52
|
|
94
|
-
|
53
|
+
Each time you use the library, you'll want to pass your [AIO Key][4] to the client.
|
95
54
|
|
96
55
|
```ruby
|
97
|
-
require 'adafruit/io'
|
98
56
|
|
99
|
-
# create an instance
|
100
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
101
|
-
|
102
|
-
#get a single feed
|
103
|
-
feed = aio.feeds.retrieve("Temperature")
|
104
|
-
puts feed.name
|
105
|
-
puts feed.last_value
|
106
|
-
```
|
107
|
-
#### Feed Updating
|
108
|
-
|
109
|
-
You can update [feed properties][3] by retrieving a feed, and subsequently calling the save method.
|
110
|
-
|
111
|
-
```ruby
|
112
57
|
require 'adafruit/io'
|
113
58
|
|
114
59
|
# create an instance
|
115
|
-
aio = Adafruit::IO::Client.new :
|
116
|
-
|
117
|
-
#get the feed
|
118
|
-
feed = aio.feeds.retrieve("Temperature")
|
119
|
-
feed.name = "adsfsdff"
|
120
|
-
feed.description = "hey hey"
|
121
|
-
feed.save
|
60
|
+
aio = Adafruit::IO::Client.new key: 'KEY'
|
122
61
|
```
|
123
|
-
#### Feed Deletion
|
124
62
|
|
125
|
-
|
63
|
+
Since every API request requires a username, you can also pass a username to the client initializer.
|
126
64
|
|
127
65
|
```ruby
|
128
|
-
require 'adafruit/io'
|
129
66
|
|
130
|
-
# create an instance
|
131
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
132
|
-
|
133
|
-
feed = aio.feeds.retrieve("Temperature")
|
134
|
-
puts feed.delete
|
135
|
-
```
|
136
|
-
|
137
|
-
### Data
|
138
|
-
|
139
|
-
Data represents the data contained in feeds. You can read, add, modify, and delete data. There are also
|
140
|
-
a few convienient methods for sending data to feeds and selecting certain pieces of data.
|
141
|
-
|
142
|
-
#### Data Creation
|
143
|
-
|
144
|
-
Data can be created [after you create a feed](#data-creation), by using the
|
145
|
-
`aio.feeds(id).data.create(value)` method.
|
146
|
-
|
147
|
-
```ruby
|
148
67
|
require 'adafruit/io'
|
149
68
|
|
150
69
|
# create an instance
|
151
|
-
aio = Adafruit::IO::Client.new :
|
152
|
-
|
153
|
-
data = aio.feeds("Temperature").data.create({:value => 11})
|
154
|
-
puts data.inspect
|
70
|
+
aio = Adafruit::IO::Client.new key: 'KEY', username: 'USERNAME'
|
155
71
|
```
|
156
72
|
|
157
|
-
|
73
|
+
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.
|
158
74
|
|
159
|
-
|
160
|
-
callback will be called with errors and the data array as arguments.
|
75
|
+
Here's an example of creating, adding data to, and deleting a feed.
|
161
76
|
|
162
77
|
```ruby
|
163
78
|
require 'adafruit/io'
|
164
79
|
|
165
|
-
|
166
|
-
|
167
|
-
|
168
|
-
data = aio.feeds(187).data.retrieve
|
169
|
-
puts data.inspect
|
170
|
-
```
|
171
|
-
|
172
|
-
You can also get a specific value by ID by using the `aio.feeds(id).data.retrieve(id)` method.
|
80
|
+
api_key = ENV['AIO_KEY']
|
81
|
+
username = ENV['AIO_USER']
|
173
82
|
|
174
|
-
|
175
|
-
require 'adafruit/io'
|
83
|
+
api = Adafruit::IO::Client.new key: api_key, username: username
|
176
84
|
|
177
|
-
# create
|
178
|
-
|
179
|
-
|
180
|
-
data = aio.feeds(187).data.retrieve(288718)
|
181
|
-
puts data.inspect
|
182
|
-
```
|
85
|
+
# create a feed
|
86
|
+
puts "create"
|
87
|
+
garbage = api.create_feed(name: "Garbage 123")
|
183
88
|
|
184
|
-
|
89
|
+
# add data
|
90
|
+
puts "add data"
|
91
|
+
api.send_data garbage, 'something'
|
92
|
+
api.send_data garbage, 'goes here'
|
185
93
|
|
186
|
-
|
94
|
+
# load data
|
95
|
+
puts "load data"
|
96
|
+
data = api.data(garbage)
|
97
|
+
puts "#{data.size} points: #{ data.map {|d| d['value']}.join(', ') }"
|
187
98
|
|
188
|
-
|
189
|
-
|
99
|
+
# get details
|
100
|
+
puts "read"
|
101
|
+
puts JSON.pretty_generate(api.feed_details(garbage))
|
190
102
|
|
191
|
-
#
|
192
|
-
|
103
|
+
# delete feed
|
104
|
+
puts "delete"
|
105
|
+
api.delete_feed(garbage)
|
193
106
|
|
194
|
-
#
|
195
|
-
|
196
|
-
|
197
|
-
|
107
|
+
# try reading
|
108
|
+
puts "read?"
|
109
|
+
# ... get nothing
|
110
|
+
puts api.feed(garbage['key']).inspect
|
198
111
|
```
|
199
112
|
|
200
|
-
|
201
|
-
|
202
|
-
Values can be deleted by retrieving the data, and calling the delete method.
|
203
|
-
|
204
|
-
```ruby
|
205
|
-
require 'adafruit/io'
|
206
|
-
|
207
|
-
# create an instance
|
208
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
209
|
-
|
210
|
-
data = aio.feeds(187).data.retrieve(288718)
|
211
|
-
puts data.delete
|
212
|
-
```
|
213
|
-
|
214
|
-
#### Helper Methods
|
215
|
-
|
216
|
-
There are a few helper methods that can make interacting with data a bit easier.
|
217
|
-
|
218
|
-
##### Send
|
219
|
-
|
220
|
-
You can use the `aio.feeds(id).data.send_data(value)` method to find or create the feed based on the name passed,
|
221
|
-
and also save the value passed.
|
222
|
-
|
223
|
-
```ruby
|
224
|
-
require 'adafruit/io'
|
225
|
-
|
226
|
-
# create an instance
|
227
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
228
|
-
|
229
|
-
data = aio.feeds("Test").data.send_data(5)
|
230
|
-
puts data.inspect
|
231
|
-
```
|
232
|
-
|
233
|
-
##### Last
|
234
|
-
|
235
|
-
You can get the last inserted value by using the `aio.feeds(id).data.last` method.
|
236
|
-
|
237
|
-
```ruby
|
238
|
-
require 'adafruit/io'
|
239
|
-
|
240
|
-
# create an instance
|
241
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
242
|
-
|
243
|
-
data = aio.feeds(187).data.last
|
244
|
-
puts data.inspect
|
245
|
-
```
|
246
|
-
|
247
|
-
##### Next
|
248
|
-
|
249
|
-
You can get the first inserted value that has not been processed by using the `aio.feeds(id).data.next` method.
|
250
|
-
|
251
|
-
```ruby
|
252
|
-
require 'adafruit/io'
|
113
|
+
## Table of Contents
|
253
114
|
|
254
|
-
#
|
255
|
-
|
115
|
+
* [Feeds](#feeds)
|
116
|
+
* [Data](#data)
|
117
|
+
* [Groups](#groups)
|
118
|
+
* [Dashboards](#dashboards)
|
119
|
+
* [Blocks](#blocks)
|
120
|
+
* [Activities](#activities)
|
121
|
+
* [Triggers](#triggers)
|
122
|
+
* [Permissions](#permissions)
|
123
|
+
* [Tokens](#tokens)
|
256
124
|
|
257
|
-
|
258
|
-
puts data.inspect
|
259
|
-
```
|
125
|
+
### Feeds
|
260
126
|
|
261
|
-
|
127
|
+
Create
|
262
128
|
|
263
|
-
You can get the the last record that has been processed by using the `aio.feeds(id).data.previous` method.
|
264
129
|
|
265
|
-
```ruby
|
266
|
-
require 'adafruit/io'
|
267
130
|
|
268
|
-
# create an instance
|
269
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
270
131
|
|
271
|
-
data = aio.feeds(187).data.previous
|
272
|
-
puts data.inspect
|
273
|
-
```
|
274
132
|
|
133
|
+
### Data
|
275
134
|
### Groups
|
135
|
+
### Dashboards
|
136
|
+
### Blocks
|
137
|
+
### Activities
|
138
|
+
### Triggers
|
139
|
+
### Permissions
|
140
|
+
### Tokens
|
276
141
|
|
277
|
-
|
278
|
-
to multiple groups.
|
279
|
-
|
280
|
-
#### Group Creation
|
142
|
+
## Pagination
|
281
143
|
|
282
|
-
You can create a group by passing an object of group properties. If you would like to find
|
283
|
-
information about what properties are available, please visit the [Adafruit IO group API docs][5].
|
284
|
-
|
285
|
-
```ruby
|
286
|
-
require 'adafruit/io'
|
287
|
-
|
288
|
-
# create an instance
|
289
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
290
|
-
|
291
|
-
puts aio.groups.create({:name => "Greenhouse"})
|
292
|
-
```
|
293
|
-
|
294
|
-
#### Group Retrieval
|
295
|
-
|
296
|
-
You can get a list of your groups by using the `aio.groups.retrieve` method.
|
297
|
-
|
298
|
-
```ruby
|
299
|
-
require 'adafruit/io'
|
300
|
-
|
301
|
-
# create an instance
|
302
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
303
|
-
|
304
|
-
#get all groups
|
305
|
-
#puts aio.groups.retrieve
|
306
|
-
```
|
307
|
-
|
308
|
-
You can also get a specific group by ID, key, or name by using the `aio.groups.retrieve(id)` method.
|
309
|
-
|
310
|
-
```ruby
|
311
|
-
require 'adafruit/io'
|
312
|
-
|
313
|
-
# create an instance
|
314
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
315
|
-
|
316
|
-
#get a single group
|
317
|
-
group = aio.groups.retrieve("First Group")
|
318
|
-
puts group.name
|
319
|
-
puts group.inspect
|
320
|
-
```
|
321
|
-
#### Group Updating
|
322
|
-
|
323
|
-
You can update [group properties][5] by retrieving a group, updating the object, and using the save method.
|
324
|
-
|
325
|
-
```ruby
|
326
|
-
require 'adafruit/io'
|
327
|
-
|
328
|
-
# create an instance
|
329
|
-
aio = Adafruit::IO::Client.new :key => '463c8fc334cfb19318eAIO_KEY_HEREa0a17c01f5b985f77f545'
|
330
|
-
|
331
|
-
#get the group
|
332
|
-
group = aio.groups.retrieve("Greenhouse")
|
333
|
-
group.name = "Gymnasium"
|
334
|
-
group.description = "hey hey"
|
335
|
-
group.save
|
336
|
-
|
337
|
-
group.name = "Greenhouse"
|
338
|
-
group.description = "new description"
|
339
|
-
group.save
|
340
|
-
```
|
341
|
-
|
342
|
-
#### Group Deletion
|
343
|
-
|
344
|
-
You can delete a group by ID, key, or name by retrieving the group, and subsequently calling the delete method.
|
345
|
-
|
346
|
-
```ruby
|
347
|
-
require 'adafruit/io'
|
348
|
-
|
349
|
-
# create an instance
|
350
|
-
aio = Adafruit::IO::Client.new :key => 'AIO_KEY_HERE'
|
351
|
-
|
352
|
-
group = aio.groups.retrieve("Greenhouse")
|
353
|
-
puts group.delete
|
354
|
-
```
|
355
144
|
|
356
145
|
## License
|
357
146
|
Copyright (c) 2014 Adafruit Industries. Licensed under the MIT license.
|