m2x-mqtt 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7b40f2dd197405129dea92eee3a9524a2ef941f0
+  data.tar.gz: 7c0504db6e1027b964e375338a62c77d20b4c5e1
+SHA512:
+  metadata.gz: 695edb1116ab19e40677f7b5d93ea1c69196098738013e8959f5faaa56b247aa4c71794edbd0144583968840d450448c2c79b4f6cca7e92ef724bae27d6e1940
+  data.tar.gz: a8066d83bd256be686471e6ae476383fb1c1e28417706fcc66e9e895b00dfd797ce3e2609340e6aaac5a7fa93850009c91baa17e88353d285e5d1c619e2fda87

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 AT&T M2X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,135 @@
+# AT&T's M2X Ruby (MQTT) Client
+
+[AT&T’s M2X](https://m2x.att.com/) is a cloud-based fully managed data storage service for network connected machine-to-machine (M2M) devices. From trucks and turbines to vending machines and freight containers, M2X enables the devices that power your business to connect and share valuable data.
+
+This library aims to provide a simple wrapper to interact with the [AT&T M2X API](https://m2x.att.com/developer/documentation/overview) for [Ruby](https://www.ruby-lang.org/en/) using the [MQTT protocol](http://mqtt.org/). Refer to the [Glossary of Terms](https://m2x.att.com/developer/documentation/glossary) to understand the nomenclature used throughout this documentation.
+
+
+Getting Started
+==========================
+1. Signup for an [M2X Account](https://m2x.att.com/signup).
+2. Obtain your _Master Key_ from the Master Keys tab of your [Account Settings](https://m2x.att.com/account) screen.
+2. Create your first [Device](https://m2x.att.com/devices) and copy its _Device ID_.
+3. Review the [M2X API Documentation](https://m2x.att.com/developer/documentation/overview).
+
+## Installation
+
+```bash
+$ gem install m2x-mqtt
+```
+## Usage
+
+In order to communicate with the M2X API, you need an instance of [M2X::MQTT](lib/m2x/mqtt.rb). You need to pass your API key in the constructor to access your data.
+
+```ruby
+m2x = M2X::MQTT.new(<YOUR-API-KEY>)
+```
+
+This provides an interface to your data in M2X
+
+- [Distribution](lib/m2x/mqtt/distribution.rb)
+  ```ruby
+  distribution = m2x.distribution("<DISTRIBUTION-ID>")
+  ```
+
+- [Device](lib/m2x/mqtt/device.rb)
+  ```ruby
+  device = m2x.device("<DEVICE-ID>")
+  ```
+
+- [Stream](lib/m2x/mqtt/stream.rb)
+  ```ruby
+  stream = m2x.stream("<DEVICE-ID>", "<STREAM-NAME>")
+
+  stream = m2x.device("<DEVICE-ID>").stream("<STREAM-NAME>")
+  ```
+
+Refer to the documentation on each class for further usage instructions.
+
+## Example
+
+In order to run this example, you will need a `Device ID` and `API Key`. If you don't have any, access your M2X account, create a new [Device](https://m2x.att.com/devices), and copy the `Device ID` and `API Key` values. The following script will send your CPU load average to three different streams named `load_1m`, `load_5m` and `load_15`. Check that there's no need to create a stream in order to write values into it.
+
+In order to execute this script, run:
+
+```bash
+API_KEY=<YOUR-API-KEY> DEVICE=<YOUR-DEVICE-ID> ./m2x-uptime.rb
+```
+
+```ruby
+#! /usr/bin/env ruby
+
+#
+# https://github.com/attm2x/m2x-ruby-mqtt#example
+# for instructions
+#
+
+require "time"
+require "m2x/mqtt"
+
+API_KEY = ENV.fetch("API_KEY")
+DEVICE  = ENV.fetch("DEVICE")
+
+puts "M2X::MQTT/#{M2X::MQTT::VERSION} example"
+
+@run = true
+
+stop = Proc.new { @run = false }
+
+trap(:INT,  &stop)
+trap(:TERM, &stop)
+
+# Match `uptime` load averages output for both Linux and OSX
+UPTIME_RE = /(\d+\.\d+),? (\d+\.\d+),? (\d+\.\d+)$/
+
+def load_avg
+  `uptime`.match(UPTIME_RE).captures
+end
+
+m2x = M2X::MQTT.new(API_KEY)
+
+# Get the device
+device = m2x.device(DEVICE)
+
+# Create the streams if they don't exist
+device.stream("load_1m").update!
+device.stream("load_5m").update!
+device.stream("load_15m").update!
+
+while @run
+  load_1m, load_5m, load_15m = load_avg
+
+  # Write the different values into AT&T M2X
+  now = Time.now.iso8601
+
+  values = {
+    load_1m:  [ { value: load_1m,  timestamp: now } ],
+    load_5m:  [ { value: load_5m,  timestamp: now } ],
+    load_15m: [ { value: load_15m, timestamp: now } ]
+  }
+
+  res = device.post_updates(values: values)
+
+  sleep 1
+end
+
+puts
+```
+
+You can find this script in [`examples/m2x-uptime.rb`](examples/m2x-uptime.rb).
+
+## Versioning
+
+This gem aims to adhere to [Semantic Versioning 2.0.0](http://semver.org/). As a summary, given a version number `MAJOR.MINOR.PATCH`:
+
+1. `MAJOR` will increment when backwards-incompatible changes are introduced to the client.
+2. `MINOR` will increment when backwards-compatible functionality is added.
+3. `PATCH` will increment with backwards-compatible bug fixes.
+
+Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format.
+
+**Note**: the client version does not necessarily reflect the version used in the AT&T M2X API.
+
+## License
+
+This gem is provided under the MIT license. See [LICENSE](LICENSE) for applicable terms.

data/lib/m2x/mqtt.rb

@@ -0,0 +1,47 @@
+module M2X
+  class MQTT
+    require_relative "mqtt/version"
+    require_relative "mqtt/client"
+    require_relative "mqtt/resource"
+    require_relative "mqtt/device"
+    require_relative "mqtt/distribution"
+    require_relative "mqtt/stream"
+
+    attr_accessor :client
+
+    def initialize(api_key, options={})
+      @api_key = api_key
+      @options = options
+    end
+
+    def client
+      @client ||= M2X::MQTT::Client.new(@api_key, @options)
+    end
+
+    # Returns the status of the M2X system.
+    #
+    # The response to this endpoint is an object in which each of its attributes
+    # represents an M2X subsystem and its current status.
+    def status
+      client.subscribe
+      client.get("/status")
+      client.get_response
+    end
+
+    def device(id)
+      M2X::MQTT::Device.new(client, "id" => id)
+    end
+
+    def create_device(attributes)
+      M2X::MQTT::Device.create!(client, attributes)
+    end
+
+    def distribution(id)
+      M2X::MQTT::Distribution.new(client, "id" => id)
+    end
+
+    def stream(device_id, name)
+      M2X::MQTT::Stream.new(client, device(device_id), "name" => name)
+    end
+  end
+end

data/lib/m2x/mqtt/client.rb

@@ -0,0 +1,117 @@
+require "mqtt"
+require "json"
+require "securerandom"
+
+class M2X::MQTT::Client
+  DEFAULT_API_URL = "api-m2x.att.com".freeze
+  API_VERSION     = "v2"
+
+  USER_AGENT = "M2X-Ruby/#{M2X::MQTT::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION} (#{RUBY_PLATFORM})".freeze
+
+  DEFAULTS = {
+    api_url: DEFAULT_API_URL,
+    use_ssl: false
+  }
+
+  def initialize(api_key, options={})
+    @api_key = api_key
+    @options = DEFAULTS.merge(options)
+  end
+
+  # Public: Subscribe the client to the responses topic.
+  #
+  # This is required in order to receive responses from the
+  # M2X API server. Note that #get_response already subscribes
+  # the client.
+  def subscribe
+    mqtt_client.subscribe(response_topic)
+  end
+
+  # Public: Send a payload to the M2X API server.
+  #
+  # payload - a Hash with the following keys:
+  #           :id
+  #           :method
+  #           :resource
+  #           :body
+  # See https://m2x.att.com/developer/documentation/v2/mqtt
+  def publish(payload)
+    mqtt_client.publish(request_topic, payload.to_json)
+  end
+
+  # Public: Retrieve a response from the M2X Server.
+  #
+  # Returns a Hash with the response from the MQTT Server in M2X.
+  # Optionally receives a block which will iterate through responses
+  # and yield each one.
+  def get_response
+    return JSON.parse(mqtt_client.get_packet(response_topic).payload) unless block_given?
+
+    mqtt_client.get_packet(response_topic) do |packet|
+      yield JSON.parse(packet.payload)
+    end
+  end
+
+  [:get, :post, :put, :delete, :head, :options, :patch].each do |verb|
+    define_method verb do |path, params=nil|
+      request(verb, path, params)
+    end
+  end
+
+  private
+
+  def request(verb, path, params=nil)
+    path  = versioned(path)
+    body  = params || {}
+
+    payload = {
+      id:       SecureRandom.hex,
+      agent:    USER_AGENT,
+      method:   verb.upcase,
+      resource: path,
+      body:     body
+    }
+
+    publish(payload)
+
+    { id: payload[:id] }
+  end
+
+  def request_topic
+    @request_topic ||= "m2x/#{@api_key}/requests".freeze
+  end
+
+  def response_topic
+    @response_topic ||= "m2x/#{@api_key}/responses".freeze
+  end
+
+  def mqtt_client
+    @mqtt_client ||= ::MQTT::Client.new.tap do |client|
+                       client.host     = @options[:api_url]
+                       client.username = @api_key
+
+                       if @options[:use_ssl]
+                         client.ssl  = true
+                         client.port = 8883
+                       end
+                     end
+
+    unless @mqtt_client.connected?
+      @mqtt_client.connect
+    end
+
+    @mqtt_client
+  end
+
+  def versioned(path)
+    versioned?(path) ? path : "/#{API_VERSION}#{path}"
+  end
+
+  def versioned?(path)
+    path =~ /^\/v\d+\//
+  end
+
+  at_exit do
+    @mqtt_client.disconnect if defined?(@mqtt_client)
+  end
+end

data/lib/m2x/mqtt/device.rb

@@ -0,0 +1,62 @@
+# Wrapper for AT&T M2X Device API
+# https://m2x.att.com/developer/documentation/v2/device
+class M2X::MQTT::Device < M2X::MQTT::Resource
+
+  PATH = "/devices"
+
+  class << self
+    # Create a new device
+    #
+    # https://m2x.att.com/developer/documentation/v2/device#Create-Device
+    def create!(client, params)
+      client.post(PATH, params)
+
+      new(client, params)
+    end
+  end
+
+  def path
+    @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
+  end
+
+  def stream(name)
+    M2X::MQTT::Stream.new(@client, self, "name" => name)
+  end
+
+  # Update the current location of the specified device.
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Update-Device-Location
+  def update_location(params)
+    @client.put("#{path}/location", params)
+  end
+
+  # 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
+  #
+  # https://staging.m2x.sl.attcompute.com/developer/documentation/v2/device#Post-Device-Updates--Multiple-Values-to-Multiple-Streams-
+  def post_updates(params)
+    @client.post("#{path}/updates", params)
+  end
+end

data/lib/m2x/mqtt/distribution.rb

@@ -0,0 +1,20 @@
+# Wrapper for AT&T M2X Distribution API
+# https://m2x.att.com/developer/documentation/v2/distribution
+class M2X::MQTT::Distribution < M2X::MQTT::Resource
+
+  PATH = "/distributions"
+
+  def path
+    @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
+  end
+
+  # Add a new device to an existing distribution
+  #
+  # Accepts a `serial` parameter, that must be a unique identifier
+  # within this distribution.
+  #
+  # https://m2x.att.com/developer/documentation/v2/distribution#Add-Device-to-an-existing-Distribution
+  def add_device(serial)
+    @client.post("#{path}/devices", serial: serial)
+  end
+end

data/lib/m2x/mqtt/resource.rb

@@ -0,0 +1,24 @@
+require "uri"
+require "forwardable"
+
+# Wrapper for M2X::Client resources
+class M2X::MQTT::Resource
+  extend Forwardable
+
+  attr_reader :attributes
+
+  def_delegator :@attributes, :[]
+
+  def initialize(client, attributes)
+    @client     = client
+    @attributes = attributes
+  end
+
+  def inspect
+    "<#{self.class.name}: #{attributes.inspect}>"
+  end
+
+  def path
+    raise NotImplementedError
+  end
+end

data/lib/m2x/mqtt/stream.rb

@@ -0,0 +1,53 @@
+# Wrapper for AT&T M2X Data Streams API
+# https://m2x.att.com/developer/documentation/v2/device
+class M2X::MQTT::Stream < M2X::MQTT::Resource
+
+  def initialize(client, device, attributes)
+    @client     = client
+    @device     = device
+    @attributes = attributes
+  end
+
+  def path
+    @path ||= "#{@device.path}/streams/#{ URI.encode(@attributes.fetch("name")) }"
+  end
+
+  # Update stream properties
+  # (if the stream does not exist it gets created).
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream
+  def update!(params={})
+    @client.put(path, params)
+
+    @attributes.merge!(params)
+  end
+
+  # Update the current value of the stream. The timestamp
+  # is optional. If ommited, the current server time will be used
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Update-Data-Stream-Value
+  def update_value(value, timestamp=nil)
+    params = { value: value }
+
+    params[:at] = timestamp if timestamp
+
+    @client.put("#{path}/value", params)
+  end
+
+  # Post multiple values to the stream
+  #
+  # The `values` parameter is an array with the following format:
+  #
+  #     [
+  #       { "timestamp": <Time in ISO8601>, "value": x },
+  #       { "timestamp": <Time in ISO8601>, "value": y },
+  #       [ ... ]
+  #     ]
+  #
+  # https://m2x.att.com/developer/documentation/v2/device#Post-Data-Stream-Values
+  def post_values(values)
+    params = { values: values }
+
+    @client.post("#{path}/values", params)
+  end
+end

data/lib/m2x/mqtt/version.rb

@@ -0,0 +1,5 @@
+module M2X
+  class MQTT
+    VERSION = "0.0.1"
+  end
+end

data/m2x-mqtt.gemspec

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+require "./lib/m2x/mqtt/version"
+
+Gem::Specification.new do |s|
+  s.name        = "m2x-mqtt"
+  s.version     = ::M2X::MQTT::VERSION
+  s.summary     = "Ruby client for AT&T M2X (MQTT)"
+  s.description = "AT&T’s M2X is a cloud-based fully managed data storage service for network connected machine-to-machine (M2M) devices. From trucks and turbines to vending machines and freight containers, M2X enables the devices that power your business to connect and share valuable data."
+  s.authors     = ["Leandro López", "Matías Flores", "Federico Saravia"]
+  s.email       = ["inkel.ar@gmail.com", "flores.matias@gmail.com", "fedesaravia@gmail.com"]
+  s.homepage    = "http://github.com/attm2x/m2x-ruby-mqtt"
+  s.licenses    = ["MIT"]
+
+  s.files = Dir[
+                "LICENSE",
+                "README.md",
+                "lib/**/*.rb",
+                "*.gemspec"
+               ]
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: m2x-mqtt
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Leandro López
+- Matías Flores
+- Federico Saravia
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-16 00:00:00.000000000 Z
+dependencies: []
+description: AT&T’s M2X is a cloud-based fully managed data storage service for network
+  connected machine-to-machine (M2M) devices. From trucks and turbines to vending
+  machines and freight containers, M2X enables the devices that power your business
+  to connect and share valuable data.
+email:
+- inkel.ar@gmail.com
+- flores.matias@gmail.com
+- fedesaravia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/m2x/mqtt.rb
+- lib/m2x/mqtt/client.rb
+- lib/m2x/mqtt/device.rb
+- lib/m2x/mqtt/distribution.rb
+- lib/m2x/mqtt/resource.rb
+- lib/m2x/mqtt/stream.rb
+- lib/m2x/mqtt/version.rb
+- m2x-mqtt.gemspec
+homepage: http://github.com/attm2x/m2x-ruby-mqtt
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Ruby client for AT&T M2X (MQTT)
+test_files: []
+has_rdoc: