tinydb.tex

tinyos中文手册,是根据tinyos系统自带手册翻译过来的,虽然质量不好,但是对英文不强的人还是有用的

the sensorboard in question; we do not document the structure or
contents of these files and components here -- refer to the TinyOS
tutorials for more information about the ADC.

TinyDB must be configured at compile time to use one of these sensorboard
directories.  Configuration is done through the {\tt \docroot/apps/TinyDBApp/Makefile}.
To change to a different sensorboard, change the line that reads {\tt SENSORBOARD=micawb}
to refer to a different subdirectory of the {\tt sensorboards} directory.

You must also add attributes to TinyDB for each of the sensors in the sensorboard
of interest.  These attributes are stored in {\tt \docroot/tos/lib/Attributes}.
For more information about authoring attributes in TinyDB, see the TinySchema documentation
which should be included with this document and is available as a part of the TinyOS
distribution in the {\tt \docroot/doc/tinyschema.pdf} file.

Once you have created attributes for your new sensors, you can add them to TinyDB via the
following steps:

\begin{itemize}
\item In {\tt \docroot/tos/lib/TinyDB/}, modify the {\tt TinyDBAttr.nc} file to wire in your
new attribute.  For example, if you create an attribute {\tt MyLightSensor.nc} that implements
the {\tt \docroot/tos/interfaces/AttrRegister} interface, you would add {\tt MyLightSensor} to the
{\tt uses} list and add the line:

{\tt MyLightSensor.StdControl = StdControl}

\noindent to the {\tt implementation}  block.  Note that {\tt MyLightSensor.nc} needs to register
itself using the {\tt AttrRegister.registerAttr()} command, as described in the TinySchema documentation.

\item Modify the {\tt \docroot/tools/java/net/tinyos/tinydb/catalog.xml} file to include information
about your new attribute in the java GUI.  You'll need to add an {\tt <attribute>} record describing
 your component to the {\tt <attributes>}  element.  The basic structure of these elements is as follows:

\begin{verbatim}
<attribute>
  <name> </name>
  <type> </type>
  <minval> </minval>
  <maxval> </maxval>
  <isConstant> </isConstant>
  <joulesPerSample> </joulesPerSample>
</attribute>
\end{verbatim}

\noindent The last four elements are optional.  Name is the name for the attribute that should
be used in the query and will be shown in the GUI.  Type is the data type of the attribute;  it
should be one of {\tt int8,uint8,int16,uint16,int32,uint32}, or {\tt string}.  {\tt minval} and
{\tt maxval} are used in the visualization and for query optimization;  the define the minimum
and maximum values for the attribute (and are only needed for integer types.)  {\tt isConstant}
is a boolean specifying whether the attribute is a constant value;  this will eventually be
used in query optimization but is currently unused.  {\tt joulesPerSample} is an approximation
of the energy required to acquire a sample from this attribute;  this is also used in query
optimization.

\end{itemize}

\subsection{Enabling Optional Query Processor Features via CompileDefines}\label{sec:compile-defines}

