In lesson 1, you build Bombilla by running the
VMBuilder application from the directory
tos/liv/VM/samples:
java net.tinyos.script.VMBuilder bombilla.vmsf
bombilla.vmsf is a VM specification file
(vmsf). It tells VMBuilder what handlers, functions,
sensorboards and other options to include in the
VM. Open tos/lib/VM/samples/bombilla.vmsf
in an editor. The first line of the file should
read:
<VM NAME="BombillaVM"
DESC="A simple VM that includes a range of triggering events and functions."
DIR="../../../../apps/Bombilla">
This is an example of an element; all
Maté files (barring nesC code) are sequences
of these XML-like elements. The name of an element
is the first word after the opening <: the above
example is a VM element. Elements have tags, which
are key value pairs. The above VM element has three
tags, NAME, DESC, and DIR. Element and tag names are
case-insensitive; the above could alternatively be
written as:
<vm name="BombillaVM"
DESC="A simple VM that includes a range of triggering events and functions."
dir="../../../../apps/Bombilla">
with no change to its meaning. The Maté
toolchain only recognizes certain elements and
tags. Unrecognized tags and elements are
ignored. Although the names of the tags are case
insensitive, often the values of the tags are case
sensitive. For example, changing the case of
directory names in the dir tag is
significant.
Every VMSF must have a VM element with a NAME,
DESC, and DIR tag. This is so VMBuilder knows what
to name files associated with the VM and what
directory in which to put them. The Bombilla DIR tag
puts the VM in
tinyos-1.x/tos/lib/VM/samples/../../../../apps/Bombilla,
which is tinyos-1.x/apps/Bombilla.
After the VM element come four SEARCH elements:
<SEARCH PATH="../opcodes">
<SEARCH PATH="../contexts">
<SEARCH PATH="../languages">
SEARCH elements tell VMBuilder where to look for
files. VMBuilder will search them in the order the
file specifies them. PATH tags that have a relative
path (like those above) are resolved from where
VMBuilder is run, that is,
tos/lib/VM/samples. PATH tags can also be
absolute paths. Every VMSF should have the first
three SEARCH elements (opcodes, contexts,
languages), which is where all of the standard
Maté files are.
The two lines of the file specify a sensorboard
and what language to use (TinyScript). If you're
using a Telos mote, it uses MicroScript instead
(microscript):
<LOAD FILE="../sensorboards/micasb.vmsf">
<LANGUAGE NAME="tinyscript">
The LOAD element tells VMBuilder to load the file
specified by the FILE tag and process the elements
contained in it. In the above example,
micasb.vmsf contains elements specifying
what functions to support, and where to find the
underlying TinyOS components. Using the LOAD
element, you can write files containing libraries of
functions, for example, which a VM can then include
with a single element.
The LANGUAGE element tells VMBuilder what
language to support. Currently, Maté only
supports TinyScript, but we're currently working on
also suppoting motlle, a scheme-like language. Every
VM should have this element, if you want to be able
to program with it.
A set of FUNCTION elements follows. These
describe the set of functions the VM should include
and provide to the programmer. For example, Bombilla
has several functions for clearing, querying, and
sorting buffers:
<FUNCTION NAME="bclear">
<FUNCTION NAME="bfull">
<FUNCTION NAME="bsize">
<FUNCTION NAME="bufsorta">
<FUNCTION NAME="bufsortd">
The NAME tag is the name of the function; it
refers to an opcode description file
(.odf). The ODF file contains information
on how many parameters the function takes and their
types, whether it has a return value, and a brief
description. Lesson 5 details how to introduce new
functions by writing ODF files.
Finally, after the FUNCTION elements are the
CONTEXT elements. These elements specify what
software handlers the VM provides: each has its own
execution context. Similar to FUNCTION elements,
they have a single tag, NAME, which specifies a
context description file (.cdf) that
contains information on the handler. Bombilla
includes six handlers:
<CONTEXT NAME="Trigger">
<CONTEXT NAME="Timer0">
<CONTEXT NAME="Timer1">
<CONTEXT NAME="Once">
<CONTEXT NAME="Reboot">
<CONTEXT NAME="Broadcast">
|