OMNeT++ - gipuzkoa · Introduction OMNeT++ is an object-oriented modular discrete event system simulation framework. It has a generic architecture, so it can be used in various problem

OMNeT++

I User Manual

I API Reference

I IDE User Guide

I Install Guide

omnetpp.org/documentation

F. Xabier Albizuri - 2014

Introduction

OMNeT++ is an object-oriented modular discrete event systemsimulation framework.

It has a generic architecture, so it can be used in various problemdomains: modeling communication networks, protocol modeling,queueing networks, multiprocessors and other distributed hardwaresystems, in general, modeling and simulation of any system wherethe discrete event approach is suitable, and can be convenientlymapped into entities communicating by exchanging messages.

OMNeT++ itself is not a simulator of anything concrete, butrather provides infrastructure and tools for writing simulations.One of the fundamental ingredients of this infrastructure is acomponent architecture for simulation models.

Modeling Concepts

An OMNeT++ model consists of modules that communicate withmessage passing. The active modules are termed simple modules;they are written in C++, using the simulation class library. Simplemodules can be grouped into compound modules and so forth; thenumber of hierarchy levels is unlimited. The whole model, callednetwork in OMNeT++, is itself a compound module.

Modules communicate with messages that may contain arbitrarydata, in addition to usual attributes such as a timestamp. Simplemodules typically send messages via gates, but it is also possible tosend them directly to their destination modules.

Modeling Concepts

Modeling Concepts

Gates are the input and output interfaces of modules: messages aresent through output gates and arrive through input gates. An inputgate and output gate can be linked by a connection. Within acompound module, corresponding gates of two submodules, or agate of one submodule and a gate of the compound module can beconnected.

Connections spanning hierarchy levels are not permitted. Becauseof the hierarchical structure of the model, messages typically travelthrough a chain of connections, starting and arriving in simplemodules.

Modeling Concepts: Hierarchical Modules

An OMNeT++ model consists of hierarchically nested modulesthat communicate by passing messages to each other. Modelstructure is described in OMNeT++’s NED language.

Modules that contain submodules are termed compound modules,as opposed to simple modules at the lowest level of the modulehierarchy. Simple modules contain the algorithms of the model.The user implements the simple modules in C++, using thesimulation class library.

Modeling Concepts: Module Types

Both simple and compound modules are instances of module types.In describing the model, the user defines module types; instancesof these module types serve as components for more complexmodule types. Finally, the user creates the system module as aninstance of a previously defined module type.

When a module type is used as a building block, it makes nodifference whether it is a simple or compound module. This allowsthe user to split a simple module into several simple modulesembedded into a compound module, or vice versa, to aggregate thefunctionality of a compound module into a single simple module.

Module types can be stored in files separately, the user can groupexisting module types and create component libraries.

Modeling Concepts: Messages, Gates, Links

Modules communicate by exchanging messages. In an actualsimulation, messages can represent frames or packets in acomputer network, jobs or customers in a queuing network or othertypes of mobile entities. Messages can contain arbitrarily complexdata structures.

The local simulation time of a module advances when the modulereceives a message. The message can arrive from another moduleor from the same module (self-messages are used to implementtimers).

Gates are the input and output interfaces of modules; messages aresent out through output gates and arrive through input gates.

Modeling Concepts: Messages, Gates, Links

Each connection (also called link) is created within a single placeof the module hierarchy: within a compound module, one canconnect the corresponding gates of two submodules, or a gate ofone submodule and a gate of the compound module.

Because of the hierarchical structure of the model, messagestypically travel through a series of connections, starting andarriving in simple modules.

Simple modules can send messages either directly to theirdestination, or through gates and connections.

Modeling Concepts: Modeling of Packet Transmissions

To facilitate the modeling of communication networks, connectionscan be used to model physical links.

Connections support the following parameters: data rate,propagation delay, bit error rate and packet error rate, and may bedisabled. These parameters and the underlying algorithms areencapsulated into channel objects. The user can parameterize thechannel types provided by OMNeT++, and also create new ones.

When data rates are in use, a packet object is by default deliveredto the target module at the simulation time that corresponds tothe end of the packet reception. Since this behavior is not suitablefor the modeling of some protocols, OMNeT++ provides thepossibility for the target module to specify that it wants the packetobject to be delivered to it when the packet reception starts.

Modeling Concepts: Parameters

Modules can have parameters, and they can be assigned in eitherthe NED files or the configuration file omnetpp.ini.

Parameters can be used to customize simple module behavior.

Parameters can take string, numeric or boolean values, or cancontain XML data trees. Numeric values include expressions usingother parameters and calling C functions, random variables fromdifferent distributions, and values input interactively by the user.

