AT&T M2X Ruby Library

Introduction

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.

This gem aims to provide a simple wrapper to interact with AT&T M2X API.

Refer to the Glossary of Terms to understand the nomenclature used through this documentation.

Getting Started

  1. 1 Signup for an M2X Account.
  2. 2 Obtain your Master Key from the Master Keys tab of your Account Settings screen.
  3. 3 Create your first Device and copy its Device ID.
  4. 4 Review the M2X API Documentation.

Example Usage

In order to be able to use this gem you will need an AT&T M2X API key and a Device ID. If you don't have an API key, create an account and, once registered and with your account activated, create a new Device, 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:


#! /usr/bin/env ruby

#
# See https://github.com/attm2x/m2x-ruby/blob/master/README.md#example-usage
# for instructions
#

require "time"
require "m2x"

API_KEY = ENV.fetch("API_KEY")
DEVICE  = ENV.fetch("DEVICE")

puts "M2X::Client/#{M2X::Client::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::Client.new(API_KEY)

# Get the device
device = m2x.device(DEVICE)

# Create the streams if they don't exist
device.create_stream("load_1m")
device.create_stream("load_5m")
device.create_stream("load_15m")

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)

  abort res.json["message"] unless res.success?

  sleep 1
end

puts

You can find the script in examples/m2x-uptime.rb.

Versioning

This gem aims to adhere to Semantic Versioning 2.0.0. As a summary, given a version number MAJOR.MINOR.PATCH:

  1. 1 MAJOR will increment when backwards-incompatible changes are introduced to the client.
  2. 2 MINOR will increment when backwards-compatible functionality is added.
  3. 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.