$ ./configure
$ ./make
$ ./make install
</PRE>
<P>Then type <CODE>tos-install-jni</CODE>. This should install serial support in 
your system. </P><A name=MOTECOM></A>
<H2><SPAN class=mw-headline>MOTECOM</SPAN></H2>
<P>If you do not pass a <CODE>-comm</CODE> parameter, then tools will check the 
<CODE>MOTECOM</CODE> environment variable for a packet source, and if there is 
no <CODE>MOTECOM</CODE>, they default to a SerialForwarder. This means that if 
you're always communicating with a mote over your serial port, you can just set 
<CODE>MOTECOM</CODE> and no longer have to specify the <CODE>-comm</CODE> 
parameter. For example: </P><PRE>export MOTECOM=serial@COM1:19200 # mica baud rate
export MOTECOM=serial@COM1:mica  # mica baud rate, again
export MOTECOM=serial@COM2:mica2 # the mica2 baud rate, on a different serial port
export MOTECOM=serial@COM3:57600 # explicit mica2 baud rate
</PRE>
<P>Try setting your MOTECOM variable and running TestSerial without a 
<CODE>-comm</CODE> parameter. </P><A 
name=BaseStation_and_net.tinyos.tools.Listen></A>
<H1><SPAN class=mw-headline>BaseStation and net.tinyos.tools.Listen</SPAN></H1>
<P><CODE>BaseStation</CODE> is a basic TinyOS utility application. It acts as a 
bridge between the serial port and radio network. When it receives a packet from 
the serial port, it transmits it on the radio; when it receives a packets over 
the radio, it transmits it to the serial port. Because TinyOS has a toolchain 
for generating and sending packets to a mote over a serial port, using a 
BaseStation allows PC tools to communicate directly with mote networks. </P>
<P>Take one of the two nodes that had BlinkToRadio (from <A 
title="Mote-mote radio communication" 
href="http://docs.tinyos.net/index.php/Mote-mote_radio_communication">lesson 
3</A>) installed and install BaseStation on it. If you turn on the node that 
still has BlinkToRadio installed, you should see LED 1 on the BaseStation 
blinking. BaseStation toggles LED 0 whenever it sends a packet to the radio and 
LED 1 whenever it sends a packet to the serial port. It toggles LED 2 whenever 
it has to drop a packet: this can happen when one of the two receives packets 
faster than the other can send them (e.g., receiving micaZ radio packets at 
256kbps but sending serial packets at 57.6kbps). </P>
<P>BaseStation is receiving your BlinkToRadio packets and sending them to the 
serial port, so if it is plugged into a PC we can view these packets. The Java 
tool Listen is a basic packet sniffer: it prints out the binary contents of any 
packet it hears. Run Listen, using either MOTECOM or a -comm parameter: </P><PRE>$ java net.tinyos.tools.Listen
</PRE>
<P>Listen creates a packet source and just prints out every packet it sees. Your 
output should look something like this: </P><PRE>00 FF FF 00 00 04 22 06 00 02 00 01
00 FF FF 00 00 04 22 06 00 02 00 02
00 FF FF 00 00 04 22 06 00 02 00 03
00 FF FF 00 00 04 22 06 00 02 00 04
00 FF FF 00 00 04 22 06 00 02 00 05
00 FF FF 00 00 04 22 06 00 02 00 06
00 FF FF 00 00 04 22 06 00 02 00 07
00 FF FF 00 00 04 22 06 00 02 00 08
00 FF FF 00 00 04 22 06 00 02 00 09
00 FF FF 00 00 04 22 06 00 02 00 0A
00 FF FF 00 00 04 22 06 00 02 00 0B
</PRE>
<P>Listen is simply printing out the packets that are coming from the mote. Each 
data packet that comes out of the mote contains several fields of data. The 
first byte (00) indicates that this is packet is an AM packet. The next fields 
are the generic Active Message fields, defined in 
<TT>tinyos-2.x/tos/serial/Serial.h</TT>. Finally, the remaining fields are the 
data payload of the message, which was defined in BlinkToRadio.h as: </P><PRE>typedef nx_struct BlinkToRadioMsg {
  nx_uint16_t nodeid;
  nx_uint16_t counter;
} BlinkToRadioMsg;
</PRE>
<P>The overall message format for the BlinkToRadioC application is therefore 
(ignoring the first 00 byte): </P>
<UL>
  <LI><B>Destination address</B> (2 bytes) 
  <LI><B>Link source address</B> (2 bytes) 
  <LI><B>Message length</B> (1 byte) 
  <LI><B>Group ID</B> (1 byte) 
  <LI><B>Active Message handler type</B> (1 byte) 
  <LI><B>Payload</B> (up to 28 bytes): 
  <UL>
    <LI><B>source mote ID</B> (2 bytes) 
    <LI><B>sample counter</B> (2 bytes) </LI></UL></LI></UL>