Numeric-valued parameters can be used to construct topologies ina flexible way. Within a compound module, parameters can definethe number of submodules, number of gates, and the way theinternal connections are made.

Using OMNeT++: Building and Running Simulations

An OMNeT++ model consists of the following parts:

I NED language topology descriptions (.ned files) that describethe module structure with parameters, gates, etc. NED filescan be written using any text editor. The OMNeT++ IDEprovides excellent support for graphical and text editing.

I Message definitions (.msg files). You can define variousmessage types and add data fields to them. OMNeT++ willtranslate message definitions into full-fledged C++ classes.

I Simple module sources. They are C++ files, with .h/.cc suffix.

The simulation system (C++ compiled into libraries) provides:

I Simulation kernel. This contains the code that manages thesimulation and the simulation class library.

I User interfaces used in simulation execution, to facilitatedebugging, demonstration, or batch execution of simulations.


Simulation programs are built from the above components:

I First, .msg files are translated into C++ code using theopp msgc program.

I Then all C++ sources are compiled and linked with thesimulation kernel and a user interface library.

I NED files are loaded dynamically in their original text formswhen the simulation program starts.

The simulation may be compiled as a standalone programexecutable (for other machines without OMNeT++), or it can becreated as a shared library (OMNeT++ shared libraries must bepresent). When the program is started, it first reads all NED filescontaining your model topology, then it reads a configuration fileusually called omnetpp.ini. This file contains settings that controlhow the simulation is executed, values for model parameters, etc.The configuration file can also prescribe several simulation runs.


The output of the simulation is written into result files: outputvector files, output scalar files, and possibly the user’s own outputfiles. Output files are line-oriented text files. The OMNeT++ IDEprovides rich environment for analyzing these files.

User Interfaces. The primary purpose of user interfaces is to makethe internals of the model visible to the user, to control simulationexecution, and possibly allow the user to intervene by changingvariables/objects inside the model.

The same simulation model can be executed with various userinterfaces. The user would typically test and debug the simulationwith a powerful graphical user interface, and finally run it with asimple, fast user interface that supports batch execution.

The NED Language: Overview

The user describes the structure of a simulation model in theNEtwork Description language.

NED lets the user declare simple modules, and connect andassemble them into compound modules. The user can label somecompound modules as networks; that is, self-contained simulationmodels.

Channels are another component type, whose instances can also beused in compound modules.

The NED language has several features which let it scale well tolarge projects.

The NED Language: Overview

Hierarchical. A too complex module can be broken down intosmaller modules, and used as a compound module.

Component-Based. Simple modules and compound modules areinherently reusable, which allows component libraries to exist.

Interfaces. Module and channel interfaces can be used as aplaceholder where normally a module or channel type would beused, and the concrete module or channel type is determined atnetwork setup time by a parameter.

Inheritance. Modules and channels can be subclassed. Derivedmodules and channels may add new parameters, gates, and (in thecase of compound modules) new submodules and connections.They may set existing parameters to a specific value, and also setthe gate size of a gate vector.

Packages (Java-like), Inner types (channel types and module typesdefined within a compound module), Metadata annotations.

The NED Language: Quickstart

We introduce the NED language via an example: a communicationnetwork.

Our hypothetical network consists of nodes. On each node there isan application running which generates packets at randomintervals. The nodes are routers themselves as well.

We assume that the application uses datagram-basedcommunication, so that we can leave out the transport layer fromthe model.



//

// The NED description of my system

//

network MyNetwork

{

submodules:

node1: Node;

node2: Node;

node3: Node;

...

connections:

node1.port++ <--> {datarate=100Mbps;} <--> node2.port++;



...

}

The NED Language: QuickstartThe above code defines a network type named MyNetwork. Thenetwork contains several nodes, named node1, node2, etc. fromthe NED module type Node.

The port++ notation adds a new gate to the port[] gate vector.The double arrow means bidirectional connection. Nodes areconnected with a channel that has a data rate of 100Mbps.

The above code would be placed into a NED file, sayMyNetwork.ned. It is a convention to put every NED definitioninto its own file and to name the file accordingly, but it is notmandatory to do so.

One can define any number of networks in the NED files, and forevery simulation the user has to specify which network to set up.The usual way of specifying the network is to put the networkoption into the configuration, by default the omnetpp.ini file:

[General]

network = MyNetwork


One can create a new channel type that encapsulates the data ratesetting, and this channel type can be defined inside the network sothat it does not litter the global namespace. Concepts used: innertypes, channels, the DatarateChannel built-in type, inheritance.

