Avrora

Avrora is an open-source cycle-accurate simulator for embedded sensing programs. The current release (version 1.7.106) of Avrora is written in Java and released under the BSD license. It can emulate two typical platforms, Mica2 and MicaZ, and run AVR elf-binary or assembly codes for both platforms. The main Avrora web page contains a lot of good information but is not actively maintained; most of the information is also available when running avrora with a -help option. Avrora development has moved to Sourceforge and a listing of recent pre-built JAR archives is available in the Avrora web page.

Installing Avrora

Avrora works fine on Linux and Windows. The main prerequisite is a Java 4 or newer development environment. Download the latest CVS snapshot by enter this command in a terminal.

cvs -d:pserver:anonymous@avrora.cvs.sourceforge.net:/cvsroot/avrora login

Simply press Enter key when a password is asked. Then enter the command:

cvs -z3 -d:pserver:anonymous@avrora.cvs.sourceforge.net:/cvsroot/avrora co -P avrora

The following will assume that you have set $AVRORA to be the absolute path to this avrora directory.

Build Avrora:

cd $AVRORA
make avrora

There should not be any error messages. With recent versions of javac, you may see errors like this if your locale is not setup properly:

src/avrora/monitors/SnifferMonitor.java:39: unmappable character for encoding ASCII

This can be fixed by setting an environment variable:

export LANG=en_US.UTF-8

Once Avrora builds properly, add $AVRORA/bin to your CLASSPATH. Ensure that you can run Avrora:

java avrora.Main

The output should be a bunch of usage information. On Cygwin the colors may not show up properly in which case you'll want to invoke Avrora using the -colors=false command line option.

Simulating TinyOS Applications

It is assumed that you have TinyOS 2.x installed and can build applications. First simulator a trivial single-node network:

cd $TOSROOT/apps/Blink
make micaz
mv build/micaz/main.exe Blink.elf
java avrora.Main -platform=micaz -simulation=sensor-network -seconds=3 -monitors=leds Blink.elf

The output should be something like this:

Avrora [Beta 1.7.107] - (c) 2003-2007 UCLA Compilers Group

Loading Blink.elf...[OK: 0.068 seconds]
=={ Simulation events }=======================================================
Node          Time   Event
------------------------------------------------------------------------------
   0       8006682  off off on  
   0       8006684  off on  on  
   0       8006686  on  on  on  
   0       8006688  on  on  off 
   0       8006690  on  off off 
   0       8006692  off off off 
   0       9793689  off off on  
   0      11579289  off off off 
   0      11579762  off on  off 
   0      13364889  off on  on  
   0      15150489  off on  off 
   0      15150962  off off off 
   0      15151490  on  off off 
   0      16936089  on  off on  
   0      18721689  on  off off 
   0      18722162  on  on  off 
   0      20507289  on  on  on  
==============================================================================
Simulated time: 22118400 cycles
Time for simulation: 1.337 seconds
Total throughput: 16.543306 mhz

Next simulate a collection of nodes:

cd $TOSROOT/apps/RadioCountToLeds
make micaz
mv build/micaz/main.exe RadioCountToLeds.elf
java avrora.Main -platform=micaz -simulation=sensor-network -seconds=10 \
  -monitors=leds,packet -nodecount=3 -stagger-start=1000000 RadioCountToLeds.elf

It is not clear in what situations the stagger-start option is needed. Sometimes, without this option, simulations can fail to start due to all nodes being in lock-step.

The output will be voluminous and should end up with something like this:

   0      72595584  <==== 00.00.00.0F.A7.0F.41.88.22.22.00.FF.FF.01.00.3F.06.00.23.CE.BB  0.660 ms
   1      73169483  on  off on  
   1      73169491  on  on  on  
   1      73169500  off on  on  
   1      73355979  ----> 00.00.00.0F.A7.0F.41.88.23.22.00.FF.FF.01.00.3F.06.00.24.62.C1  0.660 ms
   0      73356225  <==== 00.00.00.0F.A7.0F.41.88.23.22.00.FF.FF.01.00.3F.06.00.24.CE.B3  0.660 ms
   2      73356225  <==== 00.00.00.0F.A7.0F.41.88.23.22.00.FF.FF.01.00.3F.06.00.24.CE.B3  0.660 ms
