Show README syntax highlighted
EmTOS: TinyOS/NesC Emulation for EmStar
=======================================
thanos@cs.ucla.edu
$Id: README,v 1.21 2005/03/03 04:40:06 girod Exp $
Introduction
------------
EmTOS allows you to compile your NesC code as an EmStar binary, and
debug TinyOS applicatoins using the full suite of EmStar debugging
facilities. You can, for example, run NesC programs using
link:emsim.html[EmSim], or on our network of real motes using our
link:emcee.html[ceiling array].
The EmStar platform is a new platform target for motes that is similar
to the 'pc' platform. It allows code written against the TinyOS API
to run in an EmStar environment, in any mode from deployment to
"emulation" to pure simulation. This is achieved through a stub layer
called "EmTOS".
Requirements
------------
In order to use EmTOS, some additional steps must be taken when
installing EmStar. These steps are not needed for a
Microserver-only EmStar installation. The steps are detailed
in link:../install.html[The EmStar Installation Guide].
The summary of the steps is:
* Download or create a symlink to a copy of the TinyOS
SourceForge repository. If you already have a repository
checked out you will need to add two symlinks inside it.
Alternatively, you can download a preconfigured snapshot
of TinyOS-1.1.6 from the link:../downloads.html[Downloads Page].
* Edit `Make.conf`. Set `BUILD_EMTOS := 1`. Check the
settings for `NESC_DIR` and `AVR_DIR` and modify them
to point to the location of the NesC and AVR tools
packages. The default settings work for the AVR tools
package on the EmStar web site.
Since EmTOS uses the new TinyOS make system, version 3.80 of 'make' is
also needed.
How to Build and Run TinyOS Code in EmTOS
-----------------------------------------
EmTOS executables are built using the EmStar build system and
are run using EmRun, the EmStar process management tool.
Building an EmTOS Executable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EmTOS binaries are built from the EmStar build system, along with all
other EmStar objects and executables. Under the covers, EmStar's
build system will set a number of environment variables and then
invoke the TinyOS `make` with platform `emstar`. This may seem
confusing at first but it enables easy cross-compilation of the EmTOS
and NesC code using the same mechanisms that are already in place for
other uses of EmStar.
To build a TinyOS executable for EmTOS, you must add some additional
directives to an EmStar BUILD file. (Note that if you create a new
BUILD file for this purpose, you must also `include` that file from a BUILD file
higher up in the hierarchy.) A simple example is shown
below (from `mote/BUILD`):
-----
build tos {
target CntToLedsAndRfm { tinyos-1.x/apps/CntToLedsAndRfm }
}
-----
The `build tos` directive tells the EmStar build system that this is a
TinyOS target. The executable will be saved as the file
`CntToLedsAndRfm` in the current directory (within the
`obj.<platform>` hierarchy). The path enclosed in braces specifies
the location of the TinyOS application within the TinyOS tree. The
path is interpreted relative to the root of the EmStar source tree
(recall that EmTOS assumes that there is a symlink from
`emstar/tinyos-1.x` to your TinyOS SourceForge repo).
Running an EmTOS Executable
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once this has built the EmTOS binary, you can run it in emulation mode
by creating an emrun file (found in `mote/testtabs/Cnt.run`)
----
# -*- Mode: C -*-
#
# Cnt.run
# Emruntab that runs CountToLedsAndRfm in EmTOS
#
include mote/mote.run
&mote_hostmote(/dev/ttyS0,mica2,0);
&mote_motenic(mote0,0,show="leds");
process CntTLaR {
type = daemon;
waitfor = mote0;
cmd = "mote/CntToLedsAndRfm";
}
----
Make sure a mote programmed with `Transciever` is attached to
the specified serial port, and start up the system:
----
$ cd emstar/obj.i686-linux
$ emrun/emrun ../mote/testtabs/Cnt.run
----
When EmRun starts, it will first start the MoteNIC, which will connect to a
`Transceiver` mote on serial port `/dev/ttyS0` and then run the
`CountToLedsAndRfm` application. You can see the leds count by
looking at the state of the LEDs in the status device
`/dev/tos/status/leds`:
----
$ cd emstar/obj.i686-linux
$ bin/echocat -w /dev/tos/status/leds
Current Leds Status:
Red = 1
Green = 1
Yellow = 1
Current Leds Status:
Red = 0
Green = 0
Yellow = 0
----
It will also send packets to the `/dev/link/mote0` link device, which
will be transmitted by the `Transceiver`. You can see this traffic with
`linkdump`.
----
$ cd emstar/obj.i686-linux
$ bin/linkdump --uses mote0 -l -d
>> src=0.0.0.1 dst=255.255.255.255 type=TOS[4,125] data_len=8
0000: 66 00 00 00 01 00 00 00 f.......
>> src=0.0.0.1 dst=255.255.255.255 type=TOS[4,125] data_len=8
0000: 67 00 00 00 01 00 00 00 g.......
----
(Note: the `bin` directory has a number of useful programs, so you way
want to add it to your `$PATH`)
Running an EmTOS Executable in the Simulator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also run the same software in the EmStar simulator, by
creating an EmStar simulation config file. An example of a simuation
file for the CountToRfmAndLeds example is found in
`mote/testtabs/Rfm.sim`.
This config file will simulate two Motes, one running CountToRfmAndLeds
and the other running RfmToLeds. The channel model is a simple path
loss model. To run it:
----
$ cd emstar/obj.i686-linux
$ SIM_GROUP=8 emrun/emsim ../mote/testtabs/Rfm.sim
----
You can then observe the same device files as before, only
specifying the group and node ID of the mote you wish to query.
----
$ cd emstar/obj.i686-linux
$ bin/echocat -G 8 -N 1 -w /dev/tos/status/leds
...
$ bin/linkdump -G 8 -N 1 --uses mote0 -l -d
...
----
If you have access to an emulation array, the same sim config file can
be used to run the software in "emulation mode", in which real radios
are used in place of a model.
More on Building EmTOS Executables
----------------------------------
The EmStar build system supports various ways of passing
parameters and variables into the TinyOS build system.
The `tosflags` variable can be set within the `build tos` block.
These flags are a space-delimited list of environment variables and
values. These variables will be set prior to running the TinyOS make,
enabling conditionals inside the TinyOS application's makefile to be
controlled.
In addition, the `cflags` variable can be set. These flags will be
included on the `gcc` command line when the NesC program is compiled.
The following snippet demonstrates the use of these two variables:
----
build tos for emstar,mica2 {
tosflags := USE_SMAC=1
cflags := -DSTATUS_DBG -DHOSTMOTE_MAX_RECV_DATA_LENGTH=56
target EssDsp_smac { tos-contrib/dsp/apps/EssDsp }
}
----
The snippet above also demonstrates the use of platform specifiers
that enable the target to be built for specific platforms. The
`emstar` platform specifier maps to all "Microserver" platforms,
e.g. stargate, ipaq, PC, etc. The `mote` specifier maps to all Mote
platforms, e.g. Mica, Mica2, etc.
For more detail on the build system, see the
link:make.html[Easybuild Reference].
Native Mode Debugging
---------------------
...fill in text here about how to run in native mode!
Differences from TOSSIM
-----------------------
Whereas TOSSIM simulates a collection of motes and a radio channel
model all in one executable, each instance of EmTOS represents a
single mote, and all instances share a preexisting EmStar environment
that implements the RF channel.
This enables EmTOS to leverage existing simulation and emulation
support within EmStar, for example, using real Motes as the radio
channel (e.g. the ceiling and portable arrays) instead of a modeled
channel, or alternatively using EmStar's simulated channel model.
This also enables heterogenous EmTOS and EmStar builds to share in the
same simulation or emulation environment. This means that motes with
different software or different capabilities can participate in a
simulation along with distributed systems of Microservers (e.g. tiered
architecture simulation).
Deployment of TinyOS code on Linux systems
------------------------------------------
Another interesting feature of EmTOS is that it enables TinyOS code to
be deployed on Microservers. Since the EmTOS layer enables TinyOS
code to run in the Linux-based EmStar environment, the capability to
simulate or emulate also extends to deployment on Linux platforms such
as Stargate. This can make integration of Microservers to motes much
easier when there is significant effort required to port software from
NesC/TinyOS to Linux.
Controlling and visualizing EmStar simulations
----------------------------------------------
EmTOS itself does not implement the simulation environment -- it
merely enables a TinyOS application to integrate with an EmStar
system, whether a deployed system, a simulation, or an emulation.
Running an EmStar simulation requires a configuration file for the
simulation, and a configuration file for each EmStar node (called an
emruntab). To run an EmTOS mote, the emruntab must simply run the
executable generated by the EmStar build.
EmStar simulations, emulations, and deployments can be visualized
using the EmView GTK visualizer. This visualizer can be extended by
writing plugins in C that parse status output from the node.
Currently, as an example there is an EmView plugin that displays the
state of the EmTOS LEDs.
EmTOS does not yet provide an interface to TinyViz, although this
feature could easily be added if there is interest in having it.
More information about simconfig file formats and using the simulator
and visualizer can be found at
link:http://cvs.cens.ucla.edu[the EmStar documentation page].
How it works
------------
EmTos is a task-level simulator. What that means is that it does not
simulate MAC behavior, intricate timing behavior or anything that
depends heavily on timing and interrupts. Since EmTos is running in a
single thread, there is no pre-emption possible. However, it preserves
the semantics of the TinyOS FIFO scheduler, so if your application is
not using interrupts directly but posts tasks, it will work as in real
life.
LibEmTOS (the EmStar TinyOS stub layer) is a library that's responsible
for connecting NesC code to the EmStar framework. The .nc files in
the 'emstar' platform directory call library functions for things like
sending a packet, setting the clock rate or blinking a LED. If the
TinyOS code expects a callback (like SendDone, PktReceived etc), the
writer of the low-level device driver has to provide a function
pointer (and an implementation) so that EmTOS can call the appropriate
function.
When library functions are called, commands are issued to the EmStar
framework, and control returns to the NesC application. Code in the
EmTOS layer is responsible for translating to the EmStar commands to
send/receive packets and set timers. The EEPROM is simulated by an
in-memory buffer that is exposed via standard EmStar device
interfaces. Timers and other interrupts cause tasks to be posted to
the NesC task queue, which then eventually run and invoke the
appopriate signals, passing control again to the NesC code.
The callback functions are defined in tos_emstar.h. This header file
is shared (duplicated) in both the TOS and EmStar repositories.
Implemented NesC interfaces
---------------------------
The following interfaces are currently implemented in EmTOS:
- Radio (both Berekely MAC and S-MAC)
- Clock and Timer
- TimerHeap (UCLA software timer implementation)
- EEPROM (In Byte Mode only, page EEPROM has not been tested)
- Leds
We plan to implement the UART and ADC interfaces in the near future.
Emulation, e.g. the ceiling array
---------------------------------
At the CENS Systems Lab, we have set up an EmStar server that can
provide access to a real RF channel, using our Ceiling Array and
Portable Array. These arrays consist of a number of motes (55 and 16
respectively) that are connected via a serial multiplexor to a Linux
server. This server runs many emulated EmStar nodes in parallel,
sending the radio traffic out over the air via the motes. EmTOS
enables real TinyOS code to run in this environment, running in a
debugging-friendly Linux environment, but sending all traffic over the
real RF channel.
Since much of the software infrastructure is already in place, setting
up an EmStar emulation network is not difficult -- although very
little documentation exists. Interested parties are free to send mail
the the emstar-users list with questions. In some cases it may be
possible to enable remote access to the ceiling array, although do not
currently have a system for doing this.
More Help
---------
Documentation about EmStar and using the simulator can be found at:
http://cvs.cens.ucla.edu/emstar
In addition the the EmStar documentation pages, EmStar/EmTOS help is
also available from the emstar-users@cens.ucla.edu mailing list and
archive.
See more files for this project here