Learn, Imagine, Build
Geoff Messier's Projects & Ideas
ns3 is a discrete event simulator written in C++. It is a very large open source software project and you will need to spend some time setting up your C++ development environment in order to work effectively with the simulator.
You will be working with three main components:
Note that the instruction below assumes that you’re using either a linux machine or a mac (OS X is also a unix based operating system under the hood). Installing and running ns3 on Windows is not recommended. If you want to also use windows, also install linux on your machine using either a virtual machine or dual boot setup.
The ns3 simulator is essentially just a bunch of directories filled with C++ files. The simulator is configured, compiled and run using the waf script system.
Your first step should be to install the ns3 source code from the command line using mercurial as described here. Rather than downloading the entire simulation package (which has a bunch of visualization stuff we don’t need and is fussy to compile), you should download just the ns3 code itself. So, instead of using the ns-3-allinone source directory, target just the core ns3 simulator by typing:
hg clone http://code.nsnam.org/ns-3.27
or whatever version of the code is most up to date (3.27, etc.).
The FISH Lab ns3 code has been developed over time by Dr. Messier and other students like you. This code is organized and maintained on GitHub. It is managed using a branch and merge approach. You will be given your own branch of the simulator source code that you can modify and update on GitHub to keep track of your changes. Dr. Messier will periodically examine your code with you and provide feedback on your software design. Software development organizations refer to this as a code review.
To start working in your own branch, follow these steps:
git clone -b your-branch-name --single-branch https://github.com/ggmessier/ns3-isa100.11a.git your-branch-name
where your-branch-name will be the branch name Dr. Messier gives you. This will create a copy of the ISA100 simulator code on your machine in a directory with the same name as your branch.
src directory. You need to add a symbolic link to the ISA100 code from the src directory within your ns3 installation. You do this using the command
cd src
ln -s <path containing cloned code>/your-branch-name isa100-11a
which creates a symbolic link named isa100-11a.
waf configure and recompile the simulation to make sure there are no errors.The current version of the IS100 code requires IBM’s CPLEX library. You should download the linux version of the library and ensure you have all the pre-req linux packages to compile it.
Once you have CPLEX installed, you will need to modify the wscript
The eclipse program is essentially a very sophisticated code editor that also provides an interface for you to manage GitHub cloned code, compile the simulator and debug it.
To install, just follow the directions here and make sure you install C++ language support and the git plug-in. Your computer also needs a command line C++ compiler (usually gcc) and the GNU debugger (gdb or ggdb).
The next step is to configure eclipse to interact with the ns3 project. The main instructions can be found here with some additional instructions given at the end of this section.
ns-3-dev directory but your directory will likely be named ns-3.27 (or whatever version number is most recent).build/scratch subdirectory and looking for something that matches the name of the source file you’ve copied into the ns3 scratch directory.It’s also nice to be able to manage your GitHub repository from within eclipse. To do this, install the EGit add-on as described here. Since you only have the ISA100.11a code up on GitHub and not all the ns3 source code, I usually create a separate project in ns3 that points directly at the directory containing your cloned github branch code. Specifically:
That should be it. Inside your new GitHub linked project, you can now do nifty things like compare your current code to other branches or previous versions of this branch by right clicking and selecting Compare With.
Logically, you need to first learn how ns3 works before you can learn the ISA100 ns3 simulation. Currently, the FISH ISA code works with ns version 3.27 and the documentation for this release of the simulator can be found here. There are three documents you should look at: the tutorial, the manual and the doxygen API page.
This is the best place to start. It’s all worth a look but you should for sure go over:
The important sections here are:
In particular, you should be clear that you understand logging and tracing since those are the mechanisms that you will use to get performance data out of your simulator.
This page is auto-generated by the doxygen tool and is essentially a gigantic listing of all classes, member functions, member variables, etc. that make up the ns3 simulator. You definitely should not attempt to read this as a learning exercise. It’s useful mainly for it’s little search window that allows you to search up specific classes and functions.
ISA100.11a is a wireless networking standard specifically designed for high reliability industrial control applications. The standard utilizes an 802.15.4 physical layer and then redefines everything from the data link (DL) layer upwards. The purpose of this page is to help you learn the FISH implementation of the ns3 ISA100.11a simulator.
Located in the doc directory of the ISA100 SVN repository is a document written specifically to describe the FISH simulation. It’s a relatively brief, very high level document but it should give you a rough idea of what classes do what and how the different objects in the simulator interact.
After reading this document, you can start going through the code with the help of the ISA 100 doxygen page for the code that you generate yourself by simply typing doxygen in the root directory of ISA100 sim code directory. This will auto-generate a doxygen page in the empty doxygen directory in your branch. You can view the page by opening doxygen/html/index.html within your web browser.
Before diving into the standards documents, it’s useful to read over a few survey papers that provide an overview of the ISA 100 standard and wireless networking for automation in general. Two good ones are written by Petersen and Christin and can be found in the doc/refs directory of the ISA100 simulator code.
The 802.15.4 and ISA100 standards documents are located in the ‘‘doc’’ directory of the FISH ISA100 simulation code SVN repository. These documents are difficult to read start to finish and you should not attempt this. However, you should at least scan the table of contents and the intro sections to each chapter to get an idea of what the documents contain. As you develop your simulation, you will almost certainly be referring to these documents to see if what you’re doing does/doesn’t satisfy the standards.