network MyNetwork

{

types:

channel C extends ned.DatarateChannel {

datarate = 100Mbps;

}

submodules:

...

connections:

node1.port++ <--> C <--> node2.port++;

node2.port++ <--> C <--> node4.port++;

...

}


Simple modules are the basic building blocks for other (compound)modules, denoted by the simple keyword. All active behavior inthe model is encapsulated in simple modules. Behavior is definedwith a C++ class; NED files only declare the externally visibleinterface of the module (gates, parameters).

The functionality of the module Node is quite complex, so it isbetter to implement it with several smaller simple module typeswhich we are going to assemble into a compound module:

I A simple module for traffic generation (App),

I One for routing (Routing),

I And one for queueing up packets to be sent out (Queue).

By convention, the above simple module declarations go into theApp.ned, Routing.ned and Queue.ned files.


simple App

{

parameters:

int destAddress;

...

@display("i=block/browser");

gates:

input in;

output out;

}

simple Routing

{

...

}

simple Queue

...


The simple module App has a parameter called destAddress

(others have been omitted for now), and two gates named out andin for sending and receiving application packets.

The argument of @display() is called a display string, and itdefines the rendering of the module in graphical environments;i=... defines the default icon.

Generally, @-words like @display are called properties in NED, andthey are used to annotate various objects with metadata.Properties can be attached to files, modules, parameters, gates,connections, and other objects, and parameter values have a veryflexible syntax.

We can assemble App, Routing and Queue into the compoundmodule Node.



module Node

{

parameters:

int address;

@display("i=misc/node_vs,gold");

gates:

inout port[];

submodules:

app: App;

routing: Routing;

queue[sizeof(port)]: Queue;

connections:

routing.localOut --> app.in;

routing.localIn <-- app.out;

for i=0..sizeof(port)-1 {

routing.out[i] --> queue[i].in;

routing.in[i] <-- queue[i].out;

queue[i].line <--> port[i];


}

}

The compound module Node contains an address parameter, plusa gate, named port. The type of port[] is inout, which allowsbidirectional connections. It is legal to refer to sizeof(port), thegate vector size will be determined implicitly by the number ofneighbours when we create a network from nodes of this type.

The Node module type has an app submodule and a routing

submodule, plus a queue[] submodule vector that contains oneQueue module for each port.

In the connections section, the submodules are connected to eachother and to the parent module (single arrows are used to connectinput and output gates, and double arrows connect inout gates).


Putting it together:

I When the simulation program is started, it loads the NEDfiles.

I The program should already contain the C++ classes thatimplement the needed simple modules (App, Routing andQueue); their C++ code is either part of the executable or isloaded from a shared library.

I The simulation program also loads the configuration(omnetpp.ini), and determines from it that the simulationmodel to be run is the MyNetwork network. Then the networkis instantiated for simulation.

The simulation model is built in a top-down preorder fashion:starting from an empty system module, all submodules are created,their parameters and gate vector sizes are assigned, and they arefully connected before the submodule internals are built.

The NED Language: Simple Modules

Simple modules are the model active components. An example(parameters and gates sections are optional):

simple Queue

{

parameters:

int capacity;

@display("i=block/queue");

gates:

input in;

output out;

}

The NED definition doesn’t contain any code to define theoperation of the module: that part is expressed in C++. Bydefault, OMNeT++ looks for C++ classes of the same name asthe NED type (so here, Queue).

The C++ classes need to be subclassed from cSimpleModule class.

The NED Language: Simple ModulesOne can explicitly specify the C++ class with the @class property.Classes with C++ namespace qualifiers are also accepted.

simple Queue

{

parameters:

int capacity;

@class(mylib::Queue);

@display("i=block/queue");

...

}

If you have several modules in a file that are all in a commonnamespace, then a better alternative to @class is the @namespace

property, specified at the file level (@namespace(mylib);). Thenamespace will be prepended to the normal class name. Moreover,when the @namespace property is placed in a file calledpackage.ned, the namespace will apply to all files in the samedirectory and all directories below.

The NED Language: Simple Modules

Simple modules can be extended or specialized via subclassing.The motivation for subclassing can be to set some openparameters or gate sizes to a fixed value, or to replace the C++class with a different one. By default, the derived NED moduletype will inherit the C++ class from its base; you need to writeout @class if you want it to use the new class.

The following examples show how to specialize a module and howto override the inherited C++ class.

simple BoundedQueue extends Queue

{

capacity = 10;

}

simple PriorityQueue extends Queue

{

@class(PriorityQueue);

}

The NED Language: Compound Modules

