Match Execution Framework

Objective

Use an OEDL script to execute either a competitive-style or cooperative-style game for both Wildcard and Preliminary matches. Even though the use of the framework is illustrated by using 2 house bots (or 3 in the case of a cooperative game), in the actual competition, the teams will use their own radio implementations. An additional purpose of the framework is to provide certification to the images that teams submit for the Wildcard and Preliminary matches: teams must use the script in this framework to certify their image before submission. Certification is required for both competitive and cooperative style matches.

The OEDL script uses three pair of nodes: dsc-teamA, dsc-teamB, dsc-teamC (the actual topology descriptions are system:topo:dsc-team{A,B,C}). The competitive matches will use teamA and teamC nodes, while cooperative matches will use teamA, teamB and teamC nodes (contestant radios will be only on teamA nodes for the Wildcard tournament, while house bots will be using teamB and teamC nodes); configurations should be considered to be fixed and will be changed only in the case of hardware failures.

Hardware / Software Resources Used

1. Four grid nodes with USRP N210s (two for each team) for competitive match and six nodes with USRP N210s for cooperative match (two for each team).
2. dsc-wbot1.ndz,dsc-wbot2.ndz,dsc-wbot3.ndz: house bot disk images with the prerequisite software to configure the USRPs and execute a house radio bot.
3. team-image.ndz: disk image that contains the team's radio.
4. Scoring packet server: This is the server that resides on the infrastructure machine and is used as the source of data packets as well as the sink for teams to submit received packets for scoring.
5. dsc-wildcard.rb: this is the OEDL experiment script to execute the matches.

Teams must ensure that their images contain /root/dsc-code_tx and /root/dsc-code_rx. Only these names will be used for testing and scoring. Further, these executables/scripts must be able to receive as input three parameters:

• -f 1700000000 : option for specifying the center frequency (in this example 1.7GHz)
• -s idb2 : option for specifying the packet server host name (in this example idb2)
• —mode COMP or —mode COOP : option that specifies whether the match style is a competitive or cooperative match.

Please note that idb2 and 1700000000 are provided merely for illustration purposes and that the teams must allow for the values passed to be entered by the evaluators. Finally, no modifications to this execution format is allowed, and no additional fields will be used during evaluation.

Teams should also implement their radios such that packets are drawn from port 5123, while packets are delivered to port 5125 on the packet server specified with the -s argument. An illustration of this can be seen in the Python code in the table below:

Transmitter

Receiver

class dsc_pkt_src(object): def __init__(self, server, port=5123 ): self.pkt_size = 1440 # 1440 bytes of data self.pkt_server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self.pkt_server_socket.connect((server,port)) self.MESSAGE = struct.pack('!l', self.pkt_size) self.pkt_server_socket.send(self.MESSAGE) def read(self): try: data = self.pkt_server_socket.recv(self.pkt_size) except socket.error: print "Connection to packet server closed" return '' self.pkt_server_socket.send(self.MESSAGE) return data

class dsc_pkt_sink(object): def __init__(self, server, port=5125): self.pkt_sink_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self.pkt_sink_socket.connect((server,port)) def send(self, payload): try: self.pkt_sink_socket.recv(4) self.pkt_sink_socket.send(payload) except socket.error: print "Connection to packet sink closed"

Teams are also required to label their image with the image name they intend to use for submission, which should be stored in file named /.orbit_image on the root of the filesystem before node is saved. For example, if the team intends to submit an image with image name orbit-bot.ndz the /.orbit_image file should contain orbit-bot.

Packet Server

The packet server application running on the infrastructure machine has

• a packet source at port 5123 which serves fixed (1440 bytes). Clients can request packets from server with the following handshaking process after a TCP socket connection has been established:
  1. client sends server the request with packet size as 4 byte word (ignored for the matches).
  2. server sends client a single data packet (fixed at 1440 bytes)

The packet source sends out the first packet to each team only after it receives packet requests from all the teams (2 teams for competitive match and 3 for co-operative) and the start signal from the experiment script. It closes transmit socket on the first packet request after the end-of-file is reached or at the 180 second timeout. It will report the score via an email to whoever has a grid reservation (if at least one packet is received correctly).

• a packet sink at port 5125 which receive packets from client and verifies that it matches one of the sent packets. Clients can send data to server after a connection has been established:
  1. server sends client a ready packet (4 byte word).
  2. client sends server data for scoring.

• a control interface used by the experiment script to prepare the packet server for a match by setting its mode, duration etc., and to send a start signal so the packet source can send packets to the teams.

Setting up the arena

• To get started, first make a reservation on the ​Orbit Scheduler for using the Grid.
• After logging into grid console, make sure all nodes are turned off (in the example below, turn off all the nodes in the grid):

  username@console.grid:~$ omf tell -a offh -t system:topo:all
  

