=== Hurdle 2 (H2) ===

[[TOC(DSC*,depth=2)]]

=== Objective ===

The main objective of Hurdle 2 is to demonstrate an understanding of the basic principles of wireless communications and familiarity with USRP2/USRP N210 and GNU radio software tools by properly configuring and executing a basic transmitter/receiver communication system on a pair of radios on the ORBIT grid. The objective is to deliver a minimum of 2000 error-free packet in 12 seconds or less.  This is a "pass/fail" objective, and no benefit is obtained by achieving higher performance than other teams.  Upon successful completion, instructions for Hurdle 3 will be sent to the team leader. Teams are referred to [wiki:Documentation/GNURadio/Tutorials/Sandbox3 USRP tutorial] for general information regarding USRP2's or N210's on ORBIT. 

=== Instructions ===

WINLAB has created 16 virtual domains containing USRP2s and USRP N210s. Given the large quantity of teams participating in the Challenge hurdles, teams have been assigned specific times slots during which they may access specified virtual domains containing the USRP2 and USRP N210s. To ensure fairness, domains and time slots have been assigned such that teams rotate through different domains, and hence no team will have a significantly larger amount of time on a particular domain compared to other teams.  At the end of each 2-hour time slot, teams will be automatically removed from their domain to make that domain available for the next team. Please be advised that this means that experiments that have not completed will be terminated. 

a.) Look up your team's assigned time slot for a USRP virtual domain on the [https://www.orbit-lab.org/schedule/ scheduler]. These virtual domains have been labeled DCGNUR##. All  teams have been given their time assignments, with domain name and frequency band, in an initial email from the Challenge. Note that each domain has a corresponding frequency band that must be used with that domain.   The allowed frequency band can also be found using the online schedule by running the cursor over the virtual domain's name.  

Note that if a team does not use its time slot, then it will not be able to obtain a replacement time slot. Time slots have been assigned so as to give each team a fair and equitable exposure to USRP resources on ORBIT. No requests for additional time slots will be approved. 

b.) Access the GNURadio virtual domain at the reserved time using:
{{{
  ssh username@console.grid.orbit-lab.org 
}}}
For the rest of this description, we remind teams that the main ORBIT grid is a 20-by-20 array of nodes, several of which are equipped with USRP-family radios.  For discussion, we are assuming that the user reserved virtual domain DCGNUR01, which consists of node1-1 and node3-3 and is assigned a center frequency of 4.90GHz:

c.) Image the nodes with the Hurdle 2 gnuradio image and turn them on:
{{{
  omf load -i darpahurdle23.ndz -t system:topo:all
}}}
The execution and completion of this command will take several minutes as software is installed onto the nodes. 
{{{
  omf tell -a on -t system:topo:all
}}}
This command turns on the nodes and boots them into their operating system. Teams are advised to wait a few minutes before proceeding to the next step.

d.) Log into both nodes. This will require opening two separate sessions (i.e. in two separate windows). 

  i. In one window, do: 
{{{
    ssh root@node1-1
}}}
  ii. Open another window and do: 
{{{
    ssh root@node3-3
}}}

On each node, change the working directory to: 
{{{
  cd gnuradio/gr-digital/examples/narrowband
}}}

e.) Execute the transmitter and receiver on respective nodes with user-chosen parameters. Teams must select and adjust operating parameters to enable a successful link and get at least 2000 packets across the link without errors within 12 seconds time. As an example of the command for launching the receiver, the user might try: 

{{{
  root@node1-1:~/gnuradio/gr-digital/examples/narrowband# ./benchmark_rx2.py -f 2.41e9 -m bpsk --rx-gain 30 -v --bitrate 1M
}}}

Similarly, as an example of the command for launching the transmitter, the user might try:
{{{
  root@node3-3:~/gnuradio/gr-digital/examples/narrowband# ./benchmark_tx2.py --discontinuous --tx-amplitude=0.5 -f 5.0e9 -m dqpsk -v --tx-gain 15 --bitrate 500k 
}}}

