Quick manual
This quick manual has as objective explain to the user how to carry out IEEE 802.15.4 compliant wireless sensor network emulations on avroraZ. For that, it gives some tips and examples on applications developed for the micaZplatform with the TinyOS operative system. To get the files used here you should download the jars folder from the avroraZ source tree as it is explained in the downloads section of the project webpage. If you want to know more about how to use the main simulator please use the "-help option" or visit the Avrora online help system
Getting started
If you are not yet familiar with the avrora simulator, it is recommended to check first the main web page of the simulator where the main functionalities of it are explained. Anyway these should be your first steps:
- Avrora is implemented in Java, and therefore it requires that you have a functional Java Virtual Machine installed. See http://java.sun.com to download the Sun Java implementation for your platform.
- Format your program accordingly to one of the four types of program format that Avrora supports: The Atmel assembler syntax. Files that end with the .asm extension are assumed to be in this format.The GNU assembler (GAS) syntax. Files that end with the .s extension are assumed to be in this format.The output of the avr-objdump utility. Files that end with the .od extension are assumed to be in this format.Binary programs in the executable and linkable format. Files that end with the .elf extensions. This should be your option if you are working with as sensor operative system that is giving you a binary program. Just change the extension of your program to the ELF format. For example in Tinyos move main.exe to app.elf.
- AvroraZ comes packaged in a Java Archive (JAR) file. This extension file provide a way to package software written in Java and to easily distribute that software. Download the latest AvroraZ JAR archive release
Running avroraZ
Once you have the JVM installed you will use the Java tool to run the program packaged inside the Jar file. Simply issue the command: "java -jar avroraZ.jar". Running avroraZ with no options will print out the built-in help. You can get more info about JAR files in this manual.Running the built-in help
java -jar avroraZ.jar -help Avrora [Beta 1.6.0] - (c) 2003-2005 UCLA Compilers Group Usage: avrora [-action=action] [options] Usage: avrora -help [category] OVERVIEW Avrora is a tool for working with assembly language programs for the AVR architecture microcontrollers and building simulations of hardward devices based on this microcontroller.It contains tools to read AVR programs in multiple formats, perform actions on them, and generate output in multiple formats. Typical usage is to specify a list of files that contain a program in some format supported by Avrora and then specifying the action to perform on that program. For example, giving the name of a file that contains a program written in assembly language and a simulate action might look like: avrora -action=simulate -input=atmel program.asm Other actions that are available include generating a control flow graph of the program or running one of the analysis tools on the program. See the actions section for more information. OPTIONS The main options to Avrora specify the action to be performed as well as the input format and any general configuration parameters for Avrora. The available main options are listed below along with their types and default values. Each action also has its own set of options. To access help for the options related to an action, specify the name of the action along with the "help" option. -action: string = simulate This option selects the action to perform. For example, an action might be to load a program into the simulator and run it. For more information, see the section on actions. -banner: boolean = true This option is used to enable or disable the printing of the banner. -colors: boolean = true This option is used to enable or disable the terminal colors. -config-file: string = This option can be used to specify a file that contains additional command line options to Avrora. Any command-line option can be specified in this file. For repeated runs with similar options, the common options can be stored in this file for use over multiple runs. Options are processed in the following order: 1) The .avrora file in your home directory 2) A configuration file specified on the command line 3) Command line options to Avrora -help: boolean = false Displays this help message. -html: boolean = false For terminal colors. Display terminal colors as HTML tags for easier inclusion in webpages. -input: string = auto This option selects among the available program formats as input to Avrora. For example, the default input format, "atmel" selects the assembly language format supported by Atmel's assembler. -license: boolean = false Display the detailed copyright and license text. -status: boolean = true This option enables and disables printing of status information, for example when the simulator is loading a program. -verbose: list = (null) This option allows users to enable verbose printing of individual subsystems within Avrora. A list can be given with individual items separated by commas. For example: -verbose=loader,atmel.flash ADDITIONAL HELP CATEGORIES Additional help is available on a category by category basis. Below is a list of the additional categories available to provide help with actions, input formats, monitors, and more. To access help for a specific category, specify the "-help" option followed by the name of category. -help [[http://compilers.cs.ucla.edu/avrora/help/actions.html|actions]] Help for Avrora actions. -help [[http://compilers.cs.ucla.edu/avrora/help/all.html|all]] Print a list of all categories for which help is available. -help [[http://compilers.cs.ucla.edu/avrora/help/inputs.html|inputs]] Help for the supported program input formats. -help [[http://compilers.cs.ucla.edu/avrora/help/monitors.html|monitors]] Help for the supported simulation monitors. -help [[http://compilers.cs.ucla.edu/avrora/help/simulations.html|simulations]] Help for supported simulation types. For more information, see the online documentation at http://compilers.cs.ucla.edu/avrora To report bugs or seek help, consult the Avrora mailing list: http://lists.ucla.edu/cgi-bin/mailman/listinfo/avrora Please include the version number [Beta 1.6.0] when posting to the list.Running your first example: The Tinyos Blink application
Compile the Tinyos application $avroraz-user://opt/tinyos-2.x/apps/RadioCountToLeds/make micaz Copy it to the emulator JAR file route in the ELF format $avroraz-user://opt/tinyos-2.x/apps/RadioCountToLeds/cp build/micaz/main.exe /opt/avroraZ/avrora/jars/blink.elf Emulate the application executing the JAR file $avroraz-user://opt/avroraZ/avrora/jars/java -jar avroraZ.jar -seconds=5.0 blink.elf Loading blink.elf...[OK: 1.082 seconds] =={ Simulation events }======================================================= Node Time Event ------------------------------------------------------------------------------ 0 318 Red: on 0 320 Yellow: on 0 322 Green: on 0 364 Red: off 0 366 Yellow: off 0 368 Green: off 0 7208139 Red: on 0 14408142 Red: off 0 21608143 Red: on 0 28808142 Red: off 0 36008143 Red: on ============================================================================== Simulated time: 36864000 cycles Time for simulation: 0.812 seconds Total throughput: 45.399014 mhzReport seconds instead of clock cycles
You can see in the results obtained above after compiling the Blink application that the time for every event is in microcontroller clock cycles rather than seconds. You can change this by using the the "-report-seconds" option which will cause the simulator to report the time for each event in seconds. Also, the -seconds-precision option will set the number of decimal places reported for each time in seconds.Wireless Sensor Network
One of the main goals of Avrora developers was to enable sensor network research by providing an accurate and scalable simulator for the actual hardware platform on which sensor programs run. Hence, the architecture of Avrora allows multiple Simulator objects to be instantiated and run. Avrora can then simulate an entire network of nodes by periodically synchronizing the simulator instances to preserve the timing interactions between them. These nodes can communicate with each other wiressly to exchange IEEE 802.15.4 compliant packets that could include sensor data and routing information for a multi-hop network.In order to select a multi-node simulation, we will need to specify the simulation option with the value sensor-network. This tells Avrora to the simulation type is a sensor network, rather than the default, single node simulation. On the other hand, the -nodecount option must be used to load the .elf files to every node of the network. A list of integers should be passed to this option corresponding to the number of nodes that should be instantiated with each program passed on the command line. For example, if -nodecount=2,1 is passed and the arguments are RadioCountToLeds.elf,Blink.elf then two nodes will be instantiated with the RadioCountToLeds application and one node with the Blink program.
Unsynchronize nodes starting times
It is useful that the nodes do not start at the same time when the user is working with synchronized protocols like the 802.15.4 MAC layer. By doing so, the user can check if the synchronization procedure of its own protocol is working or not. With this aim avrora supports two options that perturb the starting time of each node. The -random-start option accepts an interval in clock cycles. When specified, each node's start time will be delayed by a pseudo-randomly chosen number of cycles in this interval. For example, if -random-start=[0,1000] is specified, each node will be started at a random time between 0 and 999 clock cycles, inclusive. The numbers are chosen in a pseudo-random fashion; to specify a seed to the random number generator (for repeatable simulation results), specify the -random-seed option. Also, you can use the stagger-start that will stagger the start times of the nodes by the number of clock cycles specified. For example, if -stagger-start=100 is passed, the first node will start at time 0, the second at time 100, the third at time 200, and so on.Topology file
The topology file must indicate the network topology and the the density of people in the environment. For that the 3D position of every node that is going to be emulated in avroraZ plus the radio channel parameter ρ have to be indicated as follows:#AvroraZ topology file example #Each line should be a node like: nodeid x y z ρ #nodeid = node identifier #x y z = 3D node coordinates #ρ: density of obstacles (if not present is zero) for each radio link #simulator will take the maximum rho between transmitter and receiver node0 0 0 0 0.1 node1 0 5 0 node2 0 0 5 0.2 node3 10 0 0 0.05 node4 0 10 0 node5 0 0 10 0.1Please, take a look to the radio model explanation inside the extensions section of this documentation for more information about the radio parameters settings (x,y,z, ρ ).
Noise file
The noise can be created in the simulator by means of real measurements of a radio channel. For that, RSSISample application from the Tinyos-2.x operative system is suggested to be used. This firmware generates a text file with readings from the RSSI register. Afterwards, the file can be feed into the emulator using the -noise option to generate a Noise time trace that will be used by the radio model.
Getting the noise file with the RSSISample application and running it in avroraZ:1) Install the RSSISample application on your mote selecting the appropiate channel RSSISample application is only available for the telosb platform. However, as this platform also uses the cc2420 radio chip, the noise time trace recorded with it is totally compatible with the radio model used in AvroraZ. The install command to do RSSI sampling in channel 11 (default is 26) for mote 1 is: $avroraz-user://opt/tinyos-2.x-contrib/stanford-sing/apps/RssiSample/make telosb CFLAGS=-DCC2420_DEF_CHANNEL=11 install,1 2) Running the java program to collect the sampled data in 'Noise.txt' file $avroraz-user://opt/tinyos-2.x-contrib/stanford-sing/apps/RssiSample/java RssiSample -comm serial@COMx:telosb (x is the port number you are using.) For other options like setting sampling frequency or the total number of samples you would like to take please read the README text file that comes with the RssiSAmple application. $avroraz-user://opt/tinyos-2.x-contrib/stanford-sing/apps/RssiSample/vim README.txt 3) Running avroraZ with the recorded noise time trace Once you recorded the noise in your selected environment you can introduce it in the emulator using the -noise option. $avroraz-user://opt/avroraZ/avrora/jars/java -jar avroraZ.jar -noise=/opt/tinyos-2.x-contrib/stanford-sing/apps/RssiSample/Noise.txt seconds=5.0 blink.elfMonitors
The emulator offers the ability to install execution monitors that can be the utility to the user in order to study and analyse its behaviour. The "monitors" option support a variety of different monitors which when passed will instrument the program before while it is running and then generate a report after the program has completed its execution. Run the option "-help monitors" to get a list with the monitoring possiblities of avrora. The Leds and Packet monitors are the default monitors for the emulator. See the monitoring section of this documentation to know how to use the most important monitors when using the avroraZ extension tool. Users can also create their own monitors for the emulator adding a new subclass of the MonitorFactory (read this info to know how to do this)Configuration file
Avrora supports to specify a file that contains the additional command line options to Avrora. Any command-line option can be specified in this file. Hence, for repreated runs with similar options, the common options can be stored in this file for use over multiple runs. Options are processed in the following order inside the file:
- The .avrora file in your home directory
- A configuration file specified on the command line
- Command line options to Avrora
So, a configuration file can be written including every command option that we could need for our emulations with the avroraZ tool. Here there is an example where we load RadioCountToLeds in one node. RadioCountToLeds maintains a 4Hz counter, broadcasting its value in an AM packet every time it gets updated. The other node will have just simple receiver application. Almost all options have been already explained but if you have doubt about any of them use the -help option to obtain more info. The topology file used is the one created in the topology file example above. In the example the content of the packets indicated, however if you want to know how to analyse every packet sent and received you will have to look into the monitoring section of this documentation.
1) Create and save the following info in a text file called config.txt #Configuration file example colors=true banner=false platform=micaz topology=./topology.top noise=./Noise.txt update-node-id=true stagger-start=10000 monitors=packet report-seconds real-time seconds-precision=2 seconds=5.0 simulation=sensor-network nodecount=1,1 2) Run avroraZ passing the configuration file though the -config-file option and load the application to the wsn nodes $avroraz-user://opt/avroraZ/avrora/jars/java -jar avroraZ.jar -config-file=./config.txt RadioCountToLeds.elf receiver.elf Loading RadioCountToLeds.elf...[OK: 0.076 seconds] Loading receiver.elf...[OK: 0.016 seconds] =={ Simulation events }======================================================= Node Time Event ------------------------------------------------------------------------------ 0 0:00:01.33 ----> 00.00.00.0F.A7.0E.41.88.00.22.00.FF.FF.00.00.06.00.01.C5.C7 0.629 ms (Packet 00 broadcasted with data 00.01) 1 0:00:01.33 <==== 00.00.00.0F.A7.0E.41.88.00.22.00.FF.FF.00.00.06.00.01.E0.E3 0.629 ms 0 0:00:01.58 ----> 00.00.00.0F.A7.0E.41.88.01.22.00.FF.FF.00.00.06.00.02.E3.98 0.629 ms (Packet 01 broadcasted with data 00.02) 1 0:00:01.58 <==== 00.00.00.0F.A7.0E.41.88.01.22.00.FF.FF.00.00.06.00.02.E0.E9 0.629 ms 0 0:00:01.82 ----> 00.00.00.0F.A7.0E.41.88.02.22.00.FF.FF.00.00.06.00.03.0D.39 0.629 ms (Packet 03 broadcasted with data 00.03) 1 0:00:01.82 <==== 00.00.00.0F.A7.0E.41.88.02.22.00.FF.FF.00.00.06.00.03.DE.E2 0.629 ms 0 0:00:02.05 ----> 00.00.00.0F.A7.0E.41.88.03.22.00.FF.FF.00.00.06.00.04.AF.26 0.629 ms (Packet 04 broadcasted with data 00.04) 1 0:00:02.05 <==== 00.00.00.0F.A7.0E.41.88.03.22.00.FF.FF.00.00.06.00.04.E0.EE 0.629 ms 0 0:00:02.30 ----> 00.00.00.0F.A7.0E.41.88.04.22.00.FF.FF.00.00.06.00.05.74.2A 0.629 ms (Packet 05 broadcasted with data 00.05) 1 0:00:02.30 <==== 00.00.00.0F.A7.0E.41.88.04.22.00.FF.FF.00.00.06.00.05.DE.E9 0.629 ms ============================================================================== Simulated time: 18432000 cycles Time for simulation: 3.567 seconds Total throughput: 10.334735 mhz Throughput per node: 5.1673675 mhz =={ Packet monitor results }================================================== Node sent (b/p) recv (b/p) corrupted (b) lostinMiddle(p) ------------------------------------------------------------------------------ 0 100 / 5 0 / 0 0 0 1 0 / 0 100 / 5 0 0IEEE 802.15.4 Association example
One of the features provided by the IEEE 802.15.4 MAC standard is the association procedure between the Personal Area Network (PAN) coordinator and other devices. The attached figure depicts the association procedure.An unassociated device shall initiate the association procedure by sending an associate request command to the coordinator of an existing PAN. If the association request command is received correctly, the coordinator shall send an acknowledgement. This acknowledgement however does not mean that the device has associated. The coordinator needs time to determine whether the current sources available on a PAN are sufficient to allow another device to associate. If already associated, remove all information. If sufficient resources are available, the coordinator shall allocate a short address to the device and generate an association response command containing the new address and a status indicating the successful association. If there are not enough resources, the coordinator shall generate an association response command containing a status indicating failure. This decision should be made within ResponseWaitTime symbols. This response is sent to the device using indirect transmission (pending, request,...). On the other side, the device, after getting the acknowledgement frame, waits for the response for aResponseWaitTime symbols. It either checks the beacons in the beacon-enabled network or extract the association response command from the coordinator after aResponseWaitTime symbols. On reception of association response command, the device shall send an acknowledgement. If the association is successful, store the addressed of the coordinator with which it has associated.
The open source toolset called Open-ZB provides a IEEE 802.15.4 protocol stack in beacon enable mode in the TinyOS operative system. Hence, we are going to emulate the association example provided there it in order to give a standard compliant application running onto avroraZ.
AvroraZ emulation for the open-ZB association example1) Create and save the following configuration options in a text file called config_association.txt #Configuration file example colors=true banner=false platform=micaz topology=./topology.top noise=./Noise.txt update-node-id=true stagger-start=1000000 monitors=packet,leds report-seconds real-time seconds-precision=2 seconds=50.0 simulation=sensor-network nodecount=1,1 2) Compile and give ELF extension to the coordinator association example application in tinyos (include the define TYPE_DEVICE COORDINATOR inside the header associationexample.h) $avroraz-user://opt/tinyos-2.x/tos/lib/net/zigbee/apps/AssociationExample/make micaz $avroraz-user://opt/tinyos-2.x/tos/lib/net/zigbee/apps/AssociationExample/cp build/micaz/main.exe /opt/avroraZ/avrora/jars/coordinator.elf 3) Compile and give ELF extension to the device association example application in tinyos (include the define TYPE_DEVICE END_DEVICE inside the header associationexample.h) $avroraz-user://opt/tinyos-2.x/tos/lib/net/zigbee/apps/AssociationExample/make micaz $avroraz-user://opt/tinyos-2.x/tos/lib/net/zigbee/apps/AssociationExample/cp build/micaz/main.exe /opt/avroraZ/avrora/jars/device.elf 4) Run avroraZ passing the configuration file through the -config-file option and the two applications into a pair of wsn nodes $avroraz-user://opt/avroraZ/avrora/jars/java -jar avroraZ.jar -config-file=./config_association.txt coordinator.elf device.elf Loading coordinator.elf...[OK: 0.093 seconds] Loading device.elf...[OK: 0.029 seconds] =={ Simulation events }======================================================= Node Time Event ------------------------------------------------------------------------------ 0 0:00:04.97 ----> 00.00.00.0F.A7.0F.40.88.A7.34.12.FF.FF.00.00.46.CF.80.00.E6.1D 0.660 ms (Beacon A7) 1 0:00:04.97 <==== 00.00.00.0F.A7.0F.40.88.A7.34.12.FF.FF.00.00.46.CF.80.00.E0.E9 0.660 ms 0 0:00:05.95 ----> 00.00.00.0F.A7.0F.40.88.A8.34.12.FF.FF.00.00.46.CF.80.00.D5.96 0.660 ms (Beacon A8) 1 0:00:05.95 <==== 00.00.00.0F.A7.0F.40.88.A8.34.12.FF.FF.00.00.46.CF.80.00.E0.E0 0.660 ms 0 0:00:06.94 ----> 00.00.00.0F.A7.0F.40.88.A9.34.12.FF.FF.00.00.46.CF.80.00.9C.4E 0.660 ms (Beacon A9) 1 0:00:06.94 <==== 00.00.00.0F.A7.0F.40.88.A9.34.12.FF.FF.00.00.46.CF.80.00.E0.EC 0.660 ms 0 0:00:07.93 ----> 00.00.00.0F.A7.0F.40.88.AA.34.12.FF.FF.00.00.46.CF.80.00.66.36 0.660 ms (Beacon AA) 1 0:00:07.93 <==== 00.00.00.0F.A7.0F.40.88.AA.34.12.FF.FF.00.00.46.CF.80.00.E0.E6 0.660 ms 0 0:00:08.92 ----> 00.00.00.0F.A7.0F.40.88.AB.34.12.FF.FF.00.00.46.CF.80.00.2F.EE 0.660 ms (Beacon AB) 1 0:00:08.92 <==== 00.00.00.0F.A7.0F.40.88.AB.34.12.FF.FF.00.00.46.CF.80.00.DE.E5 0.660 ms 0 0:00:09.90 ----> 00.00.00.0F.A7.0F.40.88.AC.34.12.FF.FF.00.00.46.CF.80.00.92.C7 0.660 ms (Beacon AC) 1 0:00:09.90 <==== 00.00.00.0F.A7.0F.40.88.AC.34.12.FF.FF.00.00.46.CF.80.00.E0.DF 0.660 ms 1 0:00:10.87 ----> 00.00.00.0F.A7.15.23.C8.E2.34.12.00.00.FF.FF.01.00.00.00.01.00.00.00.01.00.2D.11 0.849 ms (Ass request) 0 0:00:10.87 <==== 00.00.00.0F.A7.15.23.C8.E2.34.12.00.00.FF.FF.01.00.00.00.01.00.00.00.01.00.E0.E2 0.849 ms 0 0:00:10.87 ----> 00.00.00.0F.A7.05.12.00.E2.6F.F0 0.346 ms (Acknowledgement from coordinator) 1 0:00:10.87 <==== 00.00.00.0F.A7.05.12.00.E2.E0.DF 0.346 ms 1 0:00:10.88 ----> 00.00.00.0F.A7.10.63.C0.E3.34.12.01.00.00.00.01.00.00.00.04.97.2D 0.692 ms (Data request from device) 0 0:00:10.88 <==== 00.00.00.0F.A7.10.63.C0.E3.34.12.01.00.00.00.01.00.00.00.04.DF.E6 0.692 ms 0 0:00:10.89 ----> 00.00.00.0F.A7.0F.40.88.AD.34.12.FF.FF.00.00.46.CF.80.00.DB.1F 0.660 ms (Beacon AD) 1 0:00:10.89 <==== 00.00.00.0F.A7.0F.40.88.AD.34.12.FF.FF.00.00.46.CF.80.00.E0.EE 0.660 ms 0 0:00:10.90 ----> 00.00.00.0F.A7.1D.23.CC.F1.34.12.01.00.00.00.01.00.00.00.34.12.00.00.00.00.00.00.00.00.02.04.00.00.46.3E (Ass response) 1 0:00:10.90 <==== 00.00.00.0F.A7.1D.23.CC.F1.34.12.01.00.00.00.01.00.00.00.34.12.00.00.00.00.00.00.00.00.02.04.00.00.DE.EC 1 0:00:10.90 ----> 00.00.00.0F.A7.05.02.00.F1.5E.91 0.346 ms (Acknowlegement from device) 0 0:00:10.90 <==== 00.00.00.0F.A7.05.02.00.F1.E0.DF 0.346 ms 0 0:00:11.88 ----> 00.00.00.0F.A7.0F.40.88.AE.34.12.FF.FF.00.00.46.CF.80.00.21.67 0.660 ms (Beacon AE) 1 0:00:11.88 <==== 00.00.00.0F.A7.0F.40.88.AE.34.12.FF.FF.00.00.46.CF.80.00.DF.ED 0.660 ms ============================================================================== Simulated time: 110592000 cycles Time for simulation: 7.647 seconds Total throughput: 28.924284 mhz Throughput per node: 14.462142 mhz =={ Packet monitor results }================================================== Node sent (b/p) recv (b/p) corrupted (b) lostinMiddle(p) ------------------------------------------------------------------------------ 0 214 / 10 60 / 3 0 0 1 60 / 3 214 / 10 0 0
