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



250
251
252
253
254
 
# File 'lib/m2x/device.rb', line 250

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



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

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.



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

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

#delete_locations!(start, stop) ⇒ Object

Delete waypoints in a device’s location history by a date range The ‘start` and `stop` parameters should be ISO8601 timestamps

m2x.att.com/developer/documentation/v2/device#Delete-Location-History



106
107
108
109
110
 
# File 'lib/m2x/device.rb', line 106

def delete_locations!(start, stop)
  params = { from: start, end: stop }

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

#keys ⇒ Object

Returns a list of API keys associated with the device



222
223
224
 
# File 'lib/m2x/device.rb', line 222

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-



171
172
173
 
# File 'lib/m2x/device.rb', line 171

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-



138
139
140
 
# File 'lib/m2x/device.rb', line 138

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



259
260
261
 
# File 'lib/m2x/device.rb', line 259

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



266
267
268
 
# File 'lib/m2x/device.rb', line 266

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



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

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



199
200
201
 
# File 'lib/m2x/device.rb', line 199

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



214
215
216
217
218
 
# File 'lib/m2x/device.rb', line 214

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



178
179
180
 
# File 'lib/m2x/device.rb', line 178

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



185
186
187
 
# File 'lib/m2x/device.rb', line 185

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



192
193
194
 
# File 'lib/m2x/device.rb', line 192

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