<P>So we can interpret the data packet as follows: </P>
<TABLE cellSpacing=10>
  <TBODY>
  <TR bgColor=#d0d0d0>
    <TD><B>dest addr</B> </TD>
    <TD><B>link source addr</B> </TD>
    <TD><B>msg len</B> </TD>
    <TD><B>groupID</B> </TD>
    <TD><B>handlerID</B> </TD>
    <TD><B>source addr</B> </TD>
    <TD><B>counter</B> </TD></TR>
  <TR>
    <TD bgColor=#d0d0ff>ff ff </TD>
    <TD bgColor=#d0d0ff>00 00 </TD>
    <TD bgColor=#d0d0ff>04 </TD>
    <TD bgColor=#d0d0ff>22 </TD>
    <TD bgColor=#d0d0ff>06 </TD>
    <TD bgColor=#d0ffd0>00 02 </TD>
    <TD bgColor=#d0ffd0>00 0B </TD></TR></TBODY></TABLE>
<P>The link source address and source address field differ in who sets them. The 
serial stack does not set the link source address; for Blink, it should always 
be <B>00 00</B>. Blink sets the source address to be the node's ID, which 
depends on what mote ID you installed your BlinkToRadio application with. The 
default (if you do not specify and ID) is <CODE>00 01</CODE>. Note that the data 
is sent by the mote in <I>big-endian</I> format; for example, <CODE>01 02</CODE> 
means 258 (256*1 + 2). This format is independent of the endian-ness of the 
processor, because the packet format is an <CODE>nx_struct</CODE>, which is a 
network format, that is, big-endian and byte-aligned. Using 
<CODE>nx_struct</CODE> (rather than a standard C <CODE>struct</CODE>) for a 
message payload ensures that it will work across platforms. </P>
<P>As you watch the packets scroll by, you should see the counter field increase 
as the BlinkToRadio app increments its counter. </P><A 
name=MIG:_generating_packet_objects></A>
<H1><SPAN class=mw-headline>MIG: generating packet objects</SPAN></H1>
<P>The <TT>Listen</TT> program is the most basic way of communicating with the 
mote; it just prints binary packets to the screen. Obviously it is not easy to 
visualize the sensor data using this program. What we'd really like is a better 
way of retrieving and observing data coming from the sensor network. Of course, 
exactly what data to display and how to visualize it can be very application 
specific. For this reason, TinyOS only has a few applications for visualizing 
simple sensor data (in the next lesson, you'll use the Oscilloscope 
application), but it provides support for building new visualization or logging 
systems. </P>
<P>One problem with Listen is that it just dumps binary data: a user has to be 
able to read the bytes and parse them into a given packet format. The TinyOS 
toolchain makes this process easier by providing tools for automatically 
generating message objects from packet descriptions. Rather than parse packet 
formats manually, you can use the <CODE>mig</CODE> (Message Interface Generator) 
tool to build a Java, Python, or C interface to the message structure. Given a 
sequence of bytes, the MIG-generated code will automatically parse each of the 
fields in the packet, and it provides a set of standard accessors and mutators 
for printing out received packets or generating new ones. </P>
<P>The mig tool takes three basic arguments: what programming language to 
generate code for (Java, Python, or C), which file in which to find the 
structure, and the name of the structure. The tool also takes standard C 
options, such as -I for includes and -D for defines. The TestSerial application, 
for example, uses mig so that it can easily create and parse the packets over 
the serial port. If you go back to TestSerial and type <CODE>make 
clean;make</CODE>, you should see this: </P><PRE>rm -rf build *.class TestSerialMsg.java
rm -rf _TOSSIMmodule.so TOSSIM.pyc TOSSIM.py
mkdir -p build/telosb
mig java -target=telosb -I%T/lib/oski -java-classname=TestSerialMsg TestSerial.h TestSerialMsg 
-o TestSerialMsg.java
javac *.java
    compiling TestSerialAppC to a telosb binary
