CogNS: A Simulation Framework For Cognitive Radio Networks

Home Services Awards Company About Contact


Cognitive radio technology has been used to efficiently utilize the spectrum in wireless networks. Although many research studies have been done recently in the area of cognitive radio networks (CRNs), little effort has been made to propose a simulation framework for CRNs. We have proposed and developed a simulation framework based on NS2 (CogNS) for cognitive radio networks.

CR users are equipped with CR transceiver which senses frequency channels and decides about selecting a free channel from the list of free channels and utilize it. These abilities have been simulated in CogNS. All of the nodes have same abilities and configuration. The structure of each CR node object of CogNS, modules, timers and relation of them are illustrated in Fig. 1.

Fig. 1. Structure of the CR node object in CogNS. The MAC and physical layers and the channels have been modified
based on the structure of mobile node object in NS2.

As can be seen in this figure, The MAC layer, physical layer and the channels are modified based on the structure of mobile node object in NS2. The arrows between different layers represent the transmitting of the control information and data packets. Main modification has been done on MAC layer of the Mobile node. In the MAC layer of CogNS, a cognitive CSMA/CA-based MAC protocol is implemented which is named as CogMAC. This protocol and its state diagram has been explained in the paper published in Springer Wireless Personal Communications journal. The personal version of paper can be downloaded here.

You can watch the following video in order to learn step-by-step installation of CogNS:

The steps to install the CogNS in NS2 are as follows:

  • Install ns2.31
  • Download the source files of CogNS
  • Extract the CogNS.rar
  • Change directory to the folder of CogNS in the terminal. Then, run the following command (with this command all files of CogNS are copied to the corresponding folders inside the ns2.31 folder):

    bash "address-of-ns2.31-folder-in-your-system"

    Manual Copy: It is possible to copy the files of CogNS to the corresponding folders inside the ns2.31 folder.
  • Add the following command in the OBJ_CC section of the file "makefile" that is located in the root of ns2.31 folder:

    mac/cogmac.o \
  • Change directory to the folder of ns2.31 in the terminal. Then, run the following command:

    make clean
  • Run the following command (when you are inside the directory of ns2.31):

  • Now, you can use the CogNS.


  1. Using CogMAC as the MAC protocol
  2. The adjustable parameters of CogNS in the tcl files
  3. The file format of PU activity model
  4. A simple example
  5. Executing the simple example

Using CogMAC as the MAC protocol

In order to use the CogMAC protocol in your simulations, you should insert the following command in the parameter setting section of your tcl file:

set val(mac) Mac/Cogmac;

The adjustable parameters of CogNS in the tcl files

It is possible to configure the following parameters in the tcl files:

  1. Tsense_: Spectrum sensing time
  2. Toper_: Operating time
  3. Thandoff_: Spectrum handoff time
  4. ChanNum_: The number of wireless channels
  5. CWMin_: The minimum value of contention window
  6. CWMax_: The maximum value of contention window
  7. channelSelectionPolicy: The channel selection [P]olicy
  8. tryCountlimit_: The maximum number of contention attempts in order to get a channel
  9. contentionPolicy: The contention policy
  10. additionStep: The steps of increasing the contention window
  11. PUDetectionPr: The probability of primary user detection
  12. falseAlarmPr: The false alarm probability in the detection of primary users
  13. bandwidth_: The bandwidth of wireless channels

The file format of PU activity model

The PU activity model is provided through a text file. Each row of the PU model file contains three comma seperated values as follows:


  • channel_number: this field represents the number of wireless channel (an integer value)
  • PU_arrival_time: this field represents the arrival time of primary user (a double value)
  • PU_departure_time: this field represents the departure time of primary user (a double value)

A simple example

The following tcl file is a simple example in order to show how you can use the CogNS:

# test-cogns.tcl -- A simple example using the CogNS
set val(chan) Channel/WirelessChannel      ; #Channel Type
set val(prop) Propagation/TwoRayGround     ; #Radio propagation model
set val(netif) Phy/WirelessPhy              ; #Network interface type
set val(ant) Antenna/OmniAntenna          ; #Antenna model
set val(rp) AODV                         ;#Routing Protocol
set val(ifq) Queue/DropTail/PriQueue      ;# interface queue type
set val(ifqlen) 400                          ;# max packet in ifq
set val(mac) Mac/Cogmac                   ;# MAC type
set val(ll) LL                           ;# link layer type
set val(nn) 25                            ;# number of mobilenodes
set val(channum) 11                         ;# number of channels per radio
set val(cp) ./connections.tcl                  ;# topology traffic file 
set val(stop) 100               ;# simulation time
# ==================================================================
# Main Program
# ======================================================================

