Cookbook

This page is meant to show complete examples for common uses of the library. For more granular or specific examples of API usage check out the individual API pages.

Note

There are also examples checked into source control under /devicecloud/examples/*_playground.py which will provide additional example uses of the library.

Each example will assume an instance of devicecloud.DeviceCloud has been created with something like so:

dc = DeviceCloud(<username>, <password>)

Streams - Creating Streams and Data Points

For this example, let’s create a DataStream that represents a class room. As students enter the classroom there is a DataPoint representing them written to the stream.

First let’s get or create the stream:

classroom = dc.streams.get_stream_if_exists('classroom')
if not classroom:
    classroom = dc.streams.create_stream(
        stream_id='classroom',
        data_type=STREAM_TYPE_STRING,
        description='Stream representing a classroom of students',
    )

A student named Bob enters the classroom so we write a DataPoint representing Bob to the stream. To represent Bob let’s use a JSON object:

student = {
    'name': 'Bob',
    'student_id': 12,
    'age': 21,
}
datapoint = DataPoint(data=json.dumps(student))
classroom.write(datapoint)

Now, two students enter at the same time. For this we can write both data points as a batch which only uses one HTTP request (up to 250 data points):

students = [
    {
        'name': 'James',
        'student_id': 13,
        'age': 22,
    },
    {
        'name': 'Henry',
        'student_id': 14,
        'age': 20,
    }
]
datapoints = [DataPoint(data=json.dumps(x)) for x in students]
classroom.bulk_write_datapoints(datapoints)

Finally, let’s print the name of the student who most recently entered the classroom:

most_recent_student = classroom.get_current_value()
print json.loads(most_recent_student.get_data())['name']  # Prints 'Henry'

Streams - Deleting

Let’s delete the classroom stream from the above example so we can start fresh in the next example:

classroom.delete()

Streams - Roll-up Data

Roll-up data is a way to group data points based on time intervals in which they were written to the cloud. From our previous example lets figure out which students entered the classroom throughout the day and which hour they entered.

First let’s write some test data to the cloud. Since roll-ups only work on numerical data types we will student id’s instead of JSON.

Create a new data stream that is of type int:

classroom = dc.streams.create_stream(
        stream_id='classroom',
        data_type=STREAM_TYPE_INTEGER,
        description='Stream representing a classroom of students (as id's)',
    )

Next is a function that fills the classroom with data points that have randomly generated timestamp values within the next 24 hours:

now = time.time()
one_day_in_seconds = 86400

datapoints = list()
for student_id in xrange(100):
    deviation = random.randint(0, one_day_in_seconds)
    random_time = now + deviation
    datapoint = DataPoint(data=student_id,
                          timestamp=datetime.datetime.fromtimestamp(random_time))
    datapoints.append(datapoint)

classroom.bulk_write_datapoints(datapoints)

Finally, let’s figure out which students entered the classroom which hours of the day:

rollup_data = classroom.read(rollup_interval='hour', rollup_method='count')
hourly_data = {}
for dp in rollup_data:
    hourly_data[dp.get_timestamp().hour] = dp.get_data()
pprint.pprint(hourly_data)

The result is a dictionary where the key’s are the hour in the day and the values are the number of students who entered the classroom that hour:

{0: 10,
 1: 10,
 2: 9,
 3: 3,
 4: 3,
 5: 6,
 6: 9,
 7: 11,
 8: 5,
 9: 7,
 10: 9,
 11: 9,
 12: 7,
 13: 6,
 14: 13,
 15: 8,
 16: 13,
 17: 9,
 18: 7,
 19: 7,
 20: 11,
 21: 8,
 22: 6,
 23: 11}

Device Core - Groups

Note

This assumes your device is provisioned.

First, get a reference to the device which you would like to add a specific group:

device = devicecore.get_device('00:40:9D:50:B0:EA')

Then you can add it to a group and fetch it to make sure it works:

device.add_to_group('mygroup')
device.get_group_path()  # prints 'mygroup' (DC sometimes needs a second to catch up)

Or remove it:

device.remove_from_group()

Device Core - Tags

Note

This assumes your device is provisioned.

Similar to Groups, get a reference to the device which you would like to add a specific group:

device = devicecore.get_device('00:40:9D:50:B0:EA')

Then you can add a tag and then get the new list:

device.add_tags('mytag')
device.get_tags()  # prints ['mytags'] (DC sometimes needs a second to catch up)

Or remove it:

device.remove_tag('mytag')
device.get_tags()  # prints [] (DC sometimes needs a second to catch up)