tinyschema.tex

无线通信的主要编程软件,是无线通信工作人员的必备工具,关天相关教程我会在后续传上.

\documentclass[11pt]{article}
\usepackage{html}
\usepackage{psfig}
\usepackage{nomencl}
\oddsidemargin  -0.1in   %  Note that \oddsidemargin = \evensidemargin
\evensidemargin -0.1in

%\topmargin -55pt         %    Nominal distance from top of page to top
%                         %    of box containing running head.
\headheight 12pt         %    Height of box containing running head.
%\headsep 25pt            %    Space between running head and text.
%\footskip 60pt           %    Distance from baseline of box containing


\textheight 9.125in        % Height of text (including footnotes and
                         % figures, excluding running head and foot).
\textwidth 6.75in         % Width of text line.
                         % For two-column mode:

\textheight 9.125in        % Height of text (including footnotes and
                         % figures, excluding running head and foot).
\textwidth 6.75in         % Width of text line.
                         % For two-column mode:
\renewcommand{\baselinestretch}{1.2}


\newcommand{\docroot}{tinyos-1.x}

\begin{latexonly}
\title{\vspace{2.5in} TinySchema: Managing Attributes, Commands and Events in TinyOS}
\end{latexonly}
\begin{htmlonly}
\title{TinySchema: Managing Attributes, Commands and Events in TinyOS}
\end{htmlonly}
\author{Wei Hong and Sam Madden \\
	[e-mail], [e-mail]}
\date{}

\begin{document}
\pagenumbering{arabic}
%\pagestyle{myheadings}
\markright{{\bf TinySchema Documentation. }}

\maketitle
\begin{latexonly}
\vspace{2in}
\end{latexonly}
\begin{center}
Version 1.1 \\
September, 2003
\end{center}


\begin{latexonly}\newpage\end{latexonly}
\section{Introduction}

{\em TinySchema} is a collection of TinyOS components that manages
a small respository of named attributes, commands and events that can be
easily queried, invoked or signaled from inside or outside a mote network.
A TinySchema {\em attribute} is much like a column in a traditional database system.
It has a name and a type.  In addition, TinySchema allows you to
associate arbitrary TinyOS code to each attribute for getting
and setting the attribute value.  Once an attribute is created, it can
be retrieved or updated through a unified interface provided by TinySchema.
{\em TinyDB} (see TinyDB document), the in-network query
processing system for TinyOS, is one of the applications built on top
of this interface.  You can also build your own application for manipulating
attributes based on the interfaces provided by TinySchema.  Typically, there
are three classes of attributes:
\begin{itemize}
\item Sensor Attributes.  These can be raw readings from sensors such as
temperature and photo sensors, accelerometers, magnetometers, etc.
They can also be computed sensor values after applying some calibration
or signal processing logic.
\item Introspective Attributes.  These are values from internal
software or hardware states, e.g., software version stamp, parent node
in routing tree, battery voltage, etc.  They are very useful for
monitoring the health and statistics of a mote network.
\item Constant Attributes.  These are constant values assigned to
a mote at programming time or run time, e.g., node id, group id, name,
location, etc.
\end{itemize}

A TinySchema {\em command} is much like a stored procedure in a traditional
database system.  It consists of a name, a list of arguments and a return
type.  You can associate arbitrary TinyOS code to each command.
TinySchema provides a unified interface for invoking these commands.
TinyDB is also built on top of the TinySchema command interfaces for
its trigger actions (see TinyDB document).  Typically, there are two
classes of commands:
\begin{itemize}
\item Actuation Command.  These are commands that cause some physical
actions on a mote, e.g., rebooting a mote, flash LEDs, sound buzzer,
raise a blind (when connected to an appropriate actuator), etc.
\item Tuning Command.  These are commands that adjust internal parameters,
e.g., routing policy, number of retransmissions, sample rate, etc.
\end{itemize}

A TinySchema {\em event} is introduced to capture asynchronous
events in sensor networks, e.g., detection of a bird, push of a button, etc.
TinySchema provides interfaces for registering and invoking events as well
as associating TinySchema commands with events as callbacks when events
are signaled.

Currently all attributes and all commands must be staticly built
into each mote.  We plan to integrate with the virtual machines being
developed for the TinyOS such as Mate and Mottle to allow dynamic
creation of attributes and commands.

TinySchema is part of TinyOS1.1 release.

\section{System Overview}

TinySchema has three separate components in {\tt \docroot/tos/lib/Attributes/Attr.nc},
{\tt \docroot/tos/lib/Commands/Command.nc} 
and {\tt \docroot/tos/lib/Events/Event.nc}.  
{\em Attr} provides all attributes
related interfaces, {\em Command} provides all command related interfaces,
and {\em Event} provides all event related interfaces.

{\em Attr} provides the following interfaces:
\begin{itemize}
\item {\tt StdControl} for initialization.
\item {\tt AttrRegister} for creating new attributes.  It is parametrized
by a {\tt uint8\_t} (for up to 256 such interfaces).  Each non-constant attribute must be
connected to one of these interfaces.  The coding convention is not
to hardwire a specific number when you wire to one these 256 interfaces, but
to wire your interface to {\tt Attr.Attr[unique("Attr")]} and let
the NesC compiler to automatically choose a unique number for you.
\item {\tt AttrRegisterConst} for creating new constant attributes.  It is a
simplified interface of AttrRegister for attributes associated to 
constant values only.
\item {\tt AttrUse} for discovering and using attributes.
\end{itemize}

{\em Command} provides the following interfaces:
\begin{itemize}
\item {\tt StdControl} for initialization.
\item {\tt CommandRegister} for creating new commands.  It is parametrized
by a {\tt uint8\_t} (for up to 256 such interfaces).  Each command must be connected to
one of these interfaces.  The coding convention is not
to hardwire a specific number when you wire to one these 256 interfaces, but
to wire your interface to {\tt Command.Cmd[unique("Command")]} and let
the NesC compiler to automatically choose a unique number for you.
\item {\tt CommandUse} for discovering and using commands.
\end{itemize}

{\em Event} provides the following interfaces:
\begin{itemize}
\item {\tt StdControl} for initialization.
\item {\tt EventRegister} for creating new events.
\item {\tt EventUse} for discovering and signaling events as well as
creating command callbacks to events.
\end{itemize}

We will describe each of the above interfaces in details in the next
section.

\section{Detailed Interface Descriptions}

\subsection{Data Types and Error Codes}
All of TinySchema's data types and error codes are defined in 
{\tt \docroot/tos/interfaces/SchemaTypes.h}.

The following data types are supported:
\begin{itemize}
\item {\tt VOID}: the void type.  Used for defining commands that do not
return anything.
\item {\tt INT8 and UINT8}: 8-bit signed and unsigned integer types.
\item {\tt INT16 and UINT16}: 16-bit signed and unsigned integer types.
\item {\tt INT32 and UINT32}: 32-bit signed and unsigned integer types.
\item {\tt TIMESTAMP}: not yet supported.
\item {\tt STRING}: null-terminated ASCII strings.
\item {\tt COMPLEX\_TYPE}: not yet supported.
\end{itemize}

Here are the error codes used in all TinySchema interfaces:
\begin{itemize}
\item {\tt SCHEMA\_SUCCESS}: success!
\item {\tt SCHEMA\_ERROR}: something is wrong.
\item {\tt SCHEMA\_RESULT\_READY}: the return result is ready in the result
buffer.  Used for non-split-phase attributes and commands.
\item {\tt SCHEMA\_RESULT\_NULL}: the return result is null.
\item {\tt SCHEMA\_RESULT\_PENDING}: the return result is not yet filled in in the
result buffer.  Must wait for the data ready event.  Used for split-phase
attributes and commands.
\end{itemize}

\subsection{Attribute Related Interfaces}

\subsubsection{Attribute Data Structures}

All attribute related data structures are defined in
{\tt \docroot/tos/interfaces/Attr.h}.  The main data
structure is {\tt AttrDesc} which contains the definition
of each attribute.  {\tt AttrDescs} is just an array of
{\tt AttrDesc}'s for all the attributes defined in each mote.
You must pay attention to the constants defined at the beginning of the
file which defines the maximum number of attributes, maximum
attribute name length, etc.  Do not exceed those limits!  Increase
them as needed, but they cost more precious RAM space on a mote.

\subsubsection{AttrRegister}

\noindent{\tt command result\_t registerAttr(char *name, TOSType attrType, uint8\_t attrLen)}

This is the command you call to register an attribute.  The {\tt attrLen} 
argument is only relevant to variable-length types such as STRING.
It is ignored for fixed-length types.


\noindent{\tt event result\_t getAttr(char *name, char *resultBuf, SchemaErrorNo *errorNo)}

This is the TinyOS code that you must provide for getting the value of the
attribute you just registered through {\tt registerAttr}.  {\tt name} is 
the name of the attribute.  It is mostly redundent, but may come in handy
if you want to write one piece of code that supports mulitple attributes.
{\tt resultBuf} is a pointer to a pre-allocated buffer to hold the
value of this attribute.  You can assume
that enough space has been allocated to hold the value of this
attribute.  {\tt errorNo} is the return error code.  You are required
to do one of the following in {\tt getAttr}:
\begin{itemize}
\item fill in the attribute value in {\tt resultBuf} and set
{\tt *errorNo} to {\tt SCHEMA\_RESULT\_READY},
\item or set {\tt *errorNo} to
{\tt SCHEMA\_RESULT\_PENDING} and fill in {\tt resultBuf} later when the
data is ready and call {\tt getAttrDone},
\item or set {\tt *errorNo} to {\tt SCHEMA\_RESULT\_NULL},
\item or set {\tt *errorNo} to {\tt SCHEMA\_RESULT\_ERROR}.
\end{itemize}


\noindent{\tt event result\_t setAttr(char *name, char *attrVal)}

This is the TinyOS code that you must provide for setting the value of
the attribute you just registered through {\tt registerAttr}.
{\tt name} is
the name of the attribute.  It is mostly redundent, but may come in handy
if you want to write one piece of code that supports multiple attributes.
{\tt attrVal} is a pointer to a value of the same type as the attribute type.
NULL pointer means a null value.  If the value of this attribute cannot be set,
simply return {\tt FAIL}.


\noindent{\tt command result\_t getAttrDone(char *name, char *resultBuf, SchemaErrorNo errorNo)}

This is the command you must call for split-phase attributes.  In this case,
the {\tt getAttr} will initiate a split-phase operation, set {\tt *errorNo} to 
{\tt SCHEMA\_RESULT\_PENDING} then return.  In the split-phase completion event
(e.g. {\tt ADC.dataReady()}), you must call this command with the attribute
value filled in {\tt resultBuf}.

\subsubsection{AttrRegisterConst}

\noindent{\tt command result\_t registerAttr(char *name, TOSType attrType, char *attrVal)}

This command provides a simplified way to associate a constant value to an
attribute without having to write the {\tt getAttr} and {\tt setAttr} code
as described above in the {\tt AttrRegister} interface.  {\tt attrVal} points
to a value of the {\tt attrType} type.  The {\tt Attr}
component preallocates space to hold values for a fixed number
({\tt MAX\_CONST\_ATTRS} defined in {\tt \docroot/tos/interfaces/Attr.h})
of constant attributes.  This command assigns a slot in the preallocated
space to hold the constant value at {\tt attrVal}.  The {\tt AttrUse}
interface to be described below will automatically handle the get and set
of the newly defined constant attributes just like any other attributes.
Currently, a constant attribute can be at most 4 bytes long.

\subsubsection{AttrUse}
\label{sec:attruse}

\noindent{\tt command AttrDescPtr getAttr(char *name)}

This command returns a pointer to the attribute descriptor
for the attribute with a name that matches the argument.
The name is case-insensitive.
NULL will be returned if the attribute does not exist.
The returned attribute descriptor is NOT to be freed.


\noindent{\tt command AttrDescPtr getAttrById(uint8\_t attrIdx)}

This command returns a pointer to the attribute descriptor
corresponding to an attribute index.


\noindent{\tt command uint8\_t numAttrs()}

This command returns the total number of attributes that have been registered.


\noindent{\tt command AttrDescsPtr getAttrs()}

This command returns the array of attribute descriptors for all the
the attributes that have been registered.


\noindent{\tt command result\_t getAttrValue(char *name, char *resultBuf, SchemaErorNo *errorNo)}

This is the command retrieves the value of an attribute by name.
{\tt name} is the name of the attribute.  {\tt resultBuf} is a pointer to
a preallocated buffer to hold the attribute value.  It must be at least
as big as the attribute length.  {\tt errorNo} is a return parameter of
the error code.  It has the following cases:
\begin{itemize}
\item {\tt SCHEMA\_RESULT\_READY}.  This means
that the value of the attribute has already been copied into {\tt resultBuf}.