22.2 Usage

Any mixing of ns-3 objects with real objects will typically require that ns-3 compute checksums in its protocols. By default, checksums are not computed by ns-3. To enable checksums (e.g. UDP, TCP, IP), users must set the attribute ChecksumEnabled to true, such as follows:

GlobalValue::Bind ("ChecksumEnabled", BooleanValue (true));

The usage of the Emu net device is straightforward once the network of simulations has been configured. Since most of the work involved in working with this device is in network configuration before even starting a simulation, you may want to take a moment to review a couple of HOWTO pages on the ns-3 wiki that describe how to set up a virtual test network using VMware and how to run a set of example (client server) simulations that use Emu net devices.

• http://www.nsnam.org/wiki/index.php/HOWTO_use_VMware_to_set_up_virtual_networks_(Windows)
• http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_scripts_to_drive_real_hardware_(experimental)

Once you are over the configuration hurdle, the script changes required to use an Emu device are trivial. The main structural difference is that you will need to create an ns-3 simulation script for each node. In the case of the HOWTOs above, there is one client script and one server script. The only “challenge” is to get the addresses set correctly.

Just as with all other ns-3 net devices, we provide a helper class for the Emu net device. The following code snippet illustrates how one would declare an EmuHelper and use it to set the “DeviceName” attribute to “eth1” and install Emu devices on a group of nodes. You would do this on both the client and server side in the case of the HOWTO seen above.

  EmuHelper emu;
  emu.SetAttribute ("DeviceName", StringValue ("eth1"));
  NetDeviceContainer d = emu.Install (n);

The only other change that may be required is to make sure that the address spaces (MAC and IP) on the client and server simulations are compatible. First the MAC address is set to a unique well-known value in both places (illustrated here for one side).

  //
  // We've got the devices in place.  Since we're using MAC address 
  // spoofing under the sheets, we need to make sure that the MAC addresses
  // we have assigned to our devices are unique.  Ns-3 will happily
  // automatically assign the same MAC address to the devices in both halves
  // of our two-script pair, so let's go ahead and just manually change them
  // to something we ensure is unique.
  //
  Ptr<NetDevice> nd = d.Get (0);
  Ptr<EmuNetDevice> ed = nd->GetObject<EmuNetDevice> ();
  ed->SetAddress ("00:00:00:00:00:02");

And then the IP address of the client or server is set in the usual way using helpers.

  //
  // We've got the "hardware" in place.  Now we need to add IP addresses.
  // This is the server half of a two-script pair.  We need to make sure
  // that the addressing in both of these applications is consistent, so
  // we use provide an initial address in both cases.  Here, the client 
  // will reside on one machine running ns-3 with one node having ns-3
  // with IP address "10.1.1.2" and talk to a server script running in 
  // another ns-3 on another computer that has an ns-3 node with IP 
  // address "10.1.1.3"
  //
  Ipv4AddressHelper ipv4;
  ipv4.SetBase ("10.1.1.0", "255.255.255.0", "0.0.0.2");
  Ipv4InterfaceContainer i = ipv4.Assign (d);

You will use application helpers to generate traffic exactly as you do in any ns-3 simulation script. Note that the server address shown below in a snippet from the client, must correspond to the IP address assigned to the server node similarly to the snippet above.

  uint32_t packetSize = 1024;
  uint32_t maxPacketCount = 2000;
  Time interPacketInterval = Seconds (0.001);
  UdpEchoClientHelper client ("10.1.1.3", 9);
  client.SetAttribute ("MaxPackets", UintegerValue (maxPacketCount));
  client.SetAttribute ("Interval", TimeValue (interPacketInterval));
  client.SetAttribute ("PacketSize", UintegerValue (packetSize));
  ApplicationContainer apps = client.Install (n.Get (0));
  apps.Start (Seconds (1.0));
  apps.Stop (Seconds (2.0));

The Emu net device and helper provide access to ASCII and pcap tracing functionality just as other ns-3 net devices to. You enable tracing similarly to these other net devices:

  EmuHelper::EnablePcapAll ("emu-udp-echo-client");

To see an example of a client script using the Emu net device, see examples/emu-udp-echo-client.cc and examples/emu-udp-echo-server.cc in the repository http://code.nsnam.org/craigdo/ns-3-emu/.

This document was generated on April 21, 2010 using texi2html 1.82.