ncc -o build/telosb/main.exe -Os -O -mdisable-hwmul -Wall -Wshadow -DDEF_TOS_AM_GROUP=0x66 
-Wnesc-all -DCC2420_DEF_CHANNEL=19 -target=telosb -fnesc-cfile=build/telosb/app.c 
-board= -I%T/lib/oski  TestSerialAppC.nc -lm
    compiled TestSerialAppC to build/telosb/main.exe
            6300 bytes in ROM
             281 bytes in RAM
msp430-objcopy --output-target=ihex build/telosb/main.exe build/telosb/main.ihex
    writing TOS image
</PRE>
<P>Before building the TinyOS application, the Makefile has a rule for 
generating <CODE>TestSerialMsg.java</CODE>. It then compiles TestSerialMsg.java 
as well as TestSerial.java, and finally compiles the TinyOS application. Looking 
at the Makefile, we can see that it has a few more rules than the one for 
BlinkToRadio: </P><PRE>COMPONENT=TestSerialAppC
BUILD_EXTRA_DEPS += TestSerial.class
CLEAN_EXTRA = *.class TestSerialMsg.java

TestSerial.class: $(wildcard *.java) TestSerialMsg.java
        javac *.java

TestSerialMsg.java:
        mig java -target=null -java-classname=TestSerialMsg TestSerial.h TestSerialMsg -o $@

include $(MAKERULES)
</PRE>
<P>The <CODE>BUILD_EXTRA_DEPS</CODE> line tells the TinyOS make system that the 
TinyOS application has additional dependencies that must be satisfied before it 
can be built. The Makefile tells the make system that 
<CODE>TestSerial.class</CODE>, the Java application that we ran to test serial 
communication. The <CODE>CLEAN_EXTRA</CODE> line tells the make system extra 
things that need to be done when a user types <CODE>make clean</CODE> to clean 
up. </P>
<P>The <CODE>BUILD_EXTRA_DEPS</CODE> line tells make to compile TestSerial.class 
before the application; the line </P><PRE>TestSerial.class: $(wildcard *.java) TestSerialMsg.java
        javac *.java
</PRE>
<P>tells it that TestSerial.class depends on all of the .java files in the 
directory as well as TestSerialMsg.java. Once all of these dependencies are 
resolved, the make system will call <CODE>javac *.java</CODE>, which creates 
TestSerial.class. The final line, </P><PRE>TestSerialMsg.java:
        mig java -target=null -java-classname=TestSerialMsg TestSerial.h TestSerialMsg -o $@
</PRE>
<P>tells the make system how to create TestSerialMsg.java, the Java class 
representing the packet sent between the mote and PC. Because TestSerialMsg.java 
is a dependency for TestSerial.class, make will create it if it is needed. To 
create TestSerialMsg.java, the Makefile invokes the mig tool. Let's step through 
the parameters one by one: </P>
<TABLE>
  <TBODY>
  <TR>
    <TD>mig </TD>
    <TD>Invoke mig </TD></TR>
  <TR>
    <TD>java </TD>
    <TD>Build a Java class </TD></TR>
  <TR>
    <TD>-target=null </TD>
    <TD>For the <CODE>null</CODE>platform </TD></TR>
  <TR>
    <TD>-java-classname=TestSerialMsg </TD>
    <TD>Name the Java class TestSerialMsg </TD></TR>
  <TR>
    <TD>TestSerial.h </TD>
    <TD>The structure is in TestSerial.h </TD></TR>
  <TR>
    <TD>TestSerialMsg </TD>
    <TD>The structure is named TestSerialMsg </TD></TR>
  <TR>
    <TD>-o $@ </TD>
    <TD>Write the file to $@, which is TestSerialMsg.java </TD></TR></TBODY></TABLE>