# Initialize Global Variables
set ns_    [new Simulator]
set tracefd     [open ./ w]
$ns_ trace-all $tracefd
# set up topography object
set topo       [new Topography]
$topo load_flatgrid 1000 1000
#create nam
set namtrace [open ./test.nam w]
$ns_ namtrace-all-wireless $namtrace 1000 1000

# Create God
set god_ [create-god $val(nn)]
# configure node
$ns_ node-config -adhocRouting $val(rp) -llType $val(ll) -macType $val(mac) -ifqType $val(ifq) -ifqLen $val(ifqlen) -antType $val(ant) -propType $val(prop) -phyType $val(netif) -topoInstance $topo -agentTrace ON -routerTrace ON -macTrace ON -movementTrace ON

#CogMAC Parameters
Mac/Cogmac set channelSelectionPolicy 0 ; # 0: random selection 1:select minimum Interference channel 
Mac/Cogmac set CWMax_ 0.9
Mac/Cogmac set CWMin_ 0.01
Mac/Cogmac set tryCountlimit_ 7
Mac/Cogmac set Tsense_ 0.025
Mac/Cogmac set Toper_ 0.6
Mac/Cogmac set Thandoff_ 0.001
Mac/Cogmac set PUfileROWS 12000
Mac/Cogmac set PUfileCOLS 25
Mac/Cogmac set contentionPolicy 0  ; # 0: additive with additionstep  1: exponential
Mac/Cogmac set additionStep 0.01
Mac/Cogmac set ChanNum_ 11
Mac/Cogmac set fullduplex_mode_ 1
Mac/Cogmac set PUDetectionPr 100
Mac/Cogmac set falseAlarmPr 0
Mac set bandwidth_ 2e6

 for {set i 0} { $i < $val(channum)} {incr i} {
              set chan_($i) [new $val(chan)]

for {set i 0} {$i < $val(channum) } {incr i} {
$ns_ add-channel $i $chan_($i)

#Configure for channels
$ns_ node-config -channel $chan_(0) -ChannelNum $val(channum)

for {set i 0} {$i < $val(nn) } {incr i} {
    set node_($i) [$ns_ node]
         $node_($i) set recordIfall 1
    $node_($i) random-motion 0; # disable random motion
  $node_($i) set isprimaryuser 0

source $val(cp)      ;    #source topology and traffic file generated by others

for {set i 0} {$i < $val(nn)} { incr i } {
# 30 defines the node size for nam
$ns_ initial_node_pos $node_($i) 22

# Tell nodes when the simulation ends
for {set i 0} {$i < $val(nn) } {incr i} {
      $ns_ at $val(stop).0 "$node_($i) reset"; 

$ns_ at  $val(stop).0002 "puts \"NS EXITING...\" ; $ns_ halt "
proc stop {} {
   global ns_ tracefd
    $ns_ flush-trace
    close $tracefd
    exec nam ./test.nam &
    exit 0
puts "Starting Simulation..." 
$ns_ run

Executing the simple example

In order to execute the example, run the following command in the terminal:

ns text-cogns.tcl "address-of-PU-activity-file"

For example, a PU acitivity model has been provided in the folder of "A-Simple-Example" named "a(1)b(1).txt". This model has been generated for PU arrival rate of 1 (α = 1) and departure rate of 1 (β = 1). Therefore, in order to execute the example based on the PU-model file of a(1)b(1).txt, run the following command:

ns text-cogns.tcl "a(1)b(1).txt"

The CogNS is a free software; you can use, edit and redistribute it provided that you give a reference to the following research article:

V. Esmaeelzadeh, R. Berangi, S. M. Sebt, E. S. Hosseini, and M. Parsinia, “CogNS: A Simulation Framework for Cognitive Radio Networks”, Wireless Personal Communications, vol. 72, no. 4, pp. 2849–2865, Oct. 2013.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

Vahid Esmaeelzadeh

Ph.D. in Computer Networks
Wireless Networks Laboratory (WNL)
Department of Computer Engineering
Iran University of Science and Technology (IUST)

Office: Room-203, Department of Computer Engineering,
            Iran University of Science and Technology, Narmak, Tehran, Iran

Home Page:
Phone: (+98) 21 7322 5355