Tutorial on using SensorDB library
You will need to install the software dependancies described in the README.
You can either download the tarball from here or if you are technically inclined, you might choose to install git and run the following command: (If you do not know what git is, I suggest you use the tarball)
$ git clone git@github.com:prashmohan/SensorDB.git
Open the Python prompt in your favourite command line terminal (I use iTerm). In this tutorial, I will use iPython which is an interactive python shell. It has various features such as the ability to using tabs for autocomplete, easy access to function documentation, etc. I would suggest you use the same to follow this tutorial.
When you run 'ipython -pylab', you will be presented with a prompt similar to
% ipython -pylab
Python 2.6.6 (r266:84292, May 21 2011, 16:09:23)
Type "copyright", "credits" or "license" for more information.
IPython 0.10.1 -- An enhanced Interactive Python.
? -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help -> Python's own help system.
object? -> Details about 'object'. ?object also works, ?? prints more.
Welcome to pylab, a matplotlib-based Python environment.
For more information, type 'help(pylab)'.
In [1]:
At the prompt, you need to ensure that you are currently working in the directory holding the library files you just downloaded. In my case I would do something like this:
In [1]: cd /Users/prmohan/Projects/SensorDB/
/Users/prmohan/Projects/SensorDB
In [2]: pwd
Out[2]: '/Users/prmohan/Projects/SensorDB'
Now you import the library:
In [3]: import sensordb
First, we create a trace object to access the sensor data:
In [5]: trace = sensordb.SCADATrace()
At any point, if you want to know what functions are provided by the object, in iPython, you can type in the object name followed by a period and hit the tab button. For example:
In [7]: trace.
trace._SCADATrace__file_trace_initialize trace.__init__ trace.__weakref__
trace._SCADATrace__get_tsdb_metrics trace.__module__ trace.get_rooms
trace._SCADATrace__tsdb_trace_initialize trace.__new__ trace.get_sensor_names
trace.__class__ trace.__reduce__ trace.get_sensor_types
trace.__delattr__ trace.__reduce_ex__ trace.get_trace
trace.__dict__ trace.__repr__ trace.get_traces
trace.__doc__ trace.__setattr__ trace.start_limit
trace.__format__ trace.__sizeof__ trace.stop_limit
trace.__getattribute__ trace.__str__ trace.traces
trace.__hash__ trace.__subclasshook__
Further, if you want to know additional information on any of the functions, iPython lets you access the function documentation by typing the function name followed by a '?'. Using '??' will give you additional information including the source code of the function. For example:
In [9]: trace.get_sensor_names?
Type: instancemethod
Base Class: <type 'instancemethod'>
String Form: <bound method SCADATrace.get_sensor_names of <sensordb.SCADATrace object at 0x103e4f310>>
Namespace: Interactive
File: /Users/prmohan/Projects/scada/sensordb.py
Definition: trace.get_sensor_names(self)
Docstring:
Returns the names of all the sensors in the trace
Now, you are ready to play with the sensor data. For instance you use the get_sensor_names() function to get the name of all the sensors in the data set. The get_sensor_types() function returns the "types" of sensors available in the data set. For example some of the important sensors are:
"ART" - "Area Room Temperature"
"RVAV"/"VAV" - "Variable Air Vent"
"ARS" - "Area Room Set Point"
Now, to get all sensors of type ART, you would do trace.get_traces('ART'). On the other hand given a sensor name, if you wanted to access the sensor object for that particular sensor, you would do trace.get_trace('SODA4R637__ART').
In [9]: art_sensors = trace.get_traces('ART')
In [10]: print len(art_sensors)
247
In [11]: r637_art = trace.get_trace('SODA4R637__ART')
In [12]: type(r637_art)
Out[12]: <class 'sensordb.TSDBTrace'>
To get the data for a particular sensor, we use the get_data_tuples() function. The function expects a mandatory start time and an optional stop time. The trace for Soda Hall exists from November 2008. In python, we describe dates using the datetime object. Additionally, the plot command which is part of matplotlib can be used to visualize the data.
In [15]: import datetime
In [16]: start_time = datetime.datetime(2010, 1, 1)
In [17]: ts, data = r637_art.get_data_tuples(start_time)
In [18]: plot(ts, data)
Out[18]: [<matplotlib.lines.Line2D object at 0x106098c50>]
This should generate a window showing a plot similar to this.
You can also play with data specific to a room using the the get_rooms() function. The get_rooms() functions returns a room map containing data specific to each room. The set of rooms can be viewed by running the room_map.keys() command. The get_summary() function on a room returns the summary of the "ART" sensor by default. You can also get the summary of other sensors by accessing the "ARS" and "VAV" objects directly.
In [14]: room_map = trace.get_rooms()
In [15]: r543 = room_map['543']
In [16]: r543.get_summary()
Out[16]:
{'ave': 71.222944397777681,
'max': 80.129997253417969,
'min': 67.199996948242188}
In [17]: r543.ART.get_summary()
Out[17]:
{'ave': 71.222944397777681,
'max': 80.129997253417969,
'min': 67.199996948242188}
In [18]: r543.ARS.get_summary()
Out[18]: {'ave': 70.098393285371699, 'max': 72.0, 'min': 70.0}
In [19]: r543.VAV.get_summary()
Out[19]: {'ave': 11.264224462772159, 'max': 30.0, 'min': 1.5299999713897705}