AT&T's M2X Node.js Client

AT&T M2X is a cloud-based fully managed time-series data storage service for network connected machine-to-machine (M2M) devices and the Internet of Things (IoT).

The AT&T M2X API provides all the needed operations and methods to connect your devices to AT&T's M2X service. This library aims to provide a simple wrapper to interact with the AT&T M2X API for Node.js. Refer to the Glossary of Terms to understand the nomenclature used throughout this documentation.

Getting Started

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

Installation

m2x-nodejs is available as an npm package (https://www.npmjs.com/package/m2x). Install the latest version with:

npm install m2x

Usage

M2X Class

The main object encapsulating all API functionality is the global variable M2X. In order to create a M2X object you will need an API key, which can be either a Master Key or a key belonging to a specific device (in which case you will only be allowed to read/write to this device).

The following is a short example on how to instantiate an M2X object:

var M2X = require("m2x");

var m2x = new M2X("<API-KEY>");

The M2X object also provides a simple method for checking the API status (so if you are having connectivity issues, you can check whether the API is currently down):

m2x.status(function(status) {
    console.log(status);
});

An M2X object provides methods for communicating with the remote API. Methods are organized under the following modules: collection, commands, devices, distributions, jobs and keys.

• Collections

  m2x.collections.view("<DISTRIBUTION-ID>", function(response) {
      console.log(response.json);
  });
  
  m2x.collections.list(function(response) {
      console.log(response.json);
  });

• Commands

  m2x.commands.view("<DISTRIBUTION-ID>", function(response) {
      console.log(response.json);
  });
  
  m2x.commands.list(function(response) {
      console.log(response.json);
  });

• Devices

  m2x.devices.view("<DEVICE-ID>", function(response) {
      console.log(response.json);
  });
  
  m2x.devices.list(function(response) {
      console.log(response.json);
  });

• Distributions

  m2x.distributions.view("<DISTRIBUTION-ID>", function(response) {
      console.log(response.json);
  });
  
  m2x.distributions.list(function(response) {
      console.log(response.json);
  });

• Jobs

  m2x.jobs.view("<JOB-ID>", function(response) {
      console.log(response.json);
  });

• Keys

  m2x.keys.view("<KEY-TOKEN>", function(response) {
      console.log(response.json);
  });
  
  m2x.keys.list(function(response) {
      console.log(response.json);
  });

Time

For devices that do not have a Real Time Clock, M2X provides a set of endpoints that returns the server's time.

m2x.time(function(response) {
  console.log(response.json);
});

m2x.timeSeconds(function(response) {
  console.log(response.raw);
});

m2x.timeMillis(function(response) {
  console.log(response.raw);
});

m2x.timeIso8601(function(response) {
  console.log(response.raw);
});

Refer to the documentation on each class for further usage instructions.

Examples

//
// This is a simple application that requests the list
// of available devices for the provided API Key and then
// prints the details for each of those devices
//

var API_KEY = "<YOUR KEY>",
    M2X = require("m2x"),
    m2xClient = new M2X(API_KEY);

m2xClient.devices.list(function(response) {
    if (response.isSuccess()) {
        response.json.devices.forEach(function(device) {
            console.log(device);
        });
    } else {
        console.log(JSON.stringify(response.error()));
    }
});

Example usage

You can find additional examples in the examples directory. Instructions for each example can be found within the comments of the example file.

All examples require the m2x-nodejs library.

If you will be running the examples from within the examples directory, you will need to install the library dependencies within the root directory of the m2x-nodejs folder:

npm install

Or, if you move the example file(s) out of the examples directory you will need to modify the m2x-nodejs require line and install the m2x-nodejs library in the root directory where the example file is stored:

Change require line as follows:

var M2X = require("m2x");

Install m2x-nodejs package using npm in the root directory where you have stored the examples:

npm install m2x

Once you've selected an example to run, open the file and add your user specific information such as your API Key, Device ID, etc., and then run the example with the following command:

node example_filename.js

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. 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 library is provided under the MIT license. See LICENSE for applicable terms.

Acknowledgements

This client is a direct port of Leandro Lopez' AT&T M2X client for Ruby so all the credit should go to him.