A compound module groups other modules into a larger unit. Noactive behavior is associated with it. A compound moduledeclaration may contain several sections, all of them optional:

module Host

{

types:

...

parameters:

...

gates:

...

submodules:

...

connections:

...

}


Modules contained in a compound module are called submodules.One can create arrays of submodules (i.e. submodule vectors), andthe submodule type may come from a parameter.

Connections are listed under the connections section of thedeclaration. One can create connections using simple programmingconstructs (loop, conditional). Connection behaviour can bedefined by associating a channel with the connection; the channeltype may also come from a parameter.

Module and channel types only used locally can be defined in thetypes section as inner types (to not pollute the namespace).

Compound modules may be extended via subclassing. Inheritancemay add new submodules and new connections as well, not onlyparameters and gates. Also, one may refer to inherited submodules,to inherited types etc. What is not possible is to de-inherit ormodify submodules or connections.


We show a stub for wireless hosts. Module types and gate namesare fictional (not a real framework). We add user agents viasubclassing. The module is further extended with an Ethernet port.

module WirelessHostBase

{

gates:

input radioIn;

submodules:

tcp: TCP;

ip: IP;

wlan: Ieee80211;

connections:

tcp.ipOut --> ip.tcpIn;

tcp.ipIn <-- ip.tcpOut;

ip.nicOut++ --> wlan.ipIn;

ip.nicIn++ <-- wlan.ipOut;

wlan.radioIn <-- radioIn;

}


module WirelessHost extends WirelessHostBase

{

submodules:

webAgent: WebAgent;

connections:

webAgent.tcpOut --> tcp.appIn++;

webAgent.tcpIn <-- tcp.appOut++;

}

module DesktopHost extends WirelessHost

{

gates:

inout ethg;

submodules:

eth: EthernetNic;

connections:

ip.nicOut++ --> eth.ipIn;

ip.nicIn++ <-- eth.ipOut;

eth.phy <--> ethg;

}

The NED Language: Channels

Channels encapsulate parameters and behaviour associated withconnections.

Channels are like simple modules, in the sense that there are C++classes behind them. The default class name is the NED type name(unless there is a @class property).

There are predefined channel types that you can subclass from.The predefined types are (you can get rid of the package name ifyou import the types with the import ned.* directive):

I ned.IdealChannel

I ned.DelayChannel

I ned.DatarateChannel

The C++ class is inherited when the channel is subclassed.


IdealChannel has no parameters, and lets through all messageswithout delay or any side effect. A connection without a channelobject and a connection with an IdealChannel behave in the sameway. Still, this type has its uses when a channel object is required.

DelayChannel has two parameters:

I delay is a double parameter which represents the propagationdelay of the message. Values need to be specified togetherwith a time unit (s, ms, us, etc.)

I disabled is a boolean parameter that defaults to false; whenset to true, the channel object will drop all messages.


DatarateChannel has a few additional parameters compared toDelayChannel:

I datarate is a double parameter that represents the data rateof the channel. Values need to be specified in bits per secondor its multiples as unit (bps, kbps, Mbps, Gbps, etc.) Zeroresults in zero transmission duration, i.e. it stands for infinitebandwidth. Zero is also the default. Data rate is used forcalculating the transmission duration of packets.

I ber and per stand for Bit Error Rate and Packet Error Rate,and allow basic error modelling. They expect a double in the[0, 1] range. When the channel decides (based on randomnumbers) that an error occurred during transmission of apacket, it sets an error flag in the packet object. The receivermodule is expected to check the flag, and discard the packetas corrupted if it is set. The default ber and per are zero.


A new channel type by specializing DatarateChannel:

channel Ethernet100 extends ned.DatarateChannel

{

datarate = 100Mbps;

delay = 100us;

ber = 1e-10;

}

You may add parameters and properties to channels viasubclassing, and may modify existing ones:

channel DatarateChannel2 extends ned.DatarateChannel

{

double distance @unit(m);

delay = this.distance / 200000km * 1s;

}


Parameters are primarily useful as input to the underlying C++class, but even if you reuse the underlying C++ class of built-inchannel types, they may be read and used by other parts of themodel. For example, adding a cost parameter may be observed bythe routing algorithm and used for routing decisions. The followingexample shows a cost parameter, and annotation using a property(@backbone).

channel Backbone extends ned.DatarateChannel

{

@backbone;

double cost = default(1);

}

The NED Language: Parameters

Parameters are variables that belong to a module. Parameters canbe used in building the topology (number of nodes, etc), and tosupply input to C++ code that implements simple modules andchannels.

Parameters can be of type double, int, bool, string and xml; theycan also be declared volatile. For the numeric types, a unit ofmeasurement can be specified (@unit property), to increase safety.

Parameters may get their values from NED code, from theconfiguration (omnetpp.ini), or even, interactively from the user.NED lets you assign parameters at several places: in subclasses viainheritance; in submodule and connection definitions where theNED type is instantiated; and in networks and compound modulesthat directly or indirectly contain the corresponding submodule orconnection. A default value can also be given (default()).

The next example shows a simple module with five parameters.


simple App

{

parameters:

string protocol;

// protocol to use: "UDP" / "IP" / "ICMP" / ...

int destAddress;

// destination address

volatile double sendInterval @unit(s)

= default(exponential(1s));

// time between generating packets

volatile int packetLength @unit(byte) = default(100B);

// length of one packet

volatile int timeToLive = default(32);

// maximum number of network hops to survive

gates:

input in;

output out;

}


We specialize the above App module type via inheritance:

simple PingApp extends App

{

parameters:

protocol = "ICMP/ECHO";

sendInterval = default(1s);

packetLength = default(64byte);

}

The module definition sets the protocol parameter to a fixedvalue, this parameter is now locked, its value cannot be modifiedvia further subclassing or other ways. The default values of the twoother parameters are changed.


Now, let us see the definition of a Host compound module thatuses PingApp as submodule:

module Host

{

submodules:

ping: PingApp {

packetLength = 128B;

// always ping with 128-byte packets

}

...

}

This definition sets the packetLength parameter to a fixed value;this setting cannot be changed.


It is not only possible to set a parameter from the compoundmodule that contains the submodule, but also from modules higherup in the module tree:

network MyNetwork

{

submodules:

host[100]: Host {

ping.timeToLive = default(3);

ping.destAddress = default(0);

}

...

}


Parameter assignment can also be placed into the parametersblock of the parent module, which provides additional flexibility:

network MyNetwork

{

parameters:

host[*].ping.timeToLive = default(3);

host[0..49].ping.destAddress = default(50);

host[50..].ping.destAddress = default(0);

submodules:

host[100]: Host;

...

}

Note the use of asterisk to match any index, and “..” to matchindex ranges.


If you had a number of individual hosts instead of a submodulevector:

network MyNetwork

{

parameters:

host*.ping.timeToLive = default(3);

host{0..49}.ping.destAddress = default(50);

host{50..}.ping.destAddress = default(0);

submodules:

host0: Host;

host1: Host;

...

host99: Host;

}

An asterisk matches any substring not containing a dot, and a“..” within a pair of curly braces matches a natural numberembedded in a string.


In most assigments we have seen above, the left hand side of theequal sign contained a dot and often a wildcard as well (asterisk ornumeric range); we call these assignments pattern assignments.

The double asterisk is one more wildcard that can be used inpattern assignments: it matches any sequence of charactersincluding dots, so it can match multiple path elements.

network MyNetwork

{

parameters:

**.timeToLive = default(3);

**.destAddress = default(0);

submodules:

host0: Host;

host1: Host;

...

}


A parameter can be assigned in the configuration using a similarsyntax as NED pattern assignments:

MyNetwork.host[*].ping.sendInterval = 500ms

# for the host[100] example

MyNetwork.host*.ping.sendInterval = 500ms

# for the host0,host1,... example

**.sendInterval = 500ms

One can also write expressions, including stochastic expressions, inNED files and in ini files as well:

**.sendInterval = 1s + normal(0s, 0.001s)

NED files (together with C++ code) are considered to be part ofthe model, and to be more or less constant. Thus, parameters thatare expected to change (or make sense to be changed) duringexperimentation should be put into ini files. A non-default valueassigned from NED cannot be overwritten later in NED or ini files.


Expressions

Parameter values may be given with expressions. NED languageexpressions have a C-like syntax, with some variations on operatornames: binary and logical XOR are # and ##, while ^ has beenreassigned to power-of instead. The + operator does stringconcatenation as well as numeric addition. Expressions can usevarious numeric, string, stochastic and other functions (fabs(),toUpper(), uniform(), erlang_k(), etc).

Expressions may refer to gate vector and module vector sizes(using the sizeof operator) and the index of the current modulein a submodule vector (index).

Expressions may refer to parameters of the current module, withthe this. prefix, and to parameters of already definedsubmodules, with the syntax submodule.parametername (orsubmodule[index].parametername).


volatile

The volatile modifier causes the parameter’s value expression to beevaluated every time the parameter is read. This has significance ifthe expression is not constant (for example numbers drawn from arandom number generator). In contrast, non-volatile parametersare evaluated only once. An example:

simple Queue

