[wiki:WikiStart Orbit] > Running Demos = How To 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 steps required to run the following two demos: * Conference room demo * Streaming video demo Future demos should also include their details here. == Conference room demo == === Revision History === || Version || Date || Revised by || Changes || v0.1 || 2005-12-23 || Kishore Ramachandran || Initial version === 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. The demo itself consists of one receiver and 25 senders -- the start times of the senders are staggered (3-4 senders join the experiment in 10 second intervals). Traffic generated is UDP-CBR (constant bit-rate) at 1.5Mbps emulating high-quality video streaming from the clients to the AP. All the clients and the AP use 802.11a (channel 36 (5.18Ghz)) with negligible interference from other non-802.11 sources. The figure below provides a graphical representation. {{{ Timeline SOURCES DESTINATION 1.5Mbps UDP CBR on Wireless Time 0 Group 1: [1,2],[1,4],[1,8] -------------------------------> [5,4] Time 10 Group 2: [2,1],[2,3],[2,5] -------------------------------> [5,4] ... Time 60 Group 7: [8,1],[8,5],[8,7] -------------------------------> [5,4] Time 110 Stop Group 1 senders. Time 115 Stop Group 2 senders. ... Time 140 Stop Group 7 senders. }}} === Steps to Execute Demo === 1. '''Image name''' -- __conf-room-demo.ndz__. Resides on repository2:/export/orbit/image. a. Log onto console.sb9.orbit-lab.org using ssh (see HowToGetStarted). b. Turn off all nodes using the following command: {{{ wget -O - 'http://cmc:5012/allOff' }}} c. Execute the following command on console.sb9. {{{ imageNodes atheros baseline.ndz }}} 2. '''nodeHandler scripts''' -- execute following command on console.sb9 {{{ nodehandler -k test:exp:conf-room-demo }}} 3. '''Display machine''' On the display machine, point your Internet Explorer or Mozilla Firefox browser to http://internal3.orbit-lab.org/results.html and enter the experiment ID (displayed when nodehandler is run) The explanation for this drop is that a. the current implementation of CSMA/CA fails to prevent losses from occurring in a congested environment b. the 802.11 bit-rate adaptation algorithm, which believes CSMA/CA to be perfect, infers these losses to be due to poor channel (SNR) conditions and drops the bit-rate accordingly. This in turn makes the situation worse given that the same frame will now take a much longer time on the medium -- all senders will drop their rate to 6Mbps and the cumulative throughput will reflect this (it should be equal to the saturation throughput at 6Mbps). === Troubleshooting === 1. The graphics displaying the topology uses [http://www.w3.org/TR/SVG/ SVG] - this is built into the latest Mozilla firefox but you will need an SVG viewer extension for Internet Explorer. This extension can be downloaded from http://www.adobe.com/svg/viewer/install/main.html. [[BR]][[BR]] == 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. || v0.3 || 2006-06-02 || Mesut Ali Ergin || Revised completely to reflect the stable version of the demo with GUI. === Objective === In this demo, purpose is to run three concurrent video streaming sessions on an ad hoc network of nodes [1,2],[1,8],[2,1],[2,5],[3,2],[3,4],[3,8],[8,3]. Each row (1, 2, and 3) is used to communicate one of the streams. These three streams (of average encoding rate of 2Mbps, 1Mbps, and 1Mbps respectively) should nearly saturate the network (which is operated at fixed 6Mbps rate using 802.11a @ Ch.36) and by enabling admission control on the network (specifically on row three for the demo purposes), we should be able to see that the stream on row three is not accepted in the first place for routing. Node [8,3] is not used in the first part of the demo. It is brought in to the network later to demonstrate that routing protocol (Lunar) is able to discover that alternate route ([3,2]--->[8,3]--->[3,8]) after the fact that admission control forces rejection of the third stream. Direction of the flows are illustrated as {{{ VIDEO VIDEO SOURCES DESTINATIONS Streaming on Wireless [1,2] -----------------------> [1,8] } Streaming on Wired GBps Network [2,1] -----------------------> [2,5] }==================================> DISPLAY [3,2] ---------[3,4]---------> [3,8] } MACHINE @ Control Room [8,3] _________________________________________ _______________________________________ UDP Streaming to HTTP Streaming to destination ports #1234 destination ports #80XY (X=Orbit Node x-coordinate, Y=Orbit Node y-coordinate) }}} All script files (except the ones residing in the node image) and the required nodehandler are compiled into a nodehandler tarball and it is available for download from http://www.winlab.rutgers.edu/~ergin/files/nodeHandler-streaming.0.2.tar.gz === Preliminaries === 1. '''Versions'''[[BR]]Particular nodehandler from the above tarball has to be used. The image file 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,4],[3,8],[8,3] * bash files for experiment support: send-stream,sh, receive-stream.sh, stop-everything.sh etc. 2. '''Display machine'''[[BR]]It must be able to reach ports on grid nodes using TCP. Display machine in ORBIT control room has that capability. The port numbers to connect to 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., the URL to the stream on [1,2] -> [1,8] pair is http://10.19.1.8:8018. To ease up invoking three VLC instances with correct parameters, use the Windows Batch file written for this purpose (resides on the Display machine desktop). 3. '''Video Clip packages'''[[BR]]There are three debian packages (with different set of video clips in them) called, teststream_1.1-1_all.deb, teststream_1.1-2_all.deb, and teststream_1.1-3_all.deb. Normally, experiment support script checks the package and installs the appropriate one 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 three source nodes. 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 4. '''GUI'''[[BR]] The GUI used to drive the demo is written in TCL/Tk. Console of sb9 normally has the necessary software to run this GUI. In order to use this GUI from display machine (or any other machine capable of reaching grid network), X Server has to be used. There is an X server installed in Display machine. It can be invoked from Start->cygwin menu (open up cygwin terminal and type in startx). Also, the ssh client used to connect to console.sb9 must be configured to forward X11 (which should already be the case for the SSH client on Display machine). Invoking GUI is explained in the below steps. === Steps to Execute Demo === 1. '''Get Necessary Files''' * Download the above nodeHandler tarball and extract it under your_home@console.sb9 * cd into nodeHandler-streaming/ruby 2. '''Imaging Nodes''' * Execute the shell script image.sh * This should image the mentioned eight nodes using panasonic-demo-2.4.26-click-20051114.ndz * Imaging takes 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. 3. '''NodeHandler Script Execution''' * Start the experiment by executing the shell script run.sh. It should invoke nodeHandler as follows: {{{ ruby nodeHandler.rb -s false test:exp:streaming-panasonic }}} After all nodes check in, it will take at most 10 seconds for the streaming to start on the node pairs, except the 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 to the experiment. Subsequent runs should not have this additional delay. This delay is not a blocking delay for nodeHandler. So, demonstrator needs to wait this amount of time after the nodeHandler start script is invoked. 4. '''Invoke the GUI''' * Go up to folder nodeHandler-streaming/scripts * Start gui by typing ./streaming-dashboard * A single screen GUI should come up. If not, check X forwarding by trying simple applications like xclock, xeyes etc. * Check all nodes by first querying all nodes MAC addresses and then all nodes Lunar IP adresses. All eight should reply back. 5. '''Starting the VLC player'''[[BR]]Use the Windows batch script on the Desktop of Display machine (named something like 'streaming-demo'). If you can't find it, 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 three streams concurrently running, there should be perceivable distortion, especially on the bigger one. 6. '''Explain the Distortion''' [[BR]]Explain the audiance why there is distortion, and let them see it for a while. 7. '''Stopping the streaming from one node'''[[BR]]Stop the third stream (row three) by first clicking node3-2 and then stop streaming button on GUI. Wait a few seconds and let the VLC application buffer flush. One of the streams on display should be gone. Then click on node3-4 on GUI and click enable monitor mode button (if button was stuck in disable monitor mode, then click it twice). After this, GUI should report 0Kbps available bandwidth on air. Then, restart streaming by clicking node3-2 first and then start streaming button. Then click on the corresponding VLC's play button and demonstrate that stream is not routed, and can not be seen on the display. Admission control does not allow node3-4 to route this stream to node3-8. 8. '''Alternate Route'''[[BR]]Now, click node8-3 and then add to network button. This will bring up node8-3's wireless interface. After three second update interval of Lunar, this route should be discovered and the third stream should be communicated over node8-3. If needed, show this by reading node3-8's routing table. === 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 nodes, 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.