HOWTO use ns-3 directly on the CMU wireless emulator

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - Samples - Models - Education - Contributed Code - Papers

Note: Some of the ns-3 documentation is stale below, as it references a program emu-udp-echo-client and emu-udp-echo-server that are not part of ns-3. The closest corresponding program in current ns-3 (as of ns-3.22) is src/fd-net-device/examples/fd-emu-udp-echo.cc.

The following is a description on how to use ns-3 realtime emulation package at CMU wireless emulation test bed. We assume that you are already familiar with CMU wireless emulator. If you are new, please take a look at http://www.cs.cmu.edu/~emulator/ and go through the "Documentation" page, where you can find instructions on how to configure your account, set up experiment and go through examples. We will assume throughout this HOWTO that you have an account on the wireless emulator testbed and the name of the experiment is ns3example.

HOWTO use ns-3 directly on the CMU wireless emulator

1. Swap-in experiment. The experiment can be specified in ns-2 Tcl script like the following:

       set ns [new Simulator]
       source tb_compat.tcl
       # Allocate the nodes.  Their "wifi-ness" is determined later,
       # by the type of networks you request to be set up on them.
       set nodew1 [$ns node]
       set nodew2 [$ns node]
       # only use pcd610 
       tb-set-hardware $nodew1 pcd610
       tb-set-hardware $nodew2 pcd610
       # A wireless lan connecting the first three nodes.
       set lan0 [$ns make-lan "$nodew1 $nodew2" 11Mb 0ms]
       # Choose the wireless lan protocol.
       tb-set-lan-protocol $lan0 "80211b"
       # Set an access point.  This node becomes the access point;
       # others in the LAN become stations of it.  You can also set other
       # modes for your LAN, such as Adhoc mode.
       tb-set-lan-setting $lan0 "mode" "adhoc"
       # Choose some other settings.
       tb-set-lan-setting $lan0 "channel" 6
       tb-set-lan-setting $lan0 "txpower" "7"	
       # Select a wireless-capable image for the nodes
       tb-set-node-os $nodew1 FC6w-EMU
       tb-set-node-os $nodew2 FC6w-EMU
       $ns rtproto Static
       $ns run

This script reserves two PCs (pcd610) with kernel image "FC6w-EMU". You can then swap-in this experiment. After successful swapped-in, you should be able to ssh in these two nodes without password. The home directory of these nodes are the same as your home directory on the emucontrol (emucontrol-new.ece.cmu.edu). The FQDN of each node includes the experiment name and project name, for example, nodew1 has the following FQDN

       nodew1.ns3example.emulator.cmcl.cs.cmu.edu

2. Compile ns-3 on emulated nodes:

You might need to turn off python to compile ns-3 successfully:

       ./waf configure --disable-python

3. Configure wireless channel

In this example, you want to set a clear channel between two nodes. The following commands assumes the user name is "pei", project is "emulator", experiment name is "ns3example" and the channel configuration file is ~/run/examples/clearChannel/clearChannel2.xml.

       emulatorDaemon pei emulator ns3example
       emuRun ~/run/examples/clearChannel/clearChannel2.xml

There is a emulab.txt file created.

4. Configure wireless interface ath0 on nodew1 and nodew2

       sudo /sbin/modprobe ath_pci
       sudo /usr/local/bin/wlanconfig ath0 destroy
       sudo /usr/local/bin/wlanconfig ath0 create wlandev wifi0 wlanmode adhoc
       sudo /usr/local/sbin/iwpriv ath0 mode 2
       sudo /usr/local/sbin/iwconfig ath0 essid e_ad_hoc channel 6 
       sleep 1
       sudo /sbin/ifconfig ath0 ${EMU_WIRELESS_IP} [Use IP addresses from emulab.txt created in 3]
       sudo /usr/local/sbin/iwconfig ath0 txpower 7 
       sudo /sbin/sysctl -w dev.wifi0.diversity=0
       sudo /sbin/sysctl -w dev.wifi0.txantenna=1
       sudo /sbin/sysctl -w dev.wifi0.rxantenna=1

The above example configures the ath0 with ad hoc mode with txpower 7. You can also configure data rate and mcast rate if desired. Remember to use sudo before all commands.

5. Modify ns-3-dev/examples/emu-udp-echo-server.cc and emu-udp-echo-client.cc as needed. The following is the example of setting up ath0 in ns-3 on nodew2 with mac address "00:00:00:00:00:02" and IP address "20.1.1.2":

       EmuHelper emu;
       emu.SetAttribute ("DeviceName", StringValue ("ath0"));
       NetDeviceContainer d = emu.Install (n);
       Ptr<NetDevice> nd = d.Get (0);
       Ptr<EmuNetDevice> ed = nd->GetObject<EmuNetDevice> ();
       ed->SetAddress ("00:00:00:00:00:02");

6. Run ns-3 on emulated nodes. For example, to run the server at nodew1

       sudo /sbin/ifconfig ath0 promisc
       ./waf --run emu-udp-echo-server