= HowTo for ORBIT Demos =
This document describes the technical procedure for showing demonstrations on the ORBIT Indoor testbed. The objective here is to cover all the technical aspects so that any novice ORBIT user can run these demos. The current version covers two demos
  * Conference room demo
  * Streaming video demo

Future demos should also include their details here.

== Conference room demo ==

=== Objective ===
The objective of this demo is to show the failure of current implementations of IEEE 802.11 infrastructure networks in supporting a large number (O(10)) of clients. The cumulative throughput at the access point (AP) is the measured and it is shown that beyond a certain number of clients, there is a sharp drop rather than graceful degradation. It is hypothesized that the 802.11 bit-rate adaptation algorithm is the primary culprit for this behavior - the algorithm does not differentiate between collision-based packet loss and packet loss due to poor channel conditions. It incorrectly infers collision-based loss as an indication to drop the bit-rate, resulting in the sharp drop in cumulative throughput.

=== Preliminaries ===

1. '''Image name'''[[BR]]panasonic-demo-2.4.26-click-20051025.ndz node image file must be used. Resides on repository2:/export/orbit/image. It includes following additional installed features onto the standard click image:
  * Lunar protocol source code and compiled modules
  * VLC Media Player 0.8.2
  * ssh key files for hosts [1,2],[1,8],[2,1],[2,5],[3,2],[3,8]
  * bash files for experiment support: send-stream,sh, receive-stream.sh, stop-everything.sh

2. '''nodeHandler scripts'''[[BR]]There are two scripts with names streaming-panasonic.rb and streaming-panasonic-stop.rb. Former is used to start the experiment, and the latter is used to stop it. nodeHandler version 1.71 (modified to support execution of bash scripts and loading/unloading of driver modules) has been used with those scripts. As of writing, due to a bug in lunar modules, stop script cannot unload klunar and ksapf modules, after they are involved in data transfer. So, for a clean restart, node power cycle might be needed.
3. '''Display machine'''[[BR]]It must be able to reach ports on grid nodes using TCP. Display machine at ORBIT control room has that capability (or any other machine connected to that wall plug).  The port numbers to connect are of 80XY format, where X and Y are coordinates of the node. Display machine should have VLC Media Player 0.8.2 installed in  order to show the streams to user. E.g., if experiment is run on sandbox 9, the URL to the stream on [1,2] -> [1,8] pair is http://10.19.1.8:8018

== __Streaming video demo__ ==

=== Revision History ===

|| Version || Date || Revised by || Changes
|| v0.1 || 2005-10-25 || Mesut Ali Ergin || Initial version
|| v0.2 || 2005-10-27 || Mesut Ali Ergin || Updates some IP addresses, added UDP streaming port number.

=== Objective ===
In this demo, purpose is to run three concurrent video streams on three node pairs ([1,2],[1,8],[2,1],[2,5],[3,2],[3,8]). These three pairs should nearly saturate the network and by enabling admission control on one of the pairs, we should be able to see that one of the streams is not accepted in the first place for routing. Direction of the flow is designed to be like

{{{
     VIDEO                            VIDEO
    SOURCES                        DESTINATIONS
             Streaming on Wireless
      [1,2] -----------------------> [1,8]   } Streaming on Wired
      [2,1] -----------------------> [2,5]   }====================> DISPLAY
      [3,2] -----------------------> [3,8]   }                      MACHINE
               UDP Streaming to                  HTTP Streaming to
                destport 1234                    destports 80XY
}}}

All script files (except the ones in the node image file) are compiled into a nodehandler tarball and they can be found in repository/test/exp folder after extracting nodeHandler-panasonic.0.1.tar.gz. This tarball is available for download from http://www.winlab.rutgers.edu/~ergin/files/nodeHandler-panasonic.0.1.tar.gz

=== Preliminaries ===

1. '''Image name'''[[BR]]panasonic-demo-2.4.26-click-20051025.ndz node image file must be used. Resides on repository2:/export/orbit/image. It includes following additional installed features onto the standard click image:
  * Lunar protocol source code and compiled modules
  * VLC Media Player 0.8.2
  * ssh key files for hosts [1,2],[1,8],[2,1],[2,5],[3,2],[3,8]
  * bash files for experiment support: send-stream,sh, receive-stream.sh, stop-everything.sh

2. '''nodeHandler scripts'''[[BR]]There are two scripts with names streaming-panasonic.rb and streaming-panasonic-stop.rb. Former is used to start the experiment, and the latter is used to stop it. nodeHandler version 1.71 (modified to support execution of bash scripts and loading/unloading of driver modules) has been used with those scripts. As of writing, due to a bug in lunar modules, stop script cannot unload klunar and ksapf modules, after they are involved in data transfer. So, for a clean restart, node power cycle might be needed.
3. '''Display machine'''[[BR]]It must be able to reach ports on grid nodes using TCP. Display machine at ORBIT control room has that capability (or any other machine connected to that wall plug).  The port numbers to connect are of 80XY format, where X and Y are coordinates of the node. Display machine should have VLC Media Player 0.8.2 installed in  order to show the streams to user. E.g., if experiment is run on sandbox 9, the URL to the stream on [1,2] -> [1,8] pair is http://10.19.1.8:8018

4. '''Video Clip packages'''[[BR]]There are two debian packages (with different set of video clips in them) called, teststream_1.1-1_all.deb, teststream_1.1-2_all.deb. Normally, experiment support script checks the package and installs if it does not exist on the particular source node automatically. If debian repository, which is repository1.orbit-lab.org (or the network connected to it) fails, it may not be loaded on demand. In that case, the mentioned package have to be uploaded and installed manually to the node. Video clips are not embedded into the O/S image file due to the image file size concerns. The folder on which this debian package files reside is repository1:/var/www/video/binary

5. '''Auxiliary scripts'''[[BR]]Following are the the shell scripts that can be used on the console to help maintaining the experiment. They are not required for functionality, they are only for helping with some of the tasks.
  * poweroff-panasonic/poweron-panasonic: Powers off or on all the experiment nodes by contacting CMC web interface accordingly.
  * getlunarips: Retrieves lunar interface IP addresses from the streaming nodes. Must be run during the experiment.
  * scp-deb: copies teststream debian package to three source nodes via scp.

=== Steps to Execute Demo ===

1. '''Imaging'''
  * Make sure that all nodes in the experiment are powered off. poweroff-panasonic shell script can be used for that purpose.
  * Image the experiment nodes with the following command: 
{{{
imageNodes [1,2],[1,8],[2,1],[2,5],[3,2],[3,8] panasonic-demo-2.4.26-click-20051025.ndz
}}}
    Carefully watch the imaging process. It should take less than 10 mins. If any of the nodes do not come up with PXE image or any of them check back in during the 
    imaging process, kill the imaging nodeHandler instance, power-off the nodes, and restart imaging. If successful, nodes will be powered off automatically. They can 
    be powered-on with experiment script or with poweron-panasonic shell script without starting the experiment.

2. '''NodeHandler Script execution'''
  * Start the experiment with the following command after getting into nodeHandler-panasonic/ruby folder:
{{{
ruby nodeHandler.rb -s false test:exp:streaming-panasonic
}}}
    Change test:exp portion if the script is being invoked from some other folder structure. After all nodes check in, it will take at most 10 seconds for the 
    streaming to start on the node pairs, except first time. The first time run will involve an apt-get install command to install video clip debian package file. So, 
    this adds at most 2 minutes. Subsequent runs should not have this additional delay. This delay is not a blocking delay for nodeHandler. So, experimenter needs to 
    wait this amount of time after the nodeHandler start script is invoked.

3. '''Starting the VLC player'''[[BR]]Use display machine to run three instances of VLC player, and enter URL info of the stream into 'File->Open Network Stream->HTTP' text field. URL format is http://CTRL_IP_of_Node:80XY, where X and Y are coordinates of the node. In current setup, the URLs translate into:
    ||http://10.19.1.8:8018
    ||http://10.19.2.5:8025
    ||http://10.19.3.8:8038
Invoking these URLs should bring up three video streaming windows on display machine. With the current setup, there should be perceivable distortion on the streams, especially on the bigger one.

4. '''Stopping the streaming from one node'''[[BR]]Log-into node3-2 with {{{'ssh root@node3-2'}}} command. Execute {{{'pkill vlc'}}} on the node to stop streaming of the video. After a few seconds, video should freeze on the corresponding VLC window on display machine. Stream can be restarted, if necessary, by executing {{{'sh execfile'}}} on the node.

5. '''Starting the Monitor'''[[BR]]After stopping the stream on one pair, invoke monitor program on node3-8 (or node3-2), by executing {{{'lin/monitor2 ath1raw 3000 500'}}}. Here, 3000 means that the link is supposed to support 3Mbps bandwidth, and 500 means that the application packet rate is 500 packets/sec. This command should run a process that updates {{{/proc/pkt_rate}}} periodically. After a few updates, re-invoke the streaming by executing {{{'sh execfile'}}}. Streaming process should start, but pressing play button on the VLC software on display machine should not display the stream, since it is not accepted for routing on the wireless network.

6. '''Stopping the Monitor'''[[BR]]Stop the monitor program, and manually enter {{{'echo 40X6000 > /proc/pkt_rate'}}} to tell the admission control algorithm that there is enough bandwidth for the video. Re-invoking the stream and trying to see it on display (as explained in 5.) should succeed this time.

=== Troubleshooting ===

If video is not visible on the display machine, check the following things to see what might have gone wrong by logging into a source and destination pair.

1. At the source and destination, do a {{{'ps aux'}}}. There should be a group of vlc processes running (at least three or four). Run {{{'cat execfile'}}} to check IP addresses for streaming client and server are produced correctly. If not, re-run the nodeHandler script to see if problem persists.

2. Make sure that video clip package is installed correctly by looking into /usr/streams directory. There should be MPEG files in that folder. If not, upload teststream_1.1-2_all.deb to source nodes and install it with {{{'dpkg -i teststream_1.1-2_all.deb'}}} command.

3. Make sure that you can ping the destination node's lunar IP address (192.168.42.X) from the source node. If not, try restarting node, since lunar modules can not be reloaded in a healthy manner.

4. Make sure that display machine VLC client can connect to the stream destination node. Kill the destination vlc instance (at stream destination node) with {{{'pkill vlc'}}} and invoke it the same way specified in execfile, without -d option. This will enable foreground mode and process should inform whenever display VLC client is connected to the destination node.