Class: M2X::Client::Device

Inherits:
Resource show all
Includes:
Metadata
Defined in:
lib/m2x/device.rb

Overview

Wrapper for AT&T M2X Device API m2x.att.com/developer/documentation/v2/device

Constant Summary collapse

PATH = 
"/devices"

Instance Attribute Summary

Attributes inherited from Resource

#attributes

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Metadata

#metadata_path, #read_metadata, #read_metadata_field, #update_metadata, #update_metadata_field

Methods inherited from Resource

#delete!, #initialize, #inspect, #refresh, #update!, #view

Constructor Details

This class inherits a constructor from M2X::Client::Resource

Class Method Details

.catalog(client, params = {}) ⇒ Object

Search the catalog of public Devices.

This allows unauthenticated users to search Devices from other users that have been marked as public, allowing them to read public Device metadata, locations, streams list, and view each Devices’ stream metadata and its values.

m2x.att.com/developer/documentation/v2/device#List-Search-Public-Devices-Catalog



39
40
41
42
43
 
# File 'lib/m2x/device.rb', line 39

def catalog(client, params={})
  res = client.get("#{PATH}/catalog", params)

  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
end

.create!(client, params) ⇒ Object

Create a new device

m2x.att.com/developer/documentation/v2/device#Create-Device



56
57
58
59
60
 
# File 'lib/m2x/device.rb', line 56

def create!(client, params)
  res = client.post(PATH, nil, params, "Content-Type" => "application/json")

  new(client, res.json) if res.success?
end

.list(client, params = {}) ⇒ Object

Retrieve the list of devices accessible by the authenticated API key

m2x.att.com/developer/documentation/v2/device#List-Devices



15
16
17
18
19
 
# File 'lib/m2x/device.rb', line 15

def list(client, params={})
  res = client.get(PATH, params)

  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
end

.search(client, params = {}) ⇒ Object

Retrieve the list of devices accessible by the authenticated API key that meet the search criteria.

m2x.att.com/developer/documentation/v2/device#Search-Devices



25
26
27
28
29
 
# File 'lib/m2x/device.rb', line 25

def search(client, params={})
  res = client.get("#{PATH}/search", params)

  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
end

.tags(client) ⇒ Object

List Device Tags Retrieve the list of device tags for the authenticated user.

m2x.att.com/developer/documentation/v2/device#List-Device-Tags



49
50
51
 
# File 'lib/m2x/device.rb', line 49

def tags(client)
  client.get("#{PATH}/tags")
end

Instance Method Details

#command(id) ⇒ Object

Device’s View of Command Details

Get details of a received command including the delivery information for this device.

m2x.att.com/developer/documentation/v2/commands#Device-s-View-of-Command-Details



240
241
242
243
244
 
# File 'lib/m2x/device.rb', line 240

def command(id)
  res = @client.get("#{path}/commands/#{id}")

  M2X::Client::Command.new(@client, res.json) if res.success?
end

#commands(params = {}) ⇒ Object

Device’s List of Received Commands

Retrieve the list of recent commands sent to the current device (as given by the API key).

m2x.att.com/developer/documentation/v2/commands#Device-s-List-of-Received-Commands



229
230
231
232
233
 
# File 'lib/m2x/device.rb', line 229

def commands(params = {})
  res = @client.get("#{path}/commands", params)

  res.json["commands"].map { |atts| M2X::Client::Command.new(@client, atts) } if res.success?
end

#create_key(params) ⇒ Object

Creates a new API key associated to the device

If a parameter named ‘stream` is supplied with a stream name, it will create an API key associated with that stream only.



220
221
222
 
# File 'lib/m2x/device.rb', line 220

def create_key(params)
  ::M2X::Client::Key.create!(@client, params.merge(device: self["id"]))
end

#keys ⇒ Object

Returns a list of API keys associated with the device



212
213
214
 
# File 'lib/m2x/device.rb', line 212

def keys
  ::M2X::Client::Key.list(@client, params.merge(device: self["id"]))
end

#location ⇒ Object

Get location details of an existing Device.

Note that this method can return an empty value (response status of 204) if the device has no location defined.

m2x.att.com/developer/documentation/v2/device#Read-Device-Location



82
83
84
 
# File 'lib/m2x/device.rb', line 82

def location
  @client.get("#{path}/location")
end

#location_history(params = {}) ⇒ Object

Read Device Location History

Get location history details of an existing Device. Returns the 30 most recently logged locations by default. m2x.att.com/developer/documentation/v2/device#Read-Device-Location-History



91
92
93
 
# File 'lib/m2x/device.rb', line 91

def location_history(params = {})
  @client.get("#{path}/location/waypoints", params)
end

#log ⇒ Object

View Request Log Retrieve list of HTTP requests received lately by the specified device (up to 100 entries).

m2x.att.com/developer/documentation/v2/device#View-Request-Log



72
73
74
 
# File 'lib/m2x/device.rb', line 72

def log
  @client.get("#{path}/log")
end

#path ⇒ Object 



63
64
65
 
# File 'lib/m2x/device.rb', line 63

def path
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
end

#post_update(params) ⇒ Object

Post Device Update (Single Value to Multiple Streams)

This method allows posting a single value to multiple streams belonging to a device and optionally, the device’s location.

All the streams should be created before posting values using this method.

The ‘params` parameter accepts a Hash which can contain the following keys:

