Instructions on Running Experiments on the Emulator

Access and control of the emulator is provided through the emulation control computer. This is currently emucontrol-1.ece.cmu.edu.

Pre-Experiment Check-List

Double-check the following before proceding.

You are a member of the emulator group and project. If you did not select this during account creation, join now here.
Your default shell is bash. Check under "Experimentation" -> "My Emulab", "Profile" tab.

You have the standard-issue files and directories in your home directory on emucontrol-1.ece.cmu.edu. Your home directory should include at least:

-bash-3.2$ cd; ls -lah
total 54K
drwxr-xr-x   6 ewa  console 1.0K Jul 12 11:55 .
drwxr-xr-x 140 root     101 2.5K Jul  9 17:13 ..
lrwxrwxrwx   1 ewa  console    7 Jul 12 09:53 .bash_profile -> .bashrc
-rw-r--r--   1 ewa  console 1.2K Jul 12 09:53 .bashrc
drwxr-xr-x   2 ewa  console  512 Jul 12 09:55 emuNode
drwx------   2 ewa  console  512 Jul 12 11:55 .ssh
drwx------   2 ewa  console  512 Jul  9 17:13 .ssl

If you're missing any of these, see Setting up your CMUlab Account.

Environment Variables

The emulation control software uses a number of environment variables. The default .bashrc file sets these variables automatically when you log in. If you change this file, make sure you do not change the values of these variables.

Configuration Files

All modes of emulator operation require two configuration files: hardware configuration files and experiment configuration files.

Hardware Configuration File

A Hardware configuration file define the hardware setup of the Emulator. It is written by the Emulator administrator. Individual users can read the file to see what configuration is in use, but should not need to edit these files. Here are more details on the Hardware Configuration File.

Experiment Configuration File

The experiment configuration file is created by users to specify the experiment operation. It defines what nodes will be used, node mobility, and the signal environment to be used. Depending on the usage mode, it can also include a script to control simple experiments. Alternatively, the script can be used to specify what user code should be loaded into the emulator controller; the user code can then control the experiment. A final option is to start the GUI, allowing interactive control of the experiment. Here are more details on the Software Configuration Files and Emulation Control Software.

Some examples are provided with corresponding experiment configuration files in the /usr/local/emulator/run/examples/ folder on emucontrol-1.ece.cmu.edu.

Running an Actual Experiment

To run an actual "live" experiment that does use the emulator hardware, you need to first swap your experiment in, as described on the Create Experiments page. Once you have access to the laptops assigned by CMUlab and are ready to run your experiment, change to the experiment's run directory first.

Experiment must be swapped in before continuing.

There are several pre-configuration steps which were formerly required but are now supposed to be automated. You can read about them here, but you shouldn't have to. If you encounter errors relating to SSH or RMI when you try to start your experiment, consult that page and notify emulator-help@cs.cmu.edu.

Start the Experiment

You can now run experiments using the following command:

	emuRun <experimentConfigFile>

Where <experimentConfigFile> is the name of the experiment configuration file. The emuRun command will parse the configuration file, contact the emulator hardware, and bind to remote node daemons if necessary. Any specified user code will then be loaded, and execution of the control script will begin.

Successfull execution will look something like this:

-bash-3.2$ emuRun clearChannel2.xml 
hw config = /usr/local/emulator/run/emuHardware.xml
emulator config = clearChannel2.xml
Starting Emulator
In Emulator.init()
0	port id: 0 scID:4
1	port id: 1 scID:8
2	port id: 2 scID:6
3	port id: 3 scID:5
4	port id: 4 scID:3
5	port id: 5 scID:7
6	port id: 6 scID:11
7	port id: 7 scID:13
8	port id: 8 scID:2
9	port id: 9 scID:12
10	port id: 10 scID:10
11	port id: 11 scID:14
12	port id: 13 scID:9
13	port id: 14 scID:11B
14	port id: 15 scID:12B
Emulab input file is /usr/local/emulator/var/swapins/newuser-emulator-tut1.swapin
Reading emulab configuration file
Reading node defs
		pcemu104 adding antenna: 0
		pcemu101 adding antenna: 0
		pcemu102 adding antenna: 0
		pcemu103 adding antenna: 0
		pcemu105 adding antenna: 0
		pcemu106 adding antenna: 0
		pcemu107 adding antenna: 0
		pcemu108 adding antenna: 0
		pcemu109 adding antenna: 0
		pcemu110 adding antenna: 0
		pcemu111 adding antenna: 0
		pcemu112 adding antenna: 0
		pcemu113 adding antenna: 0
		pcemu114 adding antenna: 0
		pcemu115 adding antenna: 0
