tinyschema.tex

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

This is not a split-phase attribute.
\item {\tt SCHEMA\_RESULT\_PENDING}.  This means that
the attribute value is not ready.  It will be ready when the 
{\tt getAttrDone} event is signaled.  This is a split-phase attribute.
\item {\tt SCHEMA\_RESULT\_NULL}.  The value of this attribute is null.
\item {\tt SCHEMA\_RESULT\_ERROR}.  Something is wrong.
\end{itemize}


\noindent{\tt command result\_t setAttrValue(char *name, char *attrVal)}

This command sets the value of an attribute by name.  {\tt name} is the attribute name.  {\tt attrVal} is a pointer to a value of the same type as the
attribute.  This command will return FAIL if the attribute cannot be set.


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

This event will be signaled after a {\tt getAttrValue} command is called on
a split-phase attribute when the value of the attribute is ready.
By this time, the value of the attribute is already copied into resultBuf.
{\tt errorNo} are the same as described for {\tt getAttrValue}.

\noindent{\tt command result\_t startAttr(uint8\_t id)}

This command is called to start or restart the attribute with attribute id
{\tt id}.  It is typically
called after a mote wakes up after a sleep period for turning on 
the corresponding
sensor associated with an attribute.


\noindent{\tt event result\_t startAttrDone(uint8\_t id)}

This event will be signaled after a {\tt startAttr} command is called
when the sensor associated with the attribute is ready for use.
{\tt getAttrValue} must not be called before this event is signaled.

\subsection{Command Related Interfaces}
\subsubsection{Command Data Structures}

All command related data structures are defined in
{\tt \docroot/tos/interfaces/Command.h}.
It defines the following important data structures:
\begin{itemize}
\item {\tt CommandDesc} is for a command descriptor.
\item {\tt CommandDescs} is for an array of command descriptors.
\item {\tt ParamList} is a list of parameter types used in command definitions.
There is a convinient varg function {\tt setParamList} to 
populate a {\tt ParamList} with a list of types.
\item {\tt ParamVals} is a a list of parameter values for command invocation.
\end{itemize}

You must pay attention to the constants defined at the beginning
of {\tt Command.h} for the current limitations such as maximum number of
parameters in a command, maximum number of commands and maximum number of
characters in a command name.  These limits must be observed or extended
at the cost of more RAM consumption.

\subsubsection{CommandRegister}

\noindent{\tt command result\_t registerCommand(char *name, TOSType retType, uint8\_t retLen, ParamList *paramList)}

This NesC command registers a new TinySchema command.  {\tt name} is the
name of the command.  {\tt retType} is the return type of the command.
Use the {\tt VOID} type if the command does not return any value.
{\tt retLen} is the maximum length for the return value
for any variable length types such as {\tt STRING}.
It is ignored for fixed-length types.
{\tt paramList} is the list of parameter types that this
command expects when invoked.


\noindent{\tt event result\_t commandFunc(char *commandName, char *resultBuf, SchemaErrorNo *errorNo, ParamVals *params)}

This is the TinyOS code you provide that implements the command
that you just registered through {\tt registerCommand}.
{\tt commandName} is the name of the command.  It is mostly redundant, but may
come in handy when you want to write one piece of code to implement
multiple commands.  {\tt resultBuf} is a pointer to the preallocated buffer
this command's return value is supposed to be copied into.
{\tt errorNo} is the return parameter for error code.  {\tt params} is
the list of parameter values for the current invocation.
You are required to do one of the following in {\tt commandFunc}:
\begin{itemize}
\item Non-split-phase return.  Copy the return value to resultBuf, 
set {\tt *errorNo}
to {\tt SCHEMA\_RESULT\_READY} or {\tt SCHEMA\_RESULT\_NULL} then return.
\item Split-phase return.  Initiate the split-phase operation,
set {\tt *errorNo}
to {\tt SCHEMA\_RESULT\_PENDING} then return.  
{\tt commandDone} must be called
from the split-phase completion event.
\item Error.  Set {\tt *errorNo} to {\tt SCHEMA\_RESULT\_ERROR} then return.
\end{itemize}


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

This NesC command must be called in the split-phase completion event if
{\tt commandFunc} returns an error code of {\tt SCHEMA\_RESULT\_PENDING}.
{\tt commandName} is the command name.  {\tt resultBuf} is a pointer to
a buffer the return value is supposed to be copied into.
{\tt errorNo} is the error code.