- values:    A Hash in which the keys are the stream names and the values
             hold the stream values.
- location:  (optional) A hash with the current location of the specified
             device.
- timestamp: (optional) The timestamp for all the passed values and
             location. If ommited, the M2X server's time will be used.

   {
      values: {
          temperature: 30,
          humidity:    80
      },
      location: {
        name:      "Storage Room",
        latitude:  -37.9788423562422,
        longitude: -57.5478776916862,
        elevation: 5
      }
   }

m2x.att.com/developer/documentation/v2/device#Post-Device-Update–Single-Values-to-Multiple-Streams-



161
162
163
 
# File 'lib/m2x/device.rb', line 161

def post_update(params)
  @client.post("#{path}/update", nil, params, "Content-Type" => "application/json")
end

#post_updates(params) ⇒ Object

Post Device Updates (Multiple Values to Multiple Streams)

This method allows posting multiple values to multiple streams belonging to a device and optionally, the device location.

All the streams should be created before posting values using this method.

The ‘values` parameter contains an object with one attribute per each stream to be updated. The value of each one of these attributes is an array of timestamped values.

{
   temperature: [
                  { "timestamp": <Time in ISO8601>, "value": x },
                  { "timestamp": <Time in ISO8601>, "value": y },
                ],
   humidity:    [
                  { "timestamp": <Time in ISO8601>, "value": x },
                  { "timestamp": <Time in ISO8601>, "value": y },
                ]

}

The optional location attribute can contain location information that will be used to update the current location of the specified device

m2x.att.com/developer/documentation/v2/device#Post-Device-Updates–Multiple-Values-to-Multiple-Streams-



128
129
130
 
# File 'lib/m2x/device.rb', line 128

def post_updates(params)
  @client.post("#{path}/updates", nil, params, "Content-Type" => "application/json")
end

#process_command(id, params = {}) ⇒ Object

Process a command

m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Processed



249
250
251
 
# File 'lib/m2x/device.rb', line 249

def process_command(id, params = {})
  @client.post("#{path}/commands/#{id}/process", nil, params)
end

#reject_command(id, params = {}) ⇒ Object

Reject a command

m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Rejected



256
257
258
 
# File 'lib/m2x/device.rb', line 256

def reject_command(id, params = {})
  @client.post("#{path}/commands/#{id}/reject", nil, params)
end

#stream(name) ⇒ Object

Get details of a specific data Stream associated with the device

m2x.att.com/developer/documentation/v2/device#View-Data-Stream



196
197
198
 
# File 'lib/m2x/device.rb', line 196

def stream(name)
  ::M2X::Client::Stream.fetch(@client, self, name)
end

#streams ⇒ Object

Retrieve list of data streams associated with the device.

m2x.att.com/developer/documentation/v2/device#List-Data-Streams



189
190
191
 
# File 'lib/m2x/device.rb', line 189

def streams
  ::M2X::Client::Stream.list(@client, self)
end

#update_location(params) ⇒ Object

Update the current location of the specified device.

m2x.att.com/developer/documentation/v2/device#Update-Device-Location



98
99
100
 
# File 'lib/m2x/device.rb', line 98

def update_location(params)
  @client.put("#{path}/location", nil, params, "Content-Type" => "application/json")
end

#update_stream(name, params = {}) ⇒ Object Also known as: create_stream

Update a data stream associated with the Device (if a stream with this name does not exist it gets created).

m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream



204
205
206
207
208
 
# File 'lib/m2x/device.rb', line 204

def update_stream(name, params={})
  stream = ::M2X::Client::Stream.new(@client, self, "name" => name)

  stream.update!(params)
end

#values(params = {}) ⇒ Object

List Values from all Data Streams of a Device

m2x.att.com/developer/documentation/v2/device#List-Values-from-all-Data-Streams-of-a-Device



168
169
170
 
# File 'lib/m2x/device.rb', line 168

def values(params = {})
  @client.get("#{path}/values", params)
end

#values_export(params = {}) ⇒ Object

Export Values from all Data Streams of a Device

m2x.att.com/developer/documentation/v2/device#Export-Values-from-all-Data-Streams-of-a-Device



175
176
177
 
# File 'lib/m2x/device.rb', line 175

def values_export(params = {})
  @client.get("#{path}/values/export.csv", params)
end

#values_search(params) ⇒ Object

Search Values from all Data Streams of a Device

m2x.att.com/developer/documentation/v2/device#Search-Values-from-all-Data-Streams-of-a-Device



182
183
184
 
# File 'lib/m2x/device.rb', line 182

def values_search(params)
  @client.get("#{path}/values/search", nil, params, "Content-Type" => "application/json")
end