802.11 (WiFi) Simulator for Ad-Hoc networks

This is a java event based simulator for 802.11 networks. It implements the DCF function, which is used in WiFi networks.
Hence, it is useful to do some performance simulations for WLAN Ad-Hoc networks.
The simulator may be regarded as a timeline. Within this timeline one can add some events. If a point of time for an event is reached it will be executed.
The simulation will proceed as long as events are stored within the timeline.
Of course, events may be inserted prior the simulation as well as during the simulation process. Maybe some events may imply the insertion of new events.
Some further features are:

• Independent physical and link layer implementation
• the link layer implements the current DCF function of WiFi networks
• support of promisucous mode
• dynamic adding and removal of networking devices
• dynamic adding and removal of unidirectional and bidirectional links
• 802.11 unicast and broadcast implementation for devices within the simulation
• realistic effects like frame collisions, capture effects, ..
• extendable event mechanism

You may find the API Specification of the simulator at http://wiki.uni.lu/simulator

The Sources are available here:

Version	Changes	Download
1.0_r1	Corrected NAV (network allocation vector) calculation for broadcasts addad a simulation reset (to reuse a network for several simuations) removed some annoying print outs	simulator_1_0_r1.jar
1.0	-	simulator.jar

To get a first impression how this simulator works please read the following Tutorial

Tutorial 1

In this example 2 devices are installed. One of them sends a packet to the other device
First of all we need a Packet implementation, which means we have to implement the abstract class simulator.linklayer.interfaces.APacket. This abstract class forces a method getSize, which returns the size of one packet in bytes. This is needed to calculate transmission times of packets.


import simulator.linklayer.interfaces.APacket;

/**
 * This class implements the packets for this simulation.
 * It just stores a string to send.
 * @author thomas
 */
public class Packet extends APacket{

   public String text;

   public Packet(String text){
      this.text=text;
   }

   public int getSize() {
      return 1024;
   }

}



Now that we have packets we may proceed to implement the behaviour of Devices within the network. Don't fear. Most of the code below are comments. The Device implements an interface called ILinkLayerCaller. This interface is used to tell the link layer implementation that received packets should be forwarded to this Device object. If this Device receives a new packet, the function handlePacketReceive(ILinkLayerDevice device, APacket packet) will be called by the link layer. So there, we can define what to do with the packet. Maybe we want to forward it, or it might be processed on upper layers or anything else. In this example we simply print out, that we received a packet.
Further on, this class stores an object, which is interfaced by ILinkLayerDevice. This object represents the link layer implementation, and provides all the methods which might become useful. Here we only use the functionality to send a unicast (see method public void sendPacket(Packet packet,long target)).
Last but not least there is some work done in the constructor. The first command creates an instance of the link layer implementation. The second command tells the link layer implementation, that this object is the instance, which needs to be informed, if packets are received.


import simulator.linklayer.interfaces.*;

/**
 * This class implements the devices within our network simulator
 * @author thomas
 */
public class Device implements ILinkLayerCaller{

   /**
    * the link layer implementation of this device
    */
   public ILinkLayerDevice linkLayerDevice;

   /**
    * class constructor
    * @param address the MAC address to be used by this device
    */
   public Device(long address){
      linkLayerDevice=LinkLayerFactory.getLinkLayerDevice(address); //generate link layer device
      //add this object as a caller to the link layer device to be informed about packet reception
      // so handlePacketReceived(..) will be invoked if this device receives a packet
      linkLayerDevice.addLinkLayerCaller(this); 
   }

   /**
    * This method is invoked, if this device receives a packet.
    * Print out the content "text" of the packet
    */
   public void handlePacketReceive(ILinkLayerDevice device, APacket packet) {
      System.out.println("Device "+linkLayerDevice.getMACAddress()+": Received a packet with text: "+((Packet)packet).text);

   }

   /**
    * send a packet to the specified target
    * @param packet the packet to send
    * @param target the MAC address of the target device
    */
   public void sendPacket(Packet packet,long target){
      linkLayerDevice.sendUnicast(packet,target);
   }


}



