Difference between revisions of "GSOC2012HLA"

From Nsnam
Jump to: navigation, search
m
m (References)
 
(6 intermediate revisions by the same user not shown)
Line 27: Line 27:
 
'''Ns-3 HLA Model'''
 
'''Ns-3 HLA Model'''
  
The HLA model of ns-3 can be divided into two blocks, Java Block (please see a conceptual diagram [http://www.google-melange.com/gsoc/proposal/review/google/gsoc2012/muditrajgupta/45002 here]) and C++ block (please see a conceptual diagram [http://www.google-melange.com/gsoc/proposal/review/google/gsoc2012/muditrajgupta/45002 here]).  
+
The HLA model of ns-3 can be divided into two blocks, ''' Java Block'''  (please see a conceptual diagram [http://ns-3-review.googlecode.com/svn/wiki/Selection_001.bmp here]) and ''' C++ bloc'''k (please see a conceptual diagram [http://ns-3-review.googlecode.com/svn/wiki/Selection_002.bmp here]).  
  
 
The User Creates a script to share an object with other simulator using RTI and HLA interfaces. The first phase is to use the Rti Simulator implementation as it is responsible for synchronisation of RTI Clock with ns-3 clock. Next, use the HLA API provided in Helper to communicate with Rti and create a shared object.
 
The User Creates a script to share an object with other simulator using RTI and HLA interfaces. The first phase is to use the Rti Simulator implementation as it is responsible for synchronisation of RTI Clock with ns-3 clock. Next, use the HLA API provided in Helper to communicate with Rti and create a shared object.
Line 39: Line 39:
 
==Java Block==
 
==Java Block==
  
As it is quite clear from the diagram. The Java block communicates with the RTI. The [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/ns3Federate.java Ns3Federate] is the class which uses the portico Java API to communicate with the portico RTI. At present the sequence of events followed by Ns-3 Federate are are follows:  
+
As it is quite clear from the [http://ns-3-review.googlecode.com/svn/wiki/Selection_001.bmp diagram]. The Java block communicates with the RTI. The [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/ns3Federate.java Ns3Federate] is the '''class which uses the portico Java API to communicate with the portico RTI'''. At present the '''sequence of events''' followed by Ns-3 Federate are are follows:  
  
 
* Create Federation
 
* Create Federation
Line 52: Line 52:
 
* Destroy Federation
 
* Destroy Federation
  
The other class [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/ns3FedAmb.java Ns3FedAmb] handles Callbacks from RTI whenever an event occurs that is initiated by the other federate or RTI has to convey a request grant. The Call backs supported at present are:
+
The other class [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/ns3FedAmb.java Ns3FedAmb] '''handles Callbacks from RTI''' whenever an event occurs that is initiated by the other federate or RTI has to convey a request grant. The Call backs supported at present are:
  
 
* Synchronisation (Synchronised, Registered, Failed, Ready)
 
* Synchronisation (Synchronised, Registered, Failed, Ready)
Line 58: Line 58:
 
* Object (Object Discovered, Object Attributes Changed, Object Deleted)
 
* Object (Object Discovered, Object Attributes Changed, Object Deleted)
 
   
 
   
An other helper class is [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/j.java j]. This class is a Java Side link between the Java Block and C++ Block. It has various utility functions to set up a socket connection and receive and send messages. It also has various Getter methods to extract the value of the incoming messages into variables. It basically has functions for:
+
An other helper class is [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/j.java j]. This '''class is a Java Side link between the Java Block and C++ Block'''. It has various utility functions to set up a socket connection and receive and send messages. It also has various Getter methods to extract the value of the incoming messages into variables. It basically has functions for:
  
 
* Socket Communication (Establish Connection, Notify Changes to ns-3, Start ns-3, Send Time Advance to C++ block, read Time Advance, Initial Values)
 
* Socket Communication (Establish Connection, Notify Changes to ns-3, Start ns-3, Send Time Advance to C++ block, read Time Advance, Initial Values)
Line 65: Line 65:
 
==C++ Block==  
 
==C++ Block==  
  
It Consists of basically two parts: The Synchroniser and The Helper. It also has a class which act as a C++ link to the connection between Java and C++ block. The code is well documented in doxygen format.
+
As the [http://ns-3-review.googlecode.com/svn/wiki/Selection_001.bmp diagram] shows, it consists of basically two parts: The Synchroniser and The Helper. It also has a class which act as a C++ link to the connection between Java and C++ block. The code is well documented in doxygen format.
  
The Helper [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/helper/hla-helper.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/helper/hla-helper.h .h] contain functions to set various variables that are used to initialise the Federation and shared objects and attributes,  It also has functions to access the variables and their values. So basically,
+
'''The Helper''' [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/helper/hla-helper.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/helper/hla-helper.h .h] contain functions to set various variables that are '''used to initialise the federation, shared objects and attributes''',  It also has functions to access the variables and their values. So basically,
  
 
* Setters (Set values like federation name, Federate Name, Fom File, Object Name, Attribute Names etc.)
 
* Setters (Set values like federation name, Federate Name, Fom File, Object Name, Attribute Names etc.)
Line 74: Line 74:
 
The values of Hla Helper are updated as and when they are changed by the other federates.  
 
The values of Hla Helper are updated as and when they are changed by the other federates.  
  
The Synchroniser consists of two classes RTI Simulator Implementation [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-simulator-impl.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-simulator-impl.h .h] and RTI clock Synchroniser [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-clock-synchronizer.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-clock-synchronizer.h .h].
+
'''The Synchroniser''' consists of two classes RTI Simulator Implementation [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-simulator-impl.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-simulator-impl.h .h] and RTI clock Synchroniser [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-clock-synchronizer.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/rti-clock-synchronizer.h .h].
  
The Synchroniser is responsible for synchronising the event times with the RTI clock. The RTI Synchroniser is inspired by the wall-clock-synchronizer-impl, in it's case it fetches the RTI time from the RTI clock variable maintained in LinkToRti class. It is used by the functions in RTI Simulator Implementation. Whenever an event has to happen, this code block checks if the event time is more than the time in RTI. If yes, the event is processed and if no the a Time Advance Request is sent to the RTI. Other standard functions for simulator implementation are also present, quite similar to realtime-simulator-impl.
+
The Synchroniser is '''responsible for synchronising the event times with the RTI clock'''. The RTI Synchroniser is inspired by the wall-clock-synchronizer-impl, in it's case it fetches the RTI time from the RTI clock variable maintained in LinkToRti class. It is used by the functions in RTI Simulator Implementation. Whenever an event has to happen, this code block checks if the event time is more than the time in RTI. If yes, the event is processed and if no the a Time Advance Request is sent to the RTI. Other standard functions for simulator implementation are also present, quite similar to realtime-simulator-impl.
  
Link To Rti [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/link-to-rti.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/link-to-rti.h .h] is the class that implements sockets in C++ and communicates with the Java code.It has following functions for:
+
'''Link To Rti''' [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/link-to-rti.cc .cc] [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/model/link-to-rti.h .h] is the '''class that implements sockets in C++''' and communicates with the Java code.It has following functions for:
  
 
* Multi threading: It is implemented for simultaneous listening and sending of messages over the socket.  
 
* Multi threading: It is implemented for simultaneous listening and sending of messages over the socket.  
Line 86: Line 86:
 
== Helper Scripts ==
 
== Helper Scripts ==
  
Apart from regular ns-3 helper scripts, HLA module needs a helper script [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/hla.sh hla.sh]. This script is written to remind the end-user of the path variables to set. The script also provides a waf like build system to build java code. User does not require build tools like ant and maven for building java code and producing .class and .jar files. Once ns3 is build, this script can be used to automatically create .class and .jar files in $ns3/build/src/hla/model and running the java code. It has commands like:
+
Apart from regular ns-3 helper scripts, HLA module needs a helper script [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/hla.sh hla.sh]. This '''script is written to remind the end-user of the path variables''' to set. The script '''also provides a waf like build system to build java code'''. User does not require build tools like ant and maven for building java code and producing .class and .jar files. Once ns3 is build, this script can be used to automatically create .class and .jar files in $ns3/build/src/hla/model and running the java code. It has commands like:
  
 
* ./hla.sh --clean (Cleans .class, .jar files and RTI log files)
 
* ./hla.sh --clean (Cleans .class, .jar files and RTI log files)
Line 92: Line 92:
 
* ./hla.sh --run scratch/<filename> (.fed file has to be in scratch directory)
 
* ./hla.sh --run scratch/<filename> (.fed file has to be in scratch directory)
  
To know more about usage read below or this tutorial.
+
To know more about usage read below or this [https://www.nsnam.org/wiki/index.php/HLAExample tutorial].
  
 
== Testing ==
 
== Testing ==
Line 98: Line 98:
 
* System Integration Test
 
* System Integration Test
  
The hla model at present has a dummy federate. It has two classes [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/test/SystemIntegration/dummyFederate.java Federate] and [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/test/SystemIntegration/dummyFederateAmbassador.java FederateAbassador]. The ns-3 hla model can be checked without creating a federate in other simulator. This federates just creates a federation and modify a shared object PingPong 's attributes - Msg and MsgType. These attributes are toggles every second. The values are:
+
The hla model at present has a dummy federate. It has two classes [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/test/SystemIntegration/dummyFederate.java Federate] and [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/test/SystemIntegration/dummyFederateAmbassador.java FederateAbassador]. The '''ns-3 hla model can be checked without creating a federate in other simulator'''. This federates just creates a federation and modify a shared object PingPong 's attributes - Msg and MsgType. These attributes are toggles every second. The values are:
  
 
* MsgType : Ping, Pong
 
* MsgType : Ping, Pong
Line 107: Line 107:
 
== Examples ==
 
== Examples ==
  
All scripts that use HLA should also have a corresponding .fed file, which is nothing but a simple object description. This [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/examples/SimpleSharedObjectExample.fed .fed] file used for the examples and can be modified for more scripts. It contains the shared object "PingPong" and two attributes "Msg" and "MsgType".
+
All '''scripts that use HLA should also have a corresponding .fed file''', which is nothing but a simple object description. This [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/examples/SimpleSharedObjectExample.fed .fed] file used for the examples and can be modified for more scripts. It contains the shared object "PingPong" and two attributes "Msg" and "MsgType".
  
 
* Simple Shared Object Example
 
* Simple Shared Object Example
  
This [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/examples/simple-shared-object-example.cc example] demonstrates how to create a shared object using the HLA API and how to publish the object. The example creates a simple object PingPong with attributes Msg and MsgType and shares with other federates and sets simulator to RTI simulator Implementation. It demonstrates the concepts of Class Handles and Attribute Handles. A tutorial on the model can be found here.  
+
This [http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/file/528951a6288c/codeRev/src/hla/examples/simple-shared-object-example.cc example] demonstrates '''how to create a shared object using the HLA API and how to publish the object'''. The example creates a simple object PingPong with attributes Msg and MsgType and shares with other federates and '''sets simulator to RTI simulator Implementation'''. It demonstrates the concepts of Class Handles and Attribute Handles. A tutorial on the model can be found [https://www.nsnam.org/wiki/index.php/HLAExample here].  
  
 
* Shared Object With CallBack
 
* Shared Object With CallBack
  
In a real scenario you need to use HLA interfaces with some ns-3 model and use the attributes shared with other federates in your model. The example uses a simple mobility models and prints the object's attributes in the Callback function. One can see the attribute changes when the external federate modify it.
+
In a real scenario you '''need to use HLA interfaces with some ns-3 model''' and use the attributes shared with other federates in your model. The example uses a '''simple mobility model''' and prints the object's attributes in the Callback function. One can see the attribute changes when the external federate modify it.
  
= Usage =
+
= Packages =
  
 
Ns-3 scripts can use HLA API and RTI Simulator Implementation to communicate with other federates. HLA module uses the following external packages/software:
 
Ns-3 scripts can use HLA API and RTI Simulator Implementation to communicate with other federates. HLA module uses the following external packages/software:
Line 125: Line 125:
 
* Get and Install [http://msgpack.org/ MessagePack] for [https://github.com/msgpack/msgpack-c C++] and [https://github.com/msgpack/msgpack-java Java]
 
* Get and Install [http://msgpack.org/ MessagePack] for [https://github.com/msgpack/msgpack-c C++] and [https://github.com/msgpack/msgpack-java Java]
  
Please refer to package installation documents from respective websites (You just need portico.jar for portico).
+
Please refer to '''package installation documents''' from respective websites (You just need portico.jar for portico).
  
Once the packages are set up. You need to set two environment variables:
+
Once the packages are set up. You need to '''set two environment variables''':
  
 
* JAVA_PATH=/path/to/your/jdk/install
 
* JAVA_PATH=/path/to/your/jdk/install
 
* JAR_PATH=/path/to/portico.jar file
 
* JAR_PATH=/path/to/portico.jar file
  
Try and set both of these as your system wide variables, a small [https://help.ubuntu.com/community/EnvironmentVariables post] talks about this for Ubuntu.  
+
Try and set both of these as your system wide variables, a small [https://help.ubuntu.com/community/EnvironmentVariables post] talks about this for Ubuntu.
  
Once you are done create a new ns-3 script that uses HLA helper classes along with other models, say ns3-hla-script.cc. Write an object description file similar to one in the examples, Ns3HlaScript.fed. Copy both in $ns3/scratch/ folder. Open two terminal windows, lets call them JavaShell and CppShell.  
+
= Usage =
 +
 
 +
Once you are done '''create a new ns-3 script that uses HLA helper classes''' along with other models, say ns3-hla-script.cc. Write''' an object description file''' similar to one in the examples, Ns3HlaScript.fed. '''Copy both in $ns3/scratch/ folder'''. '''Open two terminal windows''', lets call them JavaShell and CppShell.  
  
For running your ns-3 script use the following command, in any shell (say CppShell):
+
For '''running your ns-3 script''' use the following command, in any shell (say CppShell):
  
 
<pre>
 
<pre>
Line 148: Line 150:
 
</pre>
 
</pre>
  
Start Java code in the other shell (JavaShell). There is hla.sh script in your $ns3 folder, it provides a waf like build to the java code.
+
'''Start Java code''' in the other shell (JavaShell). There is hla.sh script in your $ns3 folder, it provides a waf like build to the java code.
  
 
<pre>
 
<pre>
Line 158: Line 160:
 
</pre>
 
</pre>
  
+
If you are using HLA for the first time, you will have to '''build it first using the "--build"''' command. '''"--clean" will remove old files'''. If HLA (java) is build once you can just '''run your scripts using "--run"'''. The scripts mimics waf build system for the convenience of the user.
= Deliverables =
+
  
* 1.0 rtiScheduler ('''renamed link-to-rti''')
+
This will get your ns-3 federate started. Once you are done with this you can start your other federates or if other federates are running on the same federation, ns-3 federate will just join them automatically.  
**1.1 The class will be the sub class of the base class ns3::Scheduler and all virtual functions defined would be written like – Insert, PeakNext, IsEmpty, Remove, Remove. Activating a thread responsible to receive messages from the ns3FederateAmbassador and uses them appropriately. ('''chucked''')
+
**1.2 Setting up a message server and using appropriate sockets to get messages from ns3FederateAmbassador('''Done''')
+
**1.3 Handling/decoding messages received ('''Done''')
+
**1.4 Generating and Sending Time advance Request and taking proper action on the request being granted from the RTI. ('''Done''')
+
  
* 2.0 ns3FederateAmbassador ('''Ns3Federate''')
+
Again a small tutorial on using HLA in ns3 from writing code to running can be found [https://www.nsnam.org/wiki/index.php/HLAExample here].
**2.1 Define socket communication with link-to-rti ('''Done''')
+
**2.2 Define Semantics for other federates to send message to ns-3 ('''Done''')
+
**2.3 Define ambassador for ns3 according to poRTIco definition and adding various functions to interface with poRTIco to receive messages and send request and various other functions  ('''Done''')
+
**2.4 Integrate all the above classes and write a test code to run the ns3FederateAmbassador. ('''Done''')
+
  
* 3.0 HLA API
+
= Deliverables =
**3.1 Writing the Informer function and update HLA class ('''Done, link-to-rti has functions to make it similar to informer''')
+
**3.2 Writing HLA API for the designed system
+
  
* 4.0 Complex Network Simulation
+
The deliverables mentioned above in the "components" section
**4.1 Writing a demo model which is HLA compliant ('''Done, created dummy federate''')
+
**4.2 Writing a ns3 model which is HLA compliant and using both simultaneously
+
  
* 0.0  If time permits/future plans (post GSoC)
+
* HLA API
**0.1 Adding the possibility of object publication and sharing in the existing code and integrating it. ('''Done, publishing objects''')
+
* Synchroniser
**0.2 Addition of a functionality in which ns-3 will also be used as a source.
+
* Ns3Federate and Ns3Federate Ambassador
**0.3 Making more refined and complex model in which ns-3 will be a federate.
+
* C++ and Java Links to the C++ Java connecting pipe
 +
* Scripts, Tests and Examples
  
 
= Weekly Progress =
 
= Weekly Progress =
Line 255: Line 245:
 
  * Completing documentation
 
  * Completing documentation
 
  * Preparing code for review
 
  * Preparing code for review
 +
 +
= Limitations =
 +
 +
* Ns-3 as a source - At present ns-3 acts as a sink while in a federation. This means that ns-3 can only receive updates on the objects but cannot modify the attributes of the object. The source property was not added because of two reasons, firstly, because we could not identify a scenario in which such a feature would be useful and secondly, due to the limited time span of GSoC.  Although, adding a source property will be similar to sink property and can be implemented by adding a "RTI register object instance" and "Update Values" functions.
 +
 +
* In a federations federates communicate using objects and interactions at present the code supports publishing objects and interactions can be added, if required by writing functions for interactions that mimic object functions.     
  
 
= References =
 
= References =

Latest revision as of 22:21, 23 August 2012

HLA interfaces for ns-3: Introduction

  • Student: Mudit Raj Gupta
  • Mentors: Tommaso Pecorella
  • Code: http://code.nsnam.org/muditraajgupta/ns-3-dev-hla/codeRev/
  • Mid-Term Report:https://www.nsnam.org/wiki/index.php/GSOC2012HLAMidTerm
  • Abstract: The project deals with developing interfaces for High Level Architecture (HLA) for ns-3 project and thus enabling it to participate in a distributed simulation (Federation) involving various federates over Run Time infrastructure (RTI). The project involves three phases. Firstly, creating a Federate and Federate Ambassador for ns-3 to communicate with the RTI. Secondly, creating a synchroniser and simulator implementation that uses time from the RTI clock. Finally, creating a helper classes and modules to simplify the process of sharing and using objects in a distributed simulation. Detail proposal and initial plan can be found here here.
  • About me: I'm a fourth year student presently working for my M.Sc (H) in Chemistry and B.E. (H) in Electronics and Instrumentation Engineering at Birla Institute of Technology and Science - Pilani. I am interested in modelling and simulation of complex systems, learning in multi-agent systems and evolutionary algorithms.

Design

HLA

HLA, which is an IEEE standard, facilitates interoperability among simulations and promotes reuse of simulation models. Using HLA, a large-scale distributed simulation can be constructed by linking together a number of distributed simulation components (or federates) into an aggregate simulation (federation). [2].

RTI

Run-time infrastructure (RTI) is a middleware that is required when implementing the High Level Architecture. RTI is the fundamental component of HLA. It provides a set of software services that are necessary to support federates to coordinate their operations and data exchange during a runtime execution. In other sense, it is the implementation of the HLA interface specification but is not itself part of specification

Federates can communicate to RTI through RTI ambassador. Request of a service from/to federate to/from any other federate is done through interactions. There are two basic ways to communicate:

  • Interchange messages between federates
  • Publication of objects that are shared between federates

poRTIco is an open-source Java implementation of the above mentioned standard and it offers libraries to implement a federate ambassador. It is an interface between the RTI and the simulator. Federates can communicate to RTI through RTI ambassador.

Ns-3 HLA Model

The HLA model of ns-3 can be divided into two blocks, Java Block (please see a conceptual diagram here) and C++ block (please see a conceptual diagram here).

The User Creates a script to share an object with other simulator using RTI and HLA interfaces. The first phase is to use the Rti Simulator implementation as it is responsible for synchronisation of RTI Clock with ns-3 clock. Next, use the HLA API provided in Helper to communicate with Rti and create a shared object.

This is how it looks on the surface. The HlaHelper talks with LinkToRti, to send the details of the object and other information through a socket and proper serialisation framework (MsgPack) to Java Block. The Synchroniser part also communicates with LinkToRti in order to receive messages from RTI.

The messages from C++ blocks travels to JAVA through sockets and are serialised using Message Pack, a standard tool for serialisation, de-serialisation. These are now handled by class j. This is in turn parsed and used by ns3 Federate to initialise the federate and j also is used by ns3FedAmb when it receives a call back from RTI. The two classes handles communication with RTI

Components

Java Block

As it is quite clear from the diagram. The Java block communicates with the RTI. The Ns3Federate is the class which uses the portico Java API to communicate with the portico RTI. At present the sequence of events followed by Ns-3 Federate are are follows:

  • Create Federation
  • Join Federation
  • Synchronise with RTI
  • Enable Time Policies
  • Start Signal for C++ Block
  • Publish and Subscribe to Objects
  • Wait for ns-3 C++ Block Time Advance Request
  • Send Time Advance Requests To RTI
  • Resign From Federation
  • Destroy Federation

The other class Ns3FedAmb handles Callbacks from RTI whenever an event occurs that is initiated by the other federate or RTI has to convey a request grant. The Call backs supported at present are:

  • Synchronisation (Synchronised, Registered, Failed, Ready)
  • Time (Time Advance Request Granted, Time Policies Enabled)
  • Object (Object Discovered, Object Attributes Changed, Object Deleted)

An other helper class is j. This class is a Java Side link between the Java Block and C++ Block. It has various utility functions to set up a socket connection and receive and send messages. It also has various Getter methods to extract the value of the incoming messages into variables. It basically has functions for:

  • Socket Communication (Establish Connection, Notify Changes to ns-3, Start ns-3, Send Time Advance to C++ block, read Time Advance, Initial Values)
  • Getters (Extract Values like Federation Name, Federate Name, Fom File, Object Name, Attribute Names etc.)

C++ Block

As the diagram shows, it consists of basically two parts: The Synchroniser and The Helper. It also has a class which act as a C++ link to the connection between Java and C++ block. The code is well documented in doxygen format.

The Helper .cc .h contain functions to set various variables that are used to initialise the federation, shared objects and attributes, It also has functions to access the variables and their values. So basically,

  • Setters (Set values like federation name, Federate Name, Fom File, Object Name, Attribute Names etc.)
  • Getters (Retrieve current values of attributes, their parents, modified time etc.)

The values of Hla Helper are updated as and when they are changed by the other federates.

The Synchroniser consists of two classes RTI Simulator Implementation .cc .h and RTI clock Synchroniser .cc .h.

The Synchroniser is responsible for synchronising the event times with the RTI clock. The RTI Synchroniser is inspired by the wall-clock-synchronizer-impl, in it's case it fetches the RTI time from the RTI clock variable maintained in LinkToRti class. It is used by the functions in RTI Simulator Implementation. Whenever an event has to happen, this code block checks if the event time is more than the time in RTI. If yes, the event is processed and if no the a Time Advance Request is sent to the RTI. Other standard functions for simulator implementation are also present, quite similar to realtime-simulator-impl.

Link To Rti .cc .h is the class that implements sockets in C++ and communicates with the Java code.It has following functions for:

  • Multi threading: It is implemented for simultaneous listening and sending of messages over the socket.
  • Packing and Sending: It uses Message Pack for serialisation of the attributes of the object, implements various functions for sending data.
  • Callbacks: The class handle callbacks from RTI (Time Advance, Update, Start Signal)

Helper Scripts

Apart from regular ns-3 helper scripts, HLA module needs a helper script hla.sh. This script is written to remind the end-user of the path variables to set. The script also provides a waf like build system to build java code. User does not require build tools like ant and maven for building java code and producing .class and .jar files. Once ns3 is build, this script can be used to automatically create .class and .jar files in $ns3/build/src/hla/model and running the java code. It has commands like:

  • ./hla.sh --clean (Cleans .class, .jar files and RTI log files)
  • ./hla.sh --build (Builds HLA interfaces, Java Code)
  • ./hla.sh --run scratch/<filename> (.fed file has to be in scratch directory)

To know more about usage read below or this tutorial.

Testing

  • System Integration Test

The hla model at present has a dummy federate. It has two classes Federate and FederateAbassador. The ns-3 hla model can be checked without creating a federate in other simulator. This federates just creates a federation and modify a shared object PingPong 's attributes - Msg and MsgType. These attributes are toggles every second. The values are:

  • MsgType : Ping, Pong
  • Msg : "Client: Hello!!!", "Server: Hello!!!"

It can be executed using this helper script

Examples

All scripts that use HLA should also have a corresponding .fed file, which is nothing but a simple object description. This .fed file used for the examples and can be modified for more scripts. It contains the shared object "PingPong" and two attributes "Msg" and "MsgType".

  • Simple Shared Object Example

This example demonstrates how to create a shared object using the HLA API and how to publish the object. The example creates a simple object PingPong with attributes Msg and MsgType and shares with other federates and sets simulator to RTI simulator Implementation. It demonstrates the concepts of Class Handles and Attribute Handles. A tutorial on the model can be found here.

  • Shared Object With CallBack

In a real scenario you need to use HLA interfaces with some ns-3 model and use the attributes shared with other federates in your model. The example uses a simple mobility model and prints the object's attributes in the Callback function. One can see the attribute changes when the external federate modify it.

Packages

Ns-3 scripts can use HLA API and RTI Simulator Implementation to communicate with other federates. HLA module uses the following external packages/software:

Please refer to package installation documents from respective websites (You just need portico.jar for portico).

Once the packages are set up. You need to set two environment variables:

  • JAVA_PATH=/path/to/your/jdk/install
  • JAR_PATH=/path/to/portico.jar file

Try and set both of these as your system wide variables, a small post talks about this for Ubuntu.

Usage

Once you are done create a new ns-3 script that uses HLA helper classes along with other models, say ns3-hla-script.cc. Write an object description file similar to one in the examples, Ns3HlaScript.fed. Copy both in $ns3/scratch/ folder. Open two terminal windows, lets call them JavaShell and CppShell.

For running your ns-3 script use the following command, in any shell (say CppShell):

CppShell$ ./waf --run scratch/ns3-hla-script

Now, once you receive the following message:

CppShell$ Connecting to RTI ...

Start Java code in the other shell (JavaShell). There is hla.sh script in your $ns3 folder, it provides a waf like build to the java code.

JavaShell$ ./hla.sh --clean
JavaShell$ Removing HLA Bindings and Old Log files
JavaShell$ ./hla.sh --build
JavaShell$ Building HLA interfaces
JavaShell$ ./hla.sh --run scratch/Ns3HlaScript

If you are using HLA for the first time, you will have to build it first using the "--build" command. "--clean" will remove old files. If HLA (java) is build once you can just run your scripts using "--run". The scripts mimics waf build system for the convenience of the user.

This will get your ns-3 federate started. Once you are done with this you can start your other federates or if other federates are running on the same federation, ns-3 federate will just join them automatically.

Again a small tutorial on using HLA in ns3 from writing code to running can be found here.

Deliverables

The deliverables mentioned above in the "components" section

  • HLA API
  • Synchroniser
  • Ns3Federate and Ns3Federate Ambassador
  • C++ and Java Links to the C++ Java connecting pipe
  • Scripts, Tests and Examples

Weekly Progress

  • Week 1 : May.21 -- May.27
* Read Code related to Scheduler and various implementations like Map Scheduler and List Scheduler
* Started Coding on RTI Scheduler, implemented basic functions (similar to Map Scheduler)
* Read about MessagePack Message Format.
  • Week 2 : May.28 -- Jun.03
* Changed the default scheduler from map to list and finally rti by small changes in simulator.cc
* Modified map-scheduler and wrote a basic rti-scheduler.cc and rti-scheduler.h implementing scheduler.cc it is basic skeleton for implementing thread for handling RTI request. Tried making thread in the class, some problems.
* Tested. Discussed progress with the mentor and figured out a flaw in design.
* no scheduler required, last 10 days work not so useful. 
* Finalised a new design started working fresh. 
    
  • Week 3 : Jun.4 -- Jun.10
* Installed portico and ran demo programs in JAVA
* Tested with multiple federates, wrote a simple dummy federate. 

  • Week 4 : Jun.11 -- Jun.17
* Completed work on writing ns3Federate and ns3FederateAmbassador in JAVA using portico
* Added functionality to dummy by sharing object between the two federates and changing attributes
* Wrote a test for checking socket implementation 

  • Week 5 : Jun.18 -- Jun.24
* Integrating the server code to one of the NS3 examples.
* Tested and debugged of the entire code. 

  • Week 6 : Jun.25 -- Jul.01
* Completed work on writing a C++ code for reading socket values
* Completed work on integrating the above code with link-to-rti and decoding messages
* Completed deliverable 1.2 and 1.3
  • Week 7 : Jul.02 -- Jul.08
* Migrated code repo from code.google.com to code.nsnam.org
* Time advance request handled and wrote various functions to decode the RTI messages
* Created various functions to start simulation, stop simulation and RTI_CLOCK

  • Week 8 : Jul.09 -- Jul.15
* Finding and designing  the best way to synchronise ns-3 with RTI 
* Read about JNI basics

  • Week 9 : Jul.16 -- Jul.22
* Modified realtime-simulator-impl to schedule events according to RTI time and send time advance requests.
* Modified wall-clock-syncronizer to fetch RTI time.
* Tested the new implementation and synchronisation. 
* Designed the basic API
  • Week 10 : Jul.23 -- Jul.29
* Started working on the HLA API, some issues to be discussed with the mentor.
* Started working on hla-interface, it creates an object and add attributes to the attributes vector which is published by and modified by other federates
* Created an example (not completely working), just to have an idea ho create various components of the API
* Read about callbacks in ns-3 and Mobility. 

  • Week 11 : Jul.30 -- Aug.6
* Read documentation about Mobility model
* Tried an alternate RTI - CERTI, downloaded, build and tried a few example
* Tried using the C++ API of portico
* Read through and tried a few xmlparsers and MessagePack
* Further modified the design of the API
  • Week 12 : Aug.7 -- Aug.12
* Finally went with portico and JAVA API
* Read and implemented msgpack for serialisation  
* Designed the basic API (Helper)
  • Week 13 : Aug.13 -- Aug.19
* Cleaning Code
* Completing documentation
* Preparing code for review

Limitations

  • Ns-3 as a source - At present ns-3 acts as a sink while in a federation. This means that ns-3 can only receive updates on the objects but cannot modify the attributes of the object. The source property was not added because of two reasons, firstly, because we could not identify a scenario in which such a feature would be useful and secondly, due to the limited time span of GSoC. Although, adding a source property will be similar to sink property and can be implemented by adding a "RTI register object instance" and "Update Values" functions.
  • In a federations federates communicate using objects and interactions at present the code supports publishing objects and interactions can be added, if required by writing functions for interactions that mimic object functions.

References

  • [1] http://www.cs.bham.ac.uk/research/projects/hlarepast/
  • [2] Distributed Repast Agent Based Simulation with HLA - R. Minson and G. K. Theodoropoulos, CONCURRENCY AND COMPUTATION: PRACTICE AND EXPERIENCE
  • [3] Large Scale Agent Based Simulation on the Grid - Dan Chena , Georgios K. Theodoropoulos, Stephen J. Turner, Wentong Cai, Robert Minson, Future Generation Computer Systems, 24 (2008), 658-51
  • [4] MobileOnRealEnvironment-GIS: a federated mobile network simulator of mobile nodes on real geographic data- Emiliano Casalicchio, Emanuele Galli and Vittorio Ottaviani Dipartimento di Informatica, Sistemi e Produzione (DISP), 2009 13th IEEE/ACM International Symposium on Distributed Simulation and Real Time Applications
  • [5] http://porticoproject.org/index.php?title=Main_Page
  • [6] http://msgpack.org/