LinkBench application README

1. Authors/Contacts:
   -----------------
   veresskrisztian@gmail.com (Krisztian Veress, SZTE University, Szeged, Hungary )
	
2. Description:
   ------------
   This application's main goal is to provide a universal framework that is able to 
   conduct reproducible tests/benchmarks in order to analyze and measure the radio-
   communication generated by the applied benchmark.
   
   The focus is on the radiocommunication, hence benchmarks are given by communica-
   tion links in a directed graph representation. For specifying benchmarks, see
   UserdefinedBenchmarks.h.
   
3. TinyOS network requirements:
   ----------------------------
   To use the framework, one needs 
    - a BaseStation mote with TOS_NODE_ID = 0.
      WARNING! When programming the BaseStation TOSH_DATA_LENGTH must be set to 110!
      
    - multiple 'test motes' with TOS_NODE_IDs 1,2,3, ... based on the required mote 
      count of the benchmark to be run
   
   One should take note that mote's channels are set to the same value (based on the
   DEF_CHANNEL env variable), so when using different radio chips, compile time de-
   finitions such as
    -DRF230_DEF_CHANNEL  = $(DEF_CHANNEL), and
    -DCC2420_DEF_CHANNEL = $(DEF_CHANNEL), ...
   
   are preset in the Makefile. To change this channel, set the DEF_CHANNEL variable 
   to the required number:
     - in Unix systems : export DEF_CHANNEL=22
     - in Windows      : set DEF_CHANNEL=22    

4. Quick Install Guide:
   --------------------
    a, Connect one mote the your PC, and program it to be a BaseStation.
       Check on which port it is connected ( with motelist for example), and remember it.
    b, Connect as much motes as you would like to program to be benchmark 'test motes'.
    c, Either program them as you like, or execute the minstall.sh script:
       ./minstall.sh -i /dev/ttyUSBX
       where /dev/ttyUSBX is the device on which the BaseStation lives.
    d, Go to the javasrc directory and type:
       ant
       This will compile and assemble the Java sources.
    e, Got to the javabin directory created by the previous command, and execute:
       chmod +x *.sh
       ./linkbench.sh --help
   
4. Programming the motes:
   ----------------------
   To program the 'test motes', simply execute the make command with appropriate options.
   Examples:
    - iris mote connected to MIB510 programmer on the first USB slot, assign TOS_NODE_ID=1 
    Unix   : make iris install,1 mib510,/dev/ttyUSB0
    Windows: make iris install,1 mib510,COM1
  
    - telosa/telosb motes, assign TOS_NODE_ID=2 and 3
             make telosa install,2
             make telosb install,3
    - ...
              
    4./a 32-bit statistics support:
         --------------------------
         Statistics are generally 16-bit integers. If overflows are experienced, you should
         consider setting the USE_32_BITS compile-time flag in the Makefile:
         CFLAGS += -DUSE_32_BITS
         
    4./b Defining and using benchmarks:
         ------------------------------
         To define your own benchmarks, do it in the UserdefinedBenchmarks.h file where
         additional information is available on how you can do that. After doing that, 
         count the maximum of edges used in all your benchmarks, and set it in the Makefile:
         CFLAGS += -DMAX_EDGE_COUNT=8
         
         You can exclude benchmark sets by setting the EXCLUDE_STANDARD or 
         EXCLUDE_USERDEFINED flag in the Makefile.
                 
5. Compiling the PC program:
   -------------------------
    The application comes shipped with a PC-based control program located in the javasrc 
    directory. The program depends on the tinyos.jar (TinyOS Java components) file, which 
    comes with your TinyOS development libraries.
    
    In order to successfully compile, the code needs mig-generated classes, so make sure
    you have made a 'make <target>' for any target before compiling Java sources. Also you
    gonna need the ant (at least 1.7) utility which is a make system for Java.
    
    If everything is prepared, just type:
      ant
    in the javasrc directory. This will create a javabin directory in the root directory 
    of the project.
        
    Then, executing either of the followings in the javabin folder:
      java -jar linkbench.jar --help
      sh linkbench.sh --help
      ./linkbench --help          (if you have chmod-ed linkbench.sh to be executable)
    which will give you details on how this application can be used.
    
6. Using the application:
   ----------------------
   To use the application, power-on all programmed 'test-motes', plug in the BaseStation 
   mote to your PC, and set the MOTECOM variable to point to the BaseStation mote.
   Examples:
    - iris BaseStation mote connected to MIB510 programmer on the first USB slot
      export MOTECOM=serial@/dev/ttyUSB1:iris
    - telosb BaseStation mote connected on the second USB slot
      export MOTECOM=serial@/dev/ttyUSB2:telosb
      
   Then, execute the following:
     java -jar linkbench.jar -b 10
     ./linkbench -b 10
   which will eventually execute the 0th benchmark, and print the results on your screen. 
   For more options, see 
     java -jar linkbench.jar --help
     ./linkbench --help
      
7. Status indicators on 'test-motes':
   ----------------------------------
   The code is written in a way so that the status of each 'test mote' can be tracked 
   during the whole process. 
    0. All LEDs   off : motes are in invalid state. This can only occur if you specify a
                        benchmark to be run that is not available in the benchmark database.
                        Do not worry, just reset them (java Benchmark -r), or simply run a 
                        benchmark which is available.
    1. LED 1       on : mote is reset, standing by, waits for running a benchmark.
    2. LED 2       on : mote received configuration, waits for handshake with the PC program
    3. LED 1,LED 2 on : mote successfully configured, handshake is done
    4. LED 3       on : benchmark is currently running
    5. LED 3,LED 1 on : mote is in so-called 'lastchance' state -- being a pre-stop phase of 
                        the benchmark
    6. LED 3,LED 2 on : mote finished the benchmark, statistics are ready
    7. LED 3,LED 2 on : mote is uploading values to PC
    
   Motes should not be in states 2,3 and 5 for LONG TIME, if it happens, you can reset them 
   by invoking either of the followings:
     java -jar linkbench.jar
     ./linkbench -r
     
   ( Note that this will reset ALL motes! )
   
8. Known limitations:
   ----------------
   - Configuration and data uploading is done in a one-hop manner, so 'test-motes' must be in the radio
     reception range of the BaseStation.