\subsubsection{CommandUse}

\noindent{\tt command CommandDescPtr getCommand(char *name)}

This NesC command looks up a TinySchema command descriptor by name.  The name
is case-insensitive.  NULL is returned
if the command does not exist.


\noindent{\tt command CommandDescPtr getCommandById(uint8\_t idx)}

This NesC command looks up a TinySchema command descriptor by index.


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

This NesC command returns the total number of TinySchema commands
currently registered.


\noindent{\tt command CommandDescsPtr getCommands()}

This NesC command returns an array of command descriptors for all
the currently registered TinySchema commands.


\noindent{\tt command result\_t invoke(char *commandName, char *resultBuf, SchemaErrorNo *errorNo, ParamVals *params)}

This NesC command is for invoking a TinySchema command.  {\tt commandName} is
the name of the TinySchema command.  {\tt resultBuf} is a pointer to
the buffer the return value is supposed to be copied into.  {\tt errorNo} is
the return parameter for error code.  {\tt ParamVals} is the
list of parameter values to be passed into this TinySchema command.
See the description of {\tt getAttrValue} in Section~\ref{sec:attruse}
for all the error codes you should handle.


\noindent{\tt command result\_t invokeMsg(TOS\_MsgPtr msg, char *resultBuf, SchemaErrorNo *errorNo)}

This NesC command is a wrapper over {\tt invoke}.  It first parses the
{\tt TOS\_Msg} into a command name and a list of parameter values then calls
{\tt invoke}.  {\tt msg.data} is expected to start with the null-terminated
string for command name followed by the list of parameter values tightly
packed one after the other.  This NesC command is introduced for
supporting remote invocation of TinySchema commands via the radio.


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

This is the event you are supposed to implement to handle split-phase
command completion.  See the description for {\tt getAttrDone} event
in Section~\ref{sec:attruse}.

\subsection{Event Related Interfaces}
\subsubsection{Event Data Structures}

All event related data structures are defined in
{\tt \docroot/tos/interfaces/Event.h}.
It defines the following important data structures:
\begin{itemize}
\item {\tt EventDesc} is for a command descriptor.
\item {\tt EventDescs} is for an array of command descriptors.
\item {\tt EventInstance} represents an instance of an event that is signaled
\item {\tt EventQueue} is a queue of {\tt EventInstance}'s.
\end{itemize}

\subsubsection{EventRegister}

\noindent{\tt command result\_t registerEvent(char *name, ParamList *paramList)}

This NesC command registers a new TinySchema event.  {\tt name} is the
name of the command.  
{\tt paramList} is the list of parameter types that this
event will be signaled with.

\noindent{\tt command result\_t deleteEvent(char *name)}

This NesC command deletes a registered event.

\subsubsection{EventUse}

\noindent{\tt command EventDescPtr getEvent(char *name)}

This NesC command looks up a TinySchema event descriptor by name.  The name
is case-insensitive.  NULL is returned
if the event does not exist.


\noindent{\tt command EventDescPtr getEventById(uint8\_t idx)}

This NesC command looks up a TinySchema event descriptor by index.

\noindent{\tt command EventDescsPtr getEvents()}

This NesC command returns an array of event descriptors for all
the currently registered TinySchema events.


\noindent{\tt command result\_t signalEvent(char *eventName, ParamVals *params)}

This NesC command is for signaling a TinySchema event.  {\tt eventName} is
the name of the TinySchema event.
{\tt ParamVals} is the
list of parameter values to be passed into this TinySchema event.

\noindent{\tt command result\_t signalEventMsg(TOS\_MsgPtr msg)}

This NesC command is a wrapper over {\tt signalEvent}.  It first parses the
{\tt TOS\_Msg} into a event name and a list of parameter values then calls
{\tt signalEvent}.  {\tt msg.data} is expected to start with the null-terminated
string for command name followed by the list of parameter values tightly
packed one after the other.  This NesC command is introduced for
supporting remote signaling of TinySchema events via the radio.

\noindent{\tt command result\_t registerEventCallback(char *eventName, char *cmdName)}

This NesC command registers an event interest by associating a TinySchema
command to a TinySchema event.  The TinySchema command will be
invoked when the TinySchema event is signaled.  The maximum number
of TinySchema commands that can be associated with each event is
defined in Event.h.

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