<P>The <CODE>null</CODE> platform is a special platform which is convenient to 
use as the target when using <CODE>mig</CODE>. It includes all the standard 
system components, but with dummy do-nothing implementations. Building an 
application for the <CODE>null</CODE> platform is useless, but it allows 
<CODE>mig</CODE> to extract the layout of packets. </P>
<P>Let's build a Java packet object for BlinkToRadio. Open the Makefile for 
BlinkToRadio and add a dependency: </P><PRE>BUILD_EXTRA_DEPS=BlinkToRadioMsg.class
</PRE>
<P>Then add a step which explains how to compile a .java to a .class: </P><PRE>BlinkToRadioMsg.class: BlinkToRadioMsg.java
        javac BlinkToRadioMsg.java
</PRE>
<P><B>Note that there must be a tab before javac, and not just spaces.</B> 
Finally, add the line which explains how to create BlinkToRadioMsg.java: </P><PRE>BlinkToRadioMsg.java:
        mig java -target=null -java-classname=BlinkToRadioMsg BlinkToRadio.h BlinkToRadioMsg -o $@
</PRE>
<P>As with javac, there must be a tab (not spaces) before mig. Now, when you 
type <CODE>make</CODE> in <CODE>BlinkToRadio/</CODE>, the make system will 
compile BlinkToRadioMsg.class, a Java class that parses a binary packet into 
message fields that can be accessed through methods. </P>
<P>There is one more step, however. When you compiled, you probably saw this 
warning: </P><PRE>warning: Cannot determine AM type for BlinkToRadioMsg
         (Looking for definition of AM_BLINKTORADIOMSG)
</PRE>
<P>One part of the TinyOS communication toolchain requires being able to figure 
out which AM types correspond to what kinds of packets. To determine this, for a 
packet type named X, mig looks for a constant of the form <CODE>AM_X</CODE>. The 
warning is because we defined our AM type as AM_BLINKTORADIO, but mig wants 
AM_BLINKTORADIOMSG. Modify BlinkToRadio.h so that it defines the latter. You'll 
also need to update BlinkToRadioAppC.nc so that the arguments to AMSenderC and 
AMReceiverC use it. Recompile the application, and you should see no warning. 
Install it on a mote. </P>
<P>Now that we have a Java message class, we can use it to print out the 
messages we see from the BaseStation. With BaseStation plugged into the serial 
port and BlinkToRadio running on another mote, from the BlinkToRadio directory 
type </P><PRE>java net.tinyos.tools.MsgReader BlinkToRadioMsg
</PRE>
<P>Now, when the BaseStation sends a packet to the serial port, MsgReader reads 
it, looks at its AM type, and if it matches the AM type of one of the Java 
message classes passed at the command line, it prints out the packet. You should 
see output like this: </P><PRE>1152232617609: Message
  [nodeid=0x2]
  [counter=0x1049]

1152232617609: Message
  [nodeid=0x2]
  [counter=0x104a]

1152232617609: Message
  [nodeid=0x2]
  [counter=0x104b]

1152232617621: Message
  [nodeid=0x2]
  [counter=0x104c]
</PRE><A name=SerialForwarder_and_other_packet_sources></A>
<H1><SPAN class=mw-headline>SerialForwarder and other packet sources</SPAN></H1>
<P>One problem with directly using the serial port is that only one PC program 
can interact with the mote. Additionally, it requires you to run the application 
on the PC which is physically connected to the mote. The SerialForwarder tool is 
a simple way to remove both of these limitations. </P>
<P>Most generally, the <TT>SerialForwarder</TT> program opens a packet source