The last class of this example implements the main function and sets up the network. All the work is done in the constructor. First a link layer network instance is created and stored in network. To devices (of our implementation above are created and a bidirectional link is established between them. Then, we insert a send event into the beginning of our event queue by calling the sendPacket(...) method implemented above. Finally we start the simulation.


import simulator.linklayer.interfaces.*;

public class Example {

   public ILinkLayerNetwork network; //this is the network of the simulation

   public Example(){
      network = LinkLayerFactory.getLinkLayerNetwork(); //create the network
      network.setVerbose(true); //print some output
      Device dev1 = new Device(1); //create a Device
      Device dev2 = new Device(2); //create another device

      //add them to the network
      network.addDevice(dev1.linkLayerDevice);
      network.addDevice(dev2.linkLayerDevice);

      //add a bidirectional link between those devices
      network.addBiLink(dev1.linkLayerDevice,dev2.linkLayerDevice);

      //1 sends Hello to 2
      dev1.sendPacket(new Packet("Hello"),2);

      network.startSimulation();
   }

   public static void main(String[] args){
      new Example();
   }

}



If you execute this sample it will generate the output:


70: 2: received rts
190: 1: received cts
1020: 2: received mpdu
Device 2: Received a packet with text: Hello
1140: 1: received ack


The first value in each line is the time in microseconds. Afterwards the MAC address of the device, which prints the output is shown. As you can see, by sending a packet the (RTS/CTS/MPDU/ACK) sequence of 802.11 is executed. This output is diplayed, because we told the simulator to be verbose (in the code above).

Tutorial 2

The second tutorial will introduce the event mechanism in more detail. Here, we will repeat the tutorial above, but we will add another device which disturbs the communication above. As you can see in the output, above, the packet is transmitted between time 190 and 1020. We will just tell the third device that it should start to send a packet to device 2 at time 300. So the transmission is interrupted and the backoff procedures of 802.11 are enrolled.
This will only work, if the third device is not locked by the RTS or CTS frames exchanged before. To avoid this, we will also add the link between device 2 and 3 at time 300, not before.
So, we have to tell the simulator, that something happens at time 300 (in microseconds). Therefore we will insert an event into the Queue at time 300. But first we have to define the event. This is done by extending the abstract class simulator.event.Event. It provides a method invoke(), which will be called, if the event occures. As you can see there, we tell the simulator to add a link between device 2 and 3. Afterwards a packet is send by 2 to device 3.


import simulator.event.Event;
import simulator.linklayer.interfaces.ILinkLayerNetwork;

/**
 * This is an event, which may be included into the Event Queue of the simulator
 */
public class SendEvent extends Event{

   Device sourceDevice;
   Device targetDevice;
   ILinkLayerNetwork network;

   public SendEvent(Device sourceDevice, Device targetDevice, ILinkLayerNetwork network){
      this.sourceDevice=sourceDevice;
      this.targetDevice=targetDevice;
      this.network=network;
   }

   /**
   * this is the function, which is executed, if the event occures
   */
   public void invoke() {
      network.addBiLink(sourceDevice.linkLayerDevice,targetDevice.linkLayerDevice);
      sourceDevice.sendPacket(new Packet("evil"),targetDevice.linkLayerDevice.getMACAddress());
   }

}


Finally we have to modify our main class. Here we add a third device to our network and insert our event into the queue.
First we generate a SendEvent Object. Afterwards we put it into the event queue by calling insertEvent. The boolean true tells the simulator, that 300 is an absolute time value.
Imagine you would like to insert another event during the simulation. Maybe one event, which is invoked at the moment, wants to add a new event 200 microseconds later. Then the flag in insertEvent would be false to indicate, that 200 is a period.


import simulator.linklayer.interfaces.*;

public class Example {

   public ILinkLayerNetwork network; //this is the network of the simulation

   public Example(){
      network = LinkLayerFactory.getLinkLayerNetwork(); //create the network
      network.setVerbose(true); //print some output
      Device dev1 = new Device(1); //create a Device
      Device dev2 = new Device(2); //create another device
      Device dev3 = new Device(3); //the device which will disturb

      //add them to the network
      network.addDevice(dev1.linkLayerDevice);
      network.addDevice(dev2.linkLayerDevice);
      network.addDevice(dev3.linkLayerDevice);

      //add bidirectional links between those devices
      network.addBiLink(dev1.linkLayerDevice,dev2.linkLayerDevice);


      //1 sends Hello to 2
      dev1.sendPacket(new Packet("Hello"),2);

      //insert sendEvent into the queue
      SendEvent sendEvent = new SendEvent(dev3,dev2,network);
      network.insertEvent(sendEvent,300,true);

      network.startSimulation();
   }

   public static void main(String[] args){
      new Example();
   }

}


The generated output will be:


70: 2: received rts
190: 1: received cts
500: 3: Timeout occured
500: 3: setting backoff to: 3220
1150: 1: Timeout occured
1240: 1: setting backoff to: 3710
3720: 3: Backoff expired
3790: 2: received rts
3910: 1: stopping backoff it remains: 1040
3910: 3: received cts
4740: 2: received mpdu
Device 2: Received a packet with text: evil
4860: 3: received ack
4960: 1: setting backoff to: 1040
6000: 1: Backoff expired
6070: 2: received rts
6190: 1: received cts
7020: 2: received mpdu
Device 2: Received a packet with text: Hello
7140: 1: received ack


Hope, this was a helpful introduction. Anyway, if you have questions don't hesitate to ask me .

"802.11 Network Simulator" is mentioned on: News