Getting up and running with TinyOS

Get a copy of the TinyOS source.

October 19, 2001, 12:15pm: Updated distribution, tos-0.5.1 has been released. The release contains several bug fixes in the documentation, enhanced simulator, and includes several files omitted from the o.5 distribution.

This download is set up to run under a Linux/Unix based environment.  The Makefiles assume that the avr-gcc compilers are installed in the current path. If you place them differently (e.g. don't set your PATH under Windows, or /usr/local/bin isn't in your Linux PATH), you should either change your path variable or provide absolute paths for the avr tools.

Next, you will have to acquire a copy of the avr-gcc tools (and windows development tools).

1. If you are running under Linux, a set of binaries can be obtained: dist/atmeltools.tar.gz.  For these binaries to work, you must install them into /usr/local/avr/bin and /usr/local/bin.  Otherwise the compiler will not be able to find required components.  (the full path of avr-gcc should be /usr/local/bin/avr-gcc)   You should add /usr/local/bin to you path.  Additionally, we assume that you have Perl and a native C compiler already installed. Extract the tar file in the root directory on your machine(/) and the files will be placed in the right location.

2. Check your avr installation. Type avr-gcc in a shell. If the avr tools are in your path, you should see the error message "no input files," and everything is set up correctly. If avr-gcc is not in your path, you'll see a message such as "Command not found." Check that /usr/local/bin is in your PATH variable with printenv PATH. If it's not, you'll have to add it. Don't forget that you need to open a new shell for your modified shell init script (e.g. .tcshrc, .bashrc) to be read.

3. You also need to download and install the java.comm libraries for linux.  If you are on the Berkeley network, you can download the javax.comm rpm's from release/linux-jdk.  If you are not on the Berkeley network you must register a login at IBM's Linux developer site to download the package. CAREFULLY follow the directions provided with IBM's javax.comm distribution to install it (refer to step 9 if you have trouble). Be sure to add the IBM Java bin directory to your path (/opt/IBMJava2-3/bin). Note that it places the javax.comm libraries and files in /opt.

   If you need to install Java proper (not just the javax.comm package), you can find the recommended version at IBM.

4. There is also a new version of uisp for programming the motes. Download it, expand the archive, and read the instructions for installation. You should check the permissions of the final executable in /usr/local/bin; it should be rwsr-xr-x. It must be setuid root.

5. Install the TinyOS distribution.

Windows:

1. Log in as Administrator. Some programs you'll use (such as tvicport) can only be run by Administrator (or someone with Administrator priviledges).

   
   

2. The first step is to install the cygwin development tools that provide UNIX-like (shells, etc.) functionality under Windows.  Download this ZIP archive that contains a full release. Run the Setup program in the top-level directory. Here are the installation setup choices we recommend:
   • Install from a local folder.
     
   • Specify the location of the files for the install (the default should work, unless you moved Setup).
     
   • Configure: install for "all" and file type UNIX, with c:\cygwin as the final loccation.
     
   • Packages: Accept the defaults. This should install all the files and leave you with a cygwin icon on the desktop. For the remainder of these instructions, we'll assume you installed  cygwin into c:\cygwin\.
     

3. Now that you have a UNIX-like environment, you need to install the development tools (compilers, linkers, etc.) for the Atmel microcontrollers on the motes.   Download and run   avrgcc20010211.exe from within Windows (not the cygwin shell). It will install the avr compiler and the bin-utils. Towards the end of the process you will get an error message: Access Is Denied: outreset.  Click OK and a console window will pop up and perform the installation of the compiler and libraries. This will run for several seconds.  It is OK to receive this single error message as long at it continues to install  (several hundred lines of commands will go by).

 
4. You need to set your environment variables so the $(AVRGCC_INSTALL)\bin directory is in your path.  This will be the directory you extracted the compiler to plus \bin, typically c:\avrgcc\bin.  Under Windows 2000,  accomplish this by right-clicking on My Computer, choosing Properties, going to the Advanced tab, selecting Environment Variables,  finding the "Path" variable in the lower window and then editting it, appending ";c:\avrgcc\bin" to the entry.
5. To confirm that you have done this correctly, OPEN UP A NEW Windows command prompt and type avr-gcc.  You should get "avr-gcc: No input files", not "'avr-gcc' is not recognized as an internal or external command,"
   If you open up a cygwin shell you can type echo $PATH.  You will see that it has converted your windows paths to valid cygwin paths.  If avr-gcc is not on the path you will get an error like bash: avr-gcc: command not found.  You will need to use the Cygwin shell to run make.
6. In addition, the default version of uisp you now have has a few problems. Download a new version of uisp to somewhere where you can easily access it via cygwin. This file contains the program source. In a cygwin shell, expand the tarball and follow the instructions in INSTALL. You should check the permissions on the uisp executable in /usr/local/bin; it should be rwxr-xr-x

7. To read from the serial port you have to download and install the 1.3 JDK and the javax.comm package. The former can be found at http://java.sun.com/j2se/1.3/ and the latter can be found at http://java.sun.com/products/javacomm/.    Unpack both of these packages and then install the JDK.  Extracting javacomm will create a comapi directory containing instructions for installing it in the jdk.  Be careful to follow the instructions contained in the commapi\Readme.html file; there are a few tricky configuration requirements.  This file tells you how to copy several of the commapi files into the JDK installation directory.  MAKE SURE THIS IS DONE. You will want to create a CLASSPATH environment variable (with the same procedure as above for your PATH variable) and make sure that comm.jar and . are both on the path. For example:

   C:\jdk1.3.1\lib\comm.jar;.

   If the JDK install complains about insufficent disk space when your machine has plenty, you're experiencing a bug in the installer. This bug occurs if your disk space is just over a multiple of 4GB. The installer seemingly uses a 32-bit value to examine the available space, so if you have 4GB + 100K, it thinks you only have 100K. Create a large file (~100MB) and the problem should go away. If not, Sun has instructions This large file can be created in cygwin with the following command:

   touch /tmp/big_file;for (( i=0;i<100;i++ )) cat /usr/lib/libc.a >> /tmp/big_file; done;

   Be sure to remove /tmp/big_file when the install completes.

8. After you've created the variable, OPEN A NEW cygwin shell and type echo $CLASSPATH; check to make sure it includes both entries.

9. Install the TOS distribution.  Finally.  Cygwin creates a UNIX like structure rooted at the place where you installed it,  containing /usr, /home and all the other expect directories..  You may want to install TOS into that tree.  Alternatively, you can get to anything on the C drive using the directions below.

Cygnus shell info: First off, for those of you not familiar with Cygnus Cygwin shell, to get to your C drive type "cd /cygdrive/c" at the command prompt. You can then cd to the directory where you installed the TOS release. Alternatively, cd .. till you get to / and look around.

DOS text file format and weird errors: Often when you save a file using a regular windows text editor it saves the file in DOS mode, meaning that each text line is terminated by CR/LF. The tools which munge the description files are quite sensitive to this type of problem. We recommend that you download the dos2unx program available here and run the appropriate description/component files if you run into unexpected compilation problems.

Compile your first program

You should now have all that it takes to compile and install your first program.  Enter the apps/cnt_to_leds directory using your shell (cygwin under Windows); it's a good application to make sure that the most basic hardware is working. Type make rene in the shell. This should complete successfully and create a binary image of your program for the rene motes. You can ignore the warning about "Makefile.objs" at the beginning.

Downloading Programs to the Device

To transfer that image to an actual device, connect your programming board to the parallel port. The switch on the board should be towards the "Big_Guy" label, away from the parallel port. Power the mote and type 'make rene install'.  If you are using windows and the install doesn't work, you make need to fiddle with the port specified to uisp; depending on the hardware, cygwin can map parallel ports to wildly different names (use the -dlpt= option). You should see the upload take place (this will take 2 minutes or so) and the leds should be blinking.

If you're using an IBM Thinkpad and having trouble downloading rprograms, you'll probably need to go into the apps directory and modify Makeinclude. Halfway through the file is a commented out line that defines HOST to THINKPAD. Uncomment this line. Basically, the communication ports are named differently, and uisp needs to be told to use a different port (-dlpt=3).

Try running the simulator

If you get the following compilation error:

BLINK.o(.text+0x7): undefined reference to `BLINK_LEDy_off_COMMAND'
BLINK.o(.text+0xc): undefined reference to `BLINK_LEDr_off_COMMAND'
BLINK.o(.text+0x11): undefined reference to `BLINK_LEDg_off_COMMAND'
BLINK.o(.text+0x56): undefined reference to `BLINK_LEDy_on_COMMAND'
BLINK.o(.text+0x5d): undefined reference to `BLINK_LEDy_off_COMMAND'
BLINK.o(.text+0x67): undefined reference to `BLINK_LEDg_on_COMMAND'
BLINK.o(.text+0x71): undefined reference to `BLINK_LEDg_off_COMMAND'
BLINK.o(.text+0x7b): undefined reference to `BLINK_LEDr_on_COMMAND'
BLINK.o(.text+0x85): undefined reference to `BLINK_LEDr_off_COMMAND'
system/CLOCK.o(.text+0x43): undefined reference to `CLOCK_NULL_FUNC_EVENT'
system/MAIN.o(.text+0xcb): undefined reference to `MAIN_SUB_INIT_COMMAND'
system/MAIN.o(.text+0xd0): undefined reference to `MAIN_SUB_START_COMMAND'
collect2: ld returned 1 exit status
make: *** [main] Error 1

Then your files ended up in a DOS format instead of a UNIX format.  This can occur if winzip was used to extract the TinyOS release.  To fix the problem, you can use the extractor that came with cygnus.  Place the TinyOS release in a directory by itself.  Go to the cygnus prompt and cd to that directory.  Run:

tar xvfz tos-latest.tar.gz
cd tos5.0/apps/cnt_to_leds
make clean
make

Hopefully that will fix the problem.

When it is finished run "./binpc/main 1"  This will run a single TinyOS mote.  You should see a tremendous deluge of debugging information, ranging from clock interrupts to LED output to simulator internals. The output the simulator provides can be set with the DBG environment variable. The default value is "all". For a listing of the available debugging modes, type ./binpc/main -h. You can choose modes by setting your DBG environment variable to be a string delimited set of modes. For example, export DBG=clock,route in bash would enable output pertaining to clock events and the network routing layer used, if any. To see the LED output, set DBG to be led (export DBG=led).

After setting DBG, type ./binpc/main 1. You'll see LED output streaming by at a rate too fast to understand; the simulator is running your program much more quickly than it would in real life. For this reason, the simulator has a command line option to slow its rate of execution down. Try binpc/main -p 1 1, which puts a 1 second pause between each issued clock event. You should see output like:

0: Y_off
0: R_off
0: G_off
0:
0: Y_on
0: G_off
0: R_off
0:
0: Y_off
0: G_on
0: R_off
.
.
.
.

If you look closely at the pattern, you will see that it is a binary counter where Y is the least significant digit and R is the most significant. The zero before each line states which mote the message pertains to. Try ./binpc/main -p 1 3 and you'll see three motes execute the program, with their outputs staggered due to different boot times (staggered boot times is necessary so all of the mote clocks aren't perfectly synchronized to a degree impossible in the real world).

Reading from the COM port

Build another node that will put some messages on the air, such as cnt_to_led_and_rfm. Generic_base will pick them up and put them on the COM (serial) port; you just need to run an application that will listen to them.

Go into the tools directory and type javac net/tinyos/SerialForwarder/SerialForward.java. This file contains a Java program that presents a unified abstraction of reading mote output. It can be run with java net.tinyos.SerialForwarder.SerialForward. In addition, you need to run a program that connects to the SerialForwarder and presents data to you in a meaningful form. Compile a listener with javac net/tinyos/tools/ForwarderListen.java. This program connects to the SerialForwarder and presents the binary data in a human-readable (hex bytes) form. It can be run with net.tinyos.tools.ForwarderListen locahost 9000

Start up the SerialForwarder, then start ForwarderListen. You should see the SerialForwarder provide information on how much data it has collected, and your visualizer should begin to spit out hexidecimal bytes.

The output should look like:
7E 126 06 6 0B 11 00 0 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 38 56 02 2 3C 60 02 2 3C 60 3C 60 80 128 FF 255 06 6
7E 126 06 6 16 22 00 0 02 2 1F 31 02 2 30 48 02 2 30 48 02 2 30 48 02 2 30 48 02 2 1F 31 02 2 30 48 02 2 30 48 02 2 30 48 02 2 30 48 02 2 30 48 A9 169 3D 61 FF 255 06 6
.
.
.
 
 

If you look carefully at the hex output, you should see your cnt_to_led_and_rfm messages incrementing one of the message fields

Learning about TinyOS

Now that you have TinyOS working, you can start learning about it and writing your own programs. In the nest/doc/tutorial directory are the first three lessons for learning TinyOS. Read and follow the instructions. There are also some documents in nest/doc, such as tos-developer.pdf, that provide some high level information on the OS structure. Good luck!