README for Simone V2
Simone - Simulator for OCDMA Network Experimentation

1. Introduction
---------------

The OCDMA Local Area Network simulator Simone simulates a shared, broadcast 
Local Area Network. It simulates a network of several nodes connected by a 
passive optic coupler. It is used for evaluating 
Interference Avoidance, a Media Access Control (MAC) protocol based on State 
Estimation and Transmission Scheduling [1]. It can be modified to evaluate
 any media access control protocol for optical CDMA. 

This document describes how to build and use Simone.
Simone currently works on FreeBSD-4.9. 

2. Building Simone 
------------------

Download the code to a directory
Open the Makefile and change the $SRCBASE variable to reflect the path to the source
Type "make"
An executable called "simone" should be created


3. Running Simone
-----------------

3a. Parameters
------------

Several parameters can be configured:
Physical layer: 
(a) Bandwidth (chipping rate) of the network
(b) Codeset parameters (Length N , Wavelengths A, weight w, kappa K)
(c) Codeset used

MAC layer:
(a) Transmission scheduling algorithm: (Aloha, Selfish, Threshold, Section length
(b) Threshold parameter
State estimation parameters (distances, sensing windows, mode, backoff parameters) will be supported in the next version.

Traffic model
(a) Distribution or from a file
(b) Offered load (this decides the average inter arrival time)
(c) Average packet size

Simulation parameters:
(a) Number of packets in the simulation

For more information about the meaning of the simulation parameters, 
refer to [1], [2] [3].

3b. Command line
---------------
The command is 

./simone <seed> <N> <A> <w> <K> <Chip rate in c/s> <Traffic type> <Input traffic file> <Output traffic file> <Average packet size in bytes> <Normalized offered load> <Number of packets> <Average distance of node in m> <Tx scheduling algorithm> <Threshold>
<Tx scheduling algorithm> 0-Aloha 1-Selfish 2-Threshold 3-Overlap section 4-Overlap size
<Traffic type> 0-Poisson arrivals/Exponential packet lengths 1-Uniform/Uniform 2-Deterministic/Deterministic 3-Poisson/Trimodal 4-From traffic file

The parameters are explained in the previous section.
The simulator either generates traffic or reads the input traffic file. It runs the simulation and dumps the output to the output traffic file.

A codeset file called codes.N.A.w.K.txt must be present before running the simulation. Its format is discussed below. Sample codesets may be generated using the "codegen" tool present in the package.

If the traffic is to be read from a file then a traffic file must be present. Its format is discussed below.

3c. Trace file format
---------------------

The simulator can run using traffic files. The traffic files consist of records for each packet. 
The trace file has the following parameters:
(a) Arrival time of the packet
(b) Source, destination addresses 
(c) Packet sizes 

A sample trace file 1.trc is provided with the simulator code.
The format is 

<timestamp of packet arrival at interface card in seconds> <x coordinate of transmitter> < y coordinate> < z coordinate> <size of packet in bytes> <src address>.<src port> <dst address>.<dst port> <packet id>

<pktid> is a unique identifier (integer) for each packet

E.g.
0.0000000000000 0 0 0 1000 1.1.1.1.80 2.2.2.2.80 0

3d. Codeset file format
----------------------
A sample codeset file codes.10.10.3.3.txt is provided with the simulator code.
The naming format of the codeset file is codes.<code length>.<number of wavelengths><weight>.<kappa>.txt 
The codeset file format supports both 1D and 2D codewords.
 
The codeset file format is below:
<Number of codewords in the codeset>
<Weight of the codeset>
<Codeword1 on  Lambda1> <Codeword1 on Wavelength2>.....
<Codeword2 on  Lambda1> <Codeword2 on Wavelength2>.....
<Codeword3 on  Lambda1> <Codeword3 on Wavelength2>.....
.
. 
.
.


4. Evaluating the output
------------------------

The output trace file format is 
<timestamp of when the packet passed the coupler> <packet size in bytes>  <source addr>.<src port> <dst addr>.<dst port> <packet id> <state of packet (Received/Dropped)> 

Note that the timestamps in the output file will not be in order 
Packets are ordered in the order that they pass the coupler.
The state is 0 for received without error and 1 for received with error.

At the end of the run, the simulator provides the following results:
(a) Number of packets that were sent
(b) Number of packets that survived interference
(c) Offered load
(d) Network throughput
(e) Average number of packets on the line

5. Limitations
	- Tested on FreeBSD 4.9-RELEASE only. Other systems may need modification. 
	- The offered load printed in the output is erroneous when traffic is read from a traffic file

6. References

[1]	P. Kamath, J. D. Touch, and J. A. Bannister, ``Algorithms for Interference 
Sensing in Optical CDMA Networks,'' in IEEE International Conference on
Communications (ICC), June 2004.

[2]	P. Kamath, J. D. Touch, and J. A. Bannister, ``The Need for Media Access 
Control in Optical CDMA Networks,'' in IEEE Infocom, March 2004.

[3]	P. Kamath, J. D. Touch, and J. A. Bannister, ``Transmission scheduling in Optical CDMA Networks'', April 2005.