EmTOS: TinyOS/NesC Emulation for EmStar

by thanos@cs.ucla.edu
2005-03-03

Site and Mailing List Search:

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 EmSim, or on our network of real motes using our 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 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 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 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 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.