• Verify state of node before continuing. Make sure nodes are in the POWEROFF state.

  username@console.grid:~$ omf stat
  

• Image the two nodes to be used for the first team's radios (team A nodes):

  username@console.grid:~$ omf load -i dsc-wbot1.ndz -t system:topo:dsc-teamA
  

In the case of Wildcard matches these two nodes will receive the competitor's image (and hence replace the house bot image name with the team's image name).

• Image the two nodes to be used for the second team's radios (in this case team C nodes):

  username@console.grid:~$ omf load -i dsc-wbot2.ndz -t system:topo:dsc-teamC
  

• FOR COOPERATIVE MATCHES: image the third pair of nodes to be used for the third team's radios (in this case team B nodes):

  username@console.grid:~$ omf load -i dsc-wbot3.ndz -t system:topo:dsc-teamB
  

• Turn nodes back on and verify they are in POWERON state

  username@console.grid:~$ omf tell -a on -t system:topo:dsc-teamA
  username@console.grid:~$ omf tell -a on -t system:topo:dsc-teamC
  

• Download the OEDL experiment script to your local directory.

  username@console.grid:~$ wget http://www.orbit-lab.org/raw-attachment/wiki/DSC/zdc_framework/dsc-challenge.rb
  

Running the experiment script

The experiment script will execute /root/dsc-code_tx and /root/dsc-code_rx on the source and sink respectively (please note that there are no suffixes), for both (all three) pairs of nodes. Teams must ensure that their images contain /root/dsc-code_tx and /root/dsc-code_rx. No modifications to this execution format is allowed. The sender module draws packets from a packet server, while the sink module delivers packets to the same packet server.

• Type to following command to run the experiment. This will start the packet server, start the source and sink for all teams and release the packet source, wait for 180 seconds and then terminate the match. The actual transmission/reception will run.

For competitive matches, the command line is:

username@console.grid:~$ omf exec dsc-challenge.rb -- --mode COMP

For cooperative matches, the command line is:

username@console.grid:~$ omf exec dsc-challenge.rb -- --mode COOP

• The output should look similar to the following:

  username@console.grid:~# omf-5.4 exec dsc-challenge.rb -- --mode COMP
  
   INFO NodeHandler: OMF Experiment Controller 5.4 (git 5385228)
   INFO NodeHandler: Slice ID: default_slice (default)
   INFO NodeHandler: Experiment ID: default_slice-2013-07-17t10.04.54.210-04.00
   INFO NodeHandler: Message authentication is disabled
   INFO Experiment: load system:exp:stdlib
   INFO property.resetDelay: resetDelay = 220 (Fixnum)
   INFO property.resetTries: resetTries = 1 (Fixnum)
   INFO Experiment: load system:exp:eventlib
   INFO Experiment: load system:exp:winlib
   INFO Experiment: load dsc-challenge.rb
   INFO property.team1: team1 = "dsc-teamA" (String)
   INFO property.team2: team2 = "dsc-teamC" (String)
   INFO property.team3: team3 = "dsc-teamB" (String)
   INFO property.freq: freq = 1700000000 (Bignum)
   INFO property.server: server = "idb2" (String)
   INFO property.port: port = 5123 (Fixnum)
   INFO property.runtime: runtime = 180 (Fixnum)
   INFO property.mode: mode = "COMP" (String)
   INFO Topology: Loaded topology 'system:topo:dsc-teamA'.
   INFO Topology: Loaded topology 'system:topo:dsc-teamC'.
   INFO Topology: Loaded topology 'system:topo:dsc-teamB'.
   INFO exp: Connecting to packet server
   INFO stdlib: Waiting for nodes (Up/Down/Total): 2/2/4 - (still down: node20-19.grid.orbit-lab.org,node19-19.grid.orbit-lab.org) [0 sec.]
   INFO ALL_UP_AND_INSTALLED: Event triggered. Starting the associated tasks.
   INFO exp: Preparing packet server
   INFO exp: Request from Experiment Script: Wait for 2s....
   INFO exp: Start benchmark_rx,tx
   INFO exp: Request from Experiment Script: Wait for 10s....
   INFO exp: Sending signal to packet server to start serving packets
   INFO exp: Running the experiment
   INFO exp: Request from Experiment Script: Wait for 180s....
   INFO exp: Stoping the applcations
   INFO exp: Request from Experiment Script: Wait for 2s....
   INFO EXPERIMENT_DONE: Event triggered. Starting the associated tasks.
   INFO NodeHandler: 
   INFO NodeHandler: Shutting down experiment, please wait...
   INFO NodeHandler: 
   INFO run: Experiment default_slice-2013-07-17t10.04.54.210-04.00 finished after 3:30
  
  username@console.grid:~#
  

• Turn the nodes off

  username@console.grid:~$ omf tell -a offh -t system:topo:all
  

Submitting the image

NOTES: