[Tutorial Home] [Lesson 1] [Lesson 2] [Lesson 3] [Lesson 4] [Lesson 5] [Lesson 6]

Lesson 1: Building and Using Maté

Last modified: Wed Apr 27 19:10:18 PDT 2005
In this lesson, you build a provided Maté VM and programming environment. You install the VM on a mote (or use TOSSIM) and write a simple program to test that everything is working properly.
Introduction

Maté has two parts: a Java toolchain and TinyOS components. The Java toolchain resides in the directory

tinyos-1.x/tools/java/net/tinyos/script

while the TinyOS components reside in

tinyos-1.x/tos/lib/VM.

The first thing you need to do is compile the Maté toolchain. Go to tinyos-1.x/tools/java/net/tinyos/script and type make. This should build the two major tools, VMBuilder and Scripter. If you encounter compilation problems, chances are that you haven't properly compiled all the rest of the TinyOS Java packages that Maté depends on. These packages include util, packet and message.

VMBuilder

VM/samples contains the specification files for several sample VMs, which have the suffix vmsf. There are several sample VMs: one for mica platforms (bombilla-mica.vmsf), one for Telos revA (bombilla-telosa.vmsf), and one for Telos revB motes (bombilla-telosb.vmsf). The distinction between the last two is how much RAM they use and hardware details with regards to sensor boards: bombilla-telosa is designed to fit in the 2KB of a Telos revA node. The distinction between the mica and Telos VMs lies in the sensors they have.

Depending on what platform you have, you want to choose the appropriate vmsf file. You build a VM with the VMBuilder tool; while in the directory VM/samples, type

java net.tinyos.script.VMBuilder file

This tells VMBuilder to build the VM specified by the file named file (e.g., bombilla-telosb.vmsf). Bombilla is a VM that supports several basic sensor net operations. You should see output similar to this:

$ java net.tinyos.script.VMBuilder bombilla-telosb.vmsf
Currently, filed-based VMBuilder only works from the samples/ subdirectory.
Please be sure you execute it from there.

Writing VM to directory /opt/tinyos-1.x/apps/BombillaTelosB
config file vm.vmdf
constants file MateConstants.h
185 of 256 opcodes used.
component file MateTopLevel.nc
Makefile
	    
Running Bombilla in TOSSIM

To make sure the Maté toolchain is working properly, you'll first write programs for TOSSIM motes. TOSSIM only supports mica-class motes, so build bombilla-mica, go to the directory where VMBuilder put it (BombillaMica) and compile it for TOSSIM with make pc. You should see a long stream of output, as you build several Java classes, followed by the TOSSIM executable. Set your DBG environment variable to led, and run TOSSIM with the following flags:

./build/pc/main.exe -l=1 -b=1 1
	    

This has TOSSIM run in real-time, instead of as quickly as possible (-l=1), and makes the node boot in the first second of simulation time (-b=1). You should see no output, as the Bombilla VM currently has no code to run.

CntToLeds in Maté

Open a second window and go to the Bombilla application directory. Using your favorite editor, create a file named "reboot.txt" with this code in it:

led(1);
	    

This tells the VM to turn on the red LED. Exit your editor and type this at the command line:

java net.tinyos.script.Scripter -comm tossim-serial reboot reboot.txt
	    

This runs the TinyScript compiler/scripter. -comm tossim-serial tells it to connect to TOSSIM through a virtual serial port to mote 0. reboot reboot.txt tells it to inject code that should run when the VM reboots (Reboot), and the code is in the file reboot.txt. The VM reboots every time it installs new code.

All of the tools for interacting with a running VM, such as Scripter and VMBufferReader (which you'll use later, in Lesson 2), must be executed from the VM's application directory. This is because each VM can have customized message formats and values, and the tools must use the VM-specific versions of those Java classes, which reside in the directory named vm_specific.

In the TOSSIM window, you should see this output:

0: LEDS: Red on.
0: LEDS: Green off.
0: LEDS: Yellow off.
	    

If you don't see the output, trying running the Scripter again.

That program was very simple: it wasn't even Blink. Let's try CntToLeds. This requires writing two scripts: one for what to do when a timer fires (increment a counter and display it), and one to start the timer. Open a file named "timer0.txt" and type:

private counter;
counter = counter + 1;
led(counter % 8);
	    

Every time this program runs, it will increment counter and display its bottom three bits on the mote LEDs (% is the modulo operator). Type

java net.tinyos.script.Scripter -comm tossim-serial timer0 timer0.txt
	    

to install the timer script on the VM. However, the timer isn't firing yet; you need to install a script that will start it. Re-open "reboot.txt" and edit it to be

settimer0(10);
	    

The function settimer0 controls the rate at which timer0 fires. The parameter is in terms of tenths of a second, so 10 will fire the timer at once a second. Calling it with 0 will stop the timer. When the VM installs the script, it will reboot and run it, starting timer0:

java net.tinyos.script.Scripter -comm tossim-serial reboot reboot.txt
	    

You should see the LED increment in the TOSSIM window. You can also start TinyViz with

java net.tinyos.sim.SimDriver -gui
	    

to see the mote blink visually.

Network Programming

So far, you've been writing scripts for a single simulated mote. Maté VMs automatically propagate new programs into a network. Run TOSSIM with four motes:

./build/pc/main.exe -l=1 -b=1 4
	    

Write a script that displays mote ID on the LEDs, saving it to "id-led.txt":

led(id() % 8);
	    

Install it on mote 0 with Scripter:

java net.tinyos.script.Scripter -comm tossim-serial reboot id-led.txt
	    

A few moments later, you should see the other motes receive the code and execute it.

Programming Motes

If you have motes, you can repeat all of the above steps using them instead of TOSSIM. If you have Telos motes, you'll need to compile one of the Telos variants. Compile Bombilla for the type of mote you have, and install it as you would any other TinyOS application. Install it on four motes: be sure to give them unique IDs, preferrably sequential (e.g., 9, 10, 11 , 12).

Turn on one of the motes and plug it into your serial port or other serial communication device. Start a SerialForwarder for it. SerialForwarder is usually the default communication interface for tools like Scripter. Take the script that displays the bottom three bits of mote ID on the LEDs ("id-led.txt") and install it with Scripter. You can omit the -comm command line parameter:

java net.tinyos.script.Scripter reboot id-led.txt
	    

If Scripter tries to connect to something besides SerialForwarder, you can tell it to explicitly use SerialForwarder:

java net.tinyos.script.Scripter -comm sf reboot id-led.txt
	    

You should see the mote LEDs display the bottom three bits of the mote ID. If you happened to choose a number evenly divisible by eight (e.g., 120), then no LEDs will turn on. Use one of the other motes.

Once the script is installed and has run, turn on the other three motes. It may take a few seconds, but they will request the script, download it, and run it themselves, automatically reprogramming. The reason it might take a while is the code propagation algorithm: Maté tries to send as few packets as possible (to conserve energy). If it thinks every mote already has the program (as was the case when only one was on), then it slows its code advertisement rate. If things seem to be going too slowly, re-inject the script. This will kick-start the connected mote to advertise more frequently.

Conclusion

This concludes Lesson 1, which showed you how to build a Maté VM, injecting programs, and automatic code propagation. Lesson 2 introduces TinyScript (the language the above scripts were in) in greater depth.


Next Lesson > | Top