AT&T M2X Python Client Library

Python toolkit for the AT&T M2X API.

View the M2X Python Client README for usage details.

All methods in this client library require an API Key for authentication. There are multiple types of API Keys which provide granular access to your M2X resources. Please review the API Keys documentation for more details on the different types of keys available.

If an invalid API Key is utilized, you will receive the following error when calling client methods:

>>> client.method(...)
Traceback (most recent call last):
        ...
requests.exceptions.HTTPError: 401 Client Error: Unauthorized

API Module

class V2Mixin[source]

Bases: object

Wrapper for AT&T M2X API

collection(id)[source]

Method for View Collection Details endpoint.

Parameters:id (str) – ID of the Collection to retrieve
Returns:The matching Collection
Return type:Collection
Raises:HTTPError if an error occurs when sending the HTTP request
collections(**params)[source]

List Collections

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Collection objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
command(id)[source]

Method for View Command Details endpoint.

Parameters:id (str) – ID of the Command to retrieve
Returns:The matching Command
Return type:Command
Raises:HTTPError if an error occurs when sending the HTTP request
commands(**params)[source]

Method for List Sent Commands endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Command objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
create_collection(**params)[source]

Method for Create Collection endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created Collection
Return type:Collection
Raises:HTTPError if an error occurs when sending the HTTP request
create_device(**params)[source]

Method for Create Device endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created Device
Return type:Device
Raises:HTTPError if an error occurs when sending the HTTP request
create_distribution(**params)[source]

Method for Create Distribution endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created Distribution
Return type:Distribution
Raises:HTTPError if an error occurs when sending the HTTP request
create_key(**params)[source]

Method for Create Key endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created Key
Return type:Key
Raises:HTTPError if an error occurs when sending the HTTP request
device(id)[source]

Method for View Device Details endpoint.

Parameters:id (str) – ID of the Device to retrieve
Returns:The matching Device
Return type:Device
Raises:HTTPError if an error occurs when sending the HTTP request
device_catalog(**params)[source]

Method for List Public Devices Catalog endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Device objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
device_tags(**params)[source]

Method for List Device Tags endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:Device tags associated with your account
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
devices(**params)[source]

Method for List Devices endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Device objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request

Method for Search Devices endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Device objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
distribution(id)[source]

Method for View Distribution Details endpoint.

Parameters:id (str) – ID of the Distribution to retrieve
Returns:The matching Distribution
Return type:Distribution
Raises:HTTPError if an error occurs when sending the HTTP request
distributions(**params)[source]

Method for List Distributions endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Distribution objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
job(id)[source]

Method for View Job Details endpoint.

Parameters:id (str) – ID of the Job to retrieve
Returns:The matching Job
Return type:Job
Raises:HTTPError if an error occurs when sending the HTTP request
key(key)[source]

Method for View Key Details endpoint.

Parameters:id (str) – ID of the Key to retrieve
Returns:The matching Key
Return type:Key
Raises:HTTPError if an error occurs when sending the HTTP request
keys(**params)[source]

Method for List Keys endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Key objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
send_command(**params)[source]

Method for Send Command endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The Command that was just sent
Return type:Command
Raises:HTTPError if an error occurs when sending the HTTP request
status()[source]

Returns current status of AT&T M2X API

Returns:Current status of AT&T M2X API
Return type:dict
time()[source]

Method for the /time endpoint.

Returns:The M2X server’s current time in seconds, milliseconds and ISO8601 format
Return type:dict
time_iso8601()[source]

Method for the /time/iso8601 endpoint.

Returns:The M2X server’s current time in ISO8601 format
Return type:str
time_millis()[source]

Method for the /time/millis endpoint.

Returns:The M2X server’s current time in milliseconds
Return type:int
time_seconds()[source]

Method for the /time/seconds endpoint.

Returns:The M2X server’s current time in seconds
Return type:int

Collections Module

class Collection(api, **data)[source]

Bases: m2x.v2.resource.Resource, m2x.v2.metadata.Metadata

Wrapper for AT&T M2X Collections API

add_device(device_id)[source]

Method for Add device to collection endpoint.

Parameters:device_id (str) – ID of the Device being added to Collection
Raises:HTTPError if an error occurs when sending the HTTP request
devices(**params)[source]

Method for List Devices from an existing Collection endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Device objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
remove_device(device_id)[source]

Method for Remove device from collection endpoint.

Parameters:device_id (str) – ID of the Device being removed from Collection
Raises:HTTPError if an error occurs when sending the HTTP request

Devices Module

class Device(api, **data)[source]

Bases: m2x.v2.resource.Resource, m2x.v2.metadata.Metadata

Wrapper for AT&T M2X Device API

command(id)[source]

Method for Device’s View of Command Details endpoint.

Parameters:id – ID of the Command to retrieve
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
commands(**params)[source]

Method for Device’s List of Received Commands endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
create_key(**params)[source]

Create an API Key for this Device via the Create Key endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created Key
Return type:Key
Raises:HTTPError if an error occurs when sending the HTTP request
create_stream(name, **params)[source]

Method for Create/Update Data Stream endpoint.

Parameters:
  • name – Name of the stream to be created
  • params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:

The newly created Stream
Return type:

Stream
Raises:

HTTPError if an error occurs when sending the HTTP request
delete_location_history(**values)[source]

Method for Delete Device Location History endpoint.

Parameters:values – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
keys()[source]
Lists Keys associated with this device via the
List Keys endpoint.
Returns:List of API keys associated with this device as Key objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
location()[source]

Method for Read Device Location endpoint.

Returns:Most recently logged location of the Device, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
location_history(**params)[source]

Method for Read Device Location History endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:Location history of the Device
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
log()[source]

Method for View Request Log endpoint.

Returns:Most recent API requests made against this Device
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
post_update(**values)[source]

Method for Post Device Update (Single Values to Multiple Streams) <https://m2x.att.com/developer/documentation/v2/device#Post-Device-Update–Single-Values-to-Multiple-Streams-> endpoint.

Parameters:values (dict) – The values being posted, formatted according to the API docs
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
post_updates(**values)[source]

Method for Post Device Updates (Multiple Values to Multiple Streams) endpoint.

Parameters:values (dict) – The values being posted, formatted according to the API docs
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
process_command(id, **params)[source]

Method for Device Marks a Command as Processed endpoint.

Parameters:
  • id – ID of the Command being marked as processed
  • params – Optional data to be associated with the processed command, see API docs for details
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
reject_command(id, **params)[source]

Method for Device Marks a Command as Rejected endpoint.

Parameters:
  • id – ID of the Command being marked as rejected
  • params – Optional data to be associated with the rejected command, see API docs for details
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
stream(name)[source]

Method for View Data Stream endpoint.

Parameters:name – The name of the Stream being retrieved
Returns:The matching Stream
Return type:Stream
Raises:HTTPError if an error occurs when sending the HTTP request
streams()[source]

Method for List Data Streams endpoint.

Returns:List of data streams associated with this device as Stream objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request
update_location(**params)[source]

Method for Update Device Location endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
update_stream(name, **params)[source]

Method for Create/Update Data Stream endpoint.

Parameters:
  • name – Name of the stream to be updated
  • params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:

The Stream being updated
Return type:

Stream
Raises:

HTTPError if an error occurs when sending the HTTP request
values(**params)[source]

Method for List Data Stream Values endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
values_export(**params)[source]

Method for Export Values from all Data Streams of a Device endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request

Method for Search Values from all Data Streams of a Device endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request

Distributions Module

class Distribution(api, **data)[source]

Bases: m2x.v2.resource.Resource, m2x.v2.metadata.Metadata

Wrapper for AT&T M2X Distribution API

add_device(params)[source]

Method for Add Device to an Existing Distribution endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The newly created DistributionDevice
Return type:DistributionDevice
Raises:HTTPError if an error occurs when sending the HTTP request
devices(**params)[source]

Method for List Devices from an existing Distribution endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:List of Devices associated with this Distribution as DistributionDevice objects
Return type:list
Raises:HTTPError if an error occurs when sending the HTTP request

Keys Module

class Key(api, **data)[source]

Bases: m2x.v2.resource.Resource

Wrapper for AT&T M2X Keys API

regenerate()[source]

Method for Regenerate Key endpoint.

Raises:HTTPError if an error occurs when sending the HTTP request

Metadata Module

class Metadata(api, **data)[source]

Bases: object

Generic methods for interacting with an M2X resource’s Metadata

read_metadata()[source]

Generic method for a resource’s Read Metadata endpoint.

Example endpoints:

Returns:All of the user defined metadata associated with the resource
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
read_metadata_field(field)[source]

Generic method for a resource’s Read Metadata Field endpoint.

Example endpoints:

Returns:The value for the given metadata field of the resource
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
update_metadata(params)[source]

Generic method for a resource’s Update Metadata endpoint.

Example endpoints:

Parameters:params – The metadata being updated
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
update_metadata_field(field, value)[source]

Generic method for a resource’s Update Metadata Field endpoint.

Example endpoints:

Parameters:
  • field – The metadata field to be updated
  • value – The value to update
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request

Resource Module

class Resource(api, **data)[source]

Bases: object

Generic methods for interacting with an M2X resource

remove()[source]

Generic method for a resource’s Delete endpoint.

Example endpoints:

Parameters:attrs – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
update(**attrs)[source]

Generic method for a resource’s Update endpoint.

Example endpoints:

Parameters:attrs – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request

Streams Module

class Stream(api, device, **data)[source]

Bases: m2x.v2.resource.Resource

Methods for interacting AT&T M2X Device Streams

add_value(value, timestamp=None)[source]

Method for Update Data Stream Value endpoint.

Parameters:
  • value – The updated stream value
  • timestamp – The (optional) timestamp for the upadted value
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
delete_values(start, stop)[source]

Method for Delete Data Stream Values endpoint.

Parameters:
  • start – ISO8601 timestamp for starting timerange for values to be deleted
  • stop – ISO8601 timestamp for ending timerange for values to be deleted
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
post_values(values)[source]

Method for Post Data Stream Values endpoint.

Parameters:values (dict) – Values to post, see M2X API docs for details
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
remove()[source]

Method for Delete Data Stream endpoint.

Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
sampling(interval, **params)[source]

Method for Data Stream Sampling endpoint.

Parameters:
  • interval – the sampling interval, see API docs for supported interval types
  • params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
stats(**attrs)[source]

Method for Data Stream Stats endpoint.

Parameters:attrs – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request
update(**attrs)[source]

Method for Update Data Stream endpoint.

Parameters:attrs – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The Stream being updated
Return type:Stream
Raises:HTTPError if an error occurs when sending the HTTP request
update_value(value, timestamp=None)

Method for Update Data Stream Value endpoint.

Parameters:
  • value – The updated stream value
  • timestamp – The (optional) timestamp for the upadted value
Returns:

The API response, see M2X API docs for details
Return type:

dict
Raises:

HTTPError if an error occurs when sending the HTTP request
values(**params)[source]

Method for List Data Stream Values endpoint.

Parameters:params – Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
Returns:The API response, see M2X API docs for details
Return type:dict
Raises:HTTPError if an error occurs when sending the HTTP request