{

parameters:

volatile double serviceTime;

}

The queue module’s C++ implementation is expected to re-readthe serviceTime parameter whenever a value is needed, that is,for every job serviced.


Thus, if serviceTime is assigned an expression likeuniform(0.5s, 1.5s), every job will have a different, randomservice time.

Another configuration:

**.serviceTime = simTime()<1000s ? 1s : 2s

# queue that slows down after 1000s

Volatile parameters are typically used as a configurable source ofrandom numbers for modules. (A non-volatile parameter can beassigned a random value but the simulation would use a constantvalue chosen randomly at the beginning of the simulation.)


Units

One can declare a parameter to have an associated unit ofmeasurement, by adding the @unit property. The OMNeT++runtime does a full and rigorous unit check on parameters toensure unit safety. Constants should always include the unit.

simple App

{

parameters:

volatile double sendInterval @unit(s) =

default(exponential(350ms));

volatile int packetLength @unit(byte) = default(4KiB);

...

}

Values assigned to parameters must have the same or compatibleunit, i.e. @unit(s) accepts milliseconds, minutes, etc, and@unit(byte) accepts kilobytes, megabytes, etc, see Appendix.


XML Parameters

Sometimes modules need complex data structures as input, whichis something that cannot be done well with module parameters.One solution is to use XML syntax.

OMNeT++ contains built-in support for XML files. Using an XMLparser, OMNeT++ reads and validates the XML file, caches thefile, allows selection of parts of the document using anXPath-subset notation, and presents the contents in a DOM-likeobject tree.

This capability can be accessed via the NED parameter type xml,and the xmldoc() function.

The NED Language: Gates

Gates are the connection points of modules. OMNeT++ has threetypes of gates: input, output and inout.

One can create single gates and gate vectors. The size of a gatevector can be given in the declaration, but it is also possible toleave it open. The ++ operator that automatically expands the gatevector. The gate size can be queried from various NED expressionswith the sizeof() operator. See the example modules in theQuickstart section above.

NED normally requires that all gates be connected. To relax thisrequirement, you can annotate selected gates with the @loose

property, which turns off the connectivity check for that gate. Also,input gates that solely exist so that the module can receivemessages via sendDirect() should be annotated with @directIn.It is also possible to turn off the connectivity check for all gateswithin a compound module (allowunconnected keyword).

The NED Language: Gates

simple Classifier {

parameters:

int numCategories;

gates:

input in;

output out[numCategories];

}

simple Sink {

gates:

input in[];

}

simple TreeNode {

gates:

inout parent;

inout children[];

}

simple BinaryTreeNode extends TreeNode {

gates:

children[2]; }

The NED Language: Submodules

Modules that a compound module is composed of are called itssubmodules. A submodule has a name, and it is an instance of acompound or simple module type. A submodule is usually givenstatically, but it is also possible to specify the type with a stringexpression (parametric submodule types).

NED supports submodule arrays (vectors) and conditionalsubmodules as well. Submodule vector size must always bespecified and cannot be left open as with gates.

It is possible to add new submodules to an existing compoundmodule via subclassing.

A submodule may also have a curly brace block as body, where onecan assign parameters, set the size of gate vectors, and add, ormodify, properties like the display string. It is not possible to addnew parameters and gates.

The NED Language: Submodules

module Node

{

gates:

inout port[];

submodules:

routing: Routing {

parameters: // this keyword is optional

routingTable = "routingtable.txt"; // assign par.

gates:

in[sizeof(port)]; // set gate vector size

out[sizeof(port)];

}

queue[sizeof(port)]: Queue {

@display("t=queue id $id"); // modify display string

id = 1000+index;

// use submodule index to generate different IDs

}

connections:

... }

The NED Language: Connections

Connections are defined in the connections section of compoundmodules. One can connect two submodule gates, or a submodulegate and the inside of a gate of the parent module. Connectionscannot span across hierarchy levels.

Gates are specified as modulespec.gatespec to connect asubmodule, or as gatespec to connect the compound module.modulespec is either a name for scalar submodules, or a name plusan index in square brackets for submodule vectors. For scalar gates,gatespec is the name; for gate vectors it is either the name plus anindex in square brackets, or gatename++.

The gatename++ notation causes the first unconnected gate indexto be used. If the size of the submodule gate vector is open, the ++

operator expands the gate vector by one (the model structure isbuilt in top-down order).


Channel specifications are similar to submodules. The followingconnections use channel types definde above. The code shows thesyntax for assigning parameters and specifying a display string.

a.g++ <--> Ethernet100 <--> b.g++;

a.g++ <--> Backbone {cost=100; length=52km; ber=1e-8;}

