EmTOS -- The EmStar TOS Emulator

by Thanos,
<thanos@cs.ucla.edu>
v1, 20040210

Introduction

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

A working EmStar build is needed for NesC code to be able to compile with a make emstar. In addition, the EMSTAR_ROOT environment variable must be defined to point to the root directory of the emstar source code.

To obtain an EmStar build, download the latest release tag, or check it out via anonymous CVS at 

http://cvs.cens.ucla.edu/

When you have the source code, you must build it. Note that EmStar requires glib2-devel, gtk2-devel, and pkgconfig. 

cd emstar
export PKG_CONFIG_PATH=/usr/lib/pkgconfig
make

EmStar also builds for other platforms, notably Stargate. This requires that you first install the appropriate cross compilers, then type 

make ARCH=<platform>

EmStar depends on a kernel module called "FUSD", that compiles with the rest of EmStar. You will need the kernel sources for your kernel (usually /usr/src/linux), and you may need to modify the file make/make.platform to point to your kernel headers if they aren't in a standard place.

Once compiled, before running the EmStar system, you must become root and insert the module using "insmod". (The module is in emstar/obj.i686-linux/fusd/kfusd.o). You can also set up your machine to insert it on boot.

EmStar works slightly better when DevFS is enabled in the kernel, but it is not required. If DevFS is NOT supported by your kernel, you must also start the daemon "fusdd" (emstar/obj.i686-linux/fusd/fusdd). This must also be started as root. If DevFS is installed, fusdd is not needed.

Since EmTOS uses the new TinyOS make system, version 3.80 of make is also needed.

Installation

EmTOS needs three environment variables to be defined:

EMSTAR_ROOT needs to point to your EmStar top-level directory TOSDIR needs to point to your "tinyos-1.x/tos" directory MAKERULES needs to point to your "tinyos-1.x/beta/make" directory

After defining those three environment variables, execute the install.sh script. The install script will create 2 symbolic links (to your tinyos-1.x/tos/platform and tinyos-1.x/beta/make directories). If all goes well, you will now be able to type make emstar inside your standard TOS application directories

How to use the new platform

Type make emstar in your TOS application directory. This will create a build/emstar/main.exe file (just like make pc creates a build/pc/main.exe). This is an executable file and can be run on the PC (similar to TOSSIM executables files). However, if the radio is used, this file will not run standalone, because it expects to connect to an appropriate link device.

Typically, EmTOS apps are started by running "emrun" with a config file called an emruntab. This will first launch the link device, and then launch your EmTOS application. To start several instances of your code that share a simulated or emulated channel, you can run "emsim" with a simulation config file that specifies the topology.

Several sample emruntabs and sim-config files have been provided in the "emstar/mote/testtabs" directory. To run them, from your $(EMSTAR_ROOT)/obj.i686-linux dir, type :

"emrun/emsim ../mote/testtabs/<simconfigname>".

E.g. "emrun/emsim ../mote/testtabs/Rfm.sim" will run a 2-node simulation with CntToLedsAndRfm running on one node and RfmToLeds running on the other one.

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 "make emstar".

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 the EmStar documentation page, at 

http://cvs.cens.ucla.edu/emstar

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.

EmTOS (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

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.