OMNeT++ in a Nutshell

4/4/2015 OMNeT++ Wiki | Main / OMNeT++ in a Nutshell browse

http://www.omnetpp.org/pmwiki/index.php?n=Main.OmnetppInNutshell 1/9

View Edit History Print

Wiki Home

Back to omnetpp.org

Knowledge Base

OMNeT++ in a NutshellOMNeT++ 4.xINET FrameworkMiXiM wikiNesCT (for TinyOS)JSimpleModuleWSN Algorithms SupportTable

Discussion

Mobile-Adhoc FrameworksOMNeT++ in TeachingModels WantedWiki Site Organization

Older Pages

Workshop 2008 materialOMNeT++ 3.xINET Framework for 3.xMobility FrameworkMACSimulatorPositifOppBSD

Sandbox

People

List of all pages

Main /

OMNeT++ in a NutshellThis page is for those who are somewhat familiar with network simulators, andwould like to find out in a few minutes what OMNeT++ is about. It is probably agood idea to keep the User Manual and the API open in other browser tabs, so thatyou can search for more info there when you find something interesting in this text.

How do those simulation models and frameworksmentioned on omnetpp.org relate to OMNeT++?OMNeT++ provides the basic machinery and tools to write simulations, but itself itdoes not provide any components specifically for computer network simulations,queueing network simulations, system architecture simulations or any other area.Instead, these application areas are supported by various simulation models andframeworks such as INET/INETMANET, MiXiM or Castalia. These models aredeveloped completely independent of OMNeT++, and follow their own releasecycles.

What does OMNeT++ provide then?A C++ class library which consists of the simulation kernel and utility classes (forrandom number generation, statistics collection, topology discovery etc) -- this oneyou will use to create simulation components (simple modules and channels);infrastructure to assemble simulations from these components and configure them(NED language, ini files); runtime user interfaces or environments for simulations(Tkenv, Cmdenv); an Eclipse-based simulation IDE for designing, running andevaluating simulations; extension interfaces for real-time simulation, emulation,MRIP, parallel distributed simulation, database connectivity and so on.

OK. What does an OMNeT++ simulation model looklike?OMNeT++ provides a component architecture. Models are assembled fromreusable components, modules. Well-written modules are truly reusable and can becombined in various ways like LEGO blocks.

Modules can be connected with each other via gates (other systems would callthem ports), and combined to form compound modules. Connections are createdwithin a single level of module hierarchy: a submodule can be connected withanother, or with the containing compound module. Every simulation model is aninstance of a compound module type. This level (components and topology) is dealtwith in NED files. To give you an idea, a component named EtherMAC would bedescribed in NED like this:

//

Search



// Ethernet CSMA/CD MAC // simple EtherMAC { parameters: string address; // others omitted for brevity gates: input phyIn; // to physical layer or the network output phyOut; // to physical layer or the network input llcIn; // to EtherLLC or higher layer output llcOut; // to EtherLLC or higher layer }

And it could be used in the model of an Ethernet station like this:

// // Host with an Ethernet interface // module EtherStation { parameters: ... gates: ... input in; // for connecting to switch/hub, etc output out; submodules: app: EtherTrafficGen; llc: EtherLLC; mac: EtherMAC; connections: app.out --> llc.hlIn; app.in



unassigned in NED files will get their values from ini files -- we'll cover these topicslater.

The OMNeT++ manual has a chapter about the NED language.

How do I run this thing?Provided that you're lucky enough to have EtherMAC, EtherLLC andEtherTrafficGen already programmed by someone else in C++, you'll need tocompile an executable, hack up an omnetpp.ini that says what to run and withwhat parameters, and then you can run it as a standalone simulation program.

Building the simulation program is usually quite straighforward. In thesimplest case, when everything is in one directory (and OMNeT++ is properly setup), you just need to type

opp_makemake --deep make

opp_makemake creates a makefile with the appropriate settings, so you don't haveto do anything else.

If you have sources in several directories, such as when you use some modelframework like the Mobility Framework or the INET Framework, then this simplemethod of generating the makefile won't work, because the simulation will need tolink with code from other directories as well. Then you'll need to pass additionaloptions to opp_makemake such as -I; it is best to check the given framework'sdocumentation or existing makefile system for a hint.

To run the executable, you need an omnetpp.ini file. Without it you get thefollowing error:

$ ./etherlan OMNeT++/OMNEST Discrete Event Simulation (C) 1992-2005 Andras Varga [....] Error during startup: Cannot open ini file `omnetpp.ini'

One function of the ini file is to tell which network to simulate (there might be morethan one network definitions in the NED files). You can also specify where to loadNED files from, assign module parameters, specify how long the simulation shouldrun, what seeds to use for random number generation, how much results to collect,set up several experiments with different parameter settings, etc. An exampleomnetpp.ini (hopefully self-explaining):

[General] network = etherLAN *.numStations = 20 **.frameLength = normal(200,1400) **.station[0].numFramesToSend = 5000 **.station[1-5].numFramesToSend = 1000 **.station[*].numFramesToSend = 0



As you can see you can use wildcards when assigning module parameters.Parameter assignments in the NED file take place first, and those left unassignedcan be assigned in the ini file. (That is, parameter values in NED cannot beoverwritten from the ini file.) If there are still parameters without a value, those oneswill be asked interactively at runtime.

Why do we have separate NED and ini files, why isn't everything contained in asingle model file? Simulation is about creating a model, experimenting with it, anddrawing conclusions. In OMNeT++, C++ and the NED files represent the model,and experiments are described in ini files: parameter values, results to collect,seeds etc. Ini files let you keep the model unchanged while you're exploring theparameter space. (Note that parameters can also affect the topology, e.g. candenote the number of nodes in the network).

To load an ini file with a different name, pass the file name as command-lineargument. More than one ini file can also be loaded, with the effect of their contentsgetting merged.

$ ./etherlan common-settings.ini params15.ini seeds3.ini

Ini files also support inclusion, which is useful if you have common settings to factorout. The manual describes the ini file facility in detail, including a complete list of inifile options supported.

By default, the simulation executable builds with the graphical user interface,Tkenv. To run the simulation under the command-line (batch) user interfaceCmdenv, specify the -u Cmdenv option:

$ ./etherlan -u Cmdenv

It is also very easy to link the simulation with only Tkenv or Cmdenv. Since it's thiseasy to switch to a different UI, you could create your own GUI as well if youwanted. This is easier than you think -- reading src/cmdenv/cmdenv.cc would giveyou an idea how to do it. Embedding OMNeT++ into another application (e.g. somedesign or analysis tool that employs simulation) would go in a very similar way, andit has already been done by some commercial companies usingOMNeT++/OMNEST.

How to use the Tkenv GUI? Here we don't go into details -- please explore it byclicking and right-clicking everywhere, looking into the menus, etc. There are alsoresources in the Wiki's Omnetpp4 section.

What is the output of the simulation?The simulation results are recorded into output vector (.vec) and output scalar(.sca) files. The capability to record simulation results has to be programmed intothe simple modules, so if you're dealing with a simulation model written bysomeone else, it may or may not create these files.

An output vector file contains several output vectors, each being a named series of(timestamp, value) pairs. Output vectors can store things like queue length overtime, end-to-end delay of received packets, packet drops or channel throughput --



whatever the simple modules in the simulation have been programmed to record.You can configure output vectors from omnetpp.ini: you can enable or disablerecording individual output vectors, or limit recording to a certain simulation timeinterval. To find out what output vectors a simple module can record, look forcOutVector objects in its C++ source code. Newer models record statistics via thesignals framework, and statistics are declared in the NED files -- look for@statistic lines in them.

Output vectors capture behaviour over time. Output scalar files, on the other hand,contain summary statistics: number of packets sent, number of packet drops,average end-to-end delay of received packets, peak throughput. To check outputscalars in the C++ code, look for recordScalar() calls, typically in the finish()method of simple module classes.

Simulation results can be visualized in the Analysis Editor of the OMNeT++ IDE.

What about random numbers?OMNeT++'s default random number generator is Mersenne Twister. (A legacy LCGgenerator with a 231-1 long sequence is also available and can be configured inomnetpp.ini). OMNeT++ provides a configurable number of RNG instances (thatis, streams), which can be freely mapped to individual simple modules inomnetpp.ini. This means that you can set up a simulation model so that all trafficgenerators use global stream 0, all MACs use global stream 1 for backoffcalculation, and physical layer uses global stream 2 and global stream 3 for radiochannel modelling; you can configure this RNG mapping using wildcards inomnetpp.ini. Seeding can be automatic or manual; manual seeds also come fromthe ini file.

Several distributions are supported (in the 3.2 version 14 continuous and 6 discretedistributions, see the API doc), and they are available from both NED and C++.Non-const module parameters can be assigned random variates likeexponential(0.2), which means that the C++ code will get a different numbereach time it reads the parameter; this is a very convenient way of specifyingparameters for random traffic sources. (const parameters can also be assignedexpressions like exponential(0.2), but there it will be evaluated only once andthen stuck with it).

Can I do MRIP, parallel distributed simulation, networkemulation, or feature X with OMNeT++?Yes. OMNeT++ is very extensible, plus you have all of the source code, so the skyis the limit. Several features are supported out of the box, and it is easier andcleaner to implement others than you think. Ask for guidance on the mailing list ifyou have such plans.

MRIP stands for multiple replications in parallel, and Akaroa is an excellent tools forthat. You'll need to download and install it separately, then configure and recompileOMNeT++ with Akaroa support enabled (see configure.user). AFAIK Akaroa isavailable on Linux (*nix) only. Search for Akaroa in the OMNeT++ manual to learnmore.

Very large simulations may benefit from the parallel distributed simulation (PDES)



feature, either by getting speedup, or distributing memory requirements. If yoursimulation requires a few Gigabytes of memory, distributing it over a cluster may bethe only way to run it. For getting speedup (and not actually slowdown, which isalso easily possible), the hardware or cluster should have low latency and themodel should have inherent parallelism. Partitioning and other configuration can beconfigured in omnetpp.ini, the simulation model itself doesn't need to be changed(unless, of course, it contains global variables and the like that prevents distributedexecution in the first place.) The communication layer is MPI, but it's actuallyconfigurable, so if you don't have MPI you can still run some basic tests overnamed pipes, or (really for testing or debugging!) file-based message exchange. Or,if you care, you can add new ones by implementing the abstractcParsimCommunications interface.

Network emulation, together with real-time simulation and hardware-in-the-loop likefunctionality, is available because the event scheduler in the simulation kernel ispluggable. The OMNeT++ distribution contains a demo of real-time simulation anda simplistic example of network emulation, enough to give you hints if you're intothis area. Real network emulation with the INET Framework is in the queue.

Interfacing OMNeT++ with other simulators (hybrid operation) or HLA is also largelya matter of implementing one's own scheduler class. Once you get the idea you'llfind that it's much easier to do than you would have thought.

It is possible to replace omnetpp.ini with a database as the source ofconfiguration data, and to redirect results (output vectors and scalars) into adatabase. The standard OMNeT++ distribution also contains demo of that; or youcan check out how others have done it.

And again, since you have the full source code, and it's structured anddocumented, you can implement pretty much all your ideas. If you contact me onthe mailing list or directly, I'll be happy to give you some initial directions.

OK! Now, how do I program a model in C++?Simple modules are C++ classes. You'll subclass from cSimpleModule, redefine afew virtual member functions to add your code, and register the new class withOMNeT++ via the Define_Module() macro.

Modules primarily communicate via message passing, and timers (timeouts) arealso handled with messages the module sends to itself (self-messages). Messagesare either of class cMessage, or of some class derived from cMessage. Messagesare delivered to the handleMessage(cMessage *msg) method of the module, sothis is one you will surely want to redefine and add your code into. Almosteverything you want the module to do will go inside handleMessage(). It can easilygrow too long, so it's a good idea to factor out chunks of it into other memberfunctions which you can name processTimer(), processPacket(), etc.

You can read about activity() as an alternative to handleMessage(), butin practice there are several good reasons to avoid using it.

You can send messages to other modules using the send(cMessage *msg, constchar *outGateName) call. For wireless simulations and some other cases it can bemore convenient to send messages directly to other modules without having



connections set up to them in the NED file; this can be done withsendDirect(cMessage *msg, double delay, cModule *targetModule, constchar *inGateName). Self-messages can be sent (that is, timers can be scheduled)via scheduleAt(simtime_t time, cMessage *msg), and before they expire theycan be cancelled via cancelEvent(cMessage *msg). Like many others, thesefunctions are all members of the cSimpleModule class; look it up in the API-doc tosee further variants and other functions.

The basic cMessage class contains several data members, the practically mostimportant ones being name, length, message "kind" (an int member). Other datamembers store information about the most recent sending/scheduling of themessage: arrival time, arrival gate, etc. To facilitate protocol simulations, cMessagecan encapsulate one other cMessage object, see its encapsulate(cMessage*msg), decapsulate() methods; these methods modify the length field accordinglyas well. If you need to carry more data in the message, other data members can beadded via subclassing. However, you don't need to write the new C++ class byhand, it is more convenient to define it in a .msg file instead, and let OMNeT++ (theopp_msgc tool) generate the C++ class for you. Generated C++ files will have the_m.h, _m.cc suffix. .msg files support further inheritance, composition, arraymembers etc, and have syntax that allows you to customize the class in C++ aswell. An example message file:

message NetworkPacket { fields: int srcAddr; int destAddr; }

OMNeT++ is often used to simulate network protocol stacks, and cMessage has afield called control info that carries auxiliary information to facilitate communicationbetween protocol layers. For example, when the application layer sends data (amessage object) to TCP for transmission, it can attach a piece of control info (anobject) to the message which contains the socket identifier. Or, when TCP sends aTCP segment down to IP for transmission, it attaches control info to it that carriesthe destination IP address, and possibly other options like TTL. Control info is sentin the other direction (upwards) as well, to indicate source IP address or TCPconnection to upper layers. Control info is handled via cMessage'ssetControlInfo(cPolymorpic *ctrl) and removeControlInfo() methods.

Other cSimpleModule virtual member fuctions you may need to redefine areinitialize() (you'll want to do most initialization here, since during theconstructor call the model is still being built), initialize(int stage) and intnumInitStages() const for multi-stage initialization (that's useful if one module'sinitialization code depends on another module already having been initialized), andfinish() for recording summary results (the destructor is not suitable for that). Ifyou want the module to take notice of runtime changes in its parameters(parameters can be changed interactively from the GUI, or programmatically byanother module -- and you may want the module to re-read the parameters then),redefine the handleParameterChange(const char *paramName) method.

A simple module's NED parameters can be read using the par(const char*paramName) method; typically you'll want to do this in initialize(), and store



the values in data members of the module class. par() returns a reference to acPar object which you can cast to the appropriate type (long, double, const char*, etc) with the C/C++ cast syntax or by calling the object's doubleValue() etc.methods. In addition to basic types such as long, bool, double and string, there isXML as well: parameters can be assigned small (or not so small) XML documentsor document fragments, which are presented to the C++ code as a DOM-like objecttree.

Message exchange is not always the most suitable way of interaction betweenmodules. For example, if you have a designated module for statistics collection(very much preferred over global variables!!!), then instead of sending the statisticsupdates to it via messages, it is more convenient to regard the statistics module asa C++ object and call a public member function of it created for this purpose (e.g.updateStatistics(...)).

Direct method calls have a few tricky details. First you have to find the othermodule: the parentModule(), submodule(const char *name) methods ofcModule let you navigate relative to the current module, andsimulation.moduleByPath(const char *path) lets you find a module globally,by an absolute path name. Once you have the pointer of the other module, youneed to cast it to the actual type (i.e. to StatisticsCollector* from cModule*);this is done by check_and_cast which has the same syntax as C++'sdynamic_cast but throws an error if the cast unsuccessful or the pointer is NULL.The public method should have Enter_Method(...) orEnter_Method_Silent(...) at the top -- this enables animation of the call on theGUI, and also does something slightly obscure called temporary context switch (wedon't want to go into details here, but it's especially needed if you do messagehandling in the method). The INET Framework extensively uses method calls toaccess modules like RoutingTable, InterfaceTable, NotificationBoard, etc.

INET's NotificationBoard is actually a module that can be useful in othernontrivial simulations as well: it supports sharing information among severalmodules by decoupling producers and consumers of information, by relayingchange notifications or event notifications among them. (NotificationBoard isloosely based on the blackboard idea, but in practice it is a lot easier, simpler andmore efficient to just relay notifications than storing published information on theblackboard; moreover, notifications may contain a copy of the actual data or apointer to them.)

For debugging, it is essential that modules print some info about what they're doing.Instead of printf() and cout



output vector, then keep calling its record(double value) method to recordnumbers. Output scalars are best written from the finish() function of the module(see the recordScalar(const char *name, double value) method ofcModule), based on counters etc you keep in the module class as data members. Itis also possible to calculate basic statistics and histograms; check the cStdDev,cDoubleHistogram and cLongHistogram classes.

NED files describe static topology, but it is also possible to create modules andconnections dynamically. This can be useful when you have the network topology insome other form than a NED file (plain text file, Excel sheet, database etc), or youtruly want to create and delete modules dynamically during runtime. In the formercase, often it is an easier solution to convert the data into NED by using Awk, Perl,Python, Ruby, Tcl or a series of regex find/replace operations in a text editor;however, if you're deciding for using dynamic module creation from C++, theninvoking nedtool on a sample NED file and looking at the generated _n.cc file canbe very helpful.

* * * * *

Hope you've found this page useful. Suggestions, fixes, questions are welcome --you can post them on the mailing list, or just add them below by editing the page. --Andras

Edit - History - Print - Recent Changes - SearchPage last modified on July 05, 2010, at 01:39 PM

Documents

OMNeT++ in a Nutshell