AT&T's M2X Python 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 Python. Refer to the Glossary of Terms to understand the nomenclature used throughout this documentation.

Documentation for the AT&T M2X Python Client Library can be found here, though you should also read this README thoroughly before getting started.

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.

Description

This library provides an interface to navigate and register your data source values with the AT&T's M2X service, while supporting Python 2 and 3.

Dependencies

• requests
• iso8601

To use Python on your local machine, you'll need to first install Python-setuptools.

Installation

The project is very easy to install — the different options are:

$ pip install m2x

or:

$ easy_install m2x

or cloning the repository:

$ git clone https://github.com/attm2x/m2x-python.git
$ cd m2x-python
$ python setup.py install

Note: If you are installing from behind a proxy, setup.py may have trouble connecting to the PyPI server to download dependencies. In this case, you'll need to set the following environment variables to let the setup script know how to navigate your proxy:

HTTP_PROXY=http://proxyserver:port/
HTTPS_PROXY=https://proxyserver:ssl_port/

Usage

In order to communicate with the M2X API, you need an instance of M2XClient. You need to pass your Master API key in the constructor to access your data. Your Master API Key can be found in your account settings.

from m2x.client import M2XClient

client = M2XClient(key='<API-KEY>')

This client an interface to your data in M2X

• Distributions

  distribution = client.distribution('<DISTRIBUTION-ID>')
  distributions = client.distributions()
  

• Devices

  device = client.device('<DEVICE-ID>')
  devices = client.devices()
  

• Jobs

  job = client.job('<JOB-ID>')
  

• Key

  key = client.key('<KEY-TOKEN>')
  keys = client.keys()
  

Examples

Scripts demonstrating usage of the M2X Python Client Library can be found in the examples directory. Each example leverages system environment variables to inject user specific information such as the M2X API Key or Device ID. Review the example you would like to try first to determine which environment variables are required (hint: search for os.environ in the example). Then make sure to set the required environment variable(s) when running the script.

For example, in order to run the post_value script, you will need an API Key. After adding your API Key to the post_value.py file, navigate to the /examples directory and run the following command to execute the script:

$ API_KEY=<YOUR-API-KEY> python ./post_value.py

Getting HTTP Response

You can retrieve the last response received by the client using the last_response property of the client object:

import os
from m2x.client import M2XClient

# Instantiate a client
client = M2XClient(key=os.environ['API_KEY'])

# Make a request to the M2X API
client.devices()

# Get raw HTTP response
raw = client.last_response.raw

# Get HTTP respose status code (e.g. `200`)
status = client.last_response.status

# Get HTTP response headers
headers = client.last_response.headers

# Get json data returned in HTTP response
json = client.last_response.json

In the case of an HTTP error response (like a 400 or 500 error), the library will drop an HTTPError exception (inherited from python-requests). You can still retrieve the original respone by catching this exception:

import os

from requests.exceptions import HTTPError


from m2x.client import M2XClient

# Instantiate a client
client = M2XClient(key=os.environ['API_KEY'])

# Make a request to the M2X API
try:
    client.devices()
except HTTPError as error:
    # Get raw HTTP response
    raw = client.last_response.raw

    # Or get it from the error instance
    # raw = error.response

    # Get HTTP respose status code (e.g. `200`)
    status = client.last_response.status

    # Get HTTP response headers
    headers = client.last_response.headers

    # Get json data returned in HTTP response (might be None)
    json = client.last_response.json

Versioning

This lib 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 released under the MIT license. See LICENSE for the terms.