The latest version of TinyDB has a number of compile-time options that need to be
properly configured to enable certain features.  These options are configured through
the {\tt \docroot/tos/lib/TinyDB/CompileDefines.h} file, which contains a number of 
options that set up with {\tt \#define} or {\tt \#undef} statements. 

RAM constraints prevent TinyDB from being able to support all options simultaneously.
{\tt CompileDefines.h} includes rough measurements of the RAM requirements of each feature;
the total RAM usage of TinyDB (displayed when the {\tt make {\it mote-type}} command is issued)
should not exceed 3100 bytes.

 Options include:

\begin{tabularx}{6in}{|c|X|}
\hline
Option & Description \\
\hline
{\tt kUSE\_MAGNETOMETER}& Compile the magnetometer attribute into TinyDB. Only needed if
  a sensor board that includes a magnetometer is included.  Disabled by default. \\
{\tt kQUERY\_SHARING}& Enable the ``query sharing'' feature that allows motes to exchange queries
with their neighbors (e.g without explicit retransmission via the ``send query'' command.)
Enabled by default. \\
{\tt kFANCY\_AGGS}& Enable a number of fancy aggregates similar to those discussed in the SIGMOD
2003 paper on Acquisitional Query Processing (ACQP). Disabled by default and not otherwise
documented. \\
{\tt kEEPROM\_ATTR}& Enable the EEPROM logging attribute that allows a signal to be captured to
the EEPROM. Disabled by default and not otherwise documented. \\
{\tt kCONTENT\_ATTR}&  Enable the {\tt content} attribute which provides a 16 bit integer indicating
the amount of radio contention currently on the radio.  Disabled by default. \\
{\tt kRAW\_MIC\_ATTRS}&  Enable the raw microphone attribute {\tt tones} that indicates whether or
not the tone detector circuit on the mote is currently detecting a 400Hz tone.  Disabled
by default. \\
{\tt kLIFE\_CMD}& Enable the {\tt lifetime} command causes the mote to adjust the sample
rate of running queries to the specified lifetime.  Disabled by default and not otherwise
documented. \\
{\tt kUART\_DEBUGGER}&  Enable support for a debugging display connected over the UART.  See
section \ref{sec:debugging} or the component {\tt \docroot/tos/lib/Util/UARTDebugger.nc}
for more information.  Note that enabling this option will force the UART to run at 
9600 bits per second on all motes except the basestation (mote ID 0), and that the
serial display cannot be used on the basestation.  Disabled by default.\\ 
{\tt kSUPPORTS\_EVENTS}&  Enable support for events (see Section \ref{sec:events}).  Disabled
by default. \\
{\tt kSTATUS}&  Enable support for the status command, that indicates the queries that are
currently running on the mote.  Enabled by default. \\
{\tt kMATCHBOX}&  Enable support for the Matchbox file system and logging queries.  See Section
\ref{sec:flash} for more information.  Disabled by default. \\
{\tt NETWORK\_MODULE} &  The name of the network module to use.  By default, set to {\tt NetworkMultiHop.nc}
See \ref{sec:tinydbnetwork} for more information. \\
\hline
\end{tabularx}

\section{The Tiny Application Sensor Kit}\label{sec:task}\index{ASK, TASK}

The Tiny Application Sensor Kit (TASK) provides a number of configuration tools and
user interfaces designed to make it easier to interact with a network of sensors running
TinyDB.  Key features include:

\begin{itemize}
\item Configuration and deployment management tools:  users can place sensors on a map and record various
kinds of meta-data about them.
\item PDA-based field tool for sensor node diagnostics in the field.
\item A simplified query interface target at logging queries.
\item Complete integration with a relational database engine to record all queries, commands, and
results sent to or received from the network.
\item Data extraction tools designed to make it easy to get this relational data into a variety of
end-user applications.
\end{itemize}

For more information about TASK, see the TASK manual in
{\tt \docroot/doc/task.pdf} or at
\htmladdnormallink{http://berkeley.intel-research.net/task/}{http://berkeley.intel-research.net/task/} 


\section{Developing For TinyDB\index{TinyDB}: Java\index{Java} API\index{API}}
\label{sec:devel}
Up to this point, we have described how to use TinyDB from the
provided GUI.  However, developers will want to embed TinySQL\index{TinySQL}
queries and fetch TinyDB result rows from within application programs.
TinyDB\index{TinyDB} provides a Java\index{Java} API\index{API} for
building such programs, which we describe here.  The provided
GUI\index{GUI} application is a good example of the use of the API,
so we describe it here as well.

We begin with an overview of the API\index{API}, and go on to an
overview of the GUI\index{GUI} program, which exercises the
API\index{API}.  The discussion here is fairly high level, and is
intended to accompany some investigation of the code itself.

\subsection{The TinyDB\index{TinyDB} Java\index{Java} API\index{API}}
The API\index{API} contains a number of objects encapsulating the
TinyDB network, the TinyDB catalog\index{catalog}, the construction of TinyDB
queries, and the manner in which the application listens for and
interprets query results.  These objects appear in the corresponding
{\tt .java} files in {\tt \java/tinyos/tinydb}.

\subsubsection{\tt TinyDB\index{TinyDB}Network} 
\label{sec:tinydbnet}

This object is the main interface to a
  network of motes\index{mote}.  It is responsible for injecting new queries into
  the network ({\tt sendQuery()}), for cancelling queries ({\tt
  abortQuery()}), and for providing results from the network to
  multiple query ``listeners''\index{listener}.  Only one instance\index{instance} of the {\tt
  TinyDB\index{TinyDB}Network} object needs to be allocated for a network; that
  instance can manage multiple ongoing queries, and multiple
  listeners.  Each query's output can be sent to multiple listeners,
  and each listener can listen either to a single query, or to all
  queries.
  
  Internally, the object maintains a list of live queries, and three
  sets of listeners\index{listener}:
  \begin{enumerate}
        \item {\tt processedListeners} are signed up for a specific query
    ID\index{ID}, and get a stream of final (``processed''\index{processed}) answer tuples\index{tuple} for
    that query.
        \item {\tt qidListeners} are signed up for a specific query ID\index{ID},
    and get copies of all messages that arrive for that query.  These
    messages may not be final query answers.  They may be individual
    attributes\index{attribute} from an answer tuple\index{tuple}, or unaggregated\index{aggregate} sub-result
    tuples\index{tuple}.
        \item  {\tt listeners} are signed up to receive a copy of all
    unprocessed\index{processed} messages for {\em all} queries.  
  \end{enumerate}
  The various listeners\index{listener} can be added or deleted to the object on the
  fly via {\tt addResultListener()} and {\tt removeResultListener()}
  -- note that different arguments to the {\tt addResultListener}
  method result in one of the 3 different kinds of listeners above.

  The {\tt TinyDB\index{TinyDB}Network} object handles all incoming
  AM\index{Active Messages (AM)}\glossary{AM} messages from the
  serial port\index{serial}, and dispatches copies of them to the {\tt listeners}\index{listener}
  and {\tt qidListeners} accordingly.  It also processes the messages
  to generate result tuples\index{tuple} (via {\tt QueryResult.MergeQueryResult()})
  and sends them to {\tt processedListeners}\index{processed} accordingly.  As part of
  processing results, it maintains info on epochs\index{epoch} to make sure that
  the epoch\index{epoch} semantics\index{semantics} of the results are correct.

  Internally, the {\tt TinyDB\index{TinyDB}Network} object also has a background thread
  that participates in the sensor network's\index{sensor network} routing\index{routing} algorithms.  It
  periodically sends information down the routing\index{routing} tree, so that
  children know to choose the root\index{root} as a parent\index{parent}, and so that children
  can decide how to share the timeslots\index{timeslot} in an
  epoch\index{epoch}.  
% {\bf Note dependency here: programmers wanting to hack the
% topology\index{topology} code need to hack here too.}

\subsubsection{\tt SensorQueryer}
This class appears in the {\tt parser} subdirectory.  It represents a
simple parser for TinySQL\index{TinySQL}.  The main method of interest is {\tt
translateQuery}, which takes an SQL\index{SQL} string and returns a corresponding
{\tt TinyDBQuery} object, which we proceed to describe next.

\subsubsection{\tt TinyDB\index{TinyDB}Query} 
\label{sec:tinydbquery}
This is a Java\index{Java} data structure representing a
    query running (or to be run) on a set of motes\index{mote}.
    
    Queries consist of:
    \begin{itemize}
    \item a list of attributes\index{attribute} to select
    \item a list of expressions\index{expression} over those attributes, where an expression\index{expression}
    is
      \begin{itemize}
      \item a filter\index{filter} that discards values that do not match a
      boolean expression\index{expression}
      \item an aggregate\index{aggregate} that combines local values
        with values from
        neighbors\index{neighbor}, and optionally includes a GROUP
        BY\index{Group By}\index{group} column.  
% {\bf
%         (Hack: GROUP BY\index{Group By} columns can optionally be bit-shifted before
%         the grouping\index{group} happens, to make for fewer groups\index{group} (buckets) on a
%         dense domain.  This is called ``attenuation\index{attenuation}'' in the API\index{API}.)}
%         {\bf (Limitation: GROUP BY\index{Group By} can currently only be done on a
%        single attribute\index{attribute}, and not on multiple
%        attribute and/or expressions\index{expression}.)} 
      \end{itemize}
    \item an SQL\index{SQL} string that should correspond to the expressions\index{expression}
    listed above.

    \end{itemize}

   In addition to allowing a query to be built, this class includes
   handy methods to generate specific radio messages for the query,
   which {\tt TinyDB\index{TinyDB}Network} can use to distribute the query over the
   network, or to abort the query.

   It also includes a support routine for printing the query result
   schema\index{schema}.

\subsubsection{\tt QueryResult}
\label{sec:tinydbqueryresult}
This object accepts a query result in the
    form of an array of bytes read off the network, parses the results
    based on a query specification, and provides a number of utility
    routines to read the values back.  It also provides the {\tt
    mergeQueryResult} functionality for {\tt processedListeners}\index{processed}\index{listener}.
    This does concatenation of multiple aggs as separate attributes of
    a single result tuple, and finalizes aggregates\index{aggregate}, by
    combining data from multiple sensors\index{sensor}.

\subsubsection{\tt AggOp} 
\label{sec:tinydbaggop}

This provides the code for the aggregation\index{aggregation}
  operators SUM, MIN, MAX, and AVG.  It includes representation
  issues (internal network codes for the various ops, and code for
  pretty-printing), and also the logic for performing final merges for
  each aggregate\index{aggregate} as part of {\tt QueryResult:MergeQueryResult()}.
%  {\bf This is another place you need to touch i