Skip to content

streams.rst

Latest commit

 

History

History
107 lines (80 loc) · 3.33 KB

streams.rst

File metadata and controls

107 lines (80 loc) · 3.33 KB
Raw

Streams API

Streams Overview

Data Streams on the device cloud provide a mechanism for storing time-series values over a long period of time. Each individual value in the time series is known as a Data Point.

There are a few basic operations supported by the device cloud on streams which are supported by the device cloud and this library. Here we give examples of each.

Listing Streams

Although it is not recommended for production applications, it is often useful when building tools to be able to fetch a list of all streams. This can be done by using :meth:`.StreamsAPI.get_streams`:

dc = DeviceCloud('user', 'pass')
for stream in dc.streams.get_streams():
    print "%s: %s" % (stream.get_stream_id(),
                      stream.get_description())

Creating a Stream

Streams can be created in two ways, both of which are supported by this library.

  1. Create a stream explicitly using :meth:`.StreamsAPI.create_stream`
  2. Get a reference to a stream using :meth:`.StreamsAPI.get_stream` that does not yet exist and write a datapoint to it.

Here's examples of these two methods for creating a new stream:

dc = DeviceCloud('user', 'pass')

# explicitly create a new data stream
humidity_stream = dc.streams.create_stream(
    stream_id="mystreams/hudidity",
    data_type="float",
    description="Humidity")
humidity_stream.write(Datapoint(81.2))

# create data stream implicitly
temperature_stream = streams.get_stream("/%s/temperature" % some_id)
temperature_stream.write(Datapoint(
        stream_id="mystreams/temperature" % some_id,
        data=74.1,
        description="Outside Air Temperature in F",
        data_type=STREAM_TYPE_FLOAT,
        unit="Degrees Fahrenheit"
))

Getting Information About A Stream

Whether we know a stream by id and have gotten a reference using :meth:`.StreamsAPI.get_stream` or have discovered it using :meth:`.StreamsAPI.get_streams`, the :class:`.DataStream` should be able to provide access to all metadata about the stream that you may need. Here we show several of them:

strm = dc.streams.get_stream("test")
print strm.get_stream_id()
print strm.get_data_type()
print strm.get_units()
print strm.get_description()
print strm.get_data_ttl()
print strm.get_rollup_ttl()
print strm.get_current_value()  # return DataPoint object

Note

:meth:`.DataStream.get_current_value()` does not use cached values by default and will make a web service call to get the most recent current value unless use_cached is set to True when called.

Deleting a Stream

Deleting a data stream is possible by calling :meth:`.DataStream.delete`:

strm = dc.streams.get_stream("doomed")
strm.delete()

Updating Stream Metadata

This feature is currently not supported. Some stream information may be updated by writing a :class:`.DataPoint` and including updated stream info elements.

DataPoint objects

The :class:`.DataPoint` class encapsulates all information required for both writing data points as well as retrieving information about data points stored on the device cloud.

API Documentation

.. automodule:: devicecloud.streams
   :members: