2012-08-20T10:27:56Z

2012-08-19T08:19:51Z

Muditraajgupta: /* Design */

= HLA interfaces for ns-3: Introduction =

* Student: [mailto:mudit.raaj.gupta@gmail.com Mudit Raj Gupta]
* Mentors: [mailto:tpecorella@mac.com 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 [http://www.google-melange.com/gsoc/proposal/review/google/gsoc2012/muditrajgupta/45002 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 [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 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.

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

'''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:

* 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 [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)
* Time (Time Advance Request Granted, Time Policies Enabled)
* 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]

In order to make ns-3 IEEE 1516 a new HLA compliant scheduler for ns-3 (rtiScheduler), has to be designed along with ns3FederateAmbassador.

* 1. Ns3Federate
* 2. LinkToRti
* 3. Synchronising
* 4. HLA Helper

There is a possibility of a two way communication between ns-3 and the other federates, but in the approach mentioned ns-3 is only used as a sink and not a source. This is so because in previous discussions with the mentor a conclusion was drawn that if ns-3 would also be used as a source, it will complicate things. The only-sink methodology can be extended to source and sink after GSoC, but adding it in the GSoC timeframe would be a bit over
ambitious. Although, it will definitely be a part of post-GSoC plans.

===Ns3Federate===

It consists of basically two parts -

* ns3Federate
* ns3FedAmb
* JavaLink

'''ns3Federate:'''

It takes care of the creating a federation (if not created else joining it), registering ns3 as a Federate and running the main simulation loop. It also deals with publishing, deleting and registering objects and interaction in the RTI.

'''ns3FedAmb'''

This segment is also responsible for creating a port and communicating with the LinkToRti code (C++) This basically handles callbacks from the RTI. These callbacks include notification when attribute of an object is changed, new object is added/registered or deleted and when a time advance request is granted. A server – client paradigm is implemented between ns3FedAmb and link-to-rti. It is implemented by using sockets.

===link-to-rti===

A message server is set up and appropriate sockets are used get messages from ns3FedAmb. It also acts as an entry level module to ns3 code and links ns3Federate with HLA API. It also controls time values and maintains a RTI_CLOCK.

===Synchronisation===

There is still a lot of debate in the synchronisation of the RTI clock with ns-3. The present approach finalised and yet to be tested looks like making a minor change in wall-clock-syncronizer.cc by changing the GetRealTime to GetRtiTime (which fetches RTI_CLOCK value) and using the real time simulator with almost no modification. Since it will wait for an event to process till real time has been reached (i.e RTI_CLOCK is the new real time). So the function process_one_event will take care of event scheduling.

===HLA API===

HLA API will be designed to access various features of ns-3-hla like initialise ns-3 Federate, Create Object, Add Attributes to Object, Accessing Attributes of Object.

== Testing approach ==

* Validation Test 1 (V1): Communication with other Federates (dummy)
* System Integration Test 1 (S1): Message Passing between ns3Federate Ambassador and ns3 link-to-rti
* System Integration Test 2(S2): Message Passing between RTI and ns3FederateAmbassador
* Unit Test 1 (U1): Checking ns3Federate (Java Sockets)
* Unit Test 2 (U2): Checking link-to-rti (C++ sockets)
* API (API1) test is to be done with the final HLA RTI API.

= Deliverables =

Note: The '''bold''' text details the changes/progress from initial deliverables

* 1.0 rtiScheduler ('''renamed link-to-rti''')
**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''')
**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
**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
**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)
**0.1 Adding the possibility of object publication and sharing in the existing code and integrating it. ('''Done, publishing objects''')
**0.2 Addition of a functionality in which ns-3 will also be used as a source.
**0.3 Making more refined and complex model in which ns-3 will be a federate.

'''New Expected Deliverables'''
* Synchronisation

= Usage =

= 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

= 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/