[Tinyos-commits] CVS: tinyos-1.x/tos/lib/VM/languages/tinysql tinysql.txt, NONE, 1.1

[David Gay]

Update of /cvsroot/tinyos/tinyos-1.x/tos/lib/VM/languages/tinysql
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31274

Added Files:
	tinysql.txt 
Log Message:
tinysql docs


--- NEW FILE: tinysql.txt ---
1) Introduction
===============

Mate includes an implementation of the TinySQL query language, pioneered
by TinyDB [1], for collecting data from a sensor network.

TinySQL allows you to view a sensor network as a database, where the
sensors present on each node are treated as the columns ("attributes")
of the database. Additionally, a few other important node
characteristics, such as node id, are also attributes. This database
is then queriable using a SQL-like language, whose major difference
from SQL is that queries include a "sample period". This sample period
is an interval at which the query is evaluated and results of the
query potentially returned. The query is thus "continuous", returning
a stream of data to the sensor network's base station until stopped.

2) A simple example
===================

This example is designed for use with mica2 nodes with a micasb (aka mts300)
sensor board. To adapt it for other motes or sensor boards, please see
Section XXX.

First, because Mate's TinySQL implementation is based on compiling TinySQL
queries to motlle code, you need to build and install an appropriately 
configured motlle VM on your motes. Do this as follows:
  cd $(TOSDIR)/lib/VM/languages/motlle
  make # ensure motlle is configured
  cd examples
  ../tools/motllevm-build tsql.vmsf # create TinySQL VM
  cd $(TOSDIR)/../apps/TSQLVM
  make mica2

Then, install this program on a collection of motes, using separate ids. One
mote, which will serve as the TinySQL base station must have id 0. E.g.,
  make mica2 reinstall.0 # base station mote
  make mica2 reinstall.1 # first data gathering mote
  make mica2 reinstall.2 # second data gathering mote
You may of course need different arguments to make if you are not using
the parallel-port programming board.

Next, you need to set up your sensor network, using mote 0 as a base
station connected to your PC (no sensor board needed), and giving all
other motes a micasb sensor board. Also, you need to run a serial
forwarder on your PC, setup to talk to mote 0.

To check that your motes have been correctly programmed, etc, you should
execute the following command in the TSQLVM directory:
  ./mload -e "led(1)"
This should turn on the red LED on your base station, and shortly thereafter
on all other motes. If this doesn't happen, check that your serial forwarder
is setup correctly and that your motes are programmed correctly.

You are now ready to run your first query. Try:
  cd $(TOSDIR)/lib/VM/languages/tinysql
  ./tsqlrun "select id, light interval 10"
This should collect mote identity and light readings from all motes in the
network every 10s. The results will be printed by tsqlrun until you interrupt
it.

Interrupting tsqlrun does not stop the query. You can resume collecting
results by executing (all tsqlrun commands should be run from the
$(TOSDIR)/lib/VM/languages/tinysql directory):
  ./tsqlrun --resume
which will resume printing results until you interrupt tsqlrun.

You can terminate data collection by executing
  ./tsqlrun --stop

If you start a new query with tsqlrun, the old query will be automatically
terminated.

3) The TinySQL language
=======================

4) The tsqlrun command
======================

5) Extending TinySQL: User-specified attributes, aggregates
===========================================================

6) Configuring a TinySQL VM
===========================

A TinySQL VM configuration file (.vmsf) should look like the following:
# Pick a name and a directory for your TinySQL VM
<VM NAME="TSQLVM" DESC="A TinySQL VM with micasb sensor board support." DIR="../../../../../../apps/TSQLVM">
<OPTION CAPSULE_SIZE=1024>
<SEARCH PATH="../../../opcodes">
<SEARCH PATH="../../../contexts">
<SEARCH PATH="../mate">
<SEARCH PATH="../mate/rep-float">
<SEARCH PATH="../mate/runtime">
<SEARCH PATH="../mate/runtime/gen">
<SEARCH PATH="../matelib">
<SEARCH PATH="../matelib/gen">
<SEARCH PATH="../../../../Util">
<SEARCH PATH="../../../../MintRoute">

<LANGUAGE NAME="motlle">
<LOAD FILE="../mate/runtime/gen/floatfns.vmsf">

<FUNCTION NAME="led">
<FUNCTION name="id">
<FUNCTION name="sleep">
<CONTEXT NAME="Timer0">
<LOAD FILE="../matelib/gen/commfns.vmsf">
<LOAD FILE="../matelib/gen/mhopfns.vmsf">
<LOAD FILE="../matelib/gen/queryfns.vmsf">
# Load Mate support for your sensor board
<LOAD FILE="../../../sensorboards/micasb.vmsf">


Normally, you should only need to change the first (VM name and directory)
and last (sensor board support) lines.