Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
CONTRIBUTING.md Add link to generic contribution guidelines May 12, 2016
LICENSE
README.md
pom.xml

README.md

AT&T's M2X Java 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 Java. 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 M2X Account Settings.
  3. Review the M2X API Documentation

Setup

Via Maven Central Repository (Recommended)

We've added the M2X Java Client Library to the Maven Central Repository to make it easy for you to add it as a dependency to your Java based project.

To include the M2X Java Client Library in your project, add the following to your project's pom.xml :

    <dependencies>
        <dependency>
            <groupId>com.att.m2x</groupId>
            <artifactId>java</artifactId>
            <version>5.0.0</version>
        </dependency>
    </dependencies>

Manual Installation

  1. Obtain the com.att.m2x.java-v.v.v-one-jar.jar for the latest version of the M2X Java Client Library. Note: you must use the one-jar jar file, as this includes all M2X Java Client Library dependancies
  2. Add the com.att.m2x.java-v.v.v-one-jar.jar as a dependency for your project via your IDE of choice

Requirements and Dependencies

The M2X Java client requires Java version 1.5 or greater.

The client has the following library dependencies, though if you followed the Setup instructions from above all dependencies will be included automatically:

Example

Currently, the client supports API v2 and all M2X API documents can be found at M2X API Documentation.

To create a client instance only one parameter, the API Key, is required. Read more about M2X API keys in the API Keys section of M2X API Documentation. To create a client instance, do the following:

	import com.att.m2x.java.M2XClient;

	M2XClient client = new M2XClient("your api key here");

There is another method that has endpoint parameter. You don't need to pass it unless you want to connect to a different API endpoint.

The client class provides access to API calls returning lists of the following API objects: devices, distributions, keys, charts.

All API responses are wrapped in M2XResponse object.

  • Get the list of all your keys:
	M2XResponse keys = client.keys(null);

There are also a number of methods allowing you to get an instance of individual API object by providing its id or name as a parameter.

  • Get an instance of a device:
	M2XDevice device = client.device("your device id here");

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

  • Create a new device, stream and put current value into it:
 	M2XResponse response = client.createDevice(M2XClient.jsonSerialize(new HashMap<String, Object>()
	{{
		put("name", "My Device");
		put("visibility", "private");
	}}));
	String deviceId = response.json().getString("id");
	M2XDevice device = client.device(deviceId);

	M2XStream stream = device.stream("mystream");
	stream.createOrUpdate("{\"type\":\"numeric\",\"unit\":{\"label\":\"points\",\"symbol\":\"pt\"}}");

	stream.updateValue(M2XClient.jsonSerialize(new HashMap<String, Object>()
	{{
		put("value", 10);
	}}));

You can find this code in M2XClientTest.java. These tests have a lot of examples for the most of M2X API methods. To run the tests you should specify your Master API Key in the m2x.test.keys.xml resource file.

Versioning

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

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