<--> b.g++;

a.g++ <--> Backbone {@display("ls=green,2");} <--> b.g++;

When using built-in channel types, the type name can be omitted;it will be inferred from the parameters you assign.

a.g++ <--> {delay=10ms;} <--> b.g++;

a.g++ <--> {delay=10ms; ber=1e-8;} <--> b.g++;

a.g++ <--> {@display("ls=red");} <--> b.g++;

The default name given to channel objects is channel. It ispossible to specify the name explicitly, and also to override thedefault name per channel type.


Connection parameters, similarly to submodule parameters, canalso be assigned using pattern assignments, albeit the patterns area little more complicated and less convenient to use. (Usingbidirectional connections is a bit trickier.)

module Queueing

{

parameters:

source.out.channel.delay = 10ms;

queue.out.channel.delay = 20ms;

submodules:

source: Source;

queue: Queue;

sink: Sink;

connections:

source.out --> ned.DelayChannel --> queue.in;

queue.out --> ned.DelayChannel --> sink.in;

}

Simulation Concepts: C++ Classes

Systems that can be viewed as discrete event systems can bemodeled using discrete event simulation.

The time when events occur is often called event timestamp; withOMNeT++ we use the term arrival time (the word timestamp isreserved for an attribute in the event class). Time within the modelis often called simulation time, model time or virtual time asopposed to real time or CPU time which refer to how long thesimulation program has been running and how much CPU time ithas consumed.

Discrete event simulation maintains the set of future events in adata structure often called FES (Future Event Set) or FEL (FutureEvent List). Such simulators usually work according to thefollowing pseudocode.


initialize -- this includes building the model and

inserting initial events to FES

while (FES not empty and simulation not yet complete)

{

retrieve first event from FES

t:= timestamp of this event

process event

(processing may insert new events in FES

or delete existing ones)

}

finish simulation (write statistical results, etc)

OMNeT++ uses messages to represent events. Each event isrepresented by an instance of the cMessage class or one itssubclasses. Simple modules encapsulate C++ code that generatesevents and reacts to events, in other words, implements thebehaviour of the model.


Messages are sent from one module to another. The place wherethe event will occur is the message’s destination module, and themodel time when the event occurs is the arrival time of themessage.

Events like timeout expired are implemented by the modulesending a message to itself.

Events are consumed from the FES in arrival time order. If twoarrival times are equal, the one with the smaller scheduling priorityvalue is executed first.

The current simulation time can be obtained with the simTime()

function. Simulation time in OMNeT++ is represented by theC++ type simtime_t, by default a int64-based typedef to theSimTime class. The dbl() method of SimTime converts todouble. Several functions and methods have overloaded variantsthat directly accept SimTime.


OMNeT++ simulation models are composed of modules andconnections. Modules may be simple modules or compoundmodules; simple modules are the active components in a model,and their behaviour is defined by the user as C++ code.Connections may have associated channel objects. Channel objectsencapsulate channel behavior. Channels are also programmable inC++ by the user. Modules and channels are called components.

Components are represented with the C++ class cComponent.The abstract module class cModule and the abstract channel classcChannel both subclass from cComponent. cModule has twosubclasses: cSimpleModule and cCompoundModule. The userdefines simple module types by subclassing cSimpleModule. ThecChannel’s subclasses include the three built-in channel types:cIdealChannel, cDelayChannel and cDatarateChannel. The user cancreate new types by subclassing cChannel or other channel classes.


Signal-Based Statistics Recording

Simulation signals can be used for:

I exposing statistical properties of the model, without specifyingwhether and how to record them,

I receiving notifications about simulation model changes atruntime, and acting upon them,

I implementing a publish-subscribe style communication amongmodules,

I emitting information for other purposes.

Signals are emitted by components (modules and channels).Signals propagate on the module hierarchy up to the root. At anylevel, one can register listeners (callback objects); these listenerswill be notified (called back) whenever a signal value is emitted.The result of upwards propagation is that listeners registered at acompound module can receive signals from all components in thatsubmodule tree. A listener registered at the system module canreceive signals from the whole simulation.


Signals are identified by signal names (i.e. strings), but forefficiency reasons at runtime we use dynamically assigned numericidentifiers: signal IDs, typedef’d as simsignal_t. The mapping ofsignal names to signal IDs is global. (The registerSignal()

method takes a signal name as parameter, and returns thecorresponding simsignal_t value; the getSignalName() methoddoes the reverse.)

When a signal is emitted, it can carry a value with it. This isrealized via overloaded emit() methods in components, andoverloaded receiveSignal() methods in listeners. An example:

emit(lengthSignalId, queue.length());

The value can be of type long, double, simtime_t,const char *, or cObject *. Other types can be cast into one ofthese types, or wrapped into an object subclassed from cObject.


One use of signals is to expose variables for result collectionwithout telling where, how, and whether to record them. Modulesonly publish the variables, and the actual result recording takesplace in listeners. Listeners may be added by the simulationframework, or by dedicated modules. OMNeT++ approach goals:

I A controllable level of detail, you record all values as a timeseries, or only the mean, time average, minimum/maximum,standard deviation, etc, or the distribution as a histogram;

I Processing the results before recording them, for example torecord the percentage of time the value is nonzero or over athreshold, record the sum of the values, etc;

I Aggregate statistics, e.g. the total number of packet drops orthe average end-to-end delay for the whole network;

I Combined statistics, for example a drop percentage;

I Ignoring results generated during transient periods, etc.


Declaring Statistics

In order to record simulation results based on signals, one mustadd @statistic properties to the simple module’s (or channel’s)NED definition.

A @statistic property defines which signal(s) are used as input,what processing steps are to be applied to them (e.g. smoothing,filtering, summing, differential quotient), and what properties areto be recorded (minimum, maximum, average, etc.) and in whichform (vector, scalar, histogram). One can also specify a descriptivename for the statistic, and also a measurement unit.

Record items can be marked optional, which lets you denote adefault and a more comprehensive all result set to be recorded; thelist of record items can be further tweaked from the configuration.

Signal-Based Statistics RecordingA queue length statistic, represented with an indexed property:

simple Queue

{

parameters:

@statistic[queueLength](record=max,timeavg,vector?);

gates:

input in;

output out;

}

The above @statistic declaration assumes that module’s C++code emits the queue’s updated length as signal queueLengthwhenever elements are inserted into the queue or are removed fromit. The maximum and the time average values will be recorded asscalars. One can instruct the simulation to record all results; thiswill turn on optional record items, those marked with a questionmark, and then the queue lengths will be recorded into an outputvector. The configuration lets you fine-tune the list of result items.


In the above example, the signal to be recorded was taken fromthe statistic name. When that is not suitable, the source propertykey lets you specify a different signal as input for the statistic.

simple Queue

{

parameters:

@signal[qlen](type=int); // optional

@statistic[queueLength](source=qlen;

record=max,timeavg,vector?);

...

}

This simple module type assumes that the module’s C++ codeemits a qlen signal, and declares a queueLength statistic basedon that. (Declaring signals is currently optional and in fact@signal properties are ignored by the system.)


See the User Manual for the list of Property Keys, and the list ofAvailable Filters and Recorders.

Naming of Recorded Results: 〈statisticName〉 : 〈recordingMode〉

@statistic[dropRate](source="count(drop)/count(pk)";

record=last,vector?);

@statistic[droppedBytes](source="packetBytes(pkdrop)";

record=sum,"vector(sum)?");

(The statistics sources combine multiple signals; there arequotation marks because the NED language parser does not allowparentheses in property values.)

These statistics will produce the following scalars:dropRate:last, droppedBytes:sumand the following vectors:dropRate:vector, droppedBytes:vector(sum)

Configuring Signal-Based Statistics Recording

Recording can be tuned with the result-recording-modes

configuration option. The statistic is identified by the full path(hierarchical name) of the module or connection channel object inquestion, plus the name of the statistic.

This configuration option accepts one or more items as value. Anitem may be a result recording mode, and two words with a specialmeaning, default (the set of non-optional items from the statisticrecord list) and all (all items from the list).

For example, if the following statistic is declared:

@statistic[foo](record=count,mean,max?,vector?);

We can write the following ini file lines (results are in comments).

Configuring Signal-Based Statistics Recording

**.result-recording-modes = default # --> count, mean

**.result-recording-modes = all # --> count, mean, max

**.result-recording-modes = - # --> none

**.result-recording-modes = mean

# --> only mean (disables ’default’)

**.result-recording-modes = default,-vector,+histogram

# --> count,mean,histogram

**.result-recording-modes = -vector,+histogram

# --> same as above

**.result-recording-modes = all,-vector,+histogram

# --> count,mean,max,histogram

Here is another example with a more specific option key. Thefollowing ini line applies to queueLength statistics of fifo[]submodule vectors anywhere in the network.

**.fifo[*].queueLength.result-recording-modes = +vector

# default modes plus vector

Documents

OMNeT++ - gipuzkoa · Introduction OMNeT++ is an object-oriented modular discrete event system simulation framework. It has a generic architecture, so it can be used in various problem