Reading user configuration file
# LossTraceLibraries: 0
num of Channels: 210
Active port:3
Active port:0
Path Mask
<0,0>	<1,0>	<2,1>	<3,0>	<4,0>	<5,0>	<6,0>	<7,0>	<8,0>	<9,0>	<10,0>	<11,0>	<12,0>	<13,0>	<14,0>	<15,-1>	<16,0>	<17,-1>	<18,-1>	<19,-1>	<20,-1>	<21,-1>	<22,-1>	<23,-1>	<24,-1>	<25,-1>	<26,-1>	<27,-1>	<28,0>	<29,-1>	<30,0>	<31,-1>	<32,-1>	<33,-1>	<34,-1>	<35,-1>	<36,-1>	<37,-1>	<38,-1>	<39,-1>	<40,-1>	<41,-1>	<42,1>	<43,0>	<44,0>	<45,0>	<46,0>	<47,0>	<48,0>	<49,0>	<50,0>	<51,0>	<52,0>	<53,0>	<54,0>	<55,0>	<56,0>	<57,-1>	<58,-1>	<59,0>	<60,-1>	<61,-1>	<62,-1>	<63,-1>	<64,-1>	<65,-1>	<66,-1>	<67,-1>	<68,-1>	<69,-1>	<70,0>	<71,-1>	<72,-1>	<73,0>	<74,-1>	<75,-1>	<76,-1>	<77,-1>	<78,-1>	<79,-1>	<80,-1>	<81,-1>	<82,-1>	<83,-1>	<84,0>	<85,-1>	<86,-1>	<87,0>	<88,-1>	<89,-1>	<90,-1>	<91,-1>	<92,-1>	<93,-1>	<94,-1>	<95,-1>	<96,-1>	<97,-1>	<98,-1>	<99,-1>	<100,0>	<101,-1>	<102,-1>	<103,0>	<104,-1>	<105,-1>	<106,-1>	<107,-1>	<108,-1>	<109,-1>	<110,-1>	<111,-1>	<112,-1>	<113,-1>	<114,-1>	<115,-1>	<116,0>	<117,-1>	<118,-1>	<119,0>	<120,-1>	<121,-1>	<122,-1>	<123,-1>	<124,-1>	<125,-1>	<126,-1>	<127,-1>	<128,-1>	<129,-1>	<130,0>	<131,-1>	<132,-1>	<133,0>	<134,-1>	<135,-1>	<136,-1>	<137,-1>	<138,-1>	<139,-1>	<140,-1>	<141,-1>	<142,-1>	<143,-1>	<144,0>	<145,-1>	<146,-1>	<147,0>	<148,-1>	<149,-1>	<150,-1>	<151,-1>	<152,-1>	<153,-1>	<154,-1>	<155,-1>	<156,-1>	<157,-1>	<158,0>	<159,-1>	<160,-1>	<161,0>	<162,-1>	<163,-1>	<164,-1>	<165,-1>	<166,-1>	<167,-1>	<168,-1>	<169,-1>	<170,-1>	<171,-1>	<172,0>	<173,-1>	<174,-1>	<175,0>	<176,-1>	<177,-1>	<178,-1>	<179,-1>	<180,-1>	<181,-1>	<182,-1>	<183,-1>	<184,-1>	<185,-1>	<186,-1>	<187,-1>	<188,-1>	<189,-1>	<190,0>	<191,-1>	<192,-1>	<193,0>	<194,-1>	<195,-1>	<196,-1>	<197,-1>	<198,-1>	<199,-1>	<200,-1>	<201,-1>	<202,-1>	<203,-1>	<204,-1>	<205,-1>	<206,-1>	<207,-1>	<208,0>	<209,-1>	<210,-1>	<211,0>	<212,-1>	<213,-1>	<214,-1>	<215,-1>	<216,-1>	<217,-1>	<218,-1>	<219,-1>	<220,-1>	<221,-1>	<222,-1>	<223,-1>	<224,-1>	<225,-1>	
Creating Ricean fading table k: 3.0
Ricean fading table size: 8192
Creating Ricean fading table k: 0.0
Ricean fading table size: 8192
Reading world def
Reading event def file
commSender bypass setting: false
warning: no emu token
schedClient: null
not scheduled: CommReceiver ignored
validation disabled
Creating world
Initializing signal environment
maxMFBits: 7
maxShift: 10
binding: rmi://emucontrol-new.ece.cmu.edu:1387/guiServer

----------------------------------------------------------------
Please connect to the GUI by using the URL: 
http://emucontrol-new.ece.cmu.edu:8180/GUI/emu_newuser1387.html
in a browser.
----------------------------------------------------------------

bind host Daemon: EmuDaemon[UnicastServerRef [liveRef: [endpoint:[10.96.65.200:40854](local),objID:[42f018cc:12a7b9d57f4:-7ffb, -287758669479870222]]]]
initilizeing emuDaemon: EmuDaemon[UnicastServerRef [liveRef: [endpoint:[10.96.65.200:40854](local),objID:[42f018cc:12a7b9d57f4:-7ffb, -287758669479870222]]]]
EmuDaemon bound.
mapDaemonStubs: //10.96.65.104/NodeDaemon
DaemonCommunicator: Mapping NodeDaemon nodew1 to Ip addr: 10.96.65.104
mapDaemonStubs: //10.96.65.101/NodeDaemon
DaemonCommunicator: Mapping NodeDaemon nodew2 to Ip addr: 10.96.65.101
Reading events
Done with Emulator.init()

Starting Emulator...
sending start msg
sent start msg
EmuEventQueue start. Initial size: 3
Emulator start complete.

emuRun will run in the foreground until you stop it or the experiment is swapped out. To use the emulator's GUI interface, connect a browser to the URL given in the the emuRun output.

Verifying Emulator Operation

Verifying Communciation with the Emulator Hardware

To test communication with the Emulator Hardware, type "ping 10.0.0.1". Good responses indicate that the connection to the hardware is working.