In addition, you have to turn on the packets server by running the following code in the command line:
  {{{
/usr/local/bin/dsc_pkt_server_local --port 5123 
}}}

Also, be mindful that benchmark_tx2.py and benchmark_rx2.py were modified to work on the main grid. To successfully set up the receiver and transmitter, one should go into those files and modified the IP addresses that are associated with TCP if he or she doing it on the Sandboxes.  One can find out the neccesary IP address of the console by running the command 'ifconfig' if he or she is using linux. It should be the one after 'inet' in the 'eth1' section with the format of '10.xx.0.10'.

Teams should note that there are many different parameters available for them to adjust (information about these parameters may be found by using the flag --help at the command line). For example, users can adjust the following parameters: amplitude; receiver gain; transmitter gain; modulation type; and bitrate. Teams are advised that if they don't properly adjust parameters like gain and amplitude, then the receiver may not be able to properly demodulate, and thus will fall short of achieving the required 2000 successful packets in 12 seconds time. 

Regarding frequency selection, note that each node pair associated with a virtual domain has been assigned a specific frequency it is allowed to transmit on.  The ORBIT testbed monitors the frequencies used by each domain.  Failure to restrict usage to the assigned frequency band may result in termination of the time slot.
When packet transfers are successful, teams should expect to see output from the receiver like this:
{{{
  ok = True  pktno = 114  n_rcvd = 110  n_right = 106
  ok = True  pktno = 115  n_rcvd = 111  n_right = 107  
  ok = True  pktno = 116  n_rcvd = 112  n_right = 108
  ok = False pktno = 117 n_rcvd = 113  n_right = 108
  ok = True pktno = 118  n_rcvd = 114 n_right = 109
}}}
Teams are directed to http://gnuradio.org/ to find documentation related to benchmark_rx, which serves as the reference for benchmark_rx2.

Teams should be aware that the receiver has been modified to timeout after 1 minute.  If teams have not chosen their parameters appropriately, then the receiver will terminate without ever reaching 2000 successful packets.   The 1 minute timer starts as soon as benchmark_rx2 is initiated.  Teams should initiate benchmark_tx2 promptly after initiating benchmark_rx2 to avoid having the receiver terminate prematurely.  Also, teams should note that the packet source used by the transmitter only supports a limited number of simultaneous packet streams, and thus teams are advised that they may need to retry benchmark_tx2 if there are many teams making simultaneous demands on the packet server.

=== Validation ===

The radio modules benchmark_tx2 and benchmark_rx2 have been modified to log packets and parameters to the OML server with a database name that has the node name in it. Teams are evaluated on whether their first 2000 successfully delivered packets were delivered in 12 seconds or less. The evaluation time is calculated from the time the first packet is received to the time the 2000th correct packet is received.  After reception of the 2000th correct packet, benchmark_rx2 reports the total elapsed time. The receiver benchmark_rx2 has been modified to provide a final summary report describing the number of packets successfully received in one minute (at timeout) in case teams do not successfully receive 2000 packets. Teams are also advised that they may use the verbose flag --v  in the command line to debug their parameter selection. The use of the verbose flag causes some noticeable degradation in USRP performance, so teams should take this fact into account during testing.  
An automatic checker will monitor the database for a successful completion entry, at which time an email containing the instructions for Hurdle 3 will be sent to the team leader. 

As a reminder, this hurdle is not scored on performance.  Once your team has achieved the objective, there is no benefit in trying to further improve the performance.  Doing so will result in multiple database entries that might generate confusing messages and will reduce the amount of time your team has to work on Hurdle 3.

Questions or issues related to the hurdles should be sent by email to dsc-questions at orbit-lab dot org. Answers will be posted to a public forum site at [wiki:DSC/QandA Q&A].

Teams are reminded that the Qualification Period completes on March 5, 2013 at 23:59:59pm (Eastern). Submissions for Hurdle 3 must be turned in at the end of your time slot on that day.

We wish you the best of luck in completing the hurdle. 

--ORBIT Spectrum Challenge Team