Monitoring


Avrora's simulator offers the ability to install execution monitors that instrument the program in order to study and analyze its behavior. The "simulate" action supports this option that allows a monitor class to be loaded which will instrument the program before it is run and then generate a report after the program has completed execution. Execute the JAR file followed by the "-help monitors" option to obtain a list of all the options available. Here we only explain the monitors that we think are more interesting for IEEE 802.15.4 standard emulations.

C- print monitor
The "print" monitor watches a dedicated range of SRAM for instructions to print the value stored there. The new feature added in this monitor is that you do not need to know the location of the variable to print. In avroraZ you pass the name of the variable with the -VariableName option and the emulator looks inside the map file the variable to watch. You have to indicate also the type of the variable to print by setting the first byte of the variable to one value of the indicated on the table below. If you do not indicate the format in the first byte, the variable will be printed without any formatting.

Command Format
0x01 2 bytes hexadecimal
0x02 String
0x03 2 bytes integer
0x04 4 bytes hexadecimal
0x05 4 bytes integer
Other value No format added by emulator


Another new option added to this monitor is the possibility of login the nodes printing in files. In order to activate that option you should include -logfile option plus the name of the file to log in. The emulator will create a new log file for every new node created in the network adding the node id at the end of it.

Below there is an example of how to print the different format variables in avroraZ that could be use in any wireless sensor operative systems C language based. It is worth to note that the monitor is triggered when the first byte of the address is written and where the command value should be written. This byte should be therefore the last to be written.

#include <stdarg.h>
// Comment out the line below to DISABLE avroraZ print statements
#define AVRORAZ
#define DEBUGBUF_SIZE 64
volatile char debugbuf1[DEBUGBUF_SIZE+1];
//debugbuf (same as debugbuf[1]) refers to the data part
char *debugbuf;
//avroraZ c-print monitor will trigger when debugbuf1[0] address is written, where the commands are added
debugbuf = &debugbuf1[1];
#ifdef AVRORAZ
    #define printChar(__char) {    \
        debugbuf[0] = __char;    \
        debugbuf[1] = 0;        \
        writedebug1(2);    \
    }
    #define printInt8(__char) {    \
        debugbuf[0] = __char;    \
        debugbuf[1] = 0;        \
        writedebug1(3);            \
    }
    #define printInt16(__int) {    \
        debugbuf[0] = (uint8_t)(uint16_t)__int&0x00ff;    \
        debugbuf[1] = (uint8_t)((uint16_t)__int>>8)&0x00ff;        \
        writedebug1(3);        \
    }
    #define printInt32(__int) {    \
        debugbuf[0] = (uint8_t)((uint32_t)__int)&0x00ff;    \
        debugbuf[1] = (uint8_t)((uint32_t)__int>>8)&0x00ff;    \
        debugbuf[2] = (uint8_t)((uint32_t)__int>>16)&0x00ff;    \
        debugbuf[3] = (uint8_t)((uint32_t)__int>>24)&0x00ff;    \
        writedebug1(5);        \
    }
    #define printStr(__str) { \
        strcpy(debugbuf, __str);    \
        writedebug1(2);    \
    }
    #define printHex8(__char) { \
        debugbuf[0] = __char;   \
        debugbuf[1] = 0;        \
        writedebug1(1);        \
    }
    #define printHex16(__int) { \
        debugbuf[0] = __int&0x00ff; \
        debugbuf[1] = (__int>>8)&0x00ff;     \
        writedebug1(1);        \
    }
    #define printHex32(__int) { \
        debugbuf[0] = (uint8_t)((uint32_t)__int)&0x00ff; \
        debugbuf[1] = (uint8_t)((uint32_t)__int>>8)&0x00ff;    \
        debugbuf[2] = (uint8_t)((uint32_t)__int>>16)&0x00ff;   \
        debugbuf[3] = (uint8_t)((uint32_t)__int>>24)&0x00ff;   \
        writedebug1(4);    \
    }
    #define printfUART(__format, __args...) {             \
    //call your own OS print function here
    }
#endif
//This function writes in the command byte value that indicates the printing format option for the variable
void writedebug1(uint8_t a)
{
    debugbuf1[0] = a;
}
 

Afterwards, here is an example of how to use the print functions in your own OS application and how to get the printing results in avroraZ from the c-print monitor:

