WifiSim – User Manual

							WifiSim – User Manual

Pre-requirements:
In order to verify that WifiSim will work correctly and smoothly on your personal
computer it must stand for some pre-requirements:
     Windows XP/2003 operating system
     .NET framework version 1.1 and up.
       Use this link to download:
       http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-
       4842-8157-034d1e7cf3a3&displaylang=en

Note: No installation is needed in oder to run WifiSim. Just extract the executable and
run it.

Compilation instructions:
All the source files can in be found in the /src folder of the package. This folder
contains 8 files:
     WifiSimulation.sln - contains the solution for the application.
     GUI.cs - contains GUI sources and sources command line parsing.
     Common.cs - contains commonly used constants, global structures and
       functions used across the application.
     Node.cs - contains the Node class source files.
     Simulation.cs - contains the Simulation class source files. This class will
       instantiate all other objects in the simulation.
     EventGenerator.cs - contains the EventGenerator source files.
     Event.cs - contains the Event classes' sources used by the EventGenerator.
     Logger.cs - contains the application's logging mechanism sources.

In order to easily compile the project, the user shall use Microsoft's Visual Studio
2003 or later and load the WifiSimulation.sln file.
The solution already includes references for required projects and dll files.
The user should build the solution in order to create the client side executable
(WifiSimulation.exe).
Operation instructions - WifiSimulation.exe

       The application supports two launching modes: GUI and command line.
The user should place the executable in a folder with write permissions (for logging
output) and enough disk space.

