manual.html

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

</H2>

<P>
The previous examples of Tython scripting assumed the use of the
console. While appropriate for interactive use, this is cumbersome for
repeated actions.

<P>
The builtin <tt>execfile</tt> command can be used to source a file and
execute the contents as Tython commands:

<PRE>
>>> execfile("myscript.py")
</PRE>

<P>
This will read and execute the contents of the specified file. As an
alternative, passing the command line argument <tt>-script</tt> to
Tython will cause it to automatically source and execute the named
script file. For example:

<PRE>
java net.tinyos.sim.SimDriver -script "myscript.py"
</PRE>

<HR>
<H1><A NAME="sec:caffeinated_snake">
The Caffeinated Snake</A>
</H1>

<P>
Jython's Java support allows a user to basically use it as a Java
scripting language. It also provides the basic features of the Python
environment, including builtin functions and data structures.


<H2><A NAME="sec:exploring_objects">
Exploring Objects</A>
</H2>

<P>
As mentioned previously, the <tt>simcore</tt> module provides the
basic access to the simulator interactions. The builtin Python
<TT>dir()</TT> function is a useful hook to see the set of functions
an object provides. First, type the name of the object:

<P>
<PRE>
>>> from simcore import *
>>> sim
net.tinyos.sim.script.reflect.Sim@5f3a5f53
</PRE>

<P>
This tells you that the <TT>sim</TT> object is actually an instance of
the <TT>net.tinyos.sim.script.reflect.Sim</TT> Java class. To see the
variables and functions a <TT>Sim</TT> object provides, type
<TT>dir(Sim)</TT>.

<P>
<PRE>
>>> dir(Sim)
['__driver', 'argv', 'dumpDBG', 'exec', 'exit', 'getTossimTime', 'getWorldHeight', 'getWorldWidth', 'isPaused', 'pause', 'paused', 'reset', 'resume', 'setSimDelay', 'simDelay', 'stop', 'stopDBGDump', 'tossimTime', 'worldHeight', 'worldWidth']
</PRE>

<P>
<TT>dir()</TT> can be used on both Java and Python objects. For
example, <TT>dir(Sim)</TT> returns a Python list of strings, with each
element being a method or attribute of the Sim class. So,
<TT>dir(dir(Sim))</TT> lists the functions a Python list object
provides:

<P>
<PRE>
>>> dir(dir(sim))
['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']
</PRE>

<P>
Note that <TT>dir()</TT>'s semantics are slightly different for Python
and Java. One can call <TT>dir()</TT> on a Python object to learn its
functions, but for Java, one must call it on the class. Specifically:

<P>
<PRE>
>>> sim
net.tinyos.sim.script.reflect.Sim@5f3a5f53
>>> dir(sim)
[]
>>> dir(Sim)
['__driver', 'argv', 'dumpDBG', 'exec', 'exit', 'getTossimTime', 'getWorldHeight', 'getWorldWidth', 'isPaused', 'pause', 'paused', 'reset', 'resume', 'setSimDelay', 'simDelay', 'stop', 'stopDBGDump', 'tossimTime', 'worldHeight', 'worldWidth']
>>> m = dir(Sim)
>>> dir(m) 
['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']
</PRE>

<P>
Calling <TT>dir()</TT> with no parameters lists the set of variables,
functions, and modules currently bound in the Jython environment:

<P>
<PRE>
>>> dir()
['Commands', 'Interp', 'Location', 'Mote', 'Motes', 'PacketType', 'Packets', 'Radio', 'Sim', 
'SimBindings', 'SimReflect', '__doc__', '__driver', '__name__', 'comm', 'interp', 'location', 
'motes', 'packets', 'radio', 'sim', 'simcore', 'sys']
</PRE>

<P>
Finally, calling <TT>dir()</TT> on a module lists the set of objects
and functions exposed by that module.
</P>

<PRE>
>>> import simcore
>>> dir(simcore)
['Commands', 'Interp', 'Motes', 'Packets', 'Radio', 'Sim', '__doc__', '__name__', 'comm', 'interp', 'motes', 'packets', 'radio', 'sim']
</PRE>

<H2><A NAME="sec:importing_java">
Importing and Instantiating Java</A>
</H2>

<P>
Jython allows you to import Java classes with Python's import syntax.
For example, to import <TT>java.util.Enumeration</TT>, or the entire
<TT>java.util</TT> package:

<P>
<PRE>
>>> from java.util import Enumeration
>>> from java.util import *
</PRE>

<P>
Python is a dynamically typed language. Therefore, variables do not
have type specifiers. While instantiating a <TT>StringBuffer</TT> in
Java looks like this:

<P>
<dt><em>(Note: from now on, Tython code will be shown as if it were in a
file, that is, without a command line prompt. Each line could be just
as easily typed into a console)</em></dt>

<P>
<PRE>
StringBuffer buffer = new StringBuffer();
</PRE>

<P>
in Jython it looks like this,

<P>
<PRE>
buffer = StringBuffer()
</PRE>

<P>
Note, however, that Jython does not automatically import
<TT>java.lang.*</TT>.

<P>
By importing Java classes, one can access the TinyOS Java toolchain:

<P>
<PRE>
from net.tinyos.message import *
from net.tinyos.packet import *

moteIF = MoteIF()
msg = BaseTOSMsg()
msg.set_addr(0)
msg.set_type(5)
moteIF.send(0, msg)
</PRE>

<P>
The above code will send a message of AM type 5 to mote 0 over the
default MoteIF interface.

<P>
Access to the toolchain includes GUI-based programs. For example, one
can instatiate a SerialForwarder:

<P>
<PRE>
from net.tinyos.sf import *
s = SerialForwarder([])
</PRE>

<P>
Note, however, that some classes (SerialForwader's GUI among them)
expect to be stand-alone applications. This means that when you tell
them to quit, with the quit button, for example, they may cause the
entire Jython environment to quit.

<H2><A NAME="sec:java_vs_python">
Java vs. Python</A>
</H2>

<P>
Given that all Java objects are accessible through the python
interface, in many cases there is redundancy between the two
languages, and there is more than one interface available for a given
programming task.

<P>
Being dynamically typed, the Jython environment loses many of the
correctness benefits of the Java compilation process. For objects such
as strings, lists, and maps, it's often easier to use Python's
primitives instead of Java's, as they are syntactically built into the
language. For example, compare the use of a Python map and a Java
hashtable:

<P>
<PRE>
# Java
from java.util import *
h = new Hashtable()
h.put("Seed", getPacket())
print(h.get("Seed"))

# Python
h = {}
h["Seed"] = getPacket()
print h["Seed"]
</PRE>

<P>
Similarly, one can use either Java or Python to write a file:

<P>
<PRE>
# Java
from java.io import *
file = FileWriter("output.txt")
file.write(packets[0])

# Python
file = open("output.txt", "w")
file.write(packets[0])
</PRE>

<P>
We've found that, for data collection and processing, the Python
idioms are generally easier to use than Java. Among other things, its
data structure primitives end up being a lot simpler and less error
prone. However as mentioned previously, Java allows you to interact
with all of the existing structure a TinyOS distribution provides,
such as packet sources, message class generation, and interaction with
TinyViz.

<H2><A NAME="sec:packets"></A>
<BR>
The Packet History Structure
</H2>

<P>
Much of the power of the Tython environment comes from the synergy
between the two languages. Specifically, the use of Java to implement
internal functionality, while presenting a Python interface for
scripts.

<P>
The <TT>packets</TT> variable in the <tt>simcore</tt> module is an
example of this. This data structure allows scripts to access all of
the packets that motes have transmitted. The variable is a dictionary
of lists, keyed by mote ID. Each list contains all of the packets a
given mote has sent, in temporal order (the first packet is the first
element of the list).

<P>
<PRE>
print packets[3]
</PRE>

<P>
will print all of the packets mote 3 has sent. 

<P>Each element of a given list is a Java instance of
<TT>net.tinyos.sim.event.RadioMsgSentEvent</TT>. This class is used
because it stores not only the message sent, but also metadata, such
as time. The time represents when the packet send <I>completed</I>,
not when it began.

<P>
<TT>RadioMsgSentEvent</TT> has three basic accessor functions:
<TT>getMessage()</TT>, which returns a
<TT>net.tinyos.message.TOSMsg</TT>, <TT>getMoteID()</TT>, which
returns the sender's ID, and <TT>getTime()</TT>, which returns the
send time.

<P>
<TT>packets</TT> is an immutable object; unlike normal dictionaries, a
script cannot assign to it. If a script needs to transform the packet
dictionary, it can make a copy with <TT>packets.copy()</TT>, which is
a normal Python dictionary and can be modified accordingly.

<P>
In addition to normal dictionary operations, <TT>packets</TT> has an
extra function to support TinyOS messages, <TT>addPacketType(Message
message)</TT>. This function can create packet type specific
reflections of <TT>packets</TT>. For example,

<P>
<PRE>
from net.tinyos.message import IntMsg
packets.addPacketType(IntMsg())
</PRE>

<P>
will create a new variable in the Tython environment,
<TT>IntMsgs</TT>, which contains all of the messages in
<TT>packets</TT> that are of type <TT>IntMsg</TT>, as defined by
active message type. This variable, <TT>IntMsgs</TT>, can be indexed
and accessed just as <TT>packets</TT> is.

<P>
Note, however, that each element in the <TT>packets</TT> lists
contains a <TT>TOSMsg</TT>; this means that in the above example,
<TT>IntMsgs</TT> also has <TT>TOSMsgs</TT>; you cannot easily
manipulate the elements as if they were actually instances of
<TT>IntMsg</TT>, by accessing their message type specific fields, etc.

<P>
In order to transform the <TT>IntMsgs</TT> into a dictionary of
<TT>net.tinyos.message.IntMsg</TT>, you must call
<TT>IntMsgs.downCast()</TT>. For example:

<P>
<PRE>
from net.tinyos.msg import IntMsg
packets.addPacketType(IntMsg())

# Get a dictionary of IntMsgs, instead of TOSMsgs
myMsgs = IntMsgs.downCast()
# Print the value in the first IntMsg that mote 0 transmitted
print myMsgs[0].pop().get_val()
</PRE>

<P>
Using a <TT>downCast()</TT> dictionary allows you to easily access
message fields. However, it discards the additional metadata (such as
transmit time) that a <TT>RadioMsgSentEvent</TT> contains.

<P>
The variable defined by <TT>addPacketType()</TT> will update as more
motes send packets; it represents a filter on top of <TT>packets</TT>.
The dictionary returned by <TT>downCast()</TT>, however, is static; it
does not update as more motes send packets.