The AT&T M2X API provides all the needed operations to connect your devices to AT&T's M2X service. This client provides an easy to use interface for your favorite mobile platform, iOS.
- Signup for an M2X Account: https://m2x.att.com/signup
- Obtain your Master Key from the Master Keys tab of your Account Settings: https://m2x.att.com/account
- Create your first Data Source Blueprint and copy its Feed ID: https://m2x.att.com/blueprints
- Review the M2X API Documentation: https://m2x.att.com/developer/documentation/overview
If you have questions about any M2X specific terms, please consult the M2X glossary: https://m2x.att.com/developer/documentation/glossary
##Installation
Copy the content from the lib folder to your project.
Note: The lib folder contains the AFNetworking library to make HTTP requests.
The M2X iOS Client was developed in iOS SDK 7.0.
The client has the following library dependency:
- AFNetworking, 2.0, https://github.com/AFNetworking/AFNetworking
Currently, the client supports M2X API v1. All M2X API specifications can be found in the M2X API Documentation.
M2X is the main class that provides the methods to set the API URL ("http://api-m2x.att.com/v1" as default) and the Master Key.
Example:
//get singleton instance of M2x Class
M2x* m2x = [M2x shared];
//set the Master Api Key
m2x.api_key = @"your_api_key";The method -iSO8601ToDate: parse from a ISO8601 Date NSString to NSDate:
-(NSDate*)iSO8601ToDate:(NSString*)dateString;-dateToISO8601: parse from NSDate to a ISO8601 Date NSString:
-(NSString*)dateToISO8601:(NSDate*)date;The clients (FeedsClient, DataSourceClient and KeysClient) provide an interface to make all the requests on the respectives API.
If the call requires parameters, it must be encapsulated in a NSDictionary following the respective estructure from the API Documentation.
As well as the parameters, the response is returned in a NSDictionary object.
If required, a Feed API key can be set in these classes.
FeedsClient *feedClient = [[FeedsClient alloc] init];
[feedClient setFeed_key:@"YOUR_FEED_API_KEY"];List Feeds in a NSMutableArray:
// Note that for this call you need your Master API Key,
// otherwise you'll get a 401 Unauthorized error.
[feedClient setFeed_key:@"YOUR_MASTER_API_KEY"];
//retrieve a list of feeds without parameters
[feedClient listWithParameters:nil success:^(id object) {
NSDictionary *response = [value objectForKey:@"feeds"];
feedList = [NSMutableArray array];
for (NSDictionary *feed in response) {
//show only active feeds
if([[feed valueForKey:@"status"] isEqualToString:@"enabled"])
[feedList addObject:feed];
}
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error description]);
NSLog(@"Message: %@",message);
}];Update the current location:
//init locationManager
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
locationManager.distanceFilter = kCLDistanceFilterNone;
locationManager.desiredAccuracy = kCLLocationAccuracyBest;
[locationManager startUpdatingLocation];
//...//
//Set the current location
CLLocation *location = [locationManager location];
NSDictionary *locationDict = @{ @"name": _currentLocality,
@"latitude": [NSString stringWithFormat:@"%f",location.coordinate.latitude],
@"longitude": [NSString stringWithFormat:@"%f",location.coordinate.longitude],
@"elevation": [NSString stringWithFormat:@"%f",location.altitude] };
[feedClient updateDatasourceWithLocation:locationDict inFeed:@"your_feed_id" success:^(id object) {
//Callback function
[self didSetLocation];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Post Data Stream Values:
NSDictionary *newValue = @{ @"values": @[ @{ @"value": @"20" } ] };
[feedClient postDataValues:newValue
forStream:@"stream_name"
inFeed:@"your_feed_id"
success:^(id object) { /*success block*/ }
failure:^(NSError *error, NSDictionary *message)
{
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Create a Trigger
NSDictionary *trigger = @{ @"name": @"trigger1",
@"stream": @"temperature",
@"condition": @">",
@"value": @"30",
@"callback_url": @"http://example.com",
@"status": @"enabled" };
[feedClient createTrigger:trigger inFeed:@"ee9501931bcb3f9b0d25fde5eaf4abd8" success:^(id object) {
/*success block*/
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];View Request Log
[feedClient viewRequestLogForFeed:@"YOUR_FEED_ID" success:^(id object) {
NSArray *requests = [object objectForKey:@"requests"];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];DataSourceClient dataSourceClient = [[DataSourceClient alloc] init];
[dataSourceClient setFeed_key:@"YOUR_FEED_API_KEY"];Create Blueprint:
NSDictionary *blueprint = @{ @"name": @"Sample Blueprint",
@"description": @"Longer description for Sample Blueprint",
@"visibility": @"public" };
[dataSourceClient createBlueprint:bp success:^(id object) {
/*blueprint created*/
NSDictionary *blueprintCreated = object;
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"%@",message);
NSLog(@"%@",error);
}];List Data Sources from a Batch:
[dataSourceClient listDataSourcesfromBatch:@"batch_id" success:^(id object) {
[dataSources removeAllObjects];
[dataSources addObjectsFromArray:[dataSourcesList objectForKey:@"datasources"]];
[tableViewDataSources reloadData];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Add Data Source to an existing Batch:
NSDictionary *serial = @{ @"serial": @"your_new_serial" };
//Add Data Source to the Batch
[dataSourceClient addDataSourceToBatch:@"batch_id" withParameters:serial success:^(id object) {
//data source successfully added.
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Create Batch:
NSDictionary *batch = @{ @"name": @"your_batch_name" ,
@"description": @"a_description",
@"visibility": @"private" };
[dataSourceClient createBatch:batch success:^(id object) {
//batch successfully created.
NSDictionary *batchCreated = object;
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];View Data Source Details:
[dataSourceClient viewDetailsForDataSourceId:@"datasource_id" success:^(id object) {
//set label with data source info.
[lblDSName setText:[object valueForKey:@"name"]];
[lblDSDescription setText:[object valueForKey:@"name"]];
[lblDSSerial setText:[object valueForKey:@"serial"]];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Create Data Source:
NSDictionary *datasource = @{ @"name": @"Sample Data Source",
@"description": @"Longer description for Sample Data Source",
@"visibility": @"public" };
[dataSourceClient createDataSource:datasource success:^(id object) {
/*Data Source created*/
NSDictionary *dataSourceCreated = object;
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];KeysClient keyClient = [[KeysClient alloc] init];
[keyClient setFeed_key:@"YOUR_FEED_API_KEY"];List Keys:
[keysClient listKeysWithParameters:nil success:^(id object) {
[keysArray removeAllObjects];
[keysArray addObjectsFromArray:[object objectForKey:@"keys"]];
[self.tableView reloadData];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];View Key Details:
[keysClient viewDetailsForKey:_key success:^(id object) {
NSString *name = [object valueForKey:@"name"];
NSString *key = [object valueForKey:@"key"];
NSString *expiresAt = [object valueForKey:@"expires_at"];
NSString *permissions = [[object objectForKey:@"permissions"] componentsJoinedByString:@", "];
[lblName setText:name];
[lblKey setText:key];
[lblPermissions setText:permissions];
//check if expires_at isn't set.
if(![expiresAt isEqual:[NSNull null]]){
[lblExpiresAt setText:expiresAt];
}
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];Regenerate Key:
[keysClient regenerateKey:_key success:^(id object) {
//Update key label
[lblKey setText:[object valueForKey:@"key"]];
} failure:^(NSError *error, NSDictionary *message) {
NSLog(@"Error: %@",[error localizedDescription]);
NSLog(@"Message: %@",message);
}];The errors and messages are handled in the failure block. The error parameter is a NSError object that encapsulate the error information, for example the HTTP status code. And the message parameter is a NSDictionary and contains the response message from the API.
To get the HTTP status code from error use the method - localizedDescription.
This repository comes with a simple app that implements some of the API methods. It can be found in the following folder: M2X_iOS.
The iOS M2X API Client is available under the MIT license. See the LICENSE file for more information.