==============================================================================
Simulated time: 73728000 cycles
Time for simulation: 4.349 seconds
Total throughput: 50.85859 mhz
Throughput per node: 16.952862 mhz
=={ Packet monitor results }==================================================
Node     sent (b/p)          recv (b/p)    corrupted (b)   lostinMiddle(p)
------------------------------------------------------------------------------
   0       756 / 36            1491 / 71               0       0
   1       756 / 36            1491 / 71               0       0
   2       735 / 35            1491 / 71               0       0

The important bit is at the bottom, where the packet monitor is telling us that all 3 nodes have both transmitted and received packets.

Monitors in Avrora

Monitors provide some useful information about your simulation. Avrora already has several useful monitors that allow you to monitor your simulation as it progresses such as LED information as well as get a summary of some parameter at the end such as energy consumption. Avrora's flexible architecture makes it very easy to create your own monitors. Please refer to the main Avrora website for knowing about creating your own monitors [1]. Here we are present the usage information of existing monitors as well as some useful notes about the problems we encountered when using some monitors based on our experience.

Energy Monitor

Prints the energy usage of various components over the simulation period. For example, it prints the energy consumed by each of the following components CPU, LEDs, External Flash, Radio. To use this monitor, simply add the energy to the monitors option.

java avrora.Main -platform=micaz -simulation=sensor-network -seconds=10 \
  -monitors=energy,leds,packet -nodecount=3 -stagger-start=1000000 RadioCountToLeds.elf

NOTES: Energy Monitor has a bug in measuring Flash energy usage ( as of Sep 26 2009 ). Please refer to the mailing list thread for updated information. [2]

C-Print Monitor

Allows you to print the values of variables as the simulation progresses. It uses memory watch to monitor the memory location of the variable and any changes to the memory location is printed on the screen. To use this monitor, copy AvroraPrint.h from src/avrora/monitors/AvroraPrint.h to your application. For example, if you are running blink application, copy it to tinyos apps/Blink directory. Include the AvroraPrint.h to your implementation in module file where you want to monitor the value of the variable. Here is an example that prints a character and a variable.

implementation {
  #include "AvroraPrint.h"

  uint8_t tempvar;   // <--- LINE ADDED

  /**
   * Initialize the component.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  command result_t StdControl.init() {
    tempvar = 0;   // <--- LINE ADDED
    call Leds.init();
    return SUCCESS;
  }


  /**
   * Start things up.  This just sets the rate for the clock component.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  command result_t StdControl.start() {
    // Start a repeating timer that fires every 1000ms
    printChar('s');    // <--- LINE ADDED
    return call Timer.start(TIMER_REPEAT, 1000);
  }

  /**
   * Halt execution of the application.
   * This just disables the clock component.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  command result_t StdControl.stop() {
    return call Timer.stop();
  }


  /**
   * Toggle the red LED in response to the <code>Timer.fired</code> event.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  event result_t Timer.fired()
  {
    tempvar = 32;   // <--- LINE ADDED
    printInt8(tempvar);   // <--- LINE ADDED
    call Leds.redToggle();
    return SUCCESS;
  }
}

Now you can build the file and simulate it as follows. The variable will be printed in logfile0 as well as on the screen. Please read the notes below.

cd $TOSROOT/apps/Blink
make mica2
mv build/mica2/main.exe Blink.elf
java avrora.Main -platform=mica2 -seconds=20  -printlogfile=logfile -VariableName=BlinkM__debugbuf1 -monitors=c-print,leds Blink.elf

NOTES:

1. -monitors=c-print is required to use this monitor.
2. -VariableName=BlinkM__debugbuf1 is required to use this monitor. Note it has to be changed to <your_component>__debugbuf1 if you use with component other than BlinkM. Note, some nesc compilers use $ sign for separating variables and component names. In that case, use BlinkM$debugbuf1.
3. printlogfile is not required but can be useful.
4. You might need to use "make [target] debug" for compilation.

TODO:

1. How to use c-print monitor to directly monitor any variable in the program. For example, how to print tempvar in above the program whenever it changes.

TODO

Add sections on:

• Talking to Avrora using the serial forwarder.
• Adding more monitors and their usage.
• Troubleshooting.