previous: Installation and Setup (Version 1.0)   next: Bytecode Assembly Interface

Query Interface

This gateway application provides a query-level interface to SwissQM. Queries (similar to TinyDB) can be composed by the user. These queries are then compiled into QM bytecode programs that are then sent into the sensor network where they are executed by the SwissQM Virtual Machine.

Starting the Wireless Sensor Network

Power-up all your nodes. Nodes will turn on their green LED if they have a link to the root, which is required for proper operation. The root node (node with ID 0) will not turn on the green LED, as it has always a connection to itself. You should wait until the green LED of every node except the root node is lit.

Connect the root node to the machine on which you run the gateway.

Starting the Gateway

Change to the folder SwissQM-gateway, where you built and configured the gateway and run

ant querygui

This will bring up the graphical user interface of the SwissQM gateway, as shown below.

Working with the Query GUI of SwissQM

The Query GUI can be used to compose queries, send them into the network, and retrieve result data. The results can be plotted in the query GUI and/or logged into a database for offline analysis. The Query GUI is based on tabs of three different types: Network, New Query, and Query Plots.

Network Tab

The network tab is shown when SwissQM is started (see screenshot above). The left column shows statistical data gathered from observing the result tuples generated by the queries (QM programs). The right column shows the commands that can be sent to SwissQM. A command can sent to be executed by one specific node or by all nodes of the network. In the former case type the ID of the target node in to the Node text field, in the latter check the All Nodes checkbox. Note that when applying the command to all nodes the TinyOS broadcast address 0xffff (65535) is used. Currently supported commands are Node Reset and setting the LEDs of the nodes. For setting the LEDs use the value and the mask check box. The bits set in the mask determine which LEDs are affected by the command.

Setting Up a new Query

Queries are composed in the New Query tab. Add query fields using the New Field button. The first field epoch is always present and is used as a coarse timestamp of the data. Explanation of the fields' attributes:

• Name: Identifier (no whitespaces) of that field. This identifier is shown in the legend of the result plot and is used as a column name if the field is logged.
• Field: Field expression
• Function: Drop-down list containing all built-in functions (aggregation and mod) as well as the available user-defined functions (see below). This field closely interacts with the Field column.
• Grouping: Set this flag if this tuple is grouping, i.e., it is either used as a grouping expression for an aggregation query and produces a new time series in the plot. Plotted, non-grouping fields will generate y-Values in the plot.
• Plot: If set the value of the field is included in the plot.
• Log into DB: If set the value of the field is logged into the database.

Optionally, a selection expression that filters tuples (identical to the 'where' clause in SQL) can be specified in the Where field. The sampling period is set in the sampling period field. Following units are recognised: ms for milliseconds, s for seconds, min for minutes, and h for hours. Note that you cannot specify a sampling period shorter than specified in swissqm.properties (property ch.ethz.inf.swissqm.qm.min_sampling_period_millis). Adjust this setting to reflect the size of your network, i.e., for larger deployments you might have to increase the minimal sampling period. When pressing Submit the query will be compiled into bytecode (the assembly listing is shown in the console) and sent into the network. The results are shown in a new plot tab.

The query shown in the screenshot above retrieves the nodeid and the average value of the two light sensors of the tmote sky mote (total solar radiation sensor light and photosynthetically active radiation sensor lightpar), i.e., each sensor node reports this average value together with its identification number. Since id is grouping and the light field is plotted a line for each sensor node is shown in the result plot:

Remark: The sudden drop in the light value is due to the fact that we switch off our office lights when we go for lunch. After lunch we turned them on again since it was very cloudy that day.

Adding a user-defined function

You can define your own functions, which you can then use in the queries. These functions are then executed locally at the sensor nodes. The functions are implemented in a C-like programming language. The language provides basically the same constrol constructs as C (except switch is currently not supported). Since SwissQM is an integer virtual machine int is the only data type currently supported. A function however may have static local variables, i.e., variables that preserve their value between invocations of the function. This allows implementing complex stateful functions. The static variables are allocated in the Synopsis of SwissQM. The following example implements an exponential weighted moving average filter (1st order IIR filter):

int ewma(int x, int palpha) {
   static int xold = 0;
   int result;
   result = (palpha*xold + (10-palpha)*x)/10;
   xold = x;
   return result;
}
   

You need to put your user-defined function into a file (e.g. ewma.udf) and store it into the udf directory (or whatever directory you specify in the swissqm.properties). Upon start of the SwissQM gateway, this directory is searched for files ending on .udf, which are then parsed. Successfully parsed functions are added to the system catalog such that they can be selected in the dropdown list of the Function column in the New Query tab. For example:

previous: Installation and Setup (Version)   next: Bytecode Assembly Interface