This NesC event is signaled upon completion of all the commands
associated with the event.

\section{Examples}

Directories {\tt \docroot/tos/lib/Attributes} and 
{\tt \docroot/tos/lib/Commands}
contain all the ready-to-use components that implements
the most common attributes and commands.
These are also the attributes and commands that are built into TinyDB.
They also serve as examples of TinySchema attribute and 
command implementations. 
The following is the list of files in these two directories and the
corresponding attributes and commands that they implement.  If you want to
use any of these predefined attributes or commands in your application,
simply wire the {\tt StdControl} interface of these components to 
{\tt Main.StdControl} and the attributes or commands will be automatically
registered and ready to use.

\begin{itemize}
\item {\tt \docroot/tos/lib/Attributes/}
\begin{itemize}
\item {\tt \{AttrAccel,AttrAccelM\}.nc} defines two attributes: {\em accel\_x}
and {\em accel\_y} for the raw accelerometer readings in the X and Y axis
respectively.
\item {\tt \{AttrGlobal,AttrGlobalM\}.nc} defines two attributes: {\em nodeid}
and {\em group} for the node id and group id respectively.
\item {\tt \{AttrMag,AttrMagM\}.nc} defines two attributes: {\em mag\_x}
and {\em mag\_y}.  They are maximum magnetometer readings in the X or Y axis
at 32 samples/second since the last time you get their values.  At the same
time, they also automatically adjust the X and Y potentiometers
of the magnetometer to keep the readings centered and avoid railing.
These two attributes are designed for detecting moving magnetic fields.
For example, they are used in the car tracking demo in TinyDB in which
the car (with a magnet) is detected by a mote based on spikes in
the values of these two attributes.
\item {\tt \{AttrMic,AttrMicM\}.nc} defines four attributes: {\em rawmic},
{\em noise}, {\em rawtone} and {\em tones}.  {\em rawmic} is the raw
microphone ADC reading.  {\em noise} is the maximum microphone reading
at 32 samples/second since last time the attribute is read.  {\em rawtone}
returns 1 if a sounder tone is detected, 0 otherwise.  {\em tones} returns
the total number of tones detected at 32 samples/second since the last
time this attribute is read.
\item {\tt \{AttrPhoto,AttrPhotoM\}.nc} defines the {\em light} attribute.
It returns the raw ADC reading from the photo sensor.
\item {\tt \{AttrPot,AttrPotM\}.nc} defines the {\em pot} attribute.  It
returns the current potentiometer setting (transmit power).  
This attribute can also be set.
\item {\tt \{AttrTemp,AttrTempM\}.nc} defines the {\em temp} attribute.  It
returns the raw temperature sensor reading.
\item {\tt \{AttrVoltage,AttrVoltageM\}.nc} defines the {\em voltage} attribute.
It returns the ADC reading for the current battery voltage.  It is an indicator
of how much battery power is remaining.
\end{itemize}
\item {\tt \docroot/tos/lib/Commands/}
\begin{itemize}
\item {\tt \{CommandLeds,CommandLedsM\}.nc} defines three commands:
{\em SetLedR(UINT8)}, {\em SetLedG(UINT8)} and {\em SetLedY(UINT8)}.
They control the Red, Green and Yellow LEDs on a mote respectively.
An argument of 0 means turning the LED off, 1 means on and 2 means toggle.
All three commands return VOID.
\item {\tt \{CommandPot,CommandPotM\}.nc} defines the {\em SetPot(UINT8)}
command.  It sets the potentiometer value (transmit power) on a mote.
\item {\tt \{CommandReset,CommandResetM\}.nc} defines the dangerous
{\em reset} command.  It reboots a mote.
\item {\tt \{CommandSounder,CommandSounderM\}.nc} defines the 
{\em SetSnd(INT16)} command.  It turns on the buzzer for
a period specified by the argument (in milliseconds).
\item {\tt \{CommandAttr,CommandAttrM\}.nc} defines the 
{\em addattr(STRING, UINT8, UINT32)} command.  It dynamically
registers a new constant attribute.  The first argument is the
name of the attribute.  The second argument is the type id for the
attribute as defined in {\tt \docroot/tos/interfaces/SchemaType.h}.
The third argument is the constant value to be associated with the
attribute.
\end{itemize}
\end{itemize}

\end{document}