printChar('a');
printChar('\n');
printStr("Integers: ");
printInt8(255);
printInt16(65535);
printInt32(42949672);
printChar('\n');
printStr("Hexadecimals: ");
printHex8(0xff);
printHex16(0xffff);
printHex32(0xffffffff);
printfUART("\n abcd %i %x",1,0x1234);
 

Running the application with avroraZ produces the following result (the option -VariableName=debugbuf1 is not needed here since this is the default value): 

java -jar avroraZ.jar -monitors=c-print -logfile=print.log -report-seconds app.elf
 
The results into the file print.log0 are:
 
a
Integers: 2556553542949672
Hexadecimals: 00FFFFFFFFFFFFFF
abcd 1 00001234
 

As we have seen you can also use already formatted variables with the c-print monitor calling a standard print function (from printfUART() above):. For that, you do not need to add any byte command, the chars will be printed by the monitor as they are received by the application. however, you have to be aware that the watch in avroraZ will fire when the first byte in the variable is written. This kind of printing is not recommended for most of the applications since the micro controller will consume more memory and time doing the formatting, while if the formatting is left to avroraZ you will not consume any memory or clock ticks when printing information. On the other hand, it is better in the way that you can use only one print function for all variable types. You can get here the complete file used for the Tinyos operative system which contents all print functions defined above.

Sniffer monitor

The sniffer monitor creates the format required by the Daintree Sensor Network Analyzer software to analyze IEEE 802.15.4 compliant protocols running on the cc2420 radio chip. This is a comprehensive and powerful solution that takes you from development through to testing, commissioning and maintenance. It provides unique visualization capabilities that show all network devices and interactions simultaneously, and intuitive tools that simplify complex tasks including multi-node captures and commissioning.

You should use the -monitors = sniffer option plus one of the following features of it:

  1. Received: it will track received packets by every node in the network.
  2. Transmitted: it watches transmitted packets in every node of the network.
  3. Print: it activates screen printing.
  4. FileName=whateverfilename.dcf it activates file printing into the file that you give to avroraZ

As follows there is an example of how to use the sniffer monitor and an example of the Daintree Sensor Network Analyzer output.

java -jar avroraZ.jar -platform=micaz -monitors=sniffer -Transmitted -FileName=output.dcf -topology=topol.top 
-simulation=sensor-network -nodecount=1,10 coordinator.elf router.elf

In the example, we are creating 1 coordinator and 10 routers that would associate following the IEEE 802.15.4. If you feed the resulting output.dcf file into the network topology you will be the following features:

  • Visualize and understand network and device behavior with system-level network analysis.
  • Analyze and debug associated protocols with detailed packet analysis.
  • Obtain measurements on network, device and route performance.
  • Support for TI-specific features including location engine and over-the-air downloads.
  • Cross-reference information by using context filters to quickly obtain a filtered packet list by selecting similar packets or objects from visual displays.
  • Analyze new or custom application profiles with XML-based SoftProfiles™ and API.
  • Monitor live networks and record operation for future review (with playback controls including pause, fast forward and breakpoints). Use to test development, verify commissioning and manage deployed networks.
  • Suitable for all size networks: from small to very large.
  • Powerful and intuitive standards-based commissioning providing over-the-air configuration and integration with the SNA’s rich visualization and monitoring capabilities.

You can see below a screen shot of the Daintree Sensor Network Analyzer after feeding it with the resulting file output.dcf of this command line entry.

Daintree.jpg

Energy monitor
The energy monitor traces energy consumption. It was created by Olaf Landsiedel under the AEON (Accurate Prediction of Power Consumption) group. The monitor models the state of every single component at every point in time during program execution. Therefore, each hardware component power usage can be monitored in the emulator. Furthermore, energy profiling is available enabling a breakdown to individual source code routines. Such analysis allows to determine, how much energy the CPU spends in various routines like sensing, routing, and low level transmission and reception. Thus, it allows to identify procedures consuming much energy and so to improve their implementation.

In avroraZ we extended AEON to report also the energy consumption of the cc2420 radio chip that was not available before. For that, we created the following consumption modes for the cc2420 radio chip model as defined in the data sheet:

  1. OFF: we assume that the power consumption is 0 when the power mode is OFF
  2. PD: in power down mode the current consumption is typically 20uA
  3. IDLE: when idle mode is set the current consumtion goes to 426 uA
  4. TX: in transmit mode the consumption will depend on the output power level ranging from 8.5 mA to 17.4 mA (see cc2420 data sheet for more details)
  5. RX: when receive mode is active the current consumption is 18.8 mA

In order to use the energy monitor you will have to use the option -monitors=energy. You can indicate the battery that the nodes have in Joules (i.e. -battery=3.5) so during simulation, the energy consumption of each node is tracked, and if the node runs out of battery, it will be shut down and removed from the simulation. Results will be logged into a file when the option log=Filename is activated. If this is the case each node's energy state transitions will be written to Filename.#, where '#' represents the "node ID". The file will include logging information like the current draw of all devices, and the state changes can be loaded into Matlab, Gnuplot, Excel... for further processing and visualization.

Below there is an example of the output obtained for the energy monitor when a PAN coordinator is following the association procedure of the IEEE 802.15.4 std. You can also get first lines of the output file here

java -jar avroraZ.jar -platform=micaz -monitors=energy -battery=2340 logfile=bat.log -topology=topol.top -simulation=sensor-network
-nodecount=1,10 coordinator.elf router.elf

=={ Energy consumption results for node 0 }===================================
Node lifetime: 368640000 cycles,  50.0 seconds
 
CPU: 0.59610910843042 Joule
   Active: 0.16951190374117023 Joule, 55056029 cycles
   Idle: 0.4265972046892497 Joule, 313583971 cycles
   ADC Noise Reduction: 0.0 Joule, 0 cycles
   Power Down: 0.0 Joule, 0 cycles
   Power Save: 0.0 Joule, 0 cycles
   RESERVED 1: 0.0 Joule, 0 cycles
   RESERVED 2: 0.0 Joule, 0 cycles
   Standby: 0.0 Joule, 0 cycles
   Extended Standby: 0.0 Joule, 0 cycles
 
Yellow: 0.019007899739583334 Joule
   off: 0.0 Joule, 347406448 cycles
   on: 0.019007899739583334 Joule, 21233552 cycles
 
Green: 5.013020833333334E-8 Joule
   off: 0.0 Joule, 368639944 cycles
   on: 5.013020833333334E-8 Joule, 56 cycles
 
Red: 5.013020833333334E-8 Joule
   off: 0.0 Joule, 368639944 cycles
   on: 5.013020833333334E-8 Joule, 56 cycles
 
Radio: 2.8176916453945964 Joule
   Power Off:            : 2.46484375E-10 Joule, 30288 cycles
   Power Down:           : 5.9293619791666674E-8 Joule, 7286 cycles
   Idle:              : 4.137552734375E-5 Joule, 238696 cycles
   Receive (Rx):         : 2.8171811704101564 Joule, 368271513 cycles
   Transmit (Tx):        15:   : 4.690399169921875E-4 Joule, 92217 cycles
 
SensorBoard: 0.105 Joule
   on:  : 0.105 Joule, 368640000 cycles
 
flash: 3.0E-4 Joule
   standby: 3.0E-4 Joule, 368640000 cycles
   read: 0.0 Joule, 0 cycles
   write: 0.0 Joule, 0 cycles
   load: 0.0 Joule, 0 cycles
 

In case you prefer to get the power consumption of all the cpu instructions the -monitors=energy-profile option provides a breakdown to the procedures and records the exact cycles spend in each procedure. You can see below an example for coordinator node with the energy-profile option activated

java -jar avroraZ.jar -platform=micaz -monitors=energy-profile -topology=topol.top -simulation=sensor-network -nodecount=1,10 
coordinator.elf router.elf
=={ Energy breakdown for node 1 }=============================================
notation: procedureName@Address: cycles
   MacM$create_data_request_cmd@5098: 157
   TOS_post@2550: 9792
   MQueM$MemQueue$full@4652: 561
   LedsC$Leds$redOff@2520: 54
   MacM$scan_request@5976: 107
   HPLCC2420M$HPLCC2420$write@5748: 1343
   PhyM$PLME_SET$request@5904: 50
   MacM$neighbour_add_new@11534: 498
   MacM$perform_csma_ca_slotted@7510: 1515
   TimerAsyncM$TimerAsync$set_bi_sd@1846: 3619
   PhyM$PLME_SET_TRX_STATE$request@6052: 473
   MQueM$MemQueue$size@5314: 1503
   RandomLFSR$Random$rand@2406: 183
   MQueM$MemQueue$pop@4344: 2884
   MacM$MLME_SET$request@4506: 89
   MQueM$MemQueue$curr@5532: 2210
   MacM$TimerAsync$backoff_fired@6166: 620580
   MacM$data_indication@12112: 12175
   main@23758: 3208029
   AssociationExampleM$MLME_ASSOCIATE$confirm@11226: 176
   sprintf@6956: 9120
   LedsC$Leds$yellowOff@2464: 270
   MQueM$MemQueue$init@2612: 108
   HPLCC2420M$HPLCC2420$cmd@5656: 561
   TimerM$signalOneTimer@21270: 1783
   TimerM$HandleFire@3488: 358175
   TimerAsyncM$TimerAsync$set_backoff_symbols@2340: 36
   sleeping: 307682512
 

Packet monitor
The packet monitor prints in the screen packets sent and received by every node in the sensor network. In order to activate it the user has to type the option -monitors = packet. Sub options of the packet monitors are:
- show-bits: this option enables the printing of packet contents in bits rather than in bytes. Default is false.
- show-packets: it enables the printing of packets as they are transmitted. Default is true.
- start-symbol: when this option is present, the packet monitor will attempt to match the start symbol of packet data in order to display both the preamble, start symbol, and packet contents. Not present as default.

As follows we present a simple example of packet monitoring for the micaz platform where we can analyse the different fields of the packet based on the IEEE 802.15.4 standard. In the example we create a network with two motes where they are in range (see topology). Mote 0 sends packets in a fixed period of time (sender.elf), while mote 1 listens the network waiting for packets to be received (receiver.elf). 

java -jar avroraZ.jar topology=topology.top -monitors=packet -seconds=2.0 -nodecount=1,1 sender.elf receiver.elf
=={ Simulation events }=======================================================
Node          Time   Event
------------------------------------------------------------------------------
   0    0:00:01.35  ----> 00.00.00.0F.A7.10.41.88.00.22.00.FF.FF.01.00.06.00.01.00.01.6A.AE  0.692 ms
   1    0:00:01.35  <==== 00.00.00.0F.A7.10.41.88.00.22.00.FF.FF.01.00.06.00.01.00.01.D2.C8  0.692 ms
   0    0:00:01.59  ----> 00.00.00.0F.A7.10.41.88.01.22.00.FF.FF.01.00.06.00.01.00.02.7C.9D  0.692 ms
   1    0:00:01.59  <==== 00.00.00.0F.A7.10.41.88.01.22.00.FF.FF.01.00.06.00.01.00.02.D1.B6  0.692 ms
   0    0:00:01.83  ----> 00.00.00.0F.A7.10.41.88.02.22.00.FF.FF.01.00.06.00.01.00.03.C2.88  0.692 ms
   1    0:00:01.83  <==== 00.00.00.0F.A7.10.41.88.02.22.00.FF.FF.01.00.06.00.01.00.03.D0.C2  0.692 ms
==============================================================================
Simulated time: 14745600 cycles
Time for simulation: 3.843 seconds
Total throughput: 7.6740046 mhz
Throughput per node: 3.8370023 mhz
=={ Packet monitor results }==================================================
Node     sent (b/p)          recv (b/p)    corrupted (b)   lostinMiddle(p)
------------------------------------------------------------------------------
   0        66 / 3                0 / 0                0       0
   1         0 / 0               66 / 3                0       0
 

Here, the packet monitor has printed the packets as they have been transmitted / received (depending on the arrow direction) in bytes in hexadecimal format separated by dots. Afterwards, a report is printed showing the number of bytes/packets sent and received by every node, the number of corrupted bytes which would indicate that the packet has been complete received but with errors due to collision with other packets and the number of packets lost in the middle of a reception due to radio environment changes (i.e. a person walking between the radio link).

The content of the first packet sent by node 0 at 01:35 seconds could be analysed being split in the following 802.15.4 std fields:

1. Preamble & Start Frame Delimiter (SFD): 00.00.00.0F.A7

2. Physical Header (PHR)
Frame length: 10 (16 octects)

3. MAC Physical Data Unit (MPDU)
Frame Control Field (FCF): 41.88
Destination Sequence Number (DSN): 00
Destination PANid: 22.00
Destination address: FF.FF (Broadcast address)
Source address: 01.00

4. MAC payload (its values are application dependent)
AMType: 06 (field
Nodeid:00.01
Counter: 00.01

5. MAC Footer
Frame Check Sequence: 6A.AE (this field is changed to RSSI + Correlation value + CRCok in a received packet)