manual.html

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

<HR>
<H1><A NAME="sec:plugins">
Tython, SimDriver, plugins, and the radio</A>
</H1>

<P>
The core of SimDriver is an event bus. Java plugins can connect to
this event bus, receiving TOSSIM events and sending TOSSIM commands;
many of the Tython abstractions are built on top of SimDriver plugins.
TinyViz, the visualization environment, also uses plugins, so users
can write new visualizations. Correspondingly, there are two classes
of SimDriver plugins: GUI and non-GUI. In addition, scripts can
register event handlers as well, as described in a later <a
href="#sec:event_handlers">section</a>.

<P>
Examples of GUI plugins include TinyViz's radio quality visualization,
its communication visualization, and the basic plugin that draws motes
on the screen. Examples of non-GUI plugins include the radio model
plugin and the packet logger plugin. GUI plugins are only loadable
through TinyViz, while non-GUI plugins are accessible through Tython,
and are used to actuate TOSSIM in response to network changes.
SimDriver maintains a list of mote objects, which store state
pertinent to the scripting environment, such as position and LED
values.

<P>
For example, calling mote.moveTo() modifies that mote's position. This
can change radio connectivity. The radio model notices the event that
indicates a Mote's position has changed, and then calculates the
appropriate bit error rates based on new distances. The plugin will
then automatically communicate the new link qualities to TOSSIM, which
is internally unaware of mote position.

<P>

<H2><A NAME="sec:radio_models">
Position-based Radio Models</A>
</H2>

<P>
Tython and TinyViz provide two position-based radio models: disc and
empirical. The first models the network using "perfect disc"
connectivity, at three different disc radii ("disc10", "disc100", and
"disc1000"). Connectivity is perfect in that links are either
error-free or not present, depending on whether the target is in or
outside of the disc. Although links are perfect, collisions can still
occur, which will corrupt a packet.

<P>
The second model, "empirical", uses an error distribution based on
empirical data. Essentially, for any particular distance there is a
distribution of possible bit error rates: two links of identical
length can have different rates. These bit errors can cause a packet
to be corrupted so that a receiver does not recover it properly. Links
are directed: the error rate from A to B is distinct from the rate
from B to A. Roughly speaking, motes closer than 16 units will have
good connectivity, motes between 16 and 28 units will have highly
variable and possibly asymmetric connectivity, and motes 30 units and
higher away will have poor connectivity.

<P>
These position models boil down to a simple function: given a distance
between two motes, produce a bit error rate. For disc-based models,
this is a simple cutoff, which results in symmetric and perfect links.
For the empirical model, the function returns a sample from the
distribution corresponding to the distance.

<P>
Scripts can also explicitly specify connectivity qualities with the
<TT>radio</TT> object. <TT>setLossRate(src, dest, prob)</TT> sets the
bit error rate from ID <TT>src</TT> to ID <TT>dest</TT> to be
probability <TT>prob</TT>. <TT>comm.packetLossToBitError(prob)</TT>
calculates bit error rates from a packet loss rate*.

<P>
<DT><EM>*(This is actually a non-trivial calculation. It makes several
assumptions about the data link encoding (the mica stack, with SecDed
based encoding and a 9 bit start symbol) and packet length.
Specifically, the packet error rate represents a 36-byte packet. As
packets grow longer, their loss rate increases, as there is a set bit
error rate.)</EM></DT>

<H2><A NAME="sec:update_radio">
Updating the Radio Model</A>
</H2>

<P>
It is important to keep in mind that there at any one time, there are
actually two radio models for a given simulation. TOSSIM internally
maintains a table of bit error rates and uses this table to determine
if any corruption should be applied to a radio message. In addition,
SimDriver's Radio Model Plugin also maintains a table of error rates,
driven by the above-described models. The correlation of these two
data structures is controllable by the script (and also by the TinyViz
GUI).

<P>
The <TT>radio.setLossRate()</TT> function only affects the data
structure within SimDriver. Calling <TT>radio.publishModel()</TT>.
propagates the entire connectivity graph to TOSSIM, which is
<B>O(n<SUP>2</SUP>)</B>. Therefore, if a large number of links are
updated, it's best to only publish the model once, after all of the
updates.

<P>
To avoid this complexity and inefficiency, the Radio model also
supports an <em>auto-publish</em> mode. When enabled, any changes to
the connectivity graph within SimDriver are immediately propagated to
TOSSIM. Note however, that auto publish is not enabled by default, and
a script must enable it if desired:

<pre>
radio.setAutoPublish(True)
</pre>

<P>
In addition, as mentioned previously, the radio models will
automatically recalculate connectivity rates when Mote objects
reposition themselves in the virtual simulator space. Note that if
motes are moving around the space often, then auto-publish may result
in a large number of messages being sent to TOSSIM to update the
model.

<H2><A NAME="sec:gui_labels">
GUI Labels</A>
</H2>

<P>
When using Tython with TinyViz, scripts can add annotations to mote
visualizations. The <TT>setLabel()</TT> method of the mote class takes
three parameters: a string, an X offset, and a Y offset. For example,

<P>
<PRE>
motes[2].setLabel("queue depth: " + depth, 10, 0)
</PRE>

<P>
will put a small label 10 pixels to the right of mote 2 in the TinyViz
visualization panel, stating what its queue depth is (assuming the
variable <TT>depth</TT> has been set to this value previously).

<HR>
<H1><A NAME="sec:complex_scripting">
Complex Scripting</A>
</H1>

<P>
The previous sections described how to control and monitor TOSSIM
through Tython. However, the examples given were fairly simple. By
using some of Python's expressive power, one can write much more
intricate and complex scripts.

<P>

<H2><A NAME="sec:event_handlers"></A>
<BR>
Event Handlers
</H2>

<P>
Fundamentally, both TOSSIM and </TT>SimDriver</TT> are event-driven
programs. Internal to TOSSIM is a master event queue that manages the
various simulated motes. When <TT>SimDriver</TT> is connected to
TOSSIM, events are exchanged over the network connection. In this way,
the <TT>SimDriver</TT> core is structured as a set of event handlers
for events both coming from TOSSIM and internally generated.

<P>
Many Tython primitives depend on being able to handle TOSSIM events
which update the known state about the simulation. For example, every
time a mote transmits a packet, TOSSIM sends an event to
<TT>SimDriver</TT>. Internally, a plugin within <TT>SimDriver</tt>
subscribes to packet event notifications and uses them to update the
<TT>packets</TT> variable (discussed in a <A
HREF="manual.html#sec:packets">previous section</A>).

<P>
Tython scripts can also register event handlers through the
<TT>simcore.interp</TT> object. Event handlers must be functions that
expect a single parameter, the event handled. Scripts register
handlers with <TT>interp.addEventHandler()</TT>. The first parameter
is the event handling function, the second, optional parameter is the
Java event class type. Passing an event type will register the handler
for only events of that type; omitting it will have it handle all
event types. For example:

<P>
<PRE>
def print_handler(event):
  print event

# Print all events
interp.addEventHandler(print_handler)

# Print only LED events
from net.tinyos.sim.event import LedEvent
interp.addEventHandler(print_handler, LedEvent())
</PRE>

<P>
The <TT>net.tinyos.sim.event</TT> package contains all of the events
that TOSSIM generates (as well as a few which <TT>SimDriver</TT> uses
internally). The TOSSIM events are:

<P>
<BR><P></P>
<DIV ALIGN="CENTER"><A NAME="227"></A>
<TABLE>
<CAPTION><STRONG>Table:</STRONG>
TOSSIM Events</CAPTION>
<TR><TD>
<DIV ALIGN="CENTER"><TABLE CELLPADDING=3 BORDER="1">
<TR><TD ALIGN="LEFT">Name</TD>
<TD ALIGN="LEFT">When?</TD>
</TR>
<TR><TD ALIGN="LEFT">ADCDataReadyEvent</TD>
<TD ALIGN="LEFT">When a mote receives an ADC reading</TD>
</TR>
<TR><TD ALIGN="LEFT">AttributeEvent</TD>
<TD ALIGN="LEFT">(Internal to SimDriver) When a mote attribute such as power, location, etc changes.</TD>
</TR>
<TR><TD ALIGN="LEFT">DebugMsgEvent</TD>
<TD ALIGN="LEFT">Each enabled <TT>dbg</TT> statement</TD>
</TR>
<TR><TD ALIGN="LEFT">InterruptEvent</TD>
<TD ALIGN="LEFT">Unique scheduled event. See the next <a href="sec:future_actions">section</a></TD>
</TR>
<TR><TD ALIGN="LEFT">RadioMsgSentEvent</TD>
<TD ALIGN="LEFT">When a mote finishes sending a radio packet</TD>
</TR>
<TR><TD ALIGN="LEFT">SimObjectDraggedEvent</TD>
<TD ALIGN="LEFT">When a mote is dragged in the GUI</TD>
</TR>
<TR><TD ALIGN="LEFT">SimObjectSelectedEvent</TD>
<TD ALIGN="LEFT">When a mote is selected in the GUI</TD>
</TR>
<TR><TD ALIGN="LEFT">TossimInitEvent</TD>
<TD ALIGN="LEFT">When Tython connects to TOSSIM</TD>
</TR>
<TR><TD ALIGN="LEFT">UARTMsgSentEvent</TD>
<TD ALIGN="LEFT">When a mote finishes sending a UART packet</TD>
</TR>
</TABLE>

<A NAME="table:events"></A></DIV></TD></TR>
</TABLE>
</DIV><P></P>
<BR>

<P>
Event handlers can be useful for waiting for a condition, or for
logging information. For example, if you want to examine why a mote
sends a specific (perhaps malformed) packet, you can register a
handler for send events, and when the handler detects the packet,
pause TOSSIM.


<P>

<H2><A NAME="sec:future_actions"></A>
<BR>
Future Actions
</H2>

<P>
Most of the events described in the previous section are issued when a
mote performs a certain action, or when the user makes an action in
the TinyViz GUI. TOSSIM also provides a command for external programs
to receive a callback in the future, the <TT>InterruptEvent</TT>. The
method <TT>sim.interruptInFuture()</TT> command sends a command to
TOSSIM which schedules an <TT>InterruptEvent</TT> at a designated time
(in 4MHz simulator ticks). The command also takes an integer ID as a
parameter, which is then used to distinguish between the
InterruptEvents that fire. The <TT>sim.getInterruptID()</TT> API
function can be used to get a unique id.

<P>
Here is an example use of these pause events, in this case where a
user wants to print out mote state one minute into simulation:

<P>
<PRE>
import simcore
from net.tinyos.sim.event import InterruptEvent

id = simcore.interp.getInterruptID()

def time_handler(event):
  global id
  if event.get_id() == id:
    print "Printing motes 1-20"
    for i in range(0, 20):
      print motes[i]

simcore.interp.addEventHandler(time_handler, InterruptEvent)
simcore.interp.interruptInFuture(60 * 4000000, id)
</PRE>

<P>
To help manage some of the event and id bookkeeping, the
<TT>simutil</TT> package provides a simpler python class interface to
accomplish the same task:

<P>
<PRE>
import simutil, simtime

def time_handler():
  print "Printing motes 1-20"
  for i in range(0, 20):
    print motes[i]

simutil.CallIn(simtime.onemin, time_handler);
</PRE>

<P>
In this example, <TT>CallIn</TT> is a simple python class that manages
the pause and event identifiers. Besides the constructor method that
schedules the callback, it also exports a <TT>cancel()</TT> method,
which allows a script to nullify a previously scheduled action.

<P>
In addition, note that the first parameter to <TT>simutil.CallIn</TT>
uses the <TT>simtime</TT> module, specifically the <TT>onemin</TT>
constant. <TT>simtime</TT> is a simple module that has predefined
constants and conversion functions for manipulating 4MHz simulator
clock ticks. Also, the first parameter to <TT>CallIn</TT>is an offset
from the current time, so the above call will occur one minute in the
future. This is in contrast to both <TT>interp.interruptInFuture</TT>
and the simple wrapper <TT>simutil.CallAt</TT> which both take a
absolute time value.

<P>

<H2><A NAME="sec:periodic_actions"></A>
<BR>
Periodic Actions
</H2>

<P>
The <TT>InterruptEvent</TT> interface is the primary means by which a
script can schedule actions. Event handlers can also be made to
reschedule themselves for periodic actions. For example, a simple
change to the previous handler will cause the mote state to be printed
every minute instead of only once:

<P>
<PRE>
def time_handler(event):