Command line usage:
WifiSimulation.exe NumOfNodes#<uint> AlwaysTransmit#<1/0>
IncludeOpenSlot#<1/0> SimulationTime#<ulong>
Program#<nodeIsTDM/locateStations/noProgramn>
LengthDistribution#<uint>?<uint >!<uint>?<uint>.....
TdmTimeLength#<uint> [OpenSlotTimeLength#<int>] [NumOfAreas#<uint>]
[PacketArrivalRate#<uint>] [RadiusOfArea#<uint>]
StationsLocation#<uint>?<uint>!<uint>?<uint>....
LoggingLevel#<uint> Title#"<string>"

The parameters are divided into two groups, mandatory parameters and optional
parameters (marked with brackets []). Please note that mandatory parameters are place
sensitive. For example, AlwaysTransmit cannot appear before NumOfNodes or in any
place but the second parameter.

Mandatory parameters:

NumOfNodes#<int>    : Specifies the number of stations participating in the simulation
excluding the access point. The value must be larger than 0.

AlwaysTransmit#<1/0>      : Specifies the packet arrival simulation mode. 1 for always
transmit and 0 for Poison packet arrival rate. (When assigned 0, the field
PacketArrivalRate becomes mandatory)

IncludeOpenSlot#<1/0>        : Specifies whether the simulation will grant al the stations
the ability transmit at the each of every zones round.(When assigned 1, the field
OpenSlotTimeLength becomes mandatory)

SimulationTime#<ulong>       : Specifies the simulation length in seconds. The value
must be larger than 0.

Program#<nodeIsTDM/locateStations/noProgramn>               : Specifies the mode of the
simulation with the following options:
locateStations : A mode that enables the user to specify the exact station locations.
(When this mode is chosen, the StationsLocation field becomes mandatory and the
NumOfNodes field is ignored).
nodeIsTDM : A mode that grants each node a TDM zone for itself. (When this mode is
chosen the NumOfNodes field is ignored).
noProgramn : The default run mode where the stations' possitions are assigned
randomly.

LengthDistribution#<uint>?<uint >!<uint>?<uint>... :
The user can specify the distribution of packet lengths in bytes.
<a>?<b>  stands for: a – part of 10 ;b – the packet length
For example:
 lengthDistribution#3?1500!5?1000!2?2000 Means that 30% of the packets are 1500
bytes packet , 50% are 500 byte and 20% 2000 bytes.
lengthDistribution#10?1200 –Means that all the packets are 1200 bytes.
Note: The sum of A parameters must be equal to 10.

TdmTimeLength#<uint>      : Specifies the length of the each zone in milliseconds. The
value must be larger than 0.

Optional parameters (Unless stated otherwise above):

[OpenSlotTimeLength#<int>]        : (Mandatory if IncludeOpenSlot is assigned 1)
Specifies the length of the open zone time length in milliseconds. The value must be
larger than 0.

[PacketArrivalRate#<uint>]        : (Mandatory if AlwaysTransmit is assigned 0)
Specifies the average packet arrival rate per second from the IP layer.(Used as the
Lamda parameters of the Poison distribution function). The value must be larger than
0. For values above 200, the simulation will act like in AlwaysTransmit mode.

[RadiusOfArea#<uint>]        : Specifies the radius of the simulated area in meters.
Stations will be randomly generated within this radius. Note: When specifying the
exact location of stations, the user must respect this bound.

StationsLocation#<uint>?<uint>!<uint>?<uint>...              :
The option, combined with the locateStations program, allows the user to set the
location of the stations participating in the simulation.
<a>?<b> stands for: a – radius ;b – angle 0-359 (distance from center).
For example:
StationsLocation#90?100!230?180 Means that we locate 2 stations (the first station
was located 100 meters east from the AP and the other 180 meters south-west from
AP.
Notice: The number of station in this vector overrides the NumOfNodes parameter.

LoggingLevel#<uint>     : Values between 0 and 5. (Default value is 3)
While 1 is the most informative log (every action is being logged) and 5 only
generated the simple output. The 0 value is used for debugging purposes and special
outputs.
Note: Logging is the most "expensive" operation in the simulation. For example : 1
second of simulation with 10 nodes creates log file of 15M and makes the simulation
100 times longer (the simulation in this case lasts 2 seconds).

Title#"<string>"      : This field allows the user to set a title for the test. That title will
be presented in the log file and will make it easier to differentiate between tests.
Note : For titles longer than one word, the string must be placed inside inverted
commas. (Default value is an empty string)
Command line example:
WifiSimulation.exe NumOfNodes#5 AlwaysTransmit#1 IncludeOpenSlot#0
SimulationTime#2 Program#noProgram lengthDistribution#10?1000
TdmTimeLength#50 NumOfAreas#2 RadiusOfArea#75 LoggingLevel#2
Title#"Special Test"

This will simulate 5 randomly placed stations and an AP for 2 seconds. Each station
will always have packets to transmit. The open slot will be disabled and no special
program will be used. (Station posisions will be randomly assigned between r(0,75)
and teta(0,359).All packets will be 1000 bytes long. There will be 2 TDM zones and
every zone will last 50 milliseconds. The logging level will be 2 and the title of the
test is "Special test"

Very Important:
The command line input must be accurate and contain all mandatory parameters in the
right order with case sensitivity. The simulation performs only basic parameter
validation since it was not directed for wide common user usage.
In any case of weird behavior, please refer to the troubleshooting section of this
manual.

GUI usage:
When no command line arguments were given the application will launch the GUI.
The GUI is very simple for use and it does not let the user enter any desired input. For
more advanced runs please use the command line input.




The GUI's defaults are located in Common.cs file.
Results:
The results of each run are presented in Result.csv file (Comma separated file). The
files contents are:
     The simulation's total effective bandwidth.
     The average bandwidth of all nodes.
     The maximum bandwidth of all nodes.
     The minimum bandwidth of all nodes.
     The second minimal value of bandwidth.
     The bandwidth medial value.
     The number of start transmissions and corruptions.
     Title and user's input (in order to identify the simulation).




The results of all runs in the same directory are gathered into the same file.

Logging:
The simulation produces two log files
    Error log - Containing technical problems such as refuted assumptions,
       exceptions, etc. (Errors by simulations ran in the same directory gather in one
       file)
    Simulation log - A detailed log containing the simulated events. The
       information level of this file depends on the user input as stated above.
       (A unique file for each log)
       File name: logger-<year>-<month>-<day>T<time>.log.

Troubleshooting:

       The application was widely tested under more than thousand various tests. At
the time of release there were no open issues or bugs. Even though, in case you
encounter any suspicious behavior, please don't hesitate to contact us.

F.A.Q
Q:" I specified command line inputs, but the simulation doesn't run correctly."
A: This is probably an input problem. Check your input (case sensitivity, spelling,
mandatory fields, etc.)-That will probably solve the problem.

Q: "Still the simulation doesn't function well. What to do?"
A: Open the error file and try to find the problem there.