Simple HTTP example¶

You can use this driver as the parent class of a more specialized driver; for instance one which extracts fields from a CSV file. As an example, suppose we have a source which periodically publishes a file to a web server with a single temperature in it:

$ curl http://example.com/data.txt
10.46

To expose this as a sMAP source, we could write the following simple driver:

from smap.driver import FetchDriver

class SimpleDriver(FetchDriver):
    def setup(self, opts):
        FetchDriver.setup(self, opts)
        self.add_timeseries('/data', 'C')

    def process(self, data):
        self.add('/data', float(data))

By implementing the process method, we put our source-specific processing logic in one place; however, the actually logic for downloading the page is elsewhere.

Configuring your driver¶

In addition to whatever configuration options your driver may take, FetchDriver takes two options: Uri and Rate. The driver attempts to load data from the specified URI every rate seconds.

The driver currently understands three URI schemes:

Running the example¶

In this case, we want to use HTTP without a username or password, so we can just create a simple configuration file:

[/]
uuid = 6fa21782-27b2-11e2-9a49-370ecdac5e02

[/example]
type = example.SimpleDriver
Uri = http://example.com/data.txt
Rate = 30

More Complicated XML Example¶

If what you have is an XML document, you might want to use XSLT to pull out the readings. smap.drivers.xslt.XMLDriver provides the ability to do this. As an example, consider the data produced by an Obvius Aquisuite device; see an example data file. You can transform this file into sMAP-XML using a simple XSLT transform and generate a driver using this config file:

[/]
uuid = 6fa21782-27b2-11e2-9a49-370ecdac5e02

[/obvius]
type = smap.drivers.xslt.XMLDriver
Uri = http://un:pw@aquisuite.example.com/setup/devicexml.cgi?ADDRESS=24&TYPE=DATA
Xslt = xslt/obvius.xsl
Timeformat = %Y-%m-%d %H:%M:%S

This driver periodically loads the obvius document over http, converts it using the XSLT stylesheet, and then adds the data. Timeformat is a python strptime time string used to parse the timestamps found in the transformed xml.

Simple Example Actuator¶

Implementing an actuator is slightly more involved than a simple timeseries. The first step is to implement a class which provides the actual communication with the underlying device. The class of the actuator determines what kind of inputs can be made – is it a switch, with only two states? or perhaps it allows any floating-point value within a range as in a setpoint control.

This is a simple actuator from smap.drivers.file which allows you to “actuate” using an underlying file on the filesystem:

class FileActuator(actuate.BinaryActuator):
    """Example Binary Acutator which implements actuation by writing
    to a file
    """

    def setup(self, opts):
        actuate.BinaryActuator.setup(self, opts)
        self.file = os.path.expanduser(opts['filename'])

    def get_state(self, request):
        with open(self.file, 'r') as fp:
            return int(fp.read())

    def set_state(self, request, state):
        with open(self.file, 'w') as fp:
            fp.write(str(state))
        return state

A few key points to notice:

1. The actuator inherits from a BinaryActuator. This means it can be in only one of two positions (on/off, 1/0).
2. We implemented two methods – get_state and set_state to actually perform the actuation. These will be called from an HTTP request handler so there are some concerns about them.

Implementing get_state and set_state¶

These functions implement the actual logic for talking to your device. Since we’re using twisted, you should not block inside of these methods (I cheated a little bit by reading a file in the example). You may, however, return a Deferred which will fire with the result; however, since any HTTP requests will wait until you produce a value you should make sure to either produce a result or an error within a reasonable amount of time.

The value (or result of the deferred) for both methods should be a valid value for the actuator type in question. Every actuator class has a valid_state(state) method which returns True if the state variable contains a valid value; for instance; the smap.actuate.BinaryActuator class allows only 0 or 1 as valid states.

Building a Driver with Actuators¶

Once you’ve built your actuator, you’ll want to include it in a driver. This is also relatively simple:

class FileDriver(driver.SmapDriver):
    """Driver which creates a single point backed by a file.  You
    could use this, for instance, to expose flags in /proc"""
    def setup(self, opts):
        filename = opts.pop('Filename', '~/FileActuatorFile')
        self.add_actuator('/point0', 'Switch Position',
                          FileActuator, setup={'filename': filename})

Just like when adding a Timeseries to a sMAP server, we add an actuator with a path (/point0) and unit (Switch Position). Because this is an actuator, we also specify the classname of the actuation class with the logic we want to expose. As you can see, the setup dict will be passed to the setup method of the actuator; in this case we use it to choose what file the actuator is controlling.

Rate Limiting¶

Frequently, you’ll want to rate-limit how often the underlying actuator is accessed. You can control this when adding the actuator using the read_limit and write_limit keyword args. Take, for instance:

self.add_actuator('/point0', 'Switch Position',
                  FileActuator, setup={'filename': filename},
                  read_limit=1, write_limit=1)

Now, we’ll return an HTTP 503 Service Unavailable if we access the actuator more than once per second.

Actuator Classes¶

We have defined several different actuator classes that cover common types of actuation as part of

Full Example¶

The conf file in python/conf/example.ini includes a file actuation driver for demonstration purposes:

[/actuator0]
type = smap.drivers.file.FileDriver
Filename = ~/smap-actuator.txt

This creates a file actuator backed by the file ~/smap-actuator.txt. The sMAP server will return errors until that file is created; however, you can change the state of that file using HTTP requests, once that driver is running:

# create the file
echo 1 > ~/smap-actuator.txt

# get the current value
curl http://localhost:8080/data/actuator0/point0
{"Properties": {"Timezone": "America/Los_Angeles", "UnitofMeasure": "Switch Position", "ReadingType": "long"}, "Actuate": {"Model": "binary"}, "uuid": "7afaa0a6-7719-5c1b-ae38-0f03b6d35256", "Readings": [[1354064481000, 0]]}

# change the state
curl  -XPUT localhost:8080/data/actuator0/point0?state=1
{"Properties": {"Timezone": "America/Los_Angeles", "UnitofMeasure": "Switch Position", "ReadingType": "long"}, "Actuate": {"Model": "binary"}, "uuid": "7afaa0a6-7719-5c1b-ae38-0f03b6d35256", "Readings": [[1354064507000, 1]]}