Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
140 lines (93 sloc) 4.03 KB

AT&T's M2X MQTT Python Client

Documentation Status

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 access the MQTT API implementation with the AT&T's M2X service, while supporting Python 2 and 3.

Dependencies

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-mqtt

or:

$ easy_install m2x-mqtt

or cloning the repository:

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

Usage

In order to communicate with the M2X API, you need an instance of M2XClient. You need to pass your API key in the constructor to access your data.

from m2x_mqtt.client import M2XClient

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

This client an interface to your data in M2X

  • Distributions

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

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

Example

Here's an example of a simple application that will load the current time to a stream every 10 seconds:

import os
import time

from m2x_mqtt.client import M2XClient


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

# Create a device
device = client.create_device(
    name='Current Time Example',
    description='Store current time every 10 seconds',
    visibility='public'
)

# Create a data stream
stream = device.create_stream('current_time')

# And now register the current time every 10 seconds (hit ctrl-c to kill)
while True:
    stream.add_value(int(time.time()))
    time.sleep(10)

To run this example you need a API Key and execute it like this:

$ API_KEY=<API-KEY-